Metadata-Version: 2.4
Name: overmind
Version: 0.1.58
Summary: Overmind — autonomous agent optimisation through structured experimentation
Project-URL: Homepage, https://github.com/overmind-core/overmind
Project-URL: Repository, https://github.com/overmind-core/overmind
Author: Overmind Ltd
Keywords: ai,api,client,enforcement,overmind,policy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <4,>=3.10
Requires-Dist: litellm>=1.90.2
Requires-Dist: opentelemetry-api>=1.35.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.35.0
Requires-Dist: opentelemetry-instrumentation-agno>=0.53.0
Requires-Dist: opentelemetry-instrumentation-anthropic>=0.53.0
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.60b1
Requires-Dist: opentelemetry-instrumentation-google-generativeai>=0.53.0
Requires-Dist: opentelemetry-instrumentation-openai>=0.53.1
Requires-Dist: opentelemetry-instrumentation>=0.60b1
Requires-Dist: opentelemetry-overmind>=0.53.0
Requires-Dist: opentelemetry-sdk>=1.35.0
Requires-Dist: opentelemetry-semantic-conventions-ai>=0.4.13
Requires-Dist: opentelemetry-semantic-conventions>=0.60b1
Requires-Dist: psutil>=5.9.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.25.0
Provides-Extra: test
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.5; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

<img width="3000" height="1000" alt="X Company Banner Black" src="https://github.com/user-attachments/assets/4a5caceb-49e8-4b8e-a6aa-511222a94381" />

# Overmind

Overmind is two things in one package:

- **Tracing SDK** — drop-in observability for LLM agents. Decorate your code, get structured traces of every LLM call and tool invocation.
- **Optimiser client** — a thin, agent- and codebase-agnostic executioner. The optimisation loop (experiments → iterations → candidates → commands) is configured and driven **server-side** by the [Overmind Console](https://console.overmindlab.ai/). This repo just registers your machine, leases queued commands, runs them against your repo, and reports results back.

**Documentation:** [Overmind guide](https://docs.overmindlab.ai/guides/overmind_optimizer/)

**Console:** [console.overmindlab.ai](https://console.overmindlab.ai/)

## Install

```bash
uv tool install overmind
# or
pipx install overmind
```

## Tracing

Wire up tracing once at process start, then annotate the functions you want traced:

```python
import overmind

overmind.init(service_name="my-agent", providers=["openai", "anthropic"])  # reads OVERMIND_API_KEY from the environment

@overmind.entry_point()
def run(input_data: dict) -> dict:
    return {"response": handle(input_data)}

@overmind.tool()
def search(query: str) -> list[dict]:
    ...
```

Available decorators/helpers: `entry_point`, `workflow`, `tool`, `function`, plus `start_span` (context manager), `set_tag`, `set_user`, and `capture_exception` for Sentry-style annotations on the current span.

## Optimise

Set up and configure the experiment (agent, policy, dataset, iterations) in the [Console](https://console.overmindlab.ai/). Then, from the root of the repo you want optimised:

```bash
export OVERMIND_API_KEY=<your-api-key>
overmind optimise
```

This registers the current machine with the backend and loops forever: it leases queued commands from the experiment you configured in the Console, checks out the iteration's git branch (applying its candidate diff as a commit), runs the shell command against your repo, and reports the result back. Stop it any time with Ctrl-C; re-running is safe and idempotent per iteration branch.

### Options / environment variables

| Flag                    | Env var                        | Default                          | Description                                        |
| ----------------------- | ------------------------------- | --------------------------------- | --------------------------------------------------- |
| `--api-key`              | `OVERMIND_API_KEY`               | *(required)*                      | Sent as `X-Api-Key`.                                 |
| `--api-url`              | `OVERMIND_API_URL`               | `https://api.overmindlab.ai`      | Backend base URL.                                    |
| `--cwd`                  | `OVERMIND_CWD`                   | current directory                 | Repo root to run commands in.                        |
| `--poll-interval`        | `OPTIMIZER_POLL_INTERVAL`        | `5`                                | Idle poll seconds.                                   |
| `--heartbeat-interval`   | `OPTIMIZER_HEARTBEAT_INTERVAL`   | `60`                               | Idle "still alive" log interval, seconds.            |
| `--log-level`            | `OPTIMIZER_LOG_LEVEL`            | `INFO`                             | `DEBUG`/`INFO`/`WARNING`/`ERROR`.                    |

> [!WARNING]
> The Console can hand this client arbitrary shell to run (`shell=True`, guarded only by a per-command timeout). Only point it at a backend you trust.

## Skills

Use these from Cursor, Codex, or Claude Code to scaffold agents and configure telemetry without leaving your coding environment. Skills live at the repo-root [`skills/`](./skills/) directory so agent installers can pick them up from this repository (e.g. `npx skills add overmind-core/overmind`).

```bash
overmind skills list --verbose
overmind skills sync "Overmind Telemetry"   # or: overmind-agent-telemetry
```

| Skill                  | What it does                                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `Overmind Telemetry`   | Add tracing, verify traces via the REST API, and look up current Overmind docs (`overmind-agent-telemetry`).       |

## CLI reference

```text
overmind optimise [OPTIONS]         Register this machine and run the optimisation loop
overmind skills list [--verbose]    List installed/available skills
overmind skills sync <name>...      Sync one or more skills to the latest version
```

Run `overmind <command> --help` for full flag documentation.
