Lattice is a production-grade autonomous research agent framework written in Python. It rejects overly complex state-graph architectures in favor of a lean, iterative execution loop reinforced by token-based Jaccard self-validation loop guards, declarative tool registries, and plug-and-play LLM providers.
Inspired by Charlie Munger’s mental models of multi-dimensional understanding, Lattice is designed to systematically explore queries, cross-reference sources, prevent cognitive loops, and synthesize deep analytical resolutions.
Lattice implements a clean, production-grade linear loop architecture inspired by leading AI research agents like Dexter (virattt/dexter). Instead of relying on hyper-complex state-graph branch DAGs, the framework organizes cognitive reasoning around an elegant, sequential workflow loop:
-
Inbound Request: A query is received through either the interactive CLI (
TerminalGateway) or incoming WhatsApp webhook events (WhatsAppGateway). -
Prompt Compilation: The orchestrator dynamically aggregates instructions, active tools schema definitions, and the agent's durable persona defined in
SOUL.md. -
Execution Loop (Step 1 to N):
- LLM Routing: Dispatches the compiled prompt state to the active provider router adapter (Gemini, OpenAI, or offline Ollama).
-
Jaccard Loop Guard Validation: Intercepts proposed queries, tokenizing and cleaning words to compute similarity against history. If a repeat behavior is detected (
$\ge 0.7$ similarity), it blocks execution, injects a warning, and forces a cognitive pivot to protect against infinite loops and runaway API costs. -
Declarative Tool Execution: Dispatches validated tool arguments to the centralized
ToolRegistry(web searches, readers, or outgoing WhatsApp notifications). - Scratchpad Logging: Dynamically logs the thought, action, and resulting observation back to the agent's state manager.
- Synthesized Response: Once sufficient data is accumulated, the agent terminates the cycle and synthesizes a grounded, final analytical response back to the client interface.
- Recursive Orchestration Loop: A unified, step-by-step reasoning cycle executing thoughts, actions, and observations.
- Jaccard Similarity Validation: Proactively tokenizes, cleans, and computes word overlap (threshold >= 0.7) between consecutive queries to immediately flag and block infinite agent execution loops.
- Durable Identity Layer (SOUL.md): Fully decouples the agent's cognitive persona, behavioral protocols, and domain directives from source code.
- Model-Agnostic Routing: Integrated adapters to swap between Google Gemini (google-genai), OpenAI (openai), and offline Ollama backends.
- Declarative Tools: Clean, schema-driven tool creation using standard parameter validation maps.
- Aesthetic Terminal REPL: An interactive command-line experience with loading spinners, ANSI typography, and visual step indicators.
lattice-agent/
├── SOUL.md # Cognitive personality and analytical bounds
├── main.py # Application entry point & bootstrap loading
├── examples.py # Programmatic API & custom tool examples
├── requirements.txt # Essential library dependencies
├── LICENSE # Software license agreement
├── agent/
│ ├── agent.py # Main execution loop and JSON tool parsers
│ ├── prompts.py # Prompt compilers (SOUL.md integration)
│ ├── scratchpad.py # State manager tracking thoughts & actions
│ └── validation.py # Tokenizer & Jaccard Index calculator
├── providers/
│ └── router.py # LLM client adapters (Gemini, OpenAI, Ollama)
├── tools/
│ ├── base.py # Abstract BaseTool blueprint class
│ ├── registry.py # Centralized loading and tool execution
│ ├── web_search.py # Serper API + DuckDuckGo HTML scraping
│ └── reader.py # Web reader and HTML tag stripping
├── gateways/
│ └── terminal.py # Interactive console shell gateway
├── docs/
│ ├── architecture.md # Deep technical architecture details
│ ├── getting_started.md # Installation & operation handbook
│ └── images/ # Branding, blueprints, and console mockups
└── tests/
├── test_jaccard.py # Jaccard index unit tests
└── test_loop_detection.py # Validation triggers assertionsObserve a standard research flow when starting the CLI:
=======================================================
__ ______ ______ __ ______ ______
/ / /\ /_ __//_ __// / / ____// ____/
/ / / \ / / / / / / / __/ / __/
/ /___/ /\ \ / / / / / /__/ /___ / /___
/____/_/ \_\\_/ /_/ /____/_____//_____/
COGNITIVE SYNTHESIS ENGINE (Python Edition)
=======================================================
Type any research question to prompt the agent.
Type 'exit' or 'quit' to terminate the session.
Lattice > Search for the latest price of Google stock.
Thinking...
✔ Step Completed.
Action: web_search
=== SYNTHESIZED RESPONSE ===
Based on active market data research, Alphabet Inc. (GOOGL) stock is currently trading at $174.50, representing an increase of +1.2% in today's trading session. Alphabet's market capitalization is estimated at $2.15T with a P/E ratio of 26.4. The company's recent growth has been driven by high demand for Google Cloud infrastructure and advancements in multi-modal Gemini models.
============================
Lattice prevents runaway agent costs. Watch the Jaccard similarity validator block a duplicate search query and force the agent to pivot:
Lattice > Search for current price of Google stock, then search for it again.
Thinking...
✔ Step Completed.
Action: web_search
[Loop Guard] Looping query detected! Similarity: 100.0%
> [!WARNING]
> COGNITIVE GUARD TRIGGERED:
> LOOPING BEHAVIOR DETECTED: Proposed search query "Search for current price of Google stock" shares a 1.0 Jaccard Index similarity with a previously executed query. Execution has been blocked. Pivot your analytical strategy.
✔ Step Completed.
Action: (Cognitive Pivot & Synthesis)
=== SYNTHESIZED RESPONSE ===
Alphabet Inc. (GOOGL) is currently trading at $174.50. I intercepted a repetitive web search request to avoid redundant API execution costs and cognitive loops. The query is identical to our first step which successfully retrieved the current market details.
============================
Below is the output log when starting Lattice in GATEWAY=whatsapp mode and receiving an inbound query webhook from a phone:
=======================================================
LATTICE WHATSAPP INTEGRATION GATEWAY
=======================================================
✔ WhatsApp Webhook Server Booted successfully.
Listening at: http://0.0.0.0:5000/webhook
Configure your Twilio Sandbox Webhook to point here using ngrok!
[WhatsApp Webhook Received]
Sender: whatsapp:+14155238886
Message: "What is the weather in San Francisco?"
Starting autonomous reasoning loop...
[Lattice] Bootstrapping research for task: "What is the weather in San Francisco?"
Running with Provider: google-genai | Max Steps: 10
--- Starting Step 1/10 ---
[Lattice Tool] Invoking: web_search (Arguments: {"query": "weather in San Francisco"})
[web_search] Searching for: "weather in San Francisco"...
--- Starting Step 2/10 ---
✔ Synthesis Complete. Routing reply back to whatsapp:+14155238886.
You can run our curated developer script to observe programmatic execution flow and see how easy it is to register custom tools in the registry:
python examples.pyEmbark on the Lattice journey by exploring our highly detailed visual documents:
- Technical Architecture Guide: Explore the cognitive pipeline, Jaccard calculations, and provider wrappers.
- Getting Started Handbook: Set up virtual environments, configure environment parameters, and launch the interactive REPL terminal.
Developed and maintained by Rignesh P.
Lattice is open-source software licensed under the MIT License.