Metadata-Version: 2.4
Name: clawcash-forge
Version: 0.7.3
Summary: Forge telemetry, discovery, and feedback for FastAPI services
Requires-Python: >=3.11
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.27
Provides-Extra: test
Requires-Dist: build>=1; extra == 'test'
Requires-Dist: cdp-sdk==1.43.0; extra == 'test'
Requires-Dist: openapi-spec-validator>=0.7; extra == 'test'
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: x402==2.10.0; extra == 'test'
Description-Content-Type: text/markdown

# Forge for FastAPI (0.7.1)

Forge adds agent traffic telemetry, x402 discovery context, and service feedback to an existing FastAPI app. It does not replace your facilitator, verify payments, or settle funds.

This release matches the Express SDK (`@clawcash/forge` 0.7) on the collector contract: initialization, compact `feedback_id` invitations, pilot and sampled feedback, wallet-linked settlement identity, OpenAPI 3.0–3.2 enrichment, and merchant feedback relay. FastAPI remains ASGI-wrapped rather than Express middleware.

The package is named `clawcash-forge`, imported as `forge_sdk`. Install from PyPI:

```sh
python -m pip install clawcash-forge==0.7.1
```

## Integrate

Keep your FastAPI routes, lifespan, payment middleware, and facilitator registration as they are. Wrap the **finished app** and export that wrapper to Uvicorn:

```python
import os
from fastapi import FastAPI
from forge_sdk import init_forge

app = FastAPI()
# Register your existing routes and middleware here.
# This includes your existing x402 v1/v2 dispatch middleware.

application = init_forge(
    app,  # reads FORGE_API_KEY
    x402=resource_server,  # optional: same x402ResourceServer the middleware uses
)
```

```sh
uvicorn server:application
```

`app` is still your FastAPI object. `application` is the outer ASGI app that Uvicorn serves. Do not serve `server:app`, which bypasses Forge. With Nginx, preserve `payment-required`, `payment-response`, and legacy `x-payment-response` headers. Keep ASGI lifespan enabled. For an ASGI host without lifespan, explicitly `await application.start()` and `await application.close()` in the host's lifecycle.

Create an API key for your service in Forge first. Initialization downloads only that service's registered resource routes. Non-business routes such as health checks are excluded.

## What changes

- On registered x402 routes, captures status, duration, completion, agent type, client, and search query. Query strings, request bodies, and authorization/payment-signature headers are **not** exported wholesale.
- Captures discovery context from query parameters, JSON `agent_context` or legacy `_forge` (bodies up to 3 KB), and `X-Agent-Context` / `X-Forge-Context` headers. Runtime parsing never rejects a merchant request for missing context.
- Adds `agentType`, `agentTypeOther`, `client`, and `search_query` query declarations to GET/HEAD operations, and optional `agent_context` on eligible JSON request bodies. `agentType` and `client` are required in discovery documentation.
- Appends feedback guidance to existing `x-guidance` and `info.description`. OpenAPI 3.0, 3.1, and 3.2 are supported. Local response references and `allOf` object schemas are copied before extension. Ambiguous/composed/external response schemas are skipped.
- Adds a free `GET /feedback` questionnaire and `POST /feedback` submission route on the merchant's own origin. GET without a token returns the current form; GET with `token` fetches that invitation's questionnaire. Invalid submissions explain the accepted schema so an agent can retry.
- Adds only `feedback_id` to eligible successful JSON objects, and advertises it in their response schema. The ID is a registered short-lived credential linked to the interaction. Pilot mode (default) invites on every eligible response. `feedback_policy={"mode": "sampled", "sample_rate": 0.1}` requires a wallet-linked buyer grant, matching Express.
- Adds the feedback invitation to the v2 `payment-required` resource description. Recognized Bazaar `queryParams` declarations receive context fields; existing `agent_context` body declarations receive the same required fields as Express. Unknown/custom Bazaar schema layouts are preserved, not guessed.
- Reads settlement evidence from v2 `payment-response` and legacy `x-payment-response`, and recovers `scheme` / `asset` / amount from the request `payment-signature` (SettleResponse alone does not carry them). Challenge offers are recorded from `payment-required`. A 2xx status alone is never treated as payment. Network-qualified payer addresses from successful settlement evidence support Forge's global wallet-linked agent identity via a hashed `buyer_key`.
- Optional `x402=resource_server` (or `application.attach_x402(server)`) registers the same verify/settle observation hooks as the Express SDK, so paid calls are recorded even if a proxy strips settlement response headers.

Set `feedback=False` (or `enable_feedback=False`) for observation-only mode. This keeps request telemetry and discovery context (leave `discovery=True`, the default) while omitting feedback guidance, response IDs, feedback invitations, and the merchant feedback route. Set `discovery=False` as well only when the served OpenAPI document and x402 discovery context should remain untouched.

The legacy v1 challenge **body** is preserved byte for byte. Payment offers, recipients, assets, amounts, and opaque custom discovery fields are preserved. There is no monkey-patching of `_x402_mw`, `_settle_v1`, or facilitator functions. Do not describe this SDK as passive observation: the discovery and feedback changes above are intentional.

## Custom settlement paths

If your custom v1 implementation emits a standard settlement response header, Forge can read it automatically. Otherwise report its actual outcome after settlement, inside the request task:

```python
application.record_settlement(
    success=result.success,
    network="eip155:8453",  # or full Solana CAIP-2 network
    reference=result.transaction,
    payer=result.payer,
    protocol_version=1,
)
```

`record_payment(...)` accepts the same stages as Express (`challenge`, `attempt`, `verification`, `settlement`, `cancellation`) for custom stacks. Pass amount in base units as a string and asset address if available. Never infer payment from a request signature or HTTP 200. This is SDK-reported evidence, not independent on-chain verification. Custom background tasks outside the request context must not use these methods.

Prefer `x402=resource_server` when you already construct an `x402ResourceServer` for FastAPI payment middleware. Header observation remains the fallback and now merges accepted payment requirements from the request signature so successful settlements can enter Forge's paid ledger (`scheme=exact` plus network, asset, and transaction reference).

## Failure and response behavior

Collector initialization failures warn and retry in the background. The merchant app remains available, but telemetry, schema enrichment, and feedback IDs are unavailable until initialization succeeds. Configuration errors (invalid collector URL, missing key, feedback route collision, invalid feedback policy) raise at construction so they can be fixed before serving.

Telemetry uses a bounded in-memory queue. It is best-effort and may drop events during prolonged outages, overload, shutdown, or worker termination. Each worker owns its own queue. No disk spool is used. `application.diagnostics()` reports readiness, queue depth, verification, and feedback-grant counters.

Feedback link registration can add up to 1.5 seconds to eligible JSON responses. On failure the original response is returned. Streaming responses without a bounded Content-Length, responses larger than 64 KB, compressed/signed/cacheable responses, non-object JSON, and objects already containing reserved feedback fields are not modified. Bounded JSON responses may be buffered across chunks. Merchant exceptions and disconnect cancellation propagate normally.

The feedback endpoint is free and unauthenticated at the merchant boundary. Its token and answers are validated by Forge, which applies the existing feedback rules. Use your normal edge rate limits for this public endpoint.

```python
application = init_forge(
    app,
    api_url="https://dev-api.forge.clawca.sh",
    feedback_path="/feedback",  # or feedback_url="https://api.example.com/feedback"
    verification=True,  # automatic temporary ownership proof
    feedback=True,  # false disables feedback route, IDs and invitations
    discovery=True,  # false leaves the served OpenAPI/discovery unchanged
    feedback_policy={"mode": "pilot"},  # or {"mode": "sampled", "sample_rate": 0.1}
    queue_size=1000,
)
```

`FORGE_API_KEY` and optional `FORGE_FEEDBACK_URL` are read from the environment when those arguments are omitted. No public origin is inferred from Host or forwarded headers. Relative feedback URLs stay on the merchant origin; an absolute `feedback_url` must be HTTPS (or explicitly enabled localhost). Mount the wrapper at your API root. Register all merchant routes and custom OpenAPI generation before wrapping.

Inspect `application.diagnostics()` for `initialization`, `verification`, and `feedback` (including grant cache counters). `await application.ready()` waits for the first configuration attempt. `await application.shutdown()` aliases `close()`.

## Framework scope

FastAPI/ASGI only, not Flask/WSGI. Express-only helpers (`expressMiddleware`, `res.json` wrapping, `attachX402` on `@x402/express`) have ASGI equivalents above rather than the same function names. Compact `feedback_id` is the FastAPI invitation mode because FastAPI always serves OpenAPI; the Express legacy `service_feedback` URL invitation applies when that SDK is used without an OpenAPI document.

## Build and test

```sh
python -m pip install -e '.[test]'
python -m pytest
python -m build
```

The x402 integration test additionally requires `x402==2.10.0` and `cdp-sdk==1.43.0`. Test deployments use FastAPI 0.136.0 and Uvicorn 0.44.0, with a mock collector/facilitator and no payment. `contract.json` is copied from the Node SDK's feedback/context definitions to keep the collector contract aligned.

## Automatic ownership verification

Enabled by default. After initialization Forge obtains a temporary proof, adds `X-Forge-Verification` only to configured resource responses (including unpaid 402 responses), and polls the existing ownership API every 10 seconds. The backend makes an unpaid request to the registered public resource to verify control. Nginx must preserve this response header. No payment signature, API key, or expected proof is sent in that verification request.

Proof-bearing responses use `Cache-Control: private, no-store`. The SDK stops attaching the header after verification completes, when the proof expires, on authorization failure, and at shutdown. Already verified services receive no proof header, including after a restart. Existing merchant headers with the same name are preserved. Temporary collector failures do not block merchant requests. Pass `verification=False` to disable the handshake. `application.verification.status` exposes initializing, pending, complete, unavailable, or disabled.
