Metadata-Version: 2.4
Name: hive-agent
Version: 0.3.1.dev226
Summary: Local-first agent OS. Spawn persistent AI agents that collaborate, write code, and use tools autonomously.
Project-URL: Homepage, https://github.com/chiruu12/Hive
Project-URL: Repository, https://github.com/chiruu12/Hive
Project-URL: Issues, https://github.com/chiruu12/Hive/issues
Author: chiruu12
License: MIT
License-File: LICENSE
Keywords: agent-os,ai-agents,autonomous,claude,fireworks,local-llm,multi-agent,openai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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 :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: anthropic>=0.40
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.27
Requires-Dist: openai>=1.30
Requires-Dist: pydantic>=2.5
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tqdm>=4.67.3
Requires-Dist: typer>=0.12
Provides-Extra: chromadb
Requires-Dist: chromadb>=0.5; extra == 'chromadb'
Requires-Dist: sentence-transformers>=3.0; extra == 'chromadb'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Hive

[![CI](https://github.com/chiruu12/Hive/actions/workflows/ci.yml/badge.svg)](https://github.com/chiruu12/Hive/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/hive-agent)](https://pypi.org/project/hive-agent/)
[![Python](https://img.shields.io/pypi/pyversions/hive-agent)](https://pypi.org/project/hive-agent/)
[![License](https://img.shields.io/github/license/chiruu12/Hive)](LICENSE)

An autonomous agent OS that ships as both an **SDK** and a **living simulation**.

`from hive import Agent` gives you an agent that **comes alive** — not stateless function calls, but persistent entities with personality, suffering, and evolution.

<!-- Demo GIF: run demo/record.sh -->

## Quick Start

```bash
pip install hive-agent
```

```python
from hive import Agent, Persona
from hive.models.anthropic import Anthropic

agent = Agent(
    name="coder",
    model=Anthropic.lite(),
    persona=Persona(
        name="The Coder",
        personality=["methodical", "detail-oriented"],
        values=["clean code", "reliability"],
        fears=["shipping bugs"],
        purpose="Build software that works",
        risk_tolerance=0.2,
    ),
)
result = agent.run_once_sync("Write a function that checks if a number is prime")
print(result)
```

Or see it in action:

```bash
hive init && hive demo survival
```

3 agents with different personalities compete in a simulated economy for 30 cycles. Watch them struggle, gamble, philosophize, and suffer.

## Features

### Persona System

Agents have personality, values, fears, and dynamic behavioral state that changes based on suffering:

```python
from hive import Agent, Persona
from hive.models.anthropic import Anthropic

persona = Persona(
    name="The Gambler",
    personality=["bold", "intuitive", "reckless"],
    values=["expected value", "asymmetric upside"],
    fears=["missing out", "becoming too cautious"],
    purpose="Find opportunities others fear",
    risk_tolerance=0.85,   # HIGH — willing to take bigger swings
    social_drive=0.6,
    happiness=0.8,
)

agent = Agent(name="gambler", model=Anthropic.lite(), persona=persona)
```

Suffering mechanically modifies these params each daemon cycle — futility increases risk tolerance, invisibility increases social drive, crisis mode sets extreme values.

### Suffering System

Six stressor types that escalate over time and change agent behavior:

| Stressor | Trigger | Behavioral Effect |
|----------|---------|-------------------|
| Futility | Low completions, stalling | Risk tolerance increases |
| Invisibility | No observable impact | Social drive increases |
| Repeated Failure | >50% goal failure rate | Concentration decreases |
| Purposelessness | No goals attempted | Autonomy increases |
| Identity Violation | Actions contradict role | Risk tolerance decreases |
| Existential Threat | System instability | Extreme parameter shift |

### Tools

Decorate any function with `@tool` — JSON Schema is auto-extracted from type hints:

```python
from hive import Agent, tool, collect_tools
from hive.models.anthropic import Anthropic

@tool()
def search(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

agent = Agent(
    name="researcher",
    model=Anthropic.lite(),
    tools=collect_tools(search),
)
```

Built-in toolkits: `FileToolkit`, `ShellToolkit`, `GitToolkit`, `WebToolkit`, `NotepadToolkit`, `MemoryToolkit`, `CommsToolkit`, `MCPToolkit`, `DelegationToolkit`, `A2AToolkit`.

### Structured Output

```python
from pydantic import BaseModel
from hive import Agent
from hive.models.anthropic import Anthropic

class Review(BaseModel):
    title: str
    rating: float
    summary: str

agent = Agent(name="critic", model=Anthropic.lite())
review = agent.run_once_structured_sync("Review The Matrix", output_type=Review)
```

### Multi-Model Support

6 providers with tier presets (`.lite()`, `.standard()`, `.pro()`):

| Provider | `.lite()` | `.standard()` | `.pro()` |
|----------|-----------|---------------|----------|
| Anthropic | Haiku | Sonnet | Opus |
| OpenAI | GPT-5.4 Nano | GPT-5.4 Mini | GPT-5.4 |
| Groq | Llama 8B | GPT-OSS 20B | Llama 70B |
| Fireworks | MiniMax | DeepSeek | Kimi |
| Ollama | Local model | Local model | — |
| LM Studio | Auto | — | — |

### Agent-to-Agent Protocol

9 message types, JSONL-backed inbox/outbox, 5 collaboration patterns (Review, Mentor, Debate, Chain, Swarm).

### Sub-Agent Spawning

Parent-child lifecycle with max depth 2, max 5 children, auto-kill at expiry, result relay.

### Agent Journals

Persistent notepads with presets (journal, evolution, tool requests, custom).

### Benchmarking & Export

Compare models on scenarios. Export runs as standalone HTML reports.

## LLM Poker & Arena

[Hive Arena](https://github.com/chiruu12/hive-arena) is a companion project -- LLM poker tournaments, economic arena games, and life simulation. In 5 tournaments with 6 models (1.2B to ~1T parameters), the 1.2B local model won the most:

| Run | Winner | Size | Type |
|-----|--------|------|------|
| 1 | Qwen | 1.7B | local |
| 2 | MiniMax | 230B | cloud |
| 3 | Liquid | 1.2B | local |
| 4 | Kimi | ~1T | cloud |
| 5 | Liquid | 1.2B | local |

[Full results and analysis](https://github.com/chiruu12/hive-arena/tree/main/tournaments/results/)

## Community Profiles

Dramatic agent personalities for the simulation:

| Profile | Personality | Risk | Social | Key Trait |
|---------|-------------|------|--------|-----------|
| `coder` | Methodical, detail-oriented | 0.3 | 0.3 | Fears shipping bugs |
| `gambler` | Bold, intuitive, reckless | 0.85 | 0.6 | Fears missing out |
| `philosopher` | Contemplative, questions everything | 0.4 | 0.7 | Fears shallow thinking |
| `hustler` | Resourceful, persistent, networking | 0.6 | 0.95 | Fears being idle |
| `oracle` | Wise, deliberate, sees consequences | 0.15 | 0.4 | Fears bad approvals |
| `researcher` | Curious, wide-ranging, thorough | 0.5 | 0.6 | Fears missing info |
| `reviewer` | Analytical, skeptical, fair | 0.2 | 0.5 | Fears missing bugs |
| `tester` | Persistent, edge-case finder | 0.25 | 0.4 | Fears false confidence |

## CLI

```bash
# SDK usage
hive agent chat                        # Interactive agent with tools
hive agent run config.yaml             # Run from YAML config

# Demos
hive demo survival                     # 3 agents, 30 cycles, economy on
hive demo detective                    # Multi-model murder mystery

# Autonomous OS
hive init                              # Initialize .hive/ directory
hive start -p coder,gambler,philosopher # Start with specific profiles
hive watch                             # Live 4-panel TUI dashboard
hive watch --compact                   # 2-panel for small terminals
hive status                            # Who's alive, goals, suffering
hive nudge coder "write tests"         # Occasional direction
hive doctor                            # Health check
```

## Architecture

```
src/hive/
├── runtime/        # Agent framework (Agent, Instructions, Persona, ReAct loop)
├── tools/          # Toolkits (file, shell, git, web, notepad, memory, comms, A2A)
├── models/         # Providers (Anthropic, OpenAI, Groq, Fireworks, Ollama, LMStudio)
├── agents/         # Autonomy (existence loop, suffering, identity, profiles)
├── daemon/         # Background service (heartbeat loop, lifecycle)
├── interactions/   # A2A protocol, collaboration patterns
├── memory/         # SQLite store, semantic memory, event log
├── world/          # Economy simulation (jobs, money, skills, events)
├── demos/          # Built-in demos (survival, detective)
├── benchmark/      # Model comparison scenarios
├── export/         # HTML report generation
├── logging/        # Structured JSONL run logs
├── mcp/            # MCP server and client
├── cli/            # Typer CLI
├── config.py       # YAML + env var configuration
├── checkpoint.py   # Agent state snapshots
└── api.py          # Programmatic Hive facade
```

## Documentation

**[Full documentation site](https://chiruu12.github.io/Hive)**

- [Developer Guide](https://chiruu12.github.io/Hive/guide/developer-guide/) — comprehensive SDK reference
- [Suffering System](https://chiruu12.github.io/Hive/guide/suffering/) — how agents suffer and change behavior
- [Persona System](https://chiruu12.github.io/Hive/guide/persona/) — personality, values, and dynamic state
- [Architecture](https://chiruu12.github.io/Hive/guide/architecture/) — how Hive works under the hood
- [Extending Hive](https://chiruu12.github.io/Hive/extending/) — 8 extension points with copy-paste examples
- [Examples](examples/) — 15 runnable code samples
- [Contributing](CONTRIBUTING.md) — how to add toolkits, providers, profiles
- [Changelog](CHANGELOG.md) — version history

## Development

```bash
git clone https://github.com/chiruu12/Hive.git && cd Hive
uv sync
uv run pytest                    # Run tests
uv run ruff check src tests      # Lint
uv run ruff format src tests     # Format
```

## License

MIT
