From ad80b527596f841067d6cf5c4194753866861c5f Mon Sep 17 00:00:00 2001
From: Yiorgis Gozadinos <ggozadinos@gmail.com>
Date: Wed, 17 Sep 2025 12:51:43 +0300
Subject: [PATCH] Update documentation

---
 README.md      |  1 +
 docs/agents.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.md  |  1 +
 docs/python.md |  2 ++
 mkdocs.yml     |  3 +-
 5 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 docs/agents.md

diff --git a/README.md b/README.md
index 65217135..d6aab4d9 100644
--- a/README.md
+++ b/README.md
@@ -90,4 +90,5 @@ Full documentation at: https://ggozad.github.io/haiku.rag/
 - [Configuration](https://ggozad.github.io/haiku.rag/configuration/) - Environment variables
 - [CLI](https://ggozad.github.io/haiku.rag/cli/) - Command reference
 - [Python API](https://ggozad.github.io/haiku.rag/python/) - Complete API docs
+- [Agents](https://ggozad.github.io/haiku.rag/agents/) - QA agent and multi-agent research
 - [Benchmarks](https://ggozad.github.io/haiku.rag/benchmarks/) - Performance Benchmarks
diff --git a/docs/agents.md b/docs/agents.md
new file mode 100644
index 00000000..41a52c65
--- /dev/null
+++ b/docs/agents.md
@@ -0,0 +1,83 @@
+## Agents
+
+Two agentic flows are provided by haiku.rag:
+
+- Simple QA Agent — a focused question answering agent
+- Research Multi‑Agent — a multi‑step, analyzable research workflow
+
+
+### Simple QA Agent
+
+The simple QA agent answers a single question using the knowledge base. It retrieves relevant chunks, optionally expands context around them, and asks the model to answer strictly based on that context.
+
+Key points:
+
+- Uses a single `search_documents` tool to fetch relevant chunks
+- Can be run with or without inline citations in the prompt
+- Returns a plain string answer
+
+Python usage:
+
+```python
+from haiku.rag.client import HaikuRAG
+from haiku.rag.qa.agent import QuestionAnswerAgent
+
+client = HaikuRAG(path_to_db)
+
+# Choose a provider and model (see Configuration for env defaults)
+agent = QuestionAnswerAgent(
+    client=client,
+    provider="openai",  # or "ollama", "vllm", etc.
+    model="gpt-4o-mini",
+    use_citations=False,  # set True to bias prompt towards citing sources
+)
+
+answer = await agent.answer("What is climate change?")
+print(answer)
+```
+
+### Research Multi‑Agent
+
+The research workflow coordinates specialized agents to plan, search, analyze, and synthesize a comprehensive answer. It is designed for deeper questions that benefit from iterative investigation and structured reporting.
+
+Components:
+
+- Orchestrator: Plans, coordinates, and loops until confidence is sufficient
+- Search Specialist: Performs targeted RAG searches and answers sub‑questions
+- Analysis & Evaluation: Extracts insights, identifies gaps, proposes new questions
+- Synthesis: Produces a final structured research report
+
+Primary models:
+
+- `ResearchPlan` — produced by the orchestrator when planning
+  - `main_question: str`
+  - `sub_questions: list[str]` (standalone, self‑contained queries)
+- `SearchAnswer` — produced by the search specialist for each sub‑question
+  - `query: str` — the executed sub‑question
+  - `answer: str` — the agent’s answer grounded in retrieved context
+  - `context: list[str]` — minimal verbatim snippets used for the answer
+  - `sources: list[str]` — document URIs aligned with `context`
+- `EvaluationResult` — insights, new standalone questions, sufficiency & confidence
+- `ResearchReport` — the final synthesized report
+
+
+Python usage:
+
+```python
+from haiku.rag.client import HaikuRAG
+from haiku.rag.research import ResearchOrchestrator
+
+client = HaikuRAG(path_to_db)
+orchestrator = ResearchOrchestrator(provider="openai", model="gpt-4o-mini")
+
+report = await orchestrator.conduct_research(
+    question="What are the main drivers and recent trends of global temperature anomalies since 1990?",
+    client=client,
+    max_iterations=2,
+    confidence_threshold=0.8,
+    verbose=False,
+)
+
+print(report.title)
+print(report.executive_summary)
+```
diff --git a/docs/index.md b/docs/index.md
index 17b6d404..a788105c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -55,6 +55,7 @@ haiku-rag migrate old_database.sqlite  # Migrate from SQLite
 - [Server](server.md) - File monitoring and server mode
 - [MCP](mcp.md) - Model Context Protocol integration
 - [Python](python.md) - Python API reference
+- [Agents](agents.md) - QA agent and multi-agent research
 
 ## License
 
diff --git a/docs/python.md b/docs/python.md
index 925c2d52..94209792 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -204,3 +204,5 @@ print(answer)
 The QA agent will search your documents for relevant information and use the configured LLM to generate a comprehensive answer. With `cite=True`, responses include citations showing which documents were used as sources.
 
 The QA provider and model can be configured via environment variables (see [Configuration](configuration.md)).
+
+See also: [Agents](agents.md) for details on the QA agent and the multi‑agent research workflow.
diff --git a/mkdocs.yml b/mkdocs.yml
index a1ed910e..943f2576 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -61,8 +61,9 @@ nav:
       - Configuration: configuration.md
       - CLI: cli.md
       - Server: server.md
-      - MCP: mcp.md
+      - Agents: agents.md
       - Python: python.md
+      - MCP: mcp.md
       - Benchmarks: benchmarks.md
 markdown_extensions:
   - admonition