Metadata-Version: 2.5
Name: kade-agent-sdk
Version: 0.2.0
Summary: Creator SDK and CLI for Kade: verify gateway requests, report billable events, publish agents
Project-URL: Homepage, https://kade.taskmastergpt.nl/creators
Project-URL: Documentation, https://kade.taskmastergpt.nl/docs/creator
License-Expression: LicenseRef-PolyForm-Shield-1.0.0
License-File: LICENSE
Keywords: agents,fastmcp,kade,marketplace,mcp
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: <3.15,>=3.12
Requires-Dist: httpx>=0.28
Requires-Dist: pyjwt[crypto]>=2.10
Provides-Extra: fastmcp
Requires-Dist: fastmcp>=4.1; extra == 'fastmcp'
Description-Content-Type: text/markdown

# kade-agent-sdk

Creator SDK for [Kade](https://kade.taskmastergpt.nl): verify that requests come from the Kade
gateway, report billable events and answer data-subject (export/erase) requests.

```bash
uv add "kade-agent-sdk[fastmcp]"     # import name: marketplace_sdk
```

```python
from fastmcp import FastMCP
from marketplace_sdk import GatewayVerifier, gateway_claims, report_event
from marketplace_sdk.fastmcp import MarketplaceMiddleware, add_data_subject_tools

mcp = FastMCP("my-agent")
verifier = GatewayVerifier(
    jwks_url="https://kade.taskmastergpt.nl/.well-known/jwks.json",
    issuer="https://mcp.kade.taskmastergpt.nl",
    agent_id="agt_…",                       # from your creator console
)
mcp.add_middleware(MarketplaceMiddleware(verifier))

@mcp.tool
async def lookup(query: str) -> dict:
    report_event("record_found", 3)          # billed at your event price, capped per call
    return {"run_id": gateway_claims().run_id, "query": query}

# Required to publish. Stateless agents:
add_data_subject_tools(mcp, stores_no_user_data=True)
# ...or, if you keep data per user (subject = pseudonymous `sub` from the gateway token):
# add_data_subject_tools(mcp, erase=lambda s: db.delete(s), export=lambda s: db.records(s))

app = mcp.http_app(path="/mcp")             # serve with uvicorn on HTTPS
```

- `GatewayVerifier` checks EdDSA signature (JWKS cached 1 h, `kid` rotation), `iss`, `aud =
  agent:<agent_id>`, `exp` and `scope` (`call`, `register`, `verify`, `erase`, `export`).
- `MarketplaceMiddleware` verifies every request, rejects `register` tokens on tool calls, tokens
  issued for another tool and `erase`/`export` tokens outside the reserved tools, and merges
  reported events into the result `_meta`.
- `add_data_subject_tools` registers `kade_erase_subject` and `kade_export_subject`; Kade strips
  them from your listing and calls them only with `scope=erase`/`export` (SPEC §7.5).
- Not using FastMCP? Wrap your ASGI app in `marketplace_sdk.asgi.GatewayAuthMiddleware` and add
  `billing_meta({"record_found": 3})` to your result `_meta`.
- `gateway_claims().test` is true for creator test calls and verification runs (never billed).

## Publish from your repository: `kade`

The SDK installs a `kade` command that publishes the agent described by `kade.toml` (listing,
endpoint, prices, limits, data declaration, eval cases) through the Kade creator API, so you never
copy values into the console by hand.

```bash
kade login                       # paste a creator key (API keys → "Publishing agents")
kade apply                       # 1st run creates the agent and writes MARKETPLACE_AGENT_ID to .env
# deploy your server with that MARKETPLACE_AGENT_ID, then:
kade apply                       # registers the version, sets prices, limits, data, eval cases
kade test my_tool '{"q": "x"}'   # free test call
kade check                       # eval cases + security scan
kade submit                      # submit for review
kade status                      # checklist and the next step
```

`kade apply --dry-run` shows what would change; `--json` on any command prints the API response
for scripts and coding agents. `KADE_API_KEY` and `KADE_ENDPOINT_URL` override the saved key and
`[version] endpoint_url` (useful in CI); `KADE_UPSTREAM_KEY` sends an optional `X-Agent-Key` for
your server.

## License

[PolyForm Shield 1.0.0](LICENSE). In short: use it, change it and ship it in your agents,
including agents you sell on Kade; suggest changes to us. What it does not allow is offering the
SDK, or a product built with it, that competes with it or with Kade, for example reselling the SDK
or running a rival marketplace on it. This is a source-available license, not an OSI open-source
license.
