Lethe

Graph-native agentic orchestrator with web research.

Lethe automates deep investigation of complex questions. Given a natural-language goal, it decomposes the problem into a directed acyclic graph of tasks, iteratively reasons over each task through web crawling and LLM-generated structured operations, and assembles a comprehensive final answer grounded in discovered evidence.

The system runs two tightly coupled loops that share a common embedding algebra:

• Agent loop --- an LLM reasons over structured graph context and emits validated JSON operations that mutate a task DAG in Neo4j. The orchestrator handles all quantitative control (task selection, budget management, convergence detection) through vector-space computations the LLM never observes.

• Research engine --- a zero-LLM web research engine discovers, crawls, and embeds pages using the same spectral algebra. GA-ranked URL discovery, sliding-window fetch+embed streaming, and spectral convergence for optimal stopping.

Neo4j is the single source of truth --- working memory (tasks), episodic memory (evidence), and semantic memory (SIMILAR_TO edges) in one graph. No separate vector store.

Key Design Decisions

LLM reasons, orchestrator computes. The LLM never sees budget counters, convergence scores, or similarity thresholds. The embedding algebra behind a single compute_iteration_signals() interface drives all numeric decisions deterministically.

Continuous control surfaces. No boolean gates. Budget pressure follows an exponential horizon curve. Convergence is a weighted blend of three continuous signals (goal alignment, stability, reconstruction error). Exploration-to-exploitation emerges from geodesic computations on the unit hypersphere.

Submodular context packing. Each iteration, Personalized PageRank expands candidates from the task graph, then a greedy knapsack with incremental Marginal Information Gain and AdaGReS redundancy scaling packs evidence into the token budget with a 0.632-approximation guarantee (Lin and Bilmes, NAACL 2010).

Graph as memory. Unlike RAG architectures with separate vector databases, Lethe stores embeddings as node properties in Neo4j. SIMILAR_TO edges serve as a nearest-neighbor index within the graph topology, enabling PPR to traverse both structural and semantic links in a single computation.

Architecture

These design decisions shape how the codebase is organized. Each package below owns one concern, with import boundaries enforced in the Makefile:

src/lethe/
├── main.py / server.py     Session lifecycle, OpenAI-compatible API
├── config/                  Frozen configuration hierarchy (single source of truth)
├── graph/                   Neo4j substrate (schema, store, queries, evidence ingest)
├── din/                     LLM ↔ orchestrator protocol (8 JSON op types)
├── embed/                   Embedding algebra (spectral, temporal, batch signals)
├── context/                 PPR expansion → scoring → knapsack packing
├── loop/                    Iteration coordinator + budget management
├── llm/                     Stateless reasoning model client (thinking, repair)
├── compose/                 Final answer: DFS sections → MMR ordering → LLM compose
├── search/                  Zero-LLM research (discovery, streaming, convergence)
├── tools/                   Tool registry + semantic query dedup
└── drivers/                 I/O adapters (CloakBrowser, embed batching, whisper.cpp)

Import boundaries are enforced in the Makefile: search/ cannot import loop/ or din/, embed/ cannot import graph.store, and so on. The research engine shares algebra with the agent loop but not orchestration.

Stack

Component	Technology
Reasoning	Qwen 3.6 27B (llama.cpp, Q4_K_XL)
Embeddings	Qwen3-Embedding-4B (llama.cpp, 2560-d)
Graph	Neo4j 5.x Community
Search	SearXNG metasearch
Browser	CloakBrowser (CDP, anti-detection)
STT	whisper.cpp (large-v3-turbo)
Numerics	NumPy (SVD, PPR, spectral analysis)
API	Starlette + Uvicorn (POST /v1/responses — Open Responses spec)

Quick Start

cp .env.example .env
# Place GGUF models in .models/
docker compose up -d
curl -N -X POST http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model":"lethe","input":[{"role":"user","content":"Your research question"}],"stream":true,"background":true,"session_id":"demo"}'

Requires ~21 GB GPU VRAM (both models with Q4 KV caches). See Deployment for details.

Development

uv sync --all-extras
make check    # lock + format + lint + typecheck + boundary-check + test
make fix      # auto-format + auto-fix

Documentation

Start here: Overview covers design philosophy, a session walkthrough, and the reading order for all pages.

• Overview --- how Lethe works, design philosophy, capabilities
• Architecture --- module structure, dependency boundaries, three-layer separation
• Agent Loop --- iteration cycle, task selection, budget management, termination
• Graph Memory --- Neo4j schema, task lifecycle, evidence model, SIMILAR_TO edges
• DIN Protocol --- structured LLM communication, 8 operation types, parse and repair
• Embedding Algebra --- signal pipeline forming the quantitative control plane
• Context Composition --- Personalized PageRank and submodular knapsack packing
• Research Engine --- zero-LLM web research with information foraging theory
• Configuration --- complete reference for all tunable parameters
• Deployment --- Docker Compose stack, GPU requirements, environment setup

What Makes It Different

Dimension	Typical LLM Agent	Lethe
Control	Prompt-based ("you have 5 iterations left")	Embedding algebra --- no control signals in prompt
Research	LLM decides what to search	Zero-LLM research engine with GA scoring and spectral convergence
Memory	Chat history or flat vector store	Neo4j graph with structural + semantic edges
Context	Fixed retrieval or full history	Submodular knapsack with PPR expansion per iteration
Termination	Fixed iteration count or LLM self-report	Continuous convergence from 3-signal weighted blend

Algorithms and Techniques

The system draws from graph algorithms (Personalized PageRank), submodular optimization (greedy knapsack with Marginal Information Gain), spectral methods (SVD eigengap, Grassmannian chordal distance), information foraging theory (embedding-based relevance scoring with spectral convergence for stopping), and $C^\infty$ smooth control primitives replacing all boolean gates.

See Algorithms and Techniques for the full treatment with citations and design rationale.

Status

Pre-release. AGPL-3.0-or-later.