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.

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

from core.agent 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),
])
report = (await crew.run(inputs={"topic": "vector databases"})).final

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

Or the whole runtime — API, PostgreSQL, FalkorDB and Qdrant, 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 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: 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 8,924 tests behind a 78% branch-coverage floor, strict typing, architecture-boundary and docs-consistency gates. Report vulnerabilities through SECURITY.md; 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 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.

Copyright © 2026 BaselithCore Team.