ouro-ai 0.4.1

General AI Agent System

An open-source AI agent — run it as a Coding agent CLI or deploy it as a bot just like JARVIS.

Ouro is derived from Ouroboros—the ancient symbol of a serpent consuming its own tail to form a perfect circle. It represents the ultimate cycle: a closed loop of self-consumption, constant renewal, and infinite iteration.

At Ouro AI Lab, this is our blueprint. We are building the next generation of AI agents capable of autonomous evolution—systems that learn from their own outputs, refine their own logic, and achieve a state of infinite self-improvement.

Two Modes, One Agent

Ouro ships with a unified agent core and two deployment modes:

	CLI Mode	Bot Mode
What	Interactive REPL + one-shot task execution	Persistent IM assistant (Lark, Slack)
Install	uv tool install ouro-ai	uv tool install 'ouro-ai[bot]'
Run	ouro-cli	ouro-bot
Guide	CLI Guide	Bot Guide

Quick Start

Prerequisites: Python 3.12+ and one of uv (recommended) or pipx.

# Recommended: installs ouro in an isolated environment and exposes global
# `ouro-cli` and `ouro-bot` commands
uv tool install ouro-ai

# Alternative
pipx install ouro-ai

# Upgrading later
uv tool upgrade ouro-ai      # or: pipx upgrade ouro-ai

Plain pip install ouro-ai also works but is not recommended — it mixes ouro's dependencies into your active Python environment. Use uv tool / pipx so the ouro-cli / ouro-bot binaries are on $PATH without needing to activate a venv.

On first run, ~/.ouro/models.yaml is created. Add your API key:

models:
  openai/gpt-4o:
    api_key: sk-...
default: openai/gpt-4o
current: openai/gpt-4o

Then run:

# Interactive mode
ouro-cli

# Single task
ouro-cli --task "Calculate 123 * 456"

# Bot mode (requires ouro-ai[bot])
ouro-bot

See LiteLLM Providers for the full provider list.

Features

• Dual mode: Interactive CLI with rich TUI + persistent IM bot (Lark, Slack) — same agent core, two deployment modes
• Unified agent loop: Think-Act-Observe cycle — planning, sub-agents, and tool use all happen in one loop
• Self-verification: Ralph Loop verifies the agent's answer against the original task and re-enters if incomplete (--verify)
• Parallel execution: Concurrent readonly tool calls in a single turn, plus multi_task for spawning parallel sub-agents with dependency ordering
• Memory system: LLM-driven compression, long-term memory, and YAML session persistence resumable across restarts
• Proactive mechanisms: Heartbeat self-checks + cron-scheduled tasks, with results broadcast to active IM sessions
• Personality: Customizable soul file (~/.ouro/bot/soul.md) defines bot identity and tone
• Skills: Extensible skill registry — dynamically loaded per session
• OAuth login: --login / /login to authenticate with ChatGPT Codex subscription models
• Benchmarks: First-class Harbor integration for agent evaluation (see Evaluation)

Evaluation

Ouro can be evaluated on agent benchmarks using Harbor. A convenience script harbor-run.sh is provided at the repo root:

1. Edit harbor-run.sh to set your model, dataset, and ouro version.
2. Run:

export OURO_API_KEY=<your-api-key>
./harbor-run.sh                    # run with defaults in the script
./harbor-run.sh -l 5               # limit to 5 tasks
./harbor-run.sh --n-concurrent 4   # 4 parallel workers

Extra flags are forwarded to harbor run, so any Harbor CLI option works. See ouro_harbor/README.md for full details.

Architecture

Ouro is a three-layer namespace package. Imports flow downward only; boundaries are enforced by import-linter. Each layer has its own README — start with the umbrella overview, then drill in:

• Architecture overview -- the three layers and how they fit together
• ouro.core -- agent loop + LLM primitives + hook protocol (Python SDK)
• ouro.capabilities -- AgentBuilder, tools, memory, skills, verification (Python SDK)
• ouro.interfaces -- CLI / TUI / bot entry points (no SDK)

Documentation

• CLI Guide -- interactive mode, task mode, commands, shortcuts
• Bot Guide -- IM bot setup, commands, proactive mechanisms, personality
• Configuration -- model setup, runtime settings, custom endpoints
• Examples -- usage patterns and programmatic API
• Memory Management -- compression, persistence, token tracking
• Extending -- adding tools, agents, LLM providers
• Packaging -- building, publishing, Docker

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

For development setup (install from source):

git clone https://github.com/ouro-ai-labs/ouro.git
cd ouro
./scripts/bootstrap.sh         # creates .venv and installs editable + dev deps
source .venv/bin/activate
./scripts/dev.sh check         # precommit + typecheck + tests

End-users should prefer uv tool install ouro-ai (see Quick Start); the source checkout is only needed when contributing.

License

MIT License