sarnai 0.1.0__py3-none-any.whl

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/_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/_version.py

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

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+sarnai/__init__.py,sha256=Vradio4W3kvrO3XZNkMe2PKc1TdzFfAUcwdDUGf3m9k,358
+sarnai/_tools.py,sha256=BNTHSoV4n5L3bZDRjR_ffDhzO2L0H874VM56nL2vlKI,2712
+sarnai/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+sarnai/client.py,sha256=tt-O1jdMdYIG49r7s0Q9POzvEoq3gXqJo0qmSrEPjas,7138
+sarnai/crewai.py,sha256=k8R3KS8_EMFcICHVKre-3wgn40anRvo468wxhAUl3ss,1533
+sarnai/langchain.py,sha256=YcwooXvMgXssidLt9xgyNsytLhqKQj706sW9KiJhNrY,896
+sarnai/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sarnai-0.1.0.dist-info/METADATA,sha256=tWpMPmyaPW3i4q4gmbJBNSQy_lr3bOrGtzwPy_AR9o8,2846
+sarnai-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sarnai-0.1.0.dist-info/licenses/LICENSE,sha256=DZX5mmhScozvQJp-RS_dbA_t5FjG8HN4wyJ8IVIosAg,1064
+sarnai-0.1.0.dist-info/RECORD,,

sarnai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

sarnai-0.1.0.dist-info/licenses/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.