Metadata-Version: 2.4
Name: simplicio-agent
Version: 0.25.0
Summary: The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere
Author: Nous Research
License-Expression: MIT
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai==2.24.0
Requires-Dist: certifi==2026.5.20
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: fire==0.7.1
Requires-Dist: httpx[socks]==0.28.1
Requires-Dist: rich==14.3.3
Requires-Dist: tenacity==9.1.4
Requires-Dist: pyyaml==6.0.3
Requires-Dist: ruamel.yaml==0.18.17
Requires-Dist: requests==2.33.0
Requires-Dist: jinja2==3.1.6
Requires-Dist: pydantic==2.13.4
Requires-Dist: prompt_toolkit==3.0.52
Requires-Dist: croniter==6.0.0
Requires-Dist: packaging==26.0
Requires-Dist: Markdown==3.10.2
Requires-Dist: PyJWT[crypto]==2.13.0
Requires-Dist: urllib3<3,>=2.7.0
Requires-Dist: cryptography==46.0.7
Requires-Dist: tzdata==2025.3; sys_platform == "win32"
Requires-Dist: psutil==7.2.2
Requires-Dist: websockets==15.0.1
Requires-Dist: pathspec==1.1.1
Requires-Dist: fastapi<1,>=0.104.0
Requires-Dist: uvicorn[standard]<1,>=0.24.0
Requires-Dist: python-multipart<1,>=0.0.9
Requires-Dist: ptyprocess<1,>=0.7.0; sys_platform != "win32"
Requires-Dist: pywinpty<3,>=2.0.0; sys_platform == "win32"
Requires-Dist: Pillow==12.2.0
Requires-Dist: concurrent-log-handler==0.9.29; sys_platform == "win32"
Provides-Extra: anthropic
Requires-Dist: anthropic==0.87.0; extra == "anthropic"
Provides-Extra: exa
Requires-Dist: exa-py==2.10.2; extra == "exa"
Provides-Extra: firecrawl
Requires-Dist: firecrawl-py==4.17.0; extra == "firecrawl"
Provides-Extra: parallel-web
Requires-Dist: parallel-web==0.4.2; extra == "parallel-web"
Provides-Extra: fal
Requires-Dist: fal-client==0.13.1; extra == "fal"
Provides-Extra: edge-tts
Requires-Dist: edge-tts==7.2.7; extra == "edge-tts"
Provides-Extra: modal
Requires-Dist: modal==1.3.4; extra == "modal"
Provides-Extra: daytona
Requires-Dist: daytona==0.155.0; extra == "daytona"
Provides-Extra: hindsight
Requires-Dist: hindsight-client==0.6.1; extra == "hindsight"
Provides-Extra: dev
Requires-Dist: debugpy==1.8.20; extra == "dev"
Requires-Dist: pytest==9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: pytest-xdist==3.6.1; extra == "dev"
Requires-Dist: mcp==1.26.0; extra == "dev"
Requires-Dist: starlette==1.0.1; extra == "dev"
Requires-Dist: ty==0.0.21; extra == "dev"
Requires-Dist: ruff==0.15.10; extra == "dev"
Requires-Dist: setuptools==81.0.0; extra == "dev"
Requires-Dist: maturin<2.0,>=1.0; extra == "dev"
Provides-Extra: fast
Requires-Dist: orjson<4,>=3.11; extra == "fast"
Requires-Dist: msgspec<0.23,>=0.21; extra == "fast"
Requires-Dist: uvloop<0.24,>=0.22; sys_platform != "win32" and extra == "fast"
Provides-Extra: perf
Requires-Dist: orjson<4,>=3.11; extra == "perf"
Requires-Dist: msgspec<0.23,>=0.21; extra == "perf"
Requires-Dist: uvloop<0.24,>=0.22; sys_platform != "win32" and extra == "perf"
Provides-Extra: messaging
Requires-Dist: python-telegram-bot[webhooks]==22.6; extra == "messaging"
Requires-Dist: discord.py[voice]==2.7.1; extra == "messaging"
Requires-Dist: aiohttp==3.14.1; extra == "messaging"
Requires-Dist: brotlicffi==1.2.0.1; extra == "messaging"
Requires-Dist: slack-bolt==1.29.0; extra == "messaging"
Requires-Dist: slack-sdk==3.43.0; extra == "messaging"
Requires-Dist: qrcode==7.4.2; extra == "messaging"
Provides-Extra: cron
Provides-Extra: slack
Requires-Dist: slack-bolt==1.29.0; extra == "slack"
Requires-Dist: slack-sdk==3.43.0; extra == "slack"
Requires-Dist: aiohttp==3.14.1; extra == "slack"
Provides-Extra: matrix
Requires-Dist: mautrix[encryption]==0.21.0; extra == "matrix"
Requires-Dist: aiosqlite==0.22.1; extra == "matrix"
Requires-Dist: asyncpg==0.31.0; extra == "matrix"
Requires-Dist: aiohttp-socks==0.11.0; extra == "matrix"
Requires-Dist: aiohttp==3.14.1; extra == "matrix"
Provides-Extra: wecom
Requires-Dist: defusedxml==0.7.1; extra == "wecom"
Provides-Extra: cli
Requires-Dist: simple-term-menu==1.6.6; extra == "cli"
Provides-Extra: tts-premium
Requires-Dist: elevenlabs==1.59.0; extra == "tts-premium"
Provides-Extra: voice
Requires-Dist: faster-whisper==1.2.1; extra == "voice"
Requires-Dist: sounddevice==0.5.5; extra == "voice"
Requires-Dist: numpy==2.4.3; extra == "voice"
Provides-Extra: pty
Provides-Extra: honcho
Requires-Dist: honcho-ai==2.0.1; extra == "honcho"
Provides-Extra: supermemory
Requires-Dist: supermemory==3.50.0; extra == "supermemory"
Provides-Extra: mem0
Requires-Dist: mem0ai==2.0.10; extra == "mem0"
Provides-Extra: vision
Provides-Extra: mcp
Requires-Dist: mcp==1.26.0; extra == "mcp"
Requires-Dist: starlette==1.0.1; extra == "mcp"
Provides-Extra: nemo-relay
Requires-Dist: nemo-relay<1.0,>=0.5; extra == "nemo-relay"
Provides-Extra: homeassistant
Requires-Dist: aiohttp==3.14.1; extra == "homeassistant"
Provides-Extra: sms
Requires-Dist: aiohttp==3.14.1; extra == "sms"
Provides-Extra: teams
Requires-Dist: microsoft-teams-apps==2.0.13.4; extra == "teams"
Requires-Dist: aiohttp==3.14.1; extra == "teams"
Provides-Extra: computer-use
Requires-Dist: mcp==1.26.0; extra == "computer-use"
Requires-Dist: starlette==1.0.1; extra == "computer-use"
Provides-Extra: acp
Requires-Dist: agent-client-protocol==0.9.0; extra == "acp"
Provides-Extra: mistral
Requires-Dist: mistralai==2.4.8; extra == "mistral"
Provides-Extra: bedrock
Requires-Dist: boto3==1.42.89; extra == "bedrock"
Provides-Extra: vertex
Requires-Dist: google-auth==2.55.1; extra == "vertex"
Provides-Extra: azure-identity
Requires-Dist: azure-identity==1.25.3; extra == "azure-identity"
Provides-Extra: termux
Requires-Dist: python-telegram-bot[webhooks]==22.6; extra == "termux"
Requires-Dist: simplicio-agent[cron]; extra == "termux"
Requires-Dist: simplicio-agent[cli]; extra == "termux"
Requires-Dist: simplicio-agent[pty]; extra == "termux"
Requires-Dist: simplicio-agent[mcp]; extra == "termux"
Requires-Dist: simplicio-agent[honcho]; extra == "termux"
Requires-Dist: simplicio-agent[acp]; extra == "termux"
Provides-Extra: termux-all
Requires-Dist: simplicio-agent[termux]; extra == "termux-all"
Requires-Dist: simplicio-agent[google]; extra == "termux-all"
Requires-Dist: simplicio-agent[homeassistant]; extra == "termux-all"
Requires-Dist: simplicio-agent[sms]; extra == "termux-all"
Requires-Dist: simplicio-agent[web]; extra == "termux-all"
Provides-Extra: dingtalk
Requires-Dist: dingtalk-stream==0.24.3; extra == "dingtalk"
Requires-Dist: alibabacloud-dingtalk==2.2.42; extra == "dingtalk"
Requires-Dist: qrcode==7.4.2; extra == "dingtalk"
Provides-Extra: feishu
Requires-Dist: lark-oapi==1.6.8; extra == "feishu"
Requires-Dist: qrcode==7.4.2; extra == "feishu"
Provides-Extra: google
Requires-Dist: google-api-python-client==2.194.0; extra == "google"
Requires-Dist: google-auth-oauthlib==1.3.1; extra == "google"
Requires-Dist: google-auth-httplib2==0.3.1; extra == "google"
Provides-Extra: youtube
Requires-Dist: youtube-transcript-api==1.2.4; extra == "youtube"
Provides-Extra: web
Requires-Dist: fastapi==0.133.1; extra == "web"
Requires-Dist: uvicorn[standard]==0.41.0; extra == "web"
Requires-Dist: starlette==1.0.1; extra == "web"
Requires-Dist: python-multipart==0.0.27; extra == "web"
Provides-Extra: all
Requires-Dist: simplicio-agent[cron]; extra == "all"
Requires-Dist: simplicio-agent[cli]; extra == "all"
Requires-Dist: simplicio-agent[pty]; extra == "all"
Requires-Dist: simplicio-agent[mcp]; extra == "all"
Requires-Dist: simplicio-agent[homeassistant]; extra == "all"
Requires-Dist: simplicio-agent[sms]; extra == "all"
Requires-Dist: simplicio-agent[acp]; extra == "all"
Requires-Dist: simplicio-agent[google]; extra == "all"
Requires-Dist: simplicio-agent[web]; extra == "all"
Requires-Dist: simplicio-agent[youtube]; extra == "all"
Requires-Dist: simplicio-agent[fast]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="assets/simplicio-agent-hero-2026.png" alt="Simplicio Agent — governed autonomous intelligence on your hardware" width="100%" />
</p>

<h1 align="center">Simplicio Agent</h1>

<p align="center"><strong>Hermes speed. Simplicio determinism. Verified delivery.</strong></p>

<p align="center">
  The local-first autonomous agent that reasons broadly, executes through a Rust control plane,<br>
  gates every consequential action, and proves the work before it says “done”.
</p>

<p align="center">
  <a href="https://github.com/wesleysimplicio/simplicio-agent/stargazers"><img src="https://img.shields.io/github/stars/wesleysimplicio/simplicio-agent?style=for-the-badge&logo=github&color=F5C451" alt="GitHub stars"></a>
  <a href="https://github.com/wesleysimplicio/simplicio-agent/releases"><img src="https://img.shields.io/github/v/release/wesleysimplicio/simplicio-agent?style=for-the-badge&color=7C3AED" alt="Latest release"></a>
  <a href="https://github.com/wesleysimplicio/simplicio-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-00B894?style=for-the-badge" alt="MIT license"></a>
  <a href="https://discord.gg/wM6tr7xVb"><img src="https://img.shields.io/badge/Discord-Join%20Simplicio-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Simplicio Discord"></a>
</p>

<p align="center">
  <a href="#why-simplicio">Why Simplicio</a> ·
  <a href="#simplicio-vs-official-hermes-agent">vs Hermes</a> ·
  <a href="#architecture">Architecture</a> ·
  <a href="#quick-install">Install</a> ·
  <a href="#star-history">Star History</a>
</p>

<p align="center">
  <strong>🌍 Languages</strong><br>
  <a href="README.md">🇬🇧 English</a> |
  <a href="READMEs/README.pt-BR.md">🇧🇷 Português</a> |
  <a href="READMEs/README.es-ES.md">🇪🇸 Español</a> |
  <a href="READMEs/README.fr-FR.md">🇫🇷 Français</a> |
  <a href="READMEs/README.de-DE.md">🇩🇪 Deutsch</a> |
  <a href="READMEs/README.it-IT.md">🇮🇹 Italiano</a> |
  <a href="READMEs/README.ja-JP.md">🇯🇵 日本語</a> |
  <a href="READMEs/README.ko-KR.md">🇰🇷 한국어</a> |
  <a href="READMEs/README.zh-CN.md">🇨🇳 简体中文</a> |
  <a href="READMEs/README.ru-RU.md">🇷🇺 Русский</a> |
  <a href="READMEs/README.pl-PL.md">🇵🇱 Polski</a> |
  <a href="READMEs/README.tr-TR.md">🇹🇷 Türkçe</a> |
  <a href="READMEs/README.nl-NL.md">🇳🇱 Nederlands</a> |
  <a href="READMEs/README.hi-IN.md">🇮🇳 हिन्दी</a> |
  <a href="READMEs/README.ar-SA.md">🇸🇦 العربية</a>
</p>

---

## Why Simplicio

Most agents optimize the conversation. Simplicio optimizes the **entire delivery path**.

| Pillar | What Simplicio adds | Why it matters |
|---|---|---|
| ⚡ **Speed** | Streaming, fast JSON/serde paths, lazy schemas, warm daemon, deterministic routing, token-aware working set | Less waiting and less context waste |
| 🛡️ **Determinism** | Compiled Rust runtime, action gate, mechanical edits, checkpoints and undo | The model proposes; the runtime controls effects |
| ✅ **Proof** | HBP evidence chain, watcher recomputation, receipts, progressive validation and delivery gates | “Done” becomes auditable evidence, not a sentence |
| 🧠 **Memory** | Project guardian, runtime guardian, durable attempts, skill memory and local retrieval | The agent reuses what worked and avoids oscillation |
| 🌐 **Reach** | CLI, MCP, desktop, messaging gateways, plugins, skills and model/provider freedom | One governed agent across the surfaces you already use |
| 🏠 **Ownership** | Local-first execution, local model ladder and user-owned state | Your machine, your data, your rules |

```mermaid
flowchart LR
    A["Intent"] --> B["Map + retrieve"]
    B --> C["Reason + plan"]
    C --> D{"Action gate"}
    D -->|authorized| E["Deterministic execution"]
    D -->|blocked| C
    E --> F["Validate"]
    F --> G{"Watcher recomputes"}
    G -->|mismatch| H["Checkpoint / correct"]
    H --> C
    G -->|verified| I["Receipt + delivery"]
```

## Hermes → Simplicio Agent

<p align="center">
  <img src="assets/hermes-to-simplicio-transformation.png" alt="Hermes evolving into Simplicio Agent" width="100%" />
</p>

Simplicio Agent is an independent, public fork of [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent). It keeps the upstream strengths—broad tools, provider choice, skills, messaging, learning and fast interaction—then evolves the execution model around the Simplicio Runtime.

This is **inheritance plus evolution**: Hermes remains the origin and receives attribution; Simplicio is the product identity, control plane and delivery contract.

```mermaid
flowchart LR
    H["Hermes Agent foundation<br/>tools · providers · skills · gateways"]
    T["Turbo layer<br/>streaming · hot paths · warm daemon · token economy"]
    R["Simplicio Runtime<br/>Rust gate · checkpoints · receipts · deterministic edit"]
    A["Simplicio Agent<br/>fast · governed · reversible · verifiable"]
    H --> T --> A
    R --> A
```

## Simplicio vs official Hermes Agent

Comparison snapshot: **15 July 2026**, against the public `main` branch of [official Hermes Agent](https://github.com/NousResearch/hermes-agent). “Simplicio advantage” means a capability present and documented in this repository; it does not imply that Hermes is weak or unsuitable for its own goals.

### Measured shared hot paths

Reproduce with `python3 scripts/benchmark_vs_upstream.py --upstream ../hermes-agent`. Methodology and limits are documented in [`docs/performance.md`](docs/performance.md).

| Shared probe | Simplicio Agent | Official Hermes | Measured gain |
|---|---:|---:|---:|
| JSON encode, tool result | 2.8 µs | 33.1 µs | **12.0×** |
| JSON decode, tool args | 0.6 µs | 1.8 µs | **3.1×** |
| Canonicalize tool args | 1.2 µs | 5.2 µs | **4.5×** |
| Token estimate, 200 messages | 634 µs | 677 µs | **1.07×** |
| CLI cold import | 66.4 ms | 117.6 ms | **1.77×** |

> These are focused microbenchmarks captured on Linux/Python 3.11, not a claim that every end-to-end task is 12× faster. Run the benchmark on your hardware.

### Difference-by-difference

| Area | Official Hermes Agent | Simplicio Agent advantage |
|---|---|---|
| Product core | Python agent runtime | Hermes-derived agent fused with the compiled Simplicio Rust control plane |
| Canonical CLI | `hermes` | `simplicio-agent`; `hermes` remains a deprecated compatibility alias |
| Effect control | Tool/runtime policies | Unified mutation classification and fail-closed action gate |
| Mechanical changes | Model/tool-written operations | Zero-token deterministic edit plans when the change is mechanical |
| Recovery | Task-specific retries | Checkpoints, undo paths and transaction-aware recovery |
| Completion | Agent decides it is finished | Evidence-gated loop plus independent watcher recomputation |
| Evidence | Logs and tool results | Typed receipts plus append-only HBP evidence lineage |
| Performance posture | General-purpose defaults | Fast installers enable serde, fast JSON and uvloop by default |
| JSON/serialization | Standard shared path | `orjson`/`msgspec` fast path with pure-Python fallback |
| Native hot paths | Python-first | Optional PyO3 hot path plus compiled Rust execution kernel |
| Startup | Standard CLI lifecycle | Lazy boot path plus optional warm daemon |
| Context economy | Compression and memory | Working-set LRU, cold references, TF-IDF scoring, token cache and prefetch |
| Tool output economy | Normal tool payloads | TOON boundary and token-saver compaction with telemetry |
| Routing | Model/tool routing | Deterministic no-LLM route first, then local/remote escalation ladder |
| Repository context | Agent reads tools/files | Runtime map + mapper + zero-copy orientation pack |
| Runtime knowledge | Loaded instructions | Helo guardian ranks runtime capabilities and mutation paths |
| Project knowledge | Conversation/project memory | Isa guardian ranks project docs, examples and local memory |
| External discovery | Web tools when selected | Levi is explicitly gated: external lookup only after local guardians miss |
| Parallel work | Subagents and tool concurrency | Governed fan-out, leases, worktree isolation, backpressure and receipts |
| Orchestration | Agent loop | Bounded `simplicio-loop` with converge/drain modes and anti-oscillation journal |
| Self-modification | General development workflow | Explicit self-mutation isolation, promotion and handoff contract |
| Validation | Tests selected by workflow | Progressive validation, watcher gate, DoD and delivery certificate surfaces |
| Observability | Logs, sessions and integrations | Stage timers, token savings, lane readiness, receipts and runtime status |
| Local execution | Supports local and remote models | Local-first decision ladder with governed shared inference pool |
| Contracts | Tool/API conventions | Versioned `simplicio.* /v1` envelopes across task, progress, effects and evidence |
| Safety at scale | Host/tool safeguards | CPU, disk, queue, timeout, iteration and “never explode” caps |
| Compatibility | Upstream ecosystem | Keeps upstream capabilities while migrating toward native Simplicio identity |

## Verified execution, not performative autonomy

<p align="center">
  <img src="assets/simplicio-verified-execution.png" alt="Simplicio verified and reversible execution pipeline" width="100%" />
</p>

Every consequential run follows a bounded path. Authorization is separated from possibility; evidence is part of execution; rollback is designed in rather than improvised afterward.

```mermaid
sequenceDiagram
    participant U as User
    participant A as Simplicio Agent
    participant R as Rust Runtime
    participant W as Watcher
    participant E as Evidence Ledger
    U->>A: Goal + constraints
    A->>R: Typed task and proposed effects
    R->>R: Gate + checkpoint
    R-->>A: Authorized receipts
    A->>R: Execute + validate
    R->>W: Claimed result
    W->>W: Recompute independently
    alt evidence matches
        W->>E: Append verified receipt
        E-->>U: Auditable delivery
    else mismatch
        W-->>A: Correct or roll back
    end
```

## Architecture

```mermaid
flowchart TB
    subgraph Interfaces["Interfaces"]
      CLI["CLI"]
      MCP["MCP"]
      MSG["Messaging"]
      DESK["Desktop / TUI"]
    end
    subgraph Agent["Simplicio Agent"]
      REASON["Reasoning + provider freedom"]
      SKILLS["Skills + plugins"]
      MEMORY["Isa · Helo · Levi"]
      LOOP["Evidence-gated loop"]
    end
    subgraph Runtime["Simplicio Runtime — Rust"]
      MAP["Map + contracts"]
      GATE["Action gate"]
      EDIT["Mechanical edit"]
      CHECK["Checkpoint / undo"]
      VERIFY["Validate + HBP receipts"]
    end
    Interfaces --> Agent
    REASON --> LOOP
    SKILLS --> LOOP
    MEMORY --> LOOP
    LOOP --> Runtime
    MAP --> GATE --> EDIT --> CHECK --> VERIFY
```

The narrow waist is intentional: the model reasons and coordinates; the runtime owns deterministic effects, evidence and recovery.

## Quick install

### macOS, Linux, WSL2 and Termux

```bash
curl -fsSL https://simpleti.com.br/simplicio/install.sh | sh
simplicio-agent setup
simplicio-agent doctor
```

### From source

```bash
git clone https://github.com/wesleysimplicio/simplicio-agent.git
cd simplicio-agent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[fast]"
simplicio-agent setup
```

The `hermes` command remains available temporarily for compatibility, but new automation should use `simplicio-agent`.

## Start here

```bash
# Interactive agent
simplicio-agent

# Diagnose the fast stack and Runtime binding
simplicio-agent doctor

# Inspect the Runtime's live capability contract
simplicio runtime map --for-llm markdown --repo .
```

Useful references:

- [`docs/SIMPLICIO_OPERATIONAL_MANUAL.md`](docs/SIMPLICIO_OPERATIONAL_MANUAL.md) — execution and safety model
- [`docs/performance.md`](docs/performance.md) — benchmark methods and reproducible numbers
- [`docs/SIMPLICIO_AGENT_CAPABILITY_CONTRACT.md`](docs/SIMPLICIO_AGENT_CAPABILITY_CONTRACT.md) — capability inventory
- [`docs/architecture/INDEX.md`](docs/architecture/INDEX.md) — architectural decisions
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution guide
- [`SECURITY.md`](SECURITY.md) — security policy

## Star History

<a href="https://star-history.com/#wesleysimplicio/simplicio-agent&Date">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-agent&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-agent&type=Date" />
    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-agent&type=Date" />
  </picture>
</a>

## Lineage, license and community

Simplicio Agent is licensed under the [MIT License](LICENSE) and derives from the excellent work of [Nous Research](https://nousresearch.com) and the [Hermes Agent contributors](https://github.com/NousResearch/hermes-agent/graphs/contributors). See the repository history and license notices for attribution.

- ⭐ Star this repository if verified, local-first autonomy is the direction you want.
- 💬 Join the [Simplicio Discord](https://discord.gg/wM6tr7xVb).
- 🐛 Open an [issue](https://github.com/wesleysimplicio/simplicio-agent/issues) with a reproducible case.
- 🔧 Send a focused PR with tests and evidence.

<p align="center"><strong>Simplicio Agent — possibility is cheap; action is gated; completion is proved.</strong></p>
