needlepath 0.1.0__py3-none-any.whl

needlepath/errors.py

@@ -0,0 +1,123 @@
+"""The exception hierarchy.
+
+Every exception here is *recorded* rather than raised on the framework path
+(§8.2: fail open, always). They exist so that the recorded error carries a type
+a caller can branch on, and so that ``select_or_raise`` — the explicitly
+opt-in, explicitly-not-for-adapters variant — has something to raise.
+
+**Nothing in this module ever carries the API key.** Error messages are built
+from status codes, byte counts and the server's own bounded error bodies; the
+request headers are never interpolated into a message. That is asserted in
+``tests/test_no_secret_leak.py`` rather than left to care.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class NeedlepathError(Exception):
+    """Base class for everything this package raises or records."""
+
+
+class NeedlepathConfigError(NeedlepathError):
+    """A misconfiguration, detected at construction time.
+
+    This is the one class of failure that is *not* handled by failing open, and
+    the distinction is deliberate. Failing open on a bad request is degradation
+    a customer can absorb; failing open on "no operating point was pinned" would
+    silently accept exactly the behaviour drift §8.2 exists to prevent. A
+    configuration error is raised where it is made — at wire-up — never under
+    load.
+    """
+
+
+class NeedlepathTransportError(NeedlepathError):
+    """The request never produced an HTTP response (DNS, connect, reset, TLS)."""
+
+
+class NeedlepathTimeoutError(NeedlepathTransportError):
+    """The deadline elapsed before a response arrived."""
+
+
+class NeedlepathHTTPError(NeedlepathError):
+    """A non-2xx response.
+
+    ``body`` is the parsed JSON error body when the server sent one. Our own
+    error bodies are bounded and metadata-only by construction (they carry an
+    ``error`` enum plus counts); an intermediary's error page is truncated
+    before it is stored.
+    """
+
+    #: How much of a non-JSON error body is kept. An intermediary (a WAF, a
+    #: proxy) can return an arbitrarily large HTML page, and this error object
+    #: routinely ends up inside a caller's log line.
+    BODY_EXCERPT_MAX_CHARS = 512
+
+    def __init__(
+        self,
+        status: int,
+        *,
+        body: Any = None,
+        text: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        self.status = status
+        self.body = body
+        self.text = (text or "")[: self.BODY_EXCERPT_MAX_CHARS]
+        self.retry_after = retry_after
+        code = ""
+        if isinstance(body, dict):
+            raw = body.get("error")
+            if isinstance(raw, str):
+                code = f" ({raw})"
+        super().__init__(f"HTTP {status}{code}")
+
+    @property
+    def error_code(self) -> Optional[str]:
+        """The server's own ``error`` enum, when it sent one.
+
+        Open enum: ``bad_request``, ``request_too_large``, ``engine_error``,
+        ``not_found`` today. Callers must tolerate values they do not know.
+        """
+        if isinstance(self.body, dict):
+            raw = self.body.get("error")
+            if isinstance(raw, str):
+                return raw
+        return None
+
+
+class NeedlepathContractError(NeedlepathError):
+    """A 2xx body that violates the published response contract.
+
+    Missing a required field, or an echoed ``request_id`` that is not the one
+    that was sent. Both mean the response cannot be trusted to describe *this*
+    request, so it is not applied.
+    """
+
+
+class NeedlepathPayloadTooLargeError(NeedlepathError):
+    """The serialized request exceeded the client-side size guard.
+
+    Raised (and recorded) *before* any network call: §8.2 requires the 6 MB cap
+    to be guarded client-side rather than surfaced as a platform error from the
+    far side of the wire.
+    """
+
+    def __init__(self, size_bytes: int, limit_bytes: int) -> None:
+        self.size_bytes = size_bytes
+        self.limit_bytes = limit_bytes
+        super().__init__(
+            f"request body is {size_bytes} bytes, over the client guard of {limit_bytes} bytes"
+        )
+
+
+__all__ = [
+    "NeedlepathError",
+    "NeedlepathConfigError",
+    "NeedlepathTransportError",
+    "NeedlepathTimeoutError",
+    "NeedlepathHTTPError",
+    "NeedlepathContractError",
+    "NeedlepathPayloadTooLargeError",
+]

needlepath/features.py

@@ -0,0 +1,71 @@
+"""Feature flags for wire fields that are designed but not yet published.
+
+There is exactly one today, and it exists because the SDK has to ship a
+capability the *contract* has not shipped yet.
+
+Shadow mode
+-----------
+
+``NEEDLEPATH_SAAS_DESIGN.md`` §0.1 records the discrepancy plainly: the
+companion design calls ``mode: "shadow"`` a first-class wire field, but
+``BudgetSpec.mode`` on the published contract accepts only ``"fixed"`` and
+``"adaptive"``, and the string ``shadow`` appears nowhere in ``INTERFACE.md``.
+Adding it is a **public-repo contract change**, sequenced in E7 and required by
+E2's billing rule and E5's shadow report.
+
+So this SDK does what §8.2 asks for — "shadow mode is a one-line switch" — with
+the wire half feature-flagged off:
+
+* ``shadow=True`` **today**: the call is made exactly as a normal select call
+  (same body, same billing, same operating point), the full response comes back
+  and is reported, and **the selection is never applied**. The caller's original
+  context passes through untouched. That is the whole day-one integration path:
+  measure what Needlepath *would* have saved you, change nothing.
+* ``shadow=True`` **once the field ships**: flip ``WIRE_SHADOW_MODE`` and
+  ``budget.mode`` carries ``"shadow"`` on the wire. Client-side behaviour does
+  not change — it is already correct — so the flip is additive and reversible.
+
+Sending ``mode: "shadow"`` before the server knows it would be read as an
+unknown mode and fall through to the fixed-budget path (``select()`` branches on
+``== "adaptive"``), which is *silently the right answer for the wrong reason* —
+a fragile thing to depend on, and precisely why it is behind a flag instead of
+just being sent.
+
+The flag can be turned on for forward-compatibility testing without a release::
+
+    NEEDLEPATH_WIRE_SHADOW=1
+
+That override exists for our own integration tests against a server build that
+has the field. It is not a documented customer knob.
+"""
+
+from __future__ import annotations
+
+import os
+
+#: Whether ``budget.mode = "shadow"`` is emitted on the wire.
+#:
+#: **Flip this to ``True`` in the same change that lands the field in
+#: ``INTERFACE.md``.** Nothing else in this SDK needs to change.
+WIRE_SHADOW_MODE = False
+
+#: The value ``budget.mode`` takes when shadow is both requested and on the wire.
+WIRE_SHADOW_MODE_VALUE = "shadow"
+
+_ENV_OVERRIDE = "NEEDLEPATH_WIRE_SHADOW"
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+
+def wire_shadow_mode_enabled() -> bool:
+    """Whether to put ``shadow`` on the wire, env override included.
+
+    Read at call time rather than import time so a test can set the variable
+    without reimporting the package.
+    """
+    raw = os.environ.get(_ENV_OVERRIDE)
+    if raw is not None:
+        return raw.strip().lower() in _TRUTHY
+    return WIRE_SHADOW_MODE
+
+
+__all__ = ["WIRE_SHADOW_MODE", "WIRE_SHADOW_MODE_VALUE", "wire_shadow_mode_enabled"]

needlepath/models.py

@@ -0,0 +1,476 @@
+"""The wire contract, as plain dataclasses.
+
+This is an independent implementation of the published contract (``INTERFACE.md``
+in ``context-selection-bench``, mirrored by ``csbench.contracts``). It is copied
+rather than imported on purpose: the benchmark harness is a separate, public
+distribution with its own release cadence, and a client SDK that imports it
+would drag a research harness into every customer's dependency tree.
+
+Two properties are load-bearing and are asserted by
+``tests/test_wire_compatibility.py``:
+
+1. **Field names and defaults match the published contract exactly.** A field
+   that drifts here is a request the endpoint 400s or, worse, silently reads
+   differently.
+2. **``to_wire()`` emits the full shape**, ``None``\\ s and empty collections
+   included, exactly as the published client's ``dataclasses.asdict()`` does.
+   Emitting a compact body would be accepted by today's server — every optional
+   is read with ``.get(..., default)`` — but byte-compatibility with the client
+   that published runs cite is worth more than the few percent of payload it
+   costs, because it means "the harness works" and "the SDK works" are the same
+   statement.
+
+Unknown response fields are **ignored, never rejected**: the contract is
+additive under ``/v1`` (``API_VERSIONING.md``), and ``usage`` (E2) and
+``mode: "shadow"`` (§0.1) are both already scheduled to arrive that way.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+# --------------------------------------------------------------------------- #
+# Record kinds
+# --------------------------------------------------------------------------- #
+
+
+class RecordKind:
+    """The published record-role enum, as string constants.
+
+    Deliberately **not** an ``enum.Enum`` and deliberately not validated
+    client-side. The set is server-owned and additive; a client that rejects a
+    kind it has not heard of turns a server-side addition into a client-side
+    outage. An unknown kind is the server's 4xx/5xx to make, and the fail-open
+    path already covers it.
+    """
+
+    USER_INPUT = "user_input"
+    LLM_RESPONSE = "llm_response"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    EXTERNAL_DATA = "external_data"
+    ERROR = "error"
+    ARTIFACT = "artifact"
+    TOOL_SCHEMA = "tool_schema"
+
+
+# --------------------------------------------------------------------------- #
+# Request
+# --------------------------------------------------------------------------- #
+
+
+def _text(value: Any, default: str = "") -> str:
+    """A wire field that must be text, coerced rather than trusted.
+
+    The response comes off a socket. `rendered_context: 123` is a
+    contract-valid-looking 200 that turns into an `AttributeError` the first
+    time anything calls `.strip()` on it — and the place that happens is outside
+    the client's fail-open boundary, so a malformed response from a proxy or a
+    future server bug would reach the caller as a crash.
+
+    Coercing here rather than raising keeps a merely-sloppy field from
+    invalidating an otherwise usable response; the fields that must be *right*
+    (`request_id`, the required set) are still checked at the HTTP boundary.
+    """
+    if isinstance(value, str):
+        return value
+    if value is None:
+        return default
+    return str(value)
+
+
+@dataclass
+class ContextRecord:
+    """One unit of state the service may keep, drop, or excerpt."""
+
+    text: str
+    kind: str = RecordKind.EXTERNAL_DATA
+    id: Optional[str] = None
+    source: Optional[str] = None
+    title: Optional[str] = None
+    step_id: Optional[str] = None
+    importance: float = 0.0
+    keywords: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    attributes: Dict[str, Any] = field(default_factory=dict)
+
+    def to_wire(self) -> Dict[str, Any]:
+        return {
+            "text": self.text,
+            "kind": self.kind,
+            "id": self.id,
+            "source": self.source,
+            "title": self.title,
+            "step_id": self.step_id,
+            "importance": self.importance,
+            "keywords": list(self.keywords),
+            "tags": list(self.tags),
+            "attributes": dict(self.attributes),
+        }
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> ContextRecord:
+        return cls(
+            text=d["text"],
+            kind=d.get("kind", RecordKind.EXTERNAL_DATA),
+            id=d.get("id"),
+            source=d.get("source"),
+            title=d.get("title"),
+            step_id=d.get("step_id"),
+            importance=float(d.get("importance", 0.0)),
+            keywords=list(d.get("keywords", [])),
+            tags=list(d.get("tags", [])),
+            attributes=dict(d.get("attributes", {})),
+        )
+
+
+@dataclass
+class TaskSpec:
+    """The query the selected context has to serve."""
+
+    prompt: str
+    tool_name: Optional[str] = None
+    required_record_ids: List[str] = field(default_factory=list)
+    parent_record_ids: List[str] = field(default_factory=list)
+    keywords: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    step_id: Optional[str] = None
+    recent_prompts: List[str] = field(default_factory=list)
+    output_mode: Optional[str] = None
+    output_token_budget: Optional[int] = None
+
+    def to_wire(self) -> Dict[str, Any]:
+        return {
+            "prompt": self.prompt,
+            "tool_name": self.tool_name,
+            "required_record_ids": list(self.required_record_ids),
+            "parent_record_ids": list(self.parent_record_ids),
+            "keywords": list(self.keywords),
+            "tags": list(self.tags),
+            "step_id": self.step_id,
+            "recent_prompts": list(self.recent_prompts),
+            "output_mode": self.output_mode,
+            "output_token_budget": self.output_token_budget,
+        }
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> TaskSpec:
+        return cls(
+            prompt=d["prompt"],
+            tool_name=d.get("tool_name"),
+            required_record_ids=list(d.get("required_record_ids", [])),
+            parent_record_ids=list(d.get("parent_record_ids", [])),
+            keywords=list(d.get("keywords", [])),
+            tags=list(d.get("tags", [])),
+            step_id=d.get("step_id"),
+            recent_prompts=list(d.get("recent_prompts", [])),
+            output_mode=d.get("output_mode"),
+            output_token_budget=d.get("output_token_budget"),
+        )
+
+
+@dataclass
+class AdaptiveBudget:
+    """Budget-escalation ladder for ``mode="adaptive"``."""
+
+    initial_tokens: int
+    escalation_tokens: List[int] = field(default_factory=list)
+    allow_full_context_fallback: bool = True
+
+    def to_wire(self) -> Dict[str, Any]:
+        return {
+            "initial_tokens": self.initial_tokens,
+            "escalation_tokens": list(self.escalation_tokens),
+            "allow_full_context_fallback": self.allow_full_context_fallback,
+        }
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> AdaptiveBudget:
+        return cls(
+            initial_tokens=int(d["initial_tokens"]),
+            escalation_tokens=list(d.get("escalation_tokens", [])),
+            allow_full_context_fallback=bool(d.get("allow_full_context_fallback", True)),
+        )
+
+
+@dataclass
+class BudgetSpec:
+    """The operating point plus the arm-neutral budget overrides.
+
+    No method-tuning knob appears here, by contract: thresholds, weightings and
+    gate parameters are resolved server-side from ``operating_point``.
+    """
+
+    max_context_tokens: int
+    operating_point: Optional[str] = None
+    max_records: Optional[int] = None
+    max_excerpt_tokens_per_record: Optional[int] = None
+    mode: str = "fixed"  # "fixed" | "adaptive"  (see features.WIRE_SHADOW_MODE)
+    adaptive: Optional[AdaptiveBudget] = None
+    require_evidence_coverage: Optional[bool] = None
+
+    def to_wire(self) -> Dict[str, Any]:
+        return {
+            "max_context_tokens": self.max_context_tokens,
+            "operating_point": self.operating_point,
+            "max_records": self.max_records,
+            "max_excerpt_tokens_per_record": self.max_excerpt_tokens_per_record,
+            "mode": self.mode,
+            "adaptive": self.adaptive.to_wire() if self.adaptive is not None else None,
+            "require_evidence_coverage": self.require_evidence_coverage,
+        }
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> BudgetSpec:
+        adaptive = d.get("adaptive")
+        return cls(
+            max_context_tokens=int(d["max_context_tokens"]),
+            operating_point=d.get("operating_point"),
+            max_records=d.get("max_records"),
+            max_excerpt_tokens_per_record=d.get("max_excerpt_tokens_per_record"),
+            mode=d.get("mode", "fixed"),
+            adaptive=AdaptiveBudget.from_wire(adaptive) if adaptive else None,
+            require_evidence_coverage=d.get("require_evidence_coverage"),
+        )
+
+
+@dataclass
+class ContextRequest:
+    request_id: str
+    records: List[ContextRecord]
+    task: TaskSpec
+    budget: BudgetSpec
+    render: bool = True
+    render_format: str = "plain"  # "plain" | "hybrid"
+    return_per_record: bool = True
+
+    def to_wire(self) -> Dict[str, Any]:
+        return {
+            "request_id": self.request_id,
+            "records": [r.to_wire() for r in self.records],
+            "task": self.task.to_wire(),
+            "budget": self.budget.to_wire(),
+            "render": self.render,
+            "render_format": self.render_format,
+            "return_per_record": self.return_per_record,
+        }
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> ContextRequest:
+        return cls(
+            request_id=d["request_id"],
+            records=[ContextRecord.from_wire(r) for r in d.get("records", [])],
+            task=TaskSpec.from_wire(d["task"]),
+            budget=BudgetSpec.from_wire(d["budget"]),
+            render=bool(d.get("render", True)),
+            render_format=d.get("render_format", "plain"),
+            return_per_record=bool(d.get("return_per_record", True)),
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Response
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class SelectedRecord:
+    record_id: str
+    kind: str = RecordKind.EXTERNAL_DATA
+    title: Optional[str] = None
+    source: Optional[str] = None
+    score: float = 0.0
+    reason: str = ""
+    excerpt: str = ""
+    excerpt_format: str = "plain"
+    selected_tokens: int = 0
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> SelectedRecord:
+        return cls(
+            record_id=str(d["record_id"]),
+            kind=d.get("kind", RecordKind.EXTERNAL_DATA),
+            title=d.get("title"),
+            source=d.get("source"),
+            score=float(d.get("score", 0.0) or 0.0),
+            reason=_text(d.get("reason")),
+            # Coerced, not trusted: an adapter does `len(excerpt)` and
+            # `excerpt.strip()` on this, and an int here would raise inside the
+            # customer's agent rather than inside our fail-open boundary.
+            excerpt=_text(d.get("excerpt")),
+            excerpt_format=_text(d.get("excerpt_format"), "plain"),
+            selected_tokens=int(d.get("selected_tokens", 0)),
+        )
+
+
+@dataclass
+class SafetySummary:
+    selection_safe: bool = True
+    fallback_required: bool = False
+    fallback_reason: str = ""
+    coverage_score: float = 0.0
+    evidence_shape: str = "unknown"
+    evidence_terms: Optional[Dict[str, List[str]]] = None
+    repair_reasons: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> SafetySummary:
+        return cls(
+            selection_safe=bool(d.get("selection_safe", True)),
+            fallback_required=bool(d.get("fallback_required", False)),
+            fallback_reason=_text(d.get("fallback_reason")),
+            coverage_score=float(d.get("coverage_score", 0.0) or 0.0),
+            evidence_shape=_text(d.get("evidence_shape"), "unknown"),
+            evidence_terms=d.get("evidence_terms"),
+            repair_reasons=list(d.get("repair_reasons", [])),
+        )
+
+
+@dataclass
+class GateSummary:
+    """Neutral engage/stand-down summary.
+
+    ``reason`` is an **open, extensible enum** (``INTERFACE.md``). Nothing in
+    this SDK branches on its value, and nothing you build on this SDK should
+    either: a third outcome (*escalate*) is a planned additive change, and a
+    client that exhaustively matches today's two prefixes is a client that
+    breaks when it lands.
+    """
+
+    engaged: bool = False
+    reason: str = ""
+    signals: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> GateSummary:
+        return cls(
+            engaged=bool(d.get("engaged", False)),
+            reason=_text(d.get("reason")),
+            signals=dict(d.get("signals", {}) or {}),
+        )
+
+
+@dataclass
+class ContextResponse:
+    request_id: str
+    rendered_context: str
+    policy_version: Optional[str] = None
+    selected: List[SelectedRecord] = field(default_factory=list)
+    tokens_before: int = 0
+    tokens_after: int = 0
+    tokens_saved: int = 0
+    records_available: int = 0
+    records_selected: int = 0
+    fallback_used: bool = False
+    selection_error: Optional[str] = None
+    engine_latency_ms: float = 0.0
+    budget_tokens: int = 0
+    attempted_budget_tokens: List[int] = field(default_factory=list)
+    reduction_ratio: float = 0.0
+    safety: Optional[SafetySummary] = None
+    gate: Optional[GateSummary] = None
+    format_metrics: Dict[str, Any] = field(default_factory=dict)
+
+    #: Every response field this client does not model, kept verbatim. The
+    #: contract is additive under ``/v1``: ``usage`` (E2) and any later block
+    #: land here without a client release, and a caller can read them today.
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    _KNOWN = frozenset(
+        {
+            "request_id",
+            "rendered_context",
+            "policy_version",
+            "selected",
+            "tokens_before",
+            "tokens_after",
+            "tokens_saved",
+            "records_available",
+            "records_selected",
+            "fallback_used",
+            "selection_error",
+            "engine_latency_ms",
+            "budget_tokens",
+            "attempted_budget_tokens",
+            "reduction_ratio",
+            "safety",
+            "gate",
+            "format_metrics",
+        }
+    )
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> ContextResponse:
+        safety = d.get("safety")
+        gate = d.get("gate")
+        return cls(
+            request_id=d["request_id"],
+            rendered_context=_text(d.get("rendered_context")),
+            policy_version=(
+                _text(d["policy_version"]) if d.get("policy_version") is not None else None
+            ),
+            selected=[SelectedRecord.from_wire(s) for s in d.get("selected", []) or []],
+            tokens_before=int(d.get("tokens_before", 0)),
+            tokens_after=int(d.get("tokens_after", 0)),
+            tokens_saved=int(d.get("tokens_saved", 0)),
+            records_available=int(d.get("records_available", 0)),
+            records_selected=int(d.get("records_selected", 0)),
+            fallback_used=bool(d.get("fallback_used", False)),
+            selection_error=(
+                _text(d["selection_error"]) if d.get("selection_error") is not None else None
+            ),
+            engine_latency_ms=float(d.get("engine_latency_ms", 0.0)),
+            budget_tokens=int(d.get("budget_tokens", 0)),
+            attempted_budget_tokens=list(d.get("attempted_budget_tokens", []) or []),
+            reduction_ratio=float(d.get("reduction_ratio", 0.0)),
+            safety=SafetySummary.from_wire(safety) if safety else None,
+            gate=GateSummary.from_wire(gate) if gate else None,
+            format_metrics=dict(d.get("format_metrics", {}) or {}),
+            extra={k: v for k, v in d.items() if k not in cls._KNOWN},
+        )
+
+    # ----------------------------------------------------------------- #
+
+    @property
+    def selected_ids(self) -> set[str]:
+        """Every ``record_id`` the response claims to have selected."""
+        return {s.record_id for s in self.selected}
+
+    @property
+    def excerpts(self) -> Dict[str, str]:
+        """``record_id`` → excerpt, for the records the service kept.
+
+        Empty when the request set ``return_per_record=False``.
+        """
+        return {s.record_id: s.excerpt for s in self.selected}
+
+
+#: Fields every conformant response must carry. Checked at the HTTP boundary,
+#: exactly as the published client checks them.
+REQUIRED_RESPONSE_FIELDS = (
+    "request_id",
+    "rendered_context",
+    "tokens_before",
+    "tokens_after",
+    "tokens_saved",
+    "records_available",
+    "records_selected",
+    "fallback_used",
+    "engine_latency_ms",
+)
+
+
+__all__ = [
+    "RecordKind",
+    "ContextRecord",
+    "TaskSpec",
+    "AdaptiveBudget",
+    "BudgetSpec",
+    "ContextRequest",
+    "SelectedRecord",
+    "SafetySummary",
+    "GateSummary",
+    "ContextResponse",
+    "REQUIRED_RESPONSE_FIELDS",
+]