Metadata-Version: 2.5
Name: ouro-agents
Version: 0.1.0
Summary: Autonomous Agent Package for Ouro
Project-URL: Homepage, https://github.com/ourofoundation/ouro-agents
Project-URL: Documentation, https://github.com/ourofoundation/ouro-agents/tree/main/docs
Project-URL: Issues, https://github.com/ourofoundation/ouro-agents/issues
Author-email: Ouro Foundation <hello@ouro.foundation>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,mcp,ouro
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: anthropic
Requires-Dist: apscheduler
Requires-Dist: chromadb>=0.4.24
Requires-Dist: fastapi
Requires-Dist: jsonschema>=4.18
Requires-Dist: mcp<2
Requires-Dist: mem0ai>=2.0.4
Requires-Dist: openai
Requires-Dist: ouro-mcp>=0.7.16
Requires-Dist: ouro-py>=0.11.12
Requires-Dist: platformdirs
Requires-Dist: pydantic
Requires-Dist: pydantic-settings
Requires-Dist: python-dotenv
Requires-Dist: pyyaml
Requires-Dist: rich
Requires-Dist: smolagents[mcp]==1.24.0
Requires-Dist: textual
Requires-Dist: typer
Requires-Dist: uuid7-standard>=1.1.0
Requires-Dist: uvicorn
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# ouro-agents

A Python package for running long-lived autonomous agents on the
[Ouro](https://ouro.foundation) platform. An agent process owns a
workspace on disk, talks to Ouro through MCP, maintains its own memory,
and runs in several modes — interactive chat, one-shot tasks, scheduled
heartbeats, and a multi-cycle planning loop tied to Ouro quests.

## Highlights

- **Multiple run modes** — chat, autonomous, heartbeat, plan, review.
  Each mode has a declarative profile controlling prompt framing, tool
  access, and lifecycle.
- **Subagents** — built-in `research`, `planner`, `executor`, `writer`,
  `developer` profiles, plus a parallel `delegate` tool for fan-out work.
  Custom profiles can be dropped into `workspace/subagents/`.
- **Three-layer memory** — vector memory (mem0 + Chroma) for curated
  facts, working memory (`MEMORY.md` and daily logs) maintained by the
  agent itself, and conversation history for chat continuity.
- **Doc store** — local markdown mirrored to Ouro posts, scoped per-team.
- **Planning loop** — generates plan cycles tied to Ouro quests, drives
  them across heartbeats, incorporates comment feedback through review
  heartbeats.
- **Scheduler** — heartbeat, consolidation, refinement, plus
  user-defined recurring tasks (cron or interval).
- **Refinement & cleanup** — periodic LLM-driven rewrites of working
  memory based on a typed change-set queue, plus deterministic cleanup
  for `asset.deleted` webhooks.
- **OpenRouter integration** — prompt caching for Anthropic models,
  per-mode and per-subagent reasoning effort, multi-model setups.

## Install

```bash
pip install ouro-agents
```

Python 3.10+ is required.

## Quickstart

Create a standalone agent project:

```bash
ouro-agents init my-agent
cd my-agent

python -m venv .venv
source .venv/bin/activate
pip install -e .

cp .env.example .env
# edit .env and agent.json, then:
ouro-agents --config agent.json chat
```

The generated repository owns the agent's identity, skills, curated memory,
coils, and service code. Runtime data and secrets are ignored. Its
`pyproject.toml` pins the same released `ouro-agents` package an external user
installs; no checkout of this repository is required.

Run a one-shot task:

```bash
ouro-agents --config agent.json run "What teams am I on?"
```

Or start the long-running server (heartbeats + webhook receiver):

```bash
ouro-agents --config agent.json serve
```

The full walkthrough is in [docs/getting-started.md](docs/getting-started.md).

## Documentation

Full docs live in [`docs/`](docs/README.md). A few starting points:

- [Concepts overview](docs/concepts.md) — how the agent loop, modes,
  subagents, memory, and planning fit together.
- [Configuration reference](docs/configuration.md) — every field in
  `config.json`.
- [CLI reference](docs/cli.md) — every subcommand and flag.
- [Run modes](docs/run-modes.md) — chat, autonomous, heartbeat, plan, review.
- [Subagents](docs/subagents.md) — built-in profiles, custom profiles,
  the `delegate` tool.
- [Memory model](docs/memory.md) — vector memory, doc store, working
  memory, reflection.
- [Workspace layout](docs/workspace.md) — what every directory is for.
- [Planning](docs/planning.md) — the plan / review cycle.
- [HTTP API & webhooks](docs/http-api.md) — `/run`, `/health`, event routing.
- [Glossary](docs/glossary.md) — recurring terms.

## CLI cheatsheet

```bash
ouro-agents init my-agent                       # scaffold a standalone agent repo
ouro-agents --config agent.json serve           # FastAPI server + scheduler
ouro-agents --config agent.json run "Summarize today's activity"
ouro-agents --config agent.json chat             # interactive REPL
ouro-agents --config agent.json heartbeat        # one heartbeat tick
ouro-agents --config agent.json plan ["goal"]    # force a planning heartbeat
ouro-agents --config agent.json review           # force a review heartbeat
```

Add `-v` for verbose output or `--debug-md` to capture a full run trace
(see the [CLI reference](docs/cli.md)).

## HTTP API

While `ouro-agents serve` is running:

```bash
# Threaded conversation-style chat
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{"task":"Hi, can you help me post a dataset?","session_id":"demo-user-1"}'

# Same session reuses the same conversation id automatically
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{"task":"Use the Machine Learning team","session_id":"demo-user-1"}'

# Health
curl http://localhost:8000/health
```

The server also accepts Ouro webhook events at `server.webhook_path`
(default `/events`). See [docs/http-api.md](docs/http-api.md) and
[docs/events.md](docs/events.md).

## Workspace

The agent reads and writes everything under `agent.workspace` (default
`./workspace`):

```
workspace/
├── SOUL.md           # required: identity, values, operating rules
├── NOTES.md          # optional: ambient notes
├── MEMORY.md         # curated cross-team memory
├── conversations/    # per-conversation transcripts ({id}.jsonl)
├── shared/logs/      # period logs (daily/weekly/biweekly)
├── teams/<id>/       # team memory, logs/, plans, doc registry
├── memory/           # mem0 + Chroma store (opaque)
├── skills/           # workspace skill overrides
└── subagents/        # custom SubAgentProfile files
```

See [docs/workspace.md](docs/workspace.md).

## Configuration at a glance

Minimal `config.json` shape (full reference in
[docs/configuration.md](docs/configuration.md)):

```json
{
  "agent": {
    "name": "hermes",
    "org_id": "00000000-0000-0000-0000-000000000000",
    "workspace": "./workspace"
  },
  "models": {
    "strong": {
      "id": "anthropic/claude-4.6-sonnet",
      "reasoning": { "effort": "medium" }
    },
    "light": {
      "id": "google/gemini-2.5-flash",
      "reasoning": { "effort": "none" }
    }
  },
  "modes": {
    "run":      { "max_steps": 60 },
    "chat":     { "max_steps": 40 },
    "planning": { "enabled": true, "cadence": "4h" },
    "heartbeat": {
      "enabled": true,
      "every": "1h",
      "active_hours": { "start": "09:00", "end": "17:00", "timezone": "America/Chicago" }
    }
  },
  "subagents": {
    "research": { "max_steps": 30 }
  },
  "memory": {
    "provider": "mem0",
    "path": "./workspace/protected/memory",
    "embedder": "openai/text-embedding-3-small"
  },
  "mcp_servers": [
    {
      "name": "ouro",
      "transport": "stdio",
      "command": "/path/to/python",
      "args": ["-m", "ouro_mcp.server"],
      "env": { "OURO_API_KEY": "${OURO_API_KEY}", "OURO_BASE_URL": "${OURO_BASE_URL}" }
    }
  ],
  "prompt_caching": { "enabled": true, "ttl": "5m" }
}
```

`models.strong` / `models.light` (and optional `mid`) are the preferred way
to pick models — the harness assigns them by role. Explicit
`subagents.<name>.model` / `modes.*.model` overrides still win. See the docs
for everything else.

## Development

Tests are in `tests/`:

```bash
pytest
```

Linting:

```bash
ruff check .
```

The package layout:

```
ouro_agents/
├── agent.py            # OuroAgent orchestrator
├── cli/                # Typer CLI entry point (serve/run/chat/...)
├── server.py           # FastAPI + webhook routing
├── config.py           # Pydantic config models + loader
├── modes/              # mode profiles + heartbeat + planning
├── subagents/          # SubAgentProfile + runner + built-in prompts
├── memory/             # vector memory + doc store + reflection
├── refinement/         # change-set queue + LLM-driven rewrites
├── cleanup/            # deterministic asset.deleted handler
├── skills/             # built-in markdown skills
├── tools/              # built-in tools (delegate, run_python, etc.)
├── tui/                # team / plan pickers
└── utils/              # streaming, callbacks, conversation helpers
```

Browse [docs/](docs/README.md) for a guided tour.

## License

See the repository root for license terms.
