margin 0.11.0__tar.gz → 0.12.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.11.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
@@ -64,7 +64,28 @@ 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.
 
-### Works with any MCP-capable client
+## 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:
 

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

@@ -33,7 +33,28 @@ 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.
 
-### Works with any MCP-capable client
+## 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:
 

{margin-0.11.0 → margin-0.12.0}/adapters/agent/__init__.py

@@ -23,12 +23,26 @@ 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 .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, agent_intent
+from .wrap import AgentStep, record_step, host_observe, agent_intent
+from .advisory import Advisory, AdvisoryResult, derive_advisory
 
 __all__ = [
-    "AGENT_BASELINES", "AGENT_THRESHOLDS", "agent_parser",
+    # Thresholds + profiles
+    "AGENT_BASELINES", "AGENT_THRESHOLDS",
+    "REASONING_BASELINES", "REASONING_THRESHOLDS",
+    "FAST_BASELINES", "FAST_THRESHOLDS",
+    "AGENT_PROFILES", "agent_parser",
+    # Flow
     "AGENT_STAGES", "agent_flow",
-    "AgentStep", "record_step", "agent_intent",
+    # 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/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,
+    )

{margin-0.11.0 → margin-0.12.0}/adapters/agent/wrap.py

@@ -34,7 +34,8 @@ of lines, e.g. for Anthropic::
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Optional
+from pathlib import Path
+from typing import Any, Optional
 
 from margin import (
     Expression, Intent, Requirement, Health, Ledger, Record, Op,
@@ -95,6 +96,93 @@ def record_step(
     return record
 
 
+def host_observe(
+    values: dict[str, float],
+    *,
+    state_path: Optional[str | Path] = None,
+    profile: str = "default",
+) -> dict[str, Any]:
+    """
+    Record an agent step from the **host** side (the dispatcher that knows the
+    real metrics), persisting through the same snapshot the margin-mcp server
+    uses.  Returns a dict with the expression atom, flow atom + guidance,
+    advisory, and summary counts of drift/anomaly trajectory.
+
+    Use this when your harness has ground-truth metrics (real latency, real
+    token counts, real tool-call outcomes) and wants to feed margin *instead
+    of* relying on the model to self-report via the ``margin_observe`` tool.
+
+    Snapshot path resolution:
+        1. ``state_path`` argument if given
+        2. ``MARGIN_MCP_STATE`` environment variable
+        3. ``~/.margin/mcp-state.json``
+
+    A margin-mcp server pointed at the same path sees the updates on its next
+    resource read \u2014 so the model can ``read margin://state`` and see what the
+    host observed, with no tool call at all.
+
+    Example::
+
+        from adapters.agent import host_observe
+
+        def dispatch_with_margin(messages):
+            t0 = time.perf_counter()
+            resp = client.messages.create(...)
+            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")
+            return resp, advisory
+    """
+    # Imports are local so ``from adapters.agent import host_observe`` doesn't
+    # eagerly import adapters.mcp.state (which itself is an adapter concern).
+    from adapters.mcp.state import load_session, save_session, state_path as _state_path
+    from .advisory import derive_advisory
+
+    if state_path is not None:
+        import os
+        os.environ["MARGIN_MCP_STATE"] = str(state_path)
+
+    monitor, flow, ledger = load_session(with_ledger=True)
+    monitor.update(dict(values))
+    flow_result = flow.observe(dict(values))
+
+    # Append to the ledger for downstream replay / diff.
+    step_index = len(ledger.records)
+    record_step(ledger, step_index, monitor.expression) if monitor.expression else None
+
+    save_session(monitor, flow, ledger)
+
+    # Trajectory from Monitor (may be None if insufficient samples)
+    drift_map = {}
+    anomaly_map = {}
+    for name in getattr(monitor.parser, "baselines", {}):
+        dc = monitor.drift(name) if hasattr(monitor, "drift") else None
+        if dc is not None:
+            drift_map[name] = dc
+        ac = monitor.anomaly(name) if hasattr(monitor, "anomaly") else None
+        if ac is not None:
+            anomaly_map[name] = ac
+
+    advisory = derive_advisory(
+        monitor.expression, flow_result=flow_result, drift_map=drift_map,
+    )
+
+    return {
+        "expression": monitor.expression.to_string() if monitor.expression else None,
+        "flow":       flow_result.to_atom(),
+        "guidance":   flow_result.guidance.value,
+        "advisory":   advisory.to_dict(),
+        "drift":      {n: getattr(dc.state, "value", str(dc.state)) for n, dc in drift_map.items()},
+        "anomaly":    {n: getattr(ac.state, "value", str(ac.state)) for n, ac in anomaly_map.items()},
+        "ledger_size": len(ledger.records),
+        "state_path": str(_state_path()),
+    }
+
+
 def agent_intent(deadline_seconds: Optional[float] = None) -> Intent:
     """
     Build a default Intent covering 'the agent run is still feasible' \u2014 a

{margin-0.11.0 → margin-0.12.0}/adapters/mcp/__init__.py

@@ -9,13 +9,19 @@ calls so state survives restarts.  The filesystem is the runtime \u2014 inspect
 
 Tools exposed to the model:
 
-    margin_observe(values={...})   record an agent step \u2192 expression + guidance
+    margin_observe(values={...})   record an agent step \u2192 expression +
+                                    flow guidance + typed Advisory
     margin_reset()                  start a fresh session
 
-Resources the model can read between turns:
+Resources the model can read between turns (no tool call needed):
 
-    margin://state                  current Expression + FlowResult as JSON
+    margin://state                  current Expression + FlowResult + drift +
+                                    anomaly + Advisory as JSON
     margin://issues                 current IssueBuffer.diagnose() output
+    margin://ledger                 last N Ledger records \u2014 trajectory across turns
+
+For harnesses with ground-truth metrics, prefer ``adapters.agent.host_observe``
+over the ``margin_observe`` tool so the model reads state rather than reports it.
 
 Install the optional MCP dependency and run the server: