kinetgraph

A pure, event-sourced ECS framework for building autonomous agents over Redis Streams.

The framework models agent state as a deterministic fold over an immutable event log. Side effects (LLM calls, HTTP requests, tool execution) run outside the fold, in isolated workers. The result is an agent whose entire history is replayable, whose state is a pure function of events, and whose tool calls are at-most-once even under at-least-once delivery.

When to use

• You need agents whose decisions are auditable and replayable from first principles.
• You want to run LLM calls in process-pool workers so the event loop never blocks.
• You need idempotent tool execution across retries and dispatcher restarts.
• You want a single Redis Stream as the source of truth, with no separate state DB.
• You are building multi-tenant systems where each agent has its own isolated event log.

Install

uv add kntgraph

Optional extras (install only what you need):

uv add "kntgraph[cli]"          # knt scaffold CLI
uv add "kntgraph[falkordb]"     # graph projection + Cypher (FalkorDB)
uv add "kntgraph[ollama]"       # local LLM / embeddings
uv add "kntgraph[gliner]"       # GLiNER2 NER — intent routing and PII redaction
uv add "kntgraph[api]"          # HTTP gateway (FastAPI)
uv add "kntgraph[crypto]"       # Ed25519 event signing
uv add "kntgraph[llm]"          # LiteLLM adapter
uv add "kntgraph[all-runtime]"  # everything above

To install the unreleased main between tagged releases: uv add "kntgraph @ git+https://github.com/kinetgraph/kinetgraph.git". Tagged releases on PyPI are the canonical, supported path.

Hello world

A agent runs as a pure fold over its event log; the side effects (LLM calls, HTTP requests, tool execution) live in systems that emit events and in tools that process them. The framework gives you three primitives that compose:

• Event — append-only, signed, idempotent. The EventLog is the source of truth.
• World — a pure fold of events into AgentViews with typed ECS components. Re-fold from event 0 to reproduce any past state exactly.
• System — a pure function (World) -> list[Event]. Emits events; never touches I/O.
• Tool — an async function decorated with @tool_worker, executed by a WorkerManager in a process pool. The dispatcher fans tool.requested events out to the worker pool, and the worker writes tool.<name>.completed back to the EventLog.

import asyncio
from kntgraph.core.event import Event
from kntgraph.core.result import Ok, Result, ToolError
from kntgraph.core.world import World
from kntgraph.tools.system import ToolAwareSystem
from kntgraph.tools.worker import tool_worker


# 1. A tool — runs in a worker pool, off the event loop.
@tool_worker(name="weather_api")
class WeatherTool:
    async def invoke(self, city: str, *, idempotency_key: str) -> Result[dict, ToolError]:
        return Ok({"city": city, "temp_c": 22, "condition": "sunny"})


# 2. A system — pure, observes the World, requests a tool.
class WeatherSystem(ToolAwareSystem):
    async def __call__(self, world):
        view = world.agents.get("weather-bot")
        if view is None or view.last_event_id is None:
            return []
        # Emit tool.requested only when a new city arrives.
        if "weather.requested" in view.components:
            return []
        return [Event.domain_from(
            agent_id="weather-bot",
            event_type="weather.requested",
            data={"city": "Rio"},
            correlation=world.agents["weather-bot"].correlation_id,
        )]


# 3. A pure fold — replayable, deterministic.
events = [
    Event.create("agent.spawned", agent_id="weather-bot", event_class="lifecycle"),
    Event.create("weather.requested", agent_id="weather-bot", event_class="domain",
                 data={"city": "Rio"}),
]
world = World.fold(events, tick=2)
print(world.agents["weather-bot"].components["weather.requested"])
# {"city": "Rio"}

Run this with a real ReactiveDispatcher and WorkerManager to see the system request the tool, the worker execute it, and the fold surface the completion — see examples/19_tool_worker_pattern.py for the full picture.

The agents sub-module ships concrete LLM, cache, and PII adapters on top of the framework:

from kntgraph.agents.tools import LiteLLMToolWorker

worker = LiteLLMToolWorker()
result = await worker.invoke(
    system="You are a helpful assistant.",
    user="What is the capital of France?",
    idempotency_key="k1",
)
# ``result`` is a ``Result[dict, ToolError]``; the dict
# envelope carries ``text`` / ``model`` / ``usage`` /
# ``finish_reason`` / ``cost_usd`` / ``latency_ms``.

What the framework provides

CLI scaffold

knt is the first-party CLI for scaffolding ADR-compliant projects and contexts:

# Install with the [cli] extra
uv add "kntgraph[cli]"

# Scaffold a new application
knt init project my_platform --use-intent-http

# Or choose a routing mode explicitly
knt init project my_platform --routing-mode external
# external   — routes intents from outside the agent boundary
# autonomous — agent resolves intents internally
# collaborate — multiple agents coordinate on a shared intent

# Add domain contexts and systems
cd my_platform
knt new context weather
knt new system weather.WeatherRouter
knt new tool weather.OpenMeteoApi

# Check for framework drift in boilerplate
knt upgrade check

See the CLI Guide for a full walkthrough.

Architecture

kntgraph/
├── src/kntgraph/
│   ├── core/        # Pure: ECS, Event, World, System
│   ├── stream/      # Redis Streams (EventLog, fold)
│   ├── runner/      # Side effects (Runner, ReactiveDispatcher,
│   │                #   WorldProjection, MemoryHydrationProjection,
│   │                #   ToolCallTTLSweeperSystem)
│   ├── events/      # Dead Letter Queue
│   ├── resilience/  # Circuit breaker, retry, bulkhead, etc.
│   ├── infra/       # Config, Redis pool, hashing
│   ├── tools/       # Tool Protocol, WorkerManager, worker, ACL
│   ├── api/         # Optional HTTP gateway
│   ├── security/    # Ed25519 signing, principal, ACL, PrincipalLevel
│   ├── memory/      # Session, Profile, Continuity managers
│   ├── knowledge/   # Embedding, FalkorDB graph, GraphRAG, GLiNER2
│   ├── testing/     # Public test utilities (fakes, stubs)
│   ├── cli/         # knt CLI — scaffold generator
│   └── agents/      # LLM/PII adapters, role_systems
│       ├── role_systems/ # ChatRoleSystem, PlannerRoleSystem, etc.
│       ├── tools/   # LiteLLMToolWorker, PiiRedactionTool
│       └── memory/  # Solution extractor/promoter
├── tests/
│   ├── unit/        # No external dependencies
│   ├── integration/ # Real Redis required
│   ├── agents/      # agents sub-module tests
│   ├── stress/      # 5 agents × 3 tools × 5 s concurrent load
│   └── scripts/     # CI contract tests (workflow split, etc.)
├── ADRs/            # Architecture Decision Records
├── docs/            # Public documentation
└── examples/        # Runnable end-to-end examples

Configuration

All settings live under the KNT_ env-var prefix and are loaded via Pydantic v2 BaseSettings. The canonical schema is Settings in kntgraph.infra.config.

Run the tests

# Unit (fast, no Redis required)
uv run pytest tests/unit/

# Integration (requires Redis on localhost:6379)
uv run pytest tests/integration/

# Agents sub-module tests
uv run pytest tests/agents/

# Stress suite (requires Redis on localhost:6379)
uv run pytest tests/stress/

# CI contract tests
uv run pytest tests/scripts/

Documentation

• Getting Started — mental model and your first agent.
• Quick Start — 5-minute install and "hello world".
• Architecture — the three pillars (ECS, event sourcing, resilience) and how the pieces fit together.
• Zero Token Architecture — software handlers before LLM, read-side cache, hybrid dispatcher stack.
• API Reference — the public API map, env-var table, and common patterns.
• CLI Guide — scaffolding projects, contexts, systems, tools, and agents.
• docs/ — full index of all docs.
• ADRs/ — Architecture Decision Records.

Quality gates

The badges below mirror the gates in scripts/ci.py. Values are generated by scripts/quality_report.py on every CI run and pinned in docs/quality.md.

Pyright: 0 errors above the baseline (warnings tracked separately; see DEBT.md §4.2 for the warning budget).

Project status

Full changelog: CHANGELOG.md.

License

Apache License 2.0. See LICENSE.

Contributing

See CONTRIBUTING.md for development setup, the CI gate, and the pull request workflow. Bug reports and security disclosures follow SECURITY.md.

Project metrics