Rag

Source: examples/patterns/rag.py

Introduction

RAG establishes retrieval-grounded generation, and memory-centric agent systems such as Generative Agents and MemGPT show why persistent context is essential for longer design tasks. This example combines retrieval and reasoning steps so grounded evidence flow is explicit in traces and outputs.

Technical Implementation

  1. Configure Tracer with JSONL + console output so each run emits machine-readable traces and lifecycle logs.

  2. Build the runtime surface (public APIs only) and execute RAGPattern.run(...) with a fixed request_id.

  3. Configure and invoke Toolbox integrations (core/script/MCP/callable) before assembling the final payload.

  4. Persist and query context via SQLiteMemoryStore to demonstrate memory-backed workflow behavior.

  5. Print a compact JSON payload including trace_info for deterministic tests and docs examples.

        flowchart LR
    A["Input prompt or scenario"] --> B["main(): runtime wiring"]
    B --> C["RAGPattern.run(...)"]
    C --> D["retrieval and reasoning are composed via memory steps"]
    C --> E["Tracer JSONL + console events"]
    D --> F["ExecutionResult/payload"]
    E --> F
    F --> G["Printed JSON output"]
    
 1from __future__ import annotations
 2
 3import json
 4from pathlib import Path
 5
 6from design_research_agents import DirectLLMCall, LlamaCppServerLLMClient, Toolbox, Tracer
 7from design_research_agents.memory import SQLiteMemoryStore
 8from design_research_agents.patterns import RAGPattern
 9
10
11def main() -> None:
12    """Run one local RAG workflow and print compact JSON result."""
13    # Fixed request id keeps traces and docs output deterministic across runs.
14    request_id = "example-workflow-rag-design-001"
15    tracer = Tracer(
16        enabled=True,
17        trace_dir=Path("artifacts/examples/traces"),
18        enable_jsonl=True,
19        enable_console=True,
20    )
21    db_path = Path.cwd() / "artifacts" / "examples" / "rag_example.sqlite3"
22    db_path.parent.mkdir(parents=True, exist_ok=True)
23    if db_path.exists():
24        db_path.unlink()
25
26    # Run the local RAG pattern using public runtime surfaces. Using this with statement will automatically close
27    # the tool runtime, memory store, and managed client when the example is done.
28    with (
29        Toolbox() as seed_toolbox,
30        SQLiteMemoryStore(db_path=db_path) as store,
31        LlamaCppServerLLMClient() as llm_client,
32    ):
33        seed_toolbox.invoke_dict(
34            "memory.write",
35            {
36                "db_path": str(db_path),
37                "namespace": "design_examples",
38                "records": [
39                    {
40                        "content": "Design requirement: include graceful shutdown and runtime monitoring.",
41                        "metadata": {"kind": "requirement"},
42                    }
43                ],
44            },
45            request_id=f"{request_id}:seed_memory",
46            dependencies={},
47        )
48        pattern = RAGPattern(
49            reasoning_delegate=DirectLLMCall(llm_client=llm_client, tracer=tracer),
50            memory_store=store,
51            memory_namespace="design_examples",
52            memory_top_k=3,
53            write_back=False,
54            tracer=tracer,
55        )
56        result = pattern.run(
57            "Draft a concise architecture recommendation for a serviceable edge device.",
58            request_id=request_id,
59        )
60
61    # Print the results
62    summary = result.summary()
63    print(json.dumps(summary, ensure_ascii=True, indent=2, sort_keys=True))
64
65
66if __name__ == "__main__":
67    main()

Expected Results

Run Command

PYTHONPATH=src python3 examples/patterns/rag.py

Example output shape (values vary by run):

{
  "success": true,
  "final_output": "<example-specific payload>",
  "terminated_reason": "<string-or-null>",
  "error": null,
  "trace": {
    "request_id": "<request-id>",
    "trace_dir": "artifacts/examples/traces",
    "trace_path": "artifacts/examples/traces/run_<timestamp>_<request_id>.jsonl"
  }
}

References