BaselithCore

Agents that survive production. Durable execution, enforced budgets, and EU AI Act evidence — self-hosted, with no companion SaaS.

BaselithCore is a Python orchestration engine for agentic AI. Execution state is checkpointed as a run proceeds, so an interrupted process resumes from its last completed step instead of replaying side effects. Every request carries a budget that caps iterations, tool calls, tokens and USD spend, and every step emits OpenTelemetry spans and Prometheus metrics with real cost attached — the audit trail a regulated deployment has to produce is written while the system runs, not reconstructed from logs afterwards.

1.0 is the stable line. The public baselith API follows Semantic Versioning: a breaking change waits for a major release and goes through a deprecation cycle first. Coming from 0.x? The top-level core and plugins packages moved under baselith, the long-deprecated shims are gone, and several security postures now fail closed — Migrating to 1.0 has the checklist and upgrade notes the details.

Writing a plugin? You keep your source. The plugin exception lets any plugin that uses the framework as a library ship under any licence you like, including a closed one. Same terms for everyone.

Why BaselithCore

• Agents that survive production. Durable execution with checkpoint/resume, replayable tool steps, state history and fork/rewind — a SIGKILL mid-run recovers without repeating a single side effect.
• Everything included, nothing rented. Evaluation suites, LLM-as-judge, red-teaming, OpenTelemetry tracing, Prometheus metrics with real USD cost, Helm and Terraform deployment — built in, self-hosted, no companion SaaS to subscribe to.
• Brakes, not just horsepower. Autonomy gating, durable human-in-the-loop approvals, per-request cost budgets, prompt-injection guardrails and sandboxed code execution, every seam fail-closed by default — plus opt-in EU AI Act, GDPR, NIS2 and DORA primitives with evidence trails.

Quick start

Kick the tyres without installing anything:

uvx --from baselith-core baselith --version

Then take it as a library, in one command. The distribution is baselith-core on PyPI:

uv pip install baselith-core        # or: pip install baselith-core

import asyncio

from baselith import Agent, Crew, Task

researcher = Agent(system_prompt="You are a meticulous researcher.")
writer = Agent(system_prompt="You write crisp executive summaries.")

crew = Crew(agents=[researcher, writer], tasks=[
    Task("Research {topic} and list the key facts.", agent=researcher),
    Task("Write a summary from the research.", agent=writer),
])


async def main() -> None:
    result = await crew.run(inputs={"topic": "vector databases"})
    print(result.final)


asyncio.run(main())

Typed, budgeted and observable from the first line — the quickstart adds tools, structured output and a checkpoint store.

baselith is the public API and the only surface that carries a compatibility promise; import baselith costs ~3 ms because names resolve lazily. The framework's own packages live under baselith.core.* and each declares what it promises — see API stability tiers.

Or the whole runtime — API, PostgreSQL, FalkorDB and Qdrant, plus two Hugging Face Text Embeddings Inference servers for embedding and reranking, with migrations applied at startup. From a checkout of this repository, with Docker running:

uv pip install -e .             # installs the `baselith` CLI
baselith setup docker-core      # writes .env and configs/.env.docker.core
docker compose --env-file configs/.env.docker.core -f docker-compose.core.yml up -d --wait
baselith doctor                 # environment and configuration diagnostics

--wait returns only once every health check is green, so the next line can assume the stack is serving:

curl --fail http://localhost:8000/health

In a project generated by baselith init, baselith up does all of this for you: it writes the runtime files, builds and waits for /health in one command.

Optional capabilities (RAG, browser automation, OCR, extra model providers, vector backends, …) install as extras — the installation guide lists them, and the Docker Core guide covers the checkout-based runtime in full.

Plugins

Everything domain-specific is a plugin, and the CLI does the plumbing. Scaffold one, check it, run it — without leaving the terminal:

baselith plugin create my_plugin --type agent               # manifest.yaml, plugin.py, agent.py
baselith plugin validate my_plugin                          # syntax, manifest, schema, deps, env vars
baselith plugin add my_plugin --name my_plugin --docker     # build, rebuild the API image, probe HTTP

--type picks the shape: agent, router or graph. Running someone else's plugin is the same add command with a Git URL, and the marketplace is one command away:

baselith plugin add https://github.com/your-org/plugin-example --docker
baselith plugin marketplace search browser
baselith plugin marketplace install <plugin-id>

baselith plugin list, status and logs cover day-to-day work; sign writes the integrity hash a hardened deployment verifies before it imports anything.

The distribution ships official plugins under baselith.plugins, each signed and strictly typed: api_routers, browser_agent, coding_agent, document_sources, goals, payments (a reference AP2 adapter), reasoning_agent and web_scraper.

The first-plugin tutorial walks one end to end · creating plugins · packaging · marketplace

Architecture at a glance

graph TD
    subgraph SC["Sacred Core (Agnostic Engine)"]
        A["Core Orchestrator<br/>(intent · routing · adaptive loop · durable checkpoint/resume)"]
        F["Flow Handlers"]

        subgraph COG["Cognitive Layer"]
            RE["Reasoning<br/>(MCTS · Tree-of-Thoughts)"]
            WM["World Model<br/>(risk · rollback · simulation)"]
            SW["Swarm<br/>(auction protocols)"]
            PL["Planning"]
            MT["Meta · Reflection · Adversarial"]
        end

        LP["Engineered Loops<br/>(verifier · stall guard · escalation)"]
        M["Memory Hierarchy<br/>(STM → MTM → LTM)"]
        S["Storage Layer<br/>(Postgres · Qdrant/pgvector · Redis)"]
        R["Plugin Registry"]
        RES["Resilience · Observability · Guardrails"]
        GOV["Governance<br/>(autonomy gating · human-in-the-loop · budgets · compliance evidence)"]
    end

    A --> COG
    A --> F
    A --> LP
    A --> M
    M --> S
    COG --> M

    R --> C["Custom Agent Plugins"]
    R --> D["Capability Extensions"]
    R -.->|Inject Handlers| A
    R -.->|Inject Routers| G["API Gateway"]

    A --> H["LLM Layer<br/>(Anthropic · OpenAI · Gemini · Ollama · HF)<br/>native tool-calling · typed output · cross-provider fallback"]
    F --> H

    A --> I["Interop<br/>(MCP · A2A streaming · AP2 mandates · realtime duplex)"]
    A -.->|wrapped by| RES
    A -.->|gated by| GOV

Two rules hold the shape: baselith/core/ stays domain-agnostic, and everything domain-specific is a plugin. The architecture docs go deeper.

Contributing

Contributions are welcome, and the on-ramps are deliberately marked:

• good first issue — scoped, with context and an acceptance check
• help wanted — bigger pieces that need an owner
• Discussions — questions, ideas, and what you built

CONTRIBUTING.md covers the dev setup, the quality gates your PR has to pass, and the review turnaround you can expect. Every pull request runs 13,000+ tests behind a 85% branch-coverage floor, strict typing, architecture-boundary and docs-consistency gates. GOVERNANCE.md says how decisions get made and what needs a proposal before code; CODE_OF_CONDUCT.md applies to every space the project uses. Questions belong in SUPPORT.md's channels, vulnerabilities in SECURITY.md's; release history lives in CHANGELOG.md.

Licence

AGPL-3.0-only — see LICENSE. LICENSE.exception adds a permission under AGPL section 7: a plugin that uses the framework as a library — rather than patching files under baselith/core/ — may be licensed under any terms you choose, including closed ones, and section 13 never reaches it. Offered to everyone on identical terms; your plugin carries the notice described in section 3(c), and plugin packaging says what it must say.

NOTICE adds one term under AGPL section 7(b): attribution. Commercial use is welcome; every copy must keep the NOTICE file, and a product that shows legal notices (an About, Legal or Credits screen) must credit "Based on BaselithCore by The BaselithCore Authors".

Copyright © 2026 The BaselithCore Authors — see NOTICE.