ouro-ai 0.3.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	pip install ouro-ai	pip install ouro-ai[bot]
Run	ouro	ouro --bot
Guide	CLI Guide	Bot Guide

Quick Start

Prerequisites: Python 3.12+.

pip install ouro-ai

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

# Single task
ouro --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.

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, see the Quick Start section (install from source):

git clone https://github.com/ouro-ai-labs/ouro.git
cd ouro
./scripts/bootstrap.sh   # requires uv

License

MIT License