StarGraph - Core (stargraph)

Stateful agent-graph framework with deterministic governance.

Part of the Kraken stack: Fathom (reasoning engine) · Nautilus (policy data broker) · Stargraph (agent-graph framework).

Stargraph composes LLMs, classical ML models, tools, and deterministic logic into auditable, replayable graphs. Transitions between nodes are decided by Fathom (a CLIPS rules engine) over provenance-typed facts — not by an LLM playing router.

Coming from LangGraph, CrewAI, or AutoGen? Stargraph is the governed, auditable alternative: node transitions are decided by versioned rules instead of the model, every run is replayable, and provenance is typed end-to-end — built for compliance, regulated, and air-gapped deployments.

Status: v0.3.0 — Alpha. Public API is unstable until v1.0. Built for environments where auditability, determinism, and provenance matter more than ecosystem size (DoD, regulated, air-gapped, cleared workloads).

The thesis

LLMs are knowledge engineers, not inference engines. CLIPS is a better inference engine than any LLM. Use the right tool for each job and let rules — not LLMs — decide what happens between tools.

In most agent frameworks the LLM is both the worker and the router: it does the thinking and picks the next step. That is fine for demos and brittle in production. Stargraph splits the job. Nodes do work (LLM calls, ML inference, tool invocations, retrieval). Rules decide what happens next. The decision layer is inspectable, versioned, replayable, and free of stochastic drift.

What you get

• Rule-routed graphs. No static edges. Transitions are derived at runtime by Fathom rules matching against typed facts in CLIPS working memory.
• Provenance-typed facts. Every fact carries (origin, source, run_id, step, confidence, timestamp). Origins are typed: llm | tool | user | rule | model | external. Trust is a first-class type.
• Classical ML as first-class nodes. sklearn, XGBoost, and ONNX models run alongside DSPy LLM modules; PyTorch (incl. SB3 policies) publishes into the ONNX runtime via the stargraph[onnx-export] export path. Route on confidence, fall back to LLMs only when the cheap model is unsure.
• Counterfactual replay. Checkpoint pinning + structural graph hashing makes deterministic replay free. Re-execute from any step with mutated rule, node output, or fact, and diff against the original run.
• Pluggable stores behind Protocols. VectorStore (LanceDB), GraphStore (RyuGraph), DocStore/MemoryStore/FactStore (SQLite). Embedded by default, swappable for hosted providers.
• Boundary-clean state. Mutate Pydantic state freely inside a node. On exit, annotated fields mirror into CLIPS, rules fire, checkpoint persists. Predictable, testable, transactional.
• Two authoring modes. Python with full Pydantic typing, or YAML with a compiled subset for non-Python contributors. One runtime truth.
• Headless serving. stargraph serve exposes HTTP + WebSocket triggers (manual, cron, webhook) over FastAPI with OpenAPI 3.1.

Architecture

stargraph serve            triggers, scheduler, HTTP/WS, run history
       │
stargraph.Graph            orchestration, streaming, checkpointing
       │
stargraph.skills           agents-as-subgraphs, tool registry, plugins
       │
Bosun rule packs        budgets, retries, safety, audit (Fathom rules)
       │
Fathom (CLIPS)          routing and governance inference
       │
Nodes:  DSPy │ ML models │ tools │ retrieval │ memory ops

Install

uv add stargraph                          # core
uv add 'stargraph[ml]'                    # + sklearn / xgboost / onnxruntime
uv add 'stargraph[stores]'                # + lancedb / ryugraph / pyarrow
uv add 'stargraph[skills-rag]'            # + sentence-transformers

Requires Python 3.13.

Quick taste

A graph that runs a cheap intent classifier first and only falls back to an LLM when confidence is low:

nodes:
  classify_intent: ml:intent_clf@v3 # XGBoost
  fallback_llm: dspy:intent_predict
  act: tool:do_thing

rules:
  - when: { classify_intent.confidence: { lt: 0.7 } }
    then: { goto: fallback_llm }
  - when: { last: classify_intent, classify_intent.confidence: { gte: 0.7 } }
    then: { goto: act }

governance: [bosun:budgets, bosun:audit]

Run it:

stargraph run path/to/graph.yaml
stargraph serve                          # FastAPI on :8000

Counterfactual replay from Python:

run = stargraph.load_run("r-7af2")
alt = run.counterfactual(step=4, mutate={"facts.intent": "research"})
diff = stargraph.compare(run, alt)

Concepts at a glance

The full glossary, including disambiguations like node vs tool and state vs facts, lives in design-docs/stargraph-concepts.md.

What Stargraph is not

• Not a prompt-optimization framework — that's DSPy, which Stargraph uses.
• Not an inference engine — that's Fathom/CLIPS, which Stargraph uses.
• Not a vector or graph DB — Stores wrap real ones (LanceDB, RyuGraph, …).
• Not a workflow UI — stargraph serve is headless. UI is a future product.
• Not chasing LangGraph or n8n on mindshare. It competes on correctness, inspectability, and ability to run where those tools can't.

Project layout

src/stargraph/
  graph/          Graph, Run, transitions, streaming
  runtime/        Engine, scheduler, concurrency
  nodes/          DSPy, ML, retrieval, memory, tool-call nodes
  fathom/         Adapter to the Fathom CLIPS engine
  bosun/          Reference governance rule packs
  skills/         RAG, autoresearch, wiki, ReAct
  stores/         Vector/Graph/Doc/Memory/Fact protocols + providers
  tools/          Tool registry + Nautilus broker tool
  triggers/       manual / cron / webhook
  serve/          FastAPI HTTP + WebSocket API
  checkpoint/     Per-transition persistence (SQLite default, Postgres adapter)
  replay/         Counterfactual replay engine
  cli/            stargraph run / serve / inspect / replay / counterfactual
  ir/             YAML → IR compiler
  ml/             Classical-ML node integrations
demos/            End-to-end reference graphs (PR review, SOC triage, …)
design-docs/      Concepts, design, ADRs, plugin API, roadmap
docs/             User-facing docs site (mkdocs)
tests/            unit · integration · property · replay · migration

Documentation

• Getting Started
• Concepts & Glossary
• Design Document
• Architecture Decision Records
• Plugin API
• Roadmap

Full site: https://stargraph.krakn.ai

Sister projects

Stargraph is part of the Kraken Networks stack:

• Fathom — CLIPS rules engine Stargraph delegates routing and governance to.
• Bosun — reference rule packs (budgets, retries, audit, safety) shipped in stargraph.bosun.*.
• Nautilus — knowledge broker; ships an in-tree Stargraph tool (stargraph.tools.nautilus.broker_request).
• Railyard — Stargraph's Go predecessor. Stargraph is the Python cousin and may supersede it.

Development

make install            # uv sync --group dev --group docs
make lint               # ruff
make typecheck          # pyright (strict)
make test               # unit
make test-all           # everything (needs Fathom + integration deps)
make docs-serve         # local docs site

Contributions: see CONTRIBUTING.md and CODE_OF_CONDUCT.md. Security disclosures: SECURITY.md.

Star History

License

Apache-2.0. See LICENSE.