Turn AI pilots into production systems you can trust.

tools = [
    {"name": "retrieve", "description": "Search the doc store..."},
    {"name": "rerank",   "description": "Rerank docs by relevance..."},
    {"name": "extract",  "description": "Extract an answer from docs..."},
]

prompt = f"""You are a RAG assistant. CRITICAL: Use ONLY retrieved info.

## QUERY CLASSIFICATION (classify BEFORE acting):
- Simple factual    → retrieve(k=3) → extract
- Complex/deep dive → retrieve(k=8) → rerank(k=3) → extract
- Comparison        → retrieve(topic_A) + retrieve(topic_B) → extract

## RESPONSE FORMAT (STRICT):
Return JSON: {{"thinking": "...", "tool_calls": [...],
  "final_answer": "...", "sources": [...], "confidence": 0.0-1.0}}

## TOOL PARAMETER RULES:
- retrieve: k must be 3-10, query must be <100 chars
- rerank: only after retrieve, k <= original k
- extract: requires non-empty doc list

## CRITICAL CONSTRAINTS:
❌ NEVER hallucinate or make up information
❌ NEVER call extract without first calling retrieve
❌ NEVER exceed confidence 0.9 without source validation
✓ ALWAYS cite sources with doc_id references
✓ ALWAYS include confidence scores

REMEMBER: You are a RETRIEVAL assistant, not a knowledge base.
Query: {query}"""

# Agentic loop: the LLM picks the next tool every turn.
# Every iteration re-reads the prompt and the full history.
messages = [{"role": "system", "content": prompt}]

while True:
    response = llm.complete(messages, tools=tools)
    if not response.tool_calls:
        return response.content
    messages.append(response.message)
    for tc in response.tool_calls:
        result = execute_tool(tc.name, tc.arguments)
        messages.append({"role": "tool", "content": result})
    # 10-50 iterations later, hopefully an answer.

class RAGAgent(PlanExecute):
    @primitive
    def retrieve(self, q: str, k: int = 5) -> list[Document]: ...
    @primitive
    def rerank(self, docs, q: str) -> list[Document]: ...
    @primitive
    def extract(self, docs, q: str) -> str: ...

    @decomposition(intent="What is machine learning?")
    def simple_qa(self):
        docs = self.retrieve("machine learning definition", k=3)
        return self.extract(docs, "What is machine learning?")

    @decomposition(intent="Explain the architecture of transformers")
    def deep_dive(self):
        docs = self.retrieve("transformer architecture innovations", k=8)
        ranked = self.rerank(docs, "transformer architecture")
        return self.extract(ranked, "Explain transformer architecture")

    @decomposition(intent="Compare React vs Vue")
    def compare(self):
        docs = self.retrieve("React") + self.retrieve("Vue")
        return self.extract(docs, "Compare React vs Vue")

# Intent matching happens automatically:
answer = agent.run("What is attention?")
deep_dive = agent.run("Deep dive on transformers")
comparison = agent.run("React vs Vue")