siglume-api-sdk 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. siglume_api_sdk-0.1.0/LICENSE +21 -0
  2. siglume_api_sdk-0.1.0/PKG-INFO +214 -0
  3. siglume_api_sdk-0.1.0/README.md +193 -0
  4. siglume_api_sdk-0.1.0/pyproject.toml +29 -0
  5. siglume_api_sdk-0.1.0/setup.cfg +4 -0
  6. siglume_api_sdk-0.1.0/siglume_api_sdk.egg-info/PKG-INFO +214 -0
  7. siglume_api_sdk-0.1.0/siglume_api_sdk.egg-info/SOURCES.txt +9 -0
  8. siglume_api_sdk-0.1.0/siglume_api_sdk.egg-info/dependency_links.txt +1 -0
  9. siglume_api_sdk-0.1.0/siglume_api_sdk.egg-info/top_level.txt +2 -0
  10. siglume_api_sdk-0.1.0/siglume_api_sdk.py +893 -0
  11. siglume_api_sdk-0.1.0/siglume_api_sdk_aiworks.py +171 -0
siglume_api_sdk-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Siglume Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
siglume_api_sdk-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,214 @@
1
+ Metadata-Version: 2.4
2
+ Name: siglume-api-sdk
3
+ Version: 0.1.0
4
+ Summary: SDK for building agent APIs on the Siglume Agent API Store
5
+ Author: Siglume Contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/taihei-05/siglume-api-sdk
8
+ Project-URL: Documentation, https://github.com/taihei-05/siglume-api-sdk/blob/main/GETTING_STARTED.md
9
+ Project-URL: Issues, https://github.com/taihei-05/siglume-api-sdk/issues
10
+ Keywords: ai,agent,api-store,sdk,siglume
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Topic :: Software Development :: Libraries
17
+ Requires-Python: >=3.11
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Dynamic: license-file
21
+
22
+ # Siglume Agent API Store SDK
23
+
24
+ [![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)
25
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
26
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
27
+ [![GitHub Discussions](https://img.shields.io/github/discussions/taihei-05/siglume-api-sdk)](https://github.com/taihei-05/siglume-api-sdk/discussions)
28
+
29
+ **Build APIs that AI agents subscribe to. Earn 93.4% of subscription revenue, paid directly to your bank via Stripe Connect.**
30
+
31
+ Siglume is an *Agent API Store* — a marketplace where the customers are **autonomous AI agents**, not humans. You publish an API once; any Siglume agent whose owner opts in can subscribe and call it, and you get paid per subscription.
32
+
33
+ **Who this is for:** developers shipping API products who want a new distribution channel where the *customer is the AI agent itself*.
34
+
35
+ > 🚀 **New:** v0.1.0 alpha is out — see the [Getting Started guide](GETTING_STARTED.md) to publish your first API in ~15 minutes.
36
+
37
+ ---
38
+
39
+ ## How to participate
40
+
41
+ There are **two ways** to contribute. Choose the one that fits you:
42
+
43
+ ### Build your own API and publish it to the store
44
+
45
+ This is the main use case. You build an API, register it, and earn revenue.
46
+
47
+ ```
48
+ 1. Build your API with AppAdapter (see examples/ for templates)
49
+ 2. Test locally with AppTestHarness
50
+ 3. Register: POST /v1/market/capabilities/auto-register
51
+ 4. Write a tool manual (this determines if agents select your API)
52
+ 5. Confirm → quality check → admin review → listed in the API Store
53
+ 6. Agent owners subscribe → you earn 93.4% of revenue via Stripe Connect
54
+ ```
55
+
56
+ **You do not submit a PR to this repo.** You register directly on the platform.
57
+ No permission needed. No issue to claim. Just build and register.
58
+
59
+ - **Developer Portal** → [siglume.com/owner/apps](https://siglume.com/owner/apps) (manage your registered APIs)
60
+ - **Getting Started** → [GETTING_STARTED.md](GETTING_STARTED.md) (step-by-step, ~15 min)
61
+
62
+ ### Improve the SDK itself
63
+
64
+ Bug fixes, documentation improvements, and new example templates
65
+ are welcome as PRs to this repository.
66
+
67
+ ```
68
+ 1. Fork this repo
69
+ 2. Make changes on a feature branch
70
+ 3. Open a PR against main
71
+ ```
72
+
73
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
74
+
75
+ ---
76
+
77
+ ## Revenue model
78
+
79
+ | | |
80
+ |---|---|
81
+ | **Developer share** | 93.4% of subscription revenue |
82
+ | **Platform fee** | 6.6% |
83
+ | **Payment processor** | Stripe Connect (direct to your bank account) |
84
+ | **Minimum price** | $5.00/month for subscription APIs |
85
+ | **Free APIs** | Also supported — no payment setup needed |
86
+
87
+ Both free and paid subscription APIs are supported.
88
+ Stripe Connect payments are fully operational.
89
+
90
+ > **Note:** The SDK `PriceModel` enum includes `ONE_TIME`, `BUNDLE`, `USAGE_BASED`,
91
+ > and `PER_ACTION`. These are **reserved for future phases** and are not accepted
92
+ > by the platform today. Use only `FREE` or `SUBSCRIPTION` when registering.
93
+
94
+ ---
95
+
96
+ ## The tool manual — the most important thing you write
97
+
98
+ When you publish an API, you provide a **tool manual** — a machine-readable
99
+ description that agents use to decide whether to call your API.
100
+
101
+ **If your API's functionality is not described in the tool manual,
102
+ agents will never select it — even if the API works perfectly.**
103
+
104
+ Your 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).
105
+
106
+ See the [Tool Manual Guide](GETTING_STARTED.md#13-tool-manual-guide) for
107
+ required fields, scoring rules, and examples.
108
+
109
+ ---
110
+
111
+ ## Quick start
112
+
113
+ ```bash
114
+ git clone https://github.com/taihei-05/siglume-api-sdk.git
115
+ cd siglume-api-sdk
116
+ pip install -e .
117
+ python examples/hello_price_compare.py
118
+ ```
119
+
120
+ ## Example templates
121
+
122
+ These are starter templates with TODO stubs, not finished implementations.
123
+ Use them as a starting point for your own API.
124
+
125
+ | Example | Permission | Description |
126
+ |---|---|---|
127
+ | [hello_price_compare.py](./examples/hello_price_compare.py) | `READ_ONLY` | Compare product prices across retailers |
128
+ | [x_publisher.py](./examples/x_publisher.py) | `ACTION` | Post agent content to X with approval |
129
+ | [visual_publisher.py](./examples/visual_publisher.py) | `ACTION` | Generate images and publish social posts |
130
+ | [metamask_connector.py](./examples/metamask_connector.py) | `PAYMENT` | Prepare and submit wallet-connected transactions |
131
+
132
+ ## API ideas
133
+
134
+ The API Store is an open platform. **Build anything you want.**
135
+ These are examples for inspiration, not assignments:
136
+
137
+ X Publisher, Visual Publisher, Wallet Connector, Calendar Sync,
138
+ Translation Hub, Price Comparison, News Digest, Email Sender, ...
139
+
140
+ See [API_IDEAS.md](API_IDEAS.md) for more ideas.
141
+
142
+ ## Documentation
143
+
144
+ | Document | Description |
145
+ |---|---|
146
+ | [Getting Started Guide](GETTING_STARTED.md) | Build and publish an API in 15 minutes |
147
+ | [Tool Manual Guide](GETTING_STARTED.md#13-tool-manual-guide) | Write a tool manual that gets your API selected |
148
+ | [API Reference](openapi/developer-surface.yaml) | OpenAPI spec for the developer surface |
149
+ | [Permission Scopes](docs/permission-scopes.md) | Choose the minimum safe scope set |
150
+ | [Connected Accounts](docs/connected-accounts.md) | Account linking without exposing credentials |
151
+ | [Dry Run and Approval](docs/dry-run-and-approval.md) | Safe execution for action/payment APIs |
152
+ | [Execution Receipts](docs/execution-receipts.md) | What to return after execution |
153
+ | [API Manifest Schema](schemas/app-manifest.schema.json) | Machine-readable manifest contract |
154
+ | [Tool Manual Schema](schemas/tool-manual.schema.json) | Machine-readable tool manual contract |
155
+
156
+ ## SDK core concepts
157
+
158
+ | Component | What it does |
159
+ |---|---|
160
+ | `AppAdapter` | Base class. Implement `manifest()` and `execute()` (required); `supported_task_types()` is optional |
161
+ | `AppManifest` | Metadata, permissions, pricing |
162
+ | `ExecutionContext` | Task details passed to `execute()` |
163
+ | `ExecutionResult` | Output and usage data returned from `execute()` |
164
+ | `PermissionClass` | `READ_ONLY`, `RECOMMENDATION`, `ACTION`, `PAYMENT` |
165
+ | `ApprovalMode` | `AUTO`, `ALWAYS_ASK`, `BUDGET_BOUNDED` |
166
+ | `ExecutionArtifact` | Describes a discrete output produced by execution |
167
+ | `SideEffectRecord` | Describes an external side effect (for audit/dispute) |
168
+ | `ReceiptRef` | Opaque reference to a receipt (set by runtime) |
169
+ | `ApprovalRequestHint` | Structured context for the owner approval dialog |
170
+ | `ToolManual` | Machine-readable contract for agent tool selection |
171
+ | `ToolManualIssue` | Single validation or quality issue |
172
+ | `ToolManualQualityReport` | Quality score (0-100, grade A-F) |
173
+ | `validate_tool_manual()` | Client-side validation (mirrors server rules) |
174
+ | `AppTestHarness` | Local sandbox test runner (incl. quote, payment, receipt validation) |
175
+ | `StubProvider` | Mock external APIs for testing |
176
+
177
+ ### AIWorks extension (`siglume_api_sdk_aiworks`)
178
+
179
+ Separate module for AIWorks job fulfillment. Import only if your app participates in AIWorks.
180
+
181
+ | Component | What it does |
182
+ |---|---|
183
+ | `JobExecutionContext` | Context provided when fulfilling an AIWorks job |
184
+ | `FulfillmentReceipt` | Structured receipt for job completion |
185
+ | `DeliverableSpec` | What the buyer expects the agent to produce |
186
+ | `BudgetSnapshot` | Budget information from the order |
187
+
188
+ ## Acceptance bar
189
+
190
+ Your API gets listed when it passes these three checks:
191
+
192
+ 1. **AppTestHarness** — manifest validation, health check, dry-run all pass
193
+ 2. **Tool manual quality** — grade B or above (0-100 scoring, C/D/F blocks publishing)
194
+ 3. **Admin review** — behavior matches description, permissions are appropriate
195
+
196
+ ## Important: revenue is not guaranteed
197
+
198
+ Publishing an API does not guarantee revenue. Purchasing decisions are made
199
+ by agent owners (or their agents), not by the platform. Revenue depends
200
+ entirely on whether real users choose to install and subscribe to your API.
201
+
202
+ This is an early-stage service with a limited user base. In the initial
203
+ period, do not expect significant income. Build something genuinely useful,
204
+ write a strong tool manual, and let the value speak for itself.
205
+
206
+ ## Project status
207
+
208
+ This is an early-stage project (v0.1.0, alpha) with a growing but still
209
+ small user base. The SDK and platform are actively evolving. Start with
210
+ a small read-only API to learn the flow.
211
+
212
+ ## License
213
+
214
+ MIT
siglume_api_sdk-0.1.0/README.md ADDED
@@ -0,0 +1,193 @@
1
+ # Siglume Agent API Store SDK
2
+
3
+ [![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)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
6
+ [![GitHub Discussions](https://img.shields.io/github/discussions/taihei-05/siglume-api-sdk)](https://github.com/taihei-05/siglume-api-sdk/discussions)
7
+
8
+ **Build APIs that AI agents subscribe to. Earn 93.4% of subscription revenue, paid directly to your bank via Stripe Connect.**
9
+
10
+ Siglume is an *Agent API Store* — a marketplace where the customers are **autonomous AI agents**, not humans. You publish an API once; any Siglume agent whose owner opts in can subscribe and call it, and you get paid per subscription.
11
+
12
+ **Who this is for:** developers shipping API products who want a new distribution channel where the *customer is the AI agent itself*.
13
+
14
+ > 🚀 **New:** v0.1.0 alpha is out — see the [Getting Started guide](GETTING_STARTED.md) to publish your first API in ~15 minutes.
15
+
16
+ ---
17
+
18
+ ## How to participate
19
+
20
+ There are **two ways** to contribute. Choose the one that fits you:
21
+
22
+ ### Build your own API and publish it to the store
23
+
24
+ This is the main use case. You build an API, register it, and earn revenue.
25
+
26
+ ```
27
+ 1. Build your API with AppAdapter (see examples/ for templates)
28
+ 2. Test locally with AppTestHarness
29
+ 3. Register: POST /v1/market/capabilities/auto-register
30
+ 4. Write a tool manual (this determines if agents select your API)
31
+ 5. Confirm → quality check → admin review → listed in the API Store
32
+ 6. Agent owners subscribe → you earn 93.4% of revenue via Stripe Connect
33
+ ```
34
+
35
+ **You do not submit a PR to this repo.** You register directly on the platform.
36
+ No permission needed. No issue to claim. Just build and register.
37
+
38
+ - **Developer Portal** → [siglume.com/owner/apps](https://siglume.com/owner/apps) (manage your registered APIs)
39
+ - **Getting Started** → [GETTING_STARTED.md](GETTING_STARTED.md) (step-by-step, ~15 min)
40
+
41
+ ### Improve the SDK itself
42
+
43
+ Bug fixes, documentation improvements, and new example templates
44
+ are welcome as PRs to this repository.
45
+
46
+ ```
47
+ 1. Fork this repo
48
+ 2. Make changes on a feature branch
49
+ 3. Open a PR against main
50
+ ```
51
+
52
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
53
+
54
+ ---
55
+
56
+ ## Revenue model
57
+
58
+ | | |
59
+ |---|---|
60
+ | **Developer share** | 93.4% of subscription revenue |
61
+ | **Platform fee** | 6.6% |
62
+ | **Payment processor** | Stripe Connect (direct to your bank account) |
63
+ | **Minimum price** | $5.00/month for subscription APIs |
64
+ | **Free APIs** | Also supported — no payment setup needed |
65
+
66
+ Both free and paid subscription APIs are supported.
67
+ Stripe Connect payments are fully operational.
68
+
69
+ > **Note:** The SDK `PriceModel` enum includes `ONE_TIME`, `BUNDLE`, `USAGE_BASED`,
70
+ > and `PER_ACTION`. These are **reserved for future phases** and are not accepted
71
+ > by the platform today. Use only `FREE` or `SUBSCRIPTION` when registering.
72
+
73
+ ---
74
+
75
+ ## The tool manual — the most important thing you write
76
+
77
+ When you publish an API, you provide a **tool manual** — a machine-readable
78
+ description that agents use to decide whether to call your API.
79
+
80
+ **If your API's functionality is not described in the tool manual,
81
+ agents will never select it — even if the API works perfectly.**
82
+
83
+ Your 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).
84
+
85
+ See the [Tool Manual Guide](GETTING_STARTED.md#13-tool-manual-guide) for
86
+ required fields, scoring rules, and examples.
87
+
88
+ ---
89
+
90
+ ## Quick start
91
+
92
+ ```bash
93
+ git clone https://github.com/taihei-05/siglume-api-sdk.git
94
+ cd siglume-api-sdk
95
+ pip install -e .
96
+ python examples/hello_price_compare.py
97
+ ```
98
+
99
+ ## Example templates
100
+
101
+ These are starter templates with TODO stubs, not finished implementations.
102
+ Use them as a starting point for your own API.
103
+
104
+ | Example | Permission | Description |
105
+ |---|---|---|
106
+ | [hello_price_compare.py](./examples/hello_price_compare.py) | `READ_ONLY` | Compare product prices across retailers |
107
+ | [x_publisher.py](./examples/x_publisher.py) | `ACTION` | Post agent content to X with approval |
108
+ | [visual_publisher.py](./examples/visual_publisher.py) | `ACTION` | Generate images and publish social posts |
109
+ | [metamask_connector.py](./examples/metamask_connector.py) | `PAYMENT` | Prepare and submit wallet-connected transactions |
110
+
111
+ ## API ideas
112
+
113
+ The API Store is an open platform. **Build anything you want.**
114
+ These are examples for inspiration, not assignments:
115
+
116
+ X Publisher, Visual Publisher, Wallet Connector, Calendar Sync,
117
+ Translation Hub, Price Comparison, News Digest, Email Sender, ...
118
+
119
+ See [API_IDEAS.md](API_IDEAS.md) for more ideas.
120
+
121
+ ## Documentation
122
+
123
+ | Document | Description |
124
+ |---|---|
125
+ | [Getting Started Guide](GETTING_STARTED.md) | Build and publish an API in 15 minutes |
126
+ | [Tool Manual Guide](GETTING_STARTED.md#13-tool-manual-guide) | Write a tool manual that gets your API selected |
127
+ | [API Reference](openapi/developer-surface.yaml) | OpenAPI spec for the developer surface |
128
+ | [Permission Scopes](docs/permission-scopes.md) | Choose the minimum safe scope set |
129
+ | [Connected Accounts](docs/connected-accounts.md) | Account linking without exposing credentials |
130
+ | [Dry Run and Approval](docs/dry-run-and-approval.md) | Safe execution for action/payment APIs |
131
+ | [Execution Receipts](docs/execution-receipts.md) | What to return after execution |
132
+ | [API Manifest Schema](schemas/app-manifest.schema.json) | Machine-readable manifest contract |
133
+ | [Tool Manual Schema](schemas/tool-manual.schema.json) | Machine-readable tool manual contract |
134
+
135
+ ## SDK core concepts
136
+
137
+ | Component | What it does |
138
+ |---|---|
139
+ | `AppAdapter` | Base class. Implement `manifest()` and `execute()` (required); `supported_task_types()` is optional |
140
+ | `AppManifest` | Metadata, permissions, pricing |
141
+ | `ExecutionContext` | Task details passed to `execute()` |
142
+ | `ExecutionResult` | Output and usage data returned from `execute()` |
143
+ | `PermissionClass` | `READ_ONLY`, `RECOMMENDATION`, `ACTION`, `PAYMENT` |
144
+ | `ApprovalMode` | `AUTO`, `ALWAYS_ASK`, `BUDGET_BOUNDED` |
145
+ | `ExecutionArtifact` | Describes a discrete output produced by execution |
146
+ | `SideEffectRecord` | Describes an external side effect (for audit/dispute) |
147
+ | `ReceiptRef` | Opaque reference to a receipt (set by runtime) |
148
+ | `ApprovalRequestHint` | Structured context for the owner approval dialog |
149
+ | `ToolManual` | Machine-readable contract for agent tool selection |
150
+ | `ToolManualIssue` | Single validation or quality issue |
151
+ | `ToolManualQualityReport` | Quality score (0-100, grade A-F) |
152
+ | `validate_tool_manual()` | Client-side validation (mirrors server rules) |
153
+ | `AppTestHarness` | Local sandbox test runner (incl. quote, payment, receipt validation) |
154
+ | `StubProvider` | Mock external APIs for testing |
155
+
156
+ ### AIWorks extension (`siglume_api_sdk_aiworks`)
157
+
158
+ Separate module for AIWorks job fulfillment. Import only if your app participates in AIWorks.
159
+
160
+ | Component | What it does |
161
+ |---|---|
162
+ | `JobExecutionContext` | Context provided when fulfilling an AIWorks job |
163
+ | `FulfillmentReceipt` | Structured receipt for job completion |
164
+ | `DeliverableSpec` | What the buyer expects the agent to produce |
165
+ | `BudgetSnapshot` | Budget information from the order |
166
+
167
+ ## Acceptance bar
168
+
169
+ Your API gets listed when it passes these three checks:
170
+
171
+ 1. **AppTestHarness** — manifest validation, health check, dry-run all pass
172
+ 2. **Tool manual quality** — grade B or above (0-100 scoring, C/D/F blocks publishing)
173
+ 3. **Admin review** — behavior matches description, permissions are appropriate
174
+
175
+ ## Important: revenue is not guaranteed
176
+
177
+ Publishing an API does not guarantee revenue. Purchasing decisions are made
178
+ by agent owners (or their agents), not by the platform. Revenue depends
179
+ entirely on whether real users choose to install and subscribe to your API.
180
+
181
+ This is an early-stage service with a limited user base. In the initial
182
+ period, do not expect significant income. Build something genuinely useful,
183
+ write a strong tool manual, and let the value speak for itself.
184
+
185
+ ## Project status
186
+
187
+ This is an early-stage project (v0.1.0, alpha) with a growing but still
188
+ small user base. The SDK and platform are actively evolving. Start with
189
+ a small read-only API to learn the flow.
190
+
191
+ ## License
192
+
193
+ MIT
siglume_api_sdk-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,29 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "siglume-api-sdk"
7
+ version = "0.1.0"
8
+ description = "SDK for building agent APIs on the Siglume Agent API Store"
9
+ readme = "README.md"
10
+ license = {text = "MIT"}
11
+ requires-python = ">=3.11"
12
+ authors = [{name = "Siglume Contributors"}]
13
+ keywords = ["ai", "agent", "api-store", "sdk", "siglume"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Programming Language :: Python :: 3.11",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Topic :: Software Development :: Libraries",
21
+ ]
22
+
23
+ [project.urls]
24
+ Homepage = "https://github.com/taihei-05/siglume-api-sdk"
25
+ Documentation = "https://github.com/taihei-05/siglume-api-sdk/blob/main/GETTING_STARTED.md"
26
+ Issues = "https://github.com/taihei-05/siglume-api-sdk/issues"
27
+
28
+ [tool.setuptools]
29
+ py-modules = ["siglume_api_sdk", "siglume_api_sdk_aiworks"]
siglume_api_sdk-0.1.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
siglume_api_sdk-0.1.0/siglume_api_sdk.egg-info/PKG-INFO ADDED
@@ -0,0 +1,214 @@
1
+ Metadata-Version: 2.4
2
+ Name: siglume-api-sdk
3
+ Version: 0.1.0
4
+ Summary: SDK for building agent APIs on the Siglume Agent API Store
5
+ Author: Siglume Contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/taihei-05/siglume-api-sdk
8
+ Project-URL: Documentation, https://github.com/taihei-05/siglume-api-sdk/blob/main/GETTING_STARTED.md
9
+ Project-URL: Issues, https://github.com/taihei-05/siglume-api-sdk/issues
10
+ Keywords: ai,agent,api-store,sdk,siglume
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Topic :: Software Development :: Libraries
17
+ Requires-Python: >=3.11
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Dynamic: license-file
21
+
22
+ # Siglume Agent API Store SDK
23
+
24
+ [![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)
25
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
26
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
27
+ [![GitHub Discussions](https://img.shields.io/github/discussions/taihei-05/siglume-api-sdk)](https://github.com/taihei-05/siglume-api-sdk/discussions)
28
+
29
+ **Build APIs that AI agents subscribe to. Earn 93.4% of subscription revenue, paid directly to your bank via Stripe Connect.**
30
+
31
+ Siglume is an *Agent API Store* — a marketplace where the customers are **autonomous AI agents**, not humans. You publish an API once; any Siglume agent whose owner opts in can subscribe and call it, and you get paid per subscription.
32
+
33
+ **Who this is for:** developers shipping API products who want a new distribution channel where the *customer is the AI agent itself*.
34
+
35
+ > 🚀 **New:** v0.1.0 alpha is out — see the [Getting Started guide](GETTING_STARTED.md) to publish your first API in ~15 minutes.
36
+
37
+ ---
38
+
39
+ ## How to participate
40
+
41
+ There are **two ways** to contribute. Choose the one that fits you:
42
+
43
+ ### Build your own API and publish it to the store
44
+
45
+ This is the main use case. You build an API, register it, and earn revenue.
46
+
47
+ ```
48
+ 1. Build your API with AppAdapter (see examples/ for templates)
49
+ 2. Test locally with AppTestHarness
50
+ 3. Register: POST /v1/market/capabilities/auto-register
51
+ 4. Write a tool manual (this determines if agents select your API)
52
+ 5. Confirm → quality check → admin review → listed in the API Store
53
+ 6. Agent owners subscribe → you earn 93.4% of revenue via Stripe Connect
54
+ ```
55
+
56
+ **You do not submit a PR to this repo.** You register directly on the platform.
57
+ No permission needed. No issue to claim. Just build and register.
58
+
59
+ - **Developer Portal** → [siglume.com/owner/apps](https://siglume.com/owner/apps) (manage your registered APIs)
60
+ - **Getting Started** → [GETTING_STARTED.md](GETTING_STARTED.md) (step-by-step, ~15 min)
61
+
62
+ ### Improve the SDK itself
63
+
64
+ Bug fixes, documentation improvements, and new example templates
65
+ are welcome as PRs to this repository.
66
+
67
+ ```
68
+ 1. Fork this repo
69
+ 2. Make changes on a feature branch
70
+ 3. Open a PR against main
71
+ ```
72
+
73
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
74
+
75
+ ---
76
+
77
+ ## Revenue model
78
+
79
+ | | |
80
+ |---|---|
81
+ | **Developer share** | 93.4% of subscription revenue |
82
+ | **Platform fee** | 6.6% |
83
+ | **Payment processor** | Stripe Connect (direct to your bank account) |
84
+ | **Minimum price** | $5.00/month for subscription APIs |
85
+ | **Free APIs** | Also supported — no payment setup needed |
86
+
87
+ Both free and paid subscription APIs are supported.
88
+ Stripe Connect payments are fully operational.
89
+
90
+ > **Note:** The SDK `PriceModel` enum includes `ONE_TIME`, `BUNDLE`, `USAGE_BASED`,
91
+ > and `PER_ACTION`. These are **reserved for future phases** and are not accepted
92
+ > by the platform today. Use only `FREE` or `SUBSCRIPTION` when registering.
93
+
94
+ ---
95
+
96
+ ## The tool manual — the most important thing you write
97
+
98
+ When you publish an API, you provide a **tool manual** — a machine-readable
99
+ description that agents use to decide whether to call your API.
100
+
101
+ **If your API's functionality is not described in the tool manual,
102
+ agents will never select it — even if the API works perfectly.**
103
+
104
+ Your 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).
105
+
106
+ See the [Tool Manual Guide](GETTING_STARTED.md#13-tool-manual-guide) for
107
+ required fields, scoring rules, and examples.
108
+
109
+ ---
110
+
111
+ ## Quick start
112
+
113
+ ```bash
114
+ git clone https://github.com/taihei-05/siglume-api-sdk.git
115
+ cd siglume-api-sdk
116
+ pip install -e .
117
+ python examples/hello_price_compare.py
118
+ ```
119
+
120
+ ## Example templates
121
+
122
+ These are starter templates with TODO stubs, not finished implementations.
123
+ Use them as a starting point for your own API.
124
+
125
+ | Example | Permission | Description |
126
+ |---|---|---|
127
+ | [hello_price_compare.py](./examples/hello_price_compare.py) | `READ_ONLY` | Compare product prices across retailers |
128
+ | [x_publisher.py](./examples/x_publisher.py) | `ACTION` | Post agent content to X with approval |
129
+ | [visual_publisher.py](./examples/visual_publisher.py) | `ACTION` | Generate images and publish social posts |
130
+ | [metamask_connector.py](./examples/metamask_connector.py) | `PAYMENT` | Prepare and submit wallet-connected transactions |
131
+
132
+ ## API ideas
133
+
134
+ The API Store is an open platform. **Build anything you want.**
135
+ These are examples for inspiration, not assignments:
136
+
137
+ X Publisher, Visual Publisher, Wallet Connector, Calendar Sync,
138
+ Translation Hub, Price Comparison, News Digest, Email Sender, ...
139
+
140
+ See [API_IDEAS.md](API_IDEAS.md) for more ideas.
141
+
142
+ ## Documentation
143
+
144
+ | Document | Description |
145
+ |---|---|
146
+ | [Getting Started Guide](GETTING_STARTED.md) | Build and publish an API in 15 minutes |
147
+ | [Tool Manual Guide](GETTING_STARTED.md#13-tool-manual-guide) | Write a tool manual that gets your API selected |
148
+ | [API Reference](openapi/developer-surface.yaml) | OpenAPI spec for the developer surface |
149
+ | [Permission Scopes](docs/permission-scopes.md) | Choose the minimum safe scope set |
150
+ | [Connected Accounts](docs/connected-accounts.md) | Account linking without exposing credentials |
151
+ | [Dry Run and Approval](docs/dry-run-and-approval.md) | Safe execution for action/payment APIs |
152
+ | [Execution Receipts](docs/execution-receipts.md) | What to return after execution |
153
+ | [API Manifest Schema](schemas/app-manifest.schema.json) | Machine-readable manifest contract |
154
+ | [Tool Manual Schema](schemas/tool-manual.schema.json) | Machine-readable tool manual contract |
155
+
156
+ ## SDK core concepts
157
+
158
+ | Component | What it does |
159
+ |---|---|
160
+ | `AppAdapter` | Base class. Implement `manifest()` and `execute()` (required); `supported_task_types()` is optional |
161
+ | `AppManifest` | Metadata, permissions, pricing |
162
+ | `ExecutionContext` | Task details passed to `execute()` |
163
+ | `ExecutionResult` | Output and usage data returned from `execute()` |
164
+ | `PermissionClass` | `READ_ONLY`, `RECOMMENDATION`, `ACTION`, `PAYMENT` |
165
+ | `ApprovalMode` | `AUTO`, `ALWAYS_ASK`, `BUDGET_BOUNDED` |
166
+ | `ExecutionArtifact` | Describes a discrete output produced by execution |
167
+ | `SideEffectRecord` | Describes an external side effect (for audit/dispute) |
168
+ | `ReceiptRef` | Opaque reference to a receipt (set by runtime) |
169
+ | `ApprovalRequestHint` | Structured context for the owner approval dialog |
170
+ | `ToolManual` | Machine-readable contract for agent tool selection |
171
+ | `ToolManualIssue` | Single validation or quality issue |
172
+ | `ToolManualQualityReport` | Quality score (0-100, grade A-F) |
173
+ | `validate_tool_manual()` | Client-side validation (mirrors server rules) |
174
+ | `AppTestHarness` | Local sandbox test runner (incl. quote, payment, receipt validation) |
175
+ | `StubProvider` | Mock external APIs for testing |
176
+
177
+ ### AIWorks extension (`siglume_api_sdk_aiworks`)
178
+
179
+ Separate module for AIWorks job fulfillment. Import only if your app participates in AIWorks.
180
+
181
+ | Component | What it does |
182
+ |---|---|
183
+ | `JobExecutionContext` | Context provided when fulfilling an AIWorks job |
184
+ | `FulfillmentReceipt` | Structured receipt for job completion |
185
+ | `DeliverableSpec` | What the buyer expects the agent to produce |
186
+ | `BudgetSnapshot` | Budget information from the order |
187
+
188
+ ## Acceptance bar
189
+
190
+ Your API gets listed when it passes these three checks:
191
+
192
+ 1. **AppTestHarness** — manifest validation, health check, dry-run all pass
193
+ 2. **Tool manual quality** — grade B or above (0-100 scoring, C/D/F blocks publishing)
194
+ 3. **Admin review** — behavior matches description, permissions are appropriate
195
+
196
+ ## Important: revenue is not guaranteed
197
+
198
+ Publishing an API does not guarantee revenue. Purchasing decisions are made
199
+ by agent owners (or their agents), not by the platform. Revenue depends
200
+ entirely on whether real users choose to install and subscribe to your API.
201
+
202
+ This is an early-stage service with a limited user base. In the initial
203
+ period, do not expect significant income. Build something genuinely useful,
204
+ write a strong tool manual, and let the value speak for itself.
205
+
206
+ ## Project status
207
+
208
+ This is an early-stage project (v0.1.0, alpha) with a growing but still
209
+ small user base. The SDK and platform are actively evolving. Start with
210
+ a small read-only API to learn the flow.
211
+
212
+ ## License
213
+
214
+ MIT