margin 0.10.0__tar.gz → 0.12.0__tar.gz

{margin-0.10.0/margin.egg-info → margin-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.10.0
+Version: 0.12.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
@@ -62,6 +64,49 @@ print(guidance.to_atom())
 
 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.
 
+## Host-fed observation (recommended for production)
+
+When your harness has ground-truth metrics (real latency, real token counts, real tool outcomes), feed margin from the *host* side so the model reads typed state rather than self-reports:
+
+```python
+from adapters.agent import host_observe
+
+advisory = host_observe({
+    "latency_ms": (time.perf_counter() - t0) * 1000,
+    "tokens_used": resp.usage.input_tokens + resp.usage.output_tokens,
+    "tool_success_rate": 1.0,
+    "retry_count": 0,
+    "confidence": 0.85,
+}, profile="reasoning")      # "default" | "reasoning" | "fast"
+# → {"expression": "…", "flow": "flow:agent:plan[1/3] → ADVANCE",
+#    "advisory": {"action": "PROCEED", "reason": "…", "confidence": 0.7},
+#    "drift": {...}, "anomaly": {...}, "ledger_size": 3}
+```
+
+The `Advisory` enum (PROCEED / HOLD_AND_REFLECT / DECOMPOSE / ASK_CLARIFYING / HAND_OFF / RETRY) is margin's typed hint for what the *model* should do next — distinct from `Correction.op` (RESTORE / SUPPRESS / AMPLIFY), which is for controllers.
+
+## 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
@@ -235,6 +280,7 @@ Core adapters ship in the package. Each is a Parser factory + optional Flow / In
 | 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 |

{margin-0.10.0 → margin-0.12.0}/README.md

@@ -33,6 +33,49 @@ print(guidance.to_atom())
 
 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.
 
+## Host-fed observation (recommended for production)
+
+When your harness has ground-truth metrics (real latency, real token counts, real tool outcomes), feed margin from the *host* side so the model reads typed state rather than self-reports:
+
+```python
+from adapters.agent import host_observe
+
+advisory = host_observe({
+    "latency_ms": (time.perf_counter() - t0) * 1000,
+    "tokens_used": resp.usage.input_tokens + resp.usage.output_tokens,
+    "tool_success_rate": 1.0,
+    "retry_count": 0,
+    "confidence": 0.85,
+}, profile="reasoning")      # "default" | "reasoning" | "fast"
+# → {"expression": "…", "flow": "flow:agent:plan[1/3] → ADVANCE",
+#    "advisory": {"action": "PROCEED", "reason": "…", "confidence": 0.7},
+#    "drift": {...}, "anomaly": {...}, "ledger_size": 3}
+```
+
+The `Advisory` enum (PROCEED / HOLD_AND_REFLECT / DECOMPOSE / ASK_CLARIFYING / HAND_OFF / RETRY) is margin's typed hint for what the *model* should do next — distinct from `Correction.op` (RESTORE / SUPPRESS / AMPLIFY), which is for controllers.
+
+## 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
@@ -206,6 +249,7 @@ Core adapters ship in the package. Each is a Parser factory + optional Flow / In
 | 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 |

margin-0.12.0/adapters/agent/__init__.py

@@ -0,0 +1,48 @@
+"""
+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,
+    REASONING_BASELINES, REASONING_THRESHOLDS,
+    FAST_BASELINES, FAST_THRESHOLDS,
+    AGENT_PROFILES, agent_parser,
+)
+from .flow import AGENT_STAGES, agent_flow
+from .wrap import AgentStep, record_step, host_observe, agent_intent
+from .advisory import Advisory, AdvisoryResult, derive_advisory
+
+__all__ = [
+    # Thresholds + profiles
+    "AGENT_BASELINES", "AGENT_THRESHOLDS",
+    "REASONING_BASELINES", "REASONING_THRESHOLDS",
+    "FAST_BASELINES", "FAST_THRESHOLDS",
+    "AGENT_PROFILES", "agent_parser",
+    # Flow
+    "AGENT_STAGES", "agent_flow",
+    # Step recording + host feeder
+    "AgentStep", "record_step", "host_observe", "agent_intent",
+    # Advisory
+    "Advisory", "AdvisoryResult", "derive_advisory",
+]

margin-0.12.0/adapters/agent/advisory.py

@@ -0,0 +1,151 @@
+"""
+Advisory: a typed next-action hint for the model, derived from an Expression
+(+ optional FlowResult + drift map).
+
+Where :class:`margin.Correction` names the *controller-level* op (RESTORE /
+SUPPRESS / AMPLIFY / NOOP), ``Advisory`` names what the *model* should
+consider doing with its next turn:
+
+    PROCEED            continue as-is, the run looks healthy
+    HOLD_AND_REFLECT   pause, re-examine inputs before producing output
+    DECOMPOSE          break the problem into smaller sub-steps
+    ASK_CLARIFYING     state is too ambiguous to proceed; query the user
+    HAND_OFF           escalate to a human or a stronger model
+    RETRY              redo the last step with tighter constraints
+
+Advisories are **suggestions with reasons**, not prescriptions.  The derivation
+below is a deliberately simple heuristic over current Health, Flow guidance,
+and drift trajectory.  Callers are expected to treat ``AdvisoryResult.action``
+as one signal among several, not a hard directive.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+from margin import Health, Expression
+
+
+class Advisory(Enum):
+    """Typed next-action hint for the model."""
+    PROCEED            = "PROCEED"
+    HOLD_AND_REFLECT   = "HOLD_AND_REFLECT"
+    DECOMPOSE          = "DECOMPOSE"
+    ASK_CLARIFYING     = "ASK_CLARIFYING"
+    HAND_OFF           = "HAND_OFF"
+    RETRY              = "RETRY"
+
+
+@dataclass
+class AdvisoryResult:
+    """
+    One advisory decision.
+
+    action:     the typed suggestion
+    reason:     human-readable justification (references specific components / sigma)
+    confidence: how confident the derivation is in this advisory (0.0\u20131.0)
+    """
+    action: Advisory
+    reason: str
+    confidence: float = 0.7
+
+    def to_dict(self) -> dict:
+        return {"action": self.action.value, "reason": self.reason,
+                "confidence": round(self.confidence, 3)}
+
+    def to_atom(self) -> str:
+        return f"advisory:{self.action.value}({self.confidence:.2f}) — {self.reason}"
+
+
+def _obs(expr: Expression, name: str):
+    for o in expr.observations:
+        if o.name == name:
+            return o
+    return None
+
+
+def derive_advisory(
+    expression: Expression,
+    flow_result=None,
+    drift_map: Optional[dict] = None,
+) -> AdvisoryResult:
+    """
+    Derive a :class:`AdvisoryResult` from observed state.
+
+    Precedence, highest-to-lowest:
+        1. Flow guidance \u2014 ESCALATE/RETRY/ROLLBACK map directly.
+        2. Confidence OOD \u2192 ASK_CLARIFYING (we can't classify certainty).
+        3. Any component ABLATED \u2192 HOLD_AND_REFLECT.
+        4. Accelerating worsening drift on any component \u2192 HOLD_AND_REFLECT.
+        5. Confidence + tokens both DEGRADED \u2192 DECOMPOSE (signal + cost both soft).
+        6. Any DEGRADED component \u2192 PROCEED with reason (soft-yellow).
+        7. Otherwise \u2192 PROCEED (all intact).
+    """
+    # 1. Flow guidance wins if present.
+    if flow_result is not None:
+        g = getattr(flow_result.guidance, "value", None)
+        if g == "ESCALATE":
+            return AdvisoryResult(Advisory.HAND_OFF,
+                                  "flow guidance is ESCALATE", 0.9)
+        if g == "RETRY":
+            return AdvisoryResult(Advisory.RETRY,
+                                  "flow guidance is RETRY", 0.9)
+        if g == "ROLLBACK":
+            return AdvisoryResult(Advisory.HOLD_AND_REFLECT,
+                                  "flow guidance is ROLLBACK", 0.8)
+
+    # 2. Confidence OOD \u2192 ASK_CLARIFYING.
+    conf = _obs(expression, "confidence")
+    if conf is not None and conf.health == Health.OOD:
+        return AdvisoryResult(
+            Advisory.ASK_CLARIFYING,
+            "confidence is OOD \u2014 cannot classify certainty",
+            0.8,
+        )
+
+    # 3. Any ABLATED \u2192 HOLD_AND_REFLECT.
+    ablated = [o for o in expression.observations if o.health == Health.ABLATED]
+    if ablated:
+        names = ", ".join(o.name for o in ablated)
+        return AdvisoryResult(
+            Advisory.HOLD_AND_REFLECT,
+            f"ablated: {names}",
+            0.8,
+        )
+
+    # 4. Accelerating worsening drift.
+    if drift_map:
+        for name, dc in drift_map.items():
+            state = getattr(getattr(dc, "state", None), "value", "")
+            direction = getattr(getattr(dc, "direction", None), "value", "")
+            if state == "ACCELERATING" and direction in ("WORSENING", "DEGRADING"):
+                return AdvisoryResult(
+                    Advisory.HOLD_AND_REFLECT,
+                    f"{name} drift is accelerating-worsening",
+                    0.65,
+                )
+
+    # 5. Confidence + tokens both DEGRADED \u2192 DECOMPOSE.
+    tokens = _obs(expression, "tokens_used")
+    if (conf is not None and tokens is not None
+            and conf.health == Health.DEGRADED
+            and tokens.health == Health.DEGRADED):
+        return AdvisoryResult(
+            Advisory.DECOMPOSE,
+            "confidence and tokens_used both degraded \u2014 shrink the step",
+            0.65,
+        )
+
+    # 6. Any DEGRADED \u2192 soft-proceed.
+    degraded = [o for o in expression.observations if o.health == Health.DEGRADED]
+    if degraded:
+        names = ", ".join(o.name for o in degraded)
+        return AdvisoryResult(
+            Advisory.PROCEED,
+            f"degraded but acceptable: {names}",
+            0.7,
+        )
+
+    # 7. All INTACT \u2192 confident proceed.
+    return AdvisoryResult(Advisory.PROCEED, "all components INTACT", 0.9)

margin-0.12.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.12.0/adapters/agent/metrics.py

@@ -0,0 +1,134 @@
+"""
+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,
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Profile baselines \u2014 v0.12 additive.  Default preserves v0.11 behaviour.
+# ---------------------------------------------------------------------------
+
+REASONING_BASELINES: dict[str, float] = {
+    "latency_ms":         8000.0,   # reasoning models think for seconds per turn
+    "tokens_used":        8000.0,   # long-context turns consume a lot
+    "tool_success_rate":    0.95,
+    "retry_count":          0.0,
+    "confidence":           0.80,
+}
+
+REASONING_THRESHOLDS: dict[str, Thresholds] = {
+    "latency_ms":        Thresholds(intact=20000.0, ablated=60000.0, higher_is_better=False),
+    "tokens_used":       Thresholds(intact=20000.0, ablated=80000.0, higher_is_better=False),
+    "tool_success_rate": Thresholds(intact=0.80, ablated=0.50, higher_is_better=True),
+    "retry_count":       Thresholds(intact=2.0, ablated=5.0, higher_is_better=False),
+    "confidence":        Thresholds(intact=0.55, ablated=0.25, higher_is_better=True),
+}
+
+FAST_BASELINES: dict[str, float] = {
+    "latency_ms":          400.0,   # Haiku-class / short-turn
+    "tokens_used":         300.0,
+    "tool_success_rate":     0.95,
+    "retry_count":           0.0,
+    "confidence":            0.80,
+}
+
+FAST_THRESHOLDS: dict[str, Thresholds] = {
+    "latency_ms":        Thresholds(intact=1500.0, ablated=5000.0, higher_is_better=False),
+    "tokens_used":       Thresholds(intact=1500.0, ablated=5000.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),
+}
+
+AGENT_PROFILES: dict[str, tuple[dict[str, float], dict[str, Thresholds]]] = {
+    "default":   (AGENT_BASELINES,     AGENT_THRESHOLDS),
+    "reasoning": (REASONING_BASELINES, REASONING_THRESHOLDS),
+    "fast":      (FAST_BASELINES,      FAST_THRESHOLDS),
+}
+
+
+def agent_parser(
+    baselines: Optional[dict[str, float]] = None,
+    thresholds: Optional[dict[str, Thresholds]] = None,
+    profile: str = "default",
+) -> Parser:
+    """
+    Build a Parser with sensible agent-metric defaults.
+
+    ``profile`` picks a baseline set:
+
+        "default"    v0.11 thresholds \u2014 small-to-mid Claude / GPT calls
+        "reasoning"  long-context reasoning models (Opus-1M, o-series):
+                     ~8s/8k-token baselines, intact up to 20s/20k tokens
+        "fast"       Haiku-class short turns: ~400ms/300-token baselines
+
+    ``baselines`` and ``thresholds`` merge on top of the chosen profile, so you
+    can start from a profile and tweak the few components you care about::
+
+        parser = agent_parser(
+            profile="reasoning",
+            thresholds={"confidence": Thresholds(
+                intact=0.75, ablated=0.50, higher_is_better=True,
+            )},
+        )
+    """
+    if profile not in AGENT_PROFILES:
+        raise ValueError(
+            f"unknown profile {profile!r}; known: {sorted(AGENT_PROFILES)}"
+        )
+    profile_baselines, profile_thresholds = AGENT_PROFILES[profile]
+    merged_baselines = dict(profile_baselines)
+    if baselines:
+        merged_baselines.update(baselines)
+    merged_thresholds = dict(profile_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,
+    )