skill-proof-router 1.3.0__tar.gz

skill_proof_router-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 P Choke & SORA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skill_proof_router-1.3.0/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: skill-proof-router
+Version: 1.3.0
+Summary: Deterministic, offline skill router and global skill vault for autonomous AI fleets
+Author: P Choke & MIKA
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rapidfuzz>=3.0.0
+Provides-Extra: vectors
+Requires-Dist: model2vec>=0.10.0; extra == "vectors"
+Requires-Dist: tokenizers>=0.19.0; extra == "vectors"
+Dynamic: license-file
+
+<div align="center">
+
+# Skill Proof
+
+**Global Skill Vault & Deterministic In-Process Skill Router for AI Coding Agents**
+
+<p><em>Zero routing model calls. Unified <code>~/.skill-proof/skills</code> vault. Sub-millisecond lexical, fuzzy & local vector routing over stdio MCP.</em></p>
+
+<p>
+  <a href="https://github.com/Stxyu-p/skill-proof"><img src="docs/badges/release.svg" alt="Global Vault & MCP" /></a>
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="License" /></a>
+  <img src="docs/badges/python.svg" alt="Python 3.10+" />
+  <a href="#quick-start"><img src="docs/badges/quickstart.svg" alt="Quick Start" /></a>
+  <a href="#the-global-skill-vault-skill-proofskills"><img src="docs/badges/install.svg" alt="Global Vault" /></a>
+  <a href="#mcp-server--universal-client-installer"><img src="docs/badges/mcp.svg" alt="MCP" /></a>
+</p>
+
+<p>
+  <a href="#why-skill-proof">Why Skill Proof</a> ·
+  <a href="#live-routing-showcase">Live Routing</a> ·
+  <a href="#the-global-skill-vault-skill-proofskills">Global Skill Vault</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#how-two-tier-routing-works">How It Works</a> ·
+  <a href="#architecture--key-modules">Architecture</a> ·
+  <a href="#mcp-server--universal-client-installer">MCP & Clients</a> ·
+  <a href="#cli-hermes--configuration-reference">CLI & Config</a> ·
+  <a href="#recommended-ecosystem-combo">Trinity Combo</a>
+</p>
+
+</div>
+
+---
+
+## Why Skill Proof?
+
+As your `SKILL.md` library grows across coding agents, two compounding bottlenecks emerge:
+1. **Fragmented Multi-Folder Chaos:** Skills get duplicated across `.agents/skills`, `.claude/skills`, `.cursor/skills`, `.codex/skills`, `.gemini/skills`, and `~/.hermes/skills` — wasting disk space and drifting out of sync whenever you improve a skill.
+2. **System Prompt Bloat & Routing Uncertainty:** Stuffing 100+ skill descriptions into every system prompt burns thousands of tokens per turn, while calling a secondary LLM to pick a skill adds latency, cost, and nondeterministic guesses.
+
+**Skill Proof solves both problems 100% locally and in-process:**
+
+- **Global Skill Vault (`~/.skill-proof/skills`):** Consolidates dispersed physical skills into one canonical global vault (`vault.json`) and links them cleanly into legacy client folders via NTFS junctions or POSIX symlinks.
+- **Deterministic Zero-LLM Routing:** Scores every skill in `< 1 ms` using a pre-computed inverted index, `rapidfuzz` C++ token alignment, character n-grams for spaceless scripts (Thai, CJK), contrastive clause splitting (`"use X instead of Y"`), 6-language negation vetoes (`"do not use TDD"`), and confidence-gated local embeddings (`model2vec` / ONNX).
+- **Tamper-Evident Audit & Tool Gates:** Emits SHA-256 hash-chained selection receipts (`audit.jsonl`) storing derived numbers only (never prompts or secrets) and optionally enforces tool gates until the required skill is loaded.
+
+| Cost of a Large Skill Catalog | Without Skill Proof | With Skill Proof |
+| :--- | :--- | :--- |
+| **Skill Storage** | Duplicated across `.agents`, `.claude`, `.cursor`, `.gemini`, `.hermes` | **One canonical vault (`~/.skill-proof/skills`)** shared by all agents |
+| **Routing Execution** | Extra LLM call or full-catalog prompt reasoning | **Zero model calls** — deterministic in-process scoring in `< 1 ms` |
+| **System Prompt Size** | Every skill name & description stays in the system prompt | Confident selection can replace the full index for that turn (`reduce_skill_prompt`) |
+| **Negative Constraints** | `"do not use X"` often ignored by keyword matchers | **6-language Negation Veto** strips vetoed skills before scoring |
+| **Vague / Ambiguous Queries** | Model guesses and activates the wrong workflow | Conservative margin gate returns `ambiguous` shortlist or `no_match` |
+| **Auditability** | Opaque model choice with no provenance | **SHA-256 hash-chained receipts** + `/skill-proof why <skill>` breakdown |
+
+![Skill Proof two-tier in-process routing architecture](docs/architecture.svg)
+
+---
+
+## Live Routing Showcase
+
+### 1. Explicit Negation Veto + Contrastive Routing + Fleet Agent Hint
+Notice how `"do not use TDD"` vetoes `test-driven-development` before ranking, selects `github-code-review`, attaches `github-pr-workflow` as a companion skill, and recommends the `altima` reviewer agent:
+
+```bash
+$ skill-proof select --query "Review this pull request for syntax bugs, but do not use TDD"
+decision: selected (lexical_match)
+suggested fleet agent: altima
+selected: github-code-review score=0.940715 reasons=alias_phrase,name_terms,tag_terms,alias_terms,description_terms companions=github-pr-workflow
+candidate: github-code-review score=0.940715 reasons=alias_phrase,name_terms,tag_terms,alias_terms,description_terms
+candidate: code-review score=0.876008 reasons=alias_phrase,name_terms,alias_terms,description_terms
+candidate: github-pr-workflow score=0.852364 reasons=alias_phrase,tag_terms,alias_terms
+```
+
+### 2. Natural-Language Symptom Routing (Zero Exact Skill-Name Tokens)
+Even when the user describes a symptom (`"my page keeps crashing after login"`) without naming any skill, synonym bridges and morphology routing resolve the exact debugging playbook and companion test skill:
+
+```bash
+$ skill-proof select --query "my page keeps crashing after login"
+decision: selected (lexical_match)
+suggested fleet agent: sora
+selected: systematic-debugging score=0.796145 reasons=alias_phrase,alias_terms companions=test-driven-development
+candidate: systematic-debugging score=0.796145 reasons=alias_phrase,alias_terms
+candidate: planning-with-files score=0.076061 reasons=description_terms
+candidate: caveman score=0.035353 reasons=description_terms
+```
+
+---
+
+## The Global Skill Vault (`~/.skill-proof/skills`)
+
+Instead of scattering skill copies across every IDE and CLI, **Skill Proof** places `~/.skill-proof/skills` at the top of the root discovery hierarchy (`vault` root):
+
+```mermaid
+flowchart TD
+    Roots["Dispersed Agent Roots<br/>• ~/.agents/skills<br/>• ~/.claude/skills<br/>• ~/.cursor/skills<br/>• ~/.gemini/skills<br/>• ~/.hermes/skills"] -->|"skill-proof vault migrate"| Vault[("Global Skill Vault<br/>~/.skill-proof/skills<br/>(Canonical Single Source of Truth)")]
+
+    Vault -->|"Direct MCP Discovery"| MCP["MCP Clients<br/>(skill_select / skill_search / skill_read)"]
+    Vault -->|"skill-proof vault pin / link-all<br/>(NTFS Junctions / Symlinks)"| Legacy["Legacy Folder-Based Agents"]
+```
+
+```bash
+# 1. Migrate all physical skills from detected agent roots into ~/.skill-proof/skills
+skill-proof vault migrate
+
+# 2. Inspect global vault inventory and per-client linkage health
+skill-proof vault status
+
+# 3. Pin a specific skill (or link all vault skills) into a client directory via NTFS junction / symlink
+skill-proof vault pin --skill systematic-debugging --to ~/.claude/skills
+skill-proof vault link-all --to ~/.cursor/skills
+```
+
+> [!NOTE]
+> **Safe Reparse & Zero-Data-Loss Guarantees:**
+> - Junctions and symlinks pointing into `~/.skill-proof/skills` are automatically whitelisted by the catalog scanner (`unsafe_reparse = 0`).
+> - `skill-proof vault unpin` refuses to delete physical directories.
+> - `skill-proof vault pin` and `vault link-all` never overwrite an existing physical directory unless `--force` is explicitly provided.
+
+---
+
+## Quick Start
+
+### 1. Universal One-Command Auto-Install (Recommended)
+
+Install `skill-proof`, register its stdio MCP server across all detected AI coding clients, and consolidate your skills into the global vault:
+
+```bash
+pip install skill-proof-router
+skill-proof install
+skill-proof vault migrate
+```
+
+`skill-proof install` detects and atomically updates:
+- **Claude Code** (`~/.claude.json`) & **Claude Desktop** (`claude_desktop_config.json`)
+- **Google Antigravity & Antigravity IDE** (`~/.gemini/config/mcp_config.json`, `~/.gemini/antigravity/mcp_config.json`)
+- **Gemini CLI** (`~/.gemini/settings.json`) & **Codex CLI** (`~/.codex/config.toml`)
+- **Cursor** (`~/.cursor/mcp.json`), **Windsurf**, **VS Code (Copilot)**, **OpenCode**, and **Cline**
+
+Verify client registration and catalog state:
+
+```bash
+skill-proof clients
+skill-proof status
+skill-proof scan
+```
+
+### 2. Hermes Agent Native Plugin
+
+```bash
+# Linux / macOS
+git clone https://github.com/Stxyu-p/skill-proof.git ~/.hermes/plugins/skill-proof
+
+# Windows (PowerShell)
+git clone https://github.com/Stxyu-p/skill-proof.git "$env:LOCALAPPDATA\hermes\plugins\skill-proof"
+
+hermes plugins enable skill-proof
+```
+
+---
+
+## How Two-Tier Routing Works
+
+```mermaid
+flowchart LR
+    Q(["User Request"]) --> Dialogue["1. Dialogue & Negation Layer<br/>• Session focus ('same skill')<br/>• Contrastive split ('X not Y')<br/>• 6-language negation veto"]
+    Dialogue --> Lex["2. Inverted-Index Lexical + Fuzzy Ranker<br/>• IDF token & phrase overlap<br/>• Thai/CJK character n-grams<br/>• rapidfuzz C++ similarity"]
+    Lex --> FastGate{"3. Clear Winner?<br/>score >= 0.55 &<br/>margin >= 0.18"}
+    FastGate -- "Yes (lexical_fastpath)" --> Decide["4. Three-State Decision<br/>• selected (score >= min_score, margin >= min_margin)<br/>• ambiguous (shortlist top-k)<br/>• no_match (abstain cleanly)"]
+    FastGate -- "Borderline & Vectors Enabled" --> Vec["Confidence-Gated Embeddings<br/>(local ONNX / model2vec / gateway)<br/>+ RRF Fusion"]
+    Vec --> Decide
+```
+
+### Three-State Decision Rules
+
+- **`selected` (Clear Winner):** Top candidate meets `min_score` (default `0.28`) AND leads the runner-up by at least `min_margin` (default `0.05`). When `score >= 0.55` and `margin >= 0.18`, the embedding layer is bypassed entirely (`provider_used=lexical_fastpath`).
+- **`ambiguous` (Close Runner-Up):** Multiple candidates cluster within `min_margin`. Skill Proof returns a shortlist of up to `max_candidates` (default `3`) instead of guessing.
+- **`no_match` (Clean Abstention):** Nothing clears threshold. Skill Proof abstains so an unrelated skill is never forced onto a turn.
+
+---
+
+## Architecture & Key Modules
+
+| Module | Role | Technical Advantage |
+| :--- | :--- | :--- |
+| `skill_proof/core.py` | **Engine Facade** | Turn lifecycle, session memory, SHA-256 hash-chained receipts, and shared `SkillProofEngine.from_config` factory. |
+| `skill_proof/vault.py` | **Global Skill Vault** | Manages `~/.skill-proof/skills` and `vault.json`; implements `migrate`, `pin`, `unpin`, `sync`, and `link-all` via NTFS junctions / POSIX symlinks. |
+| `skill_proof/_catalog.py` | **Multi-Root Discovery** | Prioritizes `~/.skill-proof/skills` (`vault` root), TTL-caches scans (`catalog_cache_ttl_ms`), validates frontmatter invariants, and filters disabled skills. |
+| `skill_proof/_ranking.py` | **Lexical & Fuzzy Ranker** | Pre-computed inverted index, English morphology stemmer, Thai/CJK character n-grams, `rapidfuzz` C++ fuzzy matching, and companion skill handoff. |
+| `skill_proof/_dialogue.py` | **Conversational Focus & Veto** | Multi-turn session focus, reference resolution (`"same skill as before"`), contrastive splitting (`"use X instead of Y"`), and 6-language negation vetoes. |
+| `skill_proof/_vector.py` | **Confidence-Gated Vectors** | Runs `local` (`model2vec` / ONNX) or `gateway` embeddings with RRF fusion *only* when lexical ranking is borderline. |
+| `skill_proof/_compliance.py` | **Policy Store & Calibration** | Enforce-mode tool gates (`active_turn.json`) and audit-driven threshold calibration (`calibrate_audit`). |
+| `skill_proof/bridge.py` | **Host Hook Bridge** | Removable `PreToolUse` / `AGENTS.md` / `.cursor/rules` bridge for external harnesses. |
+| `skill_proof/mcp_server.py` | **Stdio MCP Server** | Exposes `skill_roots`, `skill_scan`, `skill_select`, `skill_search`, and `skill_read` over JSON-RPC 2.0. |
+| `skill_proof/mcp_install.py` | **Universal Client Installer** | Atomically registers/unregisters `skill-proof` across 11 AI agent CLIs and IDEs with `.pre-mcp-install.bak` backups. |
+
+### System Footprint & Speed
+
+| Property | Measured Value |
+| :--- | :--- |
+| **Routing Model Calls** | **0** (100% deterministic in-process scoring) |
+| **Warm Catalog Scan (300 skills)** | **~0.02 ms** per turn (TTL-cached) |
+| **Non-Matching Query Pruning** | **0.2 – 0.3 ms** via pre-computed inverted index |
+| **Full Routing Median (300-skill catalog)** | **~6.0 ms** in a single Python process |
+| **Embedding Work on Clear Lexical Winner** | **Skipped (`0 ms`)** via `lexical_fastpath` |
+
+---
+
+## MCP Server & Universal Client Installer
+
+When registered via `skill-proof install`, any MCP-capable host gains five deterministic tools:
+
+| MCP Tool | Purpose |
+| :--- | :--- |
+| **`skill_roots`** | List all active skill root directories (led by `~/.skill-proof/skills`) and their precedence order. |
+| **`skill_scan`** | Scan all roots and return total skill count, diagnostic counts, and root health. |
+| **`skill_select`** | Return a deterministic routing decision (`selected`, `ambiguous`, or `no_match`), top candidates, companions, and suggested fleet agent. |
+| **`skill_search`** | Hybrid lexical + semantic RRF top-$k$ search across skill names, tags, aliases, and descriptions. |
+| **`skill_read`** | Load the full `SKILL.md` body for a selected skill on demand instead of bloating the base system prompt. |
+
+---
+
+## CLI, Hermes & Configuration Reference
+
+| CLI Subcommand | Purpose |
+| :--- | :--- |
+| `skill-proof select "<query>"` | Choose one skill deterministically for a query (`--json` for structured output). |
+| `skill-proof eval "<query>"` | Interactive query diagnostics: token breakdown, n-grams, explicit matches, and full ranking matrix. |
+| `skill-proof vault <action>` | Manage `~/.skill-proof/skills` (`status`, `migrate`, `pin`, `unpin`, `sync`, `link-all`). |
+| `skill-proof install` / `clients` / `uninstall` | Register, inspect, or remove the stdio MCP server across all 11 supported AI clients. |
+| `skill-proof scan` / `roots` | Scan all detected roots and report catalog diagnostics. |
+| `skill-proof overlap` | Detect near-duplicate or overlapping skills worth pruning across roots. |
+| `skill-proof calibrate` | Compute threshold and synonym tuning suggestions from `audit.jsonl`. |
+| `skill-proof models` / `setup` / `prefetch` | Inspect, configure, or checksum-download local embedding models. |
+| `skill-proof bridge` | Install or remove optional host hook bridges (`status`, `init`, `remove`, `ai-setup`). |
+
+<details>
+<summary><strong>⚙️ Click to expand: Full Hermes Plugin Commands & Configuration Schema</strong></summary>
+
+<br/>
+
+### In-Session Slash Commands (Hermes)
+
+| Command | Purpose |
+| :--- | :--- |
+| `/skill-proof status` | Compact turn state, catalog size, and provider status. |
+| `/skill-proof why <name>` | Full scoring explanation for why a skill won, lost, or was vetoed. |
+| `/skill-proof stats` | Per-skill hit rates, misses, and overrides aggregated from `audit.jsonl`. |
+| `/skill-proof calibrate` | Data-driven threshold and weight suggestions from audit history. |
+| `/skill-proof audit-verify` | Verify the cryptographic SHA-256 `prev_sha256` hash chain of `audit.jsonl`. |
+| `/skill-proof overlap` | Near-duplicate detection paired with actual audit load counts. |
+| `/skill-proof trace` | Full bounded JSON receipt for the current turn. |
+| `/skill-proof refresh` | Force an immediate catalog rescan on the next turn. |
+| `/skill-proof health` | Self-check across catalog diagnostics, hook activity, and timing. |
+
+### Configuration Settings (`config.yaml`)
+
+```yaml
+plugins:
+  enabled:
+    - skill-proof
+  entries:
+    skill-proof:
+      settings:
+        mode: nudge                       # nudge (default), observe, or enforce-tools
+        reduce_skill_prompt: false        # opt-in; confident selection replaces the full index
+        embedding_provider: off           # off (default), local, or gateway
+        embedding_model: Xenova/multilingual-e5-small
+        min_score: 0.28
+        min_margin: 0.05
+        catalog_cache_ttl_ms: 1000        # reuse host-filtered catalog within TTL window
+        block_modified_hub_skills: false  # exclude hub skills whose bundle SHA-256 changed
+        session_memory: true              # resolve follow-ups like "use the same skill"
+        audit_log: true                   # append derived-numbers hash-chained audit records
+```
+
+</details>
+
+---
+
+## Recommended Ecosystem Combo
+
+While **Skill Proof** works standalone as your skill vault and deterministic router, pairing it with [**MemCore**](https://github.com/Stxyu-p/memcore) and [**trimtok**](https://github.com/Stxyu-p/trimtok) completes the **Global Agent Trinity** — uniting every AI coding client on your machine (**Claude Code, Cursor, Antigravity, Gemini CLI, Codex, VS Code Copilot, Windsurf, OpenCode, Cline, and Hermes**) around three shared local hubs:
+
+```mermaid
+flowchart LR
+    Task(["Developer Request"]) --> SP["Skill Proof<br/>~/.skill-proof/skills<br/>(Deterministic Skill Router)"]
+    SP --> MC["MemCore<br/>~/.memcore<br/>(Governed Bitemporal Memory)"]
+    MC --> Agent["Any AI Coding Agent"]
+    Agent --> TT["trimtok<br/>~/.trimtok<br/>(88.3% Context Compression + CCR #c1)"]
+    TT --> Agent
+```
+
+| Pillar | Repository | Global Hub | What Installing All 3 Gives You |
+| :--- | :--- | :--- | :--- |
+| **Skill Vault & Router** | **[Skill Proof](https://github.com/Stxyu-p/skill-proof)** | `~/.skill-proof/skills` | Consolidates all dispersed `SKILL.md` playbooks into **one deduplicated global vault** and routes tasks in `< 1 ms` with zero routing LLM calls. |
+| **Governed Memory** | **[MemCore](https://github.com/Stxyu-p/memcore)** | `~/.memcore` | Gives every IDE and CLI **one shared bitemporal brain** (`FTS5` + `sqlite-vec` SIMD + `model2vec`) with hard trust boundaries and source-file staleness tracking. |
+| **Context Shield** | **[trimtok](https://github.com/Stxyu-p/trimtok)** | `~/.trimtok` | Cuts terminal, traceback, diff, AST code, and JSON token bloat by **88.3%** with instant `#c1` lossless recovery. |
+
+```bash
+# Install & link the complete Global Agent Trinity across all your IDEs and CLIs
+pip install skill-proof-router memcore trimtok
+skill-proof install && memcore init && memcore install && trimtok install
+skill-proof vault migrate
+```
+
+---
+
+## Verification & License
+
+```bash
+# Run the complete 383-test offline verification suite + routing & latency gates
+pytest -q
+python routing_benchmark.py --gate
+python phase3_gates.py
+```
+
+Distributed under the [MIT License](LICENSE). Designed and maintained by **P Choke & SORA**.