Metadata-Version: 2.4
Name: alive-agent
Version: 0.2.0
Summary: A self-evolving AI agent that builds its own skills
Author: Alive Contributors
License-Expression: MIT
Keywords: agent,ai,llm,self-evolving,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40.0
Requires-Dist: duckduckgo-search>=4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai>=1.50.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: all
Requires-Dist: duckduckgo-search>=4.0; extra == 'all'
Requires-Dist: playwright>=1.40; extra == 'all'
Requires-Dist: python-telegram-bot>=20.0; extra == 'all'
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: search
Requires-Dist: duckduckgo-search>=4.0; extra == 'search'
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=20.0; extra == 'telegram'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">alive</h1>
  <p align="center"><strong>The AI agent that builds itself.</strong></p>
  <p align="center">
    <a href="#quickstart">Quickstart</a> &bull;
    <a href="#how-it-works">How It Works</a> &bull;
    <a href="#integrations">Integrations</a> &bull;
    <a href="#example-session">Examples</a> &bull;
    <a href="#skill-sharing">Sharing</a> &bull;
    <a href="#configuration">Config</a>
  </p>
  <p align="center">
    <a href="https://pypi.org/project/alive-agent/"><img alt="PyPI" src="https://img.shields.io/pypi/v/alive-agent?color=green"></a>
    <a href="https://github.com/alive-agent/alive/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
    <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue">
    <img alt="Tests" src="https://img.shields.io/badge/tests-585%20passing-brightgreen">
  </p>
</p>

---

Most AI agents come with a fixed set of tools. When they hit something they can't do, they stop and tell you.

Alive doesn't stop. It writes the code, tests it, and teaches itself the new ability &mdash; then monitors, schedules, and alerts you on its own.

<!-- TODO: Replace with actual GIF recording -->
<p align="center">
  <img src="https://placehold.co/800x400/1a1a2e/16c47f?text=alive+building+a+skill+%E2%80%94+GIF+coming+soon" alt="Alive building a skill from scratch" width="700">
</p>

<p align="center"><em>"Monitor Bitcoin price every 30 minutes, alert me on Telegram if it drops below 60k" &mdash; Alive builds the skill, schedules it, and wires up the alert. One sentence.</em></p>

---

## What makes Alive different

|  | **Alive** | Traditional Agents |
|--|-----------|-------------------|
| **Learns new skills at runtime** | Writes, tests, and saves new code | Fixed toolkit |
| **Skills persist across sessions** | `~/.alive/skills/` grows with you | Stateless |
| **Grows uniquely per user** | Shaped by YOUR requests | Same for everyone |
| **Monitoring & alerts** | Built-in scheduler, Telegram, webhooks | Requires external tools |
| **Self-reflection** | Dream log analyzes growth patterns | None |
| **Skill sharing** | Export/import `.tar.gz` or GitHub Gist | N/A |
| **Runs locally** | Ollama support, zero API keys needed | Cloud only |
| **Battle-tested builds** | Two competing implementations, best wins | Single attempt |
| **Subprocess sandbox** | 60s timeout, isolated venv | In-process |

Alive is a **personal** agent. Two people using Alive for a month will have completely different skill sets.

---

## Quickstart

```bash
pip install alive-agent
alive init
```

That's it. Alive creates `~/.alive/`, sets up a Python venv, installs three seed skills, and auto-detects your LLM provider.

```bash
alive run "get the current bitcoin price"
```

If Alive has a skill for it, it runs it. If not, it builds one, tests it, saves it, and runs it. Next time, it's instant.

### Choose your LLM

```bash
# Claude (default if ANTHROPIC_API_KEY is set)
alive config --provider claude --claude-key sk-ant-...

# OpenAI
alive config --provider openai --openai-key sk-...

# DeepSeek
alive config --provider deepseek --deepseek-key sk-...

# Ollama (local, no API key needed)
alive config --provider ollama
```

No key set? Alive auto-detects from environment variables. No environment variables? Falls back to Ollama.

---

## How it works

Every request goes through a planning and execution loop:

```
    ┌─────────────────────────────────────────────────────────┐
    |                     alive run "..."                      |
    └──────────────────────────┬──────────────────────────────┘
                               |
                    ┌──────────v──────────┐
                    |     1. PLAN          |
                    |  Decompose request   |
                    |  into steps          |
                    └──────────┬──────────┘
                               |
              ┌────────────────┼────────────────┬─────────────┐
              v                v                v             v
     ┌────────────────┐ ┌───────────────┐ ┌──────────┐ ┌──────────┐
     |  EXISTING_SKILL | |   NEW_SKILL   | | LLM_ONLY | | SCHEDULE |
     |  Run known skill| |  Build & test | | Text gen  | | Cron job |
     └────────┬───────┘ └───────┬───────┘ └────┬─────┘ └────┬─────┘
              |                 |               |            |
              |          ┌──────v──────┐       |            |
              |          |  2. BUILD    |       |            |
              |          |  Write code  |       |            |
              |          |  3. TEST     |       |            |
              |          |  Sandbox run |       |            |
              |          |  4. RETRY    |       |            |
              |          |  Fix & retry |       |            |
              |          |  (up to 5x)  |       |            |
              |          |  5. SAVE     |       |            |
              |          |  Register    |       |            |
              |          └──────┬──────┘       |            |
              |                 |               |            |
              └────────────────┬───────────────┘            |
                               |                             |
                    ┌──────────v──────────┐                 |
                    |   COMPOSE & OUTPUT   | <───────────────┘
                    |   Chain results,     |
                    |   synthesize answer   |
                    └─────────────────────┘
```

**Plan.** The LLM decomposes your request into steps: use an existing skill, build a new one, generate text, or schedule a recurring task.

**Build.** For new skills, the LLM writes a Python function with type hints, error handling, and tests. In **Battle Mode** (default), two competing implementations race &mdash; the faster, correct one wins.

**Test.** Code runs in an isolated subprocess with a 60-second timeout. Dependencies install into a shared venv at `~/.alive/venv/`.

**Retry.** If tests fail, Alive sends the error back to the LLM. Up to 5 attempts. After attempt 3, it tries a fundamentally different approach.

**Save.** Working skills persist to `~/.alive/skills/<name>/` with code, tests, docs, and metadata. Confidence scores update with every use via [Wilson score](https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval).

---

## Integrations

Alive ships with 5 integrations that compose into a unified monitoring and alerting pipeline. Say this:

> "Monitor the Hacker News front page every 2 hours, alert me on Telegram if a post about AI gets over 500 points"

Alive builds the scraping skill, schedules it, and wires up Telegram &mdash; all from one sentence.

### Web Search

Zero config. Works out of the box.

```bash
alive search "latest Python 3.13 features"
alive news "OpenAI announcements"
```

Three backends: **DuckDuckGo** (default, no key), **Tavily** (API key for better results), or **SearXNG** (self-hosted).

```bash
# Optional: upgrade to Tavily
alive config --tavily-key tvly-...

# Optional: use self-hosted SearXNG
alive config --searxng-url http://localhost:8888
```

Skills you build automatically use web search when they need live data. No extra configuration.

### Telegram Alerts

Get notified when your scheduled tasks find something interesting.

```bash
alive setup telegram
```

The setup wizard walks you through creating a bot via @BotFather, validates the token, and auto-detects your chat ID.

```bash
alive test-telegram                    # Send a test message
alive telegram start --daemon          # Run as a chat bot
```

### Scheduler & Daemon

Schedule any task with natural language intervals:

```bash
alive schedule "check if Python 3.14 has been released" --every 6h
alive schedule "fetch my server's uptime" --daily --at 09:00
alive schedule "scrape competitor prices" --cron "0 */4 * * *" --notify telegram
```

```bash
alive daemon start     # Start the background scheduler
alive daemon status    # Check what's running
alive schedules        # List all scheduled tasks
```

### Browser Automation

For JavaScript-heavy sites where simple HTTP fetch isn't enough:

```bash
alive setup browser    # Installs Playwright + Chromium
alive screenshot https://example.com
```

Skills automatically use the browser when they need to interact with dynamic pages, fill forms, or click buttons.

### Webhooks

Send alerts to Slack, Discord, or any webhook endpoint:

```bash
alive setup webhook    # Interactive: add name, URL, type, test
alive webhooks         # List configured webhooks
```

Multiple named webhooks supported. Skills and scheduled tasks can route alerts to different channels.

### All five together

```bash
# One command does everything:
alive run "monitor the price of ETH on CoinGecko every 30 minutes, \
           alert me on Telegram if it drops below $3000, \
           also post to my #crypto Slack channel"

# What happens:
# 1. Builds a skill that scrapes ETH price (uses browser if needed, web_search otherwise)
# 2. Adds Telegram alert when price < $3000
# 3. Adds Slack webhook notification
# 4. Schedules the whole thing to run every 30 minutes
# 5. Tells you to start the daemon if it's not running
```

```bash
alive integrations     # See status of all 5 integrations
```

---

## Example session

```bash
$ alive run "generate 10 random passwords, each 16 characters with symbols"
```

```
Execution Plan for: generate 10 random passwords...
+-- 1 NEW_SKILL: Build password generator (needs: "generate random passwords...")
+-- 2 LLM_ONLY: Format the output nicely

  Battle Mode: two implementations competing...
  Candidate A: secrets module with string templates  [passed] 2.1ms avg
  Candidate B: random.choices with character pools   [passed] 3.4ms avg
  Winner: A (1.6x faster)

  Attempt 1/5
  Tests passed.

  Skill Built: password_generator
  Attempts: 1  |  Dependencies: none  |  Battle: A won

  Step 1/2: Build password generator
  Step 2/2: Format the output nicely

Here are 10 random passwords:
  1. kQ#8mP!xR2nL@5vW
  2. Yj$4hS&9Bw*3Tz!e
  3. ...
```

That skill exists forever. Build on it:

```bash
$ alive run "read my .env file and check if any passwords are weak"
```

```
Execution Plan for: read .env and check passwords
+-- 1 EXISTING_SKILL file_reader: Read the .env file
+-- 2 NEW_SKILL: Analyze password strength
+-- 3 LLM_ONLY: Summarize findings

  Step 1/3: Read .env file
  Step 2/3: Analyze password strength  (built: password_strength_checker)
  Step 3/3: Summarize findings
```

Two requests, two new skills. Alive now knows how to generate passwords AND check their strength.

### Skill chains

Compose skills into reusable pipelines:

```bash
$ alive chain morning-news web_fetch html_parser summarizer
$ alive run morning-news
```

```bash
$ alive chains
```

### Teach existing code

Got a Python script you already wrote? Import it:

```bash
$ alive teach my_script.py --name "csv_cleaner"
```

Alive wraps it in the skill template, generates tests, and registers it.

### Evolve skills

Improve a skill that works but could be faster or handle more edge cases:

```bash
$ alive evolve password_generator
```

Alive analyzes the code, suggests improvements, and applies them with rollback support.

### Skill graph

See how your skills relate to each other:

```bash
$ alive graph
```

```
Skill Map (12 skills, 4 clusters)
+-- Web cluster
|   +-- web_fetch
|   |   +-- --> html_parser
|   +-- html_parser
|   +-- price_scraper
+-- Text cluster
|   +-- summarizer
|   +-- translator
+-- File cluster
|   +-- file_reader
|   +-- csv_cleaner
+-- Standalone
    +-- password_generator
    +-- qr_generator

Chains
+-- morning-news (web_fetch -> html_parser -> summarizer)
```

```bash
$ alive graph --dot > skills.dot   # Export Graphviz DOT format
```

### Watch & suggest

Alive analyzes your shell history and suggests skills to automate your workflows:

```bash
$ alive watch
```

### Dream log

Alive reflects on its own growth:

```bash
$ alive dream
```

Dream logs analyze patterns in your requests, identify your most-used domains, suggest skills to build next, and spot skill breeding opportunities.

---

## Skill sharing

### Export

```bash
$ alive share password_generator
# Creates password_generator.alive-skill.tar.gz

$ alive share password_generator --gist
# Publishes to GitHub Gist
```

### Install

```bash
# From file
$ alive install password_generator.alive-skill.tar.gz

# From URL
$ alive install https://example.com/skills/csv_parser.alive-skill.tar.gz

# From Gist
$ alive install https://gist.github.com/alice/abc123
```

Alive shows you the code before installing. No blind trust.

### Browse community

```bash
$ alive browse --search "data"
```

---

## Configuration

### Providers

| Provider | API Key Env Var | Default Model | Local? |
|----------|-----------------|---------------|--------|
| `claude` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` | No |
| `openai` | `OPENAI_API_KEY` | `gpt-4o` | No |
| `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-chat` | No |
| `ollama` | _(none needed)_ | `llama3.1` | Yes |

**Resolution order:** `--provider` flag &rarr; `ALIVE_PROVIDER` env var &rarr; `config.json` &rarr; auto-detect from API keys &rarr; Ollama fallback.

```bash
alive config --provider claude --claude-key sk-ant-...
alive config --show   # View current config (keys are masked)
```

### Environment variables

```bash
export ALIVE_HOME=~/my-alive       # Override home directory
export ALIVE_PROVIDER=claude       # Override provider
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export DEEPSEEK_API_KEY=sk-...
```

### Directory structure

```
~/.alive/
+-- config.json           # Provider, API keys, integration settings
+-- alive.db              # SQLite: requests, gaps, stats
+-- schedules.json        # Scheduled task definitions
+-- daemon.pid            # Scheduler daemon PID
+-- venv/                 # Shared Python venv for skill deps
+-- skills/               # All installed skills
|   +-- web_fetch/        # Seed skill
|   |   +-- skill.py
|   |   +-- test_skill.py
|   |   +-- metadata.json
|   |   +-- SKILL.md
|   |   +-- memory.db     # Per-skill persistent memory
|   |   +-- birth_story.json
|   +-- password_generator/  # User-built skill
|   |   +-- ...
|   +-- morning-news/     # Skill chain
|       +-- chain.json
+-- dreams/               # Dream log entries
|   +-- 2026-03-18.md
+-- logs/                 # Daemon and execution logs
```

### All CLI commands

**Core**

| Command | Description |
|---------|-------------|
| `alive run "..."` | Process a natural language request |
| `alive plan "..."` | Show execution plan without running |
| `alive simple "..."` | Skip planning, direct LLM call |
| `alive build "..."` | Build a new skill from description |

**Skills**

| Command | Description |
|---------|-------------|
| `alive skills` | List all installed skills |
| `alive skill <name>` | Show details of a specific skill |
| `alive replay <name>` | View the full build journey |
| `alive evolve <name>` | Improve a skill with LLM suggestions |
| `alive teach <file>` | Import a Python script as a skill |
| `alive watch` | Analyze shell history, suggest automations |

**Chains**

| Command | Description |
|---------|-------------|
| `alive chain <name> <steps...>` | Create a named pipeline |
| `alive chains` | List all chains |
| `alive unchain <name>` | Delete a chain |

**Memory & Analysis**

| Command | Description |
|---------|-------------|
| `alive memory <name>` | Inspect skill's persistent store |
| `alive status` | Show capabilities, gaps, and stats |
| `alive graph` | Visual map of skill relationships |
| `alive dream` | Generate self-reflection log |

**Search**

| Command | Description |
|---------|-------------|
| `alive search "..."` | Web search with rich display |
| `alive news "..."` | Search recent news |

**Scheduling**

| Command | Description |
|---------|-------------|
| `alive schedule "..." --every 30m` | Schedule a recurring task |
| `alive schedules` | List all scheduled tasks |
| `alive unschedule <task>` | Remove a task |
| `alive pause <task>` | Pause a task |
| `alive resume <task>` | Resume a task |
| `alive daemon start\|stop\|status\|logs` | Manage background scheduler |

**Integrations**

| Command | Description |
|---------|-------------|
| `alive integrations` | Show status of all integrations |
| `alive setup <name>` | Interactive setup wizard |
| `alive telegram start\|stop\|status` | Manage Telegram bot |
| `alive webhooks` | List configured webhooks |
| `alive screenshot <url>` | Take a webpage screenshot |
| `alive test-search` | Test web search |
| `alive test-telegram` | Test Telegram |
| `alive test-browser` | Test browser automation |
| `alive test-webhook` | Test webhook |

**Sharing**

| Command | Description |
|---------|-------------|
| `alive share <name>` | Export skill as `.tar.gz` or Gist |
| `alive install <source>` | Import from file, URL, or Gist |
| `alive browse` | Browse community skills |

**Setup**

| Command | Description |
|---------|-------------|
| `alive init` | First-time setup |
| `alive config` | Set provider, API keys, integrations |

### Useful flags

```bash
alive run "..." --dry-run          # See the plan without executing
alive run "..." --simple           # Skip planning, direct LLM call
alive run "..." --no-battle        # Disable battle mode
alive run "..." --verbose          # Show full errors and LLM details
alive run "..." --provider ollama  # Override provider for one command
alive build "..." --verbose        # See generated code during build
alive graph --dot                  # Output Graphviz DOT format
alive graph --classify             # Use LLM to classify skill domains
```

---

## Contributing

```bash
git clone https://github.com/alive-agent/alive.git
cd alive
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run the full test suite
pytest tests/ -v    # 585 tests

# Lint
ruff check src/ tests/
```

### Where to contribute

- **New seed skills** &mdash; add to `src/alive/seeds/`
- **Provider support** &mdash; add new LLM providers in `src/alive/llm/`
- **Integrations** &mdash; add new integrations in `src/alive/integrations/`
- **Community skills** &mdash; share skills to the community catalog
- **Bug fixes** &mdash; check [issues](https://github.com/alive-agent/alive/issues)

### Architecture

```
src/alive/
+-- cli.py                  # Typer CLI: all commands
+-- config.py               # Paths and directory setup
+-- core/
|   +-- planner.py          # Request -> ExecutionPlan
|   +-- composer.py          # ExecutionPlan -> Result
|   +-- skill_builder.py     # Description -> Working skill (battle mode)
|   +-- skill_registry.py    # CRUD for skills + Wilson scoring
|   +-- chain.py             # Skill chaining and pipelines
|   +-- graph.py             # Skill relationship visualization
|   +-- self_model.py        # Capability tracking and gap analysis
|   +-- evolve.py            # Skill improvement engine
|   +-- teach.py             # Import external scripts
|   +-- watch.py             # Shell history analysis
|   +-- replay.py            # Birth story recording
+-- llm/
|   +-- base.py              # Abstract LLMProvider
|   +-- registry.py          # Provider factory + auto-detection
|   +-- claude_provider.py   # Anthropic Claude
|   +-- openai_provider.py   # OpenAI
|   +-- deepseek_provider.py # DeepSeek
|   +-- ollama_provider.py   # Local Ollama
+-- integrations/
|   +-- web_search.py        # DuckDuckGo / Tavily / SearXNG
|   +-- telegram.py          # Alerts + chat bot
|   +-- scheduler.py         # Task scheduling + daemon
|   +-- browser.py           # Playwright automation
|   +-- webhook.py           # Slack / Discord / generic
+-- sandbox/
|   +-- runner.py            # Subprocess execution (60s timeout)
|   +-- dependency.py        # Shared venv management
+-- memory/
|   +-- skill_memory.py      # Per-skill SQLite key-value store
+-- dream/
|   +-- dream_log.py         # Self-reflection engine
+-- sharing/
|   +-- export.py            # .tar.gz + Gist publishing
|   +-- import_skill.py      # Import with security review
|   +-- browse.py            # Community catalog
+-- seeds/                   # Bundled starter skills
    +-- web_fetch/
    +-- file_reader/
    +-- shell_run/
```

---

## Roadmap

- **Skill breeding** &mdash; Alive notices two skills that combine well and proposes a hybrid
- **Proactive engine** &mdash; Monitors your workflow and pre-builds skills it predicts you'll need
- **Federated evolution** &mdash; Community skills evolve across the network, best implementations float up
- **Multi-agent composition** &mdash; Multiple Alive instances collaborating with different specializations
- **Voice interface** &mdash; Talk to Alive, it builds skills from spoken descriptions

---

## License

[MIT](LICENSE). Do whatever you want with it.

---

<p align="center">
  <em>Alive starts with 3 skills. How many will yours have?</em>
</p>
