specsmith 0.10.1.dev298__tar.gz → 0.11.3.dev418__tar.gz

{specsmith-0.10.1.dev298/src/specsmith.egg-info → specsmith-0.11.3.dev418}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.10.1.dev298
+Version: 0.11.3.dev418
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT
@@ -72,8 +72,8 @@ Dynamic: license-file
 
 # specsmith
 
-[![CI](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml)
-[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=github)](https://github.com/sponsors/BitConcepts)
+[![CI](https://github.com/layer1labs/specsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/layer1labs/specsmith/actions/workflows/ci.yml)
+[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=github)](https://github.com/sponsors/layer1labs)
 [![Docs](https://readthedocs.org/projects/specsmith/badge/?version=stable)](https://specsmith.readthedocs.io/en/stable/)
 [![PyPI](https://img.shields.io/pypi/v/specsmith?label=stable&style=flat&color=blue&cacheSeconds=60)](https://pypi.org/project/specsmith/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
@@ -96,10 +96,35 @@ per-session and per-project.
 
 ```bash
 specsmith governance-serve --port 7700     # Kairos governance REST API
-specsmith sync                              # sync .specsmith/ from docs/ markdown
+specsmith sync                              # sync YAML → JSON → MD (YAML-first mode)
+specsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md from YAML
+specsmith validate --strict                 # YAML schema checks: dup IDs, orphans, coverage
 specsmith agent permissions-check git_push # check tool permission (REQ-012)
 specsmith ollama gpu                        # detect GPU VRAM, recommend context size
 specsmith export                            # generate full compliance report
+
+# Update channel management (REQ-248)
+specsmith channel set stable               # pin to stable releases
+specsmith channel set dev                  # opt in to dev/pre-release builds
+specsmith channel get --json               # show current channel + source
+
+# ESDB extended lifecycle (REQ-249..253)
+specsmith esdb export --json               # dump all records to JSON snapshot
+specsmith esdb import backup.json          # validate + stage an import
+specsmith esdb backup                      # create timestamped snapshot
+specsmith esdb rollback --steps 2          # report WAL rollback (stub)
+specsmith esdb compact                     # request WAL compaction
+
+# Skills lifecycle (REQ-254..255)
+specsmith skills deactivate <skill-id>     # set active=false in skill.json
+specsmith skills delete <skill-id> --yes   # permanently remove skill
+
+# MCP config generation (REQ-256)
+specsmith mcp generate "Search USPTO patents" --json  # JSON config stub
+
+# Agent ask dispatcher — no LLM required (REQ-257)
+specsmith agent ask "show esdb status" --json-output
+specsmith agent ask "build skill for summarizing"
 ```
 
 It also co-installs the standalone `epistemic` Python library for direct use in any project:
@@ -213,17 +238,47 @@ specsmith phase --project-dir ./my-project
 
 ---
 
-## Machine State Sync
+## Machine State Sync + YAML Governance
 
-`.specsmith/` always mirrors the human-readable `docs/` governance files.
-Run `specsmith sync` after any change to `docs/REQUIREMENTS.md` or `docs/TESTS.md`:
+As of v0.12, specsmith uses **YAML-first governance**: `docs/requirements/*.yml`
+and `docs/tests/*.yml` are the canonical sources. `REQUIREMENTS.md` and `TESTS.md`
+are **generated artifacts** — do not hand-edit them.
 
 ```bash
-specsmith sync                     # regenerate .specsmith/requirements.json + testcases.json
-specsmith sync --check             # CI mode: exits 1 if out of sync without writing
-specsmith sync --json              # emit sync result as JSON
+# YAML-first pipeline (v0.12+)
+specsmith sync                     # YAML → .specsmith/*.json → docs/*.md (all in one)
+specsmith generate docs            # regenerate only the Markdown artifacts from YAML
+specsmith generate docs --check    # dry-run: report what would change
+specsmith validate --strict        # enforce schema: dup IDs, orphans, missing fields
+specsmith validate --strict --json # machine-readable validation result
+
+# CI guard (already in .github/workflows/ci.yml)
+specsmith sync --check             # exits 1 if JSON cache is out of sync with YAML
 ```
 
+**To add a new requirement**, edit the appropriate `docs/requirements/<domain>.yml`
+file and run `specsmith sync`. **Never** hand-edit `docs/REQUIREMENTS.md` — it will
+be overwritten by the next sync.
+
+**Domain files:**
+
+| File | REQ range | Domain |
+|---|---|---|
+| `docs/requirements/governance.yml` | REQ-001..064 | Core AEE governance |
+| `docs/requirements/agent.yml` | REQ-065..129 | Nexus + CI |
+| `docs/requirements/harness.yml` | REQ-130..160 | Slash commands + subagents |
+| `docs/requirements/intelligence.yml` | REQ-161..220 | Instinct, eval, memory |
+| `docs/requirements/context.yml` | REQ-244..247 | Context window |
+| `docs/requirements/esdb.yml` | REQ-248..262 | ESDB + skills + MCP |
+| `docs/requirements/ai_intelligence.yml` | REQ-263..299 | AI model intelligence |
+| `docs/requirements/yaml_governance.yml` | REQ-300..312 | YAML governance layer |
+| `docs/requirements/multiagent_compliance.yml` | REQ-313..320 | Multi-agent governance traceability |
+| `docs/requirements/dispatch.yml` | REQ-321..334 | Multi-agent DAG dispatcher |
+
+**Migration from Markdown-primary:** Run
+`scripts/migrate_governance_to_yaml.py` once to convert an existing project.
+Idempotent — safe to re-run.
+
 ## Least-Privilege Agent Permissions (REG-012)
 
 ```bash
@@ -269,11 +324,11 @@ human oversight, and robustness. specsmith implements:
 across the AI lifecycle. specsmith addresses all four core functions:
 
 | NIST AI RMF Function | specsmith Mechanism |
-|---|---|
-| **GOVERN** — Policies & accountability | Governance rules (H1–H13), permissions profile, `scaffold.yml` policy |
-| **MAP** — Risk identification | AEE stress-test, belief graph, contradictions and uncertainty metrics |
-| **MEASURE** — Risk analysis | Confidence scoring, epistemic equilibrium, `specsmith epistemic-audit` |
-| **MANAGE** — Risk treatment | Kill-switch, escalation, bounded retry, safe-write backup, permissions deny-list |
+||---|
+|| **GOVERN** — Policies & accountability | Governance rules (H1–H22), permissions profile, `scaffold.yml` policy |
+|| **MAP** — Risk identification | AEE stress-test, belief graph, contradictions and uncertainty metrics |
+|| **MEASURE** — Risk analysis | Confidence scoring, epistemic equilibrium, `specsmith epistemic-audit` |
+|| **MANAGE** — Risk treatment | Kill-switch, escalation, bounded retry, safe-write backup, permissions deny-list |
 
 ### How Each Compliance Mechanism Works
 
@@ -526,6 +581,177 @@ requirement, test, and work-item identifiers Specsmith assigned.
 
 ---
 
+## AI Model Intelligence
+
+specsmith ships a complete AI model intelligence layer for tracking, scoring, and routing
+to the best available LLM for each task type.
+
+### HF Open LLM Leaderboard Sync (REQ-263..REQ-269)
+
+Syncs benchmark data from the HuggingFace Open LLM Leaderboard and computes three
+task-specific bucket scores — **reasoning**, **conversational**, and **longform** — for
+every model. A 40+ model static fallback ensures scores are always available even without
+network access.
+
+```bash
+specsmith model-intel sync                  # sync from HF leaderboard (static fallback if offline)
+specsmith model-intel scores                # list all cached bucket scores
+specsmith model-intel scores --model gpt-4o # show scores for a specific model
+specsmith model-intel recommendations       # top-10 models for reasoning bucket
+specsmith model-intel recommendations --bucket conversational  # or longform
+specsmith model-intel connection            # test HF API connectivity + token status
+```
+
+Set `SPECSMITH_HF_TOKEN` for authenticated access (1000 req/5min instead of 500).
+Scores persist to `~/.specsmith/model_scores.json`. Background sync runs 15s after startup
+then daily.
+
+**Bucket formulas (normalised 0-100):**
+- Reasoning = 0.35×MATH + 0.30×GPQA + 0.25×BBH + 0.10×IFEval
+- Conversational = 0.40×IFEval + 0.35×MMLU-PRO + 0.25×BBH
+- Longform = 0.35×MUSR + 0.35×IFEval + 0.30×MMLU-PRO
+
+### Model Capability Profiles (REQ-270..REQ-271)
+
+40+ pre-built model profiles cover all major providers (OpenAI, Anthropic, Google, Mistral,
+Meta Llama, Qwen, DeepSeek, and local Ollama variants). Each profile specifies:
+`max_tokens`, `prompt_style` (sections/xml/markdown), `supports_vision`,
+`supports_tool_calls`, `reasoning_mode`, and `context_window`.
+
+Context-aware history trimming preserves system messages while summarising older turns when
+the token budget is exceeded:
+
+```python
+from specsmith.agent.model_profiles import get_profile, trim_history
+
+profile = get_profile("qwen2.5:14b")   # exact or prefix match; returns default if unknown
+messages = trim_history(messages, budget_chars=12000)
+```
+
+### LLM Client with Provider Fallback (REQ-275..REQ-277)
+
+`LLMClient` wraps multiple providers with automatic fallback on 429 / 401 errors,
+O-series parameter translation (`max_completion_tokens`, temperature=1, developer role),
+and vLLM guided-JSON payload injection:
+
+```python
+from specsmith.agent.llm_client import LLMClient
+
+client = LLMClient([
+    {"provider_type": "cloud", "model": "gpt-4o", ...},
+    {"provider_type": "ollama", "model": "qwen2.5:14b", ...},  # local fallback
+])
+result = client.chat([{"role": "user", "content": "hello"}])
+```
+
+### Endpoint Presets + Suggest Profiles (REQ-278..REQ-280)
+
+A registry of 10+ pre-configured endpoint presets for common cloud and local LLM providers:
+
+```bash
+specsmith agent endpoint-presets            # list all presets (vllm, lm_studio, openrouter, etc.)
+specsmith agent endpoint-presets --json     # machine-readable output
+specsmith agent suggest-profiles            # suggest optimal profiles based on env (API keys, hardware)
+specsmith agent suggest-profiles --json     # structured suggestions with bucket/role annotations
+```
+
+Suggestions are read-only (never persisted) and inspect `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+`GOOGLE_API_KEY`, and local Ollama availability.
+
+### Kairos AI Providers — Bucket Score Columns (REQ-281)
+
+The Kairos **Agents > AI Providers** table gained three new columns — **R** (reasoning),
+**C** (conversational), **L** (longform) — showing each provider's HF bucket scores inline.
+A **Sync Scores** button triggers a background sync from the HF leaderboard without
+interrupting the active session.
+
+---
+
+## Multi-Agent DAG Dispatcher (REQ-321..334)
+
+The `specsmith dispatch` command group decomposes a task into a **Directed Acyclic Graph** of
+agent work items and executes them concurrently, with fail-forward BLOCKED propagation and
+ESDB context injection between nodes.
+
+```bash
+# Run a task through the DAG dispatcher (default: up to 4 concurrent workers)
+specsmith dispatch run "add API endpoint with tests" --max-workers 4
+
+# Stream JSONL events while the run is in progress
+specsmith dispatch run "refactor auth module" --json
+
+# Check status of a saved run
+specsmith dispatch status --dag-id abc123def456
+
+# List all saved runs
+specsmith dispatch list
+
+# Retry a single failed node from a checkpoint
+specsmith dispatch retry --node impl --dag-id abc123def456
+```
+
+The dispatcher is also available programmatically:
+
+```python
+from specsmith.agent.orchestrator import Orchestrator
+
+orchestrator = Orchestrator()
+
+# Use the DAG path (falls back to GroupChat on cycle detection)
+result = orchestrator.run_task("add feature X", use_dag=True)
+
+# Always use DAG — returns DispatchSummary with per-node outcomes
+summary = orchestrator.run_dispatch(
+    "add feature X",
+    planner_output=[
+        {"id": "arch", "title": "Design", "role": "architect", "depends_on": []},
+        {"id": "impl", "title": "Implement", "role": "coder", "depends_on": ["arch"]},
+        {"id": "test", "title": "Write tests", "role": "tester", "depends_on": ["arch"]},
+    ],
+    max_workers=3,
+)
+print(f"{len(summary.completed)} completed, {len(summary.failed)} failed")
+```
+
+Events are persisted to `.specsmith/dispatch/<dag_id>/events.jsonl` for resume and replay.
+Kairos renders the live dispatch view — see `app/` for build instructions.
+
+---
+
+## Compiler and Tool Support
+
+All agent roles can invoke compiler, linter, and formatter tools. These are registered in
+`AVAILABLE_TOOLS` and wired into `ROLE_TOOLS` for the `coder`, `reviewer`, `tester`, `architect`,
+and `embedded-coder` roles.
+
+| Tool | Function | Default binary |
+|------|----------|-|
+| GCC / G++ | `run_gcc(args, compiler='gcc')` | `gcc` / `g++` |
+| ARM bare-metal | `run_arm_gcc(args, compiler='arm-none-eabi-gcc')` | `arm-none-eabi-gcc` |
+| AArch64 Linux | `run_aarch64_gcc(args, compiler='aarch64-linux-gnu-gcc')` | `aarch64-linux-gnu-gcc` |
+| IAR Embedded | `run_iar_compiler(project_file, executable='IarBuild')` | `IarBuild` |
+| Intel oneAPI | `run_intel_compiler(args, compiler='icx')` | `icx` / `icpx` / `icc` |
+| clang-format | `run_clang_format(files, style='file', in_place=False)` | `clang-format` |
+| clang-tidy | `run_clang_tidy(files, checks='', fix=False)` | `clang-tidy` |
+| VSG (VHDL) | `run_vsg(files, rules=None, fix=False)` | `vsg` |
+
+All tools are usable directly in the agentic REPL and in `specsmith dispatch` worker nodes:
+
+```python
+from specsmith.agent.tools import run_arm_gcc, run_clang_tidy, run_vsg
+
+# Cross-compile for ARM bare-metal
+result = run_arm_gcc("-Wall -O2 main.c -o firmware.elf", compiler="arm-none-eabi-gcc")
+
+# Lint C/C++ with clang-tidy
+result = run_clang_tidy("src/", checks="modernize-*,readability-*")
+
+# Style-check VHDL files
+result = run_vsg("rtl/top.vhd", rules="vsg_rules.yaml")
+```
+
+---
+
 ## Kairos — Flagship Terminal Client
 
 **[Kairos](https://github.com/BitConcepts/kairos)** is the recommended terminal client for specsmith.
@@ -538,7 +764,14 @@ specsmith status, version, and one-click update.
 specsmith governance-serve --port 7700 --project-dir .
 ```
 
-The VS Code extension (`specsmith-vscode`) has been **deprecated** in favour of Kairos.
+The Kairos **Dispatch Panel** (`app/` — Rust, egui/eframe) renders the multi-agent DAG live:
+- SVG DAG graph with nodes coloured by status (grey/blue/green/red/amber)
+- Gantt timeline strip showing parallelism
+- Per-node Retry (FAILED/BLOCKED) and Abort (RUNNING) buttons
+- Subscribes to `GET /api/dispatch/events?dag_id=` SSE from `specsmith serve`
+
+Build Kairos dispatch panel: `cd app && cargo build --release`
+
 Use `pipx install specsmith` for standalone CLI usage from any terminal.
 
 ---
@@ -605,7 +838,11 @@ Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
 
 **Workflow:** `phase show/set/next/list` `ledger add/list` `req list/add/gaps/trace`
 
-**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills`
+**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills` `agent suggest-profiles` `agent endpoint-presets`
+
+**Dispatch:** `dispatch run` `dispatch status` `dispatch list` `dispatch retry`
+
+**Model Intel:** `model-intel sync` `model-intel scores` `model-intel recommendations` `model-intel connection`
 
 **Ollama:** `ollama list/available/gpu/pull/suggest`
 
@@ -658,13 +895,42 @@ Use cases: linguistics research, compliance pipelines, AI alignment, patent pros
 
 ---
 
-## Governance Rules (H1–H13)
-
-13 hard rules enforced by `specsmith validate`:
-
-- **H11** — Every loop or blocking wait must have a timeout, fallback exit, and diagnostic message.
-- **H12** — Windows multi-step automation goes into `.cmd` files, not inline shell invocations.
-- **H13** — Agent tools must declare epistemic contracts (what they claim and what they cannot detect).
+## Governance Rules (H1–H22)
+
+22 hard rules enforced by `specsmith validate` and `specsmith audit`.
+Full rule text: [`docs/governance/RULES.md`](docs/governance/RULES.md)
+
+**H1–H14 — Core engineering and traceability rules:**
+- **H1** — No ledger entry = work not done.
+- **H2** — No proposal = no execution.
+- **H3** — All work must consider every target platform.
+- **H4** — No system-dependent assumptions; virtual environments required.
+- **H5** — No hidden service logic.
+- **H6** — If the task grows beyond the proposal, stop and re-propose.
+- **H7** — Every state change must be traceable and recorded.
+- **H8** — Architecture changes MUST update docs in the same work cycle.
+- **H9** — Every agent command must have a timeout.
+- **H10** — No hardcoded version strings outside `pyproject.toml`.
+- **H11** — Every loop must have a deadline; no unbounded blocking I/O.
+- **H12** — Platform-aware automation: sh/bash on Unix, `.cmd`/`.ps1` on Windows.
+- **H13** — Every proposal must declare its epistemic boundaries and assumptions.
+- **H14** — Documentation must be updated in the same work cycle as code changes.
+
+**H15–H22 — Anti-hallucination and epistemic stability (OEA framework):**
+
+Rules H15–H22 are derived from the *"Ontology-Epistemic-Agentic (OEA) Recursive
+Generative Stability"* study (BitConcepts Research, 2026), which empirically validated
+the primary control mechanisms for preventing hallucination and semantic drift in
+production LLM systems:
+
+- **H15** — Epistemic scope bounding: no claims outside verified knowledge; say "unknown" rather than fabricate.
+- **H16** — Anti-drift recursion guard: max 5 autonomous generation steps before a human checkpoint.
+- **H17** — Calibration direction: express uncertainty, not false confidence.
+- **H18** — RAG retrieval filtering: validate context relevance (similarity ≥ 0.6) before injection.
+- **H19** — Synthetic contamination prevention: never mix synthetic and real data silently.
+- **H20** — Falsifiability required: cite sources or flag claims as `[HYPOTHESIS]`.
+- **H21** — Disclose all model-specific assumptions (context window, format, temperature).
+- **H22** — Cross-platform CI: green on one OS ≠ cross-platform coverage.
 
 ---