Metadata-Version: 2.4
Name: primer-ai
Version: 0.6.0
Summary: Microagents framework
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.14.1
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: anthropic>=0.109.1
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: asyncpg>=0.31.0
Requires-Dist: croniter>=6.2.2
Requires-Dist: ddgs>=9.14.4
Requires-Dist: fastapi>=0.136.3
Requires-Dist: google-genai>=2.8.0
Requires-Dist: grpcio>=1.81.1
Requires-Dist: httpx>=0.28
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: mcp>=1.27.2
Requires-Dist: mini-racer>=0.14.1
Requires-Dist: ollama>=0.6.2
Requires-Dist: openai>=2.41.1
Requires-Dist: opentelemetry-api>=1.42.1
Requires-Dist: opentelemetry-exporter-otlp>=1.42.1
Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.63b1
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.63b1
Requires-Dist: opentelemetry-instrumentation-httpx>=0.63b1
Requires-Dist: opentelemetry-instrumentation-logging>=0.63b1
Requires-Dist: opentelemetry-sdk>=1.42.1
Requires-Dist: pgvector>=0.4.2
Requires-Dist: prometheus-client>=0.25.0
Requires-Dist: pydantic-settings>=2.14.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyjwt[crypto]<3,>=2.13
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: regopy>=1.4.0
Requires-Dist: tiktoken>=0.13.0
Requires-Dist: trafilatura>=2.1.0
Requires-Dist: transformers>=5.8.1
Requires-Dist: typer>=0.21.2
Requires-Dist: tzdata>=2026.2
Requires-Dist: uvicorn[standard]>=0.49.0
Provides-Extra: channels
Requires-Dist: discord-py>=2.7.1; extra == 'channels'
Requires-Dist: python-telegram-bot>=22.8; extra == 'channels'
Requires-Dist: slack-bolt>=1.28.0; extra == 'channels'
Requires-Dist: slack-sdk>=3.42.0; extra == 'channels'
Provides-Extra: docker
Requires-Dist: aiodocker>=0.27.0; extra == 'docker'
Provides-Extra: docling
Requires-Dist: docling>=2.102.1; extra == 'docling'
Provides-Extra: full
Requires-Dist: aiodocker>=0.27.0; extra == 'full'
Requires-Dist: discord-py>=2.7.1; extra == 'full'
Requires-Dist: docling>=2.102.1; extra == 'full'
Requires-Dist: kubernetes-asyncio>=36.1.0; extra == 'full'
Requires-Dist: lancedb>=0.33.0; extra == 'full'
Requires-Dist: python-telegram-bot>=22.8; extra == 'full'
Requires-Dist: sentence-transformers>=5.5.1; extra == 'full'
Requires-Dist: slack-bolt>=1.28.0; extra == 'full'
Requires-Dist: slack-sdk>=3.42.0; extra == 'full'
Provides-Extra: huggingface
Requires-Dist: sentence-transformers>=5.5.1; extra == 'huggingface'
Provides-Extra: kubernetes
Requires-Dist: kubernetes-asyncio>=36.1.0; extra == 'kubernetes'
Provides-Extra: lance
Requires-Dist: lancedb>=0.33.0; extra == 'lance'
Description-Content-Type: text/markdown

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/primerhq/primer/main/docs/assets/hero-dark.png">
  <img alt="Primer - orchestrate fleets of small, context-optimized agents" src="https://raw.githubusercontent.com/primerhq/primer/main/docs/assets/hero-light.png" width="760">
</picture>

<br>

**A self-hosted, open-source platform for orchestrating fleets of small, context-optimized AI agents - built on one bet: a small, local open-weight model, given a clean and purpose-built context, can do genuinely useful work. Runs on hardware you already own.**

<br>

[![License](https://img.shields.io/badge/license-Apache_2.0-61d46a.svg)](https://github.com/primerhq/primer/blob/main/LICENSE)
[![Release](https://img.shields.io/github/actions/workflow/status/primerhq/primer/release.yml?branch=main&label=release)](https://github.com/primerhq/primer/actions/workflows/release.yml)
[![Python](https://img.shields.io/badge/python-3.12+-3776ab.svg)](https://www.python.org/)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-61d46a.svg)](https://github.com/primerhq/primer/blob/main/CONTRIBUTING.md)
[![Stars](https://img.shields.io/github/stars/primerhq/primer?style=flat&color=61d46a)](https://github.com/primerhq/primer/stargazers)

[Quickstart](#quickstart) · [What makes it different](#what-makes-primer-different) · [Loop engineering](#built-for-loop-engineering) · [How it works](#how-it-works) · [Docs](#documentation) · [Contributing](https://github.com/primerhq/primer/blob/main/CONTRIBUTING.md)

</div>

---

## Why Primer

A language model spreads a fixed budget of attention across every token in its context. Keep that context tight and the few tokens that matter get most of the attention; bloat it with stale history, unused tool definitions, and irrelevant background, and the signal thins out. Primer's bet is simple: **give a small, local model exactly what it needs - and nothing more - and it can do genuinely useful work.** Not replace a frontier model; just real work, on hardware you already own. It is a bet, not a benchmark, and it is still early - the best way to test it is to run it on your own workload and tell us where it falls apart.

So instead of one giant agent with everything crammed into its prompt, Primer lets you orchestrate **fleets of small, focused agents**, each with a clean working context, wired together with the primitives a real deployment needs: LLM providers, workspaces, agent graphs, knowledge collections, channels, triggers, and semantic search - self-hosted and integrated from the start.

## What makes Primer different

A lot of what Primer ships - knowledge bases, channels, triggers, approvals - you will find in other agent frameworks too. These are the parts that were missing everywhere else, and they are what Primer is really about.

<table>
  <tr>
    <td width="33%" valign="top">

🔁 **Directed cyclic agent graphs**

Wire small agents into a feedback loop with an evaluator at the end that grades the output and feeds it back - produce, critique, revise, until the loop **converges on a target** instead of hoping a one-shot prompt lands.

</td>
    <td width="33%" valign="top">

📁 **Shared workspaces**

Multiple agents and graphs run in one sandbox, reading and writing the same filesystem - a fleet collaborates by handing off files: one writes, another picks it up.

</td>
    <td width="33%" valign="top">

⏸️ **Yielding tools**

An agent parks and **yields control** until an event fires - a file change, schedule, webhook, or human reply - so loops run in the background. One agent can wake the instant another writes a file.

</td>
  </tr>
  <tr>
    <td width="33%" valign="top">

🔎 **Semantic tool search**

Every tool, agent, and graph is a vector embedding. Each agent carries just two meta-tools - **search** and **call** - and reaches all of them without bloating its context.

</td>
    <td width="33%" valign="top">

🧩 **First-class dogfooding**

The platform's own capabilities are internal tools, so you can build **agents that build other agents**, graphs, and collections - on Primer itself.

</td>
    <td width="33%" valign="top">

🔌 **MCP over everything**

Every capability is exposed over the **Model Context Protocol**. Drive Primer from Claude, opencode, or any MCP client - **operate it by asking an agent**, not by clicking a UI.

</td>
  </tr>
</table>

## Batteries included

Everything else a real deployment needs, integrated from day one and self-hostable:

- **Knowledge collections** - ingest documents into vector collections; agents retrieve only the relevant chunks (semantic search / RAG).
- **Channels** - bridge agents to **Slack, Telegram, and Discord**: ask questions, request approvals, and kick off work from a message.
- **Triggers** - start a fresh session or graph run, or resume a parked one, on a **cron schedule, a delay, or a webhook**.
- **Human approvals** - gate sensitive tool calls behind a person's approval from a channel or the console before the agent proceeds.
- **Web search** - first-class web search built in.
- **MCP-server toolsets** - connect external MCP servers and expose their tools to your agents.
- **Harnesses** - package a tuned set of agents, graphs, and collections into a versioned, git-backed bundle you can share and deploy anywhere.

<!-- DEMO GIF: drop the ask_user -> channel reply -> resume capture here once recorded, e.g.
<div align="center"><img alt="Park on a question, reply from a channel, resume" src="docs/assets/demo-park-resume.gif" width="760"></div>
-->

<!-- SCREENSHOTS: add a framed-console section here (Dashboard / Session control room / Approvals / Graph editor) once the captures are produced. -->

## Built for loop engineering

Loop engineering is the shift from prompting an agent turn-by-turn to **designing the system that prompts it** - a loop that wakes on a schedule, works toward a stated goal, checks its own output against evidence, and escalates to a human only when it should. The leverage moves from writing a good prompt to designing a good loop.

A loop needs a specific set of primitives. Primer ships all of them, integrated and self-hostable:

| A loop needs... | Primer gives you |
|---|---|
| **A heartbeat** - work surfaced on a cadence, not by hand | **Triggers** that start a fresh session or graph run (or resume a parked one) on a cron schedule, a delay, or a webhook |
| **Isolation** - parallel agents that don't collide | **Workspaces** - a per-agent local, container, or Kubernetes sandbox with its own persistent, git-backed filesystem |
| **Durable memory** - the agent forgets, the repo doesn't | Git-backed workspace **state** plus **knowledge collections** agents retrieve from, so knowledge compounds across runs instead of resetting to zero |
| **A maker and a checker** - keep the writer away from the grader | **Directed cyclic graphs** with producer-judge loops, fan-out/fan-in, and runtime agent/graph invocation |
| **Connectors** - reach real tools and real people | A built-in **MCP server** (and MCP client), plus **Slack / Telegram / Discord** channels |
| **A human gate** - approve the risky, let the safe run | **Approval gates** and **park-and-resume**: an agent waits on a person for hours without holding compute, then continues when the reply lands |

Primer does not press "go" on the loop for you - it gives you the orchestration substrate to build one and to keep a human in it where that matters. And the same context discipline that makes a single agent accurate is what lets a loop run for a long time without drifting: each iteration gets a clean, purpose-built context instead of an ever-growing transcript.

## Quickstart

Pick whichever install fits. All three start the same server zero-config on an embedded SQLite database - perfect for a first look.

**pipx** (isolated CLI install; needs Python 3.12+):

```bash
pipx install 'primer-ai[full]'                   # batteries-included
primer api                                       # API + in-process worker
```

The bare `pipx install primer-ai` installs a lean core (REST API, console, MCP, SQLite/Postgres storage, and the API-based LLM/embedder providers). The `[full]` extra adds the optional backends - local HuggingFace embeddings, Docling ingestion, LanceDB, Slack/Telegram/Discord channels, and the container/Kubernetes workspace backends - which pull a larger ML stack. You can also pick à la carte: `primer-ai[huggingface]`, `[docling]`, `[lance]`, `[channels]`, `[docker]`, `[kubernetes]`.

**Docker** (no Python toolchain required):

```bash
docker run --rm -p 8000:8000 ghcr.io/primerhq/primer:latest
```

**From source** (for contributors):

```bash
git clone https://github.com/primerhq/primer.git
cd primer
uv sync --all-extras
uv run primer api
```

Then verify and open the console:

```bash
curl http://localhost:8000/v1/health             # -> {"status":"ok"}
```

The operator console is at **http://localhost:8000/console/**.

### Going to Postgres (multi-process, semantic search, production)

Zero-config SQLite is single-process and ships without a vector store. For multiple workers, semantic search, or production, point Primer at Postgres:

```bash
docker compose up -d postgres                    # or: podman compose up -d postgres
cp config.example.yaml config.yaml               # set db.config.password to match
uv run primer api --config config.yaml
```

`config.example.yaml` documents every field. Environment variables override file values: every `AppConfig` field maps to `PRIMER_<FIELD>` (nested fields use `__`, e.g. `PRIMER_DB__CONFIG__PASSWORD`). The Docker image reads the same variables - set `PRIMER_DB_HOST` (and friends) and it renders a Postgres + pgvector config automatically; otherwise it runs the embedded-SQLite path above. For a SQLite database that survives container restarts, mount a volume at `/app/data`.

## How it works

Primer is a stack of layers, where each layer keeps the one below it from getting cluttered:

- **Context discipline** - tool selection, meta-tools, and internal collections keep each agent's prompt lean.
- **State** - workspaces give agents a shared, minimal surface to hand off results without carrying history in-context.
- **Sequencing** - directed cyclic graphs express multi-step reasoning as structure instead of one giant prompt.
- **Time** - event-driven park-and-resume frees compute while work waits on a slow tool or a human.
- **Sharing** - harnesses package a working configuration into a versioned, git-backed bundle.
- **Edges** - channels, web search, and approval gates handle where agents reach outside the platform.

At runtime, requests arrive from many edges (REST/console, MCP clients, chat channels, triggers), become **sessions / chats / graph runs** that a worker pool claims and drives; each turn calls LLM providers, tools, workspaces, and collections, and can park on a human or event and resume later - all backed by Postgres.

## Documentation

- **Operator docs** - served at `/docs` when the server is running.
- **Agent-usage docs** - [`docs/agents/`](https://github.com/primerhq/primer/tree/main/docs/agents) - how to drive a running Primer instance from an AI agent over MCP.
- **Developer docs** - [`docs/dev/`](https://github.com/primerhq/primer/tree/main/docs/dev) - architecture patterns and subsystem references. Start at [`docs/dev/README.md`](https://github.com/primerhq/primer/blob/main/docs/dev/README.md).

## Contributing

Read [AGENTS.md](https://github.com/primerhq/primer/blob/main/AGENTS.md) first - it is the authoritative contributor contract (project layout, the Definition of Done, how to run the suites, and the hard rules). [CONTRIBUTING.md](https://github.com/primerhq/primer/blob/main/CONTRIBUTING.md) is the human-facing summary.

```bash
uv sync --all-extras
docker compose up -d postgres
# narrowed unit sweep (excludes e2e/distributed/ui_e2e):
uv run pytest tests/ -q --ignore=tests/distributed --ignore=tests/ui_e2e \
  --ignore=tests/e2e --ignore=tests/integration --ignore=tests/llm
```

See [`CODE_OF_CONDUCT.md`](https://github.com/primerhq/primer/blob/main/CODE_OF_CONDUCT.md) for community expectations.

## Security

Please report vulnerabilities privately - see [SECURITY.md](https://github.com/primerhq/primer/blob/main/SECURITY.md).

## License

Primer is licensed under the Apache License 2.0. See [LICENSE](https://github.com/primerhq/primer/blob/main/LICENSE) for the full text.
