archerprotocol-sdk 0.1.0__py3-none-any.whl

archer_sdk/__init__.py

@@ -0,0 +1,55 @@
+"""Archer contribution SDK for Python: build, monetize, and publish an
+Archer intent. Envelope builders, GUI embeds, caller context, effect
+inference, and a one-call FastAPI handler (archer_sdk.fastapi). Mirrors the
+Node @archerprotocol/sdk; the shared test-vectors enforce parity."""
+
+from types import SimpleNamespace
+
+from . import embed as _embed
+from .builders import (
+    authorization,
+    cost,
+    data,
+    envelope,
+    is_invocation_envelope,
+    record,
+)
+from .caller import ArcherCaller, get_archer_caller, require_archer_caller
+from .effects import infer_effects
+from .errors import BadInputError, UpstreamError
+from .handler import ArcherHandler, HandlerContext, run_invocation
+from .money import to_micro, to_micro_optional
+
+__version__ = "0.1.0"
+
+# The one-object surface most handlers want: archer.envelope(...), archer.render(...).
+archer = SimpleNamespace(
+    data=data,
+    cost=cost,
+    authorization=authorization,
+    record=record,
+    envelope=envelope,
+    embed=_embed,
+    render=_embed.render,
+)
+
+__all__ = [
+    "archer",
+    "authorization",
+    "cost",
+    "data",
+    "envelope",
+    "record",
+    "is_invocation_envelope",
+    "get_archer_caller",
+    "require_archer_caller",
+    "ArcherCaller",
+    "infer_effects",
+    "BadInputError",
+    "UpstreamError",
+    "ArcherHandler",
+    "HandlerContext",
+    "run_invocation",
+    "to_micro",
+    "to_micro_optional",
+]

archer_sdk/builders.py

@@ -0,0 +1,149 @@
+"""Envelope builders for the generic Archer invocation contract. Inputs take
+pythonic snake_case keywords; outputs are plain dicts whose keys and shapes
+are byte-identical to the Node SDK's JSON (the shared test-vectors enforce
+this). Optional fields are omitted when absent, never set to null."""
+
+from typing import Any, Dict, List, Optional
+
+from .money import Money, to_micro, to_micro_optional
+
+_COST_MODELS = {"flat", "percent", "x402", "embedded", "none"}
+
+
+def _prune(obj: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in obj.items() if v is not None}
+
+
+def data(value: Any) -> Dict[str, Any]:
+    """The Render arm."""
+    return {"data": value}
+
+
+def cost(
+    *,
+    model: str,
+    amount_micro: Optional[Money] = None,
+    value_micro: Optional[Money] = None,
+    bps: Optional[int] = None,
+    bob_fee_micro: Optional[Money] = None,
+    archer_fee_micro: Optional[Money] = None,
+) -> Dict[str, Any]:
+    """The Settle arm: a declared fee model plus its parameters."""
+    if model in ("flat", "x402"):
+        params = _prune(
+            {
+                "amountMicro": to_micro(amount_micro) if amount_micro is not None else None,
+                "archerFeeMicro": to_micro_optional(archer_fee_micro),
+            }
+        )
+    elif model == "percent":
+        params = _prune(
+            {
+                "valueMicro": to_micro(value_micro) if value_micro is not None else None,
+                "bps": bps,
+                "archerFeeMicro": to_micro_optional(archer_fee_micro),
+            }
+        )
+    elif model == "embedded":
+        params = _prune(
+            {
+                "bobFeeMicro": to_micro_optional(bob_fee_micro),
+                "archerFeeMicro": to_micro_optional(archer_fee_micro),
+            }
+        )
+    elif model == "none":
+        params = {}
+    else:
+        raise ValueError(f'unknown fee model "{model}" (expected one of {sorted(_COST_MODELS)})')
+    return {"model": model, "params": params}
+
+
+def authorization(
+    *,
+    type: str,
+    label: str,
+    payload: Dict[str, Any],
+    namespace: Optional[str] = None,
+) -> Dict[str, Any]:
+    """One entry of the Authorize arm. The label is the human disclosure."""
+    if not label or not isinstance(label, str):
+        raise ValueError("authorization label is required (human-readable disclosure)")
+    return _prune(
+        {
+            "type": type,
+            "namespace": namespace,
+            "label": label,
+            "payload": payload if payload is not None else {},
+        }
+    )
+
+
+def record(
+    *,
+    record_kind: str,
+    basis_micro: Optional[Money] = None,
+    value_micro: Optional[Money] = None,
+    bob_fee_micro: Optional[Money] = None,
+    archer_fee_micro: Optional[Money] = None,
+    value_read: Optional[Dict[str, Any]] = None,
+    exit_instructions: Optional[Dict[str, Any]] = None,
+    ref: Optional[str] = None,
+    group_key: Optional[str] = None,
+    view_url: Optional[str] = None,
+    disclosure: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """The Record arm: a durable, user-owned outcome (opaque to the engine)."""
+    if not record_kind or not isinstance(record_kind, str):
+        raise ValueError("record_kind is required")
+    return _prune(
+        {
+            "recordKind": record_kind,
+            "basisMicro": to_micro_optional(basis_micro),
+            "valueMicro": to_micro_optional(value_micro),
+            "bobFeeMicro": to_micro_optional(bob_fee_micro),
+            "archerFeeMicro": to_micro_optional(archer_fee_micro),
+            "valueRead": value_read,
+            "exitInstructions": exit_instructions,
+            "ref": ref,
+            "groupKey": group_key,
+            "viewUrl": view_url,
+            "disclosure": disclosure,
+        }
+    )
+
+
+def envelope(
+    *,
+    data: Any = None,
+    cost: Optional[Dict[str, Any]] = None,
+    authorizations: Optional[List[Dict[str, Any]]] = None,
+    record: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Assemble the arms into one invocation envelope, validated structurally."""
+    env = _prune(
+        {"data": data, "cost": cost, "authorizations": authorizations, "record": record}
+    )
+    if not is_invocation_envelope(env):
+        raise ValueError(
+            "envelope arms are malformed (cost needs a model, record needs a recordKind, "
+            "authorizations must be a list)"
+        )
+    return env
+
+
+def is_invocation_envelope(value: Any) -> bool:
+    """Structural check mirroring the engine's isInvocationEnvelope."""
+    if value is None or not isinstance(value, dict):
+        return False
+    if "authorizations" in value and value["authorizations"] is not None:
+        if not isinstance(value["authorizations"], list):
+            return False
+    if "cost" in value and value["cost"] is not None:
+        c = value["cost"]
+        if not isinstance(c, dict) or not isinstance(c.get("model"), str):
+            return False
+    if "record" in value and value["record"] is not None:
+        r = value["record"]
+        if not isinstance(r, dict) or not isinstance(r.get("recordKind"), str):
+            return False
+    return True

archer_sdk/caller.py

@@ -0,0 +1,39 @@
+"""Caller context. Archer injects the invoking user's context inside the
+signed args as args["archerCaller"], so it is verified as part of the
+envelope. Read it here."""
+
+from typing import Any, Dict, Optional, TypedDict
+
+
+class ArcherCaller(TypedDict):
+    evmAddress: Optional[str]
+    svmAddress: Optional[str]
+    archerFeeRate: Optional[float]
+
+
+def get_archer_caller(args: Dict[str, Any]) -> Optional[ArcherCaller]:
+    raw = args.get("archerCaller") if isinstance(args, dict) else None
+    if raw is None or not isinstance(raw, dict):
+        return None
+    evm = raw.get("evmAddress")
+    svm = raw.get("svmAddress")
+    rate = raw.get("archerFeeRate")
+    return {
+        "evmAddress": evm if isinstance(evm, str) else None,
+        "svmAddress": svm if isinstance(svm, str) else None,
+        "archerFeeRate": float(rate)
+        if isinstance(rate, (int, float)) and not isinstance(rate, bool)
+        else None,
+    }
+
+
+def require_archer_caller(args: Dict[str, Any]) -> ArcherCaller:
+    """For intents that move user funds or cause side effects, caller context
+    is mandatory. A missing caller almost always means the intent was
+    published without requiresCaller: true."""
+    caller = get_archer_caller(args)
+    if caller is None:
+        raise ValueError(
+            "caller context is missing; declare requiresCaller: true when publishing this intent"
+        )
+    return caller

archer_sdk/effects.py

@@ -0,0 +1,306 @@
+"""infer_effects: derive a reviewable effect report from one authorization.
+
+Pure and dependency-injected: descriptors are data rows, simulation and
+pricing are injected async callables. The function branches on verdict
+strategy only (simulate / decode / opaque), never on a venue. It never
+raises; an unrecognizable or malformed payload renders as OPAQUE.
+
+The shared effects vectors enforce byte-parity with the Node SDK and the
+platform's server-side derivation."""
+
+import math
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+_MAX_ROWS = 30
+_MAX_VALUE_CHARS = 120
+# JS Number.MAX_SAFE_INTEGER: a ceiling beyond any real economy is an
+# unlimited-approval sentinel and reports as unmeasurable.
+_MAX_SAFE = 9007199254740991
+
+SimulateFn = Callable[[Dict[str, Any]], Awaitable[Dict[str, Any]]]
+PriceFn = Callable[[str], Awaitable[Optional[float]]]
+
+
+async def infer_effects(
+    auth: Any,
+    *,
+    descriptors: List[Dict[str, Any]],
+    simulate: Optional[SimulateFn] = None,
+    price: Optional[PriceFn] = None,
+) -> Dict[str, Any]:
+    try:
+        return await _infer(auth, descriptors, simulate, price)
+    except Exception:
+        # The last-resort guarantee: whatever went wrong, render opaquely.
+        return _opaque_report(auth)
+
+
+async def _infer(auth, descriptors, simulate, price):
+    auth_type = auth.get("type") if isinstance(auth, dict) else None
+    auth_type = auth_type if isinstance(auth_type, str) else "unknown"
+
+    if auth_type == "tx" and simulate is not None:
+        try:
+            outcome = await simulate(auth)
+            value = outcome.get("valueUsd")
+            measurable = value if isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) else None
+            report = {
+                "verdict": "SIMULATED",
+                "authType": auth_type,
+                "namespace": _str_or_none(auth.get("namespace")),
+                "measurableValueUsd": measurable,
+                "simulation": outcome.get("raw"),
+                "display": {"title": _title_of(auth), "rows": outcome.get("rows") or []},
+            }
+            return _prune_report(report)
+        except Exception:
+            return _opaque_report(auth)
+
+    if auth_type == "sign":
+        decoded = _decode_against_descriptors(auth, descriptors or [])
+        if decoded is not None:
+            descriptor, bounded = decoded
+            report = {
+                "verdict": "DECODED_BOUNDED",
+                "authType": auth_type,
+                "namespace": _str_or_none(auth.get("namespace")),
+                "measurableValueUsd": await _value_of(descriptor, bounded, price),
+                "bounded": bounded,
+                "display": {
+                    "title": descriptor["label"],
+                    "rows": [{"label": k, "value": _clip(v)} for k, v in bounded.items()],
+                },
+                "descriptorRef": descriptor["id"],
+            }
+            return _prune_report(report)
+
+    return _opaque_report(auth)
+
+
+# ── decoding ────────────────────────────────────────────────────────────────
+
+
+def _decode_against_descriptors(auth, descriptors):
+    payload = _as_dict(auth.get("payload") if isinstance(auth, dict) else None)
+    if payload is None:
+        return None
+    domain = _as_dict(payload.get("domain"))
+    message = _as_dict(payload.get("message"))
+    primary_type = payload.get("primaryType")
+    if domain is None or message is None or not isinstance(primary_type, str):
+        return None
+
+    for descriptor in descriptors:
+        if not _matches(descriptor, primary_type, domain):
+            continue
+        if not _is_canonical_contract(descriptor, domain):
+            continue
+        bounded = {}
+        for entry in descriptor.get("extract", []):
+            value = _get_path(message, entry["path"])
+            if value is not None and not isinstance(value, (dict, list)):
+                bounded[entry["role"]] = _js_str(value)
+        return descriptor, bounded
+    return None
+
+
+def _matches(descriptor, primary_type, domain):
+    match = descriptor.get("match", {})
+    if match.get("primaryType") != primary_type:
+        return False
+    want = match.get("domain")
+    if not want:
+        return True
+    if "name" in want and domain.get("name") != want["name"]:
+        return False
+    if "version" in want and domain.get("version") != want["version"]:
+        return False
+    if "chainId" in want:
+        try:
+            if float(domain.get("chainId")) != float(want["chainId"]):
+                return False
+        except (TypeError, ValueError):
+            return False
+    return True
+
+
+def _is_canonical_contract(descriptor, domain):
+    """The canonical-contract pin: a domain/type match only earns
+    DECODED_BOUNDED when the payload's verifyingContract is one of the
+    descriptor's canonical addresses. A lookalike domain pointed at another
+    contract stays OPAQUE."""
+    vc = domain.get("verifyingContract")
+    if not isinstance(vc, str) or len(vc) == 0:
+        return False
+    needle = vc.lower()
+    contracts = descriptor.get("riskRules", {}).get("verifyingContracts", [])
+    return any(isinstance(c, str) and c.lower() == needle for c in contracts)
+
+
+# ── valuation ───────────────────────────────────────────────────────────────
+
+
+async def _value_of(descriptor, bounded, price):
+    """Priceability gates measurability: a missing amount, an unbounded
+    amount, an unknown asset, or an unpriceable asset all yield None, and the
+    policy layer treats None via its opaque-cap behavior."""
+    valuation = descriptor.get("valuation")
+    if not valuation or price is None:
+        return None
+
+    raw = bounded.get(valuation["source"])
+    if raw is None:
+        return None
+    try:
+        units = float(raw) / (10 ** valuation["decimals"])
+    except (TypeError, ValueError):
+        return None
+    if not math.isfinite(units):
+        return None
+    if units > _MAX_SAFE:
+        return None
+
+    asset = valuation.get("asset")
+    if asset is None and valuation.get("assetRole"):
+        asset = bounded.get(valuation["assetRole"])
+    if not asset:
+        return None
+
+    try:
+        unit_price = await price(asset)
+    except Exception:
+        return None
+    if unit_price is None or not math.isfinite(unit_price):
+        return None
+
+    value = units * unit_price
+    if not math.isfinite(value):
+        return None
+    return _js_number(value)
+
+
+# ── opaque rendering ────────────────────────────────────────────────────────
+
+
+def _opaque_report(auth):
+    namespace = _str_or_none(auth.get("namespace")) if isinstance(auth, dict) else None
+    report = {
+        "verdict": "OPAQUE",
+        "authType": (auth.get("type") if isinstance(auth, dict) and isinstance(auth.get("type"), str) else "unknown"),
+        "measurableValueUsd": None,
+        "display": {
+            "title": _title_of(auth),
+            "rows": _flatten_for_display(auth.get("payload") if isinstance(auth, dict) else None),
+        },
+    }
+    if namespace is not None:
+        report["namespace"] = namespace
+    return _order_report(report)
+
+
+def _flatten_for_display(payload):
+    rows = []
+    try:
+        _walk(payload, "", rows)
+    except Exception:
+        rows.append({"label": "payload", "value": "unavailable"})
+    if not rows:
+        rows.append({"label": "payload", "value": "empty"})
+    return rows[:_MAX_ROWS]
+
+
+def _walk(value, prefix, rows):
+    if len(rows) >= _MAX_ROWS:
+        return
+    if value is None:
+        if prefix:
+            rows.append({"label": prefix, "value": "None" if value is None else str(value)})
+        return
+    if not isinstance(value, (dict, list)):
+        rows.append({"label": prefix or "value", "value": _clip(_js_str(value))})
+        return
+    entries = (
+        [(str(i), v) for i, v in enumerate(value)]
+        if isinstance(value, list)
+        else list(value.items())
+    )
+    for key, child in entries:
+        _walk(child, f"{prefix}.{key}" if prefix else key, rows)
+        if len(rows) >= _MAX_ROWS:
+            return
+
+
+# ── small helpers ───────────────────────────────────────────────────────────
+
+
+def _title_of(auth):
+    label = auth.get("label") if isinstance(auth, dict) else None
+    return label if isinstance(label, str) and len(label) > 0 else "Authorization"
+
+
+def _as_dict(value):
+    return value if isinstance(value, dict) else None
+
+
+def _get_path(obj, path):
+    current = obj
+    for segment in path.split("."):
+        if not isinstance(current, dict):
+            return None
+        current = current.get(segment)
+    return current
+
+
+def _str_or_none(value):
+    return value if isinstance(value, str) and len(value) > 0 else None
+
+
+def _clip(value):
+    return value[:_MAX_VALUE_CHARS] + "…" if len(value) > _MAX_VALUE_CHARS else value
+
+
+def _js_str(value):
+    """Mirror JS String() for the value types that ride typed-data messages."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, float):
+        return _js_number_str(value)
+    return str(value)
+
+
+def _js_number_str(f):
+    if math.isnan(f):
+        return "NaN"
+    if math.isinf(f):
+        return "Infinity" if f > 0 else "-Infinity"
+    if f.is_integer() and abs(f) < 1e21:
+        return str(int(f))
+    return repr(f)
+
+
+def _js_number(value):
+    """Collapse float results that are exact integers to int so JSON matches
+    the Node output (12.5 stays 12.5; 5.0 becomes 5)."""
+    if isinstance(value, float) and value.is_integer() and abs(value) <= _MAX_SAFE:
+        return int(value)
+    return value
+
+
+_REPORT_KEY_ORDER = [
+    "verdict",
+    "authType",
+    "namespace",
+    "measurableValueUsd",
+    "bounded",
+    "simulation",
+    "display",
+    "descriptorRef",
+]
+
+
+def _prune_report(report):
+    return _order_report({k: v for k, v in report.items() if v is not None or k == "measurableValueUsd"})
+
+
+def _order_report(report):
+    return {k: report[k] for k in _REPORT_KEY_ORDER if k in report}

archer_sdk/embed.py

@@ -0,0 +1,164 @@
+"""Typed builders for the archerEmbed GUI render contract. Mirrors the
+engine's whitelisted discriminated union (by `kind`); anything off-contract
+is dropped by the engine before rendering, so the builders validate the
+load-bearing fields at author time. Output keys are byte-identical to the
+Node SDK (the shared embeds vectors enforce this)."""
+
+from typing import Any, Dict, List, Optional, Union
+
+from .builders import _prune
+
+
+def _forward_compat(
+    persistence: Optional[str],
+    live_source_url: Optional[str],
+    refresh_interval_ms: Optional[int],
+) -> Dict[str, Any]:
+    return _prune(
+        {
+            "persistence": persistence,
+            "liveSourceUrl": live_source_url,
+            "refreshIntervalMs": refresh_interval_ms,
+        }
+    )
+
+
+def chart(
+    *,
+    chart_type: str,
+    data: List[Dict[str, Any]],
+    title: Optional[str] = None,
+    x_label: Optional[str] = None,
+    y_label: Optional[str] = None,
+    series: Optional[List[Dict[str, Any]]] = None,
+    y_axis_domain: Optional[Union[str, List[float]]] = None,
+    persistence: Optional[str] = None,
+    live_source_url: Optional[str] = None,
+    refresh_interval_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    if not isinstance(data, list) or len(data) == 0:
+        raise ValueError("chart embed: data must have at least one point")
+    return _prune(
+        {
+            "kind": "chart",
+            "chartType": chart_type,
+            "title": title,
+            "xLabel": x_label,
+            "yLabel": y_label,
+            "data": data,
+            "series": series,
+            "yAxisDomain": y_axis_domain,
+            **_forward_compat(persistence, live_source_url, refresh_interval_ms),
+        }
+    )
+
+
+def metric(
+    *,
+    label: str,
+    value: str,
+    delta: Optional[Dict[str, str]] = None,
+    persistence: Optional[str] = None,
+    live_source_url: Optional[str] = None,
+    refresh_interval_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    if not label or not value:
+        raise ValueError("metric embed: label and value are required")
+    return _prune(
+        {
+            "kind": "metric",
+            "label": label,
+            "value": value,
+            "delta": delta,
+            **_forward_compat(persistence, live_source_url, refresh_interval_ms),
+        }
+    )
+
+
+def table(
+    *,
+    columns: List[Dict[str, Any]],
+    rows: Optional[List[Dict[str, Any]]] = None,
+    persistence: Optional[str] = None,
+    live_source_url: Optional[str] = None,
+    refresh_interval_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    if not isinstance(columns, list) or len(columns) == 0:
+        raise ValueError("table embed: at least one column is required")
+    return _prune(
+        {
+            "kind": "table",
+            "columns": columns,
+            "rows": rows if rows is not None else [],
+            **_forward_compat(persistence, live_source_url, refresh_interval_ms),
+        }
+    )
+
+
+def kv(
+    *,
+    pairs: List[Dict[str, str]],
+    persistence: Optional[str] = None,
+    live_source_url: Optional[str] = None,
+    refresh_interval_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    if not isinstance(pairs, list) or len(pairs) == 0:
+        raise ValueError("kv embed: at least one pair is required")
+    return _prune(
+        {
+            "kind": "kv",
+            "pairs": pairs,
+            **_forward_compat(persistence, live_source_url, refresh_interval_ms),
+        }
+    )
+
+
+def alert(
+    *,
+    tone: str,
+    body: str,
+    title: Optional[str] = None,
+    persistence: Optional[str] = None,
+    live_source_url: Optional[str] = None,
+    refresh_interval_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    if not tone or not body:
+        raise ValueError("alert embed: tone and body are required")
+    return _prune(
+        {
+            "kind": "alert",
+            "tone": tone,
+            "title": title,
+            "body": body,
+            **_forward_compat(persistence, live_source_url, refresh_interval_ms),
+        }
+    )
+
+
+def image(
+    *,
+    url: str,
+    alt: str,
+    width: Optional[int] = None,
+    height: Optional[int] = None,
+    persistence: Optional[str] = None,
+    live_source_url: Optional[str] = None,
+    refresh_interval_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    if not url or not alt:
+        raise ValueError("image embed: url and alt are required")
+    return _prune(
+        {
+            "kind": "image",
+            "url": url,
+            "alt": alt,
+            "width": width,
+            "height": height,
+            **_forward_compat(persistence, live_source_url, refresh_interval_ms),
+        }
+    )
+
+
+def render(*, text: Optional[str] = None, embed: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """The flat read payload the integrated engine reads: text + archerEmbed."""
+    return _prune({"text": text, "archerEmbed": embed})

archer_sdk/errors.py

@@ -0,0 +1,19 @@
+"""Handler error types. The one-call handler maps these to the partner
+response envelope: BadInputError -> 400, UpstreamError -> 503; anything else
+-> 500 with code UNKNOWN."""
+
+
+class BadInputError(ValueError):
+    status = 400
+
+    def __init__(self, message: str, code: str = "BAD_INPUT"):
+        super().__init__(message)
+        self.code = code
+
+
+class UpstreamError(RuntimeError):
+    status = 503
+
+    def __init__(self, message: str, code: str = "UPSTREAM_ERROR"):
+        super().__init__(message)
+        self.code = code

archer_sdk/fastapi.py

@@ -0,0 +1,58 @@
+"""FastAPI adapter for the one-call handler. Import requires the fastapi
+extra: pip install "archer-sdk[fastapi]"."""
+
+from typing import Any, Dict, Optional
+
+from archer_verify import create_verifier
+
+from .handler import ArcherHandler, run_invocation
+
+
+def create_archer_intent(
+    handler: ArcherHandler,
+    *,
+    verifier: Any = None,
+    verify: Optional[Dict[str, Any]] = None,
+    provider_cost_micro: Optional[int] = None,
+):
+    """Build a FastAPI route callable: verifies the signed envelope, invokes
+    your handler, returns the partner response envelope. Pass a prebuilt
+    `verifier`, or `verify` kwargs forwarded to archer_verify.create_verifier
+    (e.g. archer_base_url, public_key_pem)."""
+    from fastapi import Request
+    from fastapi.responses import JSONResponse
+
+    v = verifier or create_verifier(**(verify or {}))
+
+    async def route(request: Request) -> JSONResponse:
+        try:
+            body = await request.json()
+        except Exception:
+            body = None
+        status, payload = await run_invocation(
+            v,
+            handler,
+            body=body,
+            headers=dict(request.headers),
+            provider_cost_micro=provider_cost_micro,
+        )
+        return JSONResponse(status_code=status, content=payload)
+
+    return route
+
+
+def mount_archer_tools(
+    router: Any,
+    tools: Dict[str, ArcherHandler],
+    *,
+    verifier: Any = None,
+    verify: Optional[Dict[str, Any]] = None,
+    provider_cost_micro: Optional[int] = None,
+) -> None:
+    """Mount several sub-tools on a router you own (APIRouter or FastAPI app):
+    one POST route per path."""
+    v = verifier or create_verifier(**(verify or {}))
+    for path, handler in tools.items():
+        router.post(path)(
+            create_archer_intent(handler, verifier=v, provider_cost_micro=provider_cost_micro)
+        )

archer_sdk/handler.py

@@ -0,0 +1,85 @@
+"""The one-call request handler, framework-free core. Verifies the signed
+Archer envelope (via archer-verify), extracts the handler context, invokes
+your handler, and wraps the return in the partner response envelope. The
+FastAPI adapter in archer_sdk.fastapi builds routes on top of this."""
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Dict, Optional, Tuple, Union
+
+from .caller import ArcherCaller, get_archer_caller
+
+
+@dataclass
+class HandlerContext:
+    args: Dict[str, Any]
+    caller: Optional[ArcherCaller]
+    request_id: str
+    intent_definition_id: str
+    user_id: str
+
+
+ArcherHandler = Callable[[HandlerContext], Union[Any, Awaitable[Any]]]
+
+
+def _reject_message(status: int) -> str:
+    if status == 401:
+        return "Unauthorized: Archer signature missing, stale, or replayed."
+    if status == 403:
+        return "Forbidden: Archer signature invalid."
+    return "Service unavailable: cannot reach Archer to verify the signature."
+
+
+def _error_status(err: Exception) -> int:
+    status = getattr(err, "status", None)
+    return status if status in (400, 403, 503) else 500
+
+
+def _error_code(err: Exception, status: int) -> str:
+    code = getattr(err, "code", None)
+    if isinstance(code, str):
+        return code
+    return "UNKNOWN" if status == 500 else "ERROR"
+
+
+async def run_invocation(
+    verifier: Any,
+    handler: ArcherHandler,
+    *,
+    body: Any,
+    headers: Dict[str, Any],
+    provider_cost_micro: Optional[int] = None,
+) -> Tuple[int, Dict[str, Any]]:
+    """Verify + dispatch one invocation. Returns (http_status, response_body)."""
+    result = verifier.verify(headers, body=body)
+    if not result.ok:
+        status = result.status or 401
+        return status, {
+            "success": False,
+            "error": {"code": result.reason, "message": _reject_message(status)},
+        }
+
+    env = result.envelope or {}
+    args = env.get("args") if isinstance(env.get("args"), dict) else {}
+    ctx = HandlerContext(
+        args=args,
+        caller=get_archer_caller(args),
+        request_id=env.get("requestId", ""),
+        intent_definition_id=env.get("intentDefinitionId", ""),
+        user_id=env.get("userId", ""),
+    )
+
+    try:
+        invocation = handler(ctx)
+        if inspect.isawaitable(invocation):
+            invocation = await invocation
+        response: Dict[str, Any] = {"success": True, "result": invocation}
+        if provider_cost_micro is not None:
+            response["providerCostMicro"] = provider_cost_micro
+        return 200, response
+    except Exception as err:
+        status = _error_status(err)
+        return status, {
+            "success": False,
+            "error": {"code": _error_code(err, status), "message": str(err)},
+        }

archer_sdk/money.py

@@ -0,0 +1,33 @@
+"""Money coercion: everything the engine bills parses as a BigInt, so every
+micro amount travels as an integer decimal string. Mirrors the Node SDK's
+coercion strictness exactly."""
+
+import math
+import re
+from typing import Optional, Union
+
+Money = Union[int, float, str]
+
+_INT_STRING = re.compile(r"^-?\d+$")
+
+
+def to_micro(value: Money) -> str:
+    """Coerce a money input to an integer decimal string, or raise."""
+    if isinstance(value, bool):
+        raise TypeError(f"micro amount must be a finite integer, received {value!r}")
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value) or not value.is_integer():
+            raise ValueError(f"micro amount must be a finite integer, received {value!r}")
+        return str(int(value))
+    if isinstance(value, str):
+        s = value.strip()
+        if not _INT_STRING.match(s):
+            raise ValueError(f'micro amount must be an integer decimal string, received "{value}"')
+        return s
+    raise TypeError(f"micro amount must be int, integral float, or digit string, received {type(value).__name__}")
+
+
+def to_micro_optional(value: Optional[Money]) -> Optional[str]:
+    return None if value is None else to_micro(value)

archerprotocol_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: archerprotocol-sdk
+Version: 0.1.0
+Summary: Build and monetize an Archer intent from Python: typed envelope builders, embeds, caller context, effect inference, and a one-call FastAPI handler.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Archer-Laboratories/archer-sdk
+Project-URL: Repository, https://github.com/Archer-Laboratories/archer-sdk
+Project-URL: Issues, https://github.com/Archer-Laboratories/archer-sdk/issues
+Keywords: archer,archer-protocol,intent,partner-sdk,fastapi,ed25519
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: archer-verify>=0.1.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Requires-Dist: starlette>=0.36; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+
+# archerprotocol-sdk
+
+Build, monetize, and publish an Archer intent from Python. This package
+mirrors the Node `@archerprotocol/sdk` builder surface; both are held to the
+same shared test vectors, so an envelope built here is byte-identical to one
+built in TypeScript.
+
+```bash
+pip install "archerprotocol-sdk[fastapi]"
+```
+
+## One-call handler (FastAPI)
+
+```python
+from fastapi import FastAPI
+from archer_sdk import archer, require_archer_caller, BadInputError
+from archer_sdk.fastapi import mount_archer_tools
+
+app = FastAPI()
+
+async def deposit(ctx):
+    caller = require_archer_caller(ctx.args)
+    amount = ctx.args.get("amount")
+    if not amount:
+        raise BadInputError('amount is required (e.g. "1.5")')
+    return archer.envelope(
+        cost=archer.cost(model="embedded", archer_fee_micro=200),
+        authorizations=[
+            archer.authorization(
+                type="tx",
+                namespace="evm",
+                label=f"Deposit {amount} USDC",
+                payload={"chainId": 8453, "to": "0x...", "data": "0x...", "value": "0x0"},
+            )
+        ],
+        record=archer.record(
+            record_kind="position",
+            basis_micro=1_000_000,
+            disclosure={"custody": "SELF", "exitModel": "PERMISSIONLESS"},
+        ),
+    )
+
+mount_archer_tools(app, {"/deposit": deposit})
+```
+
+The handler verifies the signed Archer envelope (via `archer-verify`),
+hands you `ctx.args / ctx.caller / ctx.request_id / ctx.intent_definition_id /
+ctx.user_id`, and wraps your return in the partner response envelope.
+Raise `BadInputError` (400) or `UpstreamError` (503) for clean failures.
+
+## Reads
+
+Return the flat render payload instead of an envelope:
+
+```python
+from archer_sdk import archer
+
+async def price_chart(ctx):
+    return archer.render(
+        text="ETH, last 30 days",
+        embed=archer.embed.chart(chart_type="line", data=[{"x": "2026-01", "y": 3000}]),
+    )
+```
+
+## Effect inference (pre-flight)
+
+`infer_effects` is the same function the platform runs server-side to decode
+a `sign` authorization into a verified, bounded confirmation. Run it locally
+against your descriptors to see exactly what the user's confirmation screen
+will derive; the platform always re-derives its own report.
+
+```python
+from archer_sdk import infer_effects
+
+report = await infer_effects(auth, descriptors=my_descriptors, price=my_price_fn)
+assert report["verdict"] == "DECODED_BOUNDED"
+```
+
+## Publishing
+
+Publishing and lifecycle management use the Node CLI, which works without a
+Node project: `npx @archerprotocol/sdk` gives you `archer init / publish /
+activate / stats`.

archerprotocol_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+archer_sdk/__init__.py,sha256=7R_va7cFOSphoQFn4jJ5ZuAD2MJG8ir3yeVTEh0OTPA,1408
+archer_sdk/builders.py,sha256=_QNUx0YDTAmLUY48doNzuW6HzkwPYNY80bJ9UAeJefI,5131
+archer_sdk/caller.py,sha256=OJxIUtDOQnjIVeHFFhKo0_GTrDXwc7_cUHlQjhvGWUM,1406
+archer_sdk/effects.py,sha256=KgNeB7yvvewPeWZP_fq5IavcdXx5yS7dAxvWEabSxIA,10491
+archer_sdk/embed.py,sha256=Zos2oFXTb9rSrvbB3CqQKmXx4vNLJXpmN-YtYiDg9FY,4862
+archer_sdk/errors.py,sha256=Q4NjGtWyzn4yVEtLBBc7XV-vLB7CfK28ZTjZDX2OYAk,534
+archer_sdk/fastapi.py,sha256=L1MaeV-sT6v9N-r9g0mwYBiVGKaDNadCpuTYYsuqu1U,1854
+archer_sdk/handler.py,sha256=hLRiapkb1ft4kpZ_cbEObcpB2A6_OuFbiOVMgqLvars,2776
+archer_sdk/money.py,sha256=hJlK91LuSbLgnhaILyd3aiNLdGNEHY0Tu1J2yNhbhtM,1257
+archerprotocol_sdk-0.1.0.dist-info/METADATA,sha256=yRHUohtotgSVxQV7dB7M7cuyONuxPQ_UrMJXTKsQBfU,3683
+archerprotocol_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+archerprotocol_sdk-0.1.0.dist-info/top_level.txt,sha256=0baA18VzWTDojRlynkT01cYeuKlJO8Rm1dn97q0JZas,11
+archerprotocol_sdk-0.1.0.dist-info/RECORD,,

archerprotocol_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

archerprotocol_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+archer_sdk