Metadata-Version: 2.4
Name: simplicio-runtime
Version: 3.5.5
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Rust
Classifier: Environment :: Console
License-File: LICENSE
Summary: Native orchestration runtime for the full Simplicio ecosystem (distributed as a compiled binary).
Keywords: simplicio,runtime,agents,local-llm,orchestration
Author: Wesley Simplicio
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/wesleysimplicio/simplicio-runtime

# Simplicio

> Local-first AI coding agent and runtime that cuts up to 96% of the tokens per
> task. Single compiled binary, zero runtime dependencies.

🇧🇷 Versão em português: [README.pt-BR.md](README.pt-BR.md) ·
Official site: [simpleti.com.br/simplicio/#start](https://simpleti.com.br/simplicio/#start)

---

## Install in one line

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/simplicio/main/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://raw.githubusercontent.com/wesleysimplicio/simplicio/main/install.ps1 | iex"
```

Then verify and start:

```bash
simplicio version
simplicio ecosystem doctor --repo . --json   # is the ecosystem contract healthy? (#2950)
simplicio chat --repo .
```

Full instructions for every platform (macOS, Linux, Windows, Docker, source) are
in **[INSTALL.md](INSTALL.md)**. For the whole-ecosystem picture (what
`simplicio-mapper`/`simplicio-dev-cli`/`simplicio-loop` are and how they relate
to this runtime), see **[docs/SIMPLICIO_STACK.md](docs/SIMPLICIO_STACK.md)**.

---

## Use it as an MCP server (plug it under any LLM host)

Simplicio runs as an **MCP server** that Claude Code, Gemini CLI, Codex, Cursor,
VS Code, Zed, and more plug under — giving your assistant a governed, token-saving
substrate instead of raw file access.

```bash
bash scripts/install-mcp.sh      # installs `simplicio`, registers the server, smoke-tests it
simplicio serve --mcp --stdio    # or run the server manually
```

Your assistant gets **10 deterministic tools**: `simplicio_map` (orient) ·
`simplicio_memory` (FTS + vector recall) · `simplicio_edit` (sandboxed mechanical
edit) · `simplicio_gate` (risk classify) · `simplicio_validate` · `simplicio_run`
(gate → bridge → evidence) · `simplicio_symbol` (def + callers in one) ·
`simplicio_search` · `simplicio_read` (signature-level) · `simplicio_exec` (the full
CLI, gated). The neural memory loads on first run and is **always available**; an
update refreshes the core skills without touching what you've captured.

> One runtime dependency for the memory layer: **`sqlite3`** (`apt-get install
> sqlite3` / `brew install sqlite`). The lean build needs **no C/C++ toolchain**.

Full guide: **[INSTALL_MCP.md](INSTALL_MCP.md)**.

---

## Docker — quick start

```bash
# Official image (multi-arch: amd64 + arm64)
docker pull ghcr.io/wesleysimplicio/simplicio:latest

# Deterministic command (no model, no network):
docker run --rm \
  -v "$HOME/.simplicio:/home/simplicio/.simplicio" \
  -v "$PWD:/work" -w /work \
  ghcr.io/wesleysimplicio/simplicio:latest map --repo . --json

# Or via compose (gateway, agent, tui):
cp .env.docker.example .env
docker compose run --rm agent validate --repo .
```

Build, profiles, and publishing details: [`docs/PACKAGING.md`](docs/PACKAGING.md).

---

## What it is

Simplicio is a terminal-based AI coding agent and runtime. The frontier LLM
orients and reviews; Simplicio supplies the cheap, deterministic muscle —
repo mapping, neural memory recall, zero-token mechanical edits, action gating,
quality gates, and tamper-evident evidence — so each task costs a fraction of the
tokens it otherwise would.

- **Chat REPL** — conversational assistant over your repo
- **Agent mode** — multi-turn task execution with a sub-agent fabric
- **Neural memory** — SQLite/FTS5 recall (optional vector ANN) instead of
  re-reading files
- **Deterministic editing** — mechanical edits with zero LLM tokens
- **Delivery gates** — definition-of-done, certification, regression checks
- **Deterministic Runtime** — filesystem, evidence, gates, and MCP effects;
  provider/model execution remains owned by Simplicio Agent/Loop for now

The task surface is `simplicio-runtime`; the task discipline is inherited from
the proven `simplicio-loop` flow. In practice that means `simplicio run`,
`simplicio serve --mcp --stdio`, and assistant adapters reuse the same
evidence-gated converge/drain model, durable run journal, and worker
coordination pattern instead of inventing a second execution contract.

---

## Inference ownership (current release)

The Runtime is shipped in `deterministic-only` mode. It does not start a local
LLM, DeepSeek, OpenRouter, or any other provider, even when a model file,
llama.cpp binary, or provider environment variable is present. This keeps the
Code → Agent → Loop → Runtime boundary explicit and fail-closed.

The future local backend remains prepared behind the optional
`in-process-llm` feature and the explicit `SIMPLICIO_RUNTIME_INFERENCE=local-experimental`
mode. That mode is not enabled by default and is not part of the current
release contract.

Use an Agent/Loop provider outside the Runtime when inference is needed.

## Loop-stack economy benchmark (honest)

How **simplicio-loop** (with **Fast inside STRICT**), **Agent MCP**, and host baseline trade tokens vs wall clock — measured across five agent issues (#9 → #711), five lanes.

**PDF (pizza charts · bar charts · barramento diagram · full interpretation):**  
**[docs/evidence/loop_stack_economy_benchmark_report.pdf](docs/evidence/loop_stack_economy_benchmark_report.pdf)**

**Raw metrics:** [docs/evidence/multi_issue_lanes_metrics.json](docs/evidence/multi_issue_lanes_metrics.json)

| Lane | Mean est. token savings vs host baseline | Wall (mean) | Role |
|---|---:|---:|---|
| **loop** (mapper + Fast) | ~39% (up to ~83% on large baselines) | ~50 s cold | Production STRICT path |
| **loop + Agent MCP** | ~38% | ~53 s | Bus/tools — not the main compressor |
| **loop without Fast** | ~64% | ~18 s | Diagnostic only — less work |
| **mcp_only** | ~99%\* | ~11 s | Metadata only — not a survey |

\*High % without survey work is **not** a product win. **Runtime MCP** (`simplicio serve --mcp`) is the host tool surface; **Agent MCP** is a separate bus. Both are **optional** for the loop core (mapper + dev-cli; Fast when operational). Runtime is **not** mandatory for simplicio-loop.

Also mirrored in [simplicio-loop](https://github.com/wesleysimplicio/simplicio-loop/blob/main/docs/evidence/loop_stack_economy_benchmark_report.pdf).

## Documentation

| Doc | Purpose |
|---|---|
| [docs/SUPER_RUNTIME.md](docs/SUPER_RUNTIME.md) | **North star** — the Simplicio Super Runtime product boundary, design pillars, and token economy |
| [docs/evidence/loop_stack_economy_benchmark_report.pdf](docs/evidence/loop_stack_economy_benchmark_report.pdf) | Measured loop/MCP/Fast economy report (charts + interpretation) |
| [INSTALL.md](INSTALL.md) | Install on any platform |
| [docs/SIMPLICIO_STACK.md](docs/SIMPLICIO_STACK.md) | The whole ecosystem on one page — every repo's role, naming/alias policy, recommended path (`simplicio ecosystem doctor`), what it's not, migration notes |
| [docs/QUICKSTART.md](docs/QUICKSTART.md) | First agent in 5 minutes |
| [docs/UPGRADE.md](docs/UPGRADE.md) | Upgrade paths for every method |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common errors and fixes |
| [docs/CAPABILITY_CURATION.md](docs/CAPABILITY_CURATION.md) | What to own, call, promote, or avoid — capability curation + dedup policy (issue #35) |
| [BUILDING.md](BUILDING.md) | Build from source (developers) |

---

## Quick taste

```bash
# Map your repo to save tokens before reasoning
simplicio map --repo . --for-llm markdown

# Recall prior decisions instead of re-deriving them
simplicio memory "how does auth work" --repo . --json

# Run a governed task through the runtime-first task flow
simplicio run "fix the failing test" --repo . --evidence --json

# Standalone loop surface for the same evidence-gated task discipline
simplicio coding-loop "fix the failing test" --repo . --max-cycles 5

# Quality gate before declaring done
simplicio deliver certify --repo . --json
```

Run `simplicio --help` for the full command list.


## Asolaria Subsystem (JesseBrown1980 integration)

The `src/asolaria/` module ports the highest-value patterns from JesseBrown1980's
Asolaria ecosystem into the Simplicio Runtime. Restored 2026-07-08 (ADR-2026-07-08-ASOLARIA-RESTORATION)
and actively integrated 2026-07-09 (ADR-2026-07-09-ASOLARIA-INTEGRATION-SPRINT).

**Wired and exercised (real code, tests passing):**
- `nest_prime.rs` — N-Nest self-reflective agent nesting
- `consolidator.rs` — observation consolidation (decay/cluster passes)
- `tiered_memory.rs` — tiered memory store
- `fedenv.rs` / `hookwall.rs` — Federation-1024 policy + syscall-table stubs
- `agent_state.rs` — agent state persistence (SQLite)
- `sealed_receipt.rs` / `cosign_chain` → `src/hbp/` shared ledger (sha256 hash-chain)
- `wormhole_command.rs` — holographic wormhole codec transport
- `prism_bridge.rs` / `wormhole_bridge.rs` — re-exports of `dbbh-prism` / `wormhole-codec` crates

**Ports in progress (see ADR-2026-07-09):**
- `asolaria-hbi-hbp` `verify_chain` → `sealed_receipt.rs` integrity
- `ai-memory` consolidation → `consolidator.rs`
- `asolaria-federation-1024` council/lanes → `fedenv.rs`
- `hbp::HbpInbox::append` advisory lock (race fix — DONE)

Source repos cloned under `../jesse-imports/` for port reference.

