TPT Locus

Autonomous multi-agent orchestration framework. Locus is the central point of control — the locus — where agents, tools, and memory converge. It manages agent lifecycles, decomposes high-level goals into executable DAGs, handles state/memory, and resolves conflicts between collaborating agents.

See spec.txt for the full design and TODO.md for the phased implementation checklist.

Architecture

Layer	Technology	Crate / Module
Core runtime	Rust (Tokio async)	`tpt-locus-core`
Messaging bus	NATS pub/sub (+ gRPC later)	`tpt-locus-bus`
State & memory	TPT Keystone DB (hard dependency)	`tpt-locus-core` + `keystone` feature
Agent protocol	MCP	Phase 7
Observability	OpenTelemetry	Phase 8
API gateway	Go	`locus-gateway` (Phase 9)

┌────────────┐   goals    ┌──────────────┐   tasks    ┌──────────────────┐
│  Gateway   │ ─────────▶ │  Locus Core  │ ─────────▶ │  Agent processes │
│  (Go, WS)  │            │  DAG + FSM   │            │  (NATS pub/sub)  │
└────────────┘            └──────┬───────┘            └──────────────────┘
                                 │ persists
                                 ▼
                        ┌────────────────┐
                        │ TPT Keystone DB│  (relational + graph + vector)
                        └────────────────┘

Current status

Phases 0–8 are implemented and tested, plus the tpt-locus-cli developer tooling (Phase 13) and project documentation/benchmarks (Phase 14). See TODO.md for the live checklist — checked items are enforced by CI to correspond to real code (scripts/check-todo-drift.sh).

Implemented so far:

Rust workspace (tpt-locus-core, tpt-locus-bus, tpt-locus-cli, tpt-locus-mcp, tpt-locus-otel).
Agent lifecycle FSM: Idle → Thinking → ToolUsing → Blocked → Completed/Failed with exhaustive transition checks and unit tests.
Retry policy with exponential backoff + dead-letter escape hatch.
In-memory agent registry with capability advertisement.
StateStore persistence trait + MemoryStore (default) and a KeystoneStore backend (behind the keystone feature) that opens a real local TPT Keystone Database.
NATS pub/sub bus client with reconnect/backoff and hierarchical subjects, plus gRPC service definitions (TaskService / AgentControlService).
Goal decomposition (LLM-pluggable) → task DAG → wave scheduler with capability matching, cycle detection, and dynamic replanning (with audit trail + oscillation guard).
Shared blackboard (Keystone-backed) with vector retrieval, context budgeting, and access control; unified tool registry with timeout + fallback routing.
MCP client and server (stdio), with conformance tests.
Real multi-agent runtime: tpt-locus-cli orchestrate <goal> decomposes a goal, spawns one agent process per required capability, assigns task waves over NATS, and prints live DAG state; tpt-locus-cli dashboard renders per-agent throughput and tool-call latency.
Local dev harness (make harness / make run-goal / make dashboard) and example workflows under examples/.

Quickstart

# 1. Start NATS (requires Docker)
docker compose up -d

# 2. Run a real multi-agent goal end-to-end (spawns agent processes over NATS)
make harness
#    equivalent to:
#    cargo run -p tpt-locus-cli -- orchestrate "Research the topic. Summarize the findings. Write a report."

# 3. Run the test suite
cargo test --workspace

Watch the live "thought process" dashboard in a second terminal while a goal runs:

make dashboard

Keystone-backed persistence

cargo build -p tpt-locus-core --features keystone

This wires the real tpt-keystone crate (a path dependency in ../tpt-keystone-db) and persists lifecycle transitions durably to Keystone's storage directory.

Repository layout

tpt-locus-core/   DAG engine + agent lifecycle FSM + persistence
tpt-locus-bus/    NATS/gRPC messaging
tpt-locus-cli/    command-line client (demo, agent, orchestrate, goal, tools, blackboard, mcp, trace, dashboard)
tpt-locus-mcp/    MCP client + server
tpt-locus-otel/   OpenTelemetry init (OTLP export)
locus-gateway/  Go API gateway (Phase 9)
scripts/      CI helpers (TODO drift check)
examples/     runnable multi-agent workflow recipes
docs/         API reference + release checklist
docker-compose.yml  local NATS broker

License

Licensed under the Apache License 2.0 with LLVM Exception.

tpt-locus

Languages