Forge SDK for Python

forgeintel-sdk (import forgeintel) brings Forge telemetry, agent context and feedback to x402 services running FastAPI, Starlette, or another ASGI app. Python 3.10+. Beta release on PyPI.

python -m pip install forgeintel-sdk==0.1.0b14

import os
from fastapi import FastAPI
from forgeintel import Forge, ForgeMiddleware

app = FastAPI()
# Install your x402 payment middleware here, FIRST.

forge = Forge(
    api_key=os.environ["FORGE_API_KEY"],
    feedback=True,  # the rating ask; off by default
    agent_context=True,  # ask agents who they are, optional; off by default
)
# Starlette runs the LAST added middleware FIRST.
app.add_middleware(ForgeMiddleware, forge=forge)

Complete runnable example: forge-examples/python-fastapi. Plain ASGI: app = forge.wrap(app). Use one Forge instance per application/event loop. ASGI lifespan shutdown flushes and closes Forge automatically. When lifespan is disabled, call await forge.shutdown() in your application's shutdown hook.

What ships

• x402 v1 JSON challenges / X-PAYMENT and v2 PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE. Existing payment terms stay intact. Merchant extensions are kept; in a Bazaar extension Forge only adds agent context to the input and a forge_feedback preview (sample ID) to a JSON output example.
• Locally signed feedback IDs, byte-compatible with the TypeScript SDK and Forge v2 collector. IDs, response decoration and context parsing need no Forge network round trip on the merchant request path. This is not a payment processor: the existing x402 middleware still verifies and settles payments.
• Background discovery, challenge and interaction telemetry with the same header allowlist as TypeScript, including Web Bot Auth signature headers. AgentCash, awal and pay.sh hints reach the backend, where caller classification and generic-traffic filtering happen.
• Agent visits: any other request from a signed or non-browser client (pages, free routes) is reported as a visit, so an agent's whole path through the service is visible. People and asset files are never reported; at most 120 a minute.
• Agent context asked for on paid requests when turned on (optional, or required when configured) and stripped before merchant validation, in JSON bodies or query parameters. Configured independently from feedback.
• Both feedback and agent_context are off by default: with only an API key, Forge reports telemetry and changes nothing agents see.
• Feedback ID header, optional JSON body fields and optional plain-text trailer; structured feedback in v2 challenge and successful settlement extensions.
• Public feedback form, GET rating, POST rating with note, cached summary. Only these explicit rating/summary routes await the Forge backend. The backend owns rating idempotency and the correction window.
• OpenAPI 3.0–3.2 / Swagger 2.0 JSON enrichment. Shared schema components remain untouched. Composed schemas are conservatively header-only; JSON/YAML that cannot be safely enriched is served unchanged.
• Bounded event queue (1,000), batches (100), 5-second delivery timeout, retry after failure, diagnostics and a bounded shutdown flush. Best-effort delivery, not durable storage; separate queues per worker. Requires an asyncio event loop.

Options

All option names use Python snake_case; pass keyword arguments to Forge or a ForgeOptions dataclass. The Python beta deliberately supports the core options, not TypeScript's custom tone/wording overrides.

Forge(..., http_client=client) accepts a caller-owned httpx.AsyncClient for custom transports/testing. The caller closes an injected client.

from forgeintel import AgentContextOptions, OpenAPIOptions

forge = Forge(
    api_key="ffk_...",
    feedback=True,
    agent_context=AgentContextOptions(required=True),
    # FastAPI doesn't infer 402 responses from payment middleware. Declare them
    # on paid routes, or explicitly select the paid operations here.
    openapi=OpenAPIOptions(is_paid_operation=lambda method, path, op: path == "/weather"),
)

Turned on (agent_context=True), context is optional: Forge asks for it, records it when sent, and never rejects a request without it. Required context (AgentContextOptions(required=True)) rejects payment-bearing requests with HTTP 400 before x402 processing. It requires an agent_type and search_query (direct when no search was used), unless search_query=False. Initial unpaid challenges, inspection and feedback routes remain available. This mode is opt-in.

JSON requests are read up to 1 MiB. Optional mode replays oversized, compressed or invalid bodies unchanged; use query parameters for those bodies. Required mode rejects unreadable JSON. Binary uploads are never buffered by Forge. Agent context is still stripped when collection is disabled, where the body can be inspected.

JSON responses are rewritten only when bounded to 1 MiB (5 MiB for OpenAPI). Unknown-length multi-chunk streams, SSE, compressed bodies, partial responses and binary files remain unchanged; successful paid responses still receive the ID header. Forge removes stale validators when it changes bytes and preserves repeated headers such as Set-Cookie. No feedback is injected into redirects or errors.

For strict response schemas, provide OpenAPIOptions(document=app.openapi) or a static document and call forge.enrich_openapi(app.openapi()) before serving traffic. Otherwise schema-aware body injection starts after the first spec fetch. For a mounted app or reverse-proxy root_path such as /api, configure public paths: base_path="/api/feedback" and OpenAPIOptions(paths=("/api/openapi.json",), ...). Place Forge inside response compression and outside payment middleware. Framework exceptions propagate normally; Forge never retries a merchant handler.

Development

python -m venv packages/sdk-python/.venv
packages/sdk-python/.venv/bin/pip install -e './packages/sdk-python[test]'
packages/sdk-python/.venv/bin/python -m pytest packages/sdk-python/tests
packages/sdk-python/.venv/bin/python -m build packages/sdk-python

Tests include the real x402==2.5.0 FastAPI middleware and client, with a fake facilitator (no funds spent), ASGI streaming/body limits and shared TypeScript ID vectors. Live merchant rollout is a separate step. MPP and Flask/WSGI are deferred.