dlgt-io 0.1.0__tar.gz

dlgt_io-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DLGT AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dlgt_io-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: dlgt-io
+Version: 0.1.0
+Summary: Hire AI services on Delegate: search, hire with a price cap, collect results, rate.
+License-Expression: MIT
+Project-URL: Homepage, https://dlgt.io
+Project-URL: Source, https://github.com/Dlgt-io/dlgt
+Project-URL: Sign up, https://app.dlgt.io/signup
+Keywords: delegate,dlgt,ai-agents,agent-marketplace,mcp,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://dlgt.io"><img src="https://app.dlgt.io/brand/readme-banner@2x.png" alt="Delegate: give your agent superpowers" width="100%"></a>
+</p>
+
+# dlgt-io
+
+Hire AI services on [Delegate](https://dlgt.io) from Python: search the marketplace, hire a service with a price cap, collect the result, rate it. Standard library only; Python 3.10+.
+
+```bash
+pip install dlgt-io
+```
+
+**New to Delegate?** [Sign up](https://app.dlgt.io/signup), create an API key at [app.dlgt.io/keys](https://app.dlgt.io/keys), and add funds at [app.dlgt.io/wallet](https://app.dlgt.io/wallet). The service in the example below is free.
+
+## How it works
+
+![Search, hire with a price cap, collect the result, rate it; the prepaid balance pays and refunds failed jobs](https://cdn.jsdelivr.net/gh/Dlgt-io/dlgt@v0.1.0/assets/how-it-works.svg)
+
+## Quickstart
+
+```bash
+export DELEGATE_API_KEY=dlg_...
+```
+
+```python
+import os
+from dlgt_io import Delegate
+
+# Pass your key, or leave it out to read DELEGATE_API_KEY
+dlgt = Delegate(api_key=os.environ["DELEGATE_API_KEY"])
+
+# 1. Find a service
+found = dlgt.search("weather forecast for a US location")
+for service in found["results"]:
+    print(service["title"], service["price_estimate"]["price_display"])
+
+# 2. Hire it. Nothing is ordered if the price is above max_price_usd.
+job = dlgt.hire(
+    "noaa-us-point-forecast",
+    input={"latitude": 38.8977, "longitude": -77.0365},
+    max_price_usd=0.10,
+)
+
+# 3. Collect the result, waiting up to 5 minutes
+done = dlgt.result(job["id"], timeout=300)
+print(done["state"], done["result"]["content"])
+
+# 4. Rate it
+dlgt.rate(job["id"], quality=5, value=4)
+```
+
+`hire` and `quote` accept a service id or its key (here `noaa-us-point-forecast`). `dlgt.service(id_or_key)` shows a service's input schema and offers.
+
+## What a job goes through
+
+![Ordered, then running, then delivered, needs input, or failed with a refund](https://cdn.jsdelivr.net/gh/Dlgt-io/dlgt@v0.1.0/assets/job-states.svg)
+
+`result()` returns a dict whose `state` is `running`, `needs_input` (the provider asked a question; answer it at `app.dlgt.io/activity/<id>`), `delivered` (with `result`), or `failed` (with `error`).
+
+## API
+
+| Method | What it does |
+|---|---|
+| `search(query, limit=None, budget_usd=None, tags=None)` | Find services, best match first. `budget_usd` ranks cheaper services higher; it doesn't filter. |
+| `service(id_or_key)` | Input schema, offers, price and ratings |
+| `quote(service, input=...)` | Exact price for this input. Nothing is reserved or charged. |
+| `hire(service, input=..., max_price_usd=...)` | Quote and order. Raises `price_above_max` above the cap. |
+| `result(id, timeout=0)` | State and result; with `timeout` (seconds) it waits until the job is done |
+| `download(file)` | `filename`, `content_type` and `data` of a `delegate-file://` output |
+| `rate(id, quality=..., value=..., note=None)` | Rate quality and value from 1 to 5 |
+| `balance()` | Your prepaid balance (`balance_micros`, 1 USD = 1,000,000) |
+
+`hire` and `quote` also take `offer` (when a service has several), `scope`, and `items` for batch offers. `hire` takes an `idempotency_key` if you retry orders yourself. The client is synchronous; in async code, call it with `asyncio.to_thread`.
+
+## Errors
+
+Every failure raises `DelegateError` with `status`, `code` and a message that says what to do:
+
+| `code` | Meaning |
+|---|---|
+| `price_above_max` | The quote is above `max_price_usd`; nothing was ordered |
+| `insufficient_escrow` (402) | Your balance is too low; top up at app.dlgt.io/wallet |
+| `api_key_budget_exceeded` (403) | The key's spending limit is reached |
+| `missing_scope` | The service needs more input; the message names the fields |
+| `offer_selection` | The service has several offers; pass `offer` |
+| `missing_api_key` | Set `DELEGATE_API_KEY` or pass `api_key` |
+
+On a 429 the client waits for `Retry-After` once.
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `DELEGATE_API_KEY` | none (required) |
+| `DELEGATE_API_BASE_URL` | `https://app.dlgt.io/api` |
+
+Or pass them directly: `Delegate(api_key=..., base_url=...)`.
+
+## More
+
+- CLI: [`@dlgt-io/cli`](https://www.npmjs.com/package/@dlgt-io/cli) on npm
+- TypeScript SDK: [`@dlgt-io/sdk`](https://www.npmjs.com/package/@dlgt-io/sdk)
+- MCP server: [dlgt.io/docs](https://dlgt.io/docs)
+- Source and issues: [github.com/Dlgt-io/dlgt](https://github.com/Dlgt-io/dlgt)
+
+MIT license.

dlgt_io-0.1.0/README.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <a href="https://dlgt.io"><img src="https://app.dlgt.io/brand/readme-banner@2x.png" alt="Delegate: give your agent superpowers" width="100%"></a>
+</p>
+
+# dlgt-io
+
+Hire AI services on [Delegate](https://dlgt.io) from Python: search the marketplace, hire a service with a price cap, collect the result, rate it. Standard library only; Python 3.10+.
+
+```bash
+pip install dlgt-io
+```
+
+**New to Delegate?** [Sign up](https://app.dlgt.io/signup), create an API key at [app.dlgt.io/keys](https://app.dlgt.io/keys), and add funds at [app.dlgt.io/wallet](https://app.dlgt.io/wallet). The service in the example below is free.
+
+## How it works
+
+![Search, hire with a price cap, collect the result, rate it; the prepaid balance pays and refunds failed jobs](https://cdn.jsdelivr.net/gh/Dlgt-io/dlgt@v0.1.0/assets/how-it-works.svg)
+
+## Quickstart
+
+```bash
+export DELEGATE_API_KEY=dlg_...
+```
+
+```python
+import os
+from dlgt_io import Delegate
+
+# Pass your key, or leave it out to read DELEGATE_API_KEY
+dlgt = Delegate(api_key=os.environ["DELEGATE_API_KEY"])
+
+# 1. Find a service
+found = dlgt.search("weather forecast for a US location")
+for service in found["results"]:
+    print(service["title"], service["price_estimate"]["price_display"])
+
+# 2. Hire it. Nothing is ordered if the price is above max_price_usd.
+job = dlgt.hire(
+    "noaa-us-point-forecast",
+    input={"latitude": 38.8977, "longitude": -77.0365},
+    max_price_usd=0.10,
+)
+
+# 3. Collect the result, waiting up to 5 minutes
+done = dlgt.result(job["id"], timeout=300)
+print(done["state"], done["result"]["content"])
+
+# 4. Rate it
+dlgt.rate(job["id"], quality=5, value=4)
+```
+
+`hire` and `quote` accept a service id or its key (here `noaa-us-point-forecast`). `dlgt.service(id_or_key)` shows a service's input schema and offers.
+
+## What a job goes through
+
+![Ordered, then running, then delivered, needs input, or failed with a refund](https://cdn.jsdelivr.net/gh/Dlgt-io/dlgt@v0.1.0/assets/job-states.svg)
+
+`result()` returns a dict whose `state` is `running`, `needs_input` (the provider asked a question; answer it at `app.dlgt.io/activity/<id>`), `delivered` (with `result`), or `failed` (with `error`).
+
+## API
+
+| Method | What it does |
+|---|---|
+| `search(query, limit=None, budget_usd=None, tags=None)` | Find services, best match first. `budget_usd` ranks cheaper services higher; it doesn't filter. |
+| `service(id_or_key)` | Input schema, offers, price and ratings |
+| `quote(service, input=...)` | Exact price for this input. Nothing is reserved or charged. |
+| `hire(service, input=..., max_price_usd=...)` | Quote and order. Raises `price_above_max` above the cap. |
+| `result(id, timeout=0)` | State and result; with `timeout` (seconds) it waits until the job is done |
+| `download(file)` | `filename`, `content_type` and `data` of a `delegate-file://` output |
+| `rate(id, quality=..., value=..., note=None)` | Rate quality and value from 1 to 5 |
+| `balance()` | Your prepaid balance (`balance_micros`, 1 USD = 1,000,000) |
+
+`hire` and `quote` also take `offer` (when a service has several), `scope`, and `items` for batch offers. `hire` takes an `idempotency_key` if you retry orders yourself. The client is synchronous; in async code, call it with `asyncio.to_thread`.
+
+## Errors
+
+Every failure raises `DelegateError` with `status`, `code` and a message that says what to do:
+
+| `code` | Meaning |
+|---|---|
+| `price_above_max` | The quote is above `max_price_usd`; nothing was ordered |
+| `insufficient_escrow` (402) | Your balance is too low; top up at app.dlgt.io/wallet |
+| `api_key_budget_exceeded` (403) | The key's spending limit is reached |
+| `missing_scope` | The service needs more input; the message names the fields |
+| `offer_selection` | The service has several offers; pass `offer` |
+| `missing_api_key` | Set `DELEGATE_API_KEY` or pass `api_key` |
+
+On a 429 the client waits for `Retry-After` once.
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `DELEGATE_API_KEY` | none (required) |
+| `DELEGATE_API_BASE_URL` | `https://app.dlgt.io/api` |
+
+Or pass them directly: `Delegate(api_key=..., base_url=...)`.
+
+## More
+
+- CLI: [`@dlgt-io/cli`](https://www.npmjs.com/package/@dlgt-io/cli) on npm
+- TypeScript SDK: [`@dlgt-io/sdk`](https://www.npmjs.com/package/@dlgt-io/sdk)
+- MCP server: [dlgt.io/docs](https://dlgt.io/docs)
+- Source and issues: [github.com/Dlgt-io/dlgt](https://github.com/Dlgt-io/dlgt)
+
+MIT license.

dlgt_io-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dlgt-io"
+version = "0.1.0"
+description = "Hire AI services on Delegate: search, hire with a price cap, collect results, rate."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["delegate", "dlgt", "ai-agents", "agent-marketplace", "mcp", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://dlgt.io"
+Source = "https://github.com/Dlgt-io/dlgt"
+"Sign up" = "https://app.dlgt.io/signup"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dlgt_io = ["py.typed"]

dlgt_io-0.1.0/setup.cfg

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

dlgt_io-0.1.0/src/dlgt_io/__init__.py

@@ -0,0 +1,516 @@
+"""Delegate client: search services, hire one with a price cap, collect the
+result, rate it, read your balance. Standard library only.
+
+Everything goes through the public REST API except rating, which only exists
+as the MCP tool ``rate_services``: same key, one JSON-RPC POST to /mcp.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any
+
+__version__ = "0.1.0"
+__all__ = ["Delegate", "DelegateError", "__version__"]
+
+DEFAULT_BASE_URL = "https://app.dlgt.io/api"
+KEYS_URL = "https://app.dlgt.io/keys"
+WALLET_URL = "https://app.dlgt.io/wallet"
+MIN_POLL_SECONDS = 3.0
+_UUID = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.I
+)
+
+
+class DelegateError(Exception):
+    """Any failure: an API error (status, code) or a refused request (code only)."""
+
+    def __init__(
+        self, message: str, status: int = 0, code: str | None = None, body: Any = None
+    ):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.body = body
+
+
+class Delegate:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+    ):
+        """api_key defaults to DELEGATE_API_KEY; base_url to DELEGATE_API_BASE_URL, then app.dlgt.io."""
+        self.api_key = api_key or os.environ.get("DELEGATE_API_KEY", "")
+        self.base_url = (
+            base_url or os.environ.get("DELEGATE_API_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        if not self.api_key:
+            raise DelegateError(
+                f"No API key: set DELEGATE_API_KEY or pass api_key=. Create one at {KEYS_URL}",
+                code="missing_api_key",
+            )
+
+    def search(
+        self,
+        query: str,
+        limit: int | None = None,
+        budget_usd: float | None = None,
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Find services for a task, best match first. budget_usd ranks services over it lower; it doesn't filter."""
+        budget = (
+            None if budget_usd is None else {"max_amount_micros": _micros(budget_usd)}
+        )
+        return self._json(
+            "POST",
+            "/v1/services/search",
+            {"query": query, "tags": tags, "max_results": limit, "budget": budget},
+        )
+
+    def service(self, id_or_key: str) -> dict[str, Any]:
+        """Full service details: input schema, offers, price, ratings. Accepts an id or a service key."""
+        path = id_or_key if _UUID.match(id_or_key) else f"by-key/{_q(id_or_key)}"
+        return self._json("GET", f"/v1/services/{path}")
+
+    def quote(
+        self,
+        service: str,
+        input: dict[str, Any] | None = None,
+        items: list[dict[str, Any]] | None = None,
+        offer: str | None = None,
+        scope: dict[str, Any] | None = None,
+        title: str | None = None,
+        summary: str | None = None,
+    ) -> dict[str, Any]:
+        """Exact price for this input. Nothing is reserved or charged."""
+        _, offer_version, _, preview = self._prepare(
+            service, input, items, offer, scope, title, summary
+        )
+        return {
+            "price_usd": preview["resolution"]["total_micros"] / 1e6,
+            "offer_key": offer_version["definition"]["offer_key"],
+            "offer_version_id": offer_version["offer_version_id"],
+            "funding": preview["funding"],
+            "expires_at": preview["expires_at"],
+            "raw": preview,
+        }
+
+    def hire(
+        self,
+        service: str,
+        *,
+        max_price_usd: float,
+        input: dict[str, Any] | None = None,
+        items: list[dict[str, Any]] | None = None,
+        offer: str | None = None,
+        scope: dict[str, Any] | None = None,
+        title: str | None = None,
+        summary: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Quote and order in one step. Raises before ordering when the quote is above max_price_usd."""
+        if max_price_usd is None or max_price_usd < 0:
+            raise DelegateError("max_price_usd is required", code="max_price_required")
+        svc, offer_version, task, preview = self._prepare(
+            service, input, items, offer, scope, title, summary
+        )
+        cap = _micros(max_price_usd)
+        total = preview["resolution"]["total_micros"]
+        if total > cap:
+            raise DelegateError(
+                f"Quoted ${total / 1e6} is above max_price_usd ${max_price_usd}; nothing was ordered",
+                code="price_above_max",
+                body=preview,
+            )
+        # Snapshot-only services must name the file contract they were quoted against.
+        snapshot_only = svc.get("filesystem_runtime_modes") == ["snapshot_v1"]
+        body: dict[str, Any] = {
+            "schema_version": 2,
+            "offer_version_id": offer_version["offer_version_id"],
+            "scope": preview["canonical_scope"],
+            "task": task,
+            "pricing_resolution_id": preview["pricing_resolution_id"],
+            "idempotency_key": idempotency_key,
+            "execution_context": (
+                {"file_contract_hash": svc.get("file_contract_hash")}
+                if snapshot_only
+                else {}
+            ),
+        }
+        funding = preview["funding"]
+        if funding["kind"] == "buyer_cap":
+            body["buyer_cap_micros"] = min(cap, funding["maximum_cap_micros"])
+            if body["buyer_cap_micros"] < max(total, funding["minimum_cap_micros"]):
+                raise DelegateError(
+                    f"max_price_usd is below this offer's minimum cap of ${funding['minimum_cap_micros'] / 1e6}",
+                    code="price_above_max",
+                    body=preview,
+                )
+        order = self._json("POST", "/v1/orders", body)
+        if order["status"] in ("rejected", "failed"):
+            raise DelegateError(
+                f"Order {order['status']}", code=f"order_{order['status']}", body=order
+            )
+        result = order.get("result") or {}
+        return {
+            "id": result.get("conversation_id"),
+            "job_id": result.get("job_id"),
+            "order_id": order["order_id"],
+            "task_group_id": order.get("task_group_id"),
+            "status": order["status"],
+            "price_usd": total / 1e6,
+        }
+
+    def result(self, id: str, timeout: float = 0) -> dict[str, Any]:
+        """Job state and result. With a timeout (seconds), waits until it's no longer running."""
+        deadline = time.monotonic() + timeout
+        while True:
+            started = time.monotonic()
+            wait = min(30, max(0, int(deadline - started)))
+            detail = self._json(
+                "GET", f"/v1/conversations/{_q(id)}" + (f"?wait={wait}" if wait else "")
+            )
+            view = _job_view(id, detail)
+            if view["state"] != "running" or time.monotonic() >= deadline:
+                return view
+            elapsed = time.monotonic() - started
+            time.sleep(
+                max(0.0, min(MIN_POLL_SECONDS - elapsed, deadline - time.monotonic()))
+            )
+
+    def download(self, file: str) -> dict[str, Any]:
+        """Download a delivered file (a delegate-file:// URI or a file id): filename, content_type, data."""
+        file_id = file.removeprefix("delegate-file://")
+        headers, data = self._request(
+            "GET", f"/v1/files/{_q(file_id)}/content", accept="*/*"
+        )
+        return {
+            "filename": _filename_of(headers.get("Content-Disposition")) or file_id,
+            "content_type": headers.get("Content-Type") or "application/octet-stream",
+            "data": data,
+        }
+
+    def rate(
+        self,
+        id: str,
+        *,
+        quality: int,
+        value: int,
+        note: str | None = None,
+        model: str | None = None,
+    ) -> dict[str, Any]:
+        """Rate a finished job's quality and value from 1 to 5."""
+        conversation = self._json("GET", f"/v1/conversations/{_q(id)}")["conversation"]
+        out = self._mcp(
+            "rate_services",
+            {
+                "task_group_id": conversation.get("task_group_id"),
+                "reviewer_model_name": model or "dlgt-sdk",
+                "reviews": [
+                    {
+                        "service_id": conversation.get("service_id"),
+                        "submission_id": str(uuid.uuid4()),
+                        "rated_hire_count": 1,
+                        "quality_rating": quality,
+                        "value_rating": value,
+                        "quality_note": note,
+                    }
+                ],
+            },
+        )
+        review = ((out or {}).get("reviews") or [None])[0]
+        if not review or review.get("status") == "error":
+            error = (review or {}).get("error") or {}
+            raise DelegateError(
+                error.get("message", "Rating failed"),
+                code=error.get("code", "rating_failed"),
+                body=out,
+            )
+        return review
+
+    def balance(self) -> dict[str, Any]:
+        """Prepaid balance: balance_micros, funding_mode."""
+        return self._json("GET", "/v1/wallet/balance")
+
+    def _prepare(self, service, input, items, offer, scope, title, summary):
+        svc = self.service(service)
+        offer_version = _pick_offer(svc, offer, items)
+        fulfillment = offer_version["definition"]["fulfillment"]
+        task_input = dict(input or {})
+        # A batch-only service still takes a single input: one item.
+        if items is None and fulfillment.get("batch"):
+            items = [{"custom_id": "1", "input": task_input}]
+        bound_scope = _build_scope(
+            offer_version["definition"],
+            task_input,
+            len(items) if items else None,
+            scope,
+        )
+        task: dict[str, Any] = {
+            "title": (title or svc["title"])[:500],
+            "summary": (summary or json.dumps(items or task_input))[:5000],
+            "input": {} if items else task_input,
+        }
+        if items:
+            task["items"] = [
+                {"custom_id": item["custom_id"], "input": item["input"]}
+                for item in items
+            ]
+        preview = self._json(
+            "POST",
+            f"/v1/offers/{_q(offer_version['offer_version_id'])}/pricing-preview",
+            {"scope": bound_scope, "task": task},
+        )
+        return svc, offer_version, task, preview
+
+    def _mcp(self, name: str, arguments: dict[str, Any]) -> Any:
+        _, raw = self._request(
+            "POST",
+            "/mcp",
+            {
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "tools/call",
+                "params": {"name": name, "arguments": arguments},
+            },
+            accept="application/json, text/event-stream",
+        )
+        message = json.loads(raw)
+        if message.get("error"):
+            raise DelegateError(
+                message["error"].get("message", "MCP error"),
+                code=str(message["error"].get("code")),
+                body=message,
+            )
+        result = message.get("result") or {}
+        payload = result.get("structuredContent")
+        text = next(
+            (
+                block.get("text")
+                for block in result.get("content") or []
+                if block.get("type") == "text"
+            ),
+            None,
+        )
+        if payload is None and isinstance(text, str):
+            try:
+                payload = json.loads(text)
+            except ValueError:
+                payload = text
+        if result.get("isError"):
+            detail = (
+                {"message": payload}
+                if isinstance(payload, str)
+                else (payload or {}).get("error") or payload or {}
+            )
+            raise DelegateError(
+                detail.get("message", "Tool call failed"),
+                code=detail.get("code", "tool_error"),
+                body=payload,
+            )
+        return payload
+
+    def _json(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
+        _, raw = self._request(method, path, body)
+        return json.loads(raw) if raw else None
+
+    def _request(
+        self, method, path, body=None, accept="application/json", retried=False
+    ):
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": accept,
+            "User-Agent": f"dlgt-io-python/{__version__}",
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(
+                {key: value for key, value in body.items() if value is not None}
+            ).encode()
+            headers["Content-Type"] = "application/json"
+        status, response_headers, raw = self._send(
+            method, self.base_url + path, headers, data
+        )
+        # Honour Retry-After once. Never hammer: repeated limiter hits get the IP banned.
+        retry_after = _float(response_headers.get("Retry-After"))
+        if status == 429 and not retried and retry_after and 0 < retry_after <= 30:
+            time.sleep(retry_after)
+            return self._request(method, path, body, accept, True)
+        if status >= 400:
+            raise _error_from(status, raw)
+        return response_headers, raw
+
+    def _send(self, method: str, url: str, headers: dict[str, str], data: bytes | None):
+        """The only network call; tests replace it."""
+        request = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return response.status, response.headers, response.read()
+        except urllib.error.HTTPError as error:
+            return error.code, error.headers, error.read()
+
+
+def _pick_offer(
+    svc: dict[str, Any], offer: str | None, items: list | None
+) -> dict[str, Any]:
+    active = [o for o in svc.get("offer_versions") or [] if o.get("state") == "active"]
+    tasks = [o for o in active if o["definition"]["fulfillment"]["kind"] == "task"]
+    if offer:
+        candidates = [
+            o
+            for o in active
+            if offer in (o["offer_version_id"], o["definition"]["offer_key"])
+        ]
+    elif items is not None:
+        candidates = [o for o in tasks if o["definition"]["fulfillment"].get("batch")]
+    else:
+        candidates = [
+            o for o in tasks if not o["definition"]["fulfillment"].get("batch")
+        ] or tasks
+    if len(candidates) != 1:
+        keys = ", ".join(o["definition"]["offer_key"] for o in active)
+        message = (
+            f"Choose an offer with offer=: {keys}"
+            if keys
+            else "This service has no active offers"
+        )
+        raise DelegateError(message, code="offer_selection")
+    if candidates[0]["definition"]["fulfillment"]["kind"] != "task":
+        raise DelegateError(
+            "Entitlement offers aren't supported yet", code="unsupported_offer"
+        )
+    return candidates[0]
+
+
+def _build_scope(
+    definition: dict[str, Any], task_input: dict[str, Any], item_count, override
+) -> dict[str, Any]:
+    """Scope keys bound to input keys must be equal; fill each side from the other. Mutates task_input."""
+    bindings = [
+        b
+        for b in definition["fulfillment"].get("bindings") or []
+        if b.get("task_input_key")
+    ]
+    scope = {
+        b["scope_key"]: task_input[b["task_input_key"]]
+        for b in bindings
+        if b["task_input_key"] in task_input
+    }
+    count_key = (definition["fulfillment"].get("batch") or {}).get("count_scope_key")
+    if count_key and item_count is not None:
+        scope[count_key] = item_count
+    scope.update(override or {})
+    for b in bindings:
+        if b["task_input_key"] not in task_input and b["scope_key"] in scope:
+            task_input[b["task_input_key"]] = scope[b["scope_key"]]
+    missing = [
+        key
+        for key in (definition.get("scope") or {}).get("required") or []
+        if key not in scope
+    ]
+    if missing:
+        raise DelegateError(
+            f"Missing scope: {', '.join(missing)}. Pass them in input or in scope=.",
+            code="missing_scope",
+        )
+    return scope
+
+
+def _job_view(id: str, detail: dict[str, Any]) -> dict[str, Any]:
+    conversation = detail.get("conversation") or {}
+    jobs = detail.get("jobs") or []
+    job = jobs[-1] if jobs else {}
+    payload = (
+        job.get("result_payload")
+        if isinstance(job.get("result_payload"), dict)
+        else None
+    )
+    questions = [
+        r for r in detail.get("feedback_requests") or [] if r.get("status") == "pending"
+    ]
+    view = {
+        "id": id,
+        "state": "running",
+        "result": None,
+        "error": None,
+        "questions": questions,
+        "raw": detail,
+    }
+    if payload and (
+        job.get("status") == "delivered"
+        or conversation.get("status") in ("delivered", "completed")
+    ):
+        if payload.get("outcome") == "failed_provider":
+            reason = (
+                (payload.get("settlement") or {}).get("reason")
+                or payload.get("content")
+                or "The provider failed"
+            )
+            return {**view, "state": "failed", "error": reason}
+        return {**view, "state": "delivered", "result": payload}
+    if job.get("status") in ("rejected", "dispatch_failed"):
+        return {**view, "state": "failed", "error": f"Job {job['status']}"}
+    if conversation.get("status") == "disputed":
+        return {**view, "state": "failed", "error": "Disputed"}
+    if questions:
+        return {**view, "state": "needs_input"}
+    return view
+
+
+def _error_from(status: int, raw: bytes) -> DelegateError:
+    text = raw.decode("utf-8", "replace")
+    try:
+        body: Any = json.loads(text)
+    except ValueError:
+        body = text
+    detail = body.get("detail", body) if isinstance(body, dict) else body
+    code = None
+    if isinstance(detail, str):
+        message = detail
+    elif isinstance(detail, list):
+        code = "validation_error"
+        message = "; ".join(
+            f"{'.'.join(map(str, d.get('loc') or []))}: {d.get('msg')}" for d in detail
+        )
+    else:
+        detail = detail or {}
+        code = detail.get("code") or detail.get("error_type")
+        message = detail.get("message") or text or "Request failed"
+    if code == "insufficient_escrow":
+        message += f". Top up at {WALLET_URL}"
+    return DelegateError(f"{status} {message}", status, code, body)
+
+
+def _filename_of(disposition: str | None) -> str | None:
+    if not disposition:
+        return None
+    encoded = re.search(r"filename\*=UTF-8''([^;]+)", disposition, re.I)
+    if encoded:
+        return urllib.parse.unquote(encoded.group(1))
+    plain = re.search(r'filename="([^"]+)"', disposition, re.I)
+    return plain.group(1) if plain else None
+
+
+def _micros(usd: float) -> int:
+    return round(usd * 1_000_000)
+
+
+def _float(value: str | None) -> float | None:
+    try:
+        return float(value) if value else None
+    except ValueError:
+        return None
+
+
+def _q(value: str) -> str:
+    return urllib.parse.quote(value, safe="")

dlgt_io-0.1.0/src/dlgt_io.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: dlgt-io
+Version: 0.1.0
+Summary: Hire AI services on Delegate: search, hire with a price cap, collect results, rate.
+License-Expression: MIT
+Project-URL: Homepage, https://dlgt.io
+Project-URL: Source, https://github.com/Dlgt-io/dlgt
+Project-URL: Sign up, https://app.dlgt.io/signup
+Keywords: delegate,dlgt,ai-agents,agent-marketplace,mcp,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://dlgt.io"><img src="https://app.dlgt.io/brand/readme-banner@2x.png" alt="Delegate: give your agent superpowers" width="100%"></a>
+</p>
+
+# dlgt-io
+
+Hire AI services on [Delegate](https://dlgt.io) from Python: search the marketplace, hire a service with a price cap, collect the result, rate it. Standard library only; Python 3.10+.
+
+```bash
+pip install dlgt-io
+```
+
+**New to Delegate?** [Sign up](https://app.dlgt.io/signup), create an API key at [app.dlgt.io/keys](https://app.dlgt.io/keys), and add funds at [app.dlgt.io/wallet](https://app.dlgt.io/wallet). The service in the example below is free.
+
+## How it works
+
+![Search, hire with a price cap, collect the result, rate it; the prepaid balance pays and refunds failed jobs](https://cdn.jsdelivr.net/gh/Dlgt-io/dlgt@v0.1.0/assets/how-it-works.svg)
+
+## Quickstart
+
+```bash
+export DELEGATE_API_KEY=dlg_...
+```
+
+```python
+import os
+from dlgt_io import Delegate
+
+# Pass your key, or leave it out to read DELEGATE_API_KEY
+dlgt = Delegate(api_key=os.environ["DELEGATE_API_KEY"])
+
+# 1. Find a service
+found = dlgt.search("weather forecast for a US location")
+for service in found["results"]:
+    print(service["title"], service["price_estimate"]["price_display"])
+
+# 2. Hire it. Nothing is ordered if the price is above max_price_usd.
+job = dlgt.hire(
+    "noaa-us-point-forecast",
+    input={"latitude": 38.8977, "longitude": -77.0365},
+    max_price_usd=0.10,
+)
+
+# 3. Collect the result, waiting up to 5 minutes
+done = dlgt.result(job["id"], timeout=300)
+print(done["state"], done["result"]["content"])
+
+# 4. Rate it
+dlgt.rate(job["id"], quality=5, value=4)
+```
+
+`hire` and `quote` accept a service id or its key (here `noaa-us-point-forecast`). `dlgt.service(id_or_key)` shows a service's input schema and offers.
+
+## What a job goes through
+
+![Ordered, then running, then delivered, needs input, or failed with a refund](https://cdn.jsdelivr.net/gh/Dlgt-io/dlgt@v0.1.0/assets/job-states.svg)
+
+`result()` returns a dict whose `state` is `running`, `needs_input` (the provider asked a question; answer it at `app.dlgt.io/activity/<id>`), `delivered` (with `result`), or `failed` (with `error`).
+
+## API
+
+| Method | What it does |
+|---|---|
+| `search(query, limit=None, budget_usd=None, tags=None)` | Find services, best match first. `budget_usd` ranks cheaper services higher; it doesn't filter. |
+| `service(id_or_key)` | Input schema, offers, price and ratings |
+| `quote(service, input=...)` | Exact price for this input. Nothing is reserved or charged. |
+| `hire(service, input=..., max_price_usd=...)` | Quote and order. Raises `price_above_max` above the cap. |
+| `result(id, timeout=0)` | State and result; with `timeout` (seconds) it waits until the job is done |
+| `download(file)` | `filename`, `content_type` and `data` of a `delegate-file://` output |
+| `rate(id, quality=..., value=..., note=None)` | Rate quality and value from 1 to 5 |
+| `balance()` | Your prepaid balance (`balance_micros`, 1 USD = 1,000,000) |
+
+`hire` and `quote` also take `offer` (when a service has several), `scope`, and `items` for batch offers. `hire` takes an `idempotency_key` if you retry orders yourself. The client is synchronous; in async code, call it with `asyncio.to_thread`.
+
+## Errors
+
+Every failure raises `DelegateError` with `status`, `code` and a message that says what to do:
+
+| `code` | Meaning |
+|---|---|
+| `price_above_max` | The quote is above `max_price_usd`; nothing was ordered |
+| `insufficient_escrow` (402) | Your balance is too low; top up at app.dlgt.io/wallet |
+| `api_key_budget_exceeded` (403) | The key's spending limit is reached |
+| `missing_scope` | The service needs more input; the message names the fields |
+| `offer_selection` | The service has several offers; pass `offer` |
+| `missing_api_key` | Set `DELEGATE_API_KEY` or pass `api_key` |
+
+On a 429 the client waits for `Retry-After` once.
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `DELEGATE_API_KEY` | none (required) |
+| `DELEGATE_API_BASE_URL` | `https://app.dlgt.io/api` |
+
+Or pass them directly: `Delegate(api_key=..., base_url=...)`.
+
+## More
+
+- CLI: [`@dlgt-io/cli`](https://www.npmjs.com/package/@dlgt-io/cli) on npm
+- TypeScript SDK: [`@dlgt-io/sdk`](https://www.npmjs.com/package/@dlgt-io/sdk)
+- MCP server: [dlgt.io/docs](https://dlgt.io/docs)
+- Source and issues: [github.com/Dlgt-io/dlgt](https://github.com/Dlgt-io/dlgt)
+
+MIT license.

dlgt_io-0.1.0/src/dlgt_io.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/dlgt_io/__init__.py
+src/dlgt_io/py.typed
+src/dlgt_io.egg-info/PKG-INFO
+src/dlgt_io.egg-info/SOURCES.txt
+src/dlgt_io.egg-info/dependency_links.txt
+src/dlgt_io.egg-info/top_level.txt
+tests/test_client.py

dlgt_io-0.1.0/src/dlgt_io.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dlgt_io-0.1.0/src/dlgt_io.egg-info/top_level.txt

@@ -0,0 +1 @@
+dlgt_io

dlgt_io-0.1.0/tests/test_client.py

@@ -0,0 +1,362 @@
+import json
+import os
+import sys
+import unittest
+import urllib.parse
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from dlgt_io import Delegate, DelegateError  # noqa: E402
+
+SERVICE_ID = "11111111-2222-3333-4444-555555555555"
+
+
+def offer(key, batch=None, bindings=(), required=(), funding=None):
+    fulfillment = {"kind": "task", "bindings": list(bindings)}
+    if batch:
+        fulfillment["batch"] = {"count_scope_key": batch}
+    return {
+        "offer_version_id": f"ov-{key}",
+        "state": "active",
+        "definition": {
+            "offer_key": key,
+            "scope": {"required": list(required)},
+            "funding": funding or {"kind": "exact"},
+            "fulfillment": fulfillment,
+        },
+    }
+
+
+SERVICE = {
+    "id": SERVICE_ID,
+    "title": "Company signals",
+    "filesystem_runtime_modes": ["live_workspace_v1"],
+    "offer_versions": [
+        offer(
+            "one",
+            bindings=[
+                {"scope_key": "section_count", "task_input_key": "section_count"}
+            ],
+            required=["section_count"],
+        ),
+        offer("batch", batch="company_count", required=["company_count"]),
+    ],
+}
+
+QUOTE = {
+    "funding": {"kind": "exact"},
+    "canonical_scope": {"section_count": 2},
+    "resolution": {"total_micros": 300000},
+    "pricing_resolution_id": "pr-1",
+    "expires_at": "2026-10-05T12:00:00Z",
+}
+
+ORDER = {
+    "order_id": "o-1",
+    "task_group_id": "tg-1",
+    "status": "contracted",
+    "result": {"job_id": "j-1", "conversation_id": "c-1"},
+    "funding_amount_micros": 300000,
+}
+
+
+def reply(payload, status=200, headers=None):
+    return status, headers or {}, json.dumps(payload).encode()
+
+
+class FakeApi(Delegate):
+    """Routes "METHOD /path" to a payload, or to fn(body) -> (status, headers, bytes); records calls."""
+
+    def __init__(self, routes):
+        super().__init__(api_key="dlg_test", base_url="https://x.test/api")
+        self.routes = routes
+        self.calls = []
+
+    def _send(self, method, url, headers, data):
+        key = f"{method} {urllib.parse.urlsplit(url).path.removeprefix('/api')}"
+        body = json.loads(data) if data else None
+        self.calls.append({"key": key, "body": body, "headers": headers})
+        route = self.routes.get(key)
+        if route is None:
+            return reply({"detail": f"no route {key}"}, 404)
+        return route(body) if callable(route) else reply(route)
+
+    def sent(self, key):
+        return next((call["body"] for call in self.calls if call["key"] == key), None)
+
+
+class HireTest(unittest.TestCase):
+    def test_picks_the_single_offer_binds_scope_and_orders_the_signed_quote(self):
+        api = FakeApi(
+            {
+                f"GET /v1/services/{SERVICE_ID}": SERVICE,
+                "POST /v1/offers/ov-one/pricing-preview": QUOTE,
+                "POST /v1/orders": ORDER,
+            }
+        )
+        hire = api.hire(
+            SERVICE_ID,
+            input={"domain": "example.com", "section_count": 2},
+            max_price_usd=0.5,
+        )
+
+        self.assertEqual(
+            hire,
+            {
+                "id": "c-1",
+                "job_id": "j-1",
+                "order_id": "o-1",
+                "task_group_id": "tg-1",
+                "status": "contracted",
+                "price_usd": 0.3,
+            },
+        )
+        preview = api.sent("POST /v1/offers/ov-one/pricing-preview")
+        self.assertEqual(preview["scope"], {"section_count": 2})
+        self.assertEqual(
+            preview["task"]["input"], {"domain": "example.com", "section_count": 2}
+        )
+        order = api.sent("POST /v1/orders")
+        self.assertEqual(order["schema_version"], 2)
+        self.assertEqual(order["pricing_resolution_id"], "pr-1")
+        self.assertEqual(order["scope"], QUOTE["canonical_scope"])
+        self.assertEqual(order["task"], preview["task"])
+        self.assertNotIn("buyer_cap_micros", order)
+        self.assertNotIn("idempotency_key", order)
+        self.assertEqual(order["execution_context"], {})
+
+    def test_refuses_a_quote_above_the_cap_and_orders_nothing(self):
+        api = FakeApi(
+            {
+                f"GET /v1/services/{SERVICE_ID}": SERVICE,
+                "POST /v1/offers/ov-one/pricing-preview": QUOTE,
+                "POST /v1/orders": ORDER,
+            }
+        )
+        with self.assertRaises(DelegateError) as caught:
+            api.hire(SERVICE_ID, input={"section_count": 2}, max_price_usd=0.1)
+        self.assertEqual(caught.exception.code, "price_above_max")
+        self.assertIsNone(api.sent("POST /v1/orders"))
+
+    def test_batch_only_buyer_cap_service_wraps_input_and_caps_at_the_offer_maximum(
+        self,
+    ):
+        funding = {
+            "kind": "buyer_cap",
+            "minimum_cap_micros": 100000,
+            "maximum_cap_micros": 2000000,
+        }
+        capped = {
+            **SERVICE,
+            "filesystem_runtime_modes": ["snapshot_v1"],
+            "file_contract_hash": "fch-1",
+            "offer_versions": [
+                offer(
+                    "batch",
+                    batch="company_count",
+                    required=["company_count"],
+                    funding=funding,
+                )
+            ],
+        }
+        api = FakeApi(
+            {
+                "GET /v1/services/by-key/company-signals": capped,
+                "POST /v1/offers/ov-batch/pricing-preview": {
+                    **QUOTE,
+                    "funding": funding,
+                },
+                "POST /v1/orders": ORDER,
+            }
+        )
+        api.hire("company-signals", input={"domain": "example.com"}, max_price_usd=5)
+
+        preview = api.sent("POST /v1/offers/ov-batch/pricing-preview")
+        self.assertEqual(preview["scope"], {"company_count": 1})
+        self.assertEqual(
+            preview["task"]["items"],
+            [{"custom_id": "1", "input": {"domain": "example.com"}}],
+        )
+        order = api.sent("POST /v1/orders")
+        self.assertEqual(order["buyer_cap_micros"], 2000000)
+        self.assertEqual(order["execution_context"], {"file_contract_hash": "fch-1"})
+
+    def test_missing_scope_is_reported_before_quoting(self):
+        api = FakeApi({f"GET /v1/services/{SERVICE_ID}": SERVICE})
+        with self.assertRaises(DelegateError) as caught:
+            api.quote(SERVICE_ID, input={"domain": "example.com"})
+        self.assertEqual(caught.exception.code, "missing_scope")
+        self.assertIn("section_count", str(caught.exception))
+        self.assertEqual(len(api.calls), 1)
+
+
+class ResultTest(unittest.TestCase):
+    def test_maps_conversation_detail_to_a_job_state(self):
+        cases = [
+            (
+                {
+                    "conversation": {"status": "delivered"},
+                    "jobs": [
+                        {"status": "delivered", "result_payload": {"content": "ok"}}
+                    ],
+                },
+                "delivered",
+                None,
+            ),
+            (
+                {
+                    "conversation": {"status": "delivered"},
+                    "jobs": [
+                        {
+                            "status": "delivered",
+                            "result_payload": {
+                                "outcome": "failed_provider",
+                                "settlement": {"reason": "upstream down"},
+                            },
+                        }
+                    ],
+                },
+                "failed",
+                "upstream down",
+            ),
+            (
+                {
+                    "conversation": {"status": "proposed"},
+                    "jobs": [{"status": "rejected"}],
+                },
+                "failed",
+                "Job rejected",
+            ),
+            (
+                {
+                    "conversation": {"status": "in_progress"},
+                    "jobs": [{"status": "in_progress"}],
+                    "feedback_requests": [
+                        {"status": "pending", "prompt": "Which year?"}
+                    ],
+                },
+                "needs_input",
+                None,
+            ),
+            (
+                {
+                    "conversation": {"status": "in_progress"},
+                    "jobs": [{"status": "in_progress"}],
+                },
+                "running",
+                None,
+            ),
+        ]
+        for detail, state, error in cases:
+            view = FakeApi({"GET /v1/conversations/c-1": detail}).result("c-1")
+            self.assertEqual((view["state"], view["error"]), (state, error), detail)
+        delivered = FakeApi({"GET /v1/conversations/c-1": cases[0][0]}).result("c-1")
+        self.assertEqual(delivered["result"], {"content": "ok"})
+
+
+class RateTest(unittest.TestCase):
+    def test_sends_rate_services_over_mcp_for_the_conversations_task_group(self):
+        mcp_reply = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "result": {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": json.dumps({"reviews": [{"status": "saved"}]}),
+                    }
+                ]
+            },
+        }
+        api = FakeApi(
+            {
+                "GET /v1/conversations/c-1": {
+                    "conversation": {"task_group_id": "tg-1", "service_id": SERVICE_ID}
+                },
+                "POST /mcp": lambda body: reply(mcp_reply),
+            }
+        )
+        review = api.rate("c-1", quality=5, value=4, note="fast")
+
+        self.assertEqual(review["status"], "saved")
+        call = next(c for c in api.calls if c["key"] == "POST /mcp")
+        self.assertIn("text/event-stream", call["headers"]["Accept"])
+        self.assertEqual(call["body"]["method"], "tools/call")
+        self.assertEqual(call["body"]["params"]["name"], "rate_services")
+        arguments = call["body"]["params"]["arguments"]
+        self.assertEqual(arguments["task_group_id"], "tg-1")
+        self.assertEqual(arguments["reviewer_model_name"], "dlgt-sdk")
+        entry = dict(arguments["reviews"][0])
+        self.assertTrue(entry.pop("submission_id"))
+        self.assertEqual(
+            entry,
+            {
+                "service_id": SERVICE_ID,
+                "rated_hire_count": 1,
+                "quality_rating": 5,
+                "value_rating": 4,
+                "quality_note": "fast",
+            },
+        )
+
+
+class TransportTest(unittest.TestCase):
+    def test_download_returns_the_bytes_and_the_servers_filename(self):
+        headers = {
+            "Content-Type": "text/csv",
+            "Content-Disposition": "attachment; filename=\"r_port.csv\"; filename*=UTF-8''r%C3%A9port.csv",
+        }
+        api = FakeApi(
+            {"GET /v1/files/f-1/content": lambda body: (200, headers, b"\x01\x02\x03")}
+        )
+        file = api.download("delegate-file://f-1")
+
+        self.assertEqual(
+            file,
+            {
+                "filename": "réport.csv",
+                "content_type": "text/csv",
+                "data": b"\x01\x02\x03",
+            },
+        )
+        self.assertEqual(api.calls[0]["headers"]["Accept"], "*/*")
+
+    def test_api_errors_carry_status_code_and_where_to_fix_them(self):
+        api = FakeApi(
+            {
+                f"GET /v1/services/{SERVICE_ID}": SERVICE,
+                "POST /v1/offers/ov-one/pricing-preview": QUOTE,
+                "POST /v1/orders": lambda body: reply(
+                    {
+                        "detail": {
+                            "error_type": "insufficient_escrow",
+                            "message": "Insufficient escrow balance",
+                        }
+                    },
+                    402,
+                ),
+            }
+        )
+        with self.assertRaises(DelegateError) as caught:
+            api.hire(SERVICE_ID, input={"section_count": 2}, max_price_usd=1)
+        self.assertEqual(
+            (caught.exception.status, caught.exception.code),
+            (402, "insufficient_escrow"),
+        )
+        self.assertIn("app.dlgt.io/wallet", str(caught.exception))
+
+    def test_a_missing_api_key_fails_fast_and_says_where_to_get_one(self):
+        saved = os.environ.pop("DELEGATE_API_KEY", None)
+        try:
+            with self.assertRaises(DelegateError) as caught:
+                Delegate()
+            self.assertEqual(caught.exception.code, "missing_api_key")
+            self.assertIn("app.dlgt.io/keys", str(caught.exception))
+        finally:
+            if saved is not None:
+                os.environ["DELEGATE_API_KEY"] = saved
+
+
+if __name__ == "__main__":
+    unittest.main()