Metadata-Version: 2.4
Name: agentic-scraper-provider-sdk
Version: 0.2.0
Summary: Server-side provider monetization SDK for Agentic Scraper
Project-URL: Documentation, https://docs.agenticscraper.com
Project-URL: Repository, https://github.com/berkbirkan/agentic-scraper-cloud
Project-URL: Issues, https://github.com/berkbirkan/agentic-scraper-cloud/issues
License: MIT
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# Agentic Scraper Provider SDK for Python

Server-side SDK for event-driven MCP Market monetization. Use it inside the MCP
or API service you publish as a provider. It is separate from the Agentic
Scraper client SDK used by consumers.

```bash
pip install agentic-scraper-provider-sdk
```

## How charging works

For a Marketplace entry configured with `provider_event` pricing, the Agentic
Scraper proxy forwards a signed `x-agentic-charge-token` header to your
service. Report a configured event and count with `charge()`. Always use the
returned `chargedCount`; it may be lower than requested when the buyer's
remaining run budget is limited.

## FastAPI / async example

```python
import os

from fastapi import FastAPI, Request
from agentic_scraper_provider import AsyncAgenticProviderClient

provider = AsyncAgenticProviderClient(api_key=os.environ["AGENTIC_PROVIDER_API_KEY"])
app = FastAPI()

@app.post("/mcp")
async def mcp(request: Request):
    records = await load_records()
    result = await provider.charge(
        charge_token=request.headers["x-agentic-charge-token"],
        event_name="record-returned",
        count=len(records),
        idempotency_key=f"record-export:{request.headers.get('x-request-id')}",
        metadata={"requestedCount": len(records)},
    )
    return records[:result["chargedCount"]]
```

## Flask / sync example

```python
import os

from flask import Flask, request
from agentic_scraper_provider import AgenticProviderClient

provider = AgenticProviderClient(
    api_key=os.environ["AGENTIC_PROVIDER_API_KEY"],
)
app = Flask(__name__)

@app.post("/summarize")
def summarize():
    summary = create_summary(request.json["text"])
    result = provider.charge(
        charge_token=request.headers["x-agentic-charge-token"],
        event_name="summary-created",
        idempotency_key=f"summary:{request.headers.get('x-request-id')}",
    )
    return {"summary": summary} if result["chargedCount"] == 1 else {"summary": None}
```

## Reliability rules

- Use a stable `idempotency_key` for every logical event.
- Return or process at most `result["chargedCount"]` units.
- Both clients retry transport failures, HTTP `429`, and `5xx` responses while
  preserving the same idempotency key.
- Validation and other `4xx` errors are not retried.
- Verification and production use the same `charge()` method. Verification
  returns `verification: true` and creates no billing activity.
- Keep the provider API key and charge token on the server. Never expose or log
  them.

`AgenticProviderClient` is synchronous for Flask and other WSGI applications.
`AsyncAgenticProviderClient` is intended for FastAPI and other ASGI services.
The default API base URL is `https://api.agenticscraper.com/api/v1`.

Full REST and SDK documentation is available at
https://docs.agenticscraper.com.
