purrkey 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.
@@ -0,0 +1,34 @@
1
+ name: ci
2
+
3
+ on:
4
+ pull_request:
5
+ push:
6
+ branches: [main]
7
+ schedule:
8
+ # Weekly: fail if the live API contract changed since the last regeneration.
9
+ - cron: "0 3 * * 1"
10
+
11
+ jobs:
12
+ test:
13
+ runs-on: ubuntu-latest
14
+ strategy:
15
+ matrix:
16
+ python: ["3.10", "3.11", "3.12", "3.13"]
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+ - uses: astral-sh/setup-uv@v5
20
+ - run: uv sync --python ${{ matrix.python }}
21
+ - run: uv run pytest -q
22
+ - run: uv run mypy
23
+
24
+ contract:
25
+ runs-on: ubuntu-latest
26
+ steps:
27
+ - uses: actions/checkout@v4
28
+ - uses: astral-sh/setup-uv@v5
29
+ - run: uv sync --python 3.12
30
+ - run: uv run python scripts/generate.py --check
31
+ - if: github.event_name == 'schedule'
32
+ run: |
33
+ uv run python scripts/generate.py --fetch
34
+ git diff --exit-code openapi/ src/purrkey/types.py
@@ -0,0 +1,22 @@
1
+ name: release
2
+
3
+ # Publishes to PyPI when a GitHub release is published. Uses PyPI trusted
4
+ # publishing (OIDC), so the repository holds no PyPI token.
5
+ on:
6
+ release:
7
+ types: [published]
8
+
9
+ jobs:
10
+ publish:
11
+ runs-on: ubuntu-latest
12
+ environment: pypi
13
+ permissions:
14
+ contents: read
15
+ id-token: write
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ - uses: astral-sh/setup-uv@v5
19
+ - name: Check the tag matches pyproject.toml
20
+ run: test "v$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)" = "${{ github.event.release.tag_name }}"
21
+ - run: uv build
22
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ .pytest_cache/
6
+ .DS_Store
@@ -0,0 +1 @@
1
+ 3.12
purrkey-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Purrkey
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.
purrkey-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,149 @@
1
+ Metadata-Version: 2.5
2
+ Name: purrkey
3
+ Version: 0.1.0
4
+ Summary: Official Python SDK for Purrkey: find, price and run 1,100+ pay-per-call data tools for AI agents.
5
+ Project-URL: Homepage, https://purrkey.app
6
+ Project-URL: Documentation, https://purrkey.app/docs
7
+ Project-URL: Repository, https://github.com/purrkey/purrkey-python
8
+ Project-URL: Issues, https://github.com/purrkey/purrkey-python/issues
9
+ Author-email: Purrkey <support@purrkey.app>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: ai-agents,api,mcp,purrkey,scraping,sdk,social-media
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Typing :: Typed
17
+ Requires-Python: >=3.10
18
+ Requires-Dist: httpx<1,>=0.25
19
+ Requires-Dist: typing-extensions>=4.7
20
+ Description-Content-Type: text/markdown
21
+
22
+ # Purrkey Python SDK
23
+
24
+ [![PyPI](https://img.shields.io/pypi/v/purrkey)](https://pypi.org/project/purrkey/)
25
+
26
+ The official Python client for [Purrkey](https://purrkey.app/?utm_source=github&utm_medium=readme&utm_campaign=geo_launch), a pay-per-call tool marketplace for AI agents. One API key reaches 1,100+ data tools: social media from TikTok, Instagram, YouTube, Xiaohongshu and Douyin, Amazon and eBay listings, Google Maps reviews, SEO data, and web search and scraping. Every tool has a published price, and each call is paid from one balance.
27
+
28
+ Python 3.10+. Sync and async clients. Fully typed.
29
+
30
+ ## Install
31
+
32
+ ```sh
33
+ pip install purrkey
34
+ ```
35
+
36
+ ## Quick start
37
+
38
+ Create a key at [purrkey.app/keys](https://purrkey.app/keys?utm_source=github&utm_medium=readme&utm_campaign=geo_launch) and set it as `PURRKEY_API_KEY`. New accounts get $1 in free credit.
39
+
40
+ ```python
41
+ from purrkey import Purrkey
42
+
43
+ with Purrkey() as purrkey: # reads PURRKEY_API_KEY
44
+ # 1. Find a tool (free)
45
+ candidates = purrkey.discover("google maps reviews")["candidates"]
46
+
47
+ # 2. Read its schema and price (free)
48
+ tool = purrkey.inspect("tikhub.tiktok.app.v3.fetch_video_search_result")
49
+ print(tool["tool"]["price"]) # {'unit': 'call', 'unitPriceMicros': '1000', ...}
50
+
51
+ # 3. Run it and wait for the result
52
+ run = purrkey.run(
53
+ "tikhub.tiktok.app.v3.fetch_video_search_result",
54
+ {"query": {"keyword": "matcha latte", "count": 10}},
55
+ )
56
+ print(run["status"]) # SUCCEEDED
57
+ print(run["billing"]["chargedMicros"]) # 1000 = $0.001
58
+ print(run["result"]["output"])
59
+ ```
60
+
61
+ Async:
62
+
63
+ ```python
64
+ import asyncio
65
+ from purrkey import AsyncPurrkey
66
+
67
+ async def main() -> None:
68
+ async with AsyncPurrkey() as purrkey:
69
+ run = await purrkey.run("anyapi.web.scrape", {"url": "https://purrkey.app/about"})
70
+ print(run["result"]["output"]["data"]["markdown"])
71
+
72
+ asyncio.run(main())
73
+ ```
74
+
75
+ Browse the [tool catalog](https://purrkey.app/tools?utm_source=github&utm_medium=readme&utm_campaign=geo_launch) to see what is available.
76
+
77
+ ## Paying safely
78
+
79
+ `run()` handles the rules that keep a task from being charged twice:
80
+
81
+ - **Spending cap.** Each Run carries `maxChargeMicros`, the most it may cost (1 USD = 1,000,000 micros). For tools priced per call, the SDK uses the inspected price. When the price depends on the input (per result, per URL, per credit), pass `max_charge_micros` yourself; otherwise `run()` raises `max_charge_required` before anything is charged.
82
+ - **Idempotency.** Every Run has an `idempotencyKey`. If a response is lost, the SDK sends the same request again with the same key, and Purrkey returns the original Run instead of running and charging again. Pass your own key to make retries safe across processes:
83
+
84
+ ```python
85
+ purrkey.run(tool_id, payload, idempotency_key=f"report-{report_id}")
86
+ ```
87
+
88
+ A new key means a new, separately charged task.
89
+ - **Unknown outcomes.** `UNKNOWN` means the provider's outcome needs reconciliation. The SDK stops waiting and returns the Run. Check it later with `get_run(run_id)`; don't submit the task again.
90
+ - **Billing is separate from status.** Read `run["billing"]` (`status`, `heldMicros`, `chargedMicros`). A failed Run can still be charged for verified work when the tool's pricing allows it.
91
+
92
+ Account-wide daily and per-run caps can be set at [purrkey.app/budget](https://purrkey.app/budget?utm_source=github&utm_medium=readme&utm_campaign=geo_launch).
93
+
94
+ ## API
95
+
96
+ | Method | What it does | Cost |
97
+ | --- | --- | --- |
98
+ | `discover(query, *, limit, provider_id, category)` | Find tool candidates for one task | Free |
99
+ | `inspect(tool_id, *, tool_revision)` | Exact input/output schema, price and delivery rules | Free |
100
+ | `run(tool_id, input, *, max_charge_micros, idempotency_key, wait=True, timeout=120)` | Inspect, submit and (by default) wait for a final status | Tool price |
101
+ | `submit_run(request)` | Submit a prepared `RunRequest` | Tool price |
102
+ | `get_run(run_id)` | Read a Run and its result | Free |
103
+ | `wait_for_run(run_id, *, timeout)` | Poll until a final status; returns the Run as it is on timeout | Free |
104
+ | `cancel_run(run_id)` | Request cancellation | — |
105
+ | `list_runs(**filters)` | List your Runs (`status`, `toolId`, `cursor`, `limit`, …) | Free |
106
+ | `balance()` | Balance and held amounts | Free |
107
+ | `list_tools()`, `list_providers()`, `catalog()`, `platform_endpoints(platform)`, `rankings()` | Browse the catalog | Free |
108
+
109
+ `AsyncPurrkey` has the same methods as coroutines. Client options: `api_key` (default `PURRKEY_API_KEY`), `base_url`, `timeout`, `max_retries` (default 2; network errors, 429 and 5xx), `http_client`.
110
+
111
+ Responses are plain dicts typed with `TypedDict`s from `purrkey.types`, generated from the [public OpenAPI contract](https://purrkey.app/docs/openapi.yaml).
112
+
113
+ ## Errors
114
+
115
+ API errors and client-side checks raise `PurrkeyError`:
116
+
117
+ ```python
118
+ from purrkey import PurrkeyError
119
+
120
+ try:
121
+ purrkey.run(tool_id, payload)
122
+ except PurrkeyError as error:
123
+ print(error.status, error.code, error.message, error.request_id)
124
+ ```
125
+
126
+ Common codes: `insufficient_balance`, `schema_invalid` (input doesn't match the tool's schema), `max_charge_required`, `network_error`.
127
+
128
+ ## Other ways to connect
129
+
130
+ - [Purrkey plugin](https://github.com/purrkey/plugins) for Claude Code and Cursor (MCP)
131
+ - [Purrkey skills](https://github.com/purrkey/skills): task recipes for agents
132
+ - [Purrkey CLI](https://github.com/purrkey-ai/cli)
133
+ - [TypeScript SDK](https://github.com/purrkey/purrkey-js)
134
+ - [API reference](https://purrkey.app/docs?utm_source=github&utm_medium=readme&utm_campaign=geo_launch)
135
+
136
+ ## Development
137
+
138
+ ```sh
139
+ uv sync
140
+ uv run pytest
141
+ uv run mypy
142
+ uv run python scripts/generate.py --fetch # pull the live contract and regenerate types
143
+ ```
144
+
145
+ `src/purrkey/types.py` is generated from `openapi/openapi.yaml`; don't edit it by hand. CI fails when they disagree, and a weekly job checks the vendored contract against the live API.
146
+
147
+ ## License
148
+
149
+ [MIT](LICENSE)
@@ -0,0 +1,128 @@
1
+ # Purrkey Python SDK
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/purrkey)](https://pypi.org/project/purrkey/)
4
+
5
+ The official Python client for [Purrkey](https://purrkey.app/?utm_source=github&utm_medium=readme&utm_campaign=geo_launch), a pay-per-call tool marketplace for AI agents. One API key reaches 1,100+ data tools: social media from TikTok, Instagram, YouTube, Xiaohongshu and Douyin, Amazon and eBay listings, Google Maps reviews, SEO data, and web search and scraping. Every tool has a published price, and each call is paid from one balance.
6
+
7
+ Python 3.10+. Sync and async clients. Fully typed.
8
+
9
+ ## Install
10
+
11
+ ```sh
12
+ pip install purrkey
13
+ ```
14
+
15
+ ## Quick start
16
+
17
+ Create a key at [purrkey.app/keys](https://purrkey.app/keys?utm_source=github&utm_medium=readme&utm_campaign=geo_launch) and set it as `PURRKEY_API_KEY`. New accounts get $1 in free credit.
18
+
19
+ ```python
20
+ from purrkey import Purrkey
21
+
22
+ with Purrkey() as purrkey: # reads PURRKEY_API_KEY
23
+ # 1. Find a tool (free)
24
+ candidates = purrkey.discover("google maps reviews")["candidates"]
25
+
26
+ # 2. Read its schema and price (free)
27
+ tool = purrkey.inspect("tikhub.tiktok.app.v3.fetch_video_search_result")
28
+ print(tool["tool"]["price"]) # {'unit': 'call', 'unitPriceMicros': '1000', ...}
29
+
30
+ # 3. Run it and wait for the result
31
+ run = purrkey.run(
32
+ "tikhub.tiktok.app.v3.fetch_video_search_result",
33
+ {"query": {"keyword": "matcha latte", "count": 10}},
34
+ )
35
+ print(run["status"]) # SUCCEEDED
36
+ print(run["billing"]["chargedMicros"]) # 1000 = $0.001
37
+ print(run["result"]["output"])
38
+ ```
39
+
40
+ Async:
41
+
42
+ ```python
43
+ import asyncio
44
+ from purrkey import AsyncPurrkey
45
+
46
+ async def main() -> None:
47
+ async with AsyncPurrkey() as purrkey:
48
+ run = await purrkey.run("anyapi.web.scrape", {"url": "https://purrkey.app/about"})
49
+ print(run["result"]["output"]["data"]["markdown"])
50
+
51
+ asyncio.run(main())
52
+ ```
53
+
54
+ Browse the [tool catalog](https://purrkey.app/tools?utm_source=github&utm_medium=readme&utm_campaign=geo_launch) to see what is available.
55
+
56
+ ## Paying safely
57
+
58
+ `run()` handles the rules that keep a task from being charged twice:
59
+
60
+ - **Spending cap.** Each Run carries `maxChargeMicros`, the most it may cost (1 USD = 1,000,000 micros). For tools priced per call, the SDK uses the inspected price. When the price depends on the input (per result, per URL, per credit), pass `max_charge_micros` yourself; otherwise `run()` raises `max_charge_required` before anything is charged.
61
+ - **Idempotency.** Every Run has an `idempotencyKey`. If a response is lost, the SDK sends the same request again with the same key, and Purrkey returns the original Run instead of running and charging again. Pass your own key to make retries safe across processes:
62
+
63
+ ```python
64
+ purrkey.run(tool_id, payload, idempotency_key=f"report-{report_id}")
65
+ ```
66
+
67
+ A new key means a new, separately charged task.
68
+ - **Unknown outcomes.** `UNKNOWN` means the provider's outcome needs reconciliation. The SDK stops waiting and returns the Run. Check it later with `get_run(run_id)`; don't submit the task again.
69
+ - **Billing is separate from status.** Read `run["billing"]` (`status`, `heldMicros`, `chargedMicros`). A failed Run can still be charged for verified work when the tool's pricing allows it.
70
+
71
+ Account-wide daily and per-run caps can be set at [purrkey.app/budget](https://purrkey.app/budget?utm_source=github&utm_medium=readme&utm_campaign=geo_launch).
72
+
73
+ ## API
74
+
75
+ | Method | What it does | Cost |
76
+ | --- | --- | --- |
77
+ | `discover(query, *, limit, provider_id, category)` | Find tool candidates for one task | Free |
78
+ | `inspect(tool_id, *, tool_revision)` | Exact input/output schema, price and delivery rules | Free |
79
+ | `run(tool_id, input, *, max_charge_micros, idempotency_key, wait=True, timeout=120)` | Inspect, submit and (by default) wait for a final status | Tool price |
80
+ | `submit_run(request)` | Submit a prepared `RunRequest` | Tool price |
81
+ | `get_run(run_id)` | Read a Run and its result | Free |
82
+ | `wait_for_run(run_id, *, timeout)` | Poll until a final status; returns the Run as it is on timeout | Free |
83
+ | `cancel_run(run_id)` | Request cancellation | — |
84
+ | `list_runs(**filters)` | List your Runs (`status`, `toolId`, `cursor`, `limit`, …) | Free |
85
+ | `balance()` | Balance and held amounts | Free |
86
+ | `list_tools()`, `list_providers()`, `catalog()`, `platform_endpoints(platform)`, `rankings()` | Browse the catalog | Free |
87
+
88
+ `AsyncPurrkey` has the same methods as coroutines. Client options: `api_key` (default `PURRKEY_API_KEY`), `base_url`, `timeout`, `max_retries` (default 2; network errors, 429 and 5xx), `http_client`.
89
+
90
+ Responses are plain dicts typed with `TypedDict`s from `purrkey.types`, generated from the [public OpenAPI contract](https://purrkey.app/docs/openapi.yaml).
91
+
92
+ ## Errors
93
+
94
+ API errors and client-side checks raise `PurrkeyError`:
95
+
96
+ ```python
97
+ from purrkey import PurrkeyError
98
+
99
+ try:
100
+ purrkey.run(tool_id, payload)
101
+ except PurrkeyError as error:
102
+ print(error.status, error.code, error.message, error.request_id)
103
+ ```
104
+
105
+ Common codes: `insufficient_balance`, `schema_invalid` (input doesn't match the tool's schema), `max_charge_required`, `network_error`.
106
+
107
+ ## Other ways to connect
108
+
109
+ - [Purrkey plugin](https://github.com/purrkey/plugins) for Claude Code and Cursor (MCP)
110
+ - [Purrkey skills](https://github.com/purrkey/skills): task recipes for agents
111
+ - [Purrkey CLI](https://github.com/purrkey-ai/cli)
112
+ - [TypeScript SDK](https://github.com/purrkey/purrkey-js)
113
+ - [API reference](https://purrkey.app/docs?utm_source=github&utm_medium=readme&utm_campaign=geo_launch)
114
+
115
+ ## Development
116
+
117
+ ```sh
118
+ uv sync
119
+ uv run pytest
120
+ uv run mypy
121
+ uv run python scripts/generate.py --fetch # pull the live contract and regenerate types
122
+ ```
123
+
124
+ `src/purrkey/types.py` is generated from `openapi/openapi.yaml`; don't edit it by hand. CI fails when they disagree, and a weekly job checks the vendored contract against the live API.
125
+
126
+ ## License
127
+
128
+ [MIT](LICENSE)