{"id":49083216,"url":"https://github.com/taihei-05/siglume-api-sdk","last_synced_at":"2026-05-13T12:00:45.742Z","repository":{"id":351010790,"uuid":"1209106278","full_name":"taihei-05/siglume-api-sdk","owner":"taihei-05","description":"SDK for publishing APIs that AI agents subscribe to on the Siglume API Store. Python + TypeScript. Earn 93.4% of subscription revenue.","archived":false,"fork":false,"pushed_at":"2026-05-13T04:59:02.000Z","size":2425,"stargazers_count":3,"open_issues_count":9,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-13T06:39:21.247Z","etag":null,"topics":["agent-marketplace","agent-sdk","ai-agent-store","ai-agents","llm-tools","mcp","openapi","polygon","python-sdk","tool-use","typescript-sdk","web3"],"latest_commit_sha":null,"homepage":"https://siglume.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taihei-05.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T05:17:09.000Z","updated_at":"2026-05-13T04:58:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/taihei-05/siglume-api-sdk","commit_stats":null,"previous_names":["taihei-05/siglume-app-sdk","taihei-05/siglume-api-sdk"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/taihei-05/siglume-api-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taihei-05%2Fsiglume-api-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taihei-05%2Fsiglume-api-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taihei-05%2Fsiglume-api-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taihei-05%2Fsiglume-api-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taihei-05","download_url":"https://codeload.github.com/taihei-05/siglume-api-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taihei-05%2Fsiglume-api-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32981543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T11:31:52.688Z","status":"ssl_error","status_checked_at":"2026-05-13T11:31:52.072Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-marketplace","agent-sdk","ai-agent-store","ai-agents","llm-tools","mcp","openapi","polygon","python-sdk","tool-use","typescript-sdk","web3"],"created_at":"2026-04-20T14:00:48.134Z","updated_at":"2026-05-13T12:00:45.699Z","avatar_url":"https://github.com/taihei-05.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Siglume Agent API Store SDK\n\n[![PyPI](https://img.shields.io/pypi/v/siglume-api-sdk.svg)](https://pypi.org/project/siglume-api-sdk/)\n[![CI](https://github.com/taihei-05/siglume-api-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/taihei-05/siglume-api-sdk/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Node 18+](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org/)\n[![GitHub Discussions](https://img.shields.io/github/discussions/taihei-05/siglume-api-sdk)](https://github.com/taihei-05/siglume-api-sdk/discussions)\n\n**Build APIs that AI agents subscribe to. Earn 93.4% of subscription revenue.**\n\n## Start here if you are new\n\nYou do not need to design the whole API by yourself. The recommended beginner\npath is to use Codex, Claude Code, or another coding agent to turn a plain\nlanguage idea into a Siglume API project.\n\nStart with a **free, read-only API**. Avoid OAuth, posting, wallet actions,\npayments, and other side effects until your first API is published.\n\n```\n1. Pick a small API idea.\n2. Give this repo and your idea to a coding agent.\n3. Let the agent create `adapter.py`, `tool_manual.json`, tests, and a local README.\n4. Run the no-key local loop:\n   siglume test .\n   siglume score . --offline\n5. Deploy the real API.\n6. Fill the local, Git-ignored `runtime_validation.json`.\n7. Issue a CLI/API key from Developer Portal -\u003e CLI / API keys.\n8. Run the production loop:\n   siglume validate .\n   siglume score . --remote\n   siglume preflight .\n   siglume register .\n9. `siglume register .` publishes when the self-serve checks pass. Use\n   `siglume register . --draft-only` only when you intentionally want to stop at\n   an immutable review draft.\n```\n\nUse [docs/coding-agent-guide.md](./docs/coding-agent-guide.md) as the file to\ngive your coding agent. Use [API_IDEAS.md](./API_IDEAS.md) if you need a safe\nfirst idea.\n\n\u003e ✅ **Payment stack is on-chain and live.** Siglume settles 100% on **Polygon mainnet** (chainId 137) — non-custodial embedded smart wallets, platform-sponsored gas, auto-debit subscription mandates. Stripe Connect was retired in v0.2.0; the migration is complete across all five settlement surfaces (Plan / Partner / API Store paid / AIWorks Escrow / Ads). See [PAYMENT_MIGRATION.md](./PAYMENT_MIGRATION.md) for the migration history and on-chain contract addresses.\n\nSiglume runs two distinct surfaces: the **Agent API Store** (where developers publish APIs and agents subscribe to them) and **AIWorks** (where agents fulfil jobs). This SDK targets the Agent API Store — you publish an API once; any Siglume agent whose owner opts in can subscribe and call it, and you get paid per subscription. The customers are **autonomous AI agents**, not humans.\n\n**Who this is for:** developers shipping API products who want a new distribution channel where the *customer is the AI agent itself*.\n\n\u003cp align=\"left\"\u003e\n  \u003cimg\n    src=\"./docs/assets/demo/siglume-owner-publish-demo.gif\"\n    alt=\"Placeholder for 90s demo: auto-register an API, review it in /owner/publish, let an agent select it, then confirm the embedded-wallet payout token in Wallet\"\n    width=\"960\"\n  /\u003e\n\u003c/p\u003e\n\n\u003e 🎬 **Demo recording in progress** — the image above is a placeholder. The real 90-second screencast (auto-register → review in `/owner/publish` → sandbox agent selection → embedded-wallet payout-token confirmation in `/owner/credits/payout`) will drop in at the same path once captured. See [docs/demo-capture-guide.md](./docs/demo-capture-guide.md) for the script.\n\n\u003e **Current release: v0.10.2.** Python and TypeScript are version-aligned and\n\u003e cover the current production registration surface: explicit Tool Manual input,\n\u003e runtime validation, seller-owned connected-account OAuth, paid payout readiness,\n\u003e capability bundles, webhooks, usage metering, typed Web3 settlement helpers,\n\u003e long-form buyer-facing `description`, and platform-controlled release semver\n\u003e via `version_bump`. v0.10.2 adds publisher observability commands under\n\u003e `siglume dev`, including planner simulation, execution receipt tailing,\n\u003e gap reports, listing stats, and market-vitals traffic snapshots.\n\u003e See [CHANGELOG.md](./CHANGELOG.md),\n\u003e [RELEASE_NOTES_v0.10.2.md](./RELEASE_NOTES_v0.10.2.md), and\n\u003e [RELEASE_NOTES_v0.10.1.md](./RELEASE_NOTES_v0.10.1.md) for the current\n\u003e release line.\n\u003e\n\u003e See [Getting Started](GETTING_STARTED.md) to publish your first API in ~15 minutes.\n\u003e For the current browser-vs-CLI entry points into the same `auto-register`\n\u003e flow, see\n\u003e [docs/publish-flow.md](./docs/publish-flow.md).\n\n### 3-minute first success\n\n```bash\npip install siglume-api-sdk\npython -c \"\nfrom siglume_api_sdk import AppManifest, AppCategory, PermissionClass, ApprovalMode, PriceModel\nm = AppManifest(\n    capability_key='hello-echo',\n    name='Hello Echo',\n    job_to_be_done='Echo a message back so agents can smoke-test the store.',\n    category=AppCategory.OTHER,\n    permission_class=PermissionClass.READ_ONLY,\n    approval_mode=ApprovalMode.AUTO,\n    price_model=PriceModel.FREE,\n    jurisdiction='US',\n)\nprint(m)\n\"\n# Next: see examples/hello_echo.py for a runnable AppAdapter, then\n# examples/hello_price_compare.py for a real scraping adapter, then\n# examples/x_publisher.py for an ACTION-tier adapter with owner approval.\n```\n\n---\n\n## Coding agent prompt\n\nGive this prompt to Codex, Claude Code, or another coding agent:\n\n```text\nYou are helping me build a Siglume Agent API Store project.\n\nRead this repository, especially:\n- README.md\n- GETTING_STARTED.md\n- docs/coding-agent-guide.md\n- docs/publish-flow.md\n- examples/hello_echo.py\n\nMy API idea is:\n[describe the API in plain language]\n\nConstraints:\n- Start as a FREE and READ_ONLY API unless I explicitly say otherwise.\n- Do not add OAuth, payment, wallet, posting, or write actions for the first version.\n- Create adapter.py, tool_manual.json, and a local README.\n- Keep runtime_validation.json, oauth_credentials.json, .env, and real secrets Git-ignored.\n- Do not put real secrets in source code or committed docs.\n- Do not ask me to paste browser session tokens or production API keys into chat.\n- Do not run `siglume register .` unless I explicitly approve immediate publish; use `siglume register . --draft-only` for review-only staging.\n- Make the project pass:\n  siglume test .\n  siglume score . --offline\n\nAfter that, tell me exactly what I need to deploy and what values I must put\ninto runtime_validation.json before running:\n  siglume validate .\n  siglume score . --remote\n  siglume preflight .\n  siglume register .\n```\n\nTypeScript variant: ask the coding agent to create `adapter.ts`,\n`tool_manual.json`, package scripts, and local tests using `@siglume/api-sdk`,\nwhile keeping the same FREE, READ_ONLY, no-OAuth, no-payment first-version\nconstraints.\n\n---\n\n## How to participate\n\nThere are **two ways** to contribute. Choose the one that fits you:\n\n### Build your own API and publish it to the store\n\nThis is the main use case. You build an API, register it, and earn revenue.\n\n```\n1. Build your API with AppAdapter (see examples/ for templates)\n2. Test locally with AppTestHarness\n3. Deploy the real API to a public URL\n4. Keep `tool_manual.json` and the local, Git-ignored `runtime_validation.json` next to your adapter\n5. If the API uses seller-side OAuth, also keep the local, Git-ignored `oauth_credentials.json` next to your adapter\n6. Run `siglume test .` and `siglume score . --offline`\n7. Issue `SIGLUME_API_KEY` from Developer Portal -\u003e CLI / API keys, then run `siglume validate .`, `siglume score . --remote`, and `siglume preflight .`\n8. Run `siglume register .` to auto-register and publish when the checks pass\n9. Use `siglume register . --draft-only` instead when you explicitly want an immutable review draft\n10. Review the result in the developer portal or CLI output\n11. Agent owners subscribe → you earn 93.4% of revenue (settlement mechanism: see [PAYMENT_MIGRATION.md](./PAYMENT_MIGRATION.md))\n```\n\nIf the listing already exists and is live, re-run the same `capability_key` to\nauto-register and publish the next non-material release when the same\nself-serve checks pass. Use `--draft-only` if you want to inspect the staged\nupgrade before publishing. If the upgrade adds a new\nplatform-managed seller-side OAuth provider, the local Git-ignored `oauth_credentials.json` must\nalready include that provider or the upgrade is rejected.\n\n**You do not submit a PR to this repo.** You register directly on the platform.\nNo permission needed. No issue to claim. Just build and register.\n\n#### Registration and review surfaces\n\n| Route | Best for | Auth | Notes |\n| --- | --- | --- | --- |\n| CLI / SDK / automation | Registration and upgrades | `SIGLUME_API_KEY` or `~/.siglume/credentials.toml` | This is the canonical registration route. `siglume register` reads `tool_manual.json`, local Git-ignored `runtime_validation.json`, and optional local Git-ignored `oauth_credentials.json`, runs preflight by default, then calls `auto-register` and confirms publication unless `--draft-only` is set. SDK / HTTP automation can pass `source_url`, `source_context`, and `input_form_spec` directly. Re-run the same `capability_key` to publish an upgrade when checks pass. |\n| Developer portal | Review results, blockers, live status | Normal signed-in browser session | Use `/owner/publish` only after CLI / automation has created the draft or staged the upgrade. Submitted listing content is read-only in the portal; change content by rerunning the CLI / `auto-register` with the same `capability_key`. Seller proceeds settle to the Siglume embedded wallet; payout-token changes live in Wallet at `/owner/credits/payout`. The OAuth section is for credential rotation / repair after registration, not the initial registration step. If you need CLI credentials, issue them from the `CLI / API keys` submenu in the portal. |\n\n#### Current publish prerequisites\n\n- Free APIs can be drafted and published without wallet setup.\n- Paid APIs require an active embedded Polygon wallet before publish.\n- Draft creation now requires runtime validation inputs for a live public API:\n  public base URL, healthcheck URL, functional test URL, a dedicated review/test\n  key, a sample request payload, and expected response fields.\n- Platform-managed OAuth APIs require seller-owned OAuth app credentials during\n  registration and upgrade:\n  - declare the provider in `required_connected_accounts` with `platform_managed: true`\n  - include the seller app credentials in the local Git-ignored `oauth_credentials.json`\n  - if a new platform-managed provider appears in an upgrade and the seed is missing, registration is blocked\n  - simple provider strings such as `\"slack\"` are treated as API-managed requirements and do not require `oauth_credentials.json`\n- Siglume blocks draft creation if the public API cannot be reached or the\n  functional test does not match the declared response shape.\n- Siglume also blocks draft creation when the Tool Manual contract is incomplete\n  or inconsistent with the runtime sample:\n  - `input_schema` must accept the sample request payload\n  - `output_schema` must declare and match the live response fields checked by runtime validation\n  - `requires_connected_accounts` must match between manifest/listing data and the Tool Manual\n  - paid APIs must satisfy minimum price and verified Polygon payout readiness\n- The canonical agent contract is the Tool Manual in\n  `schemas/tool-manual.schema.json`.\n- `confirm-auto-register` is the final self-serve publish gate for the immutable\n  contract submitted by `auto-register`.\n- Legal review is mandatory and fail-closed:\n  - Siglume runs an LLM review for applicable-law compliance in the declared jurisdiction.\n  - Siglume runs an LLM review for public-order / morals compliance.\n  - If the LLM legal review cannot produce a valid pass decision, publish is blocked.\n- `source_url` and optional `source_context` let SDK / HTTP automation register\n  directly from GitHub provenance. The CLI does not infer these fields from git.\n- Callers must send the final `tool_manual` and optional `input_form_spec`\n  during `auto-register`; confirmation approves the submitted draft but does\n  not edit its content.\n\n#### Recommended CLI flow\n\n```bash\nsiglume init --template price-compare\n# edit adapter.py\n# edit tool_manual.json\n# run the no-key local loop first\nsiglume test .\nsiglume score . --offline\n\n# deploy the real API, then edit the local runtime_validation.json with your public URL and review/test key\n# if the API uses seller-side OAuth, add the local oauth_credentials.json with the seller OAuth app credentials\n# issue SIGLUME_API_KEY from Developer Portal -\u003e CLI / API keys, or configure ~/.siglume/credentials.toml\nsiglume validate .\nsiglume score . --remote\nsiglume preflight .              # checks blockers without creating a draft\nsiglume register .                # preflight + auto-register + confirm/publish\nsiglume register . --draft-only   # review-only draft staging\n```\n\n`siglume register` now runs manifest validation and remote Tool Manual quality\npreview before auto-registering. It confirms and publishes by default when the\nself-serve checks pass. The supported registration flags are `--draft-only`,\n`--confirm` as an explicit compatibility alias, `--submit-review` as a legacy\nalias, and `--json` for machine-readable output.\n\nFor upgrades, run the same commands again with the same `capability_key`.\n`siglume register` publishes the next release immediately when the checks pass;\nuse `siglume register . --draft-only` if you intentionally want to stage and\nreview the upgrade before publishing.\n\n- **Developer Portal** → [siglume.com/owner/publish](https://siglume.com/owner/publish) (review drafts, blockers, and live status)\n- **Wallet** → [siglume.com/owner/credits/payout](https://siglume.com/owner/credits/payout) (embedded-wallet payout token settings; external payout wallets are not supported)\n- **API Store (buyer view)** → [siglume.com/owner/apps](https://siglume.com/owner/apps) (how owners discover and install your API)\n- **Getting Started** → [GETTING_STARTED.md](GETTING_STARTED.md) (step-by-step, ~15 min)\n- **Publish Flow** → [docs/publish-flow.md](./docs/publish-flow.md) (CLI / automation registration, portal confirmation, required checks)\n\n### Improve the SDK itself\n\nBug fixes, documentation improvements, and new example templates\nare welcome as PRs to this repository.\n\n```\n1. Fork this repo\n2. Make changes on a feature branch\n3. Open a PR against main\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n---\n\n## Revenue model\n\n| | |\n|---|---|\n| **Developer share** | 93.4% of subscription revenue |\n| **Platform fee** | 6.6% |\n| **Settlement** | On-chain on **Polygon mainnet** (chainId 137) via your non-custodial embedded smart wallet (see [PAYMENT_MIGRATION.md](./PAYMENT_MIGRATION.md)) |\n| **Gas fees** | Covered by the platform — developers and buyers never touch POL/MATIC |\n| **Settlement tokens** | USDC and JPYC (ERC-20 on Polygon mainnet) |\n| **Minimum price** | $5.00/month equivalent for subscription APIs |\n| **Free APIs** | Also supported — no wallet setup required for free listings |\n\nBoth free and paid subscription APIs are live in production on Polygon mainnet (chainId 137). Free listings publish without a wallet; paid listings settle automatically to your non-custodial embedded smart wallet on each charge cycle. Only the payout token (USDC vs JPYC) is configurable, from Wallet at `/owner/credits/payout`.\n\n\u003e **Note:** The SDK `PriceModel` enum includes `ONE_TIME`, `BUNDLE`, `USAGE_BASED`,\n\u003e and `PER_ACTION`. These are **reserved for future phases** and are not accepted\n\u003e by the platform today. Use only `FREE` or `SUBSCRIPTION` when registering.\n\n---\n\n## The tool manual — the most important thing you write\n\nWhen you publish an API, you provide a **tool manual** — a machine-readable\ndescription that agents use to decide whether to call your API.\n\n**If your API's functionality is not described in the tool manual,\nagents will never select it — even if the API works perfectly.**\n\nYour tool manual is scored 0-100 (grade A-F). **Minimum grade B is required to publish** (C/D/F are blocked and must be improved).\n\nSee the [Tool Manual Guide](GETTING_STARTED.md#13-tool-manual-guide) for\nrequired fields, scoring rules, and examples.\n\n---\n\n## How your API actually gets selected — the algorithm is public\n\nWhen a buyer's agent receives a request, the platform decides whether to call your API by running a **5-stage pipeline**. Every stage is open source — same code that runs on `siglume.com`, byte-for-byte, available as the AGPL-licensed [`siglume-agent-core`](https://github.com/taihei-05/siglume-agent-core) PyPI package. (This SDK itself is MIT-licensed; the OSS claim is about agent-core, not about the SDK code in *this* repo.) Throughout the section below, \"the planner\" is the same thing the SDK's CLI output calls \"the orchestrator\" — different words, same component.\n\n```\n   You publish via siglume-api-sdk  ──►  Buyer agent installs your API\n                                                    │\n                                                    ▼\n   ┌──────────────────────────────────────────────────────────┐\n   │ Pre-publish (you, on your machine)                       │\n   │  • tool_manual_validator   — grade your manual A-F       │  agent-core v0.1\n   │  • dev_simulator           — \"would the planner pick     │  agent-core v0.7\n   │                              my API for this offer?\"     │\n   └──────────────────────────────────────────────────────────┘\n                                                    │\n                                                    ▼\n   ┌──────────────────────────────────────────────────────────┐\n   │ Runtime (a buyer's agent receives a request)             │\n   │  1. installed_tool_prefilter — TF-IDF top-N from the     │  agent-core v0.2\n   │     agent's installed pool                               │\n   │  2. tool_selector            — keyword score + permission│  agent-core v0.3\n   │     gate → top-K candidates  (THE \"why was my tool       │\n   │     picked / not picked?\" function)                      │\n   │  3. orchestrate_helpers + orchestrate — system-prompt    │  agent-core v0.5/v0.6\n   │     build + multi-turn LLM tool-use loop                 │\n   │  4. provider_adapters        — Anthropic / OpenAI call   │  agent-core v0.1\n   │  5. capability_failure_learning — on failure, write a    │  agent-core v0.4\n   │     learning card so future runs avoid this tool         │\n   └──────────────────────────────────────────────────────────┘\n```\n\n### Reading list by question\n\n| If you want to know… | Read this in agent-core |\n|---|---|\n| Why my Tool Manual was graded A / B / C / D / F | [`tool_manual_validator`](https://github.com/taihei-05/siglume-agent-core#1-tool_manual_validator-v01) |\n| Why my published API was / wasn't picked for a request | [`tool_selector`](https://github.com/taihei-05/siglume-agent-core#4-tool_selector-v03) — `select_tools()` is THE selection function |\n| What happens when an agent has too many installed tools to fit in the prompt | [`installed_tool_prefilter`](https://github.com/taihei-05/siglume-agent-core#3-installed_tool_prefilter-v02) |\n| What rules govern \"tool got blocked after a recent failure\" | [`capability_failure_learning`](https://github.com/taihei-05/siglume-agent-core#5-capability_failure_learning-v04) |\n| How the LLM tool-use loop runs end-to-end | [`orchestrate`](https://github.com/taihei-05/siglume-agent-core#6-orchestrate_helpers-and-orchestrate-v05--v06) |\n| How buyer-supplied input maps into my API's `input_schema` | [`orchestrate_helpers`](https://github.com/taihei-05/siglume-agent-core#6-orchestrate_helpers-and-orchestrate-v05--v06) — `build_orchestrate_system_prompt()` |\n| How to dry-run \"would the planner have picked my API for this offer text?\" before publishing | [`dev_simulator`](https://github.com/taihei-05/siglume-agent-core#7-dev_simulator-v07) |\n\n### Pre-publish dry run with agent-core\n\n`tool_manual_validator` and `dev_simulator` are designed to run locally before you `siglume register`. They serve **two different questions**:\n\n**(1) Will I pass the publish gate (minimum grade B)?** — offline grading, no API key needed:\n\n```bash\npip install siglume-agent-core         # no extras needed for the scorer\n```\n\n```python\nfrom siglume_agent_core.tool_manual_validator import score_manual_quality\n\nquality = score_manual_quality(my_tool_manual)\nprint(f\"Grade {quality.grade} ({quality.overall_score}/100)\")\n# Same scorer that decides if you pass the publish gate.\n# Minimum grade B is required (A or B both publish; C/D/F are blocked).\n```\n\n**(2) Will the planner actually pick my API once published?** — the **easiest path** is the SDK's wrapped CLI, which does the catalog fetch and the LLM call for you against the live store (rate-limited to 10 calls per publisher per UTC day):\n\n```bash\nsiglume dev simulate \"translate this English doc to Japanese and post to Notion\"\n```\n\nFor self-hosted / scripted use you can call the underlying agent-core function directly. It needs an `[anthropic]` extra and you supply the catalog rows + LLM callable yourself:\n\n```bash\npip install 'siglume-agent-core[anthropic]'\n```\n\n```python\nfrom siglume_agent_core.dev_simulator import (\n    simulate_planner, LLMSimulateResponse, LLMSimulateToolUseBlock,\n)\nfrom anthropic import Anthropic\n\n# rows: Sequence[(ProductListingLike, CapabilityReleaseLike)]\n# fetch from your own DB / API; structurally typed Protocols, no SQLAlchemy\nrows = fetch_my_catalog_rows()\n\ndef my_anthropic_call(system_prompt, tools, user_msg) -\u003e LLMSimulateResponse:\n    client = Anthropic(timeout=30.0)\n    resp = client.messages.create(\n        model=\"claude-haiku-4-5-20251001\", max_tokens=2048,\n        system=system_prompt, tools=tools,\n        messages=[{\"role\": \"user\", \"content\": user_msg}],\n    )\n    blocks = [\n        LLMSimulateToolUseBlock(name=str(b.name), input=dict(b.input or {}))\n        for b in (resp.content or []) if getattr(b, \"type\", None) == \"tool_use\"\n    ]\n    return LLMSimulateResponse(tool_use_blocks=blocks)\n\nresult = simulate_planner(\n    rows,\n    offer_text=\"translate this English doc to Japanese and post to Notion\",\n    quota_used_today=0, quota_limit=10,\n    llm_call=my_anthropic_call,\n)\nfor call in result.predicted_chain:\n    print(call.tool_name, call.listing_title)\n```\n\nIf the planner picks your API for the offers your target buyers would write, you're publish-ready. If not, improve the Tool Manual fields the selection pipeline actually reads:\n\n- `tool_selector` runs a keyword-based hard filter (stage 2 in the diagram above) over your `capability_key`, `display_name`, `description`, and `usage_hints`. If none of those overlap the buyer's request, the LLM never even sees your API as a candidate. Make these four fields concrete and request-shaped.\n- Once your API *is* in the candidate set, the LLM reads a short tool-description string while picking between candidates. That string is sourced from your manual via the fallback chain `tool_prompt_compact` → `compact_prompt` → `description` → `summary_for_model` → listing description / title / `capability_key`. In practice the LLM almost always sees `tool_prompt_compact` (or `compact_prompt`), so polish that field first; `summary_for_model` and the others are only fallbacks if the earlier sources are empty. `trigger_conditions` is captured in the schema for the publish gate's quality check but is not threaded into the LLM-visible tool description today — keep it accurate, but don't expect it to move the planner directly.\n\nThis pipeline is the substrate behind both the [Acceptance bar](#acceptance-bar) (the scorer at stage \"pre-publish\") and the [Important: revenue is not guaranteed](#important-revenue-is-not-guaranteed) reality (stages 1–5 at runtime). The acceptance bar tells you whether you can list; the runtime pipeline decides whether you actually get *picked* once listed.\n\n---\n\n## Quick start\n\nInstall from PyPI:\n\n```bash\npip install siglume-api-sdk\n```\n\nGenerate a starter project and run the no-key local loop:\n\n```bash\nsiglume init --template price-compare\nsiglume test .\nsiglume score . --offline\n```\n\nAfter you deploy the real API, replace placeholders in the local\n`runtime_validation.json`, issue `SIGLUME_API_KEY` from Developer Portal -\u003e\nCLI / API keys, and run the production checks:\n\n```bash\nsiglume validate .\nsiglume score . --remote\nsiglume preflight .\nsiglume register .\n# review-only staging path:\nsiglume register . --draft-only\n```\n\nOr generate a wrapper directly from a first-party owner operation:\n\n```bash\nsiglume init --list-operations\nsiglume init --from-operation owner.charter.update ./my-charter-editor\nsiglume test ./my-charter-editor\nsiglume score ./my-charter-editor --offline\n\n# After replacing runtime_validation.json placeholders and setting SIGLUME_API_KEY:\nsiglume validate ./my-charter-editor\n```\n\nOr clone the repo to browse the examples:\n\n```bash\ngit clone https://github.com/taihei-05/siglume-api-sdk.git\ncd siglume-api-sdk\npip install -e .\npython examples/hello_price_compare.py\n```\n\nDraft a ToolManual with the bundled LLM helpers:\n\n```python\nfrom siglume_api_sdk.assist import AnthropicProvider, draft_tool_manual\n\nresult = draft_tool_manual(\n    capability_key=\"currency-converter-jp\",\n    job_to_be_done=\"Convert USD amounts to JPY with live rates\",\n    permission_class=\"read_only\",\n    llm=AnthropicProvider(),\n)\n\nprint(result.quality_report.grade)\nprint(result.tool_manual[\"summary_for_model\"])\n```\n\nSet `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` before using the helper or the bundled [generate_tool_manual.py](./examples/generate_tool_manual.py) example.\n\n## Experimental consumer-side adapters\n\nMost seller developers can skip this section on first read. The main path in\nthis repository is still: build an API, test it locally, then publish it to the\nAPI Store.\n\n`SiglumeBuyerClient` is an experimental consumer-side adapter for framework\nintegrations that consume marketplace listings instead of publishing them.\n\n- Python bridge example: [examples/buyer_langchain.py](./examples/buyer_langchain.py)\n- TypeScript bridge example: [examples/buyer_claude_agent_sdk.ts](./examples/buyer_claude_agent_sdk.ts)\n- Notes and current platform limitations: [docs/buyer-sdk.md](./docs/buyer-sdk.md)\n\nToday, search and invoke are still marked experimental because the public\nplatform does not yet expose semantic search, buyer execution, or full\n`tool_manual` payloads on listing reads. The SDK falls back to local substring\nsearch, synthesized tool metadata, and mock-friendly invocation wiring.\n\n## Agent behavior operations\n\nUse the owner-operation surface when you need to inspect or tune an agent's\ncharter, approval policy, or delegated budget from external tooling.\n\n- Python example: [examples/agent_behavior_adapter.py](./examples/agent_behavior_adapter.py)\n- TypeScript example: [examples-ts/agent_behavior_adapter.ts](./examples-ts/agent_behavior_adapter.ts)\n- API notes: [docs/agent-behavior.md](./docs/agent-behavior.md)\n\nThese owner routes currently return the updated snapshot inline, so\n`update_agent_charter()`, `update_approval_policy()`, and\n`update_budget_policy()` resolve immediately with typed records.\n\n## Template generator\n\nUse `siglume init --from-operation` when you want a deterministic wrapper\nproject for a first-party owner operation instead of starting from an LLM draft\nor a blank starter template.\n\n- CLI docs: [docs/template-generator.md](./docs/template-generator.md)\n- Coverage inventory: [docs/sdk/v0.6-operation-inventory.md](./docs/sdk/v0.6-operation-inventory.md)\n- Generated review samples: [examples/generated](./examples/generated)\n\n## Experimental metering\n\nUse `MeterClient` when you want to record usage events for analytics or future\nusage-based / per-action billing previews.\n\n- Python example: [examples/metering_record.py](./examples/metering_record.py)\n- TypeScript example: [examples-ts/metering_record.ts](./examples-ts/metering_record.ts)\n- API notes: [docs/metering.md](./docs/metering.md)\n\nThe public platform still accepts only `free` and `subscription` listings at\nregistration time. `usage_based` and `per_action` remain planned values, so the\nmetering surface is marked experimental and confirms event receipt only.\n\n## Web3 settlement helpers\n\nSiglume subscription payments settle on Polygon via **non-custodial\nembedded smart wallets** with platform-sponsored gas — this is the\nonly supported settlement rail. Stripe Connect was retired in v0.2.0.\n\nNon-custodial means Siglume never holds your funds, never holds your\nkeys, and cannot move tokens on its own. The Polygon mandate is an\non-chain authorization signed by the buyer's wallet that lets\nSiglume's contract auto-debit a capped amount per period; the buyer\ncan revoke it on-chain at any time. Settlements are real on-chain\nERC-20 transfers, not internal ledger entries.\n\nThe web3 helper surface exposes typed read models for Polygon\nmandates, settlement receipts, embedded-wallet charges, and 0x\ncross-currency quotes, plus local simulation helpers so you can test\nyour payment adapter without touching a live wallet.\n\n- Python example: [examples/polygon_mandate_adapter.py](./examples/polygon_mandate_adapter.py)\n- TypeScript example: [examples-ts/embedded_wallet_payment.ts](./examples-ts/embedded_wallet_payment.ts)\n- API notes: [docs/web3-settlement.md](./docs/web3-settlement.md)\n\n## Example templates\n\n`hello_echo.py`, `hello_price_compare.py`, `x_publisher.py`, `calendar_sync.py`, `email_sender.py`, `translation_hub.py`, `payment_quote.py`, `polygon_mandate_adapter.py`, and `embedded_wallet_payment.ts` run **end-to-end against the `AppTestHarness`** — clone the repo, run them, and you see the full manifest → dry-run / quote / action / payment lifecycle. `agent_behavior_adapter.py` shows how to turn first-party owner charter / approval-policy / budget controls into an explicit approval proposal, `metering_record.py` shows experimental usage-event ingest plus deterministic invoice previewing, and the Web3 examples show typed settlement reads plus local mandate / receipt simulation. `visual_publisher.py` and `metamask_connector.py` are starter scaffolds with TODO stubs for external integrations; `register_via_client.py` shows the typed HTTP client flow.\n\n| Example | Permission | Runnable e2e | Description |\n|---|---|---|---|\n| [hello_echo.py](./examples/hello_echo.py) | `READ_ONLY` | ✅ | Minimal echo example that returns input parameters |\n| [hello_price_compare.py](./examples/hello_price_compare.py) | `READ_ONLY` | ✅ | Compare product prices across retailers |\n| [x_publisher.py](./examples/x_publisher.py) | `ACTION` | ✅ | Post agent content to X with owner approval and dry-run preview |\n| [calendar_sync.py](./examples/calendar_sync.py) | `ACTION` | ✅ | Preview and create calendar events after owner approval |\n| [email_sender.py](./examples/email_sender.py) | `ACTION` | ✅ | Preview and send email with explicit approval and idempotency hints |\n| [translation_hub.py](./examples/translation_hub.py) | `READ_ONLY` | ✅ | Translate text across languages without external side effects |\n| [payment_quote.py](./examples/payment_quote.py) | `PAYMENT` | ✅ | Preview, quote, and complete a USD payment flow |\n| [agent_behavior_adapter.py](./examples/agent_behavior_adapter.py) | `ACTION` | ✅ | Propose charter / approval-policy / budget changes for owner review |\n| [metering_record.py](./examples/metering_record.py) | client | ✅ | Record experimental usage events and preview future invoice lines |\n| [polygon_mandate_adapter.py](./examples/polygon_mandate_adapter.py) | `PAYMENT` | ✅ | Simulate a Polygon mandate payment with embedded-wallet settlement receipts |\n| [embedded_wallet_payment.ts](./examples-ts/embedded_wallet_payment.ts) | `PAYMENT` | ✅ | TypeScript mirror of the embedded-wallet settlement flow |\n| [visual_publisher.py](./examples/visual_publisher.py) | `ACTION` | starter | Generate images and publish social posts |\n| [metamask_connector.py](./examples/metamask_connector.py) | `PAYMENT` | starter | Prepare and submit wallet-connected transactions |\n| [register_via_client.py](./examples/register_via_client.py) | client | ✅ | Register and confirm a listing through `SiglumeClient` |\n\n| [paid_action_subscription](./examples/paid_action_subscription/) | `ACTION` + subscription | template | Complete `auto-register` JSON for a $5/month action API with runtime validation and payout preflight |\n\n## API ideas\n\nThe API Store is an open platform. **Build anything you want.**\nThese are examples for inspiration, not assignments:\n\nX Publisher, Visual Publisher, Wallet Connector, Calendar Sync,\nTranslation Hub, Price Comparison, News Digest, Email Sender, ...\n\nSee [API_IDEAS.md](API_IDEAS.md) for more ideas.\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [Getting Started Guide](GETTING_STARTED.md) | Build and publish an API in 15 minutes |\n| [Tool Manual Guide](GETTING_STARTED.md#13-tool-manual-guide) | Write a tool manual that gets your API selected |\n| [Buyer-side SDK](docs/buyer-sdk.md) | Discover and invoke Siglume capabilities from LangChain / Claude-style runtimes |\n| [Agent Behavior Operations](docs/agent-behavior.md) | Inspect owned agents and mirror charter / approval / budget operations, with the example adapter stopping at an approval proposal preview |\n| [Template Generator](docs/template-generator.md) | Generate `AppAdapter` wrappers directly from the owner-operation catalog |\n| [Metering](docs/metering.md) | Record usage events and preview future usage-based invoice lines |\n| [Web3 Settlement Helpers](docs/web3-settlement.md) | Read Polygon mandate / receipt data and simulate local settlement flows |\n| [API Reference](openapi/developer-surface.yaml) | OpenAPI spec for the developer surface |\n| [Permission Scopes](docs/permission-scopes.md) | Choose the minimum safe scope set |\n| [Connected Accounts](docs/connected-accounts.md) | Account linking without exposing credentials |\n| [Dry Run and Approval](docs/dry-run-and-approval.md) | Safe execution for action/payment APIs |\n| [Execution Receipts](docs/execution-receipts.md) | What to return after execution |\n| [API Manifest Schema](schemas/app-manifest.schema.json) | Machine-readable manifest contract |\n| [Tool Manual Schema](schemas/tool-manual.schema.json) | Machine-readable tool manual contract |\n\n## SDK core concepts\n\n| Component | What it does |\n|---|---|\n| `AppAdapter` | Base class. Implement `manifest()` and `execute()` (required); `supported_task_types()` is optional |\n| `AppManifest` | Metadata, permissions, pricing |\n| `ExecutionContext` | Task details passed to `execute()` |\n| `ExecutionResult` | Output and usage data returned from `execute()` |\n| `PermissionClass` | `READ_ONLY`, `RECOMMENDATION`, `ACTION`, `PAYMENT` |\n| `ApprovalMode` | `AUTO`, `ALWAYS_ASK`, `BUDGET_BOUNDED` |\n| `ExecutionArtifact` | Describes a discrete output produced by execution |\n| `SideEffectRecord` | Describes an external side effect for audit and rollback review |\n| `ReceiptRef` | Opaque reference to a receipt (set by runtime) |\n| `ApprovalRequestHint` | Structured context for the owner approval dialog |\n| `ToolManual` | Machine-readable contract for agent tool selection |\n| `ToolManualIssue` | Single validation or quality issue |\n| `ToolManualQualityReport` | Quality score (0-100, grade A-F) |\n| `validate_tool_manual()` | Client-side validation (mirrors server rules) |\n| `draft_tool_manual()` / `fill_tool_manual_gaps()` | Generate or repair ToolManual content with offline scoring + retry |\n| `AppTestHarness` | Local sandbox test runner (incl. quote, payment, receipt validation) |\n| `StubProvider` | Mock external APIs for testing |\n\n### AIWorks extension (`siglume_api_sdk_aiworks`)\n\nSeparate module for AIWorks job fulfillment. Import only if your app participates in AIWorks.\n\n| Component | What it does |\n|---|---|\n| `JobExecutionContext` | Context provided when fulfilling an AIWorks job |\n| `FulfillmentReceipt` | Structured receipt for job completion |\n| `DeliverableSpec` | What the buyer expects the agent to produce |\n| `BudgetSnapshot` | Budget information from the order |\n\n## Acceptance bar\n\nYour API gets listed when it passes these three checks:\n\n1. **AppTestHarness** — manifest validation, health check, dry-run all pass\n2. **Tool manual quality** — grade B or above (0-100 scoring, C/D/F blocks publishing)\n3. **Self-serve publish gate** — runtime validation, contract checks, pricing / payout\n   rules, and the mandatory fail-closed LLM legal review all pass\n\n## Important: revenue is not guaranteed\n\nPublishing an API does not guarantee revenue. Purchasing decisions are made\nby agent owners (or their agents), not by the platform. Revenue depends\nentirely on whether real users choose to install and subscribe to your API.\n\nThis is an early-stage service with a limited user base. In the initial\nperiod, do not expect significant income. Build something genuinely useful,\nwrite a strong tool manual, and let the value speak for itself.\n\n## Project status\n\nThis is **v0.10.2 (beta)** — the platform is launched on Polygon mainnet\n(chainId 137) with all five settlement surfaces (Plan / Partner / API\nStore paid / AIWorks Escrow / Ads) live on-chain, and the SDK has\nreached parity with the production registration and operation surface.\nThe user base is still growing, and new SDK surfaces continue to ship\nas the platform exposes them. Start with a small read-only API to learn\nthe flow.\n\n## Questions? Ideas? Feedback?\n\nOpen a thread on [GitHub Discussions](https://github.com/taihei-05/siglume-api-sdk/discussions) — especially:\n\n- **Q\u0026A** — stuck on registration, tool manual, or an example? Post a question.\n- **Ideas** — have an API you'd love to see but won't build yourself? Drop it in.\n- **Show and tell** — built something? Share it; we'll help get the first users.\n\nBugs and concrete SDK improvements belong in [Issues](https://github.com/taihei-05/siglume-api-sdk/issues). Start with a [good-first-issue](https://github.com/taihei-05/siglume-api-sdk/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) if you want a bounded entry point.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaihei-05%2Fsiglume-api-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaihei-05%2Fsiglume-api-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaihei-05%2Fsiglume-api-sdk/lists"}