Metadata-Version: 2.4
Name: hermes-hive
Version: 2.0.19
Summary: Multi-Agent Orchestration for Hermes Agent. Code constrains AI — not the other way around.
License-Expression: MIT
Project-URL: Homepage, https://github.com/Ebonyhtx/Hermes-Hive
Project-URL: Repository, https://github.com/Ebonyhtx/Hermes-Hive.git
Project-URL: Issues, https://github.com/Ebonyhtx/Hermes-Hive/issues
Keywords: hermes,multi-agent,orchestration,code-generation,llm,state-machine
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: transitions>=0.9.3
Provides-Extra: memory
Requires-Dist: chromadb>=1.5.9; extra == "memory"
Requires-Dist: sentence-transformers>=5.5.1; extra == "memory"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/badge/Hermes-Plugin-blue?style=for-the-badge" alt="Hermes Plugin"/>
  <img src="https://img.shields.io/badge/Python-3.12+-blue?style=for-the-badge&logo=python" alt="Python"/>
  <img src="https://img.shields.io/badge/DeepSeek-V4-536DFE?style=for-the-badge" alt="DeepSeek"/>
  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License"/>
  <img src="https://img.shields.io/badge/tests-49%2F49-brightgreen?style=for-the-badge" alt="Tests"/>
</p>

<h1 align="center">🐝 HIVE</h1>
<h3 align="center">Code constrains AI — not the other way around.</h3>

<p align="center">
  <b>Multi-Agent Orchestration for Hermes.</b><br>
  Architect → Planner → Coder → Reviewer. All driven by a deterministic state machine,<br>
  none driven by prompt prayers.
</p>

<p align="center">
  <b>pip install hermes-hive</b>
</p>

---

## Why HIVE?

Every multi-agent framework tells LLMs *"please follow these rules."*

**HIVE doesn't ask. It enforces.**

| Framework | How it constrains LLMs | Can LLM break it? |
|-----------|----------------------|:---:|
| **CrewAI** | Prompts describe roles | ✅ Yes — LLM forgets it's a Coder |
| **AutoGen** | Agents negotiate via chat | ✅ Yes — two LLMs agree on a mistake |
| **MetaGPT** | SOP written in prompts | ✅ Yes — LLM skips a step, no one notices |
| **LangGraph** | Graphs, but LLM can route edges | ✅ Yes — LLM takes wrong path |
| **HIVE** | **State machine in Python code** | **❌ No — code is the guard** |

HIVE's orchestrator is a **deterministic state machine** (`transitions` library, 12 states, 23 transitions). LLMs are called *only* at specific states (Architect, Planner, Reviewer). They cannot skip steps, change the flow, or override constraints.

---

## Quick Start

```bash
pip install hermes-hive
hive init
hive build "A CLI calculator"
```

That's it. HIVE orchestrates 4 agents across your project. You watch it build.

---

## The 4-Agent Pipeline

```
You: "Build a calculator"
  │
  ▼
┌─────────────────────────────────────┐
│ 🏗️  Architect (v4-pro)              │
│ Multi-turn requirements dialogue    │
│          │ User confirms            │
│          ▼                          │
│       project_brief.json            │
└─────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────┐
│ 📋  Planner (v4-flash)             │
│ Splits into DAG tasks:             │
│   T1: Core engine (reasonix)       │
│   T2: Deploy verify (toolman)      │
│   T3: Cleanup (toolman)            │
│          │                         │
│          ▼                         │
│       tasks/*.json                  │
└─────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────┐
│ ⌨️  Coder (Reasonix / LLM fallback) │
│ Writes code + pytest self-verify   │
│   T1 → calculator.py               │
│          │                         │
│          ▼                         │
│       src/*.py                      │
└─────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────┐
│ 🔍  Reviewer (v4-flash)            │
│ Audits every output:               │
│   ✅ pass → next layer             │
│   🟡 minor → retry                 │
│   🔴 fatal → replan                │
│          │                         │
│          ▼                         │
│       ✅ DONE → projects/           │
└─────────────────────────────────────┘
```

**Every transition between boxes? Python code, not an LLM decision.**

---

HIVE is a **Hermes plugin**. No extra desktop app needed.

```
~/.hermes/
├── config.yaml          ← HIVE reads your model/API config
├── .env                 ← HIVE reads your API keys
├── skills/hive/         ← SKILL.md teaches Hermes when to invoke hive
└── hive/
    ├── hive.json        ← 🌐 Global config
    ├── projects/        ← Built projects
    ├── chroma_db/       ← L3 vector memory
    └── skill_registry.json
```

From Hermes CLI or Desktop: "Build me a web scraper" → Hermes loads the `hive` skill → runs `hive build`.

---

## What HIVE Manages

| Capability | Description |
|-----------|-------------|
| **Project lifecycle** | Versioned briefs, changelogs, task progress |
| **Skill evolution** | DONE triggers skill extraction; review → approve/reject/merge |
| **L3 Memory (ChromaDB)** | 3-domain vector memory, BGE embeddings (optional) |
| **Crash recovery** | Atomic file-system checkpoints; `resume` skips done tasks |
| **Parallel execution** | ThreadPoolExecutor, max 3 concurrent agents |
| **Entropy control** | Stale workspace cleanup, dormant skill archival |
| **Full audit trail** | Every action → JSON file. Debuggable, replayable |
| **LLM fallback** | Coder: Reasonix (Go) preferred, LLM auto-fallback |
| **Multi-Provider** | DeepSeek / OpenAI / Anthropic / OpenRouter |
| **Bilingual CLI** | `lang zh` / `lang en` instant switch |
| **Open framework** | Add custom agents via config files — no code changes needed |

---

## Customize & Extend

HIVE is an **open framework**. Every agent is defined by configuration files, not hardcoded logic. You — or your Hermes agent — can add new agent roles, tune behavior, and manage the ecosystem without touching Python code.

### Agent Configuration (3 files per role)

```
profiles/{role}/
└── config.yaml      ← model, tools, memory settings

agents/{role}/
├── soul.md          ← agent identity & behavior rules
├── skills.md        ← domain knowledge & patterns
└── model.yaml       ← model parameters
```

### Constitution (`agents/constitution.md`)

Global rules injected into every agent. All agents share this — define cross-cutting constraints here.

### Ecosystem Management (`governance/`)

| File | Purpose |
|------|---------|
| `skill_governor.py` | Skill registry — conflict detection, lifecycle |
| `hive_memory.py` | ChromaDB L3 memory — three-domain vector store |
| `entropy.py` | Cleanup — stale workspaces, dormant skills |
| `profile_manager.py` | Profile validation on startup |

### Global Configuration (`hive.json`)

All HIVE behavior is controlled by a single file at `~/.hermes/hive/hive.json`. Deployed automatically by `hive init`.

**🔒 Safety guarantee:** If you delete this file, corrupt the JSON, or set invalid values — HIVE runs with code defaults. Each field falls back independently. You cannot break HIVE by misconfiguring it.

```json
{
  "orchestrator":    // max_children, max_retries, parallel_workers …
  "provider_defaults": // deepseek / openai / anthropic / openrouter
  "coder":           // engine: auto | reasonix | llm
  "memory":          // ChromaDB enabled, embedding model, top_k
  "language":        // default: zh | en
  "skills":          // auto_approve, merge_threshold
  "entropy":         // workspace TTL, skill lifecycle days
  "agent_overrides": // per-role temperature / max_tokens
}
```

Full reference: see `hive.json` in the repository.

### Adding a New Agent

1. Create `profiles/{my-agent}/config.yaml`
2. Create `agents/{my-agent}/soul.md`
3. Add to `constitution.md` if global rules apply
4. Register in `orchestrator/protocol.py` if new task types needed

**No Python code changes required for basic agents.** The state machine discovers profiles from the filesystem.

---

## Architecture

```
┌──────────────────────────────────────────┐
│              HIVE Orchestrator            │
│          (Pure Python State Machine)      │
│                                          │
│  IDLE → ARCHITECTING → PLANNING →        │
│  DISPATCH → EXECUTING → REVIEWING →      │
│  DONE / REPLAN / RETRY                   │
│                                          │
│  🔒 LLMs cannot cross state boundaries   │
└──────────────────────────────────────────┘
         │          │          │
    ┌────▼───┐ ┌───▼────┐ ┌──▼──────┐
    │Architect│ │Planner │ │Reviewer │
    │(v4-pro) │ │(v4-flash)│(v4-flash)│
    └────────┘ └────────┘ └─────────┘
                    │
              ┌─────▼─────┐
              │  Reasonix  │
              │ (Go binary)│
              └───────────┘

Communication: File system + JSON
Concurrency:   Atomic file renames
Auditability:  Every action = one JSON file
```

---

## Design Philosophy

**1. Code Constrains LLMs.** If the rule can be expressed in code, it's in code. Prompts are for creative work, not enforcement.

**2. File System as Protocol.** Agents communicate via JSON files in agreed directories. `cat` any file to see exactly what happened.

**3. No Trust.** LLMs fill fields → code validates and may override. Reviewer misses a task? Code fills in default `pass`. LLM misjudges? Code override corrects it.

**4. Local-First.** Everything runs locally. Orchestration, memory, and state stay on your machine.

---

## Requirements

- **Hermes Agent** — [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)
- **Python 3.12+**
- **API key** in `~/.hermes/.env` (DeepSeek / OpenAI / Anthropic / OpenRouter)
- **Reasonix** (optional — LLM Coder auto-fallback)

---

## vs. The Competition

| Feature | HIVE | CrewAI | AutoGen | LangGraph |
|---------|:---:|:---:|:---:|:---:|
| **Constraint** | Code state machine | Prompt roles | Prompt negotiation | Graph + LLM routing |
| **LLM breaks flow?** | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes |
| **Crash recovery** | ✅ Checkpoint | ❌ | ❌ | ❌ |
| **Parallel execution** | ✅ ThreadPool | ❌ sequential | ✅ conversation | ✅ graph |
| **Auditability** | Every action = file | Logs | Logs | Traces |
| **Memory** | 3-domain ChromaDB | Single vector DB | History | Checkpoints |
| **Skill evolution** | ✅ Auto-extract | ❌ | ❌ | ❌ |
| **Hermes native** | ✅ Plugin | ❌ | ❌ | ❌ |
| **Install size** | <300KB | pip + deps | pip + deps | pip + deps |

---

## FAQ

**Q: Do I need to know multi-agent systems?**
No. Type `hive build "your idea"` and watch.

**Q: What if the LLM makes a mistake?**
Reviewer catches it. Minor → retry. Fatal → replan. Code override prevents LLM misjudgments from derailing builds.

**Q: Can I use OpenAI instead of DeepSeek?**
Yes. HIVE reads Hermes's provider config. Set provider in profile configs.

**Q: What if my computer crashes mid-build?**
`hive resume` picks up from the last checkpoint.

**Q: Is this just a fancy prompt chain?**
No. The orchestrator is a Python state machine. LLMs are called at 4 specific points. Everything between is deterministic code.

**Q: Do I need Hermes?**
Yes — HIVE is a Hermes plugin. It uses Hermes's AIAgent engine and provider management.

---

<p align="center">
  <sub>Built for the Hermes ecosystem. v2.0.2</sub>
</p>
