osf-agentkit 0.1.0__py3-none-any.whl

osf_agentkit/__init__.py

@@ -0,0 +1,234 @@
+"""OSF (Open Source Filings) action provider for Coinbase AgentKit.
+
+Provenance-stamped "ground truth" tools for AI agents, each paid per call over
+x402 (USDC on Base mainnet) using the agent's own EVM wallet:
+
+  * lookup_entity        - resolve a company/person against authoritative public
+                           registries (CMS NPI, GLEIF LEI, FDIC, SEC EDGAR)
+  * screen_entity        - sanctions/watchlist screening by name (OFAC SDN, EU, UK)
+  * check_cve_exploited  - is a CVE actively exploited (CISA KEV / EPSS / CVSS)
+
+Every result carries a provenance URL to the authoritative primary source (and,
+for sanctions, an audit receipt). Payment is automatic: on a 402 the x402 client
+signs and settles the micropayment with the agent's wallet, then retries. Each
+action is bounded by a per-call spend ceiling.
+
+This is a single-file build of the osf-agentkit package.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+from pydantic import BaseModel, Field
+
+from x402.clients.base import decode_x_payment_response
+from x402.clients.requests import x402_requests
+
+from coinbase_agentkit.action_providers.action_provider import ActionProvider
+from coinbase_agentkit.action_providers.action_decorator import create_action
+from coinbase_agentkit.network import Network
+from coinbase_agentkit.wallet_providers.evm_wallet_provider import EvmWalletProvider
+
+
+class LookupEntitySchema(BaseModel):
+    """Resolve a company or person against authoritative public registries."""
+
+    query: str = Field(
+        ...,
+        description=(
+            "An entity identifier for an exact match, OR a company/person name for "
+            "candidate matches. Accepted identifiers: US healthcare provider NPI "
+            "(10 digits), GLEIF LEI (20 chars), FDIC certificate number, or SEC EDGAR "
+            "CIK. Examples: 'Apple Inc', '254900XAWYYH4QOUWQ70' (LEI), '1174150262' (NPI)."
+        ),
+    )
+
+
+class ScreenEntitySchema(BaseModel):
+    """Sanctions/watchlist screening of a single name."""
+
+    name: str = Field(
+        ...,
+        description=(
+            "Full name of the person or entity to screen against the OFAC SDN, EU "
+            "consolidated, and UK OFSI sanctions lists. Example: 'Vladimir Putin'."
+        ),
+    )
+
+
+class CheckCveExploitedSchema(BaseModel):
+    """Check whether a CVE is actively exploited."""
+
+    cve_id: str = Field(
+        ...,
+        description=(
+            "A CVE identifier in canonical form 'CVE-YYYY-NNNN' (4+ digits in the "
+            "sequence number). Example: 'CVE-2021-44228' (Log4Shell)."
+        ),
+    )
+
+
+# OSF settles on Base mainnet only.
+SUPPORTED_NETWORKS = ["base-mainnet"]
+
+DEFAULT_BASE_URL = "https://api.osf-master-server.com/x402"
+
+# Per-action spend ceilings in atomic USDC (6 decimals: 1_000_000 = $1.00).
+# Headroom over OSF's live prices (entity $0.01, sanctions $0.05, cve $0.02) so a
+# modest price change does not break calls, while capping runaway spend. The
+# x402 client refuses to pay more than this for the call.
+_MAX_ENTITY_ATOMIC = 50_000   # $0.05 ceiling
+_MAX_SCREEN_ATOMIC = 150_000  # $0.15 ceiling
+_MAX_CVE_ATOMIC = 100_000     # $0.10 ceiling
+
+_TIMEOUT_SECONDS = 30
+
+
+class OSF(ActionProvider[EvmWalletProvider]):
+    """Paid access to OSF provenance-stamped government and scientific data.
+
+    Note: AgentKit derives each agent-facing action name as ``{ClassName}_{method}``,
+    so this class is named ``OSF`` to yield clean tool names like ``OSF_lookup_entity``.
+    """
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL) -> None:
+        super().__init__("osf", [])
+        self._base_url = base_url.rstrip("/")
+
+    def supports_network(self, network: Network) -> bool:
+        """OSF endpoints settle on Base mainnet."""
+        return network.network_id in SUPPORTED_NETWORKS
+
+    # ------------------------------------------------------------------ #
+    # internal: a single paid GET with automatic x402 settlement
+    # ------------------------------------------------------------------ #
+    def _paid_get(
+        self,
+        wallet_provider: EvmWalletProvider,
+        path: str,
+        max_value_atomic: int,
+    ) -> str:
+        try:
+            account = wallet_provider.to_signer()
+            session = x402_requests(account, max_value=max_value_atomic)
+            url = f"{self._base_url}{path}"
+            response = session.request(url=url, method="GET", timeout=_TIMEOUT_SECONDS)
+
+            payment = None
+            if "x-payment-response" in response.headers:
+                try:
+                    proof = decode_x_payment_response(response.headers["x-payment-response"])
+                    payment = {
+                        "transaction": proof.get("transaction"),
+                        "network": proof.get("network"),
+                        "payer": proof.get("payer"),
+                    }
+                except Exception:
+                    payment = None
+
+            is_json = "application/json" in response.headers.get("content-type", "")
+            data = response.json() if is_json else response.text
+
+            out: dict[str, Any] = {
+                "success": response.status_code == 200,
+                "status": response.status_code,
+                "data": data,
+            }
+            if payment:
+                out["payment"] = payment
+            return json.dumps(out, indent=2)
+
+        except Exception as error:  # noqa: BLE001 - surface a clean message to the agent
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": str(error),
+                    "hint": (
+                        "Check the agent wallet holds USDC on Base mainnet and that "
+                        "the per-call spend ceiling is high enough for the endpoint price."
+                    ),
+                },
+                indent=2,
+            )
+
+    # ------------------------------------------------------------------ #
+    # actions
+    # ------------------------------------------------------------------ #
+    @create_action(
+        name="lookup_entity",
+        description=(
+            "Resolve and verify a company or person against authoritative public "
+            "registries: US healthcare providers (CMS NPI), global legal entities "
+            "(GLEIF LEI), US banks (FDIC), and SEC filers / public companies (EDGAR "
+            "CIK). Pass an identifier (NPI, LEI, FDIC cert, or CIK) for an exact "
+            "match, or a name for candidate matches. Returns legal name, status, "
+            "type, jurisdiction, key identifiers, and a provenance URL to the official "
+            "source. Use for KYC, KYB, counterparty due-diligence, provider "
+            "verification, and onboarding. Costs a small USDC micropayment per call "
+            "(paid automatically via x402 on Base)."
+        ),
+        schema=LookupEntitySchema,
+    )
+    def lookup_entity(self, wallet_provider: EvmWalletProvider, args: dict[str, Any]) -> str:
+        """Resolve an entity by identifier or name against public registries."""
+        q = quote(str(args["query"]), safe="")
+        return self._paid_get(wallet_provider, f"/identity/entity/{q}", _MAX_ENTITY_ATOMIC)
+
+    @create_action(
+        name="screen_entity",
+        description=(
+            "Sanctions and compliance screening of a single name against the OFAC SDN, "
+            "EU consolidated, and UK OFSI sanctions lists. Returns hit or no-hit, the "
+            "matched list, a provenance URL, and an audit receipt. Use for AML, KYC, "
+            "watchlist, and OFAC compliance checks before moving money or onboarding a "
+            "counterparty. Costs a small USDC micropayment per call (paid automatically "
+            "via x402 on Base)."
+        ),
+        schema=ScreenEntitySchema,
+    )
+    def screen_entity(self, wallet_provider: EvmWalletProvider, args: dict[str, Any]) -> str:
+        """Screen a name against OFAC/EU/UK sanctions lists."""
+        n = quote(str(args["name"]), safe="")
+        return self._paid_get(wallet_provider, f"/screen/sanctions/{n}", _MAX_SCREEN_ATOMIC)
+
+    @create_action(
+        name="check_cve_exploited",
+        description=(
+            "Check whether a CVE is being actively exploited in the wild. Returns its "
+            "presence on the US CISA Known Exploited Vulnerabilities (KEV) catalog, its "
+            "EPSS exploit-probability score, and its CVSS severity, each with a "
+            "provenance URL to the authoritative US government source. Use for "
+            "vulnerability management, patch prioritization, threat intelligence, and "
+            "DevSecOps triage. Costs a small USDC micropayment per call (paid "
+            "automatically via x402 on Base)."
+        ),
+        schema=CheckCveExploitedSchema,
+    )
+    def check_cve_exploited(self, wallet_provider: EvmWalletProvider, args: dict[str, Any]) -> str:
+        """Check whether a CVE is on CISA KEV / its EPSS + CVSS scores."""
+        c = quote(str(args["cve_id"]), safe="")
+        return self._paid_get(wallet_provider, f"/security/cve/{c}", _MAX_CVE_ATOMIC)
+
+
+def osf_action_provider(base_url: str = DEFAULT_BASE_URL) -> "OSF":
+    """Create an OSF action provider (AgentKit factory convention).
+
+    Args:
+        base_url: Override the OSF base URL (defaults to the public mainnet API).
+
+    Returns:
+        An OSF provider exposing lookup_entity, screen_entity, and
+        check_cve_exploited (surfaced to the agent as OSF_lookup_entity, etc.).
+    """
+    return OSF(base_url=base_url)
+
+
+# Backward-compatible alias.
+OsfActionProvider = OSF
+
+
+__all__ = ["OSF", "OsfActionProvider", "osf_action_provider"]
+__version__ = "0.1.0"

osf_agentkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: osf-agentkit
+Version: 0.1.0
+Summary: Coinbase AgentKit action provider for OSF (Open Source Filings): provenance-stamped sanctions, entity, and CVE data for AI agents, paid per call over x402 (USDC on Base).
+Project-URL: Homepage, https://api.osf-master-server.com
+Project-URL: Source, https://github.com/onefreeman1337/osf-agentkit
+Author: Corey Gallant
+License: MIT
+Keywords: agentkit,ai-agents,coinbase,cve,entity-resolution,kyb,kyc,ofac,provenance,sanctions,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: coinbase-agentkit>=0.7.0
+Requires-Dist: x402<2.0.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+# osf-agentkit
+
+A [Coinbase AgentKit](https://github.com/coinbase/agentkit) action provider for **OSF (Open Source Filings)**: provenance-stamped, public-domain U.S. government and scientific data for AI agents, paid per call over **x402** (USDC on Base mainnet).
+
+Three tools, each returning structured JSON with a provenance URL to the authoritative primary source:
+
+- **OSF_lookup_entity** ($0.01) - resolve/verify a company or person against public registries (CMS NPI, GLEIF LEI, FDIC, SEC EDGAR). For KYC, KYB, counterparty due-diligence.
+- **OSF_screen_entity** ($0.05) - sanctions screening against OFAC SDN, EU, and UK OFSI lists. Returns hit/no-hit, matched list, and an audit receipt. For AML/KYC.
+- **OSF_check_cve_exploited** ($0.02) - is a CVE actively exploited (CISA KEV), plus EPSS probability and CVSS severity. For vulnerability management and DevSecOps.
+
+Payment is automatic: on an HTTP 402 the x402 client signs and settles the USDC micropayment with the agent's own EVM wallet, then retries. Each action enforces a per-call spend ceiling.
+
+## Install
+
+```
+pip install osf-agentkit
+```
+
+## Use
+
+```python
+from coinbase_agentkit import AgentKit, AgentKitConfig
+from osf_agentkit import osf_action_provider
+
+agent_kit = AgentKit(AgentKitConfig(
+    wallet_provider=your_evm_wallet_provider,
+    action_providers=[osf_action_provider()],
+))
+```
+
+The agent's wallet must hold USDC on Base mainnet. Learn more at the [OSF data marketplace](https://api.osf-master-server.com/mcp).
+
+## License
+
+MIT

osf_agentkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+osf_agentkit/__init__.py,sha256=dULct-sDCqtA2V8YCQTdx25QIhqyXx3qGtDLSHkcdfk,9728
+osf_agentkit-0.1.0.dist-info/METADATA,sha256=2_y8aVL9ykO5dmxW2dHyvcMMUvBgif407ApEvzGzFWk,2560
+osf_agentkit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+osf_agentkit-0.1.0.dist-info/RECORD,,

osf_agentkit-0.1.0.dist-info/WHEEL

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