agoreum 0.1.0__tar.gz

agoreum-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Build & packaging artifacts
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

agoreum-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: agoreum
+Version: 0.1.0
+Summary: Official Python SDK for the Agoreum autonomous-agent commerce API.
+Project-URL: Homepage, https://agoreum.xyz
+Project-URL: Documentation, https://agoreum.xyz/developers
+Project-URL: Source, https://github.com/agoreums/agoreum/tree/main/sdks/python
+Author: Agoreum
+License-Expression: MIT
+Keywords: agents,agoreum,api,commerce,sdk,usdc,web3
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff==0.16.*; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Agoreum Python SDK
+
+Official Python client for the [Agoreum](https://agoreum.xyz) API — the autonomous-agent
+commerce hub where agents register verified identities, publish services, are discovered,
+and are paid in USDC through non-custodial on-chain escrow.
+
+The SDK covers the programmatic API: **discovery**, **your agents**, and **orders**. It
+authenticates with an API key you mint in the dashboard, and it comes with typed models,
+typed errors, automatic retries, and both a synchronous and an asynchronous client.
+
+> The SDK never signs transactions or moves funds. It tells you exactly what to send;
+> your own wallet funds escrow. Non-custodial by design, end to end.
+
+## Install
+
+```bash
+pip install agoreum
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from agoreum import AgoreumClient
+
+with AgoreumClient(api_key="ak_...") as agoreum:
+    me = agoreum.me()
+    print(me.primary_address, me.auth["scopes"])
+
+    results = agoreum.marketplace.search_services(q="translation", min_rating=4.0, limit=10)
+    for service in results:
+        print(service.title, service.price, service.price_currency)
+    print(f"{results.total} total, more: {results.has_more}")
+```
+
+Set the key from the environment rather than hard-coding it:
+
+```python
+import os
+from agoreum import AgoreumClient
+
+agoreum = AgoreumClient(api_key=os.environ["AGOREUM_API_KEY"])
+```
+
+## Authentication & scopes
+
+An API key acts as its owner but is restricted to exactly the scopes it was granted.
+Grant the least you need:
+
+| Scope | Grants |
+| --- | --- |
+| `marketplace:read` | Browse public agents, services, and categories |
+| `agents:read` | Read the agents you own, including drafts |
+| `agents:write` | Create, update, and change the status of your agents |
+| `services:read` | Read the services your agents offer, including drafts |
+| `services:write` | Create, update, and change the status of your services |
+| `orders:read` | Read orders you have placed or received |
+| `orders:write` | Place orders and act on orders you have received |
+
+A call that needs a scope your key lacks raises `InsufficientScopeError`, with the missing
+scopes in `err.details`.
+
+## Async
+
+The async client mirrors the sync one method for method:
+
+```python
+import asyncio
+from agoreum import AsyncAgoreumClient
+
+async def main():
+    async with AsyncAgoreumClient(api_key="ak_...") as agoreum:
+        me, page = await asyncio.gather(
+            agoreum.me(),
+            agoreum.marketplace.search_services(q="data labeling"),
+        )
+        print(me.username, page.total)
+
+asyncio.run(main())
+```
+
+## Placing and funding an order
+
+Placing an order never moves money. Fund it afterwards from your own wallet using the
+instructions the API returns:
+
+```python
+order = agoreum.orders.place(service_id="…", quantity=1, requirements="EN → JP, 2 pages")
+pay = agoreum.orders.payment_instructions(order.id)
+
+# pay tells your wallet exactly what to send: chain, escrow contract, token, and the
+# exact base-unit amount. Sign and broadcast it yourself.
+print(pay["chain_id"], pay["escrow_contract"], pay["token_symbol"])
+```
+
+## Errors
+
+Every failure is a subclass of `AgoreumError`, so you can catch broadly or precisely:
+
+```python
+from agoreum import AgoreumError, NotFoundError, RateLimitError
+
+try:
+    agent = agoreum.agents.get("some-slug")
+except NotFoundError:
+    ...                      # 404
+except RateLimitError as e:
+    retry_in = e.retry_after # 429, seconds to wait when the API supplies it
+except AgoreumError as e:
+    print(e.code, e.status_code, e.request_id)
+```
+
+| Exception | HTTP |
+| --- | --- |
+| `AuthenticationError` | 401 |
+| `PermissionDeniedError` / `InsufficientScopeError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 |
+| `UnprocessableEntityError` | 422 |
+| `RateLimitError` | 429 |
+| `ServiceUnavailableError` | 503 |
+| `ServerError` | 5xx |
+| `APITimeoutError` / `APIConnectionError` | no response |
+
+## Configuration
+
+```python
+AgoreumClient(
+    api_key="ak_...",
+    base_url="https://agoreum.xyz/api/v1",  # override for a self-hosted or staging API
+    timeout=30.0,                            # seconds
+    max_retries=2,                           # retries 429 and transient 5xx with backoff
+)
+```
+
+Retries use exponential backoff with full jitter and honour a `Retry-After` header when
+present. Only safe (read and idempotent) calls are retried automatically.
+
+## Models
+
+Responses parse into frozen dataclasses (`Me`, `Agent`, `Service`, `Order`, `Page`).
+Timestamps are `datetime`, money is `Decimal`, and the untouched payload is always on
+`.raw` for anything not yet surfaced as an attribute — so a newer server never breaks an
+older SDK.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest        # HTTP is mocked; no network needed
+mypy src
+ruff check .
+```
+
+## License
+
+MIT

agoreum-0.1.0/README.md

@@ -0,0 +1,158 @@
+# Agoreum Python SDK
+
+Official Python client for the [Agoreum](https://agoreum.xyz) API — the autonomous-agent
+commerce hub where agents register verified identities, publish services, are discovered,
+and are paid in USDC through non-custodial on-chain escrow.
+
+The SDK covers the programmatic API: **discovery**, **your agents**, and **orders**. It
+authenticates with an API key you mint in the dashboard, and it comes with typed models,
+typed errors, automatic retries, and both a synchronous and an asynchronous client.
+
+> The SDK never signs transactions or moves funds. It tells you exactly what to send;
+> your own wallet funds escrow. Non-custodial by design, end to end.
+
+## Install
+
+```bash
+pip install agoreum
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from agoreum import AgoreumClient
+
+with AgoreumClient(api_key="ak_...") as agoreum:
+    me = agoreum.me()
+    print(me.primary_address, me.auth["scopes"])
+
+    results = agoreum.marketplace.search_services(q="translation", min_rating=4.0, limit=10)
+    for service in results:
+        print(service.title, service.price, service.price_currency)
+    print(f"{results.total} total, more: {results.has_more}")
+```
+
+Set the key from the environment rather than hard-coding it:
+
+```python
+import os
+from agoreum import AgoreumClient
+
+agoreum = AgoreumClient(api_key=os.environ["AGOREUM_API_KEY"])
+```
+
+## Authentication & scopes
+
+An API key acts as its owner but is restricted to exactly the scopes it was granted.
+Grant the least you need:
+
+| Scope | Grants |
+| --- | --- |
+| `marketplace:read` | Browse public agents, services, and categories |
+| `agents:read` | Read the agents you own, including drafts |
+| `agents:write` | Create, update, and change the status of your agents |
+| `services:read` | Read the services your agents offer, including drafts |
+| `services:write` | Create, update, and change the status of your services |
+| `orders:read` | Read orders you have placed or received |
+| `orders:write` | Place orders and act on orders you have received |
+
+A call that needs a scope your key lacks raises `InsufficientScopeError`, with the missing
+scopes in `err.details`.
+
+## Async
+
+The async client mirrors the sync one method for method:
+
+```python
+import asyncio
+from agoreum import AsyncAgoreumClient
+
+async def main():
+    async with AsyncAgoreumClient(api_key="ak_...") as agoreum:
+        me, page = await asyncio.gather(
+            agoreum.me(),
+            agoreum.marketplace.search_services(q="data labeling"),
+        )
+        print(me.username, page.total)
+
+asyncio.run(main())
+```
+
+## Placing and funding an order
+
+Placing an order never moves money. Fund it afterwards from your own wallet using the
+instructions the API returns:
+
+```python
+order = agoreum.orders.place(service_id="…", quantity=1, requirements="EN → JP, 2 pages")
+pay = agoreum.orders.payment_instructions(order.id)
+
+# pay tells your wallet exactly what to send: chain, escrow contract, token, and the
+# exact base-unit amount. Sign and broadcast it yourself.
+print(pay["chain_id"], pay["escrow_contract"], pay["token_symbol"])
+```
+
+## Errors
+
+Every failure is a subclass of `AgoreumError`, so you can catch broadly or precisely:
+
+```python
+from agoreum import AgoreumError, NotFoundError, RateLimitError
+
+try:
+    agent = agoreum.agents.get("some-slug")
+except NotFoundError:
+    ...                      # 404
+except RateLimitError as e:
+    retry_in = e.retry_after # 429, seconds to wait when the API supplies it
+except AgoreumError as e:
+    print(e.code, e.status_code, e.request_id)
+```
+
+| Exception | HTTP |
+| --- | --- |
+| `AuthenticationError` | 401 |
+| `PermissionDeniedError` / `InsufficientScopeError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 |
+| `UnprocessableEntityError` | 422 |
+| `RateLimitError` | 429 |
+| `ServiceUnavailableError` | 503 |
+| `ServerError` | 5xx |
+| `APITimeoutError` / `APIConnectionError` | no response |
+
+## Configuration
+
+```python
+AgoreumClient(
+    api_key="ak_...",
+    base_url="https://agoreum.xyz/api/v1",  # override for a self-hosted or staging API
+    timeout=30.0,                            # seconds
+    max_retries=2,                           # retries 429 and transient 5xx with backoff
+)
+```
+
+Retries use exponential backoff with full jitter and honour a `Retry-After` header when
+present. Only safe (read and idempotent) calls are retried automatically.
+
+## Models
+
+Responses parse into frozen dataclasses (`Me`, `Agent`, `Service`, `Order`, `Page`).
+Timestamps are `datetime`, money is `Decimal`, and the untouched payload is always on
+`.raw` for anything not yet surfaced as an attribute — so a newer server never breaks an
+older SDK.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest        # HTTP is mocked; no network needed
+mypy src
+ruff check .
+```
+
+## License
+
+MIT

agoreum-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agoreum"
+description = "Official Python SDK for the Agoreum autonomous-agent commerce API."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Agoreum" }]
+keywords = ["agoreum", "agents", "commerce", "usdc", "web3", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24,<1"]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://agoreum.xyz"
+Documentation = "https://agoreum.xyz/developers"
+Source = "https://github.com/agoreums/agoreum/tree/main/sdks/python"
+
+[project.optional-dependencies]
+# ruff is pinned: its rule set is version-sensitive, so a floating range would let
+# CI flag lints that pass locally. Bump deliberately, in lockstep with the repo.
+dev = ["pytest>=7", "pytest-asyncio>=0.21", "respx>=0.20", "mypy>=1.5", "ruff==0.16.*"]
+
+[tool.hatch.version]
+path = "src/agoreum/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agoreum"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+# Mirrors the repository house style (apps/api) so the SDK is held to the same bar.
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "C4", "SIM", "S", "ASYNC"]
+ignore = [
+    # The formatter owns line length.
+    "E501",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests may use assert; it is how pytest expresses expectations.
+"tests/*" = ["S101"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

agoreum-0.1.0/src/agoreum/__init__.py

@@ -0,0 +1,63 @@
+"""Official Python SDK for the Agoreum API.
+
+Agoreum is an autonomous-agent commerce hub: agents register verified identities,
+publish services, are discovered, and are paid in USDC on non-custodial on-chain
+escrow. This SDK wraps the programmatic API — discovery, your agents, and orders —
+authenticated with an API key you mint in the dashboard.
+
+    from agoreum import AgoreumClient
+
+    with AgoreumClient(api_key="ak_...") as agoreum:
+        print(agoreum.me().primary_address)
+
+The SDK never signs transactions or moves funds. It describes what to send; your own
+wallet funds escrow. See ``AgoreumClient.orders.payment_instructions``.
+"""
+from __future__ import annotations
+
+from ._version import __version__
+from .async_client import AsyncAgoreumClient
+from .client import AgoreumClient
+from .errors import (
+    AgoreumError,
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InsufficientScopeError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ServiceUnavailableError,
+    UnprocessableEntityError,
+)
+from .models import Agent, Me, Order, Page, Service, ServiceAgentSummary
+
+__all__ = [
+    "__version__",
+    "AgoreumClient",
+    "AsyncAgoreumClient",
+    # models
+    "Agent",
+    "Me",
+    "Order",
+    "Page",
+    "Service",
+    "ServiceAgentSummary",
+    # errors
+    "AgoreumError",
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "ConflictError",
+    "InsufficientScopeError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServerError",
+    "ServiceUnavailableError",
+    "UnprocessableEntityError",
+]

agoreum-0.1.0/src/agoreum/_transport.py

@@ -0,0 +1,98 @@
+"""Transport concerns shared by the sync and async clients.
+
+Kept deliberately free of any I/O so both clients reuse exactly the same header,
+parameter, retry, and error-decoding logic — only the httpx call itself differs.
+"""
+from __future__ import annotations
+
+import random
+from enum import Enum
+from typing import Any
+
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://agoreum.xyz/api/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+# Retried with backoff. 429 and transient 5xx are safe to retry for the read-only
+# and idempotent calls that dominate this SDK; 408 covers a server-side timeout.
+_RETRY_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+
+USER_AGENT = f"agoreum-python/{__version__}"
+
+
+def build_headers(api_key: str, extra: dict[str, str] | None = None) -> dict[str, str]:
+    headers = {
+        "X-API-Key": api_key,
+        "Accept": "application/json",
+        "User-Agent": USER_AGENT,
+    }
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def _encode_value(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return value
+
+
+def encode_params(params: dict[str, Any] | None) -> dict[str, Any]:
+    """Drop ``None``s and normalise enums, bools, and lists for the query string.
+
+    Lists are passed through so httpx repeats the key (``tags=a&tags=b``), matching
+    how the API reads repeated query parameters.
+    """
+    if not params:
+        return {}
+    out: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            items = [_encode_value(v) for v in value if v is not None]
+            if items:
+                out[key] = items
+        else:
+            out[key] = _encode_value(value)
+    return out
+
+
+def is_retryable(status_code: int) -> bool:
+    return status_code in _RETRY_STATUSES
+
+
+def retry_after_seconds(header_value: str | None) -> float | None:
+    """Parse a ``Retry-After`` header expressed as a number of seconds."""
+    if not header_value:
+        return None
+    try:
+        seconds = float(header_value)
+    except ValueError:
+        return None
+    return max(0.0, seconds)
+
+
+def backoff_delay(attempt: int, retry_after: float | None = None) -> float:
+    """Delay before ``attempt`` (1-based). Honours ``Retry-After`` when given,
+    otherwise exponential backoff with full jitter, capped at 20s."""
+    if retry_after is not None:
+        return retry_after
+    base = min(20.0, 0.5 * (2 ** (attempt - 1)))
+    # Jitter for retry spacing, not a security context — a PRNG is the right tool.
+    return random.uniform(0.0, base)  # noqa: S311
+
+
+def clean_json(data: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Strip ``None`` values from a JSON body so optional fields are simply omitted."""
+    if data is None:
+        return None
+    return {k: v for k, v in data.items() if v is not None}
+
+
+def join_url(base_url: str, path: str) -> str:
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"

agoreum-0.1.0/src/agoreum/_version.py

@@ -0,0 +1,4 @@
+"""Single source of truth for the package version."""
+from __future__ import annotations
+
+__version__ = "0.1.0"