# ALIVE — Self-Evolving AI Agent

## Project Context
Alive is an open-source AI agent that builds its own skills when it encounters
tasks it can't perform. Unlike agents with fixed toolkits, Alive is a PERSONAL
agent that grows uniquely for each user. It writes code, tests it in a sandbox,
and permanently learns new abilities.

## Architecture Principles
- Skills are plain Python files in ~/.alive/skills/<name>/
- Each skill has: skill.py, test_skill.py, metadata.json, SKILL.md, birth_story.json
- The skill builder writes code, tests it in sandbox, retries on failure (max 5)
- Battle Mode (default): two competing implementations, faster correct one wins
- The planner decomposes requests into steps: EXISTING_SKILL, NEW_SKILL, LLM_ONLY, SCHEDULE
- All state in SQLite at ~/.alive/alive.db
- Multi-provider LLM support (Claude, OpenAI, Ollama, DeepSeek)
- 5 composable integrations: web search, telegram, scheduler, browser, webhooks
- ALP (Agent Language Protocol): peer-to-peer skill discovery and exchange

## Code Style
- Python 3.11+, type hints everywhere
- async where beneficial (LLM calls), sync for simplicity elsewhere
- rich library for all terminal output (spinners, tables, panels, trees)
- No classes where functions suffice. Keep it simple
- Error messages should be helpful and suggest next steps
- Lazy imports for optional dependencies (playwright, telegram)

## Key Design Decisions
- Skills run in subprocess with 60s timeout, NOT in-process
- Dependencies installed in a shared venv at ~/.alive/venv/
- The LLM provider is configurable via ALIVE_PROVIDER env var
- Default provider: claude (falls back to ollama if no API key)
- Skill metadata.json tracks: created_at, times_used, success_rate,
  last_used, dependencies, description, confidence_score, domain
- Skill builder prompt dynamically injects available integration context
- Scheduler daemon runs as a background subprocess with PID file
- Web search uses DuckDuckGo by default (zero config), Tavily/SearXNG optional
- Browser automation uses sync Playwright API (skills run in subprocesses)
- Per-skill persistent memory via SQLite key-value store

## Module Overview
- **core/planner.py** — Decomposes requests into ExecutionPlan with typed steps
- **core/composer.py** — Executes plans step-by-step, chains outputs, synthesizes
- **core/skill_builder.py** — Self-Extension Engine with battle mode
- **core/skill_registry.py** — Skill CRUD, metadata, Wilson score confidence
- **core/chain.py** — Named multi-skill pipelines with scheduling
- **core/graph.py** — Skill relationship visualization (chains, co-usage, co-creation)
- **core/self_model.py** — Capability tracking, gap analysis, domain classification
- **core/evolve.py** — Skill improvement based on execution stats
- **core/teach.py** — Import external Python scripts as skills
- **core/watch.py** — Shell history analysis for skill suggestions
- **core/replay.py** — Birth story recording including battle logs
- **integrations/web_search.py** — DuckDuckGo / Tavily / SearXNG backends
- **integrations/telegram.py** — Alert mode + chat bot mode
- **integrations/scheduler.py** — Task scheduling + background daemon
- **integrations/browser.py** — Playwright-based web automation
- **integrations/webhook.py** — Slack / Discord / generic webhook notifications
- **network/identity.py** — Agent identity (UUID, alias, agent card)
- **network/discovery.py** — UDP broadcast peer discovery + manual connect
- **network/server.py** — HTTP server for skill exchange (card, catalog, pull)
- **network/exchange.py** — Skill pull, LLM adaptation, sandbox test, lineage
- **network/security.py** — Code scanning for risks before installation
- **network/conversation_log.py** — Human-readable network activity log
- **memory/skill_memory.py** — Per-skill SQLite key-value persistence
- **sandbox/runner.py** — Subprocess execution with timeout
- **sandbox/dependency.py** — Shared venv management

## Testing
- 657 tests covering all modules
- Tests use unittest.mock extensively for external services
- Optional deps (playwright) use sys.modules injection for mock compatibility
- Run: `pytest tests/ -v`

## Current Status
- [x] Project scaffold
- [x] CLI with typer + rich (40+ commands)
- [x] LLM provider abstraction (Claude, OpenAI, DeepSeek, Ollama)
- [x] Skill registry with Wilson score confidence
- [x] Skill builder with Battle Mode
- [x] Sandbox executor (subprocess, 60s timeout)
- [x] Planner (4 step types: EXISTING_SKILL, NEW_SKILL, LLM_ONLY, SCHEDULE)
- [x] Composer (step-by-step execution with error recovery)
- [x] Skill chaining (named pipelines)
- [x] Skill graph (relationship visualization + DOT export)
- [x] Self-model (capabilities, gaps, domains, growth timeline)
- [x] Dream log (self-reflection engine)
- [x] Skill evolution (improve existing skills)
- [x] Skill teaching (import Python scripts)
- [x] Shell history analysis (watch command)
- [x] Persistent memory (per-skill key-value store)
- [x] Skill sharing (export/import/browse)
- [x] Web search integration (3 backends)
- [x] Telegram integration (alerts + bot)
- [x] Scheduler integration (daemon + cron)
- [x] Browser integration (Playwright)
- [x] Webhook integration (Slack/Discord/generic)
- [x] Integration-aware skill builder prompts
- [x] ALP network layer (peer discovery, skill exchange, lineage tracking)
- [x] Agent identity system (UUID, alias, agent card)
- [x] UDP broadcast peer discovery + manual connect
- [x] HTTP server for skill catalog and exchange
- [x] Skill mutation on transfer (LLM adaptation)
- [x] Security scanning for foreign code
- [x] Network conversation log
- [x] Tests (657 passing)
- [ ] README with demo GIFs
- [ ] PyPI publish
