stateprobe 0.3.1

The attention layer for LLM agents — see what the model fires before it ships.

StateProbe

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.

For closed-source agents, this is fast task-level attention inferred from text. Open-weight models unlock the optional Lab / future Runtime Probe path for activations and vectors.

English | 简体中文

---

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

pip install stateprobe

For MCP integration (Claude Code, Cursor, Cline, Continue):

pip install "stateprobe[mcp]"

For activation projection on open-source DeepSeek (optional):

pip install "stateprobe[lab]"

30-second demo

Copy-paste this after pip install stateprobe to catch a bad plan before it ships:

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:

stateprobe skill overlay \
  --context-text "Focus on safety; do not include deprecated APIs." \
  --output-text "The answer recommends a deprecated API first."

Or run the legacy prompt diagnostic, with the included smart_but_not_answering demo:

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, MCP server.

Two product lines

Line	What	Status
Skill — Agent Attention HUD	Shipped external control layer. Text-to-text task attention, preview before output, overlay after output, control levers for the next turn. Works with closed and open models.	✅ Shipped
Lab — Activation Projection	Opt-in open-weight lab path. Projects prompt activations onto Persona Vectors on DeepSeek-R1-Distill-Qwen. Requires local model access.	✅ Available / experimental
Enterprise — Runtime Probe	Future production line for hidden states, router traces, expert routing, output-state reports, and operator controls on open-weight models.	🛠 Placeholder only

Boundary: the Skill HUD never claims neural interpretability; it makes task-level attention visible and steerable from text. Closed-source APIs (OpenAI, Claude) cannot expose hidden states — OpenAI/Claude 物理上读不到 hidden states — so they run the Skill layer only. Open-source models (DeepSeek, Qwen, Llama) unlock the Lab path today and the future Runtime Probe line later.

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): 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
• DeepSeek-AI — DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning

DeepSeek-first, not DeepSeek-only — see DeepSeek roadmap.

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 for the full version history.

Documentation

• Skill spec — attention HUD reference
• MCP server — Claude Code / Cursor / Cline / Continue setup
• Architecture — hybrid evidence pipeline
• FAQ — common objections answered

More docs — evidence model, ADRs, roadmaps, contributor guides

• Evidence model — three-layer evidence boundaries
• DeepSeek roadmap — DeepSeek-first, not DeepSeek-only
• Architecture decisions — ADRs for hybrid pipeline and lab contributor
• Publishing — release process
• CHANGELOG / CITATION / CODE_OF_CONDUCT / CONTRIBUTING

中文文档（含 China 镜像、PowerShell 编码 fix、完整命令样例）：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.

python scripts/acceptance_check.py

License

MIT — see 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.