simplicio-cli 0.5.14__tar.gz → 0.5.16__tar.gz

{simplicio_cli-0.5.14 → simplicio_cli-0.5.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-cli
-Version: 0.5.14
+Version: 0.5.16
 Summary: Portable task-to-code pipeline that works with any LLM. Turn a one-line task into a verified code change — diff + test + verify loop. +55 pts on a 156-check benchmark, 21% faster, ~same tokens.
 Author-email: Wesley Simplicio <wesleybob4@gmail.com>
 License: MIT
@@ -30,8 +30,8 @@ Requires-Dist: sentence-transformers>=5.1.2
 Requires-Dist: numpy>=2.0.2
 Requires-Dist: anthropic>=0.105.2
 Requires-Dist: openai>=2.38.0
-Requires-Dist: simplicio-mapper>=0.7.1
-Requires-Dist: simplicio-prompt>=1.13.1
+Requires-Dist: simplicio-mapper>=0.7.3
+Requires-Dist: simplicio-prompt>=1.13.3
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: orjson>=3.11.5
 Requires-Dist: diskcache>=5.6.3
@@ -43,7 +43,101 @@ Requires-Dist: llama-cpp-python>=0.3.23; extra == "local"
 Requires-Dist: huggingface-hub>=1.8.0; extra == "local"
 Dynamic: license-file
 
-# simplicio-cli
+<h1 align="center">simplicio-cli</h1>
+
+<p align="center">
+  <strong>Turn a one-line task into a verified code change: mapper context, six-layer contract, diff, test, and evidence.</strong><br />
+  <em>Commands stay in English so they can be copied exactly.</em>
+</p>
+
+<p align="center">
+<a href="https://github.com/wesleysimplicio/simplicio-dev-cli/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/wesleysimplicio/simplicio-dev-cli?style=flat-square" /></a>
+<a href="https://pypi.org/project/simplicio-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/simplicio-cli.svg?style=flat-square" /></a>
+<a href="https://pypi.org/project/simplicio-cli/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/simplicio-cli.svg?style=flat-square" /></a>
+<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-yellow?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="output/imagegen/simplicio-cli-readme-hero-web.png" alt="simplicio-cli preview" width="860" />
+</p>
+
+---
+
+## The short version
+
+Turn a one-line task into a verified code change: mapper context, six-layer contract, diff, test, and evidence.
+
+## Project DNA
+
+simplicio-cli is not just a command wrapper; it is the measured execution layer of the ecosystem. Its older README carried the hard proof: real hidden tests, benchmark tables, model comparisons, provider policy, and the honest boundary between better prompting and actual capability. That evidence belongs beside the new hero, not behind it.
+
+The new first screen is the doorway; the restored guide below is the workshop. This README should help a stranger understand the promise quickly and still give an operator enough depth to run, validate, and extend the project.
+
+## Quick Start
+
+```bash
+pip install -U simplicio-cli
+simplicio detect "hide the Delete button for non-admins"
+simplicio task "hide the Delete button for non-admins"
+```
+
+## What it does
+
+- Classifies the task before execution so small fixes stay small and sprint-scale work becomes a plan.
+- Loads simplicio-mapper artifacts before asking an LLM to edit.
+- Keeps a verification loop around generated diffs instead of trusting the first answer.
+- Works with local Simplicio1, OpenRouter, OpenAI, Anthropic, DeepSeek, Hermes, Codex and Claude-style hosts.
+
+## Why this README is built to earn attention
+
+- clear first-screen promise
+- language links before installation
+- badges and a visual hero for fast trust
+- copy-ready quick start
+- proof before long reference material
+- star history for social proof
+
+## How it works
+
+```mermaid
+flowchart LR
+  mapper["simplicio-mapper
+repo context"] --> current["simplicio-cli
+this project"]
+  prompt["simplicio-prompt
+reasoning runtime"] --> current
+  current --> evidence["validated evidence
+tests, docs, screenshots"]
+  current --> sprint["simplicio-sprint
+delivery loop"]
+```
+
+## Proof and validation
+
+- Benchmark docs compare plain prompting vs the Simplicio contract on real code tasks.
+- Package metadata tests pin ecosystem dependency floors.
+- The CLI is the executor layer used by SendSprint and SimplicioCode flows.
+
+## Simplicio ecosystem
+
+- [simplicio-mapper](https://github.com/wesleysimplicio/simplicio-mapper) supplies repo context before interpretation.
+- [simplicio-cli](https://github.com/wesleysimplicio/simplicio-dev-cli) executes focused code tasks with verification.
+- [simplicio-prompt](https://github.com/wesleysimplicio/simplicio-prompt) provides fan-out and consensus runtime patterns.
+- [simplicio-sprint](https://github.com/wesleysimplicio/simplicio-sprint) turns cards into draft PR delivery loops.
+
+## Documentation standard
+
+- [docs/PYTHON_PACKAGE_INTERDEPENDENCE.md](docs/PYTHON_PACKAGE_INTERDEPENDENCE.md)
+- [docs/LLM_USAGE_POLICY.md](docs/LLM_USAGE_POLICY.md)
+- [docs/readme-globalization-standard.md](docs/readme-globalization-standard.md)
+
+## Original Field Guide
+
+The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory.
 
 **Your tasks with 99% accuracy using any LLM (Claude, DeepSeek, Codex, Gemini, Hermes, OpenClaw, Cursor).**
 
@@ -63,7 +157,7 @@ pip install simplicio-cli
 ```
 
 ---
-## Recommended Default Stack (Official)
+### Recommended Default Stack (Official)
 
 The recommended and supported way to use `simplicio-dev-cli` is as part of the full Simplicio execution stack:
 
@@ -81,11 +175,11 @@ See the canonical policy:
 When bootstrapping a new project with the Simplicio starter, this stack is configured by default.
 
 
-## Why it works — the numbers
+### Why it works — the numbers
 
 Two complementary benchmarks measure different things. Read them in order.
 
-### 1. Execution benchmark — real project, real tasks, real test suite (the "does it work" answer)
+#### 1. Execution benchmark — real project, real tasks, real test suite (the "does it work" answer)
 
 **This is not regex pattern-matching. This is not a synthetic toy harness in
 isolation.** Run against [`wesleysimplicio/sistema-sindico`](https://github.com/wesleysimplicio/sistema-sindico)
@@ -137,7 +231,7 @@ clone `sistema-sindico` (public), `composer install`, then
 python3 bench/run_exec_sindico.py`. Hidden tests live under
 `bench/sindico_hidden/`; harness in `bench/run_exec_sindico.py`.
 
-### 2. Contract-adherence benchmark — structural checks across many models
+#### 2. Contract-adherence benchmark — structural checks across many models
 
 The tables below measure something **narrower and complementary**: did the
 model produce **the right shape of actionable output** (target-file mention +
@@ -154,7 +248,7 @@ M1 MacBook (8 GB), five sub-4B tiny models, six frontier 2026 models, and three
 mid-tier 7B–12B open models. Every one gained at least **+14 points** when
 wrapped in simplicio's 6-layer contract.
 
-#### Hugging Face — recommended Qwen3-Coder defaults (HF router)
+##### Hugging Face — recommended Qwen3-Coder defaults (HF router)
 
 The served Qwen Coder recommendation now uses the Qwen3-Coder MoE family.
 `Qwen/Qwen2.5-Coder-3B-Instruct` and
@@ -199,7 +293,7 @@ Pro) show `n/a` for the new column: their OpenRouter calls hit account-level
 HTTP 402 / provider failures on >50% of requests this round, so the sample is
 too small to publish; their old numbers still stand.
 
-#### Local offline — Qwen3-Coder GGUF recommendation, Qwen2.5 legacy baseline
+##### Local offline — Qwen3-Coder GGUF recommendation, Qwen2.5 legacy baseline
 
 For local OpenAI-compatible servers, prefer the Qwen3-Coder GGUF builds when
 the machine can host MoE weights:
@@ -226,7 +320,7 @@ M1 8 GB, run on 2026-05-27 (30 runs/side, 156 checks):
 > Reproduce the legacy fallback: `BENCH_BASE_URL=http://localhost:11434/v1 BENCH_API_KEY=ollama
 > BENCH_MODELS="qwen2.5-coder:7b" python3 bench/run_offline.py`.
 
-#### Tiny models — sub-4B, run on 2026-05-26 (50 runs/side, 260 checks)
+##### Tiny models — sub-4B, run on 2026-05-26 (50 runs/side, 260 checks)
 
 | Model | Without simplicio | With simplicio | Gain |
 |---|---|---|---|
@@ -242,7 +336,7 @@ M1 8 GB, run on 2026-05-27 (30 runs/side, 156 checks):
 > Nemotron Nano 4B (OR's smallest Nemotron is 9B). Sub-4B substitutes used above.
 > simplicio still gains **+14 to +58 points** even on a 1B-param model.
 
-#### Frontier 2026 models — run on 2026-05-26 (60 runs/side, 312 checks)
+##### Frontier 2026 models — run on 2026-05-26 (60 runs/side, 312 checks)
 
 | Model | Without simplicio | With simplicio | Gain |
 |---|---|---|---|
@@ -254,7 +348,7 @@ M1 8 GB, run on 2026-05-27 (30 runs/side, 156 checks):
 | **DeepSeek V4 Pro** (`deepseek/deepseek-v4-pro`) | 44% | **96%** | **+52 pts** |
 | **Frontier avg (6 models · 10 cases · 312 checks)** | **41%** | **99%** | **+58 pts (+136%)** |
 
-#### Mid-tier 7B–12B open models — earlier run (v0.2.2, 30 runs/side, 156 checks)
+##### Mid-tier 7B–12B open models — earlier run (v0.2.2, 30 runs/side, 156 checks)
 
 | Model | Without simplicio | With simplicio | Gain |
 |---|---|---|---|
@@ -270,7 +364,7 @@ M1 8 GB, run on 2026-05-27 (30 runs/side, 156 checks):
 > models, and mid-tier 7B–12B alike — five of the six frontier models hit
 > **100% pass-rate**.
 
-### Output-quality signals (rate across all 60 frontier runs)
+#### Output-quality signals (rate across all 60 frontier runs)
 
 | Signal | Raw prompt | With simplicio |
 |---|---|---|
@@ -278,7 +372,7 @@ M1 8 GB, run on 2026-05-27 (30 runs/side, 156 checks):
 | Target file mentioned | 1% | **100%** |
 | TEST block present | 88% | **98%** |
 
-### Cost — tokens & wall-clock (measured, not estimated)
+#### Cost — tokens & wall-clock (measured, not estimated)
 
 Same provider, same models, same cases. Token counts pulled from the API
 `usage` field; latency from `time.perf_counter()` around each call.
@@ -304,7 +398,7 @@ Full report: [`bench/results.md`](bench/results.md) · [`bench/results.pdf`](ben
 
 ---
 
-## How it works
+### How it works
 
 ```
 mapper        WHERE   project structure + latest state
@@ -315,7 +409,7 @@ test          JUDGE   contract written as testable states
 verify        PROOF   ran it — did it actually pass? loop-fix up to 3x
 ```
 
-### Rich mapper integration
+#### Rich mapper integration
 
 When `simplicio-mapper` has generated `.simplicio/project-map.json` and
 `.simplicio/precedent-index.json`, `simplicio-cli` consumes them directly:
@@ -328,7 +422,7 @@ When `simplicio-mapper` has generated `.simplicio/project-map.json` and
 If those artifacts are missing, the CLI falls back to the older target-file
 inspection path, so existing projects keep working.
 
-### Adaptive retry and observability
+#### Adaptive retry and observability
 
 The retry loop now validates generated output before applying/testing it,
 classifies failures, and sends targeted retry feedback. Bench and pipeline runs
@@ -341,7 +435,7 @@ Relevant > complete — inject the *right* context, never *all* of it.
 
 ---
 
-## Install
+### Install
 
 ```bash
 pip install simplicio-cli           # from PyPI (pulls simplicio-mapper + simplicio-prompt)
@@ -381,7 +475,7 @@ for) real subagent fan-out all work out of the box without extra setup.
 
 ---
 
-## How you use it — pick your path
+### How you use it — pick your path
 
 simplicio-cli has **three distinct entry points**. Same engine, three front doors — pick the one that matches what you already pay for:
 
@@ -397,7 +491,7 @@ simplicio-cli has **three distinct entry points**. Same engine, three front door
 
 **Path 3 is for environments without any logged-in CLI** — a remote server, a build runner, a notebook, a different LLM provider. You bring an API key (Anthropic, OpenRouter, OpenAI, GLM, DeepSeek, Ollama…), simplicio calls the provider directly.
 
-### Path 1 example — inside Claude Code
+#### Path 1 example — inside Claude Code
 
 After `pip install simplicio-cli && simplicio smoke` (which triggers auto-bootstrap), just type your task in Claude Code:
 
@@ -407,7 +501,7 @@ hide the Delete button for non-admins in src/app/screen/screen.component.html
 
 Claude Code sees the skill (semantic match) and the hook hint (`[SIMPLICIO_PROMPT_HINT]` on stderr — deterministic classifier). It runs simplicio's 6-layer contract under the hood. You see the diff + tests + verification — same as before, just dramatically more accurate.
 
-### Path 2 example — subscription shell-out, zero key
+#### Path 2 example — subscription shell-out, zero key
 
 You already pay for Claude Pro/Max or ChatGPT Plus + Codex CLI. simplicio
 piggybacks on that login — no extra bill, no key to manage.
@@ -450,7 +544,7 @@ cost_usd, diff_summary, warnings}`. Repeat `--bound-paths <glob>` to reject
 diffs outside the allowed edit surface; violations are reported in `warnings`
 and the command exits non-zero.
 
-### Path 3 example — standalone with API key
+#### Path 3 example — standalone with API key
 
 ```bash
 export SIMPLICIO_API_KEY=sk-or-v1-…                      # OpenRouter key
@@ -471,7 +565,7 @@ Provider-agnostic — see [Configure](#configure--any-llm-nothing-hardcoded) for
 
 ---
 
-### Path 1 deep-dive — auto-activation in Claude Code
+#### Path 1 deep-dive — auto-activation in Claude Code
 
 `pip install` puts `simplicio` on your PATH. To make Claude Code
 **automatically** route code-edit tasks through simplicio, a skill + hook
@@ -513,7 +607,7 @@ Either way, two files land in `~/.claude/`:
 A backup of your previous `settings.json` is written to `settings.json.bak`
 before any merge.
 
-### How it works at runtime
+#### How it works at runtime
 
 After install, every prompt you type in Claude Code flows through two layers:
 
@@ -530,14 +624,14 @@ After install, every prompt you type in Claude Code flows through two layers:
 The layers are complementary. Skill = "Claude *might* pick simplicio". Hook
 = "Claude *sees* the hint regardless".
 
-### Why UserPromptSubmit and not PreToolUse
+#### Why UserPromptSubmit and not PreToolUse
 
 UserPromptSubmit fires **once, before Claude decides which tool to call** —
 exactly when we want to steer. PreToolUse fires *after* the decision is made,
 and again for every tool call in the turn, with no access to the original
 user prompt. UserPromptSubmit is the right pre-hook for routing decisions.
 
-### Disable / re-enable
+#### Disable / re-enable
 
 | Goal | How |
 |---|---|
@@ -549,7 +643,7 @@ user prompt. UserPromptSubmit is the right pre-hook for routing decisions.
 
 ---
 
-## Configure — any LLM, nothing hardcoded
+### Configure — any LLM, nothing hardcoded
 
 > Applies to **Path 2** (standalone CLI). Path 1 users can skip this entire
 > section — Claude Code handles the LLM call with the model and key already
@@ -573,7 +667,7 @@ your `base_url` — so **any** OpenAI-like provider works without code changes.
 simplicio smoke      # prints provider config + one test call
 ```
 
-### Path 4 — local Ollama primary with GGUF fallback
+#### Path 4 — local Ollama primary with GGUF fallback
 
 When **no provider is configured** (`SIMPLICIO_MODEL` and
 `SIMPLICIO_BASE_URL` both unset), simplicio uses local Ollama with
@@ -608,7 +702,7 @@ default `0`), `SIMPLICIO_LOCAL_MAX_TOKENS` (generation cap),
 `SIMPLICIO_LOCAL_TEMP` (default `0.1`), `SIMPLICIO_LOCAL_MODEL_REPO` /
 `SIMPLICIO_LOCAL_MODEL_FILE`.
 
-### The pipeline (both paths)
+#### The pipeline (both paths)
 
 Whichever entry point you use, each task runs through the same engine:
 
@@ -627,7 +721,7 @@ models (see [the numbers](#why-it-works--the-numbers) above). The retry loop
 is what catches the remaining edge cases — measured separately in the
 [4-quadrant bench](#4-quadrant-bench--agent--simplicio-matrix).
 
-### Common questions
+#### Common questions
 
 **"I have a Claude Pro subscription but no API key — does this work?"** Yes,
 on Path 1. Install simplicio-cli, open Claude Code, type your task as normal.
@@ -663,7 +757,7 @@ delete the hook entry from `~/.claude/settings.json`.
 
 ---
 
-## Cache — why it doesn't re-map every time
+### Cache — why it doesn't re-map every time
 
 Embeddings are keyed by **content hash**, stored in `.simplicio/`. Unchanged
 code block → vector reused. Change one file → only that block re-embeds.
@@ -676,7 +770,7 @@ code block → vector reused. Change one file → only that block re-embeds.
 
 ---
 
-## Benchmark — reproduce in 30 seconds
+### Benchmark — reproduce in 30 seconds
 
 ```bash
 OPENROUTER_API_KEY=… \
@@ -689,7 +783,7 @@ the LLM. Each case runs twice on the **same** model: raw one-line objective vs
 simplicio's 6-layer contract. Outputs scored on target-file mention, DIFF
 block, TEST block, contract-state words. Full numbers in [`bench/results.md`](bench/results.md).
 
-### Full harness (your real project, your real tests)
+#### Full harness (your real project, your real tests)
 
 ```bash
 simplicio bench --cases bench/cases.json --stack angular
@@ -699,7 +793,7 @@ Runs each case two ways and runs **your real test command** (e.g. `ng test
 --watch=false`) on each output. Writes the true pass-rate to
 [`bench/results.md`](bench/results.md).
 
-### 4-quadrant bench — agent × simplicio matrix
+#### 4-quadrant bench — agent × simplicio matrix
 
 Adds the second axis: not just *"does the 6-layer wrap help one call?"* but
 *"does it still help inside a retry loop?"*. Same model, same cases — only
@@ -731,7 +825,7 @@ The matrix decomposes:
 - **Composition gain over best single axis**: Q4 − max(Q2, Q3)
 - **Synergy vs linear stacking**: Q4 − (Q1 + (Q2−Q1) + (Q3−Q1))
 
-#### Run 1 — focused single-model, `google/gemma-3-4b-it`, 5 cases, max_iters=3 (2026-05-26)
+##### Run 1 — focused single-model, `google/gemma-3-4b-it`, 5 cases, max_iters=3 (2026-05-26)
 
 | Quadrant | Prompt | Execution | Pass rate | Avg iters | Tokens / pass |
 |---|---|---|---|---|---|
@@ -750,7 +844,7 @@ Decomposition (rejection threshold `|Δ| ≥ 5 pts`):
 
 Cost per passing case: Q1 = 4,683 tok / 236s — Q2 = **800 tok / 21s** — Q3 = 3,135 tok / 109s — Q4 = **1,018 tok / 20s**. Full table + charts in [`bench/results_4quadrant.md`](bench/results_4quadrant.md).
 
-#### Run 2 — wider multi-model, 3 models × 10 cases (partial), max_iters=5 (2026-05-26)
+##### Run 2 — wider multi-model, 3 models × 10 cases (partial), max_iters=5 (2026-05-26)
 
 Replicated the matrix across more models and more cases. `qwen-2.5-7b` covers only the first 5 of 10 cases (wide run was killed mid-execution); `claude-3.5-haiku` not reached. Aggregate counts every observed `(model × case × quadrant)` tuple as one observation:
 
@@ -781,7 +875,7 @@ Same picture at every scale: Q4 (composition) wins on pass-rate, **and** Q4 stay
 
 ---
 
-## Plug points (stubs marked in code)
+### Plug points (stubs marked in code)
 
 | File | Replace with |
 |---|---|
@@ -789,7 +883,7 @@ Same picture at every scale: Q4 (composition) wins on pass-rate, **and** Q4 stay
 | `pipeline.py::_aplicar_e_testar` | extract diff → `git apply` → parse test result |
 | `skill_router.py` | point `SIMPLICIO_SKILLS_DIR` at your mapper's skills |
 
-## Layout
+### Layout
 
 ```
 simplicio/
@@ -810,5 +904,19 @@ bench/
   charts/         # SVG: overall, delta, by_case, by_stack
 ```
 
-## License
+### License
 MIT
+
+## Star History
+
+<a href="https://www.star-history.com/#wesleysimplicio/simplicio-dev-cli&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-dev-cli&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-dev-cli&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-dev-cli&type=Date" />
+  </picture>
+</a>
+
+## License
+
+MIT. See [LICENSE](LICENSE).