margin 0.9.32__tar.gz → 0.11.0__tar.gz

{margin-0.9.32/margin.egg-info → margin-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.32
+Version: 0.11.0
 Summary: Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened.
 Author: Cope Labs LLC
 License: MIT
@@ -25,6 +25,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
 Dynamic: license-file
 
 # margin
@@ -34,9 +36,57 @@ Dynamic: license-file
 [![Downloads/month](https://static.pepy.tech/badge/margin/month)](https://pepy.tech/project/margin)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-**Typed health classification for systems that measure things.**
+**Typed primitives for system self-awareness.**
 
-Every system with health bars, thresholds, alerts, or status dashboards solves the same problem: take a number, decide if it's healthy, correct it if it isn't, explain what happened. Margin is that pattern, typed once, with the polarity bug fixed.
+When a system has to answer *"how am I doing, and what should I do about it?"* — an LLM agent between steps, an ML pipeline mid-inference, a data job deciding whether to ship — margin gives it the vocabulary. Typed `Health`, `Confidence`, `Absence`, `Issue`, `Flow`, `Intent`, `Contract` — composable, serializable, zero-dependency Python.
+
+```python
+from adapters.agent import agent_parser, AgentStep, agent_flow
+
+parser = agent_parser()
+flow   = agent_flow()                 # plan → act → reflect
+
+# Record what you already measure after one LLM + tool step:
+step = AgentStep(latency_ms=2400, tokens_used=1800,
+                 tool_success_rate=0.9, retry_count=1, confidence=0.72)
+
+expr     = parser.parse(step.to_values())
+guidance = flow.observe(step.to_values())
+
+print(expr.to_string())
+# [latency_ms:INTACT(-0.60σ)] [tokens_used:INTACT(-1.25σ)]
+# [tool_success_rate:INTACT(-0.05σ)] [retry_count:INTACT(+0.00σ)]
+# [confidence:INTACT(-0.10σ)]
+
+print(guidance.to_atom())
+# flow:agent:plan[1/3] → ADVANCE
+```
+
+Every metric is polarity-aware (more tokens = worse, higher confidence = better), sigma-normalised so you can compare them, and emits typed diagnostics when something goes wrong. Nothing stringly-typed; your decision loop reads typed enums.
+
+### Works with any MCP-capable client
+
+Install the MCP extra and you get an stdio server any model's client (Claude Desktop, Claude Code, Cursor, Cline, Windsurf, …) can spawn:
+
+```bash
+pip install margin[mcp]
+```
+
+```json
+{
+  "mcpServers": {
+    "margin": {
+      "command": "margin-mcp"
+    }
+  }
+}
+```
+
+The model now has a `margin_observe(values)` tool and can read `margin://state` / `margin://issues` between turns to reason about its own typed self-state. Full details: [adapters/mcp/README.md](adapters/mcp/README.md).
+
+---
+
+Not building an agent? Margin works on any scalar with a threshold:
 
 ```python
 from margin import Parser, Thresholds
@@ -48,13 +98,12 @@ parser = Parser(
         "error_rate": Thresholds(intact=0.005, ablated=0.05, higher_is_better=False),
     },
 )
-
 expr = parser.parse({"throughput": 480.0, "error_rate": 0.03})
 print(expr.to_string())
 # [throughput:INTACT(-0.04σ)] [error_rate:DEGRADED(-14.00σ)]
 ```
 
-Throughput and error rate on the same scale. One is higher-is-better, the other is lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
+Throughput and error rate on the same scale. One higher-is-better, the other lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
 
 ## Install
 
@@ -203,30 +252,24 @@ parser = parser_from_calibration(
 
 `full_step()` orchestrates the first seven in one call. `Flow` composes them into a sequence. `Issue` is ambient — every layer emits diagnostics into the same buffer.
 
-## Domain adapters
+## Adapters
 
-Ready-to-use threshold profiles for specific domains:
+Core adapters ship in the package. Each is a Parser factory + optional Flow / Intent / Monitor helpers with domain-appropriate thresholds:
 
-| Adapter | What it monitors | Polarity |
-|---|---|---|
-| [**healthcare**](https://github.com/Cope-Labs/margin/tree/main/adapters/healthcare/) | Vital signs (HR, BP, SpO2, temp, glucose) — WHO/AHA ranges, sepsis screening | bands |
-| [**godot**](https://github.com/sethc5/margin-godot) | Game systems (food, morale, stress, stamina) — native GDScript | mixed |
-| [**homeassistant**](https://github.com/Cope-Labs/margin/tree/main/adapters/homeassistant/) | Smart home sensors (temp, humidity, battery, solar, power) | mixed |
-| [**evcharging**](https://github.com/Cope-Labs/margin/tree/main/adapters/evcharging/) | EV charging (SoC, grid draw, solar surplus, efficiency) | mixed |
-| [**infrastructure**](https://github.com/Cope-Labs/margin/tree/main/adapters/infrastructure/) | Server monitoring (CPU, memory, disk, latency, error rate) | mixed |
-| [**aquarium**](https://github.com/Cope-Labs/margin/tree/main/adapters/aquarium/) | Water chemistry (pH, ammonia, nitrite, temp, hardness) | bands |
-| [**greenhouse**](https://github.com/Cope-Labs/margin/tree/main/adapters/greenhouse/) | Growing environment (soil moisture, CO₂, light, VPD) | bands |
-| [**fitness**](https://github.com/Cope-Labs/margin/tree/main/adapters/fitness/) | Wearables (resting HR, HRV, sleep, steps, stress) | mixed |
-| [**transformer**](https://github.com/Cope-Labs/margin/tree/main/adapters/transformer/) | ML circuit interpretability (pythia-6.9b) | higher |
-| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) | mixed |
-| [**database**](https://github.com/Cope-Labs/margin/tree/main/adapters/database/) | DB health (pool usage, query latency, replication lag, deadlocks) | mixed |
-| [**celery**](https://github.com/Cope-Labs/margin/tree/main/adapters/celery/) | Task queue (queue depth, failure rate, worker utilization, retries) | mixed |
-| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) | mixed |
-| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) | mixed |
+| Adapter | What it monitors |
+|---|---|
+| [**agent**](https://github.com/Cope-Labs/margin/tree/main/adapters/agent/) | LLM / agent step health — latency, tokens, tool success rate, retries, confidence. Includes a three-stage `plan → act → reflect` Flow and a default feasibility Intent. |
+| [**mcp**](https://github.com/Cope-Labs/margin/tree/main/adapters/mcp/) | stdio Model Context Protocol server. Exposes `margin_observe` / `margin_reset` tools and `margin://state` / `margin://issues` resources to any MCP client. `pip install margin[mcp]`. |
+| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) |
+| [**numpy**](https://github.com/Cope-Labs/margin/tree/main/adapters/numpy/) | Array health (NaN rate, drift, distribution shape) |
+| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) — ASGI middleware |
+| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) — conftest plugin |
+
+Additional domain profiles (healthcare, ros2, transformer circuit interpretability, homeassistant, aquarium, greenhouse, evcharging, fitness, infrastructure, weather, printer3d, neuro, godot, celery, database) live in [`contrib/`](https://github.com/Cope-Labs/margin/tree/main/contrib/) — reference material, not shipped in the pip package.
 
 ## Docs
 
-Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md)
+Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md) — a typed grammar for system self-awareness.
 
 ## License
 

{margin-0.9.32 → margin-0.11.0}/README.md

@@ -5,9 +5,57 @@
 [![Downloads/month](https://static.pepy.tech/badge/margin/month)](https://pepy.tech/project/margin)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-**Typed health classification for systems that measure things.**
+**Typed primitives for system self-awareness.**
 
-Every system with health bars, thresholds, alerts, or status dashboards solves the same problem: take a number, decide if it's healthy, correct it if it isn't, explain what happened. Margin is that pattern, typed once, with the polarity bug fixed.
+When a system has to answer *"how am I doing, and what should I do about it?"* — an LLM agent between steps, an ML pipeline mid-inference, a data job deciding whether to ship — margin gives it the vocabulary. Typed `Health`, `Confidence`, `Absence`, `Issue`, `Flow`, `Intent`, `Contract` — composable, serializable, zero-dependency Python.
+
+```python
+from adapters.agent import agent_parser, AgentStep, agent_flow
+
+parser = agent_parser()
+flow   = agent_flow()                 # plan → act → reflect
+
+# Record what you already measure after one LLM + tool step:
+step = AgentStep(latency_ms=2400, tokens_used=1800,
+                 tool_success_rate=0.9, retry_count=1, confidence=0.72)
+
+expr     = parser.parse(step.to_values())
+guidance = flow.observe(step.to_values())
+
+print(expr.to_string())
+# [latency_ms:INTACT(-0.60σ)] [tokens_used:INTACT(-1.25σ)]
+# [tool_success_rate:INTACT(-0.05σ)] [retry_count:INTACT(+0.00σ)]
+# [confidence:INTACT(-0.10σ)]
+
+print(guidance.to_atom())
+# flow:agent:plan[1/3] → ADVANCE
+```
+
+Every metric is polarity-aware (more tokens = worse, higher confidence = better), sigma-normalised so you can compare them, and emits typed diagnostics when something goes wrong. Nothing stringly-typed; your decision loop reads typed enums.
+
+### Works with any MCP-capable client
+
+Install the MCP extra and you get an stdio server any model's client (Claude Desktop, Claude Code, Cursor, Cline, Windsurf, …) can spawn:
+
+```bash
+pip install margin[mcp]
+```
+
+```json
+{
+  "mcpServers": {
+    "margin": {
+      "command": "margin-mcp"
+    }
+  }
+}
+```
+
+The model now has a `margin_observe(values)` tool and can read `margin://state` / `margin://issues` between turns to reason about its own typed self-state. Full details: [adapters/mcp/README.md](adapters/mcp/README.md).
+
+---
+
+Not building an agent? Margin works on any scalar with a threshold:
 
 ```python
 from margin import Parser, Thresholds
@@ -19,13 +67,12 @@ parser = Parser(
         "error_rate": Thresholds(intact=0.005, ablated=0.05, higher_is_better=False),
     },
 )
-
 expr = parser.parse({"throughput": 480.0, "error_rate": 0.03})
 print(expr.to_string())
 # [throughput:INTACT(-0.04σ)] [error_rate:DEGRADED(-14.00σ)]
 ```
 
-Throughput and error rate on the same scale. One is higher-is-better, the other is lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
+Throughput and error rate on the same scale. One higher-is-better, the other lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
 
 ## Install
 
@@ -174,30 +221,24 @@ parser = parser_from_calibration(
 
 `full_step()` orchestrates the first seven in one call. `Flow` composes them into a sequence. `Issue` is ambient — every layer emits diagnostics into the same buffer.
 
-## Domain adapters
+## Adapters
 
-Ready-to-use threshold profiles for specific domains:
+Core adapters ship in the package. Each is a Parser factory + optional Flow / Intent / Monitor helpers with domain-appropriate thresholds:
 
-| Adapter | What it monitors | Polarity |
-|---|---|---|
-| [**healthcare**](https://github.com/Cope-Labs/margin/tree/main/adapters/healthcare/) | Vital signs (HR, BP, SpO2, temp, glucose) — WHO/AHA ranges, sepsis screening | bands |
-| [**godot**](https://github.com/sethc5/margin-godot) | Game systems (food, morale, stress, stamina) — native GDScript | mixed |
-| [**homeassistant**](https://github.com/Cope-Labs/margin/tree/main/adapters/homeassistant/) | Smart home sensors (temp, humidity, battery, solar, power) | mixed |
-| [**evcharging**](https://github.com/Cope-Labs/margin/tree/main/adapters/evcharging/) | EV charging (SoC, grid draw, solar surplus, efficiency) | mixed |
-| [**infrastructure**](https://github.com/Cope-Labs/margin/tree/main/adapters/infrastructure/) | Server monitoring (CPU, memory, disk, latency, error rate) | mixed |
-| [**aquarium**](https://github.com/Cope-Labs/margin/tree/main/adapters/aquarium/) | Water chemistry (pH, ammonia, nitrite, temp, hardness) | bands |
-| [**greenhouse**](https://github.com/Cope-Labs/margin/tree/main/adapters/greenhouse/) | Growing environment (soil moisture, CO₂, light, VPD) | bands |
-| [**fitness**](https://github.com/Cope-Labs/margin/tree/main/adapters/fitness/) | Wearables (resting HR, HRV, sleep, steps, stress) | mixed |
-| [**transformer**](https://github.com/Cope-Labs/margin/tree/main/adapters/transformer/) | ML circuit interpretability (pythia-6.9b) | higher |
-| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) | mixed |
-| [**database**](https://github.com/Cope-Labs/margin/tree/main/adapters/database/) | DB health (pool usage, query latency, replication lag, deadlocks) | mixed |
-| [**celery**](https://github.com/Cope-Labs/margin/tree/main/adapters/celery/) | Task queue (queue depth, failure rate, worker utilization, retries) | mixed |
-| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) | mixed |
-| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) | mixed |
+| Adapter | What it monitors |
+|---|---|
+| [**agent**](https://github.com/Cope-Labs/margin/tree/main/adapters/agent/) | LLM / agent step health — latency, tokens, tool success rate, retries, confidence. Includes a three-stage `plan → act → reflect` Flow and a default feasibility Intent. |
+| [**mcp**](https://github.com/Cope-Labs/margin/tree/main/adapters/mcp/) | stdio Model Context Protocol server. Exposes `margin_observe` / `margin_reset` tools and `margin://state` / `margin://issues` resources to any MCP client. `pip install margin[mcp]`. |
+| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) |
+| [**numpy**](https://github.com/Cope-Labs/margin/tree/main/adapters/numpy/) | Array health (NaN rate, drift, distribution shape) |
+| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) — ASGI middleware |
+| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) — conftest plugin |
+
+Additional domain profiles (healthcare, ros2, transformer circuit interpretability, homeassistant, aquarium, greenhouse, evcharging, fitness, infrastructure, weather, printer3d, neuro, godot, celery, database) live in [`contrib/`](https://github.com/Cope-Labs/margin/tree/main/contrib/) — reference material, not shipped in the pip package.
 
 ## Docs
 
-Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md)
+Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md) — a typed grammar for system self-awareness.
 
 ## License
 

margin-0.11.0/adapters/agent/__init__.py

@@ -0,0 +1,34 @@
+"""
+margin adapter for agent / LLM-pipeline self-awareness.
+
+The primitives (Confidence, Absence, Issue, Flow, Intent, Contract) that margin
+exposes are *exactly* the vocabulary an LLM agent needs when it has to answer
+"how am I doing, and should I continue?" at each step of its run.
+
+This adapter packages sensible defaults so you can go from zero to a typed
+health read-out of an agent step in three lines:
+
+    from adapters.agent import agent_parser, AgentStep
+
+    parser = agent_parser()
+    step   = AgentStep(latency_ms=2400, tokens_used=1800,
+                       tool_success_rate=0.9, retry_count=1, confidence=0.72)
+    print(parser.parse(step.to_values()).to_string())
+    # [latency_ms:INTACT(+0.40\u03c3)] [tokens_used:INTACT(+0.75\u03c3)]
+    # [tool_success_rate:INTACT(-0.05\u03c3)] [retry_count:DEGRADED(...)]
+    # [confidence:INTACT(-0.10\u03c3)]
+
+Use :func:`agent_flow` when your agent runs in stages (plan \u2192 act \u2192 reflect) and
+you want typed live guidance (ADVANCE/HOLD/RETRY/ROLLBACK) between them.
+
+Zero SDK dependencies.  See module docstrings for wiring to Anthropic / OpenAI.
+"""
+from .metrics import AGENT_BASELINES, AGENT_THRESHOLDS, agent_parser
+from .flow import AGENT_STAGES, agent_flow
+from .wrap import AgentStep, record_step, agent_intent
+
+__all__ = [
+    "AGENT_BASELINES", "AGENT_THRESHOLDS", "agent_parser",
+    "AGENT_STAGES", "agent_flow",
+    "AgentStep", "record_step", "agent_intent",
+]

margin-0.11.0/adapters/agent/flow.py

@@ -0,0 +1,72 @@
+"""
+A Flow template for a typical three-stage agent loop:
+
+    PLAN  \u2192  ACT  \u2192  REFLECT  \u2192  (COMPLETE)
+
+Each stage uses the same agent_parser, but advances on different predicates:
+
+    PLAN    \u2192  a concrete plan is produced (confidence above threshold)
+    ACT     \u2192  tool calls are succeeding (tool_success_rate holds)
+    REFLECT \u2192  the run is converging (retries haven't exploded)
+
+Flow.observe() returns typed live guidance (ADVANCE / HOLD / RETRY / ROLLBACK /
+ESCALATE) at every step, and emits typed Issues for predicate failures and
+degraded stage entries.  This means your agent gets a typed answer to
+"continue, retry, or escalate?" after every observation \u2014 not a string you have
+to parse.
+"""
+from __future__ import annotations
+
+from margin import Flow, Stage, Expression
+
+from .metrics import agent_parser
+
+
+def _has_plan(expr: Expression) -> bool:
+    """PLAN advances once the model's stated confidence crosses intact."""
+    conf = next((o for o in expr.observations if o.name == "confidence"), None)
+    return conf is not None and conf.health.value == "INTACT"
+
+
+def _tools_holding(expr: Expression) -> bool:
+    """ACT advances once tool success rate is intact and retries aren't ablated."""
+    success = next((o for o in expr.observations if o.name == "tool_success_rate"), None)
+    retries = next((o for o in expr.observations if o.name == "retry_count"), None)
+    if success is None or success.health.value != "INTACT":
+        return False
+    if retries is not None and retries.health.value == "ABLATED":
+        return False
+    return True
+
+
+def _converging(expr: Expression) -> bool:
+    """REFLECT advances once retry_count is intact and confidence is intact."""
+    retries = next((o for o in expr.observations if o.name == "retry_count"), None)
+    conf    = next((o for o in expr.observations if o.name == "confidence"), None)
+    return (
+        retries is not None and retries.health.value == "INTACT"
+        and conf is not None and conf.health.value == "INTACT"
+    )
+
+
+AGENT_STAGES = ("plan", "act", "reflect")
+
+
+def agent_flow(label: str = "agent") -> Flow:
+    """
+    Build a typical three-stage agent Flow with shared thresholds.
+
+    Each Flow.observe() call returns a FlowResult whose ``guidance`` is one of
+    ADVANCE / HOLD / RETRY / ROLLBACK / ESCALATE / COMPLETE.  Use
+    ``result.to_atom()`` to get a single-line summary suitable for logging,
+    e.g. ``flow:agent:act[2/3] \u2192 ADVANCE``.
+    """
+    parser = agent_parser()
+    return Flow(
+        stages=[
+            Stage(name="plan",    parser=parser, advance_when=_has_plan),
+            Stage(name="act",     parser=parser, advance_when=_tools_holding),
+            Stage(name="reflect", parser=parser, advance_when=_converging),
+        ],
+        label=label,
+    )

margin-0.11.0/adapters/agent/metrics.py

@@ -0,0 +1,78 @@
+"""
+Default baselines and thresholds for common agent / LLM-pipeline metrics.
+
+Polarity is the critical part: for cost-like metrics (latency, tokens, retries)
+more is worse, so ``higher_is_better=False``.  For quality metrics (confidence,
+tool success rate) more is better.  Margin's sigma normalisation threads that
+polarity correctly through every comparison downstream.
+
+The baselines below are deliberately conservative defaults for a mid-size
+Claude / GPT call with occasional tool use.  Override per-component for your
+specific agent.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from margin import Parser, Thresholds
+
+
+AGENT_BASELINES: dict[str, float] = {
+    "latency_ms":        1500.0,   # typical end-to-end call
+    "tokens_used":        800.0,   # input + output
+    "tool_success_rate":   0.95,   # fraction of tool calls that succeeded
+    "retry_count":         0.0,    # zero retries is the happy path
+    "confidence":          0.80,   # model-stated or rubric-derived
+}
+
+
+AGENT_THRESHOLDS: dict[str, Thresholds] = {
+    "latency_ms": Thresholds(
+        intact=3000.0, ablated=10000.0, higher_is_better=False,
+    ),
+    "tokens_used": Thresholds(
+        intact=3000.0, ablated=10000.0, higher_is_better=False,
+    ),
+    "tool_success_rate": Thresholds(
+        intact=0.80, ablated=0.50, higher_is_better=True,
+    ),
+    "retry_count": Thresholds(
+        intact=1.0, ablated=3.0, higher_is_better=False,
+    ),
+    "confidence": Thresholds(
+        intact=0.60, ablated=0.30, higher_is_better=True,
+    ),
+}
+
+
+def agent_parser(
+    baselines: Optional[dict[str, float]] = None,
+    thresholds: Optional[dict[str, Thresholds]] = None,
+) -> Parser:
+    """
+    Build a Parser with sensible agent-metric defaults.
+
+    ``baselines`` and ``thresholds`` merge over the defaults, so you can pass
+    just the overrides you care about::
+
+        parser = agent_parser(
+            baselines={"latency_ms": 5000.0},           # slower model
+            thresholds={"confidence": Thresholds(
+                intact=0.75, ablated=0.50, higher_is_better=True,
+            )},
+        )
+    """
+    merged_baselines = dict(AGENT_BASELINES)
+    if baselines:
+        merged_baselines.update(baselines)
+    merged_thresholds = dict(AGENT_THRESHOLDS)
+    if thresholds:
+        merged_thresholds.update(thresholds)
+    # Default per-component thresholds cover every baseline, so the Parser-level
+    # fallback is only hit if the caller adds an unrelated component.
+    fallback = Thresholds(intact=0.0, ablated=0.0)
+    return Parser(
+        baselines=merged_baselines,
+        thresholds=fallback,
+        component_thresholds=merged_thresholds,
+    )

margin-0.11.0/adapters/agent/wrap.py

@@ -0,0 +1,114 @@
+"""
+Lightweight helpers for recording an agent step and deriving a feasibility
+Intent from it.
+
+The ``AgentStep`` dataclass carries the five canonical agent metrics so you can
+collect them once at the call site and feed them to margin in typed form.
+There is no hard dependency on any LLM SDK \u2014 wire your own adapter in a couple
+of lines, e.g. for Anthropic::
+
+    import time, anthropic
+    from adapters.agent import AgentStep, agent_parser
+
+    client = anthropic.Anthropic()
+    parser = agent_parser()
+
+    def call(messages, tools=None):
+        t0 = time.perf_counter()
+        resp = client.messages.create(
+            model="claude-opus-4-7",
+            max_tokens=1024,
+            messages=messages,
+            tools=tools or [],
+        )
+        step = AgentStep(
+            latency_ms=(time.perf_counter() - t0) * 1000,
+            tokens_used=resp.usage.input_tokens + resp.usage.output_tokens,
+            tool_success_rate=1.0,   # fill in from your tool-runner's accounting
+            retry_count=0,
+            confidence=0.8,          # rubric-derived or model-stated
+        )
+        expr = parser.parse(step.to_values())
+        return resp, expr
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from margin import (
+    Expression, Intent, Requirement, Health, Ledger, Record, Op,
+)
+
+
+@dataclass
+class AgentStep:
+    """
+    One agent step's observable metrics.
+
+    latency_ms:        end-to-end wall time for the call in milliseconds
+    tokens_used:       input + output tokens
+    tool_success_rate: fraction of tool calls that succeeded (0.0\u20131.0)
+    retry_count:       how many retries this step consumed
+    confidence:        model-stated or rubric-derived confidence (0.0\u20131.0)
+    """
+    latency_ms: float
+    tokens_used: float
+    tool_success_rate: float
+    retry_count: float
+    confidence: float
+
+    def to_values(self) -> dict[str, float]:
+        """Dict shape expected by ``agent_parser().parse(...)``."""
+        return {
+            "latency_ms":        self.latency_ms,
+            "tokens_used":       self.tokens_used,
+            "tool_success_rate": self.tool_success_rate,
+            "retry_count":       self.retry_count,
+            "confidence":        self.confidence,
+        }
+
+
+def record_step(
+    ledger: Ledger,
+    step_index: int,
+    expression: Expression,
+    tag: str = "",
+) -> Record:
+    """
+    Append one agent step's first observation to the ledger so margin's
+    drift/forecast/contract layers can reason about trajectory across steps.
+    """
+    obs = expression.observations[0] if expression.observations else None
+    if obs is None:
+        return None
+    record = Record(
+        step=step_index,
+        tag=tag or f"step-{step_index}",
+        before=obs,
+        fired=False,
+        op=Op.NOOP,
+        alpha=0.0,
+        magnitude=0.0,
+    )
+    ledger.append(record)
+    return record
+
+
+def agent_intent(deadline_seconds: Optional[float] = None) -> Intent:
+    """
+    Build a default Intent covering 'the agent run is still feasible' \u2014 a
+    compact goal-feasibility check you can drop into ``full_step(... intent=...)``.
+
+    Requirements say latency must stay at DEGRADED-or-better and confidence must
+    stay at DEGRADED-or-better.  ``deadline_seconds`` sets an ETA-to-violation
+    window from the moment ``Intent.evaluate()`` is called.
+    """
+    return Intent(
+        goal="agent run is still feasible",
+        requirements=[
+            Requirement(component="latency_ms", min_health=Health.DEGRADED),
+            Requirement(component="confidence", min_health=Health.DEGRADED),
+        ],
+        deadline_seconds=deadline_seconds,
+    )

margin-0.11.0/adapters/dataframe/__init__.py

@@ -0,0 +1,7 @@
+"""
+DataFrame / data pipeline adapter for margin.
+
+Data quality metrics: completeness, null rate, drift, freshness, row count.
+Works with any tabular data — no pandas dependency required.
+"""
+from .quality import DQ_METRICS, parse_quality, pipeline_expression