haiku.rag 0.11.2__py3-none-any.whl → 0.11.3__py3-none-any.whl

haiku/rag/app.py

@@ -194,10 +194,44 @@ class HaikuRAGApp:
             for chunk, score in results:
                 self._rich_print_search_result(chunk, score)
 
-    async def ask(self, question: str, cite: bool = False):
+    async def ask(
+        self,
+        question: str,
+        cite: bool = False,
+        deep: bool = False,
+        verbose: bool = False,
+    ):
         async with HaikuRAG(db_path=self.db_path) as self.client:
             try:
-                answer = await self.client.ask(question, cite=cite)
+                if deep:
+                    from rich.console import Console
+
+                    from haiku.rag.qa.deep.dependencies import DeepQAContext
+                    from haiku.rag.qa.deep.graph import build_deep_qa_graph
+                    from haiku.rag.qa.deep.nodes import DeepQAPlanNode
+                    from haiku.rag.qa.deep.state import DeepQADeps, DeepQAState
+
+                    graph = build_deep_qa_graph()
+                    context = DeepQAContext(
+                        original_question=question, use_citations=cite
+                    )
+                    state = DeepQAState(context=context)
+                    deps = DeepQADeps(
+                        client=self.client, console=Console() if verbose else None
+                    )
+
+                    start_node = DeepQAPlanNode(
+                        provider=Config.QA_PROVIDER,
+                        model=Config.QA_MODEL,
+                    )
+
+                    result = await graph.run(
+                        start_node=start_node, state=state, deps=deps
+                    )
+                    answer = result.output.answer
+                else:
+                    answer = await self.client.ask(question, cite=cite)
+
                 self.console.print(f"[bold blue]Question:[/bold blue] {question}")
                 self.console.print()
                 self.console.print("[bold green]Answer:[/bold green]")

haiku/rag/cli.py

@@ -299,11 +299,21 @@ def ask(
         "--cite",
         help="Include citations in the response",
     ),
+    deep: bool = typer.Option(
+        False,
+        "--deep",
+        help="Use deep multi-agent QA for complex questions",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        help="Show verbose progress output (only with --deep)",
+    ),
 ):
     from haiku.rag.app import HaikuRAGApp
 
     app = HaikuRAGApp(db_path=db)
-    asyncio.run(app.ask(question=question, cite=cite))
+    asyncio.run(app.ask(question=question, cite=cite, deep=deep, verbose=verbose))
 
 
 @cli.command("research", help="Run multi-agent research and output a concise report")

haiku/rag/graph/__init__.py

@@ -0,0 +1 @@
+from haiku.rag.graph.models import ResearchPlan, SearchAnswer

haiku/rag/graph/base.py

@@ -0,0 +1,31 @@
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+from rich.console import Console
+
+from haiku.rag.client import HaikuRAG
+from haiku.rag.graph.models import SearchAnswer
+
+
+@runtime_checkable
+class GraphContext(Protocol):
+    """Protocol for graph context objects."""
+
+    original_question: str
+    sub_questions: list[str]
+    qa_responses: list[SearchAnswer]
+
+    def add_qa_response(self, qa: SearchAnswer) -> None: ...
+
+
+class BaseGraphDeps(BaseModel):
+    """Base dependencies for graph nodes."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    client: HaikuRAG = Field(description="RAG client for document operations")
+    console: Console | None = None
+
+    def emit_log(self, message: str) -> None:
+        if self.console:
+            self.console.print(message)

haiku/rag/graph/common.py

@@ -0,0 +1,33 @@
+from typing import Any, Protocol
+
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.providers.ollama import OllamaProvider
+from pydantic_ai.providers.openai import OpenAIProvider
+
+from haiku.rag.config import Config
+
+
+class HasEmitLog(Protocol):
+    def emit_log(self, message: str, state: Any = None) -> None: ...
+
+
+def get_model(provider: str, model: str) -> Any:
+    if provider == "ollama":
+        return OpenAIChatModel(
+            model_name=model,
+            provider=OllamaProvider(base_url=f"{Config.OLLAMA_BASE_URL}/v1"),
+        )
+    elif provider == "vllm":
+        return OpenAIChatModel(
+            model_name=model,
+            provider=OpenAIProvider(
+                base_url=f"{Config.VLLM_RESEARCH_BASE_URL or Config.VLLM_QA_BASE_URL}/v1",
+                api_key="none",
+            ),
+        )
+    else:
+        return f"{provider}:{model}"
+
+
+def log(deps: HasEmitLog, state: Any, message: str) -> None:
+    deps.emit_log(message, state)

haiku/rag/graph/models.py

@@ -0,0 +1,24 @@
+from pydantic import BaseModel, Field
+
+
+class ResearchPlan(BaseModel):
+    main_question: str
+    sub_questions: list[str]
+
+
+class SearchAnswer(BaseModel):
+    query: str = Field(description="The search query that was performed")
+    answer: str = Field(description="The answer generated based on the context")
+    context: list[str] = Field(
+        description=(
+            "Only the minimal set of relevant snippets (verbatim) that directly "
+            "support the answer"
+        )
+    )
+    sources: list[str] = Field(
+        description=(
+            "Document titles (if available) or URIs corresponding to the"
+            " snippets actually used in the answer (one per snippet; omit if none)"
+        ),
+        default_factory=list,
+    )

haiku/rag/{research → graph}/nodes/analysis.py

@@ -3,15 +3,13 @@ from dataclasses import dataclass
 from pydantic_ai import Agent
 from pydantic_graph import BaseNode, GraphRunContext
 
+from haiku.rag.graph.common import get_model, log
 from haiku.rag.research.common import (
     format_analysis_for_prompt,
     format_context_for_prompt,
-    get_model,
-    log,
 )
 from haiku.rag.research.dependencies import ResearchDependencies
 from haiku.rag.research.models import EvaluationResult, InsightAnalysis, ResearchReport
-from haiku.rag.research.nodes.synthesize import SynthesizeNode
 from haiku.rag.research.prompts import DECISION_AGENT_PROMPT, INSIGHT_AGENT_PROMPT
 from haiku.rag.research.state import ResearchDeps, ResearchState
 
@@ -89,6 +87,8 @@ class AnalyzeInsightsNode(BaseNode[ResearchState, ResearchDeps, ResearchReport])
             for question in analysis.new_questions:
                 log(deps, state, f"   • {question}")
 
+        from haiku.rag.graph.nodes.analysis import DecisionNode
+
         return DecisionNode(self.provider, self.model)
 
 
@@ -169,7 +169,8 @@ class DecisionNode(BaseNode[ResearchState, ResearchDeps, ResearchReport]):
         status = "[green]Yes[/green]" if output.is_sufficient else "[red]No[/red]"
         log(deps, state, f"   Sufficient: {status}")
 
-        from haiku.rag.research.nodes.search import SearchDispatchNode
+        from haiku.rag.graph.nodes.search import SearchDispatchNode
+        from haiku.rag.graph.nodes.synthesize import SynthesizeNode
 
         if (
             output.is_sufficient

haiku/rag/{research → graph}/nodes/plan.py

@@ -3,11 +3,11 @@ from dataclasses import dataclass
 from pydantic_ai import Agent, RunContext
 from pydantic_graph import BaseNode, GraphRunContext
 
-from haiku.rag.research.common import get_model, log
+from haiku.rag.graph.common import get_model, log
+from haiku.rag.graph.models import ResearchPlan
+from haiku.rag.graph.prompts import PLAN_PROMPT
 from haiku.rag.research.dependencies import ResearchDependencies
-from haiku.rag.research.models import ResearchPlan, ResearchReport
-from haiku.rag.research.nodes.search import SearchDispatchNode
-from haiku.rag.research.prompts import PLAN_PROMPT
+from haiku.rag.research.models import ResearchReport
 from haiku.rag.research.state import ResearchDeps, ResearchState
 
 
@@ -67,4 +67,6 @@ class PlanNode(BaseNode[ResearchState, ResearchDeps, ResearchReport]):
         for i, sq in enumerate(state.context.sub_questions, 1):
             log(deps, state, f"      {i}. {sq}")
 
+        from haiku.rag.graph.nodes.search import SearchDispatchNode
+
         return SearchDispatchNode(self.provider, self.model)

haiku/rag/{research → graph}/nodes/search.py

@@ -7,10 +7,11 @@ from pydantic_ai.format_prompt import format_as_xml
 from pydantic_ai.output import ToolOutput
 from pydantic_graph import BaseNode, GraphRunContext
 
-from haiku.rag.research.common import get_model, log
+from haiku.rag.graph.common import get_model, log
+from haiku.rag.graph.models import SearchAnswer
+from haiku.rag.graph.prompts import SEARCH_AGENT_PROMPT
 from haiku.rag.research.dependencies import ResearchDependencies
-from haiku.rag.research.models import ResearchReport, SearchAnswer
-from haiku.rag.research.prompts import SEARCH_AGENT_PROMPT
+from haiku.rag.research.models import ResearchReport
 from haiku.rag.research.state import ResearchDeps, ResearchState
 
 
@@ -25,7 +26,7 @@ class SearchDispatchNode(BaseNode[ResearchState, ResearchDeps, ResearchReport]):
         state = ctx.state
         deps = ctx.deps
         if not state.context.sub_questions:
-            from haiku.rag.research.nodes.analysis import AnalyzeInsightsNode
+            from haiku.rag.graph.nodes.analysis import AnalyzeInsightsNode
 
             return AnalyzeInsightsNode(self.provider, self.model)
 

haiku/rag/{research → graph}/nodes/synthesize.py

@@ -3,10 +3,9 @@ from dataclasses import dataclass
 from pydantic_ai import Agent
 from pydantic_graph import BaseNode, End, GraphRunContext
 
-from haiku.rag.research.common import format_context_for_prompt, get_model, log
-from haiku.rag.research.dependencies import (
-    ResearchDependencies,
-)
+from haiku.rag.graph.common import get_model, log
+from haiku.rag.research.common import format_context_for_prompt
+from haiku.rag.research.dependencies import ResearchDependencies
 from haiku.rag.research.models import ResearchReport
 from haiku.rag.research.prompts import SYNTHESIS_AGENT_PROMPT
 from haiku.rag.research.state import ResearchDeps, ResearchState

haiku/rag/graph/prompts.py

@@ -0,0 +1,45 @@
+PLAN_PROMPT = """You are the research orchestrator for a focused, iterative
+workflow.
+
+Responsibilities:
+1. Understand and decompose the main question
+2. Propose a minimal, high‑leverage plan
+3. Coordinate specialized agents to gather evidence
+4. Iterate based on gaps and new findings
+
+Plan requirements:
+- Produce at most 3 sub_questions that together cover the main question.
+- Each sub_question must be a standalone, self‑contained query that can run
+  without extra context. Include concrete entities, scope, timeframe, and any
+  qualifiers. Avoid ambiguous pronouns (it/they/this/that).
+- Prioritize the highest‑value aspects first; avoid redundancy and overlap.
+- Prefer questions that are likely answerable from the current knowledge base;
+  if coverage is uncertain, make scopes narrower and specific.
+- Order sub_questions by execution priority (most valuable first)."""
+
+SEARCH_AGENT_PROMPT = """You are a search and question‑answering specialist.
+
+Tasks:
+1. Search the knowledge base for relevant evidence.
+2. Analyze retrieved snippets.
+3. Provide an answer strictly grounded in that evidence.
+
+Tool usage:
+- Always call search_and_answer before drafting any answer.
+- The tool returns snippets with verbatim `text`, a relevance `score`, and the
+  originating document identifier (document title if available, otherwise URI).
+- You may call the tool multiple times to refine or broaden context, but do not
+  exceed 3 total calls. Favor precision over volume.
+- Use scores to prioritize evidence, but include only the minimal subset of
+  snippet texts (verbatim) in SearchAnswer.context (typically 1‑4).
+- Set SearchAnswer.sources to the corresponding document identifiers for the
+  snippets you used (title if available, otherwise URI; one per snippet; same
+  order as context). Context must be text‑only.
+- If no relevant information is found, clearly say so and return an empty
+  context list and sources list.
+
+Answering rules:
+- Be direct and specific; avoid meta commentary about the process.
+- Do not include any claims not supported by the provided snippets.
+- Prefer concise phrasing; avoid copying long passages.
+- When evidence is partial, state the limits explicitly in the answer."""

haiku/rag/qa/deep/__init__.py

@@ -0,0 +1 @@
+from haiku.rag.qa.deep.models import DeepQAAnswer

haiku/rag/qa/deep/dependencies.py

@@ -0,0 +1,29 @@
+from pydantic import BaseModel, Field
+from rich.console import Console
+
+from haiku.rag.client import HaikuRAG
+from haiku.rag.graph.models import SearchAnswer
+
+
+class DeepQAContext(BaseModel):
+    original_question: str = Field(description="The original question")
+    sub_questions: list[str] = Field(
+        default_factory=list, description="Decomposed sub-questions"
+    )
+    qa_responses: list[SearchAnswer] = Field(
+        default_factory=list, description="QA pairs collected during answering"
+    )
+    use_citations: bool = Field(
+        default=False, description="Whether to include citations in the answer"
+    )
+
+    def add_qa_response(self, qa: SearchAnswer) -> None:
+        self.qa_responses.append(qa)
+
+
+class DeepQADependencies(BaseModel):
+    model_config = {"arbitrary_types_allowed": True}
+
+    client: HaikuRAG = Field(description="RAG client for document operations")
+    context: DeepQAContext = Field(description="Shared QA context")
+    console: Console | None = None

haiku/rag/qa/deep/graph.py

@@ -0,0 +1,21 @@
+from pydantic_graph import Graph
+
+from haiku.rag.qa.deep.models import DeepQAAnswer
+from haiku.rag.qa.deep.nodes import (
+    DeepQADecisionNode,
+    DeepQAPlanNode,
+    DeepQASearchDispatchNode,
+    DeepQASynthesizeNode,
+)
+from haiku.rag.qa.deep.state import DeepQADeps, DeepQAState
+
+
+def build_deep_qa_graph() -> Graph[DeepQAState, DeepQADeps, DeepQAAnswer]:
+    return Graph(
+        nodes=[
+            DeepQAPlanNode,
+            DeepQASearchDispatchNode,
+            DeepQADecisionNode,
+            DeepQASynthesizeNode,
+        ]
+    )

haiku/rag/qa/deep/models.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel, Field
+
+
+class DeepQAEvaluation(BaseModel):
+    is_sufficient: bool = Field(
+        description="Whether we have sufficient information to answer the question"
+    )
+    reasoning: str = Field(description="Explanation of the sufficiency assessment")
+    new_questions: list[str] = Field(
+        description="Additional sub-questions needed if insufficient",
+        default_factory=list,
+    )
+
+
+class DeepQAAnswer(BaseModel):
+    answer: str = Field(description="The comprehensive answer to the question")
+    sources: list[str] = Field(
+        description="Document titles or URIs used to generate the answer",
+        default_factory=list,
+    )

haiku/rag/qa/deep/nodes.py

@@ -0,0 +1,303 @@
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic_ai import Agent, RunContext
+from pydantic_ai.format_prompt import format_as_xml
+from pydantic_ai.output import ToolOutput
+from pydantic_graph import BaseNode, End, GraphRunContext
+
+from haiku.rag.graph.common import get_model, log
+from haiku.rag.graph.models import ResearchPlan, SearchAnswer
+from haiku.rag.graph.prompts import PLAN_PROMPT, SEARCH_AGENT_PROMPT
+from haiku.rag.qa.deep.dependencies import DeepQADependencies
+from haiku.rag.qa.deep.models import DeepQAAnswer, DeepQAEvaluation
+from haiku.rag.qa.deep.prompts import (
+    DECISION_PROMPT,
+    SYNTHESIS_PROMPT,
+    SYNTHESIS_PROMPT_WITH_CITATIONS,
+)
+from haiku.rag.qa.deep.state import DeepQADeps, DeepQAState
+
+
+@dataclass
+class DeepQAPlanNode(BaseNode[DeepQAState, DeepQADeps, DeepQAAnswer]):
+    provider: str
+    model: str
+
+    async def run(
+        self, ctx: GraphRunContext[DeepQAState, DeepQADeps]
+    ) -> BaseNode[DeepQAState, DeepQADeps, DeepQAAnswer]:
+        state = ctx.state
+        deps = ctx.deps
+
+        log(deps, state, "\n[bold cyan]📋 Planning approach...[/bold cyan]")
+
+        plan_agent = Agent(
+            model=get_model(self.provider, self.model),
+            output_type=ResearchPlan,
+            instructions=(
+                PLAN_PROMPT
+                + "\n\nUse the gather_context tool once on the main question before planning."
+            ),
+            retries=3,
+            deps_type=DeepQADependencies,
+        )
+
+        @plan_agent.tool
+        async def gather_context(
+            ctx2: RunContext[DeepQADependencies], query: str, limit: int = 6
+        ) -> str:
+            results = await ctx2.deps.client.search(query, limit=limit)
+            expanded = await ctx2.deps.client.expand_context(results)
+            return "\n\n".join(chunk.content for chunk, _ in expanded)
+
+        prompt = (
+            "Plan a focused approach for answering the main question.\n\n"
+            f"Main question: {state.context.original_question}"
+        )
+
+        agent_deps = DeepQADependencies(
+            client=deps.client,
+            context=state.context,
+            console=deps.console,
+        )
+        plan_result = await plan_agent.run(prompt, deps=agent_deps)
+        state.context.sub_questions = list(plan_result.output.sub_questions)[
+            : state.max_sub_questions
+        ]
+
+        log(deps, state, "\n[bold green]✅ Plan Created:[/bold green]")
+        log(
+            deps,
+            state,
+            f"   [bold]Main Question:[/bold] {state.context.original_question}",
+        )
+        log(deps, state, "   [bold]Sub-questions:[/bold]")
+        for i, sq in enumerate(state.context.sub_questions, 1):
+            log(deps, state, f"      {i}. {sq}")
+
+        return DeepQASearchDispatchNode(self.provider, self.model)
+
+
+@dataclass
+class DeepQASearchDispatchNode(BaseNode[DeepQAState, DeepQADeps, DeepQAAnswer]):
+    provider: str
+    model: str
+
+    async def run(
+        self, ctx: GraphRunContext[DeepQAState, DeepQADeps]
+    ) -> BaseNode[DeepQAState, DeepQADeps, DeepQAAnswer]:
+        state = ctx.state
+        deps = ctx.deps
+
+        if not state.context.sub_questions:
+            return DeepQADecisionNode(self.provider, self.model)
+
+        # Take up to max_concurrency questions and answer them concurrently
+        take = max(1, state.max_concurrency)
+        batch: list[str] = []
+        while state.context.sub_questions and len(batch) < take:
+            batch.append(state.context.sub_questions.pop(0))
+
+        async def answer_one(sub_q: str) -> SearchAnswer | None:
+            log(
+                deps,
+                state,
+                f"\n[bold cyan]🔍 Searching & Answering:[/bold cyan] {sub_q}",
+            )
+            agent = Agent(
+                model=get_model(self.provider, self.model),
+                output_type=ToolOutput(SearchAnswer, max_retries=3),
+                instructions=SEARCH_AGENT_PROMPT,
+                retries=3,
+                deps_type=DeepQADependencies,
+            )
+
+            @agent.tool
+            async def search_and_answer(
+                ctx2: RunContext[DeepQADependencies], query: str, limit: int = 5
+            ) -> str:
+                search_results = await ctx2.deps.client.search(query, limit=limit)
+                expanded = await ctx2.deps.client.expand_context(search_results)
+
+                entries: list[dict[str, Any]] = [
+                    {
+                        "text": chunk.content,
+                        "score": score,
+                        "document_uri": (
+                            chunk.document_title or chunk.document_uri or ""
+                        ),
+                    }
+                    for chunk, score in expanded
+                ]
+                if not entries:
+                    return f"No relevant information found in the knowledge base for: {query}"
+
+                return format_as_xml(entries, root_tag="snippets")
+
+            agent_deps = DeepQADependencies(
+                client=deps.client,
+                context=state.context,
+                console=deps.console,
+            )
+            try:
+                result = await agent.run(sub_q, deps=agent_deps)
+            except Exception as e:
+                log(deps, state, f"[red]Search failed:[/red] {e}")
+                return None
+
+            return result.output
+
+        answers = await asyncio.gather(*(answer_one(q) for q in batch))
+        for ans in answers:
+            if ans is None:
+                continue
+            state.context.add_qa_response(ans)
+            preview = ans.answer[:150] + ("…" if len(ans.answer) > 150 else "")
+            log(deps, state, f"   [green]✓[/green] {preview}")
+
+        return DeepQASearchDispatchNode(self.provider, self.model)
+
+
+@dataclass
+class DeepQADecisionNode(BaseNode[DeepQAState, DeepQADeps, DeepQAAnswer]):
+    provider: str
+    model: str
+
+    async def run(
+        self, ctx: GraphRunContext[DeepQAState, DeepQADeps]
+    ) -> BaseNode[DeepQAState, DeepQADeps, DeepQAAnswer]:
+        state = ctx.state
+        deps = ctx.deps
+
+        log(
+            deps,
+            state,
+            "\n[bold cyan]📊 Evaluating information sufficiency...[/bold cyan]",
+        )
+
+        agent = Agent(
+            model=get_model(self.provider, self.model),
+            output_type=DeepQAEvaluation,
+            instructions=DECISION_PROMPT,
+            retries=3,
+            deps_type=DeepQADependencies,
+        )
+
+        context_data = {
+            "original_question": state.context.original_question,
+            "gathered_answers": [
+                {
+                    "question": qa.query,
+                    "answer": qa.answer,
+                    "sources": qa.sources,
+                }
+                for qa in state.context.qa_responses
+            ],
+        }
+        context_xml = format_as_xml(context_data, root_tag="gathered_information")
+
+        prompt = (
+            "Evaluate whether we have sufficient information to answer the question.\n\n"
+            f"{context_xml}"
+        )
+
+        agent_deps = DeepQADependencies(
+            client=deps.client,
+            context=state.context,
+            console=deps.console,
+        )
+        result = await agent.run(prompt, deps=agent_deps)
+        evaluation = result.output
+
+        state.iterations += 1
+
+        log(deps, state, f"   [bold]Assessment:[/bold] {evaluation.reasoning}")
+        status = "[green]Yes[/green]" if evaluation.is_sufficient else "[red]No[/red]"
+        log(deps, state, f"   Sufficient: {status}")
+
+        # Add new questions if not sufficient
+        for new_q in evaluation.new_questions:
+            if new_q not in state.context.sub_questions:
+                state.context.sub_questions.append(new_q)
+
+        if evaluation.new_questions:
+            log(deps, state, "   [cyan]New questions:[/cyan]")
+            for question in evaluation.new_questions:
+                log(deps, state, f"   • {question}")
+
+        # Decide next step
+        if evaluation.is_sufficient or state.iterations >= state.max_iterations:
+            if state.iterations >= state.max_iterations:
+                log(
+                    deps,
+                    state,
+                    f"\n[bold yellow]⚠️  Reached max iterations ({state.max_iterations})[/bold yellow]",
+                )
+            log(deps, state, "\n[bold green]✅ Moving to synthesis.[/bold green]")
+            return DeepQASynthesizeNode(self.provider, self.model)
+
+        log(
+            deps,
+            state,
+            f"\n[bold cyan]🔄 Starting iteration {state.iterations + 1}...[/bold cyan]",
+        )
+        return DeepQASearchDispatchNode(self.provider, self.model)
+
+
+@dataclass
+class DeepQASynthesizeNode(BaseNode[DeepQAState, DeepQADeps, DeepQAAnswer]):
+    provider: str
+    model: str
+
+    async def run(
+        self, ctx: GraphRunContext[DeepQAState, DeepQADeps]
+    ) -> End[DeepQAAnswer]:
+        state = ctx.state
+        deps = ctx.deps
+
+        log(
+            deps,
+            state,
+            "\n[bold cyan]📝 Synthesizing final answer...[/bold cyan]",
+        )
+
+        prompt_template = (
+            SYNTHESIS_PROMPT_WITH_CITATIONS
+            if state.context.use_citations
+            else SYNTHESIS_PROMPT
+        )
+
+        agent = Agent(
+            model=get_model(self.provider, self.model),
+            output_type=DeepQAAnswer,
+            instructions=prompt_template,
+            retries=3,
+            deps_type=DeepQADependencies,
+        )
+
+        context_data = {
+            "original_question": state.context.original_question,
+            "sub_answers": [
+                {
+                    "question": qa.query,
+                    "answer": qa.answer,
+                    "sources": qa.sources,
+                }
+                for qa in state.context.qa_responses
+            ],
+        }
+        context_xml = format_as_xml(context_data, root_tag="gathered_information")
+
+        prompt = f"Synthesize a comprehensive answer to the original question.\n\n{context_xml}"
+
+        agent_deps = DeepQADependencies(
+            client=deps.client,
+            context=state.context,
+            console=deps.console,
+        )
+        result = await agent.run(prompt, deps=agent_deps)
+
+        log(deps, state, "[bold green]✅ Answer complete![/bold green]")
+        return End(result.output)

haiku/rag/qa/deep/prompts.py

@@ -0,0 +1,57 @@
+SYNTHESIS_PROMPT = """You are an expert at synthesizing information into clear, concise answers.
+
+Task:
+- Combine the gathered information from sub-questions into a single comprehensive answer
+- Answer the original question directly and completely
+- Base your answer strictly on the provided evidence
+- Be clear, accurate, and well-structured
+
+Output format:
+- answer: The complete answer to the original question (2-4 paragraphs)
+- sources: List of document titles/URIs used (extract from the sub-answers)
+
+Guidelines:
+- Start directly with the answer - no preamble like "Based on the research..."
+- Use a clear, professional tone
+- Organize information logically
+- If evidence is incomplete, state limitations clearly
+- Do not include any claims not supported by the gathered information"""
+
+SYNTHESIS_PROMPT_WITH_CITATIONS = """You are an expert at synthesizing information into clear, concise answers with proper citations.
+
+Task:
+- Combine the gathered information from sub-questions into a single comprehensive answer
+- Answer the original question directly and completely
+- Base your answer strictly on the provided evidence
+- Include inline citations using [Source Title] format
+
+Output format:
+- answer: The complete answer with inline citations (2-4 paragraphs)
+- sources: List of document titles/URIs used (extract from the sub-answers)
+
+Guidelines:
+- Start directly with the answer - no preamble like "Based on the research..."
+- Add citations after each claim: [Source Title]
+- Use a clear, professional tone
+- Organize information logically
+- If evidence is incomplete, state limitations clearly
+- Do not include any claims not supported by the gathered information"""
+
+DECISION_PROMPT = """You are an expert at evaluating whether gathered information is sufficient to answer a question.
+
+Task:
+- Review the original question and all gathered sub-question answers
+- Determine if we have enough information to provide a comprehensive answer
+- If insufficient, suggest specific new sub-questions to fill the gaps
+
+Output format:
+- is_sufficient: Boolean indicating if we can answer the question comprehensively
+- reasoning: Clear explanation of your assessment
+- new_questions: List of specific follow-up questions needed (empty if sufficient)
+
+Guidelines:
+- Be strict but reasonable in your assessment
+- Focus on whether core aspects of the question are addressed
+- New questions should be specific and distinct from what's been asked
+- Limit new questions to 2-3 maximum
+- Consider whether additional searches would meaningfully improve the answer"""

haiku/rag/qa/deep/state.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+
+from rich.console import Console
+
+from haiku.rag.client import HaikuRAG
+from haiku.rag.qa.deep.dependencies import DeepQAContext
+
+
+@dataclass
+class DeepQADeps:
+    client: HaikuRAG
+    console: Console | None = None
+
+    def emit_log(self, message: str, state: "DeepQAState | None" = None) -> None:
+        if self.console:
+            self.console.print(message)
+
+
+@dataclass
+class DeepQAState:
+    context: DeepQAContext
+    max_sub_questions: int = 3
+    max_iterations: int = 2
+    max_concurrency: int = 3
+    iterations: int = 0

haiku/rag/research/__init__.py

@@ -1,28 +1,3 @@
+from haiku.rag.graph.models import SearchAnswer
 from haiku.rag.research.dependencies import ResearchContext, ResearchDependencies
-from haiku.rag.research.graph import (
-    PlanNode,
-    ResearchDeps,
-    ResearchState,
-    build_research_graph,
-)
-from haiku.rag.research.models import EvaluationResult, ResearchReport, SearchAnswer
-from haiku.rag.research.stream import (
-    ResearchStateSnapshot,
-    ResearchStreamEvent,
-    stream_research_graph,
-)
-
-__all__ = [
-    "ResearchDependencies",
-    "ResearchContext",
-    "SearchAnswer",
-    "EvaluationResult",
-    "ResearchReport",
-    "ResearchDeps",
-    "ResearchState",
-    "PlanNode",
-    "build_research_graph",
-    "stream_research_graph",
-    "ResearchStreamEvent",
-    "ResearchStateSnapshot",
-]
+from haiku.rag.research.models import EvaluationResult, ResearchReport

haiku/rag/research/common.py

@@ -1,39 +1,8 @@
-from typing import TYPE_CHECKING, Any
-
 from pydantic_ai import format_as_xml
-from pydantic_ai.models.openai import OpenAIChatModel
-from pydantic_ai.providers.ollama import OllamaProvider
-from pydantic_ai.providers.openai import OpenAIProvider
 
-from haiku.rag.config import Config
 from haiku.rag.research.dependencies import ResearchContext
 from haiku.rag.research.models import InsightAnalysis
 
-if TYPE_CHECKING:  # pragma: no cover
-    from haiku.rag.research.state import ResearchDeps, ResearchState
-
-
-def get_model(provider: str, model: str) -> Any:
-    if provider == "ollama":
-        return OpenAIChatModel(
-            model_name=model,
-            provider=OllamaProvider(base_url=f"{Config.OLLAMA_BASE_URL}/v1"),
-        )
-    elif provider == "vllm":
-        return OpenAIChatModel(
-            model_name=model,
-            provider=OpenAIProvider(
-                base_url=f"{Config.VLLM_RESEARCH_BASE_URL or Config.VLLM_QA_BASE_URL}/v1",
-                api_key="none",
-            ),
-        )
-    else:
-        return f"{provider}:{model}"
-
-
-def log(deps: "ResearchDeps", state: "ResearchState", msg: str) -> None:
-    deps.emit_log(msg, state)
-
 
 def format_context_for_prompt(context: ResearchContext) -> str:
     """Format the research context as XML for inclusion in prompts."""

haiku/rag/research/dependencies.py

@@ -4,11 +4,11 @@ from pydantic import BaseModel, Field
 from rich.console import Console
 
 from haiku.rag.client import HaikuRAG
+from haiku.rag.graph.models import SearchAnswer
 from haiku.rag.research.models import (
     GapRecord,
     InsightAnalysis,
     InsightRecord,
-    SearchAnswer,
 )
 from haiku.rag.research.stream import ResearchStream
 

haiku/rag/research/graph.py

@@ -1,23 +1,12 @@
 from pydantic_graph import Graph
 
+from haiku.rag.graph.nodes.analysis import AnalyzeInsightsNode, DecisionNode
+from haiku.rag.graph.nodes.plan import PlanNode
+from haiku.rag.graph.nodes.search import SearchDispatchNode
+from haiku.rag.graph.nodes.synthesize import SynthesizeNode
 from haiku.rag.research.models import ResearchReport
-from haiku.rag.research.nodes.analysis import AnalyzeInsightsNode, DecisionNode
-from haiku.rag.research.nodes.plan import PlanNode
-from haiku.rag.research.nodes.search import SearchDispatchNode
-from haiku.rag.research.nodes.synthesize import SynthesizeNode
 from haiku.rag.research.state import ResearchDeps, ResearchState
 
-__all__ = [
-    "PlanNode",
-    "SearchDispatchNode",
-    "AnalyzeInsightsNode",
-    "DecisionNode",
-    "SynthesizeNode",
-    "ResearchState",
-    "ResearchDeps",
-    "build_research_graph",
-]
-
 
 def build_research_graph() -> Graph[ResearchState, ResearchDeps, ResearchReport]:
     return Graph(

haiku/rag/research/models.py

@@ -131,31 +131,6 @@ class InsightAnalysis(BaseModel):
     )
 
 
-class ResearchPlan(BaseModel):
-    main_question: str
-    sub_questions: list[str]
-
-
-class SearchAnswer(BaseModel):
-    """Structured output for the SearchSpecialist agent."""
-
-    query: str = Field(description="The search query that was performed")
-    answer: str = Field(description="The answer generated based on the context")
-    context: list[str] = Field(
-        description=(
-            "Only the minimal set of relevant snippets (verbatim) that directly "
-            "support the answer"
-        )
-    )
-    sources: list[str] = Field(
-        description=(
-            "Document titles (if available) or URIs corresponding to the"
-            " snippets actually used in the answer (one per snippet; omit if none)"
-        ),
-        default_factory=list,
-    )
-
-
 class EvaluationResult(BaseModel):
     """Result of analysis and evaluation."""
 

haiku/rag/research/prompts.py

@@ -1,49 +1,3 @@
-PLAN_PROMPT = """You are the research orchestrator for a focused, iterative
-workflow.
-
-Responsibilities:
-1. Understand and decompose the main question
-2. Propose a minimal, high‑leverage plan
-3. Coordinate specialized agents to gather evidence
-4. Iterate based on gaps and new findings
-
-Plan requirements:
-- Produce at most 3 sub_questions that together cover the main question.
-- Each sub_question must be a standalone, self‑contained query that can run
-  without extra context. Include concrete entities, scope, timeframe, and any
-  qualifiers. Avoid ambiguous pronouns (it/they/this/that).
-- Prioritize the highest‑value aspects first; avoid redundancy and overlap.
-- Prefer questions that are likely answerable from the current knowledge base;
-  if coverage is uncertain, make scopes narrower and specific.
-- Order sub_questions by execution priority (most valuable first)."""
-
-SEARCH_AGENT_PROMPT = """You are a search and question‑answering specialist.
-
-Tasks:
-1. Search the knowledge base for relevant evidence.
-2. Analyze retrieved snippets.
-3. Provide an answer strictly grounded in that evidence.
-
-Tool usage:
-- Always call search_and_answer before drafting any answer.
-- The tool returns snippets with verbatim `text`, a relevance `score`, and the
-  originating document identifier (document title if available, otherwise URI).
-- You may call the tool multiple times to refine or broaden context, but do not
-  exceed 3 total calls. Favor precision over volume.
-- Use scores to prioritize evidence, but include only the minimal subset of
-  snippet texts (verbatim) in SearchAnswer.context (typically 1‑4).
-- Set SearchAnswer.sources to the corresponding document identifiers for the
-  snippets you used (title if available, otherwise URI; one per snippet; same
-  order as context). Context must be text‑only.
-- If no relevant information is found, clearly say so and return an empty
-  context list and sources list.
-
-Answering rules:
-- Be direct and specific; avoid meta commentary about the process.
-- Do not include any claims not supported by the provided snippets.
-- Prefer concise phrasing; avoid copying long passages.
-- When evidence is partial, state the limits explicitly in the answer."""
-
 INSIGHT_AGENT_PROMPT = """You are the insight aggregation specialist for the
 research workflow.
 

{haiku_rag-0.11.2.dist-info → haiku_rag-0.11.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiku.rag
-Version: 0.11.2
+Version: 0.11.3
 Summary: Agentic Retrieval Augmented Generation (RAG) with LanceDB
 Author-email: Yiorgis Gozadinos <ggozadinos@gmail.com>
 License: MIT
@@ -78,6 +78,12 @@ haiku-rag ask "Who is the author of haiku.rag?"
 # Ask questions with citations
 haiku-rag ask "Who is the author of haiku.rag?" --cite
 
+# Deep QA (multi-agent question decomposition)
+haiku-rag ask "Who is the author of haiku.rag?" --deep --cite
+
+# Deep QA with verbose output
+haiku-rag ask "Who is the author of haiku.rag?" --deep --verbose
+
 # Multi‑agent research (iterative plan/search/evaluate)
 haiku-rag research \
   "What are the main drivers and trends of global temperature anomalies since 1990?" \

{haiku_rag-0.11.2.dist-info → haiku_rag-0.11.3.dist-info}/RECORD

@@ -1,7 +1,7 @@
 haiku/rag/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-haiku/rag/app.py,sha256=TRFwMP9mzLaM7EPc7dhsPODKZxCDkSSgPCnGAdj65VU,17929
+haiku/rag/app.py,sha256=B5BZaUgC9u3hz17tRKu_xKefPu5xqdZQPCxfa5K8_EI,19180
 haiku/rag/chunker.py,sha256=PVe6ysv8UlacUd4Zb3_8RFWIaWDXnzBAy2VDJ4TaUsE,1555
-haiku/rag/cli.py,sha256=wreAxyXSRnn7f09t9SGe4uAXQjlieUQIpNpOapJT7y8,12910
+haiku/rag/cli.py,sha256=6GmWfs30uUytcnyBMv-OE4tCkkuKnfYeJFU5DIrZ_vU,13212
 haiku/rag/client.py,sha256=fz5bZP1KNWbc9cvpEC8puMBHEvt-vVtFjRMItt_WD0M,23920
 haiku/rag/config.py,sha256=c2WoaieI3-HAWb6lCmVnJHY22NXl2SGLsndRbiqCzeA,2305
 haiku/rag/logging.py,sha256=dm65AwADpcQsH5OAPtRA-4hsw0w5DK-sGOvzYkj6jzw,1720
@@ -16,26 +16,39 @@ haiku/rag/embeddings/ollama.py,sha256=c1BeKTgpymniZw1sm4iAIdK5vA0MYoRzHLcd2_pFA4
 haiku/rag/embeddings/openai.py,sha256=bwoUVlzu9UtbDpN7CtG6OPt0d5tfJNeje4lR81Btpl0,546
 haiku/rag/embeddings/vllm.py,sha256=7ocp9D9bD1R5rqRIC4-Vih9VlKQNuD429k8-9wu234E,669
 haiku/rag/embeddings/voyageai.py,sha256=I4kVdT2KPtwcbjxD22GWJmgcIQIEEHpkOY2_QbFh7mQ,712
+haiku/rag/graph/__init__.py,sha256=BHfMchuUO_UhHKpjjGHjd6xPxNkrIwJzHn4YJiLqG1g,62
+haiku/rag/graph/base.py,sha256=DepZqLF9E64YCCkjmbqmgyp28oNp69WfJCXp614xzh0,819
+haiku/rag/graph/common.py,sha256=xTejucXei3x9tqbal3ZS_64lZAC6Bw3-QfXPniZcZEw,986
+haiku/rag/graph/models.py,sha256=sgL5_wSbQJrNOITH615jryPBhTE8J3ZiZWVxO9Ty-JI,755
+haiku/rag/graph/prompts.py,sha256=xJgAHjUVczxCgk7YLPyy6DdQFi0lwj42vJqIFnPqcYw,2221
+haiku/rag/graph/nodes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haiku/rag/graph/nodes/analysis.py,sha256=g-Aw3nPuCHWo0CXM96Ixa4vQI4TpI6tg6ooHT_JuIkE,6568
+haiku/rag/graph/nodes/plan.py,sha256=Bb6Fva9vwArCU-5xBr24N4pM3wfLP-Vwufgss8HfXMQ,2622
+haiku/rag/graph/nodes/search.py,sha256=DdHhEY7fmWUqis6Nk0bj-di56-ML262B51N9zytzKYk,3699
+haiku/rag/graph/nodes/synthesize.py,sha256=WF0D44SwLP1OK8C6ViOAhFOtGQ0mj3aO54z5bemJb4E,1828
 haiku/rag/qa/__init__.py,sha256=Sl7Kzrg9CuBOcMF01wc1NtQhUNWjJI0MhIHfCWrb8V4,434
 haiku/rag/qa/agent.py,sha256=rtUkEmnD8lMHIxpPPVY6TdmF4aSlZnLjad5eDefrlBw,3145
 haiku/rag/qa/prompts.py,sha256=Lqwn3m4zCsu_CJiC4s9cLsuPNbb9nq6j2PqEF3lw1eA,3380
+haiku/rag/qa/deep/__init__.py,sha256=SnCpWxWip-TaFzVKlFyrOgYeXEqT_gpIlaSItEEJ6r0,50
+haiku/rag/qa/deep/dependencies.py,sha256=AKFqcC1D3N1VPudnFmLH29K5eJWEC5wtwUGkO4FM4jc,998
+haiku/rag/qa/deep/graph.py,sha256=a_Uf3Haz8j4qla8FDFRVRdwH15ciAXhbtrqvzdvpFQ8,543
+haiku/rag/qa/deep/models.py,sha256=siZMQXD21_3nk8kaLCv0BCuD9TydLYo-yC4-9CxQy3E,683
+haiku/rag/qa/deep/nodes.py,sha256=XbDujD_xg-NsJS2oYm3LqkfxeHZCzT2f9wBNhVh0wns,10442
+haiku/rag/qa/deep/prompts.py,sha256=t1fEvoD5Rdab92eAOvefv2wBVmkPFuR0BQ8Kh4X0-mY,2565
+haiku/rag/qa/deep/state.py,sha256=ICFIX0oRtBs6Sdq9YnmnP04BkGiQYwucfS3Mf8XLcCU,570
 haiku/rag/reranking/__init__.py,sha256=95ApqN51rcog9MLkTh_uNE69qOVozO1Z6KMbZZj8nH0,963
 haiku/rag/reranking/base.py,sha256=LM9yUSSJ414UgBZhFTgxGprlRqzfTe4I1vgjricz2JY,405
 haiku/rag/reranking/cohere.py,sha256=1iTdiaa8vvb6oHVB2qpWzUOVkyfUcimVSZp6Qr4aq4c,1049
 haiku/rag/reranking/mxbai.py,sha256=uveGFIdmNmepd2EQsvYr64wv0ra2_wB845hdSZXy5Cw,908
 haiku/rag/reranking/vllm.py,sha256=xVGH9ss-ISWdJ5SKUUHUbTqBo7PIEmA_SQv0ScdJ6XA,1479
-haiku/rag/research/__init__.py,sha256=Ujci3u7yM11g10J3EzOYs6y4nG1W3CeG70pMRvPoSL4,708
-haiku/rag/research/common.py,sha256=E-7SN1XBbMoTp5sWGGcItBfnmOvFgbeybB0FnqSCp9I,3995
-haiku/rag/research/dependencies.py,sha256=GYtD2jkxBkxeHm44JAtrCGx0IMJbDCiVXnbQd_n6T0M,8118
-haiku/rag/research/graph.py,sha256=Zaqdjj3wmSTPdMoMl5CmhM2z1otwDq9kS-e5vYi-Y7k,879
-haiku/rag/research/models.py,sha256=LInrRtcL-VzCL_PA8LRBqpH5wVckEFuf8zkVnZg7wEg,6666
-haiku/rag/research/prompts.py,sha256=5lDXT874npJn-oXucLk6Z5jqvXEf0cGrnEeNE46iur8,7056
+haiku/rag/research/__init__.py,sha256=xfVzYkt8QETjZaP8v4LdK8MC2R_JmxKDD34LefvrJbo,201
+haiku/rag/research/common.py,sha256=mrKXolTnDxcONjodmSPVAtXYWqbU0Bie2W-4lOTclGY,2988
+haiku/rag/research/dependencies.py,sha256=hiGImk7HyJF4LRYnTmsLFGzY1QrGjAyPW5vb_2JQRDo,8148
+haiku/rag/research/graph.py,sha256=FqjE58NK7hBJtbt9WLFsaojSqXaFpkuidz2UIKRwkSE,672
+haiku/rag/research/models.py,sha256=w5a727euhBYGEHSHfMztF0ATyYoFSlkrhJhyz_Mn7jY,5888
+haiku/rag/research/prompts.py,sha256=opz4MXjoDHH1wjG6bPyiqT0LVzk3pBA6y_a9zpBW8yM,4834
 haiku/rag/research/state.py,sha256=P8RXJMi3wA3l1j6yo8dsAyso6S27FgqS7fvZUUY447A,917
 haiku/rag/research/stream.py,sha256=amyGDimkNp_FHYUXCqtpbeDOx7sC1jQ-7DwoxuNOL1g,5576
-haiku/rag/research/nodes/analysis.py,sha256=-ydF7dpzyiOSwk6jwhWHqUtTXk_Bzr-dMWodIdBr9KA,6475
-haiku/rag/research/nodes/plan.py,sha256=8lsrDt70SjLcK-awnII7PyW6gaGZ-YLmP7nCqCxqkBo,2588
-haiku/rag/research/nodes/search.py,sha256=-5JgsaWVivFmt7jCdBradE0ZXf_i87o2fj9eLgRC1uE,3674
-haiku/rag/research/nodes/synthesize.py,sha256=SEQ6aDgSwvSVHyJxVK0248JnpfrfDoUbvlEUTAQll58,1803
 haiku/rag/store/__init__.py,sha256=R2IRcxtkFDxqa2sgMirqLq3l2-FPdWr6ydYStaqm5OQ,104
 haiku/rag/store/engine.py,sha256=i2t15j1hhEY0SMNXk2uUSeCio-mHnTpnN5S83afVx6o,10257
 haiku/rag/store/models/__init__.py,sha256=kc7Ctf53Jr483tk4QTIrcgqBbXDz4ZoeYSkFXfPnpks,89
@@ -48,8 +61,8 @@ haiku/rag/store/repositories/settings.py,sha256=ObrDrzxHn-yA1WcbgIoJoVmAbVvQHAFv
 haiku/rag/store/upgrades/__init__.py,sha256=RQ8A6rEXBASLb5PD9vdDnEas_m_GgRzzdVu4B88Snqc,1975
 haiku/rag/store/upgrades/v0_10_1.py,sha256=qNGnxj6hoHaHJ1rKTiALfw0c9NQOi0KAK-VZCD_073A,1959
 haiku/rag/store/upgrades/v0_9_3.py,sha256=NrjNilQSgDtFWRbL3ZUtzQzJ8tf9u0dDRJtnDFwwbdw,3322
-haiku_rag-0.11.2.dist-info/METADATA,sha256=Eij1eM8K5MOYM1QZccm96n6v97r9x-lS3RG8tdPcXPw,6542
-haiku_rag-0.11.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-haiku_rag-0.11.2.dist-info/entry_points.txt,sha256=G1U3nAkNd5YDYd4v0tuYFbriz0i-JheCsFuT9kIoGCI,48
-haiku_rag-0.11.2.dist-info/licenses/LICENSE,sha256=eXZrWjSk9PwYFNK9yUczl3oPl95Z4V9UXH7bPN46iPo,1065
-haiku_rag-0.11.2.dist-info/RECORD,,
+haiku_rag-0.11.3.dist-info/METADATA,sha256=kohzziLYTajCvyfMxnJkaY7XeEfqPnmVuC_20NpkeLA,6748
+haiku_rag-0.11.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+haiku_rag-0.11.3.dist-info/entry_points.txt,sha256=G1U3nAkNd5YDYd4v0tuYFbriz0i-JheCsFuT9kIoGCI,48
+haiku_rag-0.11.3.dist-info/licenses/LICENSE,sha256=eXZrWjSk9PwYFNK9yUczl3oPl95Z4V9UXH7bPN46iPo,1065
+haiku_rag-0.11.3.dist-info/RECORD,,