The Problem

Modern agentic systems often struggle with the reliability of LLM-as-scorer mechanisms, where probabilistic free-text outputs lead to inconsistent agent behavior—colloquially known as the "flat-band pathology." This repository addresses that instability by implementing a deterministic-picker pattern, requiring LLMs to commit to categorical features (booleans, enums) rather than unstructured scores, allowing Python to compose the final decision signal.

What This Does

The project provides a Python library implementing 35 distinct agentic AI patterns, ranging from Reflexion and LATS to GraphRAG and Voyager. Each architecture ships as a runnable Architecture class with a uniform .run(task) interface, all documented in Jupyter notebooks located in docs/architectures/ and notebooks/. A central technical discipline across 13 architectures is the deterministic-picker pattern, which structures LLM outputs into categorical features for reliable Python-side composition; a further 9 architectures are architecturally immune to the scorer pathology by design. The library is multi-provider, supporting Nebius, OpenAI, Anthropic, Groq, Ollama, Together, Fireworks, Mistral, and Google, and is built on top of LangGraph state machines.

How It Is Wired

Execution begins by instantiating a specific Architecture subclass (e.g., Reflection, LATS) from src/agentic_architectures/architectures/. These classes accept an LLM instance via get_llm() and a task string. The uniform .run(task) method triggers the architecture-specific state machine logic. The deterministic-picker logic is embedded within the scorer components of architectures like Reflexion, ensuring the LLM's output is parsed into structured Python types before further processing. The pyproject.toml file manages package dependencies, while environment variables configured in .env.example handle LLM provider credentials. The code touches external networks via API calls to the configured LLM providers and manages state internally through LangGraph state persistence.

How To Use It

Setup:

pip install "agentic-architectures[nebius,faiss,tavily]"

Configuration: Copy .env.example and populate the required API keys for the desired LLM provider (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY).

Running it: Use the uniform .run(task) interface demonstrated in the quickstart:

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)

Real-World Use

A practical use case involves deploying Reflexion to improve output quality in a closed-loop generation task. By instantiating Reflection(llm=get_llm(), max_iterations=2), the architecture iteratively queries the LLM and scores outputs against a target, leveraging the deterministic-picker to halt when the score threshold is met. This pattern is applicable for improving reliability in tool-use agents or code generation workflows where output validation is critical.

Code Health & Issues

A heuristic analysis identified one low-risk finding: dependencies are declared in pyproject.toml without a corresponding lockfile, which may lead to non-reproducible builds across environments. Beyond this, the repository structure is well-organized with extensive documentation and test coverage (283 passing tests per the README), though the absence of a lockfile is the primary static analysis finding.

The Bottom Line

This repository is a valuable resource for experimenting with and comparing 35 major agentic AI patterns within a consistent framework. The multi-provider support and the deterministic-picker pattern offer a practical solution to LLM reliability concerns. However, the lack of a dependency lockfile presents a reproducibility risk for production deployment that should be addressed before integrating into strict CI/CD pipelines.