mnfst 0.1.0__tar.gz

mnfst-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q
+      - run: python -m pip wheel --no-deps . --wheel-dir dist

mnfst-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,93 @@
+name: Publish
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - src/mnfst/version.py
+  workflow_dispatch:
+
+concurrency:
+  group: publish-mnfst
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.detect.outputs.version }}
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Detect version bump
+        id: detect
+        env:
+          BEFORE_SHA: ${{ github.event.before }}
+          AFTER_SHA: ${{ github.sha }}
+          MANUAL: ${{ github.event_name == 'workflow_dispatch' }}
+        run: |
+          current=$(git show "${AFTER_SHA}:src/mnfst/version.py" | sed -n 's/^__version__ = "\([^"]*\)"$/\1/p')
+          if [ -z "$current" ]; then
+            echo "::error::Could not read the current package version."
+            exit 1
+          fi
+          if [ "$MANUAL" = "true" ]; then
+            echo "version=$current" >> "$GITHUB_OUTPUT"
+            echo "Manual dispatch: publishing $current"
+            exit 0
+          fi
+          if [ -n "$BEFORE_SHA" ] && [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
+            previous=$(git show "${BEFORE_SHA}:src/mnfst/version.py" 2>/dev/null | sed -n 's/^__version__ = "\([^"]*\)"$/\1/p')
+          else
+            previous=""
+          fi
+          if [ -n "$previous" ] && [ "$previous" != "$current" ]; then
+            echo "version=$current" >> "$GITHUB_OUTPUT"
+            echo "Version bumped: $previous -> $current"
+          else
+            echo "version=" >> "$GITHUB_OUTPUT"
+            echo "::notice::No version change; nothing to publish."
+          fi
+
+  build:
+    needs: detect
+    if: needs.detect.outputs.version != ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.14'
+          cache: pip
+      - run: python -m pip install build twine
+      - run: python -m pip install -e '.[dev]'
+      - run: python -m pytest -q
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: python-package-distributions
+          path: dist/
+          retention-days: 1
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mnfst
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2

mnfst-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+.superpowers/

mnfst-0.1.0/CONTRACT.md

@@ -0,0 +1,50 @@
+# SDK / app contract
+
+The SDK talks to the configured Manifest API using `Authorization: Bearer <project key>` and `User-Agent: mnfst-python/<version>`.
+
+## Capture
+
+`POST /v1/heal` receives:
+
+```json
+{
+  "traceId": "unique-capture-id",
+  "request": {"method": "POST", "url": "https://example.com/orders", "headers": {}, "body": {"limit": 200}},
+  "response": {"statusCode": 400, "body": {"error": "limit must be at most 100"}, "truncated": false},
+  "responseTimeMs": 25
+}
+```
+
+Credential filtering and body limits are described in the README. Capture gates live in `gate.py`; the server owns repair policy.
+
+A successful heal response may contain `status: patched|unverified`, `healAttemptId`, `operations` and `healedRequest` with `url`, `headers` or `body`. Only these two statuses authorize a retry. No patch, malformed responses and unavailable service return the original error response. HTTP 403 with `{"error":"project_disabled"}` suppresses healing for five minutes.
+
+## Apply
+
+A healed URL replaces the URL only within the original origin. Headers set or replace case-insensitively; null removes a header. Content length is recalculated. Objects merge using the server's healed body as the authoritative copy of fields sent to the server; withheld local credential fields are restored. Non-object JSON replaces the body. An unreadable original body needs a replacement body before it can be retried.
+
+Each captured failure permits one retry. A retry response, including another failure, is returned to the caller. A transport failure returns the original response. Successful response streams are not eagerly consumed.
+
+## Outcome
+
+`PATCH /v1/heal-attempts/:id` sends exactly one of:
+
+```json
+{"response":{"statusCode":200}}
+```
+
+```json
+{"response":{"statusCode":400,"body":{"error":"raw upstream error"},"truncated":false}}
+```
+
+```json
+{"failure":{"kind":"transport_error","message":"connection reset"}}
+```
+
+```json
+{"failure":{"kind":"not_attempted","message":"replay_not_attempted"}}
+```
+
+HTTP status must be 200–599. Failure messages are capped at 512 UTF-8 bytes after credential filtering. HTTP status zero is not a wire status. Transport failures and unattempted retries are inconclusive evidence; neither can verify or invalidate a patch. The server determines the verdict from the raw evidence, with the first accepted report winning.
+
+Reports are best effort, bounded, and observable through logger warnings. The SDK sends the failed retry's raw body so the app can distinguish recurrence from a newly revealed issue. It does not assert `succeeded` or `failed` itself.

mnfst-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,91 @@
+# 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/docs/guide.md

@@ -0,0 +1,56 @@
+# SDK guide
+
+[← Quick start](../README.md)
+
+## Configuration
+
+Call `manifest()` once at startup. Arguments override environment variables:
+
+| Argument | Environment | Default |
+| --- | --- | --- |
+| `key` | `MNFST_KEY` | Missing key disables the SDK with a warning |
+| `url` | `MNFST_URL` | `https://api.manifest.build` |
+| `on_heal` | — | Optional callback receiving a `HealEvent` |
+
+Use `url="http://127.0.0.1:5310"` with a local Manifest app. The hosted default requires a deployed, compatible app. Changing configuration after initialization requires a process restart.
+
+```python
+from mnfst import manifest, flush
+
+manifest(on_heal=lambda event: print(event.heal_status, event.replay_status_code))
+# Before a short-lived process exits:
+flush(timeout=5)
+```
+
+Reports run in background threads. `flush` waits for outstanding reports within one total timeout; it does not guarantee delivery. Normal interpreter exit allows two seconds to flush. Failed or dropped reports emit warnings on the `mnfst` logger. Abrupt termination can lose reports.
+
+## Behavior and limits
+
+- Standard httpx transports and requests adapters are instrumented process-wide, including existing clients. Custom transports, aiohttp, browsers and other languages are not covered.
+- Eligible HTTP failures are sent to Manifest; successful calls, authentication failures, rate limits and server errors pass through. A network failure before an HTTP response also passes through.
+- Manifest selects repairs. The SDK retries at most once per captured failure. The original error response is returned if healing is unavailable, no repair can be applied, or the retry has a transport error.
+- A successful streaming retry remains streamed. Error capture reads a bounded prefix and preserves the original response bytes for the caller. Error reads use the caller's read timeout; healing adds up to 60 seconds, and the retry uses the caller's timeout.
+- The sync heal worker pool permits eight concurrent calls. Excess calls fail open. Timed-out workers can continue in the background within that bound. Outcome reporting permits 64 concurrent reports per reporter.
+- Request JSON is limited to 256 KiB and depth 64. Multipart, binary, streamed, oversized and invalid JSON bodies travel as `null`; they are not generally repairable. Response metadata is limited to 64 KiB; truncated errors are reported without retry. Gzip and deflate error prefixes are decoded within that limit; unsupported content encodings provide no body evidence.
+- Retries can repeat side effects. Use APIs with safe retry semantics and caller-managed idempotency keys. Existing credentials and idempotency headers are retained unless explicitly changed by the repair. URL repairs must stay on the same origin.
+
+## Data sent to Manifest
+
+Failed request URLs, headers, JSON bodies and error responses are sent to the configured server. Known credential names in query parameters and headers are masked. Credential-named **top-level** request body fields are withheld and restored for the retry.
+
+This is not general data-loss prevention: nested fields, arbitrary secret names, personal data, prompts and response bodies may still contain sensitive content. Only enable it for traffic you permit Manifest to process and store. The server does not receive the original credential values masked by the SDK.
+
+## Development
+
+```sh
+pip install -e '.[dev]'
+pytest -q
+# Optional: point only at a disposable app (creates a test customer/project).
+MNFST_TEST_APP_URL=http://127.0.0.1:5310 pytest -q tests/test_live_app.py
+```
+
+CI tests Python 3.10, 3.13 and 3.14 and builds the wheel. The live app test runs locally because the app repository is private; cross-repository CI needs separate checkout credentials. Validated against app commit `9ea359279577f99e4058b7600c75889b1a2c5881`.
+
+See [CONTRACT.md](../CONTRACT.md) for the wire protocol. Transport failures require the app's explicit `failure` outcome support; they must never be reported as HTTP success.
+
+Adapted from [guillaumegay13/autofix-python](https://github.com/guillaumegay13/autofix-python), source commit `9a82d8235a037392826f982626f49422f3828213`.

mnfst-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "mnfst"
+dynamic = ["version"]
+readme = "README.md"
+description = "Heal failing JSON API requests on the fly."
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.24,<1", "anyio>=4,<5"]
+
+[project.urls]
+Homepage = "https://manifest.build"
+Repository = "https://github.com/mnfst/manifest-python"
+Issues = "https://github.com/mnfst/manifest-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "requests>=2.31"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mnfst"]
+
+[tool.hatch.version]
+path = "src/mnfst/version.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mnfst-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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