Metadata-Version: 2.4
Name: harombe
Version: 0.3.1
Summary: Full-stack agent framework — voice, memory, tools, security — runs on your hardware, no cloud required
Project-URL: Homepage, https://github.com/smallthinkingmachines/harombe
Project-URL: Documentation, https://github.com/smallthinkingmachines/harombe#readme
Project-URL: Repository, https://github.com/smallthinkingmachines/harombe
Project-URL: Issues, https://github.com/smallthinkingmachines/harombe/issues
Author: harombe contributors
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,container-isolation,framework,mcp,ollama,rag,security,self-hosted,voice
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.11
Requires-Dist: chromadb<1.0,>=0.4
Requires-Dist: cryptography<45.0,>=41.0
Requires-Dist: dnspython<3.0,>=2.4
Requires-Dist: docker<8.0,>=7.0
Requires-Dist: duckduckgo-search<8.0,>=6.0
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: faster-whisper<2.0,>=1.0
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: joblib<2.0,>=1.3
Requires-Dist: mcp<2.0,>=1.2
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: openai<3.0,>=1.40
Requires-Dist: piper-tts<2.0,>=1.2
Requires-Dist: playwright<2.0,>=1.40
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: pynput<2.0,>=1.7
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich<14.0,>=13.7
Requires-Dist: scikit-learn<2.0,>=1.3
Requires-Dist: scipy<2.0,>=1.11
Requires-Dist: sentence-transformers<4.0,>=2.2
Requires-Dist: sounddevice<1.0,>=0.4
Requires-Dist: sse-starlette<3.0,>=2.0
Requires-Dist: typer[all]<1.0,>=0.12
Requires-Dist: uvicorn[standard]<1.0,>=0.30
Requires-Dist: zeroconf>=0.132
Provides-Extra: coqui
Requires-Dist: tts>=0.22; (python_version < '3.11') and extra == 'coqui'
Provides-Extra: dev
Requires-Dist: detect-secrets>=1.4; extra == 'dev'
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs-mermaid2-plugin>=1.1; extra == 'dev'
Requires-Dist: mkdocs>=1.5; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docker
Requires-Dist: docker>=7.0; extra == 'docker'
Provides-Extra: docs
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs-mermaid2-plugin>=1.1; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Description-Content-Type: text/markdown

# harombe

**The full-stack agent framework that runs entirely on your hardware.**

> Manages the complete agent lifecycle — tool execution in containers, network-level security, voice I/O, persistent memory with semantic search, and multi-node cluster routing. No cloud required.

[![CI](https://github.com/smallthinkingmachines/harombe/actions/workflows/ci.yml/badge.svg)](https://github.com/smallthinkingmachines/harombe/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

## Quick Start

```bash
pip install harombe
harombe init          # detects hardware, writes config
ollama pull qwen2.5:7b
harombe chat          # autonomous agent with tools
```

Or use it as a library:

```python
import asyncio
from harombe.agent.loop import Agent
from harombe.llm.ollama import OllamaClient
from harombe.tools.registry import get_enabled_tools

async def main():
    llm = OllamaClient(model="qwen2.5:7b")
    tools = get_enabled_tools(shell=True, filesystem=True, web_search=True)
    agent = Agent(llm=llm, tools=tools, system_prompt="You are a helpful assistant.")
    response = await agent.run("Find all Python files in src/ and count them.")
    print(response)

asyncio.run(main())
```

See [`examples/`](examples/) for more.

## What is harombe?

Harombe manages the full stack for AI agents — hardware detection, tool execution (in containers), security (network-level), I/O (voice + CLI + API), memory (SQLite + vector search), and networking (multi-node clusters with service discovery). Think of it as an operating system for AI agents — as a `pip install`.

### Security

Harombe's security is infrastructure-level, not bolt-on:

- Every tool runs in its own Docker container with resource limits
- Per-container network egress filtering (iptables, DNS allowlists)
- Audit logging with automatic credential redaction
- Human-in-the-loop approval gates with risk classification
- Secret management via Vault/SOPS
- ZKP-based audit proofs (experimental)

### What harombe manages

| Responsibility    | What it does                                                                         |
| ----------------- | ------------------------------------------------------------------------------------ |
| **Execution**     | ReAct agent loop, tool calling (shell, filesystem, web search, browser, code exec)   |
| **Voice I/O**     | Whisper STT + Piper TTS, push-to-talk, VAD, WebSocket streaming                      |
| **Memory**        | SQLite conversations, ChromaDB vectors, cross-session semantic search                |
| **Security**      | Container isolation, network filtering, audit logging, HITL gates, anomaly detection |
| **Networking**    | Multi-node clusters, mDNS discovery, complexity-based routing, circuit breakers      |
| **Privacy**       | PII detection, data sanitization, local/hybrid/cloud routing modes                   |
| **Extensibility** | MCP server + client, container-isolated plugins with auto-generated MCP scaffolds    |

## Architecture

```
┌─────────────────────────────────────┐
│  Layer 6: Clients                   │  Voice, iOS, Web, CLI
├─────────────────────────────────────┤
│  Layer 5: Privacy Router            │  Hybrid local/cloud AI
│  PII detection, context sanitizer   │  local-only / hybrid / cloud
├─────────────────────────────────────┤
│  Layer 4: Agent & Memory            │  ReAct loop, tools, memory
├─────────────────────────────────────┤
│  Layer 3: Security                  │  Defense-in-depth
│  MCP Gateway, container isolation   │  Credential vault, audit log
│  Per-tool egress, secret scanning   │  HITL gates, browser pre-auth
├─────────────────────────────────────┤
│  Layer 2: Orchestration             │  Smart routing, health monitoring
│  Cluster config, mDNS discovery     │  Circuit breakers, metrics
├─────────────────────────────────────┤
│  Layer 1: Runtimes                  │  llama.cpp, Whisper, TTS, embeddings
└─────────────────────────────────────┘
```

Each layer only talks to its neighbors. Security (Layer 3) wraps every tool invocation — there is no path from the agent to a tool that bypasses the gateway. See [ARCHITECTURE.md](ARCHITECTURE.md) for full design documentation.

## Security Deep Dive

Harombe enforces the **Capability-Container Pattern**: agents never execute tools directly. Every tool call goes through the MCP Gateway, which routes it to an isolated Docker container.

```
Agent  ──→  MCP Gateway  ──→  [ Container: shell ]
                          ──→  [ Container: browser ]
                          ──→  [ Container: web_search ]
```

**Container Isolation** — Each tool runs in its own Docker container with CPU/memory limits, read-only filesystem mounts, and no host network access.

**Network Egress** — Per-container iptables rules and DNS allowlists. A web_search container can reach DuckDuckGo; a filesystem container can reach nothing.

**Audit Logging** — Every tool call, approval decision, and security event is logged to SQLite with automatic redaction of API keys, passwords, and tokens.

**HITL Gates** — Operations are risk-classified (LOW/MEDIUM/HIGH/CRITICAL). High-risk operations require explicit human approval with default-deny on timeout.

**Anomaly Detection** — Per-agent Isolation Forest models learn baseline behavior and flag deviations. Integrated with SIEM (Splunk, Elasticsearch, Datadog).

See [docs/security-quickstart.md](docs/security-quickstart.md) for setup instructions.

## Features

### Agent Core

ReAct agent loop with autonomous planning, tool calling, and multi-step execution. Tools: shell, read/write files, web search, browser automation. Configurable step limits and confirmation gates.

### Voice

Whisper STT (tiny to large-v3) + Piper TTS. Push-to-talk CLI (`harombe voice`), REST + WebSocket API, voice activity detection. Cross-platform audio I/O.

### Memory & RAG

SQLite conversation persistence with token-based context windowing. ChromaDB vector store with sentence-transformers embeddings (local, no API calls). Semantic search across sessions. RAG-enabled agents auto-inject relevant context.

### Distributed Clusters

Define nodes in YAML, route queries by complexity. mDNS auto-discovery, health monitoring, circuit breakers, load balancing. Works with any hardware mix: Apple Silicon, NVIDIA, AMD, CPU.

### MCP Protocol

JSON-RPC 2.0 MCP server and client. Gateway-mediated tool execution with per-tool container isolation. Compatible with the broader MCP ecosystem.

### Plugins

Container-isolated plugins with auto-generated MCP scaffolds. ZKP audit proofs, compliance reporting, and container-based extensions ship as built-in plugins. See [`src/harombe/plugins/`](src/harombe/plugins/) for examples.

### Privacy

PII detection and data sanitization. Three routing modes: local-only (nothing leaves your machine), hybrid (sensitive data stays local, general queries can use cloud), and cloud. Configurable per-agent.

## Examples

| #   | Example                                                        | Description                                |
| --- | -------------------------------------------------------------- | ------------------------------------------ |
| 01  | [`simple_agent.py`](examples/01_simple_agent.py)               | Basic single-node agent with all tools     |
| 02  | [`api_usage.py`](examples/02_api_usage.py)                     | Programmatic agent creation and tool usage |
| 03  | [`data_pipeline.py`](examples/03_data_pipeline.py)             | Data processing with autonomous agents     |
| 04  | [`code_review.py`](examples/04_code_review.py)                 | Automated code review workflows            |
| 05  | [`research_agent.py`](examples/05_research_agent.py)           | Research automation with web search        |
| 06  | [`memory_conversation.py`](examples/06_memory_conversation.py) | Persistent conversation history            |
| 07  | [`cluster_routing.py`](examples/07_cluster_routing.py)         | Task-based routing across nodes            |
| 08  | [`semantic_memory.py`](examples/08_semantic_memory.py)         | Semantic search and RAG                    |
| 09  | [`voice_assistant.py`](examples/09_voice_assistant.py)         | Voice-enabled assistant (STT + TTS)        |

## Configuration

Configuration lives at `~/.harombe/harombe.yaml`. Minimal example:

```yaml
model:
  name: qwen2.5:7b
  temperature: 0.7

tools:
  shell: true
  filesystem: true
  web_search: true
  confirm_dangerous: true

memory:
  enabled: true
  storage_path: ~/.harombe/memory.db
```

All fields have sensible defaults — you can run with no config at all. See [`harombe.yaml.example`](harombe.yaml.example) for the full reference.

## Status

| Production                        | Experimental              | Planned            |
| --------------------------------- | ------------------------- | ------------------ |
| ReAct agent loop                  | Hardware security modules | iOS/Web clients    |
| Tool execution (shell, fs, web)   | Distributed cryptography  | Multi-modal vision |
| Container isolation + egress      |                           |                    |
| Code execution sandbox            |                           |                    |
| ZKP audit proofs                  |                           |                    |
| Audit logging + secret management |                           |                    |
| HITL approval gates               |                           |                    |
| Conversation memory + RAG         |                           |                    |
| Voice (STT + TTS)                 |                           |                    |
| Multi-node clusters               |                           |                    |
| MCP server + client               |                           |                    |
| Privacy router + PII detection    |                           |                    |
| Anomaly detection + SIEM          |                           |                    |

2400+ tests. Python 3.11-3.13. CI on Ubuntu + macOS. See [docs/roadmap.md](docs/roadmap.md) for full phase history.

## Development

```bash
git clone https://github.com/smallthinkingmachines/harombe.git
cd harombe && pip install -e ".[dev]"
pytest
```

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed setup and [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for contribution guidelines.

## License

Apache 2.0 — see [LICENSE](LICENSE).
