osf-agentkit 0.1.1__tar.gz

osf_agentkit-0.1.1/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling / IDE
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets / env
+.env
+*.pem

osf_agentkit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corey Gallant / OSF (Open Source Filings)
+
+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.

osf_agentkit-0.1.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: osf-agentkit
+Version: 0.1.1
+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
+License-File: LICENSE
+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: solana<0.40,>=0.36.6
+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 that gives AI agents three provenance-stamped "ground truth" tools, paid per call over [x402](https://docs.cdp.coinbase.com/x402) (USDC on Base):
+
+| Action | Input | Returns | Price |
+| --- | --- | --- | --- |
+| `OSF_lookup_entity` | a company/person name or an identifier (NPI, LEI, FDIC cert, SEC CIK) | legal name, status, type, jurisdiction, identifiers, and a **provenance URL** to the official registry | $0.01 |
+| `OSF_screen_entity` | a name | hit / no-hit against OFAC SDN, EU, and UK sanctions lists, with matched list, provenance URL, and an **audit receipt** | $0.05 |
+| `OSF_check_cve_exploited` | a CVE id | CISA KEV actively-exploited status, EPSS score, CVSS severity, each with a **provenance URL** | $0.02 |
+
+Every answer carries a link back to the authoritative primary source (US CMS NPI, GLEIF, FDIC, SEC EDGAR, OFAC, CISA), so an agent can **justify a decision to an auditor or regulator** instead of citing an opaque API. Payment is automatic and per-request: no API keys, no accounts, no subscriptions.
+
+## Install
+
+```bash
+pip install osf-agentkit
+```
+
+## Quickstart (AgentKit)
+
+Add the provider to your AgentKit config. The agent pays for each call from its own wallet, so you need an `EvmWalletProvider` funded with USDC on **Base mainnet**.
+
+```python
+from coinbase_agentkit import AgentKit, AgentKitConfig
+from osf_agentkit import osf_action_provider
+
+agent_kit = AgentKit(AgentKitConfig(
+    wallet_provider=your_evm_wallet_provider,   # e.g. a CDP EVM wallet on base-mainnet
+    action_providers=[
+        osf_action_provider(),
+        # ... your other providers
+    ],
+))
+```
+
+The agent now has `OSF_lookup_entity`, `OSF_screen_entity`, and `OSF_check_cve_exploited` available. See the [AgentKit docs](https://docs.cdp.coinbase.com/agent-kit/welcome) for wallet-provider setup.
+
+## Use with LangChain
+
+AgentKit actions convert to LangChain tools via the LangChain extension:
+
+```bash
+pip install coinbase-agentkit-langchain
+```
+
+```python
+from coinbase_agentkit_langchain import get_langchain_tools
+
+tools = get_langchain_tools(agent_kit)   # includes the three OSF tools
+# pass `tools` to your LangChain / LangGraph agent
+```
+
+## Wallet, network, and spend caps
+
+- **Network:** OSF settles on **Base mainnet** only. `supports_network` returns `False` for other networks, so the actions simply won't be offered off Base.
+- **Funding:** the agent's wallet needs USDC on Base to pay per call.
+- **Per-call spend ceilings** (atomic USDC, protective; the client refuses to pay more):
+  - `lookup_entity` — $0.05
+  - `screen_entity` — $0.15
+  - `check_cve_exploited` — $0.10
+
+  These sit above OSF's list prices so a small price change won't break calls, while capping runaway spend. If OSF ever reprices above a ceiling, bump the constants in `provider.py`.
+
+## Configuration
+
+Point the provider at a different base URL (e.g. for testing) if needed:
+
+```python
+osf_action_provider(base_url="https://api.osf-master-server.com/x402")
+```
+
+## How it works
+
+Each action makes a single paid `GET` to the corresponding OSF endpoint using `x402_requests(wallet_provider.to_signer(), max_value=<cap>)`. When OSF replies `402 Payment Required`, the x402 client signs and settles the micropayment with the agent's wallet, then retries — all transparently. The action returns the JSON result plus the on-chain payment proof.
+
+## About OSF
+
+OSF (Open Source Filings) sells provenance-stamped US public-domain government and scientific data to autonomous agents over x402. Learn more at [api.osf-master-server.com](https://api.osf-master-server.com).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

osf_agentkit-0.1.1/README.md

@@ -0,0 +1,82 @@
+# osf-agentkit
+
+A [Coinbase AgentKit](https://github.com/coinbase/agentkit) action provider that gives AI agents three provenance-stamped "ground truth" tools, paid per call over [x402](https://docs.cdp.coinbase.com/x402) (USDC on Base):
+
+| Action | Input | Returns | Price |
+| --- | --- | --- | --- |
+| `OSF_lookup_entity` | a company/person name or an identifier (NPI, LEI, FDIC cert, SEC CIK) | legal name, status, type, jurisdiction, identifiers, and a **provenance URL** to the official registry | $0.01 |
+| `OSF_screen_entity` | a name | hit / no-hit against OFAC SDN, EU, and UK sanctions lists, with matched list, provenance URL, and an **audit receipt** | $0.05 |
+| `OSF_check_cve_exploited` | a CVE id | CISA KEV actively-exploited status, EPSS score, CVSS severity, each with a **provenance URL** | $0.02 |
+
+Every answer carries a link back to the authoritative primary source (US CMS NPI, GLEIF, FDIC, SEC EDGAR, OFAC, CISA), so an agent can **justify a decision to an auditor or regulator** instead of citing an opaque API. Payment is automatic and per-request: no API keys, no accounts, no subscriptions.
+
+## Install
+
+```bash
+pip install osf-agentkit
+```
+
+## Quickstart (AgentKit)
+
+Add the provider to your AgentKit config. The agent pays for each call from its own wallet, so you need an `EvmWalletProvider` funded with USDC on **Base mainnet**.
+
+```python
+from coinbase_agentkit import AgentKit, AgentKitConfig
+from osf_agentkit import osf_action_provider
+
+agent_kit = AgentKit(AgentKitConfig(
+    wallet_provider=your_evm_wallet_provider,   # e.g. a CDP EVM wallet on base-mainnet
+    action_providers=[
+        osf_action_provider(),
+        # ... your other providers
+    ],
+))
+```
+
+The agent now has `OSF_lookup_entity`, `OSF_screen_entity`, and `OSF_check_cve_exploited` available. See the [AgentKit docs](https://docs.cdp.coinbase.com/agent-kit/welcome) for wallet-provider setup.
+
+## Use with LangChain
+
+AgentKit actions convert to LangChain tools via the LangChain extension:
+
+```bash
+pip install coinbase-agentkit-langchain
+```
+
+```python
+from coinbase_agentkit_langchain import get_langchain_tools
+
+tools = get_langchain_tools(agent_kit)   # includes the three OSF tools
+# pass `tools` to your LangChain / LangGraph agent
+```
+
+## Wallet, network, and spend caps
+
+- **Network:** OSF settles on **Base mainnet** only. `supports_network` returns `False` for other networks, so the actions simply won't be offered off Base.
+- **Funding:** the agent's wallet needs USDC on Base to pay per call.
+- **Per-call spend ceilings** (atomic USDC, protective; the client refuses to pay more):
+  - `lookup_entity` — $0.05
+  - `screen_entity` — $0.15
+  - `check_cve_exploited` — $0.10
+
+  These sit above OSF's list prices so a small price change won't break calls, while capping runaway spend. If OSF ever reprices above a ceiling, bump the constants in `provider.py`.
+
+## Configuration
+
+Point the provider at a different base URL (e.g. for testing) if needed:
+
+```python
+osf_action_provider(base_url="https://api.osf-master-server.com/x402")
+```
+
+## How it works
+
+Each action makes a single paid `GET` to the corresponding OSF endpoint using `x402_requests(wallet_provider.to_signer(), max_value=<cap>)`. When OSF replies `402 Payment Required`, the x402 client signs and settles the micropayment with the agent's wallet, then retries — all transparently. The action returns the JSON result plus the on-chain payment proof.
+
+## About OSF
+
+OSF (Open Source Filings) sells provenance-stamped US public-domain government and scientific data to autonomous agents over x402. Learn more at [api.osf-master-server.com](https://api.osf-master-server.com).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

osf_agentkit-0.1.1/osf_agentkit/__init__.py

@@ -0,0 +1,10 @@
+"""OSF action provider for Coinbase AgentKit.
+
+Provenance-stamped sanctions, entity, and CVE data for AI agents, paid per call
+over x402 (USDC on Base mainnet).
+"""
+
+from .provider import OSF, OsfActionProvider, osf_action_provider
+
+__all__ = ["OSF", "OsfActionProvider", "osf_action_provider"]
+__version__ = "0.1.1"

osf_agentkit-0.1.1/osf_agentkit/provider.py

@@ -0,0 +1,197 @@
+"""OSF (Open Source Filings) action provider for Coinbase AgentKit.
+
+Gives an AgentKit agent three provenance-stamped "ground truth" tools, 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 back to the authoritative primary source
+(and, for sanctions, an audit receipt), so an agent can justify a decision to an
+auditor or regulator.
+
+Payment is automatic: when an OSF endpoint replies 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 so a mispriced or hostile endpoint cannot
+drain the wallet.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+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
+
+from .schemas import (
+    CheckCveExploitedSchema,
+    LookupEntitySchema,
+    ScreenEntitySchema,
+)
+
+# 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

osf_agentkit-0.1.1/osf_agentkit/schemas.py

@@ -0,0 +1,46 @@
+"""Argument schemas for the OSF AgentKit action provider.
+
+Each schema documents the single input an agent must supply. The field
+descriptions are written for an LLM planner: concrete, example-bearing, and
+matched to how an agent would phrase the task.
+"""
+
+from pydantic import BaseModel, Field
+
+
+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_agentkit-0.1.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "osf-agentkit"
+version = "0.1.1"
+description = "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)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Corey Gallant" }]
+keywords = [
+    "x402",
+    "agentkit",
+    "coinbase",
+    "ai-agents",
+    "sanctions",
+    "ofac",
+    "kyb",
+    "kyc",
+    "cve",
+    "entity-resolution",
+    "provenance",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "coinbase-agentkit>=0.7.0",
+    "x402>=1.0.0,<2.0.0",
+    # coinbase-agentkit imports the synchronous solana.rpc.api.Client, which was
+    # removed in solana 0.40.0. cdp-sdk / coinbase-agentkit only require
+    # solana>=0.36.6 (no upper bound), so a fresh install otherwise pulls 0.40.0
+    # and fails to import. Cap solana below 0.40 so the package imports cleanly.
+    "solana>=0.36.6,<0.40",
+]
+
+[project.urls]
+Homepage = "https://api.osf-master-server.com"
+Source = "https://github.com/onefreeman1337/osf-agentkit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["osf_agentkit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["osf_agentkit", "README.md", "LICENSE"]