Metadata-Version: 2.4
Name: europacore
Version: 0.4.0a13
Summary: Agent and harness core for building agent-based applications: a multi-turn tool-calling harness with guardrails, checkpoint/resume, human-in-the-loop, compaction and sub-agent delegation.
License-Expression: MIT
License-File: LICENSE
Author: Mark Moloney
Author-email: m4rkmo@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Provides-Extra: anthropic
Provides-Extra: artifacts
Provides-Extra: bedrock
Provides-Extra: bedrock-openai
Provides-Extra: browser
Provides-Extra: claude-code
Provides-Extra: costs
Provides-Extra: credentials
Provides-Extra: graph
Provides-Extra: images
Provides-Extra: mcp
Provides-Extra: monitor
Provides-Extra: notebooks
Provides-Extra: openai
Provides-Extra: openai-responses
Provides-Extra: otel
Provides-Extra: postgres
Provides-Extra: promptstore
Provides-Extra: s3
Provides-Extra: sandbox
Provides-Extra: server
Provides-Extra: telemetry
Provides-Extra: temporal
Requires-Dist: anthropic (>=2.3,<3) ; extra == "anthropic"
Requires-Dist: aws-bedrock-token-generator (>=1.1.0,<2.0.0) ; extra == "bedrock-openai"
Requires-Dist: boto3 (>=1.43.37,<2.0.0) ; extra == "bedrock"
Requires-Dist: boto3 (>=1.43.37,<2.0.0) ; extra == "s3"
Requires-Dist: boto3 (>=1.43.37,<2.0.0) ; extra == "sandbox"
Requires-Dist: botocore[crt] (>=1.43.37,<2.0.0) ; extra == "bedrock"
Requires-Dist: botocore[crt] (>=1.43.37,<2.0.0) ; extra == "bedrock-openai"
Requires-Dist: cel-python (>=0.5,<0.6) ; extra == "graph"
Requires-Dist: claude-agent-sdk (>=0.2.170,<0.3.0) ; extra == "claude-code"
Requires-Dist: cryptography (>=42.0.0,<51.0.0) ; extra == "credentials"
Requires-Dist: euporie (>=2.10,<3) ; extra == "notebooks"
Requires-Dist: fastapi (>=0.115,<1.0) ; extra == "server"
Requires-Dist: ipykernel (>=6.29,<8) ; extra == "notebooks"
Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
Requires-Dist: litellm (>=1.75.2,<2.0.0) ; extra == "costs"
Requires-Dist: markdown-it-py (>=3,<4) ; extra == "artifacts"
Requires-Dist: mcp (>=2,<3) ; extra == "mcp"
Requires-Dist: mdit-py-plugins (>=0.4,<0.5) ; extra == "artifacts"
Requires-Dist: openai (>=1.74.1,<3.0.0) ; extra == "openai"
Requires-Dist: opentelemetry-api (>=1.27,<2) ; extra == "otel"
Requires-Dist: pillow (>=10.0,<13) ; extra == "images"
Requires-Dist: playwright (>=1.60.0,<2.0.0) ; extra == "browser"
Requires-Dist: promptstore-telemetry (>=0.1.3,<0.2.0) ; extra == "telemetry"
Requires-Dist: promptstorepy (>=0.1.3,<0.2.0) ; extra == "promptstore"
Requires-Dist: psycopg[binary] (>=3.2.9,<4.0.0) ; extra == "postgres"
Requires-Dist: pybars3 (>=0.9.7,<0.10.0)
Requires-Dist: pydantic (>=2.10.6,<3.0.0)
Requires-Dist: pydantic-graph (>=2,<3) ; extra == "graph"
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: requests (>=2.32.4,<3.0.0) ; extra == "bedrock-openai"
Requires-Dist: requests (>=2.32.4,<3.0.0) ; extra == "openai-responses"
Requires-Dist: requests (>=2.32.4,<3.0.0) ; extra == "sandbox"
Requires-Dist: requests-sse (>=0.3.2,<0.4.0) ; extra == "bedrock-openai"
Requires-Dist: requests-sse (>=0.3.2,<0.4.0) ; extra == "openai-responses"
Requires-Dist: temporalio (>=1.14.1,<2.0.0) ; extra == "temporal"
Requires-Dist: tenacity (>=9.1.2,<10.0.0) ; extra == "bedrock"
Requires-Dist: tenacity (>=9.1.2,<10.0.0) ; extra == "bedrock-openai"
Requires-Dist: tenacity (>=9.1.2,<10.0.0) ; extra == "openai-responses"
Requires-Dist: tenacity (>=9.1.2,<10.0.0) ; extra == "sandbox"
Requires-Dist: tiktoken (>=0.9.0,<0.10.0)
Requires-Dist: typing-extensions (>=4.14.1,<5.0.0)
Requires-Dist: uvicorn (>=0.30,<1.0) ; extra == "server"
Requires-Dist: watchfiles (>=1.0,<2) ; extra == "monitor"
Description-Content-Type: text/markdown

# europacore

The agent and harness core for building agent-based applications. It includes:

- **`AgentHarness`**: a multi-turn, tool-calling loop with:
  - guardrails
  - checkpoint/resume and human-in-the-loop approval
  - streaming
  - provider-agnostic retry
  - context compaction
  - sub-agent delegation
  - opt-in failure-spend governance (`failure_spend_governance=True`): a fan-out cap, a circuit breaker for identically failing calls, and a failure budget that steers a failing run to answer early (`failure_arm_after_distinct_calls=2` arms it only once two different calls have failed, for tools that report ordinary misses as errors)
- **`SingleShotAgent`**: one prompt in, one schema-validated output, in a single forced LLM call.
- **`ToolAgent`**: the base class for the tools the harness dispatches.
- **Built-in tools** for planning, skills and delegation, each enabled by a flag. `enable_planning=True` registers `todo_write` and, by default, nudges the model to plan before substantial work; `planning_mode="auto"` keeps the tool and drops the nudge, so a one-line question costs no extra round-trip.
- **An LLM layer**: a Chat-Completions-shaped `LLM` contract with Amazon Bedrock (Claude), Anthropic API and OpenAI (Responses API) providers, plus a `(name, version)` prompt registry.
- **Optional durable state and runtimes**:
  - Postgres checkpointer and run journal
  - a Temporal-backed autonomous multi-agent runtime
  - sandbox providers (local subprocess, AWS Lambda MicroVMs)

Moving code from the library's predecessor? See [`docs/migration.md`](docs/migration.md).

## Install

Python 3.11+. The core has few dependencies; everything else is an extra, imported only when you use it:

```bash
pip install --pre europacore                              # core only (--pre: the 0.4 releases are alphas)
pip install --pre 'europacore[server,bedrock,postgres]'   # the server, Claude on Bedrock, Postgres state
europacore doctor --model claude-haiku-4-5                # what is installed and configured, and how to fix what is not
```

[docs/install.md](docs/install.md) lists every extra, what `europacore doctor` checks, and the providers' environment variables.

## Quickstart

### Try it

One command serves the showcase offline, with no credentials: an assistant that plans, calls tools and asks before it saves a note, the Europa Bistro's table-booking flow, a refunds agent whose tool is a flow with an approval gate, and the flow designer with both flows in it:

```bash
pip install --pre 'europacore[server,graph]'
europacore demo                          # --repo DIR adds a sample repository and a coding agent that fixes it
npx @markmo/europacore-cli               # the terminal client (Node 22); or open the chat link the demo printed
```

The chat page at the server's address is europacoreui's session UI (europacoreui is the full product app) around this server; the terminal client is [`ec`](https://www.npmjs.com/package/@markmo/europacore-cli). `europacore demo --model claude-haiku-4-5` runs the same agents live.

### A new project

`europacore init` makes an agent project that passes its tests and serves offline before any credentials are set:

```bash
europacore init my-agents            # --model claude-haiku-4-5 to start on a live model
cd my-agents && pip install -e '.[dev]'
pytest                               # a scripted model plays the turns
npx @markmo/europacore-cli --spawn my_agents.agents:registry   # serve it and chat with it in the terminal
```

It writes:
- an agent registry (`my_agents/agents.py`), built with the option groups;
- its tools, one of which waits for the user's approval;
- offline tests with an eval set (`evals/smoke.json`);
- `.env.example` and a `Dockerfile`;
- a `pyproject.toml` that depends on `europacore[server]`, plus the extra the model's provider needs.

The default model, `demo`, is an offline stand-in (`europacore.testing.DemoLLM`) that plans and calls the tools when asked to. Set `EUROPACORE_MODEL` to go live, and check it with `europacore doctor`.

### In code

An agent that runs offline on a core-only install ([`examples/minimal_agent.py`](examples/minimal_agent.py)):

```python runnable
from europacore.agents import AgentHarness, function_tool
from europacore.testing import ScriptedLLM, text, tool_call

@function_tool
def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

llm = ScriptedLLM([tool_call("add", {"a": 2, "b": 40}), text("2 + 40 = 42")])   # plays the model
agent = AgentHarness(llm, tools=[add], system_prompt="You are a careful calculator.")
print(agent(question="What is 2 + 40?").text)
```

To go live, pass a real model instead of `ScriptedLLM`: `create_model("claude-haiku-4-5")` (`europacore.llm`) runs Claude on Bedrock, `create_model("anthropic/claude-opus-5-5")` on the Anthropic API, and `create_model("gpt-6-luna")` on OpenAI.

### In a notebook

The same API, a step at a time: `europacore notebook` opens four notebooks (a first agent, durable state and approval, flows, evals) in [euporie](https://github.com/joouha/euporie), a Jupyter client that runs in the terminal. They run offline, and your edits are kept:

```bash
pip install --pre 'europacore[notebooks,graph]'
europacore notebook                  # or `europacore notebook 02` for one; --list lists them
```

## The guide

[docs/guide](docs/guide/README.md) goes from a first agent to agents that run unattended:

1. [Building an agent](docs/guide/01-agent.md): tools, structured answers, option groups, models, hooks, prompt templates, results and stop hints, security defaults
2. [Durable state](docs/guide/02-durable.md): checkpoints and the run journal, approvals, recovery, steering, inspecting runs, memory, tracing
3. [The server](docs/guide/03-server.md): HTTP and SSE, editors over ACP, tool credentials
4. [Flows](docs/guide/04-flows.md): FlowScript, pauses, flows as tools, the designer
5. [Coding agents](docs/guide/05-coding.md): sandboxes, the coding agent and its monitors (a command or file watch whose output wakes the session), fleets, design checks, the autonomous runtime
6. [Testing and evals](docs/guide/06-evals.md): scripted models, cassettes, eval sets, `europacore eval`, pytest fixtures

[europacore in pictures](docs/showcase.md) tours it all with screenshots: the coding agent, the `ec` terminal client, the web session UI, the flow designer and fleets.

## What is in it

| Package | What | Read |
|---|---|---|
| `europacore.agents` | `AgentHarness`, tools, guardrails, checkpointers and the run journal | [guide 1](docs/guide/01-agent.md), [2](docs/guide/02-durable.md) |
| `europacore.llm` | the model contract, providers, `create_model`, `FallbackLLM` | [guide 1](docs/guide/01-agent.md#models-by-name-and-failover) |
| `europacore.routing` | a tier of model per turn (fast, standard, capable), judged by Jev, within the task's budget | [guide 1](docs/guide/01-agent.md#routing-between-models), [model-routing.md](docs/model-routing.md) |
| `europacore.server` | `europacore serve`: sessions, runs and resumable streams over HTTP | [guide 3](docs/guide/03-server.md), [server-api.md](docs/server-api.md) |
| `europacore.credentials` | tools that act with a person's own account (OAuth, API keys) | [guide 3](docs/guide/03-server.md#tool-credentials-europacorecredentials), [tool-oauth.md](docs/tool-oauth.md) |
| `europacore.memory` | long-term memory across sessions: org, user and project scopes | [guide 2](docs/guide/02-durable.md#long-term-memory-europacorememory), [memory.md](docs/memory.md) |
| `europacore.artifacts` | pages the agent makes for a person to open, keep and share, versioned, served and published | [artifacts.md](docs/artifacts.md) |
| `europacore.graph` | FlowScript flows and the designer | [guide 4](docs/guide/04-flows.md), [flowscript.md](docs/flowscript.md) |
| `europacore.coding` | the coding agent | [guide 5](docs/guide/05-coding.md) |
| `europacore.sandbox` | local, OS-sandboxed and MicroVM sandboxes | [guide 5](docs/guide/05-coding.md#sandboxes-europacoresandbox) |
| `europacore.peers` | coding sessions in one repository told about each other: file claims, requests answered path by path | [peers.md](docs/peers.md) |
| `europacore.fleet` | scored parallel coding tasks over one repository | [fleet.md](docs/fleet.md) |
| `europacore.cloud` | moving sessions and fleet runs to another server and back | [cloud.md](docs/cloud.md) |
| `europacore.design` | design checks that keep a change from making a repository worse | [design.md](docs/design.md) |
| `europacore.autonomous` | a persisted multi-agent run graph, in process or on Temporal | [guide 5](docs/guide/05-coding.md#autonomous-runtime-europacoreautonomous) |
| `europacore.evaluation`, `europacore.testing` | eval sets, scripted models, cassettes | [guide 6](docs/guide/06-evals.md) |
| `europacore.claude_code` | Claude Code sessions served next to europacore's own agents | [claude-code.md](docs/claude-code.md) |

The [examples](examples) run offline: [`minimal_agent.py`](examples/minimal_agent.py), [`delegation_agent.py`](examples/delegation_agent.py), [`mcp_agent.py`](examples/mcp_agent.py), [`memory_agent.py`](examples/memory_agent.py), [`artifact_agent.py`](examples/artifact_agent.py), [`monitor_agent.py`](examples/monitor_agent.py), [`browser_agent.py`](examples/browser_agent.py) (on a real browser), [`credentialed_tool.py`](examples/credentialed_tool.py), [`eval_in_ci`](examples/eval_in_ci), the server registries, flows and the coding agent. [`kubernetes`](examples/kubernetes) deploys the server as two replicas on Postgres.

## Reference

- [api.md](docs/api.md): every public name with its signature; anything not listed there is internal. [deprecations.md](docs/deprecations.md) says what a release may change.
- [constructor.md](docs/constructor.md): every `AgentHarness` argument, its default and its group.
- [events.md](docs/events.md): every event a run emits.
- [settings.md](docs/settings.md): every `EUROPACORE_*` variable; `europacore config` shows their values.
- [server-api.md](docs/server-api.md) and [server-settings.md](docs/server-settings.md): the HTTP protocol, and running a server.
- [threat-model.md](docs/threat-model.md): each trust boundary, its control and its test.
- [llms.txt](llms.txt): this documentation's map, for coding agents.

## Development

```bash
poetry install --all-extras
make check     # the suite, mypy, ruff and the design checks against main
```

[docs/development.md](docs/development.md) has the other commands, and how to request the full CI gates.

