oneshot-python 0.37.0__tar.gz → 0.38.0__tar.gz

{oneshot_python-0.37.0 → oneshot_python-0.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.37.0
+Version: 0.38.0
 Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 48 tools
 License-Expression: MIT
 Requires-Python: >=3.10

{oneshot_python-0.37.0 → oneshot_python-0.38.0}/README.md

@@ -315,6 +315,16 @@ client.hunts.leaderboard()    # public predictor leaderboard
 
 Async variants prefix the method with `a` (`alist`, `astatus`, `apredict`, `acapture`, `acollection`, `aleaderboard`). `list`/`status`/`collection`/`leaderboard` are free reads and work for both wallet and access-token sessions. `predict`/`capture` debit a stake and require Soul Hunt's wallet-signed write proof, which an access-token (credits-only) session cannot produce — those two raise `ValidationError` locally rather than reaching the network. The client never forwards the OneShot bearer token to Soul Hunt; only the wallet address and, for wallet sessions, the signed `x-agent-proof` go out.
 
+## Declared routes and inbox methods (#1273)
+
+Every route in the API registry states an agent tool. The ones without a typed method are in the lookup
+manifest and reached with `call_lookup(name, **fields)`, for example `call_lookup("company_filings", cik="320193")`
+(`acall_lookup` for async): a free route is a signed
+call, a paid one goes through `call_tool` and its quote. LangChain and GAME build their tools from the same
+manifest. The inbox, SMS inbox and notification routes also have methods: `inbox`, `inbox_get`, `sms_inbox`,
+`sms_inbox_get`, `notifications`, `mark_notification_read`, `mark_all_notifications_read` (each with an `a`
+async form).
+
 ## Requirements
 
 - Python 3.10+
@@ -324,7 +334,7 @@ Async variants prefix the method with `a` (`alist`, `astatus`, `apredict`, `acap
 ## Links
 
 - [Documentation](https://docs.oneshotagent.com/sdk/installation#install-via-pip-python)
-- [LangChain integration](https://pypi.org/project/langchain-oneshot/): 48 tools as LangChain BaseTool
+- [LangChain integration](https://pypi.org/project/langchain-oneshot/): 48 tools plus the lookup tools as LangChain BaseTool
 - [GAME plugin](https://pypi.org/project/game-plugin-oneshot/): Virtuals Protocol integration
 - [TypeScript SDK](https://www.npmjs.com/package/@oneshot-agent/sdk)
 - [MCP Server](https://www.npmjs.com/package/@oneshot-agent/mcp-server)

{oneshot_python-0.37.0 → oneshot_python-0.38.0}/oneshot/__init__.py

@@ -39,9 +39,11 @@ from oneshot._types import (
     DomainPoolStatusResult,
 )
 from oneshot.client import OneShotClient
+from oneshot.lookup import lookup_tools
 from oneshot.x402 import sign_payment_authorization
 
 __all__ = [
+    "lookup_tools",
     "PhysicalMail", "PostalAddress", "MailQuote", "MailOrder",
     "OneShotClient",
     "OneShotError",

{oneshot_python-0.37.0 → oneshot_python-0.38.0}/oneshot/_types.py

@@ -127,6 +127,7 @@ class ComputeCancelResult(TypedDict, total=False):
     goal_id: str
     status: str
     remaining_budget: str
+    message: str
 
 
 class ComputeTaskResponseResult(TypedDict, total=False):

{oneshot_python-0.37.0 → oneshot_python-0.38.0}/oneshot/client.py

@@ -44,6 +44,7 @@ from oneshot._types import (
     DomainPoolListResult,
     DomainPoolStatusResult,
 )
+from oneshot.lookup import PAID_PRICING, find_lookup_tool, lookup_query, lookup_request
 from oneshot.x402 import (
     build_zero_cost_authorization,
     encode_payment_header,
@@ -59,7 +60,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.37.0"
+    SDK_VERSION = "0.38.0"
 
 _BASE_URL = "https://win.oneshotagent.com"
 _HUNT_BASE_URL = "https://api.soulhunt.ai"
@@ -74,6 +75,7 @@ _USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 _POLL_BACKOFF = (0.3, 0.6, 1.0, 2.0)  # seconds
 _POLL_RETRY_BASE = 2.0  # seconds, transient-error retry backoff base
 _MAX_POLL_RETRIES = 3
+_BUILD_TRANSPORT_KWARGS = ("max_cost", "timeout_sec", "wait", "approval_id", "idempotency_key")
 
 
 def _build_email_payload(
@@ -159,6 +161,24 @@ def _parse_policy_rejection(resp: Any) -> Optional[OneShotError]:
     return None
 
 
+def _parse_invalid_proof(resp: Any) -> Optional[tuple[str, str]]:
+    """``(reason, message)`` when ``resp`` is the API's 401 ``invalid_proof`` refusal (#1437), else None."""
+    if resp.status_code != 401:
+        return None
+    try:
+        data = resp.json()
+    except Exception:  # noqa: BLE001 - non-JSON body
+        return None
+    if not isinstance(data, dict) or data.get("error") != "invalid_proof":
+        return None
+    reason = data.get("reason")
+    message = data.get("message")
+    return (
+        reason if isinstance(reason, str) else "invalid",
+        message if isinstance(message, str) else "The agent proof could not be verified.",
+    )
+
+
 def _parse_budget_rejection(resp: Any) -> Optional[BudgetExceededError]:
     """Map a 403 ``budget_exceeded`` body onto :class:`BudgetExceededError`.
 
@@ -666,6 +686,29 @@ class OneShotClient:
         if self.debug:
             print(f"[OneShot] {msg}")
 
+    async def _post_proved(self, client: httpx.AsyncClient, url: str, build_headers: Any, payload: dict[str, Any]) -> Any:
+        """POST a leg that proves the wallet. ``build_headers`` returns the headers
+        with a freshly signed proof each time it is called.
+
+        The API refuses a request whose proof it rejected, saying why (#1437). A
+        proof outside its window or sent twice is cured by signing a new one, so
+        the leg is sent again once. Any other reason, or a second refusal, is
+        raised with the reason. Nothing is paid in answer to this refusal.
+        """
+        resp = await client.post(url, headers=build_headers(), json=payload)
+        refusal = _parse_invalid_proof(resp)
+        if refusal is None:
+            return resp
+        reason, message = refusal
+        if reason in ("expired", "already_used"):
+            self._log(f"Wallet proof refused ({reason}); signing a new proof and retrying once")
+            resp = await client.post(url, headers=build_headers(), json=payload)
+            refusal = _parse_invalid_proof(resp)
+            if refusal is None:
+                return resp
+            reason, message = refusal
+        raise OneShotError(f"The API refused the wallet proof ({reason}): {message}")
+
     async def aensure_budgets_synced(self) -> None:
         """Push ``budgets`` / ``alert_email`` to the server once (async).
 
@@ -774,6 +817,44 @@ class OneShotClient:
             )
         )
 
+    def call_lookup(self, name: str, /, **params: Any) -> Any:
+        """Call a lookup tool by its manifest name, e.g. ``call_lookup("company_filings", cik="320193")``.
+
+        The tool's name is positional only, so a tool whose own input is called
+        ``name`` can be given it: ``call_lookup("company_legal_identifier", name="Apple Inc.")``.
+
+        Sends the params through :meth:`call_tool`. Params that are ``None`` are
+        left out. An unknown name raises ``ValidationError``; see
+        :func:`oneshot.lookup.lookup_tools` for the names.
+        """
+        entry = find_lookup_tool(name)
+        method, pricing, path, payload = lookup_request(entry, params)
+        if pricing in PAID_PRICING:
+            return self.call_tool(path, payload)
+        return asyncio.get_event_loop().run_until_complete(self._acall_free_lookup(method, path, payload))
+
+    async def acall_lookup(self, name: str, /, **params: Any) -> Any:
+        """Async form of :meth:`call_lookup`, sent through :meth:`acall_tool`."""
+        entry = find_lookup_tool(name)
+        method, pricing, path, payload = lookup_request(entry, params)
+        if pricing in PAID_PRICING:
+            return await self.acall_tool(path, payload)
+        return await self._acall_free_lookup(method, path, payload)
+
+    async def _acall_free_lookup(self, method: str, path: str, payload: dict[str, Any]) -> Any:
+        """A route with no payment of its own (a goal read or control, an inbox, a notification, a number or
+        account setting): a GET sends the params as the query, the other methods are write-scoped signed calls;
+        the ``{"success", "data"}`` envelope is stripped as the compute methods do."""
+        if method == "GET":
+            return self._unwrap_data(await self.acall_free_get(path, lookup_query(payload) or None))
+        if method == "PATCH":
+            return self._unwrap_data(await self.acall_free_patch(path, payload, scope="write"))
+        if method == "PUT":
+            return self._unwrap_data(await self.acall_free_put(path, payload))
+        if method == "DELETE":
+            return self._unwrap_data(await self.acall_free_delete(path, scope="write"))
+        return self._unwrap_data(await self.acall_free_post(path, payload, scope="write"))
+
     def wait_for_result(
         self,
         request_id: str,
@@ -870,11 +951,16 @@ class OneShotClient:
             # before they ever get to the 402 dance unless x-quote-id rides
             # on this very first attempt, so an already-obtained quote_id
             # must be sent from the start, not just on the paid retry.
-            initial_headers = self._with_approval(self._headers(max_cost=max_cost, idempotency_key=idempotency_key), approval_id)
-            self._prove_wallet(initial_headers, endpoint)
-            if quote_id:
-                initial_headers["x-quote-id"] = quote_id
-            resp = await client.post(url, headers=initial_headers, json=payload)
+            initial_headers_base = self._with_approval(self._headers(max_cost=max_cost, idempotency_key=idempotency_key), approval_id)
+
+            def _initial_headers() -> dict[str, str]:
+                headers = dict(initial_headers_base)
+                self._prove_wallet(headers, endpoint)
+                if quote_id:
+                    headers["x-quote-id"] = quote_id
+                return headers
+
+            resp = await self._post_proved(client, url, _initial_headers, payload)
 
             # The spend-budget gate rejects at quote time (403) so nothing is
             # signed; surface it as the typed error.
@@ -1002,16 +1088,21 @@ class OneShotClient:
                     resource=parsed_req.get("resource"),
                     extensions=parsed_req.get("extensions"),
                 )
-                headers = {
+                zero_cost_base = {
                     **self._with_approval(self._headers(max_cost=max_cost, idempotency_key=idempotency_key), approval_id),
                     "payment-signature": encode_payment_header(auth),
                 }
-                # The zero-cost authorization is an unsigned stub, so this leg
-                # still has to prove the wallet for the credits to be spent.
-                self._prove_wallet(headers, endpoint)
-                if quote_id:
-                    headers["x-quote-id"] = quote_id
-                resp2 = await client.post(url, headers=headers, json=payload)
+
+                def _zero_cost_headers() -> dict[str, str]:
+                    # The zero-cost authorization is an unsigned stub, so this leg
+                    # still has to prove the wallet for the credits to be spent.
+                    headers = dict(zero_cost_base)
+                    self._prove_wallet(headers, endpoint)
+                    if quote_id:
+                        headers["x-quote-id"] = quote_id
+                    return headers
+
+                resp2 = await self._post_proved(client, url, _zero_cost_headers, payload)
             else:
                 auth = sign_payment_authorization(
                     private_key=self._private_key,
@@ -1429,7 +1520,12 @@ class OneShotClient:
         return self._unwrap_data(await self.acall_free_get(f"/v1/compute/{goal_id}/budget"))
 
     def cancel_compute_goal(self, goal_id: str, reason: Optional[str] = None) -> Any:
-        """Cancel a goal; remaining budget is credited. Blocking."""
+        """Cancel a goal; remaining budget is credited. Blocking.
+
+        When reservations are still in flight the server answers 202 and the
+        refund is deferred: the result then has ``status == "pending_settlement"``
+        (no exception is raised).
+        """
         return asyncio.get_event_loop().run_until_complete(
             self.acancel_compute_goal(goal_id, reason)
         )
@@ -1437,11 +1533,17 @@ class OneShotClient:
     async def acancel_compute_goal(
         self, goal_id: str, reason: Optional[str] = None
     ) -> Any:
-        """Cancel a goal; remaining budget is credited. Async."""
+        """Cancel a goal; remaining budget is credited. Async.
+
+        A 202 ``pending_settlement`` answer is returned as a result, not raised.
+        """
         payload: dict[str, Any] = {"reason": reason} if reason is not None else {}
-        return self._unwrap_data(
+        result = self._unwrap_data(
             await self.acall_free_post(f"/v1/compute/{goal_id}/cancel", payload, scope="write")
         )
+        if isinstance(result, dict) and result.get("status") == "pending_settlement":
+            result = {"goal_id": goal_id, **{k: v for k, v in result.items() if k != "success"}}
+        return result
 
     def respond_to_compute_task(
         self,
@@ -1510,7 +1612,11 @@ class OneShotClient:
         )
 
     async def afund_compute_goal(self, goal_id: str, amount: float) -> Any:
-        """Top up budget on a recurring goal. Quote+pay (x402) via `acall_tool`."""
+        """Top up budget on a recurring goal, or on any goal that ended with
+        ``end_reason == "budget_exhausted"`` (it is set back to ``active`` and woken, keeping
+        its tasks and workspace). Other endings and passed deadlines are refused; a refund
+        still settling answers a retryable ``refund_pending`` (409). Quote+pay (x402) via
+        `acall_tool`."""
         if not amount or amount <= 0:
             raise ValidationError("amount must be a positive number", "amount")
         return await self.acall_tool(
@@ -1999,29 +2105,29 @@ class OneShotClient:
         """Enrich a company from domain, name, LinkedIn URL, or ticker. Async."""
         return await self.acall_tool("/v1/tools/enrich/company", kwargs)
 
-    def local_search(self, **kwargs: Any) -> Any:
+    def business_find(self, **kwargs: Any) -> Any:
         """Discover local businesses (restaurants, contractors, practices) by category/keywords x location. Blocking."""
-        return self.call_tool("/v1/tools/local/search", kwargs)
+        return self.call_tool("/v1/tools/find/business", kwargs)
 
-    async def alocal_search(self, **kwargs: Any) -> Any:
+    async def abusiness_find(self, **kwargs: Any) -> Any:
         """Discover local businesses (restaurants, contractors, practices) by category/keywords x location. Async."""
-        return await self.acall_tool("/v1/tools/local/search", kwargs)
+        return await self.acall_tool("/v1/tools/find/business", kwargs)
 
-    def local_resolve(self, name: str, **kwargs: Any) -> Any:
+    def business_resolve(self, name: str, **kwargs: Any) -> Any:
         """Resolve a business name + one locating field (address/city/postal_code/phone) to its domain, phone, status. Blocking."""
-        return self.call_tool("/v1/tools/local/resolve", {"name": name, **kwargs})
+        return self.call_tool("/v1/tools/resolve/business", {"name": name, **kwargs})
 
-    async def alocal_resolve(self, name: str, **kwargs: Any) -> Any:
+    async def abusiness_resolve(self, name: str, **kwargs: Any) -> Any:
         """Resolve a business name + one locating field (address/city/postal_code/phone) to its domain, phone, status. Async."""
-        return await self.acall_tool("/v1/tools/local/resolve", {"name": name, **kwargs})
+        return await self.acall_tool("/v1/tools/resolve/business", {"name": name, **kwargs})
 
-    def gov_solicitations(self, naics: list[str], **kwargs: Any) -> Any:
+    def record_solicitations_find(self, naics: list[str], **kwargs: Any) -> Any:
         """Federal Sources Sought / Presolicitation notices (SAM.gov) by NAICS code with the contracting officer's contact. Result carries `data_as_of` (snapshot behind the rows). Blocking."""
-        return self.call_tool("/v1/tools/gov/solicitations", {"naics": naics, **kwargs})
+        return self.call_tool("/v1/tools/find/record-solicitations", {"naics": naics, **kwargs})
 
-    async def agov_solicitations(self, naics: list[str], **kwargs: Any) -> Any:
+    async def arecord_solicitations_find(self, naics: list[str], **kwargs: Any) -> Any:
         """Federal Sources Sought / Presolicitation notices (SAM.gov) by NAICS code with the contracting officer's contact. Result carries `data_as_of` (snapshot behind the rows). Async."""
-        return await self.acall_tool("/v1/tools/gov/solicitations", {"naics": naics, **kwargs})
+        return await self.acall_tool("/v1/tools/find/record-solicitations", {"naics": naics, **kwargs})
 
     def find_email(self, company_domain: str, *, full_name: Optional[str] = None, first_name: Optional[str] = None, last_name: Optional[str] = None, **kwargs: Any) -> Any:
         """Find a person's email address. Blocking."""
@@ -2127,6 +2233,16 @@ class OneShotClient:
         """Build a website. Async."""
         return await self.acall_tool("/v1/tools/build", {"product": product, **kwargs})
 
+    def update_build(self, build_id: str, changes: str, **kwargs: Any) -> Any:
+        """Apply natural-language changes to an existing build (same route as build). Blocking."""
+        transport = {k: kwargs.pop(k) for k in _BUILD_TRANSPORT_KWARGS if k in kwargs}
+        return self.call_tool("/v1/tools/build", {"build_id": build_id, "changes": changes, **kwargs}, **transport)
+
+    async def aupdate_build(self, build_id: str, changes: str, **kwargs: Any) -> Any:
+        """Apply natural-language changes to an existing build (same route as build). Async."""
+        transport = {k: kwargs.pop(k) for k in _BUILD_TRANSPORT_KWARGS if k in kwargs}
+        return await self.acall_tool("/v1/tools/build", {"build_id": build_id, "changes": changes, **kwargs}, **transport)
+
     def get_balance(self) -> dict:
         """Get unified balance (on-chain USDC + credits). Blocking."""
         return self.call_free_get("/v1/tools/balance")
@@ -2135,6 +2251,69 @@ class OneShotClient:
         """Get unified balance (on-chain USDC + credits). Async."""
         return await self.acall_free_get("/v1/tools/balance")
 
+    # Inboxes and notifications (#1273). Free signed reads and writes of the agent's own data.
+
+    @staticmethod
+    def _inbox_params(**values: Any) -> Optional[dict[str, str]]:
+        params = {k: ("true" if v is True else "false" if v is False else str(v)) for k, v in values.items() if v is not None}
+        return params or None
+
+    def inbox(self, *, since: Optional[str] = None, limit: Optional[int] = None, include_body: Optional[bool] = None) -> Any:
+        """List emails received by the agent, newest first. Free. Blocking."""
+        return self.call_free_get("/v1/tools/inbox", self._inbox_params(since=since, limit=limit, include_body=include_body))
+
+    async def ainbox(self, *, since: Optional[str] = None, limit: Optional[int] = None, include_body: Optional[bool] = None) -> Any:
+        """List emails received by the agent, newest first. Free. Async."""
+        return await self.acall_free_get("/v1/tools/inbox", self._inbox_params(since=since, limit=limit, include_body=include_body))
+
+    def inbox_get(self, email_id: str) -> Any:
+        """One received email with its body and attachments. Free. Blocking."""
+        return self.call_free_get(f"/v1/tools/inbox/{quote(email_id, safe='')}")
+
+    async def ainbox_get(self, email_id: str) -> Any:
+        """One received email with its body and attachments. Free. Async."""
+        return await self.acall_free_get(f"/v1/tools/inbox/{quote(email_id, safe='')}")
+
+    def sms_inbox(self, *, since: Optional[str] = None, limit: Optional[int] = None, from_number: Optional[str] = None) -> Any:
+        """List text messages received by the agent. Free. Blocking."""
+        return self.call_free_get("/v1/tools/sms/inbox", self._inbox_params(since=since, limit=limit, **{"from": from_number}))
+
+    async def asms_inbox(self, *, since: Optional[str] = None, limit: Optional[int] = None, from_number: Optional[str] = None) -> Any:
+        """List text messages received by the agent. Free. Async."""
+        return await self.acall_free_get("/v1/tools/sms/inbox", self._inbox_params(since=since, limit=limit, **{"from": from_number}))
+
+    def sms_inbox_get(self, message_id: str) -> Any:
+        """One received text message. Free. Blocking."""
+        return self.call_free_get(f"/v1/tools/sms/inbox/{quote(message_id, safe='')}")
+
+    async def asms_inbox_get(self, message_id: str) -> Any:
+        """One received text message. Free. Async."""
+        return await self.acall_free_get(f"/v1/tools/sms/inbox/{quote(message_id, safe='')}")
+
+    def notifications(self, *, unread: Optional[bool] = None, limit: Optional[int] = None) -> Any:
+        """List the agent's notifications (job completions, failures, budget warnings). Free. Blocking."""
+        return self.call_free_get("/v1/tools/notifications", self._inbox_params(unread=unread, limit=limit))
+
+    async def anotifications(self, *, unread: Optional[bool] = None, limit: Optional[int] = None) -> Any:
+        """List the agent's notifications (job completions, failures, budget warnings). Free. Async."""
+        return await self.acall_free_get("/v1/tools/notifications", self._inbox_params(unread=unread, limit=limit))
+
+    def mark_notification_read(self, notification_id: str) -> Any:
+        """Mark one notification as read. Free. Blocking."""
+        return self.call_free_patch(f"/v1/tools/notifications/{quote(notification_id, safe='')}/read", scope="write")
+
+    async def amark_notification_read(self, notification_id: str) -> Any:
+        """Mark one notification as read. Free. Async."""
+        return await self.acall_free_patch(f"/v1/tools/notifications/{quote(notification_id, safe='')}/read", scope="write")
+
+    def mark_all_notifications_read(self) -> Any:
+        """Mark every notification as read. Free. Blocking."""
+        return self.call_free_patch("/v1/tools/notifications/read-all", scope="write")
+
+    async def amark_all_notifications_read(self) -> Any:
+        """Mark every notification as read. Free. Async."""
+        return await self.acall_free_patch("/v1/tools/notifications/read-all", scope="write")
+
     # `pause`/`resume` sit behind the API's paidEndpointLimiter (a rate limiter,
     # not a price) — no x402 quote, so they use `call_free_post`, not `call_tool`.
 

oneshot_python-0.38.0/oneshot/lookup.py

@@ -0,0 +1,252 @@
+"""The lookup tools: the manifest, and the plain mapping from an entry to a tool.
+
+The manifest (``oneshot.lookup_manifest``) is generated from the API's lookup
+registry. ``lookup_tools()`` returns it; ``OneShotClient.call_lookup`` and
+``acall_lookup`` call one entry by name.
+
+``lookup_tool_spec`` turns an entry into a name, a description and an argument
+list. It imports no agent framework, so the LangChain and GAME adapters share it
+and it is tested on its own. Lookup inputs are flat by rule: strings, numbers,
+booleans, enums, or arrays of those. Anything else stops with an error that
+names the tool and the field.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+from urllib.parse import quote
+
+from oneshot._errors import ValidationError
+from oneshot.lookup_manifest import LOOKUP_MANIFEST
+
+TOOL_PREFIX = "oneshot_"
+
+_SCALARS = ("string", "number", "integer", "boolean")
+
+
+class LookupSchemaError(ValueError):
+    """A manifest entry has an input the adapters cannot map."""
+
+    def __init__(self, tool: str, field: str, problem: str) -> None:
+        super().__init__(f'lookup tool "{tool}", field "{field}": {problem}')
+        self.tool = tool
+        self.field = field
+
+
+@dataclass(frozen=True)
+class LookupArg:
+    """One input field of a lookup tool."""
+
+    name: str
+    #: "string", "number", "integer", "boolean", "array" or "object" (passed through as given).
+    type: str
+    required: bool
+    description: str = ""
+    #: Allowed values, when the field (or the array's items) is an enum.
+    enum: Optional[tuple[str, ...]] = None
+    #: The array's item type; ``None`` unless ``type == "array"``.
+    item_type: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class LookupToolSpec:
+    """What an adapter needs to expose one lookup tool."""
+
+    #: The manifest name, e.g. ``company_filings``; this is what ``call_lookup`` takes.
+    lookup_name: str
+    #: The adapter-facing name, ``oneshot_<lookup_name>``.
+    name: str
+    description: str
+    args: tuple[LookupArg, ...]
+
+
+def lookup_tools() -> list[dict[str, Any]]:
+    """The lookup tools, one plain dictionary each: ``name``, ``path``, ``title``,
+    ``description``, ``input_schema`` and ``example``.
+    The list is a copy: changing it does not change the tools the client calls."""
+    return deepcopy(LOOKUP_MANIFEST)
+
+
+def find_lookup_tool(name: str) -> dict[str, Any]:
+    for entry in LOOKUP_MANIFEST:
+        if entry["name"] == name:
+            return entry
+    raise ValidationError(f"Unknown lookup tool: {name!r}", "name")
+
+
+def lookup_payload(params: Mapping[str, Any]) -> dict[str, Any]:
+    """The request body for a lookup call: the given params without the ``None`` ones."""
+    return {key: value for key, value in params.items() if value is not None}
+
+
+_PATH_PARAM = re.compile(r"\{([a-z0-9_]+)\}")
+
+#: Entry ``pricing`` values that are settled with a payment (``call_tool``). Every other value
+#: (``free``, ``included``, ``credits``, ``listed``) is a signed call with no payment of its own.
+PAID_PRICING = frozenset({"quoted", "fixed"})
+
+
+def lookup_query(params: Mapping[str, Any]) -> dict[str, str]:
+    """The query string values for a ``GET`` entry: booleans as ``true``/``false``, lists and
+    objects as JSON, everything else as text."""
+    out: dict[str, str] = {}
+    for key, value in params.items():
+        if isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        elif isinstance(value, (dict, list)):
+            out[key] = json.dumps(value)
+        else:
+            out[key] = str(value)
+    return out
+
+
+def lookup_request(entry: Mapping[str, Any], params: Mapping[str, Any]) -> tuple[str, str, str, dict[str, Any]]:
+    """How to send one manifest entry: ``(method, pricing, path, payload)``.
+
+    A lookup entry has neither ``method`` nor ``pricing``: it is a quoted POST to its
+    ``path`` with every param in the body. A registry route entry (Compute, Fund Goal and the
+    goal routes) states both, and a ``{goal_id}`` in its ``path`` is taken out of the params and
+    put into the path. A missing path param raises ``ValidationError``.
+    """
+    payload = lookup_payload(params)
+    path = str(entry["path"])
+    for field in _PATH_PARAM.findall(path):
+        value = payload.pop(field, None)
+        if value is None or str(value) == "":
+            raise ValidationError(f"{entry['name']}: {field} is required", field)
+        path = path.replace("{" + field + "}", quote(str(value), safe=""))
+    return str(entry.get("method", "POST")), str(entry.get("pricing", "quoted")), path, payload
+
+
+def _arg(tool: str, field: str, prop: Any, required: bool) -> LookupArg:
+    if not isinstance(prop, dict):
+        raise LookupSchemaError(tool, field, "the schema for this field is not an object")
+    kind = prop.get("type")
+    description = str(prop.get("description") or "")
+    enum = prop.get("enum")
+    if enum is not None and (not isinstance(enum, list) or not all(isinstance(v, str) for v in enum)):
+        raise LookupSchemaError(tool, field, "an enum must list strings")
+    if kind in _SCALARS:
+        if enum is not None and kind != "string":
+            raise LookupSchemaError(tool, field, f"an enum of type {kind!r} is not supported; use a string enum")
+        return LookupArg(field, kind, required, description, tuple(enum) if enum else None)
+    if kind == "object":
+        return LookupArg(field, "object", required, description)
+    if kind == "array":
+        items = prop.get("items")
+        if not isinstance(items, dict):
+            items = {}
+        item_kind = items.get("type")
+        if item_kind not in _SCALARS:
+            raise LookupSchemaError(tool, field, f"an array of {item_kind!r} is not supported; items must be strings, numbers or booleans")
+        item_enum = items.get("enum")
+        if item_enum is not None and (item_kind != "string" or not all(isinstance(v, str) for v in item_enum)):
+            raise LookupSchemaError(tool, field, "an array's enum must list strings")
+        return LookupArg(field, "array", required, description, tuple(item_enum) if item_enum else None, item_kind)
+    raise LookupSchemaError(tool, field, f"type {kind!r} is not supported; inputs are strings, numbers, booleans, enums or arrays of those")
+
+
+def lookup_tool_spec(entry: Mapping[str, Any]) -> LookupToolSpec:
+    """Map one manifest entry to a name, a description and an argument list."""
+    tool = str(entry["name"])
+    schema = entry.get("input_schema") or {}
+    properties = schema.get("properties") or {}
+    required = set(schema.get("required") or [])
+    args = tuple(_arg(tool, field, prop, field in required) for field, prop in properties.items())
+    return LookupToolSpec(tool, f"{TOOL_PREFIX}{tool}", str(entry["description"]), args)
+
+
+def lookup_tool_specs() -> list[LookupToolSpec]:
+    """A spec for every tool in the manifest."""
+    return [lookup_tool_spec(entry) for entry in LOOKUP_MANIFEST]
+
+
+def _coerce_scalar(spec: LookupToolSpec, arg: LookupArg, kind: str, text: str) -> Any:
+    try:
+        if kind == "integer":
+            return int(text)
+        if kind == "number":
+            return float(text)
+        if kind == "boolean":
+            lowered = text.strip().lower()
+            if lowered in ("true", "yes", "1"):
+                return True
+            if lowered in ("false", "no", "0"):
+                return False
+            raise ValueError(text)
+        return text
+    except ValueError:
+        raise ValidationError(f"{spec.name}: {arg.name} must be a {kind}, got {text!r}", arg.name) from None
+
+
+_STATE_CODE = re.compile(r"[A-Z]{2}")
+
+
+_LOCATION_FIELDS = frozenset({"location"})
+
+
+def _split_array_text(text: str, item_type: str, field: str = "") -> list[str]:
+    """Split GAME array text into items.
+
+    Semicolons or newlines separate items when the text has any, else commas do.
+    In a location field, a comma part that is only a two-letter uppercase code
+    stays with the part before it, so "Austin, TX" is one item. Every other
+    string array (agencies, keywords, NAICS) splits on every comma.
+    """
+    if ";" in text or "\n" in text:
+        return [part.strip() for part in re.split(r"[;\n]", text) if part.strip()]
+    parts = [part.strip() for part in text.split(",") if part.strip()]
+    if item_type != "string" or field not in _LOCATION_FIELDS:
+        return parts
+    items: list[str] = []
+    for part in parts:
+        if items and _STATE_CODE.fullmatch(part):
+            items[-1] = f"{items[-1]}, {part}"
+        else:
+            items.append(part)
+    return items
+
+
+def _coerce_object(spec: LookupToolSpec, arg: LookupArg, raw: Any) -> dict[str, Any]:
+    """An object field: a mapping as given, or text that is a JSON object (what a GAME worker sends)."""
+    if isinstance(raw, Mapping):
+        return dict(raw)
+    try:
+        value = json.loads(str(raw))
+    except ValueError:
+        value = None
+    if not isinstance(value, dict):
+        raise ValidationError(f"{spec.name}: {arg.name} must be a JSON object, got {str(raw)!r}", arg.name)
+    return value
+
+
+def coerce_text_args(spec: LookupToolSpec, values: Mapping[str, Any]) -> dict[str, Any]:
+    """Turn text values (what a GAME worker sends) into the types the tool takes.
+
+    Empty and missing values are dropped; arrays are comma-separated (or semicolon-separated; a "City, ST" location item stays whole). A missing
+    required field or a value that does not parse raises ``ValidationError``.
+    """
+    out: dict[str, Any] = {}
+    for arg in spec.args:
+        raw = values.get(arg.name)
+        text = "" if raw is None else str(raw).strip()
+        if not text:
+            if arg.required:
+                raise ValidationError(f"{spec.name}: {arg.name} is required", arg.name)
+            continue
+        if arg.type == "array":
+            out[arg.name] = [_coerce_scalar(spec, arg, arg.item_type or "string", part) for part in _split_array_text(text, arg.item_type or "string", arg.name)]
+        elif arg.type == "object":
+            out[arg.name] = _coerce_object(spec, arg, raw)
+        else:
+            out[arg.name] = _coerce_scalar(spec, arg, arg.type, text)
+        if arg.enum:
+            chosen = out[arg.name] if arg.type == "array" else [out[arg.name]]
+            bad = [v for v in chosen if v not in arg.enum]
+            if bad:
+                raise ValidationError(f"{spec.name}: {arg.name} must be one of {', '.join(arg.enum)}", arg.name)
+    return out