lithe

lithe is a reusable, storage-free ReAct agent kernel for Python: the engine, framework, and protocols that drive a tool-calling agent, plus optional capability bundles. The kernel knows nothing about how runs are stored — or even whether they are — so any application (a thesis-writing platform, a coding agent, a support bot) supplies its own tools, system prompt, and persistence, and reuses everything else: the loop, the event stream, undo, and delegation.

Highlights

• Zero-I/O core. import lithe performs no file or network I/O. Every module in the root package is pure engine + protocol; anything that touches a disk or a socket ships as an optional bundle.
• Storage-free by design. Persistence is a pair of host-supplied interfaces (an EventSink to write, a MemoryProvider to replay). Don't want storage? Pass nothing. Want storage? JsonlRunStore is the zero-database default.
• An honest event stream. Streaming assistant_delta events, a usage event per model call (tokens, cost, context fullness), tool calls announced before they execute, and cancellation that closes the in-flight model stream instead of paying for a response nobody wants.
• Undo built in. Every bundled write tool registers a reverter; the UndoEngine is pure and storage-free like the rest of the core, and AgentHost exposes one-call undo_run.
• Delegation without context bloat. Subagents run isolated, are tagged so undo still reverts their work, fan out in parallel with per-delegation budgets, and fold their spend back into the parent run's stats.
• Any OpenAI-compatible endpoint. Chat-completions and Responses protocols behind one interface, with retries, jittered backoff, Retry-After-aware 429 handling, and SSE streaming; usage is normalized to one shape across both.

Install

pip install lithe
# local development (editable install + test/lint deps):
pip install -e ".[dev]"

Requires Python 3.10+. The only runtime dependency is httpx.

Quickstart

A minimal host: sandboxed file tools, a JSONL store, and a run.

from lithe import AgentContext, LLMConfig, ToolRegistry
from lithe.bundles import AgentHost, JsonlRunStore
from lithe.bundles.workspace import Workspace, register_file_tools

registry = ToolRegistry()
# workspace_for(ctx) -> Workspace (a sandboxed root per user):
register_file_tools(registry, lambda ctx: Workspace(f"/data/{ctx.user_id}"))
store = JsonlRunStore("/var/lib/myapp/agent")                       # zero-DB default
host = AgentHost(registry,
                 LLMConfig(model=..., base_url=..., api_key=...),
                 store, build_system_prompt=my_prompt_builder)

ctx = AgentContext(run_id=rid, user_id=uid)
async for event in host.run(ctx, task, history=prior_turns):
    ...  # forward run_start / step / tool_call / tool_result / done to your frontend

A host supplies only its tools, system prompt, and (optionally) a store backend — the engine, persistence, run envelope, undo, and (via subagents) delegation are all reused.

Architecture

Core — lithe (zero I/O, zero business logic)

Bundles — lithe.bundles (optional capabilities)

from lithe.bundles import MCPManager, MCPServerConfig

manager = MCPManager([MCPServerConfig(
    name="zai", command=["npx", "-y", "@z_ai/mcp-server"],
    env={"Z_AI_API_KEY": "...", "Z_AI_MODE": "ZHIPU"},
    default_category="read")])
await manager.attach(registry)   # registry gains zai__* tools

Safety defaults

Long-lived autonomous loops need guardrails on by default:

• Path sandboxing — workspace tools resolve inside the sandbox root; directory walks never follow symlinks, so code executed by run_code cannot plant a link to a host file and read it back.
• SSRF guard — download_file accepts only globally routable http/https addresses, re-validating every redirect hop (cloud metadata endpoints included in the rejection set).
• Secret hygiene — spawned MCP servers get an env allow-list, never the parent environment; URLs log as scheme://host so credentials in query strings never reach a log line.
• Shell execution is explicit — run_command is an optional host bundle, not a default tool. When enabled, commands run with the host user's permissions; they are not sandboxed and their side effects cannot be undone.
• Write serialization — READ tools run in parallel, every WRITE/META tool runs alone in model order: no write races.
• Run budgets — max_cost / max_total_tokens cut a runaway run short with no further tool execution or model calls.

Storage model

The kernel stores nothing. A host provides:

• an EventSink (write side) — persists message records however it likes (DB / file / nowhere);
• a MemoryProvider (read side, optional) — replays prior turns;
• an UndoEngine fed from wherever the host kept actions.

More

• examples/minimal_host.py — a runnable, offline minimal host (tools → run → events → undo); runs in CI.
• examples/live_host.py — the same flow against a real OpenAI-compatible endpoint (set LITHE_API_KEY / LITHE_BASE_URL / LITHE_MODEL; no default endpoint, it never spends tokens by accident).
• CHANGELOG.md — what changed and when.

License

MIT