ausca 0.0.2__tar.gz

ausca-0.0.2/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: ausca
+Version: 0.0.2
+Summary: Client for Ausca metered agent infrastructure services: catalog-bound invocations paid per call under a hard USD cap, through pluggable payment authorities (x402 v2 today), with receipt-backed results.
+License-Expression: MIT
+Project-URL: Homepage, https://ausca.com
+Project-URL: Documentation, https://ausca.com/docs
+Project-URL: Repository, https://github.com/auscahq/ausca-integrations
+Project-URL: Issues, https://github.com/auscahq/ausca-integrations/issues
+Keywords: ausca,x402,agents,payments,mcp
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Requires-Dist: x402[evm]>=2.21.0
+Requires-Dist: eth-account>=0.13
+
+# ausca
+
+Client for [Ausca](https://ausca.com) metered agent infrastructure services:
+document OCR, document analysis, media transcription, browser sessions, and
+agent inboxes. Paid per call under a hard USD cap you set, with no account
+or provider API keys, and a settlement receipt on every completed
+invocation.
+
+## Install
+
+```bash
+pip install ausca
+```
+
+## Use
+
+```python
+import os
+from ausca import AuscaClient
+
+client = AuscaClient.with_local_key(
+    private_key=os.environ["AUSCA_PRIVATE_KEY"],  # pays USDC on Base
+    max_payment_usd=0.50,                         # hard per-call cap
+)
+
+outcome = client.invoke("browser.session", {"duration_seconds": 600})
+print(outcome.result)
+print(outcome.payment.transaction)  # settlement proof
+```
+
+`invoke` resolves the offer's immutable revision, schema digests, and
+payable route from the live catalog, reads the exact payment requirement,
+pays it if it fits the cap, and retries the same bytes with the same
+idempotency key. Each call starts with a fresh key. For recovery after an
+uncertain response, pass the same caller-owned `idempotency_key`; use a new
+key for another intentional purchase, even when its input is identical.
+
+A CLI ships with the package:
+
+```bash
+ausca catalog
+ausca price document.ocr
+AUSCA_PRIVATE_KEY=0x... AUSCA_MAX_PAYMENT_USD=0.50 \
+  ausca invoke browser.session '{"duration_seconds":600}'
+# Reuse this key only to recover that same intended purchase:
+ausca invoke browser.session '{"duration_seconds":600}' \
+  --idempotency-key browser-attempt-20260903-0001
+```
+
+## Payment rails
+
+Payment is a pluggable authority, never a client concern. The built-in
+`LocalKeyAuthority` pays x402 v2 with a local signing key through the
+official [`x402`](https://pypi.org/project/x402/) library, which enforces
+the cap through its spend controls before anything is signed; other rails
+implement the same small `PaymentAuthority` protocol.
+`client.pay_request(url, ...)` runs one paid call against any resource the
+configured authority can pay; nothing in it is vendor-specific.
+
+## Artifact-backed offers
+
+Document and media offers take an immutable artifact commitment instead of
+raw bytes. `ausca commit file.pdf` sends the bytes to Ausca's keyless
+temporary ingress and returns the commitment the offer input carries; the
+library equivalent is `client.commit(data, media_type)`. Repeating the same
+bytes is idempotent. The active offer catalog sets the usable input limit.
+
+Successful paid state includes `receipt_ref.public_url`, an immutable
+hash-only proof of the Ausca service, public price, completion time, and
+receipt digest. It contains no request or result bytes, content digests, or
+access capabilities. Anyone holding the unguessable URL can read it.
+
+The full agent contract lives at <https://ausca.com/SKILL.md>; discover the
+active offers at <https://ausca.com/catalog.json>. The npm equivalent is
+[`ausca`](https://www.npmjs.com/package/ausca), which adds a local MCP
+server (`npx ausca mcp`).
+
+## License
+
+MIT

ausca-0.0.2/README.md

@@ -0,0 +1,80 @@
+# ausca
+
+Client for [Ausca](https://ausca.com) metered agent infrastructure services:
+document OCR, document analysis, media transcription, browser sessions, and
+agent inboxes. Paid per call under a hard USD cap you set, with no account
+or provider API keys, and a settlement receipt on every completed
+invocation.
+
+## Install
+
+```bash
+pip install ausca
+```
+
+## Use
+
+```python
+import os
+from ausca import AuscaClient
+
+client = AuscaClient.with_local_key(
+    private_key=os.environ["AUSCA_PRIVATE_KEY"],  # pays USDC on Base
+    max_payment_usd=0.50,                         # hard per-call cap
+)
+
+outcome = client.invoke("browser.session", {"duration_seconds": 600})
+print(outcome.result)
+print(outcome.payment.transaction)  # settlement proof
+```
+
+`invoke` resolves the offer's immutable revision, schema digests, and
+payable route from the live catalog, reads the exact payment requirement,
+pays it if it fits the cap, and retries the same bytes with the same
+idempotency key. Each call starts with a fresh key. For recovery after an
+uncertain response, pass the same caller-owned `idempotency_key`; use a new
+key for another intentional purchase, even when its input is identical.
+
+A CLI ships with the package:
+
+```bash
+ausca catalog
+ausca price document.ocr
+AUSCA_PRIVATE_KEY=0x... AUSCA_MAX_PAYMENT_USD=0.50 \
+  ausca invoke browser.session '{"duration_seconds":600}'
+# Reuse this key only to recover that same intended purchase:
+ausca invoke browser.session '{"duration_seconds":600}' \
+  --idempotency-key browser-attempt-20260903-0001
+```
+
+## Payment rails
+
+Payment is a pluggable authority, never a client concern. The built-in
+`LocalKeyAuthority` pays x402 v2 with a local signing key through the
+official [`x402`](https://pypi.org/project/x402/) library, which enforces
+the cap through its spend controls before anything is signed; other rails
+implement the same small `PaymentAuthority` protocol.
+`client.pay_request(url, ...)` runs one paid call against any resource the
+configured authority can pay; nothing in it is vendor-specific.
+
+## Artifact-backed offers
+
+Document and media offers take an immutable artifact commitment instead of
+raw bytes. `ausca commit file.pdf` sends the bytes to Ausca's keyless
+temporary ingress and returns the commitment the offer input carries; the
+library equivalent is `client.commit(data, media_type)`. Repeating the same
+bytes is idempotent. The active offer catalog sets the usable input limit.
+
+Successful paid state includes `receipt_ref.public_url`, an immutable
+hash-only proof of the Ausca service, public price, completion time, and
+receipt digest. It contains no request or result bytes, content digests, or
+access capabilities. Anyone holding the unguessable URL can read it.
+
+The full agent contract lives at <https://ausca.com/SKILL.md>; discover the
+active offers at <https://ausca.com/catalog.json>. The npm equivalent is
+[`ausca`](https://www.npmjs.com/package/ausca), which adds a local MCP
+server (`npx ausca mcp`).
+
+## License
+
+MIT

ausca-0.0.2/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ausca"
+version = "0.0.2"
+description = "Client for Ausca metered agent infrastructure services: catalog-bound invocations paid per call under a hard USD cap, through pluggable payment authorities (x402 v2 today), with receipt-backed results."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["ausca", "x402", "agents", "payments", "mcp"]
+dependencies = [
+  "httpx>=0.28",
+  "x402[evm]>=2.21.0",
+  "eth-account>=0.13",
+]
+
+[project.scripts]
+ausca = "ausca.cli:main"
+
+[project.urls]
+Homepage = "https://ausca.com"
+Documentation = "https://ausca.com/docs"
+Repository = "https://github.com/auscahq/ausca-integrations"
+Issues = "https://github.com/auscahq/ausca-integrations/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ausca-0.0.2/setup.cfg

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

ausca-0.0.2/src/ausca/__init__.py

@@ -0,0 +1,47 @@
+"""Ausca: metered agent infrastructure services, paid per call."""
+
+from ausca.artifacts import (
+    MAX_ARTIFACT_BYTES,
+    ArtifactCommitment,
+    ArtifactError,
+    ArtifactStore,
+    AuscaArtifactStore,
+)
+from ausca.client import (
+    CATALOG_URL,
+    ORIGIN,
+    SKILL_URL,
+    AuscaClient,
+    AuscaError,
+    InvocationResult,
+    Offer,
+    Price,
+    PriceOption,
+)
+from ausca.payment import (
+    InertAuthority,
+    LocalKeyAuthority,
+    PaymentAuthority,
+    PaymentReceipt,
+)
+
+__all__ = [
+    "ArtifactCommitment",
+    "ArtifactError",
+    "ArtifactStore",
+    "AuscaArtifactStore",
+    "AuscaClient",
+    "AuscaError",
+    "CATALOG_URL",
+    "InertAuthority",
+    "InvocationResult",
+    "LocalKeyAuthority",
+    "ORIGIN",
+    "Offer",
+    "PaymentAuthority",
+    "PaymentReceipt",
+    "Price",
+    "PriceOption",
+    "MAX_ARTIFACT_BYTES",
+    "SKILL_URL",
+]

ausca-0.0.2/src/ausca/artifacts.py

@@ -0,0 +1,97 @@
+"""Artifact commitments for document and media offers.
+
+Artifact-backed offers take an immutable input commitment instead of raw
+bytes. This port turns bytes into that commitment; Ausca's keyless ingress is
+the default implementation and custom stores remain an explicit seam.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from dataclasses import dataclass
+from typing import Protocol
+
+import httpx
+
+AUSCA_ORIGIN = "https://ausca.com"
+MAX_ARTIFACT_BYTES = 25 * 1024 * 1024
+
+
+class ArtifactError(Exception):
+    """A refused or failed artifact operation."""
+
+
+@dataclass(frozen=True)
+class ArtifactCommitment:
+    """The immutable input commitment an artifact-backed offer requires."""
+
+    artifact_ref: str
+    content_digest: str
+    media_type: str
+
+
+class ArtifactStore(Protocol):
+    """Stores bytes and returns the commitment the invocation input carries."""
+
+    def commit(self, data: bytes, media_type: str) -> ArtifactCommitment: ...
+
+
+class AuscaArtifactStore:
+    """Commits bytes through Ausca's keyless temporary artifact ingress."""
+
+    def __init__(
+        self,
+        *,
+        origin: str = AUSCA_ORIGIN,
+        http: httpx.Client | None = None,
+    ) -> None:
+        self._origin = origin.rstrip("/")
+        self._http = http or httpx.Client(timeout=120)
+
+    def commit(self, data: bytes, media_type: str) -> ArtifactCommitment:
+        if not data or len(data) > MAX_ARTIFACT_BYTES:
+            raise ArtifactError(f"artifact must contain 1 to {MAX_ARTIFACT_BYTES} bytes")
+        if not media_type or media_type.strip() != media_type or len(media_type) > 200:
+            raise ArtifactError("artifact media type is invalid")
+        digest_hex = hashlib.sha256(data).hexdigest()
+        content_digest = f"sha256:{digest_hex}"
+        request_hex = hashlib.sha256(
+            f"{content_digest}\n{media_type}".encode()
+        ).hexdigest()
+        response = self._http.post(
+            f"{self._origin}/v1/artifacts",
+            json={
+                "data_base64": base64.b64encode(data).decode(),
+                "content_digest": content_digest,
+                "media_type": media_type,
+                "idempotency_key": f"ausca-artifact-{request_hex[:32]}",
+            },
+        )
+        if response.status_code >= 400:
+            raise ArtifactError(
+                f"artifact ingress answered {response.status_code}: {response.text[:512]}"
+            )
+        try:
+            result = response.json()
+        except ValueError as error:
+            raise ArtifactError("artifact ingress answered non-JSON") from error
+        if set(result) != {"status", "artifact"} or result["status"] != "stored":
+            raise ArtifactError("artifact ingress returned malformed evidence")
+        evidence = result["artifact"]
+        if not isinstance(evidence, dict) or set(evidence) != {
+            "artifact_ref", "content_digest", "created_at", "media_type", "size_bytes"
+        }:
+            raise ArtifactError("artifact ingress returned malformed evidence")
+        artifact_ref = f"runx:artifact:{content_digest}"
+        if (
+            evidence["artifact_ref"] != artifact_ref
+            or evidence["content_digest"] != content_digest
+            or evidence["media_type"] != media_type
+            or evidence["size_bytes"] != len(data)
+            or not isinstance(evidence["created_at"], str)
+        ):
+            raise ArtifactError("artifact ingress returned mismatched evidence")
+        return ArtifactCommitment(
+            artifact_ref=artifact_ref, content_digest=content_digest, media_type=media_type
+        )

ausca-0.0.2/src/ausca/cli.py

@@ -0,0 +1,181 @@
+"""The front-door verbs, mirroring the npm ``ausca`` bin.
+
+Configuration is environment only: a signing key and a mandatory per-call
+USD cap for paying verbs, nothing else. Artifact commits are keyless. Output
+is JSON on stdout.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Mapping, TextIO
+
+from ausca.client import AuscaClient, ORIGIN
+
+USAGE = """ausca: metered agent infrastructure services, paid per call
+
+  ausca catalog                    active offers, prices, routes
+  ausca price <offer-id>           published price policy
+  ausca invoke <offer-id> [input] [--idempotency-key <key>]
+                                     paid invocation; input inline, @file, or stdin
+  ausca commit <file>              artifact commitment for document and media offers
+
+Environment: AUSCA_PRIVATE_KEY and AUSCA_MAX_PAYMENT_USD pay invocations;
+AUSCA_NETWORK overrides the payment network; AUSCA_ORIGIN overrides the service.
+The MCP server ships in the npm package: npx ausca mcp."""
+
+MEDIA_TYPES = {
+    "pdf": "application/pdf",
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "tif": "image/tiff",
+    "tiff": "image/tiff",
+    "txt": "text/plain",
+    "md": "text/markdown",
+    "html": "text/html",
+    "csv": "text/csv",
+    "json": "application/json",
+    "mp3": "audio/mpeg",
+    "wav": "audio/wav",
+    "m4a": "audio/mp4",
+    "flac": "audio/flac",
+    "ogg": "audio/ogg",
+    "mp4": "video/mp4",
+    "mov": "video/quicktime",
+    "webm": "video/webm",
+    "mkv": "video/x-matroska",
+}
+
+
+def media_type_for(name: str) -> str:
+    return MEDIA_TYPES.get(name.lower().rsplit(".", 1)[-1], "application/octet-stream")
+
+
+def _client(env: Mapping[str, str], *, require_payment: bool = False) -> AuscaClient:
+    origin = env.get("AUSCA_ORIGIN", ORIGIN)
+    key = env.get("AUSCA_PRIVATE_KEY")
+    if not key:
+        if require_payment:
+            raise SystemExit(
+                "paid invocations need AUSCA_PRIVATE_KEY and AUSCA_MAX_PAYMENT_USD"
+                " in the environment"
+            )
+        return AuscaClient(origin=origin)
+    try:
+        cap = float(env.get("AUSCA_MAX_PAYMENT_USD", ""))
+    except ValueError:
+        cap = 0.0
+    if cap <= 0:
+        raise SystemExit(
+            "AUSCA_MAX_PAYMENT_USD must be a positive USD amount when"
+            " AUSCA_PRIVATE_KEY is set; refusing to guess a spend limit"
+        )
+    return AuscaClient.with_local_key(
+        private_key=key,
+        max_payment_usd=cap,
+        network=env.get("AUSCA_NETWORK", "eip155:8453"),
+        origin=origin,
+    )
+
+
+def _json(value: Any) -> str:
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        value = dataclasses.asdict(value)
+    return json.dumps(value, indent=2, default=lambda item: dataclasses.asdict(item))
+
+
+def _resolve_input(argument: str | None, stdin: TextIO) -> dict[str, Any]:
+    if argument is None or argument == "-":
+        text = stdin.read()
+    elif argument.startswith("@"):
+        text = Path(argument[1:]).read_text()
+    else:
+        text = argument
+    try:
+        return json.loads(text)
+    except ValueError as error:
+        raise SystemExit("invocation input must be valid JSON") from error
+
+
+def _invocation_args(argv: list[str]) -> tuple[str, str | None, str | None]:
+    if not argv:
+        raise SystemExit(
+            "usage: ausca invoke <offer-id> [input] [--idempotency-key <key>]"
+        )
+    offer_id = argv[0]
+    input_argument: str | None = None
+    idempotency_key: str | None = None
+    index = 1
+    while index < len(argv):
+        argument = argv[index]
+        if argument == "--idempotency-key":
+            if idempotency_key is not None or index + 1 >= len(argv):
+                raise SystemExit("--idempotency-key requires one value")
+            idempotency_key = argv[index + 1]
+            index += 2
+        elif input_argument is None:
+            input_argument = argument
+            index += 1
+        else:
+            raise SystemExit(f"unexpected invoke argument {argument}")
+    return offer_id, input_argument, idempotency_key
+
+
+def run(
+    argv: list[str],
+    env: Mapping[str, str],
+    stdout: TextIO,
+    stdin: TextIO,
+) -> int:
+    verb = argv[0] if argv else None
+    if verb in (None, "help", "--help"):
+        print(USAGE, file=stdout)
+        return 1 if verb is None else 0
+    if verb == "catalog":
+        offers = _client(env).catalog().get("offers", [])
+        listing = [
+            {key: offer.get(key) for key in ("offer_id", "title", "route", "price", "revision")}
+            for offer in offers
+        ]
+        print(_json(listing), file=stdout)
+        return 0
+    if verb == "price":
+        if len(argv) < 2:
+            raise SystemExit("usage: ausca price <offer-id>")
+        print(_json(_client(env).price(argv[1])), file=stdout)
+        return 0
+    if verb == "invoke":
+        offer_id, input_argument, idempotency_key = _invocation_args(argv[1:])
+        client = _client(env, require_payment=True)
+        outcome = client.invoke(
+            offer_id,
+            _resolve_input(input_argument, stdin),
+            idempotency_key=idempotency_key,
+        )
+        print(_json(outcome), file=stdout)
+        return 0
+    if verb == "commit":
+        if len(argv) < 2:
+            raise SystemExit("usage: ausca commit <file>")
+        path = Path(argv[1])
+        commitment = _client(env).commit(path.read_bytes(), media_type_for(path.name))
+        print(_json(commitment), file=stdout)
+        return 0
+    raise SystemExit(f"unknown verb {verb}; run ausca help")
+
+
+def main() -> None:
+    try:
+        sys.exit(run(sys.argv[1:], os.environ, sys.stdout, sys.stdin))
+    except SystemExit:
+        raise
+    except Exception as error:  # noqa: BLE001 - the CLI boundary reports and exits
+        print(str(error), file=sys.stderr)
+        sys.exit(1)