entropy-sdk 0.1.5__tar.gz

entropy_sdk-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wang Miaosheng / CYD-PRC
+
+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.

entropy_sdk-0.1.5/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: entropy-sdk
+Version: 0.1.5
+Summary: Gear-based safety control layer for autonomous agents (EntropyRuntime core, embeddable SDK)
+Author-email: Wang Miaosheng <wmsmiaosheng@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/CYD-PRC/entropy-sdk
+Project-URL: Paper, https://arxiv.org/abs/2607.00334
+Keywords: ai-safety,agent,governance,runtime-verification,gear
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core<1.0,>=0.2.43; extra == "langchain"
+Provides-Extra: pydanticai
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# entropy-sdk
+
+**An embeddable, gear-based safety control layer for autonomous agents** — the
+SDK distillation of the EntropyRuntime paper's core abstractions
+([arXiv:2607.00334](https://arxiv.org/abs/2607.00334)).
+
+> Make an AI's degree of autonomy observable, governable, and accountable.
+
+[![test](https://github.com/CYD-PRC/entropy-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/CYD-PRC/entropy-sdk/actions/workflows/test.yml)
+![license](https://img.shields.io/badge/license-MIT-blue)
+![python](https://img.shields.io/badge/python-%3E%3D3.10-blue)
+
+> Test readings are reported from **raw CI logs, not badge conclusions**:
+> latest verified reading — **96 passed / 0 skipped** across Python 3.10–3.13
+> (Actions run inspected line-by-line). A green badge alone is not evidence.
+
+Unlike [CYD-PRC/entropyruntime](https://github.com/CYD-PRC/entropyruntime)
+(the full production system — FastAPI + PostgreSQL + Redis + OPA), this
+repository is the **zero-dependency, embeddable** minimal control layer:
+`pip install` and five lines of code wire it into any agent loop.
+
+## Core abstractions
+
+| Abstraction | Paper | SDK |
+|---|---|---|
+| Five-level gear ladder G0–G4 | Definition 1 (𝒜₀⊂…⊂𝒜₄) | `Gear` |
+| Utility gate U(s,a) ≥ θ | Definitions 2–3, Theorem 2 | `UtilityGate` |
+| Slow-up-fast-down state machine | §4 Gear state machine | `GearPolicy` |
+| Event-driven fallback | Theorem 4 | `FallbackConfig` |
+| Runtime state ρ=(g,σ,ϵ) | Definition 4 | `RuntimeState` |
+| Audit chain | §5/§8 empirical requirements | `AuditLog` (append-only JSONL) |
+
+## Design rules
+
+1. **Pure stdlib core, zero dependencies.** Framework adapters (LangChain /
+   PydanticAI) ship as optional extras.
+2. **fail-closed.** The utility function must be injected explicitly; there is
+   no fail-open switch — the utility gate is the sole dispatch channel
+   (Theorem 2, enforced in code).
+3. **Audit chain built in.** Every gate decision, gear transition, and
+   suspension is appended to JSONL. `gate_acceptance_rate()` and
+   `gear_histogram()` produce the empirical data that the paper's Theorem 1
+   assumption and Theorem 3 prediction call for.
+
+## Quickstart
+
+```bash
+pip install entropy-sdk
+```
+
+```python
+from entropy_sdk import EntropyRuntime, Gear, action, observe
+
+# 1. Inject your domain utility function (the SDK ships no built-in U)
+def my_utility(state, act):
+    return state.task_gain(act) + 2.0 * state.safety(act) - 0.5 * act.cost
+
+# Note: action()'s **kwargs are call parameters of the wrapped function,
+# not utility metadata. Feed metadata to the utility via post-creation
+# assignment (act.utility_value = ... style).
+# 2. Create the runtime (theta is the only safety-vs-output knob)
+runtime = EntropyRuntime(utility=my_utility, theta=0.15,
+                         audit_log="audit.jsonl")
+
+# 3. Every agent action goes through the gate
+result = runtime.step(
+    state=my_state,
+    action=action(delete_records, "users", required_gear=Gear.EXECUTE),
+    execute=lambda a: a(),
+    propose_alternative=my_fallback_planner,  # optional: rejected-action fallback
+)
+
+if result.suspended:
+    alert_human()          # m consecutive rejections -> suspend at G0, await review
+    runtime.resume()       # after human review, gears must be re-earned
+```
+
+### Gear semantics
+
+| Gear | Name | Permitted actions |
+|---|---|---|
+| G0 | Observe | Read-only observation, safe holding |
+| G1 | Suggest | Side-effect-free candidate plans |
+| G2 | Plan | Bounded, reversible recovery actions |
+| G3 | Execute | Independently chosen side-effecting actions |
+| G4 | Integrate | System-level coordination (an emergent property of all-G3 fleets) |
+
+**Slow up, fast down** (earned autonomy): escalation requires σ < σ_low **and**
+h consecutive clean cycles — every gear must be re-earned (v0.1.2+);
+de-escalation on σ overflow or error is immediate. Autonomy is earned, and it
+can always be revoked.
+
+A runnable version of this narrative lives in
+[`examples/lifecycle_demo.py`](examples/lifecycle_demo.py)
+(`python examples/lifecycle_demo.py`).
+
+## Framework adapters
+
+```python
+# LangChain: pip install entropy-sdk[langchain]
+from entropy_sdk.adapters.langchain import gated_tool
+safe_tool = gated_tool(runtime, my_tool, required_gear=Gear.EXECUTE)
+
+# PydanticAI-compatible callable decorator: pip install entropy-sdk[pydanticai]
+from entropy_sdk.adapters.pydanticai import gated
+
+@gated(runtime, required_gear=Gear.EXECUTE)
+def delete_records(table: str) -> str: ...
+```
+
+On rejection the adapters **return an explanatory string instead of raising** —
+rejection itself is feedback the agent can act on next turn.
+
+(Note on naming: this is a **PydanticAI-compatible callable decorator**, not a
+true PydanticAI adapter — it is a pure stdlib decorator with zero framework
+dependencies (the `pydanticai` extra list is intentionally empty, FIX-8) and has
+**not been validated against a real PydanticAI runtime**. Just
+`from entropy_sdk.adapters.pydanticai import gated`.)
+
+(LangChain boundary: `args_schema` passthrough only works for real
+StructuredTool instances carrying a schema; bare tool objects (func only, no
+args_schema) remain limited by the wrapper's `*args/**kwargs` signature.)
+
+## Threat model boundaries (paper armor — read before deploying)
+
+1. **The gate is the sole dispatch channel — only inside execution paths the
+   SDK controls.** A caller holding the raw callable can bypass the gate
+   (`tool.func(...)` skips it); the SDK governs calls that go through
+   `runtime.step`, not references in the caller's hands.
+2. **`required_gear` is a caller-side attestation contract.** The SDK trusts
+   the label's truthfulness; whether labels may be trusted (who is allowed to
+   tag an action's gear) is the deployer's responsibility — the SDK
+   fail-closes on *invalid* values, but is not responsible for
+   under-tagged powerful actions.
+3. **The gate governs invocation, not transactions.** Side effects that
+   already happened inside `execute` are not rolled back — the semantics are
+   invocation control, not atomicity. Implement compensation in your own
+   `execute` if you need transactional behavior.
+4. **`resume()` does not clear σ** (design semantics, not a bug): human
+   review ≠ instant restoration of trust — σ persists after resuming, and
+   gears must be re-earned through clean cycles.
+5. **`except Exception` does not cover `BaseException`**: if a
+   proposer/execute callback raises SystemExit/KeyboardInterrupt, the state
+   machine can still desynchronize — this is standard Python practice;
+   callers must not raise BaseException inside callbacks.
+6. **Concurrency**: the runtime is lock-free. Under current CPython (GIL),
+   8000/8000 cycles measured with no lost updates; on free-threaded Python
+   (3.13t+), the read-modify-write of cycle/σ can lose updates — serialize
+   externally when using multiple threads.
+7. **A deleted audit file reads as empty** (fail-open read path): in file
+   mode, `entries`/metrics return empty results for a missing chain file
+   rather than raising — asymmetric with the fail-closed write path. Deployers
+   should monitor the audit file's existence (a missing append-only chain file
+   is itself an event).
+
+## Empirical data API
+
+```python
+runtime.audit.gate_acceptance_rate()  # gate acceptance rate (Theorem 1, p1≥p3)
+runtime.audit.gear_histogram()        # gear transition histogram (Theorem 3)
+```
+
+Every run produces data for the framework's empirical validation — a unique
+value of the SDK relative to the full system.
+
+## Changelog & security record
+
+- [CHANGELOG.md](CHANGELOG.md) — versioned changes, including behavior-change
+  and compatibility notes.
+- 中文文档：[README.zh-CN.md](README.zh-CN.md)
+
+## License
+
+MIT © Wang Miaosheng (ORCID: 0009-0003-2767-2421) — see [LICENSE](LICENSE).

entropy_sdk-0.1.5/README.md

@@ -0,0 +1,174 @@
+# entropy-sdk
+
+**An embeddable, gear-based safety control layer for autonomous agents** — the
+SDK distillation of the EntropyRuntime paper's core abstractions
+([arXiv:2607.00334](https://arxiv.org/abs/2607.00334)).
+
+> Make an AI's degree of autonomy observable, governable, and accountable.
+
+[![test](https://github.com/CYD-PRC/entropy-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/CYD-PRC/entropy-sdk/actions/workflows/test.yml)
+![license](https://img.shields.io/badge/license-MIT-blue)
+![python](https://img.shields.io/badge/python-%3E%3D3.10-blue)
+
+> Test readings are reported from **raw CI logs, not badge conclusions**:
+> latest verified reading — **96 passed / 0 skipped** across Python 3.10–3.13
+> (Actions run inspected line-by-line). A green badge alone is not evidence.
+
+Unlike [CYD-PRC/entropyruntime](https://github.com/CYD-PRC/entropyruntime)
+(the full production system — FastAPI + PostgreSQL + Redis + OPA), this
+repository is the **zero-dependency, embeddable** minimal control layer:
+`pip install` and five lines of code wire it into any agent loop.
+
+## Core abstractions
+
+| Abstraction | Paper | SDK |
+|---|---|---|
+| Five-level gear ladder G0–G4 | Definition 1 (𝒜₀⊂…⊂𝒜₄) | `Gear` |
+| Utility gate U(s,a) ≥ θ | Definitions 2–3, Theorem 2 | `UtilityGate` |
+| Slow-up-fast-down state machine | §4 Gear state machine | `GearPolicy` |
+| Event-driven fallback | Theorem 4 | `FallbackConfig` |
+| Runtime state ρ=(g,σ,ϵ) | Definition 4 | `RuntimeState` |
+| Audit chain | §5/§8 empirical requirements | `AuditLog` (append-only JSONL) |
+
+## Design rules
+
+1. **Pure stdlib core, zero dependencies.** Framework adapters (LangChain /
+   PydanticAI) ship as optional extras.
+2. **fail-closed.** The utility function must be injected explicitly; there is
+   no fail-open switch — the utility gate is the sole dispatch channel
+   (Theorem 2, enforced in code).
+3. **Audit chain built in.** Every gate decision, gear transition, and
+   suspension is appended to JSONL. `gate_acceptance_rate()` and
+   `gear_histogram()` produce the empirical data that the paper's Theorem 1
+   assumption and Theorem 3 prediction call for.
+
+## Quickstart
+
+```bash
+pip install entropy-sdk
+```
+
+```python
+from entropy_sdk import EntropyRuntime, Gear, action, observe
+
+# 1. Inject your domain utility function (the SDK ships no built-in U)
+def my_utility(state, act):
+    return state.task_gain(act) + 2.0 * state.safety(act) - 0.5 * act.cost
+
+# Note: action()'s **kwargs are call parameters of the wrapped function,
+# not utility metadata. Feed metadata to the utility via post-creation
+# assignment (act.utility_value = ... style).
+# 2. Create the runtime (theta is the only safety-vs-output knob)
+runtime = EntropyRuntime(utility=my_utility, theta=0.15,
+                         audit_log="audit.jsonl")
+
+# 3. Every agent action goes through the gate
+result = runtime.step(
+    state=my_state,
+    action=action(delete_records, "users", required_gear=Gear.EXECUTE),
+    execute=lambda a: a(),
+    propose_alternative=my_fallback_planner,  # optional: rejected-action fallback
+)
+
+if result.suspended:
+    alert_human()          # m consecutive rejections -> suspend at G0, await review
+    runtime.resume()       # after human review, gears must be re-earned
+```
+
+### Gear semantics
+
+| Gear | Name | Permitted actions |
+|---|---|---|
+| G0 | Observe | Read-only observation, safe holding |
+| G1 | Suggest | Side-effect-free candidate plans |
+| G2 | Plan | Bounded, reversible recovery actions |
+| G3 | Execute | Independently chosen side-effecting actions |
+| G4 | Integrate | System-level coordination (an emergent property of all-G3 fleets) |
+
+**Slow up, fast down** (earned autonomy): escalation requires σ < σ_low **and**
+h consecutive clean cycles — every gear must be re-earned (v0.1.2+);
+de-escalation on σ overflow or error is immediate. Autonomy is earned, and it
+can always be revoked.
+
+A runnable version of this narrative lives in
+[`examples/lifecycle_demo.py`](examples/lifecycle_demo.py)
+(`python examples/lifecycle_demo.py`).
+
+## Framework adapters
+
+```python
+# LangChain: pip install entropy-sdk[langchain]
+from entropy_sdk.adapters.langchain import gated_tool
+safe_tool = gated_tool(runtime, my_tool, required_gear=Gear.EXECUTE)
+
+# PydanticAI-compatible callable decorator: pip install entropy-sdk[pydanticai]
+from entropy_sdk.adapters.pydanticai import gated
+
+@gated(runtime, required_gear=Gear.EXECUTE)
+def delete_records(table: str) -> str: ...
+```
+
+On rejection the adapters **return an explanatory string instead of raising** —
+rejection itself is feedback the agent can act on next turn.
+
+(Note on naming: this is a **PydanticAI-compatible callable decorator**, not a
+true PydanticAI adapter — it is a pure stdlib decorator with zero framework
+dependencies (the `pydanticai` extra list is intentionally empty, FIX-8) and has
+**not been validated against a real PydanticAI runtime**. Just
+`from entropy_sdk.adapters.pydanticai import gated`.)
+
+(LangChain boundary: `args_schema` passthrough only works for real
+StructuredTool instances carrying a schema; bare tool objects (func only, no
+args_schema) remain limited by the wrapper's `*args/**kwargs` signature.)
+
+## Threat model boundaries (paper armor — read before deploying)
+
+1. **The gate is the sole dispatch channel — only inside execution paths the
+   SDK controls.** A caller holding the raw callable can bypass the gate
+   (`tool.func(...)` skips it); the SDK governs calls that go through
+   `runtime.step`, not references in the caller's hands.
+2. **`required_gear` is a caller-side attestation contract.** The SDK trusts
+   the label's truthfulness; whether labels may be trusted (who is allowed to
+   tag an action's gear) is the deployer's responsibility — the SDK
+   fail-closes on *invalid* values, but is not responsible for
+   under-tagged powerful actions.
+3. **The gate governs invocation, not transactions.** Side effects that
+   already happened inside `execute` are not rolled back — the semantics are
+   invocation control, not atomicity. Implement compensation in your own
+   `execute` if you need transactional behavior.
+4. **`resume()` does not clear σ** (design semantics, not a bug): human
+   review ≠ instant restoration of trust — σ persists after resuming, and
+   gears must be re-earned through clean cycles.
+5. **`except Exception` does not cover `BaseException`**: if a
+   proposer/execute callback raises SystemExit/KeyboardInterrupt, the state
+   machine can still desynchronize — this is standard Python practice;
+   callers must not raise BaseException inside callbacks.
+6. **Concurrency**: the runtime is lock-free. Under current CPython (GIL),
+   8000/8000 cycles measured with no lost updates; on free-threaded Python
+   (3.13t+), the read-modify-write of cycle/σ can lose updates — serialize
+   externally when using multiple threads.
+7. **A deleted audit file reads as empty** (fail-open read path): in file
+   mode, `entries`/metrics return empty results for a missing chain file
+   rather than raising — asymmetric with the fail-closed write path. Deployers
+   should monitor the audit file's existence (a missing append-only chain file
+   is itself an event).
+
+## Empirical data API
+
+```python
+runtime.audit.gate_acceptance_rate()  # gate acceptance rate (Theorem 1, p1≥p3)
+runtime.audit.gear_histogram()        # gear transition histogram (Theorem 3)
+```
+
+Every run produces data for the framework's empirical validation — a unique
+value of the SDK relative to the full system.
+
+## Changelog & security record
+
+- [CHANGELOG.md](CHANGELOG.md) — versioned changes, including behavior-change
+  and compatibility notes.
+- 中文文档：[README.zh-CN.md](README.zh-CN.md)
+
+## License
+
+MIT © Wang Miaosheng (ORCID: 0009-0003-2767-2421) — see [LICENSE](LICENSE).

entropy_sdk-0.1.5/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "entropy-sdk"
+version = "0.1.5"
+description = "Gear-based safety control layer for autonomous agents (EntropyRuntime core, embeddable SDK)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Wang Miaosheng", email = "wmsmiaosheng@outlook.com" },
+]
+keywords = ["ai-safety", "agent", "governance", "runtime-verification", "gear"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# 核心零依赖：纯 stdlib。框架适配器按需安装 extras。
+dependencies = []
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.2.43,<1.0"]  # 地板钉实测值：0.2.0 实测不兼容（pydantic v1 shim 校验炸），0.2.43 实测通过
+pydanticai = []  # FIX-8：该适配器为纯 stdlib 装饰器，实际零框架依赖（名实对齐）
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/CYD-PRC/entropy-sdk"
+Paper = "https://arxiv.org/abs/2607.00334"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

entropy_sdk-0.1.5/setup.cfg

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

entropy_sdk-0.1.5/src/entropy_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""
+entropy-sdk — EntropyRuntime 控制层的可嵌入 SDK
+
+论文同款核心抽象（arXiv:2607.00334）：
+Gear 五级档位 · Utility Gate 效用门 · 事件驱动 Fallback · append-only 审计链。
+
+设计铁律：
+1. 核心纯 stdlib，零依赖；
+2. fail-closed —— 效用函数必须显式注入，门是唯一调度通道；
+3. 每次判定自动落审计链，为经验验证生产数据。
+"""
+from .adapters.raw import RawAction, action, observe
+from .fallback import FallbackConfig
+from .gate import GateDecision, UtilityGate
+from .gear import Gear
+from .policy import GearPolicy
+from .runtime import CycleResult, EntropyRuntime
+from .state import AuditLog, RuntimeState
+
+__version__ = "0.1.5"
+__all__ = [
+    "Gear", "UtilityGate", "GateDecision", "GearPolicy", "FallbackConfig",
+    "RuntimeState", "AuditLog", "EntropyRuntime", "CycleResult",
+    "RawAction", "action", "observe",
+]

entropy_sdk-0.1.5/src/entropy_sdk/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Agent 框架适配器。raw 零依赖；langchain/pydanticai 按需 extras 安装。"""
+from .base import AgentAdapter, GatedAction
+from .raw import RawAction, action, observe
+
+__all__ = ["AgentAdapter", "GatedAction", "RawAction", "action", "observe"]

entropy_sdk-0.1.5/src/entropy_sdk/adapters/base.py

@@ -0,0 +1,31 @@
+"""适配器基座：一个动作协议 + 一个提案协议，接任何 agent 框架。"""
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from ..gear import Gear
+
+
+@runtime_checkable
+class GatedAction(Protocol):
+    """被门控的动作必须声明自己需要的最低档位。
+
+    这是嵌套动作空间 A0⊂…⊂A4 的实现侧契约：
+    required_gear=G0 的动作（只读）在任何档位都允许；
+    required_gear=G3 的动作（有副作用）只在 Execute 以上放行。
+    """
+
+    required_gear: int | Gear
+
+
+class AgentAdapter(Protocol):
+    """Agent 框架适配协议（对齐生产仓 interfaces/agent_adapter.py 的轻量版）。"""
+
+    def propose(self, state: Any, gear: Gear, history: list[dict]) -> GatedAction:
+        """按当前档位生成候选动作。实现侧应遵守档位语义：
+        档位越低，生成的动作越保守。"""
+        ...
+
+    def execute(self, action: GatedAction) -> Any:
+        """真正执行。只会在门放行后被调用。"""
+        ...

entropy_sdk-0.1.5/src/entropy_sdk/adapters/langchain.py

@@ -0,0 +1,52 @@
+"""LangChain 适配：把 Tool 包成"门不过就不执行"的安全工具。
+
+需要 ``pip install entropy-sdk[langchain]``。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..gear import Gear
+from ..runtime import EntropyRuntime, _safe_gear
+
+
+def gated_tool(runtime: EntropyRuntime, tool: Any, required_gear: int | Gear = Gear.EXECUTE,
+               state_fn=lambda *a, **k: None):
+    """把一个 LangChain Tool 包装成受 EntropyRuntime 门控的工具。
+
+    门拒绝时返回拒绝说明字符串（不执行、不抛异常），
+    让 LLM 在下一轮自行调整——拒绝本身是反馈信号。
+    """
+    # FIX5-2：与 runtime 同一严格度——构造期即拒非法 gear（3.0/"3"/True 等），
+    # 消灭「adapter 静默截断、runtime 拒绝」的两处判定不一致
+    gear = _safe_gear(required_gear)
+    if gear is None:
+        raise ValueError(f"invalid required_gear {required_gear!r} "
+                         "(want Gear instance or plain int 0-4)")
+
+    def _run(*args: Any, **kwargs: Any) -> str:
+        from .raw import action  # 延迟导入，避免硬依赖
+
+        # FIX-7：description 透传，效用函数可按工具身份定价
+        act = action(tool.func if hasattr(tool, "func") else tool,
+                     *args, required_gear=gear,
+                     description=getattr(tool, "description", "") or getattr(tool, "name", ""),
+                     **kwargs)
+        result = runtime.step(state=state_fn(), action=act, execute=lambda a: a())
+        if result.executed:
+            return str(result.result)
+        if result.suspended:
+            return "[GATE] runtime suspended after repeated rejections; human review required."
+        reason = result.gate.reason if result.gate else "gear does not permit this action"
+        return f"[GATE] action rejected: {reason}. Propose a safer alternative."
+
+    from langchain_core.tools import StructuredTool  # noqa: 仅在调用时需要
+
+    return StructuredTool.from_function(
+        func=_run,
+        name=f"gated_{getattr(tool, 'name', 'tool')}",
+        description=(getattr(tool, "description", "") or "")
+        + f" [safety-gated, requires gear {gear.label}]",
+        # FIX-6：透传原工具的 args_schema——不带它，带参工具没有正常调用路径
+        args_schema=getattr(tool, "args_schema", None),
+    )

entropy_sdk-0.1.5/src/entropy_sdk/adapters/pydanticai.py

@@ -0,0 +1,43 @@
+"""PydanticAI 适配：工具函数装饰器，门控逻辑与框架解耦。
+
+需要 ``pip install entropy-sdk[pydanticai]``。
+"""
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable
+
+from ..gear import Gear
+from ..runtime import EntropyRuntime
+
+
+def gated(runtime: EntropyRuntime, required_gear: int | Gear = Gear.EXECUTE,
+          state_fn=lambda *a, **k: None):
+    """装饰任意工具函数，使其经过 EntropyRuntime 效用门。
+
+    拒绝时返回说明字符串而非抛异常，让 agent 把拒绝当作反馈。
+    用法::
+
+        @gated(runtime, required_gear=Gear.EXECUTE)
+        def delete_records(table: str) -> str: ...
+    """
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from .raw import action
+
+            # FIX-7：description 透传（docstring 优先，函数名兜底），效用可按工具身份定价
+            act = action(fn, *args, required_gear=required_gear,
+                         description=(fn.__doc__ or "").strip() or fn.__name__,
+                         **kwargs)
+            result = runtime.step(state=state_fn(), action=act, execute=lambda a: a())
+            if result.executed:
+                return result.result
+            if result.suspended:
+                return "[GATE] runtime suspended; human review required."
+            reason = result.gate.reason if result.gate else "gear does not permit this action"
+            return f"[GATE] rejected: {reason}"
+
+        return wrapper
+
+    return decorator

entropy_sdk-0.1.5/src/entropy_sdk/adapters/raw.py

@@ -0,0 +1,38 @@
+"""零框架适配：把任意 Python callable 包装成被门控的动作。"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from ..gear import Gear
+
+
+@dataclass
+class RawAction:
+    """最小动作包装。"""
+
+    fn: Callable[..., Any]
+    args: tuple = ()
+    kwargs: dict = field(default_factory=dict)
+    required_gear: int | Gear = Gear.EXECUTE
+    description: str = ""
+
+    def __call__(self) -> Any:
+        return self.fn(*self.args, **self.kwargs)
+
+
+def action(
+    fn: Callable[..., Any],
+    *args: Any,
+    required_gear: int | Gear = Gear.EXECUTE,
+    description: str = "",
+    **kwargs: Any,
+) -> RawAction:
+    """一行包装：``action(send_email, to, body, required_gear=Gear.EXECUTE)``。"""
+    return RawAction(fn=fn, args=args, kwargs=kwargs,
+                     required_gear=required_gear, description=description)
+
+
+def observe(fn: Callable[..., Any], *args: Any, **kwargs: Any) -> RawAction:
+    """只读动作快捷包装：required_gear=G0，任何档位可执行。"""
+    return action(fn, *args, required_gear=Gear.OBSERVE, **kwargs)