Metadata-Version: 2.4
Name: simplicio-runtime
Version: 0.1.0
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

<h1 align="center">simplicio-runtime</h1>

<p align="center">
  <strong>The native runtime that packages every Simplicio project plus local LLMs into one adaptive execution program.</strong><br />
  <em>Map, plan, execute, validate, collect evidence, and open PRs while spending fewer paid tokens.</em>
</p>

<p align="center">
<a href="https://github.com/wesleysimplicio/simplicio-runtime/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/wesleysimplicio/simplicio-runtime?style=flat-square" /></a>
<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-proprietary-red?style=flat-square" /></a>
<a href="docs/BENCHMARK_PLAN.md"><img alt="Benchmark plan" src="https://img.shields.io/badge/benchmark-with_vs_without_runtime-00b8a9?style=flat-square" /></a>
<a href="docs/INTEGRATIONS.md"><img alt="Integrations" src="https://img.shields.io/badge/integrates-Codex%20%7C%20Claude%20%7C%20VS%20Code%20%7C%20Copilot%20%7C%20Kiro%20%7C%20Cursor-blue?style=flat-square" /></a>
</p>

<p align="center">
<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.ja-JP.md">日本語</a> | <a href="READMEs/README.ko-KR.md">한국어</a> | <a href="READMEs/README.zh-CN.md">简体中文</a> | <a href="READMEs/README.it-IT.md">Italiano</a> | <a href="READMEs/README.fr-FR.md">Français</a> | <a href="READMEs/README.ru-RU.md">Русский</a> | <a href="READMEs/README.pl-PL.md">Polski</a> | <a href="READMEs/README.hi-IN.md">हिन्दी</a> | <a href="READMEs/README.ar-SA.md">العربية</a> | <a href="READMEs/README.he-IL.md">עברית</a> | <a href="READMEs/README.ms-MY.md">Bahasa Melayu</a> | <a href="READMEs/README.id-ID.md">Bahasa Indonesia</a>
</p>

<p align="center">
  <img src="assets/simplicio-runtime-hero-v4.png" alt="Simplicio Runtime architecture preview" width="920" />
</p>

---

## The Short Version

`simplicio-runtime` is the new native product layer for the full Simplicio ecosystem.

It coordinates:

- `simplicio-mapper`: repository context, endpoint inventory, screen inventory, symbols, call graph, docs.
- `simplicio-dev-cli`: focused code execution, diffs, tests, smoke checks, local LLM calls.
- `simplicio-prompt`: prompt contracts, subagent schemas, fan-out, consensus, context envelopes.
- `simplicio-sprint`: task graph, autonomous progress, evidence, PR handoff, Done state.
- Local LLM runtime: `llama.cpp`, managed GGUF files, shared model process, cache, backpressure.
- External assistants: Codex, Claude, GitHub Copilot, VS Code, Kiro, Cursor, and other work tools.

## Project DNA

The runtime is not just a launcher. It is the adaptive execution brain that decides which command to run, which context to load, which model to call, how many workers to schedule, and when to escalate.

The goal is simple: make local agents do the heavy mechanical work while premium LLMs spend their tokens only on planning, architecture, review, and hard decisions.

The north star is a local, native, fast, resource-aware super runtime for
programming and engineering tasks. It should solve as much as possible on the
machine itself, using local tools, local LLMs, governed agents, evidence, and
minimal remote-token spend.

## Real Gains

Simplicio Runtime is designed to turn a computer into a local engineering
execution environment.

- Install once, use everywhere: after global setup, compatible LLMs, IDEs, MCP
  clients, shell agents, and humans can call the same `simplicio` runtime.
- No-install terminal mode: the runtime must also work directly from a cloned
  repo, extracted release folder, or portable binary path without changing
  global machine configuration.
- Fewer paid tokens: mapper artifacts, cache, deterministic tools, and local
  LLMs handle the repetitive work before any premium model is needed.
- Faster repeated work: daemon mode can keep caches, model services, and agent
  state warm instead of restarting every task from zero.
- More local autonomy: agents can map, inspect, edit, test, validate, collect
  evidence, and prepare PR handoff on the machine itself.
- Adaptive agents: the runtime can run as many agents/subagents as the machine
  can safely handle, then throttle, kill, reuse, or replace them to keep the
  computer responsive.
- Better context discipline: skills and tools are indexed broadly but loaded
  narrowly, so each step receives only the context it needs.
- Better programming quality: curated packs cover repo intelligence, debugging,
  TDD, browser evidence, code review, source control, docs/research, release
  ops, agent ops, and token economy.
- Works with the real task sources: GitHub, Jira, Azure DevOps, local sprint
  files, and direct CLI task text can all feed the same execution brain.
- Evidence-first delivery: logs, tests, screenshots, traces, reports, commits,
  and PR summaries become first-class artifacts.
- Local-first privacy: code and data stay local by default; remote LLMs become
  explicit escalation paths for planning, architecture, and high-risk review.
- Reasoning router: local LLMs are the default, but the runtime can call Codex,
  Claude, or other CLI/model backends when better reasoning, review, or answer
  quality is worth the cost.
- Clear live progress: the runtime should explain what it is doing now, such as
  mapping the project, analyzing the task, validating changes, or waiting on a
  model worker.
- Cross-platform path: macOS, Linux, and Windows releases all target the same
  runtime contract.
- Release-aware updates: the runtime should detect new GitHub releases, verify
  checksums/signatures, update safely, restart services when needed, and keep
  rollback available.

## Visual Flow: Explanation Image

<p align="center">
  <img src="assets/simplicio-runtime-flow-hero.png" alt="Simplicio Runtime visual execution flow" width="920" />
</p>

This is the second README image: the top image presents the product vision,
and this explanation image shows how the runtime works during a real task.

The editable diagram source also lives in
[`assets/simplicio-runtime-flow.svg`](assets/simplicio-runtime-flow.svg).

The intended flow:

1. Install once and register `simplicio` through PATH, MCP, local HTTP, stdio,
   and optional daemon mode.
2. Connect work sources such as GitHub, Jira, Azure DevOps, local sprint files,
   or direct CLI task text.
3. Map the repository before asking any LLM for broad context.
4. Let the decision engine choose deterministic tools, local LLMs, local agents,
   or remote escalation.
5. Run local agents under adaptive capacity control so the task moves fast
   without making the machine slow.
6. Validate with targeted checks first, then widen to build, tests, lint,
   Playwright, or deployment smoke when needed.
7. Collect evidence: logs, screenshots, traces, reports, token ledger, and
   final status.
8. Hand off cleanly with commit, push, PR summary, or a shareable evidence
   bundle.
9. Detect new releases and update safely with checksum, signature, backup, and
   rollback.

## Natural-Language Sprint Flow

The user should be able to talk to the runtime directly:

```bash
simplicio chat "faça todas as tasks da sprint https://jira.example/browse/MM-42; o repositório é /work/maturity-matrix" --local
```

Target behavior:

1. Detect the sprint/task source from the link: Jira, Azure DevOps, GitHub, or
   local sprint file.
2. Authenticate through the configured adapter.
3. Read tasks, comments, acceptance criteria, attachments, branches, labels, and
   dependencies.
4. Map the repository before planning.
5. Build the task graph and execution order.
6. Select capability packs and skills per task.
7. Execute with local agents under adaptive capacity control.
8. Validate every task with relevant tests, build, lint, API smoke, or
   Playwright evidence.
9. Commit, push, and open PRs when policy allows.
10. Update the source system and produce a final evidence report.

## Quick Start

No global install is required for development or portable use:

```bash
git clone https://github.com/wesleysimplicio/simplicio-runtime.git
cd simplicio-runtime

# No global install required:
cargo run -- doctor --repo .
cargo run -- plan "fix backend API endpoint CORS" --repo . --json

# The binary is named "simplicio".
cargo build --release
./target/release/simplicio doctor
./target/release/simplicio map --repo ../simplicio-dev-cli
./target/release/simplicio run --repo ../my-project --agents 20 --local --evidence
./target/release/simplicio sprint --repo ../my-project --agents 100 --local --evidence
```

You can also run it straight through Cargo while hacking on the runtime:

```bash
cargo run -- doctor --repo .
cargo run -- run "map this project and explain the next task" --repo . --local --evidence
```

Global installation is optional. Source mode, built binary mode, and portable
release folders must work without mutating PATH or assistant configs.

Naming and compatibility policy: [docs/NAMING_AND_COMPATIBILITY.md](docs/NAMING_AND_COMPATIBILITY.md).
Compatibility matrix: [docs/COMPATIBILITY_MATRIX.md](docs/COMPATIBILITY_MATRIX.md).
Command runner failure shape: [docs/COMMAND_RUNNER.md](docs/COMMAND_RUNNER.md).

## Intended Install Experience

The release installer will target macOS, Windows, and Linux:

```bash
# Future release shape
simplicio doctor --repair
simplicio run "integrate front with api" --repo . --agents 20 --local --evidence
simplicio sprint ./sprint-01 --repo . --agents 100 --pr --watch
```

Global installation is a convenience path, not a requirement. Every core
command should remain runnable from `./target/release/simplicio`, `cargo run --`,
or a portable extracted release folder.

## What It Decides

For every task, the runtime should choose the cheapest safe path:

- no LLM when deterministic tools are enough;
- local LLM for classification, summarization, simple edits, and first-pass review;
- remote LLM only for planning, architecture, escalation, or final review;
- narrow validation first, wider validation before closing;
- parallel reads/checks where safe, serialized writes where necessary;
- mapper cache reuse before broad context loading;
- model backpressure so `--agents 100` means 100 logical work slots, not 100 loaded GGUF models.
- agent lifecycle control: reuse warm agents when cheaper, kill idle or stuck agents, and create replacements only when the queue/resource balance justifies it.

## Why This Saves Tokens

Without the runtime, every assistant tends to rediscover the repository, ask for too much context, rerun repeated prompts, and make broad calls to paid models.

With the runtime:

- mapper artifacts become the first context layer;
- context envelopes are scoped to the next action;
- prompt/model outputs are cached by content hash;
- repeated agent prompts are deduplicated;
- local LLM handles low-risk mechanical work;
- paid LLMs supervise, review, and solve the hard parts.

## Local LLMs And Skills

The runtime can use local LLMs for more than code generation:

- communicate progress in the user's language;
- summarize what just happened;
- translate or normalize task text;
- classify work from GitHub, Jira, Azure DevOps, or local notes;
- choose relevant skills before spending remote LLM tokens;
- explain blockers and next actions from logs and evidence.

Skills are part of the execution context. The runtime should discover global
skills, project skills, and Simplicio package skills, then load only the small
skill subset needed for the current step.

The origin of a good programming capability does not matter. If a pattern from
Hermes, ECC, Codex, Claude, Copilot, Kiro, Cursor, or another tool improves
debugging, testing, review, evidence, source control, or token economy, the
runtime should absorb the pattern into a curated pack or call it through an
adapter.

## Reasoning Router

Simplicio Runtime should choose the best reasoning backend for each step:

- no LLM for deterministic work;
- local LLM for classification, summarization, translation, progress messages,
  low-risk edits, and first-pass reviews;
- Codex CLI or Codex-like tools for coding-heavy reasoning when configured;
- Claude CLI or Claude-like tools for deep architecture, review, and nuanced
  explanation when configured;
- other model CLIs or OpenAI-compatible endpoints when they are cheaper,
  faster, local, or better for the task.

Every escalation should be explainable:

```json
{
  "reasoning_backend": "claude-cli",
  "reason": "architecture trade-off requires deeper review",
  "local_attempted": true,
  "cost_policy": "approved-escalation"
}
```

The goal is not to avoid strong LLMs. The goal is to use them only when they
create real value, while local tools and local models handle the mechanical
majority of the work.

## Runtime Architecture

```mermaid
flowchart LR
  user["User / Assistant"] --> runtime["simplicio runtime"]
  runtime --> decision["decision engine"]
  decision --> mapper["simplicio-mapper"]
  decision --> prompt["simplicio-prompt"]
  decision --> dev["simplicio-dev-cli"]
  decision --> sprint["simplicio-sprint"]
  decision --> llm["local llama.cpp service"]
  decision --> lifecycle["agent lifecycle manager"]
  dev --> evidence["tests / Playwright / evidence"]
  sprint --> pr["commit / push / PR"]
  runtime --> tools["Codex / Claude / VS Code / Copilot / Kiro / Cursor"]
```

## Invocation Model

```bash
simplicio doctor --repair
simplicio install --global
simplicio serve --mcp
simplicio map --repo .
simplicio plan --repo . --agents 20 --json
simplicio run "fix the dev CORS issue" --repo . --agents 20 --local --evidence
simplicio sprint ./sprint-01 --repo . --agents 100 --local --pr --watch
simplicio chat "what is blocking this PR?" --repo . --local
```

The assistant can stay in planning/review mode while the runtime performs local
mapping, triage, execution, validation, evidence collection, and status updates.

## Integrations

- [Codex, Claude, VS Code, GitHub Copilot, Kiro, Cursor](docs/INTEGRATIONS.md)
- [MCP and server mode](docs/MCP_SERVER_MODE.md)
- [Release pipeline](docs/RELEASE_PIPELINE.md)
- [Managed Python packaging ADR](docs/ADR-0001-managed-python-packaging.md)
- [Case study 001](docs/CASE_STUDY_001_RUNTIME_BACKLOG.md)
- [Security and privacy](docs/SECURITY_AND_PRIVACY.md)
- [Observability](docs/OBSERVABILITY.md)
- [Installation model](docs/INSTALLATION_MODEL.md)
- [Update model](docs/UPDATE_MODEL.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Super runtime north star](docs/SUPER_RUNTIME.md)
- [Anyone can use](docs/ANYONE_CAN_USE.md)
- [Capability curation](docs/CAPABILITY_CURATION.md)
- [Programming tool and skill inventory](docs/PROGRAMMING_TOOL_SKILL_INVENTORY.md)
- [Conversation evolution ledger](docs/CONVERSATION_EVOLUTION_LEDGER.md)
- [Benchmark plan: with vs without runtime](docs/BENCHMARK_PLAN.md)
- [Package evolution and subcommand roadmap](docs/PACKAGE_EVOLUTION.md)
- [Release manifest](docs/RELEASE_MANIFEST.md)

## First Commands

```bash
simplicio doctor --json
simplicio version --json
simplicio plan --repo . --agents 20 --json
simplicio run --repo . --agents 20 --local --evidence
```

## Proof Roadmap

This repository will track results as the runtime evolves:

- baseline: direct assistant workflow without Simplicio Runtime;
- runtime: same tasks with mapper, decision engine, local LLM, cache, and governed workers;
- metrics: elapsed time, commands avoided, local tokens, remote tokens, cache hits, test pass rate, PR evidence completeness.

## Simplicio Ecosystem

- [simplicio-mapper](https://github.com/wesleysimplicio/simplicio-mapper)
- [simplicio-dev-cli](https://github.com/wesleysimplicio/simplicio-dev-cli)
- [simplicio-prompt](https://github.com/wesleysimplicio/simplicio-prompt)
- [simplicio-sprint](https://github.com/wesleysimplicio/simplicio-sprint)

## Original Field Guide

This is a new repository, so there is no older manual to preserve yet. Future README upgrades should keep this section for operational memory and append deeper field notes instead of replacing them.

