sarnai 0.1.0__tar.gz

sarnai-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

sarnai-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -m "not live"

sarnai-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

sarnai-0.1.0/CLAUDE.md

@@ -0,0 +1,20 @@
+# CLAUDE.md
+
+Project: the official SarnAI Python package, published to PyPI as `sarnai`.
+The brand is always written "SarnAI"; code names (package, modules, functions) are lowercase.
+
+## Prompt rules
+
+- One goal per prompt. Do that goal, then report and stop.
+- The user approves every push. Commit locally on a branch; never push without explicit approval.
+- No secrets in chat. Never ask for, print, or commit API keys or tokens; read them from the environment.
+- Give results in copy-paste format: plain text or commands in fenced code blocks.
+
+## API sources
+
+Learn the public SarnAI APIs only from:
+
+- https://board.sarnai.dev/llms.txt
+- https://verify.sarnai.dev/llms.txt
+
+Do not read other repos to infer API behavior, and do not guess endpoints.

sarnai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mglbagi
+
+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.

sarnai-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: sarnai
+Version: 0.1.0
+Summary: Official SarnAI Python package: find agent services on the Agent Discovery Board and verify agent output.
+Project-URL: Homepage, https://github.com/sarnai-dev/sarnai-python
+Project-URL: Board, https://board.sarnai.dev
+Project-URL: Verifier, https://verify.sarnai.dev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai-agents,crewai,langchain,sarnai,verification,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.100; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# sarnai
+
+Official SarnAI Python package: find agent services on the
+[Agent Discovery Board](https://board.sarnai.dev) and verify agent output with the
+[Agent Output Verifier](https://verify.sarnai.dev). No account or secrets needed.
+
+```
+pip install sarnai                 # client only (httpx)
+pip install sarnai[langchain]      # + LangChain tools
+pip install sarnai[crewai]         # + CrewAI tools
+```
+
+## LangChain in 10 lines
+
+```python
+from langchain.agents import create_agent
+from sarnai.langchain import find_service, verify_output
+
+agent = create_agent("anthropic:claude-sonnet-5-5", tools=[find_service, verify_output])
+reply = agent.invoke({"messages": [
+    {"role": "user", "content": "Find a service that extracts invoice data, "
+     "then check this output against {\"type\":\"object\",\"required\":[\"total\"]}: {\"total\": 42}"}]})
+print(reply["messages"][-1].content)
+```
+
+CrewAI: `from sarnai.crewai import find_service, verify_output`.
+
+## Client
+
+```python
+from sarnai import SarnAIClient
+
+with SarnAIClient() as sarnai:
+    page = sarnai.search_listings("invoice extraction", limit=5)   # GET /listings
+    listing = sarnai.get_listing(page["listings"][0]["id"])        # GET /listings/{id}
+    result = sarnai.verify_output(                                 # POST /verify/schema
+        {"type": "object", "required": ["total"]}, {"total": 42})
+    print(result.passed, result.hints)
+```
+
+Verification is free during launch (daily allowance per caller, see the
+[verifier docs](https://verify.sarnai.dev/llms.txt)); beyond it the service answers 402 and the
+client raises `PaymentRequiredError`. Errors raise `SarnAIError` with `status` and `code`.
+
+## Tests
+
+```
+pytest                  # everything, including live calls to the SarnAI services
+pytest -m "not live"    # offline only
+```
+
+## License
+
+MIT

sarnai-0.1.0/README.md

@@ -0,0 +1,54 @@
+# sarnai
+
+Official SarnAI Python package: find agent services on the
+[Agent Discovery Board](https://board.sarnai.dev) and verify agent output with the
+[Agent Output Verifier](https://verify.sarnai.dev). No account or secrets needed.
+
+```
+pip install sarnai                 # client only (httpx)
+pip install sarnai[langchain]      # + LangChain tools
+pip install sarnai[crewai]         # + CrewAI tools
+```
+
+## LangChain in 10 lines
+
+```python
+from langchain.agents import create_agent
+from sarnai.langchain import find_service, verify_output
+
+agent = create_agent("anthropic:claude-sonnet-5-5", tools=[find_service, verify_output])
+reply = agent.invoke({"messages": [
+    {"role": "user", "content": "Find a service that extracts invoice data, "
+     "then check this output against {\"type\":\"object\",\"required\":[\"total\"]}: {\"total\": 42}"}]})
+print(reply["messages"][-1].content)
+```
+
+CrewAI: `from sarnai.crewai import find_service, verify_output`.
+
+## Client
+
+```python
+from sarnai import SarnAIClient
+
+with SarnAIClient() as sarnai:
+    page = sarnai.search_listings("invoice extraction", limit=5)   # GET /listings
+    listing = sarnai.get_listing(page["listings"][0]["id"])        # GET /listings/{id}
+    result = sarnai.verify_output(                                 # POST /verify/schema
+        {"type": "object", "required": ["total"]}, {"total": 42})
+    print(result.passed, result.hints)
+```
+
+Verification is free during launch (daily allowance per caller, see the
+[verifier docs](https://verify.sarnai.dev/llms.txt)); beyond it the service answers 402 and the
+client raises `PaymentRequiredError`. Errors raise `SarnAIError` with `status` and `code`.
+
+## Tests
+
+```
+pytest                  # everything, including live calls to the SarnAI services
+pytest -m "not live"    # offline only
+```
+
+## License
+
+MIT

sarnai-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sarnai"
+dynamic = ["version"]
+description = "Official SarnAI Python package: find agent services on the Agent Discovery Board and verify agent output."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+keywords = ["sarnai", "agents", "ai-agents", "verification", "x402", "langchain", "crewai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[tool.hatch.version]
+path = "src/sarnai/_version.py"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+crewai = ["crewai>=0.100"]
+dev = ["pytest>=8", "langchain-core>=0.3"]
+
+[project.urls]
+Homepage = "https://github.com/sarnai-dev/sarnai-python"
+Board = "https://board.sarnai.dev"
+Verifier = "https://verify.sarnai.dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sarnai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["live: calls the live SarnAI services (skip with: pytest -m 'not live')"]

sarnai-0.1.0/src/sarnai/__init__.py

@@ -0,0 +1,8 @@
+"""SarnAI: find agent services and verify agent output."""
+
+from ._version import __version__
+from .client import (BOARD_URL, VERIFY_URL, PaymentRequiredError, SarnAIClient,
+                     SarnAIError, VerifyResult)
+
+__all__ = ["SarnAIClient", "SarnAIError", "PaymentRequiredError", "VerifyResult",
+           "BOARD_URL", "VERIFY_URL", "__version__"]

sarnai-0.1.0/src/sarnai/_tools.py

@@ -0,0 +1,74 @@
+"""Framework-neutral logic shared by the LangChain and CrewAI tools."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .client import SarnAIClient, SarnAIError
+
+FIND_SERVICE_DESCRIPTION = (
+    "Find AI agent services on the SarnAI Agent Discovery Board (MCP servers, x402 "
+    "services, REST APIs). Input: plain-words query. Returns JSON with matching "
+    "listings: id, name, description, endpoint_url, connection types, payment types."
+)
+
+VERIFY_OUTPUT_DESCRIPTION = (
+    "Verify an agent's JSON output against a JSON Schema with the SarnAI Agent Output "
+    "Verifier (free REST check). Input: expected_schema (JSON Schema, object or JSON "
+    "string) and submitted_output (the output to check, as JSON). Returns JSON with "
+    "result pass/fail, errors, and fix hints."
+)
+
+_LISTING_KEYS = ("id", "name", "description", "listing_type", "task_categories",
+                 "endpoint_url", "pricing_amount", "stale")
+
+
+def _load(value: Any) -> Any:
+    """Models often pass JSON as a string; accept both."""
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except ValueError:
+            return value
+    return value
+
+
+def find_service(query: str, limit: int = 5, *, client: SarnAIClient | None = None) -> str:
+    own = client or SarnAIClient()
+    try:
+        page = own.search_listings(query, limit=limit)
+    except SarnAIError as exc:
+        return json.dumps({"error": str(exc)})
+    finally:
+        if client is None:
+            own.close()
+    listings = []
+    for item in page.get("listings", []):
+        row = {k: item.get(k) for k in _LISTING_KEYS}
+        row["connection_types"] = [c.get("type") for c in item.get("connections") or []]
+        row["payment_types"] = [p.get("type") for p in item.get("payment_methods") or []]
+        listings.append(row)
+    return json.dumps({"total": page.get("total"), "listings": listings})
+
+
+def verify_output(expected_schema: Any, submitted_output: Any, *,
+                  client: SarnAIClient | None = None) -> str:
+    schema = _load(expected_schema)
+    if not isinstance(schema, dict):
+        return json.dumps({"error": "expected_schema must be a JSON Schema object"})
+    own = client or SarnAIClient()
+    try:
+        result = own.verify_output(schema, _load(submitted_output))
+    except SarnAIError as exc:
+        return json.dumps({"error": str(exc)})
+    finally:
+        if client is None:
+            own.close()
+    return json.dumps({
+        "result": result.result,
+        "verification_id": result.verification_id,
+        "errors": result.errors,
+        "hints": result.hints,
+        "next_actions": result.raw.get("next_actions", []),
+    })

sarnai-0.1.0/src/sarnai/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sarnai-0.1.0/src/sarnai/client.py

@@ -0,0 +1,192 @@
+"""HTTP client for the SarnAI Agent Discovery Board and Agent Output Verifier."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Iterable
+
+import httpx
+
+from ._version import __version__
+
+BOARD_URL = "https://board.sarnai.dev"
+VERIFY_URL = "https://verify.sarnai.dev"
+USER_AGENT = f"sarnai-python/{__version__}"
+
+
+class SarnAIError(Exception):
+    """A SarnAI service returned an error (or an unreadable response)."""
+
+    def __init__(self, message: str, *, status: int | None = None,
+                 code: str | None = None, payload: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.payload = payload
+
+
+class PaymentRequiredError(SarnAIError):
+    """HTTP 402: the free allowance is used up and x402 payment is needed."""
+
+
+@dataclass
+class VerifyResult:
+    """Outcome of a verification. `raw` is the full signed response."""
+
+    result: str
+    verification_id: str
+    task_id: str
+    raw: dict[str, Any] = field(repr=False)
+
+    @property
+    def passed(self) -> bool:
+        return self.result == "pass"
+
+    @property
+    def errors(self) -> list[Any]:
+        return self.raw.get("errors") or []
+
+    @property
+    def hints(self) -> list[Any]:
+        return self.raw.get("hints") or []
+
+    @property
+    def attestation(self) -> dict[str, Any]:
+        return self.raw.get("attestation") or {}
+
+
+def _clean(params: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}
+
+
+class SarnAIClient:
+    """Find services on the board and verify outputs. No secrets needed.
+
+    >>> with SarnAIClient() as sarnai:
+    ...     page = sarnai.search_listings("invoice extraction", limit=5)
+    """
+
+    def __init__(self, *, board_url: str = BOARD_URL, verify_url: str = VERIFY_URL,
+                 timeout: float = 30.0, client: httpx.Client | None = None,
+                 transport: httpx.BaseTransport | None = None):
+        self.board_url = board_url.rstrip("/")
+        self.verify_url = verify_url.rstrip("/")
+        self._owns_client = client is None
+        self._http = client or httpx.Client(timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "SarnAIClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- board ---------------------------------------------------------------
+
+    def search_listings(
+        self,
+        q: str | None = None,
+        *,
+        listing_type: str | None = None,
+        task_category: str | Iterable[str] | None = None,
+        connection_type: str | Iterable[str] | None = None,
+        payment_type: str | Iterable[str] | None = None,
+        status: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        """GET /listings. Returns {listings, total, limit, offset, next_cursor}.
+
+        Without `q`, newest activity first; with `q`, ranked full-text search.
+        Pass `next_cursor` back as `cursor` for the next page (with the same `q`).
+        """
+        params: dict[str, Any] = _clean({
+            "q": q, "listing_type": listing_type, "status": status,
+            "limit": limit, "cursor": cursor,
+        })
+        for key, value in (("task_category", task_category),
+                           ("connection_type", connection_type),
+                           ("payment_type", payment_type)):
+            if value is not None:
+                params[key] = [value] if isinstance(value, str) else list(value)
+        return self._request("GET", f"{self.board_url}/listings", params=params)
+
+    def get_listing(self, listing_id: str) -> dict[str, Any]:
+        """GET /listings/{id}."""
+        return self._request("GET", f"{self.board_url}/listings/{listing_id}")
+
+    # -- verifier ------------------------------------------------------------
+
+    def verify_output(
+        self,
+        expected_schema: dict[str, Any],
+        submitted_output: Any,
+        *,
+        task_id: str | None = None,
+        agent_id: str | None = None,
+        rules: list[dict[str, Any]] | None = None,
+        bounds: dict[str, Any] | None = None,
+        enforce_rules: bool | None = None,
+        strict_content_check: bool | None = None,
+        compact: bool = False,
+        endpoint: str = "schema",
+    ) -> VerifyResult:
+        """POST /verify/schema (or /verify/deliverable with endpoint="deliverable").
+
+        Free during launch (see the verifier's llms.txt for the daily allowance).
+        Beyond it the service answers 402 and this raises PaymentRequiredError.
+        """
+        if endpoint not in ("schema", "deliverable"):
+            raise ValueError("endpoint must be 'schema' or 'deliverable'")
+        body = _clean({
+            "task_id": task_id or str(uuid.uuid4()),
+            "expected_schema": expected_schema,
+            "submitted_output": submitted_output,
+            "agent_id": agent_id,
+            "rules": rules,
+            "bounds": bounds,
+            "enforce_rules": enforce_rules,
+            "strict_content_check": strict_content_check,
+            "detail": "compact" if compact else None,
+        })
+        # submitted_output may legitimately be null; _clean would drop it.
+        body["submitted_output"] = submitted_output
+        data = self._request("POST", f"{self.verify_url}/verify/{endpoint}", json=body)
+        return VerifyResult(
+            result=data["result"],
+            verification_id=data.get("verification_id", ""),
+            task_id=data.get("task_id", body["task_id"]),
+            raw=data,
+        )
+
+    def reputation(self, agent_id: str) -> dict[str, Any]:
+        """GET /reputation/{agent_id}: free pass/fail call history."""
+        return self._request("GET", f"{self.verify_url}/reputation/{agent_id}")
+
+    # -- internals -----------------------------------------------------------
+
+    def _request(self, method: str, url: str, **kwargs: Any) -> Any:
+        try:
+            response = self._http.request(
+                method, url, headers={"User-Agent": USER_AGENT}, **kwargs)
+        except httpx.HTTPError as exc:
+            raise SarnAIError(f"request to {url} failed: {exc}") from exc
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        if response.is_success:
+            if payload is None:
+                raise SarnAIError("response was not JSON", status=response.status_code)
+            return payload
+        # Board errors use `error_code`, the verifier uses `code`.
+        info = payload if isinstance(payload, dict) else {}
+        code = info.get("error_code") or info.get("code")
+        message = info.get("message") or response.text[:200] or "request failed"
+        cls = PaymentRequiredError if response.status_code == 402 else SarnAIError
+        raise cls(f"{response.status_code} {code or ''}: {message}".replace("  ", " "),
+                  status=response.status_code, code=code, payload=payload)

sarnai-0.1.0/src/sarnai/crewai.py

@@ -0,0 +1,47 @@
+"""CrewAI tools. Install with: pip install sarnai[crewai]"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from crewai.tools import BaseTool
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("Install the extra: pip install sarnai[crewai]") from exc
+from pydantic import BaseModel, Field
+
+from . import _tools
+
+
+class _FindServiceArgs(BaseModel):
+    query: str = Field(description="What you need, in plain words")
+    limit: int = Field(default=5, description="Maximum listings to return")
+
+
+class _VerifyOutputArgs(BaseModel):
+    expected_schema: Any = Field(description="JSON Schema the output must satisfy")
+    submitted_output: Any = Field(description="The output to verify, as JSON")
+
+
+class FindServiceTool(BaseTool):
+    name: str = "find_service"
+    description: str = _tools.FIND_SERVICE_DESCRIPTION
+    args_schema: type[BaseModel] = _FindServiceArgs
+
+    def _run(self, query: str, limit: int = 5) -> str:
+        return _tools.find_service(query, limit)
+
+
+class VerifyOutputTool(BaseTool):
+    name: str = "verify_output"
+    description: str = _tools.VERIFY_OUTPUT_DESCRIPTION
+    args_schema: type[BaseModel] = _VerifyOutputArgs
+
+    def _run(self, expected_schema: Any, submitted_output: Any) -> str:
+        return _tools.verify_output(expected_schema, submitted_output)
+
+
+find_service = FindServiceTool()
+verify_output = VerifyOutputTool()
+tools = [find_service, verify_output]
+__all__ = ["FindServiceTool", "VerifyOutputTool", "find_service", "verify_output", "tools"]

sarnai-0.1.0/src/sarnai/langchain.py

@@ -0,0 +1,32 @@
+"""LangChain tools. Install with: pip install sarnai[langchain]"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from langchain_core.tools import StructuredTool
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("Install the extra: pip install sarnai[langchain]") from exc
+
+from . import _tools
+
+find_service = StructuredTool.from_function(
+    func=lambda query, limit=5: _tools.find_service(query, limit),
+    name="find_service",
+    description=_tools.FIND_SERVICE_DESCRIPTION,
+)
+
+
+def _verify(expected_schema: Any, submitted_output: Any) -> str:
+    return _tools.verify_output(expected_schema, submitted_output)
+
+
+verify_output = StructuredTool.from_function(
+    func=_verify,
+    name="verify_output",
+    description=_tools.VERIFY_OUTPUT_DESCRIPTION,
+)
+
+tools = [find_service, verify_output]
+__all__ = ["find_service", "verify_output", "tools"]

sarnai-0.1.0/tests/test_live.py

@@ -0,0 +1,54 @@
+"""Tests against the live SarnAI services. Skip with: pytest -m "not live"."""
+
+import json
+
+import pytest
+
+from sarnai import SarnAIClient, SarnAIError
+
+pytestmark = pytest.mark.live
+
+SCHEMA = {"type": "object", "required": ["total"], "properties": {"total": {"type": "number"}}}
+
+
+@pytest.fixture
+def client():
+    with SarnAIClient() as c:
+        yield c
+
+
+def test_search_and_get_listing(client):
+    page = client.search_listings("verify", limit=2)
+    assert page["listings"] and "next_cursor" in page
+    listing = client.get_listing(page["listings"][0]["id"])
+    assert listing["id"] == page["listings"][0]["id"]
+
+
+def test_get_missing_listing(client):
+    with pytest.raises(SarnAIError) as info:
+        client.get_listing("00000000-0000-0000-0000-000000000000")
+    assert info.value.status in (404, 422)
+
+
+def test_verify_pass_and_fail(client):
+    # agent_id with the reserved 'test-' prefix is never recorded.
+    ok = client.verify_output(SCHEMA, {"total": 3}, agent_id="test-sarnai-python")
+    bad = client.verify_output(SCHEMA, {"total": "x"}, agent_id="test-sarnai-python")
+    assert ok.passed and not bad.passed
+    assert bad.attestation["algorithm"] == "Ed25519"
+
+
+def test_tools_end_to_end():
+    from sarnai import _tools
+
+    found = json.loads(_tools.find_service("verification", 2))
+    assert found["listings"]
+    res = json.loads(_tools.verify_output(SCHEMA, {"total": 1}))
+    assert res["result"] == "pass"
+
+
+def test_compact_detail(client):
+    res = client.verify_output(SCHEMA, {"total": "x"}, agent_id="test-sarnai-python",
+                               compact=True)
+    assert not res.passed and "errors" not in res.raw
+    assert res.attestation["algorithm"] == "Ed25519"

sarnai-0.1.0/tests/test_offline.py

@@ -0,0 +1,87 @@
+import json
+
+import httpx
+import pytest
+
+from sarnai import PaymentRequiredError, SarnAIClient, SarnAIError
+from sarnai import _tools
+
+
+def make_client(handler):
+    return SarnAIClient(transport=httpx.MockTransport(handler))
+
+
+def test_search_builds_query():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = request.url
+        return httpx.Response(200, json={"listings": [], "total": 0})
+
+    make_client(handler).search_listings("invoice", task_category=["a", "b"], limit=3)
+    assert seen["url"].path == "/listings"
+    assert seen["url"].params["q"] == "invoice"
+    assert seen["url"].params.get_list("task_category") == ["a", "b"]
+    assert seen["url"].params["limit"] == "3"
+
+
+def test_board_error_code():
+    client = make_client(lambda r: httpx.Response(
+        404, json={"error_code": "not_found", "message": "No such listing"}))
+    with pytest.raises(SarnAIError) as info:
+        client.get_listing("x")
+    assert info.value.code == "not_found" and info.value.status == 404
+
+
+def test_verify_402_and_body():
+    seen = {}
+
+    def handler(request):
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(402, json={"error_code": "no_payment", "message": "pay"})
+
+    with pytest.raises(PaymentRequiredError):
+        make_client(handler).verify_output({"type": "object"}, None, compact=True)
+    assert "submitted_output" in seen["body"] and seen["body"]["detail"] == "compact"
+    assert seen["body"]["task_id"]
+
+
+def test_verify_result():
+    client = make_client(lambda r: httpx.Response(200, json={
+        "result": "pass", "verification_id": "v", "task_id": "t"}))
+    assert client.verify_output({"type": "object"}, {}).passed
+
+
+def test_tool_helpers_accept_json_strings():
+    def handler(request):
+        return httpx.Response(200, json={"result": "fail", "verification_id": "v",
+                                         "task_id": "t", "errors": ["e"], "hints": []})
+
+    out = json.loads(_tools.verify_output('{"type": "object"}', '{"a": 1}',
+                                          client=make_client(handler)))
+    assert out["result"] == "fail" and out["errors"] == ["e"]
+    assert "error" in json.loads(_tools.verify_output("nope", {}))
+
+
+def test_langchain_tool_names():
+    pytest.importorskip("langchain_core")
+    from sarnai.langchain import tools
+
+    assert [t.name for t in tools] == ["find_service", "verify_output"]
+
+
+def test_user_agent_on_every_request():
+    import sarnai
+
+    agents = []
+
+    def handler(request):
+        agents.append(request.headers["user-agent"])
+        return httpx.Response(200, json={"result": "pass"})
+
+    client = make_client(handler)
+    client.search_listings("x")
+    client.get_listing("id")
+    client.verify_output({"type": "object"}, {})
+    client.reputation("agent")
+    assert agents == [f"sarnai-python/{sarnai.__version__}"] * 4