cracked-ai 0.1.0__tar.gz

cracked_ai-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: cracked-ai
+Version: 0.1.0
+Summary: Zero-dependency Python client for Cracked, the agent tool router: discover, inspect, run and poll 50,000+ tools with one API key.
+Author: Cracked
+License: MIT
+Project-URL: Homepage, https://cracked.ai
+Project-URL: Documentation, https://cracked.ai/docs/sdks
+Project-URL: API reference, https://cracked.ai/docs/api
+Keywords: agents,tools,api,llm,scraping,mcp,cracked
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# cracked-ai (Python)
+
+Zero-dependency Python client for [Cracked](https://cracked.ai), the tool router for agents: one API key, one balance, 50,000+ tools (scrapers, search, data, AI models). Discover a tool in natural language, inspect its schema, run it, poll if it is asynchronous.
+
+Publishing to PyPI soon. Until then install from the repo path:
+
+```bash
+pip install ./sdk/python            # from the repo root
+# or, once published:
+pip install cracked-ai
+```
+
+Python 3.9+. Uses only the standard library (`urllib`).
+
+## Quick start
+
+```python
+import os
+from cracked_ai import Cracked, CrackedError
+
+c = Cracked()  # reads CRACKED_API_KEY; base URL from CRACKED_BASE_URL (default https://cracked.ai/v1)
+
+hits = c.discover("weather forecast for a lat/long", limit=5)["results"]
+best = hits[0]
+schema = c.inspect(best["provider"], best["endpoint"])["input"]["body"]   # JSON Schema, never guess fields
+
+rec = c.run("open-meteo", "/forecast", {"latitude": 30.27, "longitude": -97.74})
+print(rec["status"], rec["billing"]["totalUsd"])
+print(rec["output"])
+```
+
+No key yet? Register an agent workspace with no human in the loop (trial credit included):
+
+```python
+reg = Cracked.register_agent(name="my-agent")
+reg.client.run(...)            # ready to use
+print(reg.api_key)             # shown once: store it as CRACKED_API_KEY
+print(reg.claim_url)           # give this to your human: adds credit, unlocks top-ups
+```
+
+## Methods
+
+| Method | Endpoint | Notes |
+|---|---|---|
+| `discover(query, limit=8, live_only=None, min_score=None, category=None, provider=None, include_apify=None, include_unavailable=None)` | `POST /discover` | Returns `{query, count, results}` |
+| `inspect(provider, endpoint)` | `POST /inspect` | Schema in `["input"]["body"]`, price, health |
+| `run(provider, endpoint, input=None, wait=True, poll=None, webhook_url=None, timeout=300, poll_wait=30)` | `POST /run` | Returns a `RunRecord`; polls on 202 when `poll` (defaults to `wait`) |
+| `run_capability(capability, input=None, ...)` | `POST /run {capability}` | Smart run: Cracked picks the provider and falls back. Adds `routedTo`, `attempts` |
+| `capabilities(id=None)` | `GET /capabilities?id=` | List capabilities (input schema + ranked candidates), or one by id. No auth |
+| `get_run(run_id, wait=None)` | `GET /runs/{id}?wait=` | `wait` long-polls up to 100 s |
+| `wait_for(run_id, timeout=300, poll_wait=30)` | polls `GET /runs/{id}` | Raises `CrackedTimeout` (with `.record`) if still RUNNING |
+| `stop(run_id)` | `POST /runs/{id}/stop` | 409 if already finished |
+| `runs(limit=25)` | `GET /runs` | Recent runs, no output bodies |
+| `feedback(run_id, ok, note=None)` | `POST /runs/{id}/feedback` | Thumbs up/down; small bounty on claimed workspaces |
+| `balance()` | `GET /wallet/balance` | `balance`, `lifetimeTopUp`, `lifetimeSpend` |
+| `whoami()` | `GET /auth/whoami` | |
+| `referrals()` / `referral_link()` | `GET /referrals` | Share the link: both sides get credit |
+| `bounty_program()` | `GET /bounties/program` | Public, no auth |
+| `bounties()` | `GET /bounties` | Your bounty ledger |
+| `claim_bounty(url)` | `POST /bounties` | Backlink/listing bounty for a page carrying your referral link |
+| `Cracked.register_agent(name=None, ref=None, base_url=None)` | `POST /agents/register` | Classmethod, no auth. Returns `AgentRegistration(client, api_key, claim_url, referral_url, ...)` |
+
+All responses are plain `dict`s typed as `TypedDict`s (`RunRecord`, `SmartRunRecord`, `DiscoverResult`, `InspectResult`, `Balance`, ...). Import them from `cracked_ai`.
+
+## Async runs
+
+Scrapers marked `async: true` in discover results can take minutes. Either let the client poll:
+
+```python
+rec = c.run("apify", "/apify/instagram-profile-scraper", {"usernames": ["nike"]}, wait=False, poll=True, timeout=600)
+```
+
+or drive it yourself:
+
+```python
+rec = c.run("apify", "/apify/instagram-profile-scraper", {"usernames": ["nike"]}, wait=False)   # HTTP 202, status RUNNING
+rec = c.wait_for(rec["runId"], timeout=600)                                                     # or c.get_run(id, wait=30) in a loop
+c.stop(rec["runId"])                                                                            # abort if needed
+```
+
+Terminal statuses: `COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT`. `COMPLETED` with `providerResponse.httpStatus == 404` means the provider found nothing; that is not an error. `BLOCKED` (HTTP 503, not billed) means the provider needs your own key: add it at `/app/connections` or pick another result.
+
+## Errors
+
+Every non-2xx response raises `CrackedError` with `.status`, `.code`, `.message` (and `.run_id` when relevant):
+
+```python
+try:
+    c.run("some-provider", "/endpoint", {...})
+except CrackedError as e:
+    if e.insufficient_funds:   # 402: top up at https://cracked.ai/app/billing or earn credit via bounties
+        ...
+    elif e.unauthorized:       # 401: bad or missing key
+        ...
+    elif e.rate_limited:       # 429
+        ...
+```
+
+Transport failures raise `CrackedError` with `status == 0` and code `NETWORK_ERROR` / `NETWORK_TIMEOUT`.
+
+## CLI
+
+```bash
+python -m cracked_ai discover "instagram profile followers" -l 5
+python -m cracked_ai inspect open-meteo /forecast
+python -m cracked_ai run open-meteo /forecast '{"latitude":30.27,"longitude":-97.74}'
+python -m cracked_ai capability instagram-profile '{"username":"nike"}'
+python -m cracked_ai get <runId> -w 30
+python -m cracked_ai balance
+python -m cracked_ai register my-agent
+```
+
+(`cracked-ai ...` works too once installed via pip.)
+
+## Tests
+
+`tests/test_smoke.py` hits the live API and is skipped unless `CRACKED_API_KEY` is set. It spends well under $0.05 (two keyless weather calls).
+
+```bash
+CRACKED_API_KEY=ck_live_... CRACKED_BASE_URL=https://cracked.ai/v1 python -m pytest sdk/python/tests -q
+```
+
+## Publishing
+
+```bash
+cd sdk/python && python -m pip install build twine && python -m build && twine upload dist/*
+```

cracked_ai-0.1.0/README.md

@@ -0,0 +1,127 @@
+# cracked-ai (Python)
+
+Zero-dependency Python client for [Cracked](https://cracked.ai), the tool router for agents: one API key, one balance, 50,000+ tools (scrapers, search, data, AI models). Discover a tool in natural language, inspect its schema, run it, poll if it is asynchronous.
+
+Publishing to PyPI soon. Until then install from the repo path:
+
+```bash
+pip install ./sdk/python            # from the repo root
+# or, once published:
+pip install cracked-ai
+```
+
+Python 3.9+. Uses only the standard library (`urllib`).
+
+## Quick start
+
+```python
+import os
+from cracked_ai import Cracked, CrackedError
+
+c = Cracked()  # reads CRACKED_API_KEY; base URL from CRACKED_BASE_URL (default https://cracked.ai/v1)
+
+hits = c.discover("weather forecast for a lat/long", limit=5)["results"]
+best = hits[0]
+schema = c.inspect(best["provider"], best["endpoint"])["input"]["body"]   # JSON Schema, never guess fields
+
+rec = c.run("open-meteo", "/forecast", {"latitude": 30.27, "longitude": -97.74})
+print(rec["status"], rec["billing"]["totalUsd"])
+print(rec["output"])
+```
+
+No key yet? Register an agent workspace with no human in the loop (trial credit included):
+
+```python
+reg = Cracked.register_agent(name="my-agent")
+reg.client.run(...)            # ready to use
+print(reg.api_key)             # shown once: store it as CRACKED_API_KEY
+print(reg.claim_url)           # give this to your human: adds credit, unlocks top-ups
+```
+
+## Methods
+
+| Method | Endpoint | Notes |
+|---|---|---|
+| `discover(query, limit=8, live_only=None, min_score=None, category=None, provider=None, include_apify=None, include_unavailable=None)` | `POST /discover` | Returns `{query, count, results}` |
+| `inspect(provider, endpoint)` | `POST /inspect` | Schema in `["input"]["body"]`, price, health |
+| `run(provider, endpoint, input=None, wait=True, poll=None, webhook_url=None, timeout=300, poll_wait=30)` | `POST /run` | Returns a `RunRecord`; polls on 202 when `poll` (defaults to `wait`) |
+| `run_capability(capability, input=None, ...)` | `POST /run {capability}` | Smart run: Cracked picks the provider and falls back. Adds `routedTo`, `attempts` |
+| `capabilities(id=None)` | `GET /capabilities?id=` | List capabilities (input schema + ranked candidates), or one by id. No auth |
+| `get_run(run_id, wait=None)` | `GET /runs/{id}?wait=` | `wait` long-polls up to 100 s |
+| `wait_for(run_id, timeout=300, poll_wait=30)` | polls `GET /runs/{id}` | Raises `CrackedTimeout` (with `.record`) if still RUNNING |
+| `stop(run_id)` | `POST /runs/{id}/stop` | 409 if already finished |
+| `runs(limit=25)` | `GET /runs` | Recent runs, no output bodies |
+| `feedback(run_id, ok, note=None)` | `POST /runs/{id}/feedback` | Thumbs up/down; small bounty on claimed workspaces |
+| `balance()` | `GET /wallet/balance` | `balance`, `lifetimeTopUp`, `lifetimeSpend` |
+| `whoami()` | `GET /auth/whoami` | |
+| `referrals()` / `referral_link()` | `GET /referrals` | Share the link: both sides get credit |
+| `bounty_program()` | `GET /bounties/program` | Public, no auth |
+| `bounties()` | `GET /bounties` | Your bounty ledger |
+| `claim_bounty(url)` | `POST /bounties` | Backlink/listing bounty for a page carrying your referral link |
+| `Cracked.register_agent(name=None, ref=None, base_url=None)` | `POST /agents/register` | Classmethod, no auth. Returns `AgentRegistration(client, api_key, claim_url, referral_url, ...)` |
+
+All responses are plain `dict`s typed as `TypedDict`s (`RunRecord`, `SmartRunRecord`, `DiscoverResult`, `InspectResult`, `Balance`, ...). Import them from `cracked_ai`.
+
+## Async runs
+
+Scrapers marked `async: true` in discover results can take minutes. Either let the client poll:
+
+```python
+rec = c.run("apify", "/apify/instagram-profile-scraper", {"usernames": ["nike"]}, wait=False, poll=True, timeout=600)
+```
+
+or drive it yourself:
+
+```python
+rec = c.run("apify", "/apify/instagram-profile-scraper", {"usernames": ["nike"]}, wait=False)   # HTTP 202, status RUNNING
+rec = c.wait_for(rec["runId"], timeout=600)                                                     # or c.get_run(id, wait=30) in a loop
+c.stop(rec["runId"])                                                                            # abort if needed
+```
+
+Terminal statuses: `COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT`. `COMPLETED` with `providerResponse.httpStatus == 404` means the provider found nothing; that is not an error. `BLOCKED` (HTTP 503, not billed) means the provider needs your own key: add it at `/app/connections` or pick another result.
+
+## Errors
+
+Every non-2xx response raises `CrackedError` with `.status`, `.code`, `.message` (and `.run_id` when relevant):
+
+```python
+try:
+    c.run("some-provider", "/endpoint", {...})
+except CrackedError as e:
+    if e.insufficient_funds:   # 402: top up at https://cracked.ai/app/billing or earn credit via bounties
+        ...
+    elif e.unauthorized:       # 401: bad or missing key
+        ...
+    elif e.rate_limited:       # 429
+        ...
+```
+
+Transport failures raise `CrackedError` with `status == 0` and code `NETWORK_ERROR` / `NETWORK_TIMEOUT`.
+
+## CLI
+
+```bash
+python -m cracked_ai discover "instagram profile followers" -l 5
+python -m cracked_ai inspect open-meteo /forecast
+python -m cracked_ai run open-meteo /forecast '{"latitude":30.27,"longitude":-97.74}'
+python -m cracked_ai capability instagram-profile '{"username":"nike"}'
+python -m cracked_ai get <runId> -w 30
+python -m cracked_ai balance
+python -m cracked_ai register my-agent
+```
+
+(`cracked-ai ...` works too once installed via pip.)
+
+## Tests
+
+`tests/test_smoke.py` hits the live API and is skipped unless `CRACKED_API_KEY` is set. It spends well under $0.05 (two keyless weather calls).
+
+```bash
+CRACKED_API_KEY=ck_live_... CRACKED_BASE_URL=https://cracked.ai/v1 python -m pytest sdk/python/tests -q
+```
+
+## Publishing
+
+```bash
+cd sdk/python && python -m pip install build twine && python -m build && twine upload dist/*
+```

cracked_ai-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cracked-ai"
+version = "0.1.0"
+description = "Zero-dependency Python client for Cracked, the agent tool router: discover, inspect, run and poll 50,000+ tools with one API key."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Cracked" }]
+keywords = ["agents", "tools", "api", "llm", "scraping", "mcp", "cracked"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://cracked.ai"
+Documentation = "https://cracked.ai/docs/sdks"
+"API reference" = "https://cracked.ai/docs/api"
+
+[project.scripts]
+cracked-ai = "cracked_ai.__main__:main"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cracked_ai = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cracked_ai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cracked_ai-0.1.0/src/cracked_ai/__init__.py

@@ -0,0 +1,69 @@
+"""cracked_ai: zero-dependency Python client for Cracked, the agent tool router.
+
+    from cracked_ai import Cracked
+    c = Cracked()  # CRACKED_API_KEY, CRACKED_BASE_URL
+    rec = c.run("open-meteo", "/forecast", {"latitude": 30.27, "longitude": -97.74})
+"""
+
+from .client import (
+    DEFAULT_BASE_URL,
+    SERVER_MAX_POLL_WAIT,
+    TERMINAL_STATUSES,
+    AgentRegistration,
+    Cracked,
+    __version__,
+    is_terminal,
+)
+from .errors import CrackedError, CrackedTimeout
+from .types import (
+    Balance,
+    Billing,
+    BountyClaim,
+    DiscoverResponse,
+    DiscoverResult,
+    FeedbackResult,
+    HealthSummary,
+    InspectResult,
+    Price,
+    ProviderResponse,
+    ReferralStats,
+    RegistrationResponse,
+    RouteAttempt,
+    RoutedTo,
+    RunList,
+    RunRecord,
+    RunStatus,
+    SmartRunRecord,
+    StopResult,
+)
+
+__all__ = [
+    "Cracked",
+    "AgentRegistration",
+    "CrackedError",
+    "CrackedTimeout",
+    "DEFAULT_BASE_URL",
+    "SERVER_MAX_POLL_WAIT",
+    "TERMINAL_STATUSES",
+    "is_terminal",
+    "__version__",
+    "Balance",
+    "Billing",
+    "BountyClaim",
+    "DiscoverResponse",
+    "DiscoverResult",
+    "FeedbackResult",
+    "HealthSummary",
+    "InspectResult",
+    "Price",
+    "ProviderResponse",
+    "ReferralStats",
+    "RegistrationResponse",
+    "RouteAttempt",
+    "RoutedTo",
+    "RunList",
+    "RunRecord",
+    "RunStatus",
+    "SmartRunRecord",
+    "StopResult",
+]

cracked_ai-0.1.0/src/cracked_ai/__main__.py

@@ -0,0 +1,105 @@
+"""Minimal CLI: ``python -m cracked_ai discover "instagram followers"``.
+
+Commands: discover, inspect, run, capability, get, stop, balance, referral, register.
+Set CRACKED_API_KEY (and optionally CRACKED_BASE_URL). Output is JSON.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .client import Cracked
+from .errors import CrackedError
+
+
+def _json_arg(s: str | None) -> dict:
+    if not s:
+        return {}
+    if s.startswith("@"):
+        with open(s[1:], "r", encoding="utf-8") as f:
+            return json.load(f)
+    return json.loads(s)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="python -m cracked_ai", description="Cracked tool router CLI (JSON output)")
+    p.add_argument("--base-url", help="override CRACKED_BASE_URL")
+    p.add_argument("--api-key", help="override CRACKED_API_KEY")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    d = sub.add_parser("discover", help="search tools in natural language")
+    d.add_argument("query", nargs="+")
+    d.add_argument("-l", "--limit", type=int, default=8)
+    d.add_argument("--live", action="store_true", help="only providers that run without your own key")
+
+    i = sub.add_parser("inspect", help="schema, price, health")
+    i.add_argument("provider")
+    i.add_argument("endpoint")
+
+    r = sub.add_parser("run", help="execute an endpoint")
+    r.add_argument("provider")
+    r.add_argument("endpoint")
+    r.add_argument("input", nargs="?", help='JSON object or @file.json')
+    r.add_argument("--no-wait", action="store_true", help="return the 202 immediately, do not poll")
+    r.add_argument("--timeout", type=float, default=300)
+
+    cap = sub.add_parser("capability", help="smart run by capability name, e.g. instagram-profile")
+    cap.add_argument("capability")
+    cap.add_argument("input", nargs="?", help='JSON object or @file.json')
+    cap.add_argument("--no-wait", action="store_true")
+    cap.add_argument("--timeout", type=float, default=300)
+
+    g = sub.add_parser("get", help="fetch a run")
+    g.add_argument("run_id")
+    g.add_argument("-w", "--wait", type=int, default=0, help="long-poll seconds (max 100)")
+
+    s = sub.add_parser("stop", help="abort a running job")
+    s.add_argument("run_id")
+
+    sub.add_parser("balance", help="wallet balance")
+    sub.add_parser("referral", help="referral link and earnings")
+    sub.add_parser("program", help="bounty program (no auth)")
+
+    reg = sub.add_parser("register", help="self-register an agent workspace and print the key once")
+    reg.add_argument("name", nargs="?")
+    reg.add_argument("--ref")
+
+    a = p.parse_args(argv)
+    try:
+        if a.cmd == "register":
+            out = Cracked.register_agent(a.name, a.ref, base_url=a.base_url).raw
+        else:
+            c = Cracked(api_key=a.api_key, base_url=a.base_url)
+            if a.cmd == "discover":
+                out = c.discover(" ".join(a.query), limit=a.limit, live_only=True if a.live else None)
+            elif a.cmd == "inspect":
+                out = c.inspect(a.provider, a.endpoint)
+            elif a.cmd == "run":
+                out = c.run(a.provider, a.endpoint, _json_arg(a.input), wait=not a.no_wait, timeout=a.timeout)
+            elif a.cmd == "capability":
+                out = c.run_capability(a.capability, _json_arg(a.input), wait=not a.no_wait, timeout=a.timeout)
+            elif a.cmd == "get":
+                out = c.get_run(a.run_id, wait=a.wait or None)
+            elif a.cmd == "stop":
+                out = c.stop(a.run_id)
+            elif a.cmd == "balance":
+                out = c.balance()
+            elif a.cmd == "referral":
+                out = c.referrals()
+            elif a.cmd == "program":
+                out = c.bounty_program()
+            else:  # pragma: no cover
+                p.error("unknown command")
+        json.dump(out, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        return 0
+    except CrackedError as e:
+        json.dump({"error": e.code, "status": e.status, "message": e.message, **({"runId": e.run_id} if e.run_id else {})}, sys.stderr, indent=2)
+        sys.stderr.write("\n")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())