Skip to content

Quickstart

Once you have installed the package with a provider extra and set your API key in .env, here's the smallest end-to-end run:

from agentic_architectures import get_llm
from agentic_architectures.architectures import Reflection

arch = Reflection(llm=get_llm(), max_iterations=2, target_score=8)
result = arch.run("Write a haiku about a glacier.")

print(result.output)
print("score:", result.metadata["final_score"], "/ 10")
print("iterations:", result.metadata["iterations"])

Every architecture follows the same contract:

class Architecture(ABC):
    name: str
    description: str
    reference: str

    def build(self) -> CompiledStateGraph: ...
    def run(self, task: str, **kwargs) -> ArchitectureResult: ...

And every .run() returns:

@dataclass
class ArchitectureResult:
    output: str                          # the user-facing answer
    state: dict[str, Any]                # architecture-specific state snapshot
    trace: list[dict[str, Any]]          # per-node trace events
    metadata: dict[str, Any]             # numeric / boolean signals

So you can compose architectures uniformly:

from agentic_architectures.architectures import Reflection, AgenticRAG, ChainOfVerification
from agentic_architectures.data import STARDUST_CORPUS

llm = get_llm()

for cls in (Reflection, AgenticRAG, ChainOfVerification):
    kwargs = {"documents": STARDUST_CORPUS} if cls is AgenticRAG else {}
    arch = cls(llm=llm, **kwargs)
    r = arch.run("What propellant does the Phoenix-2 engine use?")
    print(f"{cls.__name__:25s} → {r.output[:80]}")

Run all 35 architectures end-to-end

Every notebook is fully runnable. From the repo root:

.venv/Scripts/python.exe -m papermill notebooks/18_reflexion.ipynb /tmp/out.ipynb --kernel python3

Or use the build scripts to regenerate them:

.venv/Scripts/python.exe scripts/build_18_reflexion.py
.venv/Scripts/python.exe -m papermill notebooks/18_reflexion.ipynb notebooks/18_reflexion.ipynb --kernel python3
.venv/Scripts/python.exe scripts/tailor_18_commentary.py

Next