stateprobe 0.3.0__tar.gz

stateprobe-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StateProbe Contributors
+
+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.

stateprobe-0.3.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: stateprobe
+Version: 0.3.0
+Summary: The attention layer for LLM agents — see what the model fires before it ships.
+Author: StateProbe Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Erye932/stateprobe
+Project-URL: Issues, https://github.com/Erye932/stateprobe/issues
+Keywords: llm,agent,mcp,claude-code,prompt-engineering,prompt-debugging,llm-evaluation,persona-vectors,activation-steering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: mcp>=1.7.1; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Provides-Extra: lab
+Requires-Dist: torch>=2.2.0; extra == "lab"
+Requires-Dist: transformers>=4.40.0; extra == "lab"
+Requires-Dist: accelerate>=0.28.0; extra == "lab"
+Requires-Dist: safetensors>=0.4.0; extra == "lab"
+Requires-Dist: numpy>=1.26.0; extra == "lab"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.7.1; extra == "mcp"
+Dynamic: license-file
+
+# StateProbe
+
+[![PyPI](https://img.shields.io/pypi/v/stateprobe.svg)](https://pypi.org/project/stateprobe/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Tests](https://github.com/Erye932/stateprobe/actions/workflows/ci.yml/badge.svg)](https://github.com/Erye932/stateprobe/actions/workflows/ci.yml)
+
+> **The attention layer for LLM agents.**
+
+Your agent already drifted — wrong focus, stale context, confidently editing files you never asked about. StateProbe catches it **before** the agent ships the answer. Works with **Claude Code**, **Cursor**, **Cline**, **Continue**, and any MCP host.
+
+English | [简体中文](README.zh-CN.md)
+
+---
+
+## Why
+
+LLM agents drift. They miss the user's actual point, get steered by stale context, or burn cycles on the wrong subtopic. Today's fix is "rewrite the prompt and pray." StateProbe gives you a sharper tool:
+
+- **See** what the agent is about to focus on, before it answers
+- **Decide** to continue, rewrite the focus, ask a boundary question, or cut stale context
+- **Audit** the actual output afterwards and surface drift
+
+Runs **locally**. Costs **zero LLM tokens** by default. Plugs into any MCP host.
+
+## Install
+
+```bash
+pip install stateprobe
+```
+
+For MCP integration (Claude Code, Cursor, Cline, Continue):
+
+```bash
+pip install "stateprobe[mcp]"
+```
+
+For activation projection on open-source DeepSeek (optional):
+
+```bash
+pip install "stateprobe[lab]"
+```
+
+## 30-second demo
+
+Before the agent answers, preview its planned focus:
+
+```bash
+stateprobe skill preview \
+  --context-text "Focus on safety; do not include deprecated APIs." \
+  --plan-text "I will list deprecated APIs and explain why they are unsafe."
+```
+
+After the agent answers, audit alignment with user requirements:
+
+```bash
+stateprobe skill overlay \
+  --context examples/skill_attention_context.txt \
+  --output examples/skill_attention_output.txt
+```
+
+Or run the legacy prompt diagnostic, with the included
+[`smart_but_not_answering`](demos/smart_but_not_answering) demo:
+
+```bash
+stateprobe demo
+```
+
+## What it gives back
+
+`stateprobe skill preview` returns a JSON `activation_decision` — your agent host branches on it:
+
+| Action | Meaning |
+| --- | --- |
+| `continue` | Aligned. Agent can speak. |
+| `rewrite_planned_focus` | Plan misses user's actual must. **Don't ship.** Rewrite focus first. |
+| `ask_boundary_question` | Visual / creative ambiguity. **Ask the user one yes/no first.** |
+| `cut_context_contamination` | Agent is following stale context. **Cut the old direction first.** |
+
+`stateprobe skill overlay` returns an `interrupt_level` (`ok` / `watch` / `interrupt`) plus `attention_gaps` and `control_levers` for the next turn.
+
+Full schemas: [Skill spec](docs/SKILL_ATTENTION_HUD.md), [MCP server](docs/MCP_SERVER.md).
+
+## Two product lines
+
+| Line | What | Status |
+| --- | --- | --- |
+| **Skill — Agent Attention HUD** | External control layer. Text-to-text task attention. Works with closed and open models. | ✅ Available |
+| **Lab — Activation Projection** | Projects prompt activations onto Persona Vectors on open-source DeepSeek-R1-Distill-Qwen. Opt-in. | ✅ Available |
+| **Enterprise — Runtime Probe** | Future direction: hidden states, router traces, expert routing on open-source models. | 🛠 Not yet implemented |
+
+**Boundary**: closed-source APIs (OpenAI, Claude) cannot expose hidden states — for them, StateProbe runs the text-level Skill layer only. Open-source models (DeepSeek, Qwen, Llama) unlock the Lab layer. OpenAI/Claude 物理上读不到 hidden states; the Lab layer requires open weights.
+
+## How it differs
+
+|  | promptfoo | Guardrails AI | LangSmith | **StateProbe** |
+| --- | --- | --- | --- | --- |
+| Analyzes | Output quality | Output safety | Call traces | **Agent's planned attention before output** |
+| When | After release | Runtime | Production | **Before each turn** |
+| LLM API needed | Yes | Yes | Yes | **No (default)** |
+
+Complementary, not competitive. promptfoo / Guardrails check what came out; StateProbe shapes what's about to come out.
+
+## Architecture
+
+Hybrid evidence pipeline ([ADR_009](docs/adr/009-hybrid-engine.md)): independent contributors emit confidence-weighted evidence, aggregated into 8 behavior axes. Static rules are always on (zero cost); the LLM and Lab layers are opt-in and stack on top.
+
+| Layer | Purpose | Cost |
+| --- | --- | --- |
+| **Static Mode** (`StaticRuleContributor`) | Regex rules. Always on. | Zero |
+| **LLM judge** (`LLMJudgeContributor`) | LLM semantic evidence. Opt-in via `--llm-augment`. | API call |
+| **DeepSeek Lab** (`LabContributor`) | Hidden-state projection on DeepSeek-R1-Distill-Qwen-1.5B. Opt-in via `--lab-augment`. | Local GPU |
+| **Black-box Eval** (independent) | Runs original / rewritten prompts on a target model and scores outputs. | API call |
+
+Theoretical foundation:
+
+- Anthropic — [Persona Vectors: Monitoring and Controlling Character Traits in Language Models](https://arxiv.org/abs/2507.21509)
+- DeepSeek-AI — [DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning](https://arxiv.org/abs/2501.12948)
+
+DeepSeek-first, not DeepSeek-only — see [DeepSeek roadmap](docs/DEEPSEEK_ROADMAP.md).
+
+## Roadmap
+
+- **v0.3** *(current)* — Skill HUD, MCP server, Lab activation projection on 4 axes
+- **v0.3.1** — Remaining 4 axes; embedding contributor for offline fallback; VS Code / Cursor extension
+- **v0.4** — MoE expert routing contributor on DeepSeek-MoE
+- **v0.5** — Named steering vectors; output-time intervention API
+
+See [CHANGELOG](CHANGELOG.md) for the full version history.
+
+## Documentation
+
+- [Skill spec](docs/SKILL_ATTENTION_HUD.md) — attention HUD reference
+- [MCP server](docs/MCP_SERVER.md) — Claude Code / Cursor / Cline / Continue setup
+- [Architecture](docs/ARCHITECTURE.md) — hybrid evidence pipeline
+- [FAQ](docs/FAQ.md) — common objections answered
+
+<details>
+<summary><b>More docs</b> — evidence model, ADRs, roadmaps, contributor guides</summary>
+
+- [Evidence model](docs/EVIDENCE_MODEL.md) — three-layer evidence boundaries
+- [DeepSeek roadmap](docs/DEEPSEEK_ROADMAP.md) — DeepSeek-first, not DeepSeek-only
+- [Architecture decisions](docs/adr/) — ADRs for hybrid pipeline and lab contributor
+- [Publishing](docs/PUBLISHING.md) — release process
+- [CHANGELOG](CHANGELOG.md) / [CITATION](CITATION.cff) / [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) / [CONTRIBUTING](CONTRIBUTING.md)
+
+</details>
+
+中文文档（含 China 镜像、PowerShell 编码 fix、完整命令样例）：[README.zh-CN.md](README.zh-CN.md)
+
+## Contributing
+
+Rule library quality = the project's core value. If you find a prompt pattern that isn't detected, a misfire, or want a new target preset — open an issue or PR.
+
+Each rule contribution must include: pattern / affected axis / direction / weight / **mechanism** / **paper citation**. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+python scripts/acceptance_check.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Built on Anthropic interpretability and DeepSeek-AI open research. This tool turns those findings into something agent hosts and prompt engineers can use every day, without having to actually answer the question of how the model "thinks" — just what it's about to focus on next.

stateprobe-0.3.0/README.md

@@ -0,0 +1,167 @@
+# StateProbe
+
+[![PyPI](https://img.shields.io/pypi/v/stateprobe.svg)](https://pypi.org/project/stateprobe/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Tests](https://github.com/Erye932/stateprobe/actions/workflows/ci.yml/badge.svg)](https://github.com/Erye932/stateprobe/actions/workflows/ci.yml)
+
+> **The attention layer for LLM agents.**
+
+Your agent already drifted — wrong focus, stale context, confidently editing files you never asked about. StateProbe catches it **before** the agent ships the answer. Works with **Claude Code**, **Cursor**, **Cline**, **Continue**, and any MCP host.
+
+English | [简体中文](README.zh-CN.md)
+
+---
+
+## Why
+
+LLM agents drift. They miss the user's actual point, get steered by stale context, or burn cycles on the wrong subtopic. Today's fix is "rewrite the prompt and pray." StateProbe gives you a sharper tool:
+
+- **See** what the agent is about to focus on, before it answers
+- **Decide** to continue, rewrite the focus, ask a boundary question, or cut stale context
+- **Audit** the actual output afterwards and surface drift
+
+Runs **locally**. Costs **zero LLM tokens** by default. Plugs into any MCP host.
+
+## Install
+
+```bash
+pip install stateprobe
+```
+
+For MCP integration (Claude Code, Cursor, Cline, Continue):
+
+```bash
+pip install "stateprobe[mcp]"
+```
+
+For activation projection on open-source DeepSeek (optional):
+
+```bash
+pip install "stateprobe[lab]"
+```
+
+## 30-second demo
+
+Before the agent answers, preview its planned focus:
+
+```bash
+stateprobe skill preview \
+  --context-text "Focus on safety; do not include deprecated APIs." \
+  --plan-text "I will list deprecated APIs and explain why they are unsafe."
+```
+
+After the agent answers, audit alignment with user requirements:
+
+```bash
+stateprobe skill overlay \
+  --context examples/skill_attention_context.txt \
+  --output examples/skill_attention_output.txt
+```
+
+Or run the legacy prompt diagnostic, with the included
+[`smart_but_not_answering`](demos/smart_but_not_answering) demo:
+
+```bash
+stateprobe demo
+```
+
+## What it gives back
+
+`stateprobe skill preview` returns a JSON `activation_decision` — your agent host branches on it:
+
+| Action | Meaning |
+| --- | --- |
+| `continue` | Aligned. Agent can speak. |
+| `rewrite_planned_focus` | Plan misses user's actual must. **Don't ship.** Rewrite focus first. |
+| `ask_boundary_question` | Visual / creative ambiguity. **Ask the user one yes/no first.** |
+| `cut_context_contamination` | Agent is following stale context. **Cut the old direction first.** |
+
+`stateprobe skill overlay` returns an `interrupt_level` (`ok` / `watch` / `interrupt`) plus `attention_gaps` and `control_levers` for the next turn.
+
+Full schemas: [Skill spec](docs/SKILL_ATTENTION_HUD.md), [MCP server](docs/MCP_SERVER.md).
+
+## Two product lines
+
+| Line | What | Status |
+| --- | --- | --- |
+| **Skill — Agent Attention HUD** | External control layer. Text-to-text task attention. Works with closed and open models. | ✅ Available |
+| **Lab — Activation Projection** | Projects prompt activations onto Persona Vectors on open-source DeepSeek-R1-Distill-Qwen. Opt-in. | ✅ Available |
+| **Enterprise — Runtime Probe** | Future direction: hidden states, router traces, expert routing on open-source models. | 🛠 Not yet implemented |
+
+**Boundary**: closed-source APIs (OpenAI, Claude) cannot expose hidden states — for them, StateProbe runs the text-level Skill layer only. Open-source models (DeepSeek, Qwen, Llama) unlock the Lab layer. OpenAI/Claude 物理上读不到 hidden states; the Lab layer requires open weights.
+
+## How it differs
+
+|  | promptfoo | Guardrails AI | LangSmith | **StateProbe** |
+| --- | --- | --- | --- | --- |
+| Analyzes | Output quality | Output safety | Call traces | **Agent's planned attention before output** |
+| When | After release | Runtime | Production | **Before each turn** |
+| LLM API needed | Yes | Yes | Yes | **No (default)** |
+
+Complementary, not competitive. promptfoo / Guardrails check what came out; StateProbe shapes what's about to come out.
+
+## Architecture
+
+Hybrid evidence pipeline ([ADR_009](docs/adr/009-hybrid-engine.md)): independent contributors emit confidence-weighted evidence, aggregated into 8 behavior axes. Static rules are always on (zero cost); the LLM and Lab layers are opt-in and stack on top.
+
+| Layer | Purpose | Cost |
+| --- | --- | --- |
+| **Static Mode** (`StaticRuleContributor`) | Regex rules. Always on. | Zero |
+| **LLM judge** (`LLMJudgeContributor`) | LLM semantic evidence. Opt-in via `--llm-augment`. | API call |
+| **DeepSeek Lab** (`LabContributor`) | Hidden-state projection on DeepSeek-R1-Distill-Qwen-1.5B. Opt-in via `--lab-augment`. | Local GPU |
+| **Black-box Eval** (independent) | Runs original / rewritten prompts on a target model and scores outputs. | API call |
+
+Theoretical foundation:
+
+- Anthropic — [Persona Vectors: Monitoring and Controlling Character Traits in Language Models](https://arxiv.org/abs/2507.21509)
+- DeepSeek-AI — [DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning](https://arxiv.org/abs/2501.12948)
+
+DeepSeek-first, not DeepSeek-only — see [DeepSeek roadmap](docs/DEEPSEEK_ROADMAP.md).
+
+## Roadmap
+
+- **v0.3** *(current)* — Skill HUD, MCP server, Lab activation projection on 4 axes
+- **v0.3.1** — Remaining 4 axes; embedding contributor for offline fallback; VS Code / Cursor extension
+- **v0.4** — MoE expert routing contributor on DeepSeek-MoE
+- **v0.5** — Named steering vectors; output-time intervention API
+
+See [CHANGELOG](CHANGELOG.md) for the full version history.
+
+## Documentation
+
+- [Skill spec](docs/SKILL_ATTENTION_HUD.md) — attention HUD reference
+- [MCP server](docs/MCP_SERVER.md) — Claude Code / Cursor / Cline / Continue setup
+- [Architecture](docs/ARCHITECTURE.md) — hybrid evidence pipeline
+- [FAQ](docs/FAQ.md) — common objections answered
+
+<details>
+<summary><b>More docs</b> — evidence model, ADRs, roadmaps, contributor guides</summary>
+
+- [Evidence model](docs/EVIDENCE_MODEL.md) — three-layer evidence boundaries
+- [DeepSeek roadmap](docs/DEEPSEEK_ROADMAP.md) — DeepSeek-first, not DeepSeek-only
+- [Architecture decisions](docs/adr/) — ADRs for hybrid pipeline and lab contributor
+- [Publishing](docs/PUBLISHING.md) — release process
+- [CHANGELOG](CHANGELOG.md) / [CITATION](CITATION.cff) / [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) / [CONTRIBUTING](CONTRIBUTING.md)
+
+</details>
+
+中文文档（含 China 镜像、PowerShell 编码 fix、完整命令样例）：[README.zh-CN.md](README.zh-CN.md)
+
+## Contributing
+
+Rule library quality = the project's core value. If you find a prompt pattern that isn't detected, a misfire, or want a new target preset — open an issue or PR.
+
+Each rule contribution must include: pattern / affected axis / direction / weight / **mechanism** / **paper citation**. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+python scripts/acceptance_check.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Built on Anthropic interpretability and DeepSeek-AI open research. This tool turns those findings into something agent hosts and prompt engineers can use every day, without having to actually answer the question of how the model "thinks" — just what it's about to focus on next.

stateprobe-0.3.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stateprobe"
+version = "0.3.0"
+description = "The attention layer for LLM agents — see what the model fires before it ships."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+    { name = "StateProbe Contributors" }
+]
+keywords = ["llm", "agent", "mcp", "claude-code", "prompt-engineering", "prompt-debugging", "llm-evaluation", "persona-vectors", "activation-steering"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "click>=8.1.0",
+    "rich>=13.7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mcp>=1.7.1",
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+lab = [
+    "torch>=2.2.0",
+    "transformers>=4.40.0",
+    "accelerate>=0.28.0",
+    "safetensors>=0.4.0",
+    "numpy>=1.26.0",
+]
+mcp = [
+    "mcp>=1.7.1",
+]
+
+[project.scripts]
+stateprobe = "stateprobe.cli:main"
+stateprobe-mcp = "stateprobe.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/Erye932/stateprobe"
+Issues = "https://github.com/Erye932/stateprobe/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stateprobe*"]
+
+[tool.setuptools.package-data]
+stateprobe = ["templates/*.html"]

stateprobe-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stateprobe-0.3.0/stateprobe/__init__.py

@@ -0,0 +1,53 @@
+"""StateProbe — Prompt State Debugger.
+
+Diagnose which behavioral vectors your prompt activates in an LLM,
+identify pollution sources, and get rewrite suggestions to reach a target state.
+
+Theoretical foundation:
+- Anthropic, "Persona Vectors: Monitoring and Controlling Character Traits in
+  Language Models" (arXiv:2507.21509, 2025)
+- DeepSeek-AI, "DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via
+  Reinforcement Learning" (arXiv:2501.12948, 2025)
+"""
+
+__version__ = "0.3.0"
+
+from stateprobe.models import (
+    Axis,
+    AxisReading,
+    PollutionSource,
+    Report,
+    TargetPreset,
+)
+from stateprobe.detector import diagnose
+from stateprobe.rewriter import suggest_rewrite
+from stateprobe.engines import (
+    Engine,
+    EngineError,
+    EngineUnavailable,
+    EvidenceContributor,
+    LLMJudgeContributor,
+    LLMJudgeEngine,
+    StaticEngine,
+    StaticRuleContributor,
+)
+
+__all__ = [
+    "Axis",
+    "AxisReading",
+    "PollutionSource",
+    "Report",
+    "TargetPreset",
+    "diagnose",
+    "suggest_rewrite",
+    "EvidenceContributor",
+    "EngineError",
+    "EngineUnavailable",
+    "StaticRuleContributor",
+    "LLMJudgeContributor",
+    # Deprecated aliases (removed in v0.3):
+    "Engine",
+    "StaticEngine",
+    "LLMJudgeEngine",
+    "__version__",
+]

stateprobe-0.3.0/stateprobe/__main__.py

@@ -0,0 +1,13 @@
+"""Entry point for ``python -m stateprobe``.
+
+Forwards to the standard CLI defined by ``[project.scripts] stateprobe`` so
+users who don't have the ``stateprobe`` script on PATH (e.g. ``pip install
+--user`` without PATH set, or running directly from a checkout) can still
+invoke the CLI in the conventional way.
+"""
+
+from stateprobe.cli import main
+
+
+if __name__ == "__main__":
+    main()