mnfst 0.1.0__py3-none-any.whl

mnfst/__init__.py

@@ -0,0 +1,43 @@
+"""manifest(): repair failing API requests on the fly, based on the API's error.
+
+    from mnfst import manifest
+    manifest()  # once, at startup
+
+Instruments the process's HTTP clients (httpx and requests). When a call your
+app makes fails, the failing request and the API's error go to Phoenix; if the
+server returns a repaired body, the call is retried once. Successes are never
+touched. The surface is three options: key, url, on_heal — everything that
+is policy (which providers and endpoints get healed, and how hard the server
+tries) is server-side configuration, editable in the dashboard.
+"""
+from __future__ import annotations
+
+import atexit
+import warnings
+from typing import Callable, Optional
+
+from .config import resolve_config
+from .heal_api import HealEvent
+from .outbound import flush, install_outbound, installed_config
+from .version import VERSION
+
+__all__ = ["manifest", "flush", "HealEvent", "VERSION"]
+
+atexit.register(flush, 2.0)
+
+
+def manifest(*, key: Optional[str] = None, url: Optional[str] = None,
+            on_heal: Optional[Callable] = None) -> None:
+    config = resolve_config(api_key=key, url=url, on_heal=on_heal)
+    if config.api_key is None:
+        warnings.warn("mnfst: MNFST_KEY is not set; mnfst is disabled.",
+                      stacklevel=2)
+        return
+    # Patching is process-global and one-shot. A second call with different
+    # options cannot take effect, so say so instead of pretending.
+    existing = installed_config()
+    if existing is not None and existing != config:
+        warnings.warn("mnfst: already installed with a different configuration; "
+                      "reconfiguring requires a restart. "
+                      "The first configuration stays in effect.", stacklevel=2)
+    install_outbound(config)

mnfst/config.py

@@ -0,0 +1,37 @@
+"""Options resolution: kwargs beat environment beats defaults.
+
+The surface is deliberately tiny: credentials, server, and a local
+observability hook. Everything that is policy — whether a given app,
+provider, endpoint, or direction gets healed, and how long the server may
+spend finding a fix — lives server-side, where it is editable in the
+dashboard without a deploy. The SDK only replays when the server hands it
+a healed body, so the server can enforce all of that with no client knob.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+HOSTED_URL = "https://api.manifest.build"
+
+# Hard client-side cap on a heal round-trip. Not configuration: fail-open
+# needs a deadline even when the server misbehaves. How long the server
+# actually spends investigating is server-side policy under this bound.
+HEAL_TIMEOUT_SECONDS = 60.0
+
+
+@dataclass(frozen=True)
+class Config:
+    api_key: Optional[str]
+    base_url: str
+    on_heal: Optional[Callable]
+
+
+def resolve_config(api_key: Optional[str] = None, url: Optional[str] = None,
+                   on_heal: Optional[Callable] = None) -> Config:
+    return Config(
+        api_key=api_key or os.environ.get("MNFST_KEY") or None,
+        base_url=(url or os.environ.get("MNFST_URL") or HOSTED_URL).rstrip("/"),
+        on_heal=on_heal,
+    )

mnfst/gate.py

@@ -0,0 +1,51 @@
+"""Capture any method, but only request-side failures.
+
+400/404/422 are the statuses where the failure is the request's fault —
+the only failures worth reporting and the only ones worth repairing.
+401/403 (auth), 402 (billing), 429 (rate limits) and every 5xx are excluded
+by design: editing the request cannot help, and reporting them is noise.
+
+That status gate is the client's only eligibility rule. Whether a captured
+failure gets retried is the server's call: the SDK retries when Phoenix
+hands back a healed request (CONTRACT §4).
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+GATED_STATUSES = frozenset({400, 404, 422})
+REQUEST_BODY_LIMIT = 262144  # past this a body is a payload, not a form to repair
+
+
+def should_capture(status: int) -> bool:
+    return status in GATED_STATUSES
+
+
+def parse_json_body(body_bytes: Optional[bytes]) -> Any:
+    """The request body as JSON — object, array or scalar — else None (absent,
+    huge, not JSON). Fails open on anything: deep nesting raises
+    RecursionError, and no parse failure may ever break the caller's request."""
+    if not body_bytes or len(body_bytes) > REQUEST_BODY_LIMIT:
+        return None
+    try:
+        parsed = json.loads(body_bytes)
+        return parsed if bounded_json(parsed) else None
+    except Exception:
+        return None
+
+
+def bounded_json(value: Any, max_depth: int = 64) -> bool:
+    """Bound depth and work independently of interpreter recursion behavior."""
+    stack = [(value, 0)]
+    visited = 0
+    while stack:
+        value, depth = stack.pop()
+        visited += 1
+        if depth > max_depth or visited > 100_000:
+            return False
+        if isinstance(value, dict):
+            stack.extend((child, depth + 1) for child in value.values())
+        elif isinstance(value, list):
+            stack.extend((child, depth + 1) for child in value)
+    return True

mnfst/heal_api.py

@@ -0,0 +1,242 @@
+"""The SDK's own calls to Phoenix. Everything here fails soft: a heal that
+cannot complete returns None and the caller serves the original response."""
+from __future__ import annotations
+
+import contextvars
+import threading
+import queue
+import logging
+import anyio
+import time
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+from .config import HEAL_TIMEOUT_SECONDS, Config
+from .version import VERSION
+from .gate import bounded_json
+
+logger = logging.getLogger("mnfst")
+_HEAL_SLOTS = threading.BoundedSemaphore(8)
+MAX_HEAL_RESPONSE = 1_048_576
+
+def _bounded_call(call):
+    if not _HEAL_SLOTS.acquire(blocking=False):
+        return None
+    result = queue.Queue(maxsize=1)
+    def run():
+        try:
+            result.put(call())
+        except Exception:
+            result.put(None)
+        finally:
+            _HEAL_SLOTS.release()
+    try:
+        threading.Thread(target=run, daemon=True).start()
+    except Exception:
+        _HEAL_SLOTS.release()
+        return None
+    try:
+        return result.get(timeout=HEAL_TIMEOUT_SECONDS)
+    except queue.Empty:
+        return None
+
+
+internal_call = contextvars.ContextVar("mnfst_internal_call", default=False)
+
+DISABLED_BACKOFF_SECONDS = 300
+MAX_INFLIGHT_REPORTS = 64
+
+# An attempt Phoenix opened that we never replayed (strip mode, or nothing
+# replayable came back). Reported so the attempt ledger closes instead of
+# holding open an answer that will never arrive.
+NOT_ATTEMPTED = "replay_not_attempted"
+
+
+@dataclass
+class HealEvent:
+    url: str
+    status_code: int
+    heal_status: str
+    replay_status_code: Optional[int]
+    heal_ms: int
+    operations: Optional[list]
+
+
+def _headers(config: Config) -> dict:
+    headers = {
+        "user-agent": f"mnfst-python/{VERSION}",
+        "x-mnfst-source": "python-sdk",
+    }
+    if config.api_key:
+        headers["authorization"] = f"Bearer {config.api_key}"
+    return headers
+
+
+class _Disable:
+    """Shared kill-switch backoff state."""
+
+    def __init__(self) -> None:
+        self._disabled_until = 0.0
+
+    def enabled(self) -> bool:
+        return time.monotonic() >= self._disabled_until
+
+    def trip(self) -> None:
+        self._disabled_until = time.monotonic() + DISABLED_BACKOFF_SECONDS
+
+
+def _is_app_disabled(response: httpx.Response) -> bool:
+    if response.status_code != 403:
+        return False
+    try:
+        body = response.json()
+        return isinstance(body, dict) and (body.get("error") == "project_disabled" or body.get("status") == "app_disabled")
+    except ValueError:
+        return False
+
+
+class HealApi:
+    def __init__(self, config: Config, transport: Optional[httpx.BaseTransport] = None):
+        self._client = httpx.Client(base_url=config.base_url, timeout=HEAL_TIMEOUT_SECONDS,
+                                    transport=transport, headers=_headers(config))
+        self._disable = _Disable()
+        self._pending: list[threading.Thread] = []
+        self._pending_lock = threading.Lock()
+        self.report_failures = 0
+        self.reports_dropped = 0
+
+    @property
+    def _disabled_until(self) -> float:
+        return self._disable._disabled_until
+
+    @_disabled_until.setter
+    def _disabled_until(self, value: float) -> None:
+        self._disable._disabled_until = value
+
+    def healing_enabled(self) -> bool:
+        return self._disable.enabled()
+
+    def heal(self, payload: dict) -> Optional[dict]:
+        return _bounded_call(lambda: self._heal(payload))
+
+    def _heal(self, payload: dict) -> Optional[dict]:
+        if not self._disable.enabled():
+            return None
+        token = internal_call.set(True)
+        try:
+            # The post() call stays inside the try: serializing a pathological
+            # payload can raise, and that must fail open like any other error.
+            if not bounded_json(payload):
+                return None
+            with self._client.stream("POST", "/v1/heal", json=payload) as streamed:
+                data = bytearray()
+                for chunk in streamed.iter_bytes():
+                    if len(data) + len(chunk) > MAX_HEAL_RESPONSE:
+                        return None
+                    data.extend(chunk)
+                response = httpx.Response(streamed.status_code, content=bytes(data))
+            if _is_app_disabled(response):
+                self._disable.trip()
+                return None
+            if response.status_code != 200:
+                return None
+            result = response.json()
+            return result if isinstance(result, dict) else None
+        except Exception:
+            return None
+        finally:
+            internal_call.reset(token)
+
+    def report_outcome(self, heal_attempt_id: str, retry_status_code: int,
+                       error: Any = None, truncated: bool = False) -> None:
+        if retry_status_code == 0:
+            body = {"failure": {"kind": "not_attempted" if error == NOT_ATTEMPTED else "transport_error", "message": error or NOT_ATTEMPTED}}
+        else:
+            body = {"response": {"statusCode": retry_status_code}}
+            if error is not None:
+                body["response"].update(body=error, truncated=truncated)
+
+        def _send() -> None:
+            internal_call.set(True)
+            try:
+                response = self._client.patch(f"/v1/heal-attempts/{heal_attempt_id}", json=body)
+                response.raise_for_status()
+            except Exception:
+                with self._pending_lock:
+                    self.report_failures += 1
+                logger.warning("Outcome report failed; attempt remains unconfirmed")
+
+        thread = threading.Thread(target=_send, daemon=True)
+        with self._pending_lock:
+            # Reports are fire-and-forget, so nothing else ever clears this in
+            # a long-running process — sweep the finished ones as we go, and
+            # under a flood drop the report rather than spawn without bound:
+            # a lost outcome costs one learning signal, not the host process.
+            self._pending = [t for t in self._pending if t.is_alive()]
+            if len(self._pending) >= MAX_INFLIGHT_REPORTS:
+                self.reports_dropped += 1
+                logger.warning("Outcome report capacity reached; report dropped")
+                return
+            self._pending.append(thread)
+            thread.start()
+
+    def join_pending_reports(self, timeout: float = 5.0) -> None:
+        deadline = time.monotonic() + timeout
+        with self._pending_lock:
+            pending = list(self._pending)
+        for thread in pending:
+            thread.join(max(0, deadline - time.monotonic()))
+
+
+class AsyncHealApi:
+    def __init__(self, config: Config, transport: Optional[httpx.AsyncBaseTransport] = None):
+        self._client = httpx.AsyncClient(base_url=config.base_url, timeout=HEAL_TIMEOUT_SECONDS,
+                                         transport=transport, headers=_headers(config))
+        self._sync = HealApi(config)  # outcome reports go out on threads either way
+        self._disable = self._sync._disable
+
+    def healing_enabled(self) -> bool:
+        return self._disable.enabled()
+
+    async def heal(self, payload: dict) -> Optional[dict]:
+        try:
+            with anyio.fail_after(HEAL_TIMEOUT_SECONDS):
+                return await self._heal(payload)
+        except TimeoutError:
+            return None
+
+    async def _heal(self, payload: dict) -> Optional[dict]:
+        if not self._disable.enabled():
+            return None
+        token = internal_call.set(True)
+        try:
+            # Same fail-open envelope as the sync client, serialization included.
+            if not bounded_json(payload):
+                return None
+            async with self._client.stream("POST", "/v1/heal", json=payload) as streamed:
+                data = bytearray()
+                async for chunk in streamed.aiter_bytes():
+                    if len(data) + len(chunk) > MAX_HEAL_RESPONSE:
+                        return None
+                    data.extend(chunk)
+                response = httpx.Response(streamed.status_code, content=bytes(data))
+            if _is_app_disabled(response):
+                self._disable.trip()
+                return None
+            if response.status_code != 200:
+                return None
+            result = response.json()
+            return result if isinstance(result, dict) else None
+        except Exception:
+            return None
+        finally:
+            internal_call.reset(token)
+
+    def report_outcome(self, heal_attempt_id: str, retry_status_code: int,
+                       error: Any = None, truncated: bool = False) -> None:
+        self._sync.report_outcome(heal_attempt_id, retry_status_code, error, truncated)
+
+    def join_pending_reports(self, timeout: float = 5.0) -> None:
+        self._sync.join_pending_reports(timeout)

mnfst/merge.py

@@ -0,0 +1,23 @@
+"""Settle a healed body against the one the caller sent (CONTRACT §4).
+
+Objects merge: the healed object decides every key it names, a key it
+omits is dropped (deletion-by-omission is how a field gets removed), and
+keys that never travelled — the credential-named ones withheld from the
+wire — are restored from the caller's copy unless the healed object names
+them. Anything else (arrays, scalars, a body that changed type) is replaced
+wholesale.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def merge_healed_body(original: Any, traveled: Any, healed: Any) -> Any:
+    if not isinstance(original, dict) or not isinstance(healed, dict):
+        return healed
+    merged = dict(healed)
+    traveled_keys = traveled.keys() if isinstance(traveled, dict) else ()
+    for key, value in original.items():
+        if key not in traveled_keys and key not in merged:
+            merged[key] = value
+    return merged

mnfst/outbound.py

@@ -0,0 +1,368 @@
+"""Auto-instrumentation of outbound HTTP clients (httpx and requests).
+Patches at TRANSPORT level: one hook per client library, so every client —
+including ones created before manifest() ran — is covered, and redirects,
+retries and streaming stay the client's business. The internal_call guard
+keeps the SDK's own Phoenix calls out of the loop.
+
+Per captured failure (CONTRACT §1): capture → heal → apply the server's
+healedRequest (url / headers / body) → retry once → report the outcome.
+"""
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from typing import Any, Mapping, Optional
+from urllib.parse import urlsplit
+
+import httpx
+
+from .config import Config
+from .gate import parse_json_body, should_capture
+from .heal_api import NOT_ATTEMPTED, AsyncHealApi, HealApi, HealEvent, internal_call
+from .merge import merge_healed_body
+from .response_capture import capture_httpx, capture_httpx_async, capture_requests
+from .wire import capped_response_body, heal_payload, safe_error_text, traveling_body
+
+_installed = False
+_installed_config: Optional[Config] = None
+_originals: dict = {}
+_reporters: list = []
+
+
+def flush(timeout: float = 5.0) -> None:
+    """Wait up to timeout seconds total for outstanding outcome reports."""
+    deadline = time.monotonic() + max(0, timeout)
+    for api in _reporters:
+        api.join_pending_reports(max(0, deadline - time.monotonic()))
+
+
+def installed_config() -> Optional[Config]:
+    """The config the process is instrumented with, or None. Patching is
+    process-global and one-shot, so a second manifest() with different options
+    cannot take effect — the entry point warns instead of silently ignoring."""
+    return _installed_config
+
+
+# --- the loop, client-agnostic ---------------------------------------------
+
+class _Capture:
+    """Everything the SDK knows about one failing call."""
+
+    def __init__(self, method: str, url: str, headers: Mapping[str, Any],
+                 content: Optional[bytes], status_code: int, raw_response: bytes,
+                 response_time_ms: int, incomplete: bool = False):
+        self.method = method or "GET"
+        self.url = url
+        self.headers = headers
+        self.content = content  # None = the body could not be read (streamed)
+        self.body = parse_json_body(content)
+        response_body, truncated = capped_response_body(raw_response)
+        self.payload = heal_payload(
+            trace_id=uuid.uuid4().hex, method=self.method, url=url, headers=headers,
+            body=self.body, status_code=status_code, response_body=response_body,
+            truncated=truncated or incomplete, response_time_ms=response_time_ms)
+        self.started = time.monotonic()
+
+
+class _Retry:
+    """A rebuilt request: the original with the server's changes applied."""
+
+    def __init__(self, url: str, headers: dict, content: Optional[bytes]):
+        self.url = url
+        self.headers = headers
+        self.content = content
+
+
+def _healed_request(result: Optional[dict]) -> Optional[dict]:
+    if not result or result.get("status") not in ("patched", "unverified"):
+        return None
+    healed = result.get("healedRequest")
+    if not isinstance(healed, dict) or not any(k in healed for k in ("url", "headers", "body")):
+        return None
+    return healed
+
+
+def _apply(capture: _Capture, healed: dict) -> Optional[_Retry]:
+    """CONTRACT §4: url replaces; headers set/replace, null removes; body
+    merges (objects) or replaces. Returns None when the retry cannot be
+    built (the original body was unreadable and the server sent no body)."""
+    url = healed.get("url") or capture.url
+    if not _same_origin(url, capture.url):
+        return None  # a URL heal may move the path, never the host: the
+                     # retry carries the caller's credentials (CONTRACT §4)
+    headers = {k: v for k, v in capture.headers.items() if k.lower() != "content-length"}
+    for name, value in (healed.get("headers") or {}).items():
+        headers = {k: v for k, v in headers.items() if k.lower() != str(name).lower()}
+        if value is not None:
+            headers[str(name)] = str(value)
+    if "body" in healed:
+        merged = merge_healed_body(capture.body, traveling_body(capture.body), healed["body"])
+        content: Optional[bytes] = json.dumps(merged).encode()
+    else:
+        content = capture.content
+        if content is None and capture.method not in ("GET", "HEAD", "DELETE", "OPTIONS"):
+            return None
+    return _Retry(url, headers, content)
+
+
+def _same_origin(url: str, original: str) -> bool:
+    try:
+        a, b = urlsplit(str(url)), urlsplit(str(original))
+    except Exception:
+        return False
+    return (a.scheme, a.netloc.lower()) == (b.scheme, b.netloc.lower())
+
+
+def _report(api, result: Optional[dict], retry_status: int,
+            error: Any = None, truncated: bool = False) -> None:
+    attempt_id = (result or {}).get("healAttemptId")
+    if attempt_id:
+        try:
+            api.report_outcome(attempt_id, retry_status, error, truncated)
+        except Exception:
+            pass
+
+
+def _emit(config: Config, capture: _Capture, result: Optional[dict],
+          retry_status: Optional[int], replay_attempted: bool = True) -> None:
+    if not config.on_heal:
+        return
+    try:
+        status = (result or {}).get("status") or "heal_unreachable"
+        if (replay_attempted and result and retry_status is None
+                and status in ("patched", "unverified")):
+            status = "replay_failed"
+        config.on_heal(HealEvent(
+            url=capture.payload["request"]["url"],
+            status_code=capture.payload["response"]["statusCode"],
+            heal_status=status, replay_status_code=retry_status,
+            heal_ms=int((time.monotonic() - capture.started) * 1000),
+            operations=(result or {}).get("operations")))
+    except Exception:
+        pass
+
+
+def _decide(config: Config, api, capture: _Capture, result: Optional[dict]) -> Optional[_Retry]:
+    """Turn a heal result into a retry, or close the attempt and return None."""
+    healed = None if capture.payload["response"]["truncated"] else _healed_request(result)
+    try:
+        retry = _apply(capture, healed) if healed else None
+    except Exception:
+        retry = None
+    if retry is None:
+        _report(api, result, 0, NOT_ATTEMPTED)
+        _emit(config, capture, result, None, replay_attempted=False)
+    return retry
+
+
+# --- httpx -------------------------------------------------------------------
+
+def _safe_request_content(request: httpx.Request) -> Optional[bytes]:
+    """A streamed or iterator request body raises RequestNotRead on `.content`.
+    Capture without it; a retry then needs the server to supply a body."""
+    try:
+        content = request.content
+    except Exception:
+        return None
+    return content if isinstance(content, bytes) else None
+
+
+def _rebuild(request: httpx.Request, retry: _Retry) -> httpx.Request:
+    # Extensions carry the per-request timeout (and the caller's trace hooks);
+    # dropping them would silently retry under the client default.
+    return httpx.Request(request.method, retry.url, headers=retry.headers,
+                         content=retry.content, extensions=dict(request.extensions))
+
+
+def install_outbound(config: Config, heal_api: Optional[HealApi] = None,
+                     async_heal_api: Optional[AsyncHealApi] = None) -> None:
+    global _installed, _installed_config
+    if _installed:
+        return
+    sync_api = heal_api or HealApi(config)
+    async_api = async_heal_api or AsyncHealApi(config)
+    _installed = True
+    _installed_config = config
+    _reporters[:] = [sync_api, async_api]
+
+    _originals["httpx_sync"] = httpx.HTTPTransport.handle_request
+    _originals["httpx_async"] = httpx.AsyncHTTPTransport.handle_async_request
+
+    def patched_sync(self, request: httpx.Request) -> httpx.Response:
+        original = _originals["httpx_sync"]
+        started = time.monotonic()
+        response = original(self, request)
+        elapsed_ms = int((time.monotonic() - started) * 1000)
+        if internal_call.get():
+            return response
+        try:
+            # Status decides capture, before the response body is touched — a
+            # successful streamed response is never read here.
+            if not should_capture(response.status_code) or not sync_api.healing_enabled():
+                return response
+            try:
+                response, raw = capture_httpx(response)
+            except Exception:
+                return response
+            capture = _Capture(request.method, str(request.url), request.headers,
+                               _safe_request_content(request), response.status_code,
+                               raw, elapsed_ms, response.extensions.get("mnfst_capture_incomplete", False))
+            result = sync_api.heal(capture.payload)
+            retry = _decide(config, sync_api, capture, result)
+            if retry is None:
+                return response
+            try:
+                retried = original(self, _rebuild(request, retry))
+                retry_body, truncated = None, False
+                if retried.status_code >= 400:
+                    retried, raw = capture_httpx(retried)
+                    retry_body, truncated = capped_response_body(raw)
+                    truncated = truncated or retried.extensions.get("mnfst_capture_incomplete", False)
+            except Exception as exc:
+                _report(sync_api, result, 0, safe_error_text(exc))
+                _emit(config, capture, result, None)
+                return response
+            _report(sync_api, result, retried.status_code, retry_body, truncated)
+            _emit(config, capture, result, retried.status_code)
+            try:
+                response.close()
+            except Exception:
+                pass
+            return retried
+        except Exception:
+            return response  # nothing in here may reach the caller
+
+    async def patched_async(self, request: httpx.Request) -> httpx.Response:
+        original = _originals["httpx_async"]
+        started = time.monotonic()
+        response = await original(self, request)
+        elapsed_ms = int((time.monotonic() - started) * 1000)
+        if internal_call.get():
+            return response
+        try:
+            if not should_capture(response.status_code) or not async_api.healing_enabled():
+                return response
+            try:
+                response, raw = await capture_httpx_async(response)
+            except Exception:
+                return response
+            capture = _Capture(request.method, str(request.url), request.headers,
+                               _safe_request_content(request), response.status_code,
+                               raw, elapsed_ms, response.extensions.get("mnfst_capture_incomplete", False))
+            result = await async_api.heal(capture.payload)
+            retry = _decide(config, async_api, capture, result)
+            if retry is None:
+                return response
+            try:
+                retried = await original(self, _rebuild(request, retry))
+                retry_body, truncated = None, False
+                if retried.status_code >= 400:
+                    retried, raw = await capture_httpx_async(retried)
+                    retry_body, truncated = capped_response_body(raw)
+                    truncated = truncated or retried.extensions.get("mnfst_capture_incomplete", False)
+            except Exception as exc:
+                _report(async_api, result, 0, safe_error_text(exc))
+                _emit(config, capture, result, None)
+                return response
+            _report(async_api, result, retried.status_code, retry_body, truncated)
+            _emit(config, capture, result, retried.status_code)
+            try:
+                await response.aclose()
+            except Exception:
+                pass
+            return retried
+        except Exception:
+            return response
+
+    httpx.HTTPTransport.handle_request = patched_sync
+    httpx.AsyncHTTPTransport.handle_async_request = patched_async
+    install_requests(config, sync_api)
+
+
+def uninstall_outbound() -> None:
+    global _installed, _installed_config
+    if not _installed:
+        return
+    httpx.HTTPTransport.handle_request = _originals["httpx_sync"]
+    httpx.AsyncHTTPTransport.handle_async_request = _originals["httpx_async"]
+    uninstall_requests()
+    _installed = False
+    _installed_config = None
+
+
+# --- requests ----------------------------------------------------------------
+
+def install_requests(config: Config, heal_api: HealApi) -> None:
+    try:
+        import requests.adapters
+    except ImportError:
+        return  # requests is not a runtime dependency; nothing to patch
+    if "requests_send" in _originals:
+        return
+
+    _originals["requests_send"] = requests.adapters.HTTPAdapter.send
+
+    def patched_send(self, request, **kwargs):
+        original = _originals["requests_send"]
+        started = time.monotonic()
+        response = original(self, request, **kwargs)
+        # `.elapsed` is only stamped by Session.send, after the adapter
+        # returns — so time the call here instead.
+        elapsed_ms = int((time.monotonic() - started) * 1000)
+        if internal_call.get():
+            return response
+        try:
+            if not should_capture(response.status_code) or not heal_api.healing_enabled():
+                return response
+            try:
+                response, raw = capture_requests(response)
+            except Exception:
+                return response
+            # A generator/file body is not bytes or str — capture without it,
+            # so a streamed upload is never consumed.
+            body = request.body
+            content = body if isinstance(body, bytes) else \
+                (body.encode() if isinstance(body, str) else None)
+            capture = _Capture(request.method, request.url, request.headers, content,
+                               response.status_code, raw, elapsed_ms, getattr(response, "_mnfst_capture_incomplete", False))
+            result = heal_api.heal(capture.payload)
+            retry = _decide(config, heal_api, capture, result)
+            if retry is None:
+                return response
+            try:
+                rebuilt = request.copy()
+                rebuilt.url = retry.url
+                rebuilt.headers.clear()
+                rebuilt.headers.update(retry.headers)
+                rebuilt.body = retry.content
+                if retry.content is not None:
+                    rebuilt.headers["content-length"] = str(len(retry.content))
+                retried = original(self, rebuilt, **kwargs)
+                retry_body, truncated = None, False
+                if retried.status_code >= 400:
+                    retried, raw = capture_requests(retried)
+                    retry_body, truncated = capped_response_body(raw)
+                    truncated = truncated or getattr(retried, "_mnfst_capture_incomplete", False)
+            except Exception as exc:
+                _report(heal_api, result, 0, safe_error_text(exc))
+                _emit(config, capture, result, None)
+                return response
+            _report(heal_api, result, retried.status_code, retry_body, truncated)
+            _emit(config, capture, result, retried.status_code)
+            try:
+                response.close()
+            except Exception:
+                pass
+            return retried
+        except Exception:
+            return response
+
+    requests.adapters.HTTPAdapter.send = patched_send
+
+
+def uninstall_requests() -> None:
+    if "requests_send" not in _originals:
+        return
+    import requests.adapters
+    requests.adapters.HTTPAdapter.send = _originals.pop("requests_send")

mnfst/py.typed

@@ -0,0 +1 @@
+

mnfst/response_capture.py

@@ -0,0 +1,169 @@
+"""Bounded capture of failures without consuming the caller's response.
+
+Keep a replayable raw prefix plus the remaining iterator. Successful responses
+never enter this module. Capture uses the original client's read timeout.
+"""
+from __future__ import annotations
+
+import io
+import zlib
+from typing import Iterator
+
+import httpx
+
+from .wire import RESPONSE_BODY_CAP
+
+
+class ReplayStream(httpx.SyncByteStream):
+    def __init__(self, chunks, iterator, original):
+        self.chunks, self.iterator, self.original = chunks, iterator, original
+
+    def __iter__(self):
+        yield from self.chunks
+        yield from self.iterator
+
+    def close(self):
+        self.original.close()
+
+
+class AsyncReplayStream(httpx.AsyncByteStream):
+    def __init__(self, chunks, iterator, original):
+        self.chunks, self.iterator, self.original = chunks, iterator, original
+
+    async def __aiter__(self):
+        for chunk in self.chunks:
+            yield chunk
+        async for chunk in self.iterator:
+            yield chunk
+
+    async def aclose(self):
+        await self.original.aclose()
+
+
+def _decode(raw: bytes, encoding: str) -> bytes:
+    encoding = encoding.lower().strip()
+    if not encoding or encoding == 'identity':
+        return raw
+    if encoding not in ('gzip', 'deflate'):
+        # Unsupported content coding: capture metadata, never interpret bytes
+        # as provider prose. The original wire response remains untouched.
+        return b''
+    try:
+        decoder = zlib.decompressobj(31 if encoding == 'gzip' else 15)
+        return decoder.decompress(raw, RESPONSE_BODY_CAP + 1)
+    except zlib.error:
+        return b''
+
+
+def capture_httpx(response: httpx.Response):
+    if response.is_stream_consumed:
+        return response, response.content[:RESPONSE_BODY_CAP + 1]
+    chunks, size = [], 0
+    incomplete = True
+    iterator = iter(response.stream)
+    try:
+        for chunk in iterator:
+            chunks.append(chunk)
+            size += len(chunk)
+            if size > RESPONSE_BODY_CAP:
+                break
+        else:
+            incomplete = False
+            response.close()
+    except Exception:
+        # Replay consumed bytes and the original exception to the caller.
+        # A failed capture must not turn a truncated response into success.
+        import sys
+        error = sys.exception() if hasattr(sys, 'exception') else sys.exc_info()[1]
+        def failed():
+            raise error
+            yield  # pragma: no cover
+        iterator = failed()
+    restored = httpx.Response(response.status_code, headers=response.headers,
+                              extensions={**response.extensions, "mnfst_capture_incomplete": incomplete},
+                              stream=ReplayStream(chunks, iterator, response))
+    raw = b''.join(chunks)[:RESPONSE_BODY_CAP + 1]
+    return restored, _decode(raw, response.headers.get('content-encoding', ''))
+
+
+async def capture_httpx_async(response: httpx.Response):
+    if response.is_stream_consumed:
+        return response, response.content[:RESPONSE_BODY_CAP + 1]
+    chunks, size = [], 0
+    incomplete = True
+    iterator = response.stream.__aiter__()
+    try:
+        async for chunk in iterator:
+            chunks.append(chunk)
+            size += len(chunk)
+            if size > RESPONSE_BODY_CAP:
+                break
+        else:
+            incomplete = False
+            await response.aclose()
+    except Exception as exc:
+        error = exc
+        async def failed():
+            raise error
+            yield  # pragma: no cover
+        iterator = failed()
+    restored = httpx.Response(response.status_code, headers=response.headers,
+                              extensions={**response.extensions, "mnfst_capture_incomplete": incomplete},
+                              stream=AsyncReplayStream(chunks, iterator, response))
+    raw = b''.join(chunks)[:RESPONSE_BODY_CAP + 1]
+    return restored, _decode(raw, response.headers.get('content-encoding', ''))
+
+
+class _Reader(io.RawIOBase):
+    def __init__(self, chunks: Iterator[bytes], original):
+        self.iterator, self.original, self.buffer = chunks, original, b''
+
+    def readable(self):
+        return True
+
+    def readinto(self, target):
+        while not self.buffer:
+            self.buffer = next(self.iterator, b'')
+            if not self.buffer:
+                return 0
+        size = min(len(target), len(self.buffer))
+        target[:size], self.buffer = self.buffer[:size], self.buffer[size:]
+        return size
+
+    def close(self):
+        self.original.close()
+        super().close()
+
+
+def capture_requests(response):
+    from itertools import chain
+    from urllib3.response import HTTPResponse
+    if response._content is not False:
+        return response, response.content[:RESPONSE_BODY_CAP + 1]
+    original = response.raw
+    chunks, size = [], 0
+    incomplete = True
+    iterator = original.stream(amt=65536, decode_content=False)
+    try:
+        for chunk in iterator:
+            chunks.append(chunk)
+            size += len(chunk)
+            if size > RESPONSE_BODY_CAP:
+                break
+        else:
+            incomplete = False
+    except Exception as exc:
+        error = exc
+        def failed():
+            raise error
+            yield  # pragma: no cover
+        iterator = failed()
+    response._mnfst_capture_incomplete = incomplete
+    reader = io.BufferedReader(_Reader(iter(chain(chunks, iterator)), original))
+    response.raw = HTTPResponse(body=reader, headers=dict(response.headers),
+                                status=response.status_code, preload_content=False,
+                                decode_content=False)
+    # requests extracts Set-Cookie from this stdlib response metadata.
+    response.raw._original_response = getattr(original, "_original_response", None)
+    raw = b''.join(chunks)[:RESPONSE_BODY_CAP + 1]
+    return response, _decode(raw, response.headers.get('content-encoding', ''))

mnfst/version.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+# Backward-compatible public name. The release value lives only above so Hatch,
+# package metadata, and the SDK's User-Agent cannot drift independently.
+VERSION = __version__

mnfst/wire.py

@@ -0,0 +1,155 @@
+"""Build the /v1/heal payload. The SDK never parses error dialects —
+the raw error body travels (capped) and the server normalizes (CONTRACT §3).
+
+Everything about the failing request travels — URL with query, headers,
+body — so the server has the whole context to heal with. Credential VALUES
+never do (CONTRACT §6): query/header values are masked to REDACTED with
+their names kept, and credential-named top-level body keys are withheld and
+restored on retry by the merge. `safe_url` / `safe_headers` output is for
+the wire only; never feed it back into a live request.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Mapping, Tuple
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+RESPONSE_BODY_CAP = 65536
+HEADER_VALUE_CAP = 1024
+ERROR_TEXT_CAP = 512
+
+# The client-side MINIMUM of credential-named fields (query params and body
+# keys). Matched after normalization; the server may know more names.
+SECRET_PARAMS = frozenset({
+    "api_key", "apikey", "api_token", "key", "token", "access_token", "refresh_token",
+    "auth", "authorization", "signature", "sig", "secret", "client_secret",
+    "password", "session", "session_id",
+    "bearer", "jwt", "id_token", "auth_token", "pwd", "passwd", "private_key",
+})
+
+# Header names are matched on ROOTS: any header whose normalized name contains
+# one carries a credential (authorization, proxy_authorization, x_api_key,
+# x_goog_api_key, cookie, x_amz_security_token, ...). Over-masking a harmless
+# header (idempotency_key) costs nothing — its presence still travels.
+SECRET_HEADER_ROOTS = ("auth", "key", "token", "secret", "session", "password",
+                       "passwd", "cookie", "signature", "credential", "bearer", "jwt")
+
+_CAMEL_BOUNDARY = re.compile(r"([a-z0-9])([A-Z])")
+
+
+def _normalize(name: str) -> str:
+    """X-Api-Key, apiKey and api_key are all the same secret."""
+    normalized = _CAMEL_BOUNDARY.sub(r"\1_\2", name).replace("-", "_").lower()
+    return normalized[2:] if normalized.startswith("x_") else normalized
+
+
+def is_secret_field(name: Any) -> bool:
+    return isinstance(name, str) and _normalize(name) in SECRET_PARAMS
+
+
+def is_secret_header(name: str) -> bool:
+    normalized = _normalize(name)
+    return normalized in SECRET_PARAMS or any(root in normalized for root in SECRET_HEADER_ROOTS)
+
+
+def safe_url(url: str) -> str:
+    parts = urlsplit(url)
+    query = parts.query
+    if query:
+        pairs = parse_qsl(query, keep_blank_values=True)
+        query = urlencode([(k, "REDACTED" if is_secret_field(k) else v) for k, v in pairs])
+    # user:password@host is a credential too — keep host[:port] only.
+    netloc = parts.netloc.rsplit("@", 1)[-1]
+    return urlunsplit((parts.scheme, netloc, parts.path, query, ""))
+
+
+def safe_headers(headers: Mapping[str, Any]) -> dict:
+    """Every header travels, lowercased; credential values are masked."""
+    out: dict = {}
+    try:
+        for name, value in headers.items():
+            key = str(name).lower()
+            text = value.decode("latin-1") if isinstance(value, bytes) else str(value)
+            out[key] = "REDACTED" if is_secret_header(key) else text[:HEADER_VALUE_CAP]
+    except Exception:
+        pass
+    return out
+
+
+def traveling_body(body: Any) -> Any:
+    """What of the body goes on the wire: an object minus its credential-named
+    top-level keys (the merge restores them on retry, CONTRACT §4); any other
+    JSON as-is."""
+    if isinstance(body, dict):
+        return {k: v for k, v in body.items() if not is_secret_field(k)}
+    return body
+
+
+# What a client's exception text embeds: a whole URL, or the rooted path plus
+# query it failed on (requests says "Max retries exceeded with url: /p?key=…").
+_URL_IN_TEXT = re.compile(
+    r"https?://[^\s'\"<>)\]}]+"
+    r"|/[^\s'\"<>)\]}]*\?[^\s'\"<>)\]}]+"
+)
+_PARAM_ASSIGNMENT = re.compile(r"([A-Za-z0-9_-]+)=([^\s&'\"<>)\]}]+)")
+
+
+def _mask_url_match(match: "re.Match") -> str:
+    try:
+        return safe_url(match.group(0))
+    except Exception:
+        return "REDACTED_URL"  # unparseable: drop it whole rather than guess
+
+
+def _mask_param_match(match: "re.Match") -> str:
+    name = match.group(1)
+    return f"{name}=REDACTED" if is_secret_field(name) else match.group(0)
+
+
+def safe_error_text(exc: Any) -> str:
+    """Exception text travels to Phoenix in the outcome report. An HTTP client
+    error embeds the URL it failed on — query secrets included — so mask
+    before it leaves the process."""
+    try:
+        text = str(exc)
+    except Exception:
+        return type(exc).__name__
+    try:
+        text = _URL_IN_TEXT.sub(_mask_url_match, text)
+        text = _PARAM_ASSIGNMENT.sub(_mask_param_match, text)
+    except Exception:
+        return type(exc).__name__
+    return text.encode("utf-8")[:ERROR_TEXT_CAP].decode("utf-8", "ignore")
+
+
+def capped_response_body(raw: bytes) -> Tuple[Any, bool]:
+    truncated = len(raw) > RESPONSE_BODY_CAP
+    raw = raw[:RESPONSE_BODY_CAP]
+    try:
+        return json.loads(raw), truncated
+    except Exception:
+        text = raw.decode("utf-8", "replace")
+        # Decoding can grow the body (each undecodable byte becomes a 3-byte
+        # replacement char), and it is the text that travels — so cap the text.
+        encoded = text.encode("utf-8")
+        if len(encoded) > RESPONSE_BODY_CAP:
+            text = encoded[:RESPONSE_BODY_CAP].decode("utf-8", "ignore")
+            truncated = True
+        return text, truncated
+
+
+def heal_payload(*, trace_id: str, method: str, url: str, headers: Mapping[str, Any],
+                 body: Any, status_code: int, response_body: Any, truncated: bool,
+                 response_time_ms: int) -> dict:
+    return {
+        "traceId": trace_id,
+        "request": {
+            "method": method.upper(),
+            "url": safe_url(url),
+            "headers": safe_headers(headers),
+            "body": traveling_body(body),  # any JSON; None when absent/huge/not JSON
+        },
+        "response": {"statusCode": status_code, "body": response_body, "truncated": truncated},
+        "responseTimeMs": response_time_ms,
+    }

mnfst-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: mnfst
+Version: 0.1.0
+Summary: Heal failing JSON API requests on the fly.
+Project-URL: Homepage, https://manifest.build
+Project-URL: Repository, https://github.com/mnfst/manifest-python
+Project-URL: Issues, https://github.com/mnfst/manifest-python/issues
+Requires-Python: >=3.10
+Requires-Dist: anyio<5,>=4
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: requests>=2.31; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Manifest for Python
+
+[![CI](https://github.com/mnfst/manifest-python/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mnfst/manifest-python/actions/workflows/ci.yml)
+
+Repair failed JSON API requests automatically. Works with `httpx` and `requests`, for everyday APIs and LLMs alike.
+
+```python
+from mnfst import manifest
+
+manifest()
+# Keep making your API calls as usual.
+```
+
+Your API rejects a request → Manifest finds a repair → the SDK retries once, locally.
+
+## Setup
+
+### 1. Install
+
+Requires **Python 3.10+**:
+
+```sh
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install mnfst
+```
+
+On Windows, activate with `.venv\Scripts\activate` instead. The package and import name are **mnfst**. `httpx` is included; install `requests` separately if you use it.
+
+### 2. Connect your project
+
+Create a project in your Manifest dashboard and copy the project key shown during setup. In **Project Settings**, turn **Autofix** on to enable repairs.
+
+```sh
+export MNFST_KEY='your-project-key'
+```
+
+The SDK defaults to `https://api.manifest.build`. For a local app running on port 5310, also set:
+
+```sh
+export MNFST_URL='http://127.0.0.1:5310'
+```
+
+Your server must support the [SDK API contract](CONTRACT.md). The local app must already be running.
+
+### 3. Initialize before your requests
+
+Call `manifest()` once at startup. Save this as `example.py`, replacing the example endpoint and payload with your own:
+
+```python
+import httpx
+from mnfst import manifest, flush
+
+manifest(
+    on_heal=lambda event: print(
+        "[manifest]", event.heal_status, event.replay_status_code
+    )
+)
+
+try:
+    response = httpx.post(
+        "https://api.example.com/orders",
+        json={"limit": 500},
+    )
+    print(response.status_code, response.text)
+finally:
+    flush(timeout=5)
+```
+
+Run it with `python example.py`. For an API that rejects `limit: 500` and has a matching repair, Manifest can retry with a valid limit. Repairs depend on the API error and available patches.
+
+The same initialization covers `httpx.AsyncClient` and `requests` calls using their standard transports.
+
+## Check that it works
+
+Send a JSON request that your test API rejects with **400, 404 or 422**. Check the failure in your project's dashboard and the `on_heal` callback for the repair result. A successful request alone does not contact Manifest. `flush()` lets a short script wait for outcome reports before exiting.
+
+## What to expect
+
+- **One retry.** Manifest returns a repair; the SDK sends the corrected request directly to your API.
+- **Original error if healing is unavailable.** A heal call can add up to 60 seconds. If a retry returns an HTTP response, that response reaches your application.
+- **Sync and async.** Standard `httpx` transports and `requests` adapters are covered process-wide. Custom transports and `aiohttp` are not intercepted.
+- **Retry semantics still matter.** Use idempotency keys where needed; a repeated request can repeat side effects.
+
+## Privacy
+
+Manifest receives failed request URLs, headers, JSON bodies and error responses. Known credential fields are masked or withheld, but nested secrets, prompts and business data can still be sent. Enable it only for traffic you permit your Manifest server to process and store.
+
+## More
+
+[Configuration, limits & development](docs/guide.md) · [API contract](CONTRACT.md) · [Node.js SDK](https://github.com/mnfst/manifest-node)

mnfst-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+mnfst/__init__.py,sha256=9qMBmHrYWaEpmZ_y-KMc1YiVkkVA2aWkMiqMb9Q0TE8,1787
+mnfst/config.py,sha256=W0DZrFbTnr__KYHUnZNFOjd3Yc1wQNk6l5_luyG16nY,1364
+mnfst/gate.py,sha256=HnEVwx2-z5k5XGn0k5kwcR7LWoFWvhtFOx5UWtP_tCY,1908
+mnfst/heal_api.py,sha256=SJNsuVFQjl-ZkjqR9tAOMzY6edyUT-IVsuXoagcRO7k,8852
+mnfst/merge.py,sha256=eLH5g69rY-rCTg57ZiQU5LsaZSeT3kUEZmO-ZAd7xrw,933
+mnfst/outbound.py,sha256=44Sp9X8fVaxXX_2LQBc7yL5F16Q_Qx7gwuOU80Eui-k,15827
+mnfst/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+mnfst/response_capture.py,sha256=S1LfrZTrg_w4P7-0uhBSbTDbwde3C3gQauyLYoZgOko,5935
+mnfst/version.py,sha256=FmVhVCCcR0wnEsA1rjRkb7hlpSR7ysl_gyuF-lhwSMI,198
+mnfst/wire.py,sha256=4D7ho2qHbLdgHHwdaH9BCs9YjY0DbEmVnVH_9MwEPpI,6122
+mnfst-0.1.0.dist-info/METADATA,sha256=9mKKDePOX4AaysTf_TyUtmsJPKlQoDh_GaIPDuhLsYE,3929
+mnfst-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mnfst-0.1.0.dist-info/RECORD,,

mnfst-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any