# Changelog

All notable changes to KOAN will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- **Graph-Augmented Reasoning** (`koan.graph.augmented`) -- `GraphAugmentedAgent` reads from the decision graph before reasoning (precedents, entity history, domain profile, policies) and writes traces back after. Closes the read-write loop.
- **GraphContextProvider** (`koan.graph.context`) -- Queries the graph to build structured context for agent augmentation. Returns domain profile, entity history, precedents, active policies, and feedback history.
- **Self-Organizing Policies** (`koan.graph.policies`) -- `PolicyManager` with `auto_evolve()` to discover and promote tool patterns that repeat 3+ times with >70% success. `retire_underperforming()` deletes policies with >50% failure rate. Full lifecycle: cold start → accumulation → emergence → gating → feedback → retirement → recovery.
- **Policy-Gated Tools** (`koan.graph.gated_tools`) -- `PolicyGatedTools` wraps a `ToolProvider` to structurally enforce policy constraints. Filters `definitions()` to only allowed tools and blocks `execute()` for gated tools.
- **Feedback-Weighted Precedents** (`koan.graph.context`) -- Precedent queries now JOIN to Feedback nodes, returning `feedback_score` and `feedback_type` per decision. Precedents are sorted by quality (successful+liked first, failed/disliked last) so the LLM prioritizes proven patterns.
- **Human Feedback** (`koan.graph.feedback`) -- `record_feedback()` to capture user satisfaction signals (thumbs up/down, explicit ratings). `FeedbackType` enum covers explicit, fork, rewind, thumbs_up, thumbs_down.
- **Confidence Calibration** (`koan.graph.feedback`) -- `ConfidenceCalibrator` queries historical feedback to compute adjustment factors. Fork/rewind events weighted at 0.7x of explicit negative feedback, floor of 0.3.
- **Fork/Rewind Tracking** -- `ForkableThread` now accepts an `on_fork` callback fired on `fork_at()`, `fork()`, and `rewind_to()`. Fork/rewind events can be recorded as implicit dissatisfaction signals in the graph.
- **Agent Feedback API** -- `GraphAugmentedAgent.submit_feedback(satisfied=True/False, comment="...")` convenience method.
- **FeedbackNode** schema model for graph node representation.
- **Evaluation Framework** (`koan.graph.evaluation`) -- `DecisionEvaluator` auto-evaluates agent decisions using calibrated confidence and configurable `EvaluationPolicy` thresholds (auto-approve, flag, reject). `record_review_decision()` captures human reviewer decisions.
- **Multi-Agent Feedback Propagation** (`koan.graph.propagation`) -- `FeedbackPropagator` walks `DELEGATED_TO` edges backwards to distribute feedback across handoff chains with configurable decay. `link_runs()` connects parent/child runs.
- **Demo 5** — Self-organizing graph CLI demo showing the full policy lifecycle in 9 automated steps
- **Demo 6** — Legal assistant (port 8006): case lookup, document search, motion drafting, hearing schedules
- **Demo 7** — Medical triage (port 8007): patient vitals, lab ordering, medication checks, allergy screening
- **Demo 8** — Investment advisor (port 8008): portfolio risk assessment, trade execution, market data
- **TEST_QUESTIONS.md** — Copy-paste test scripts for all 8 demos covering threading, streaming, tool calls, graph context, feedback, and policy lifecycle
- Examples `17_graph_augmented_agent.py` and `18_feedback_and_calibration.py`

## [0.1.0] - 2026-03-07

### Added

- **Core LLM Client** (`koan.llm`) -- Unified async client for OpenAI and Anthropic with automatic retry via tenacity
- **Structured Output** (`koan.output`) -- Parse LLM responses into Pydantic models with JSON schema generation
- **Prompt Templates** (`koan.prompts`) -- Jinja2-powered prompt engine with variable injection
- **Streaming** (`koan.streaming`) -- Token-by-token streaming for both providers, tool call accumulation, SSE helper
- **Tool System** (`koan.tools`) -- `@tool` decorator with type hint introspection, `ToolRegistry`, async/sync execution
- **Memory** (`koan.memory`) -- Thread-scoped conversation store (SQLAlchemy/SQLite), vector memory (ChromaDB), forkable threads
- **Agents** (`koan.agents`) -- `ReactAgent` with ReAct loop, `StreamingReactAgent`, `SequentialChain`, `ParallelFanOut`, `Orchestrator`, `Supervisor`
- **Agent Streaming** -- All agents and orchestration primitives support `run_stream()` yielding typed `AgentEvent` objects
- **MCP Integration** (`koan.mcp`) -- `KoanMCPServer` to expose KOAN tools as MCP servers, `MCPToolSource` client, `CombinedToolSource`
- **Context Graphs** (`koan.graph`) -- Unified `GraphClient` for Neo4j, Memgraph, and FalkorDB with Cypher queries
- **Decision Tracer** -- `DecisionTracer` context manager to record decisions, actions, outcomes, entity links, policy governance, and precedent citations
- **Graph Queries** -- `get_run_trace()`, `find_precedents()`, `detect_policy_gaps()`, `trace_causal_chain()`, `find_cross_entity_decisions()`
- **Precedent Search** -- `PrecedentSearch` for finding past decisions by entity and type
- **Observability** (`koan.telemetry`) -- `KoanTracer` (OpenTelemetry spans), `setup_logging` (structlog), `CostTracker`
- **CLI** (`koan.cli`) -- `koan verify`, `koan init`, `koan mcp dev`, `koan graph init`
- **Docker Compose** -- Pre-configured containers for FalkorDB, Memgraph, and Neo4j
- **354 unit tests** passing with >80% coverage
- **Integration tests** for OpenAI, Anthropic, streaming, agents, and graph databases
- **19 example scripts** demonstrating all features

[0.1.0]: https://github.com/koan-framework/koan/releases/tag/v0.1.0
