agent-intent-x402 0.2.0__tar.gz

agent_intent_x402-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*

agent_intent_x402-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+# Publishes to PyPI on version-tag push, e.g. `git tag v0.1.0 && git push origin v0.1.0`.
+#
+# Setup: add a repository secret named PYPI_API_TOKEN
+#   (Settings -> Secrets and variables -> Actions -> New repository secret)
+#   Value: a PyPI API token scoped to the `agent-intent-x402` project.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*

agent_intent_x402-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store

agent_intent_x402-0.2.0/LICENSE

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

agent_intent_x402-0.2.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: agent-intent-x402
+Version: 0.2.0
+Summary: Pay-per-request access to any service for AI agents, over the open x402 protocol. Declare an intent, discover a provider, and settle on-chain with a single signature.
+Project-URL: Homepage, https://github.com/api-jarvisclaw/agent-intent-x402
+Project-URL: Documentation, https://github.com/api-jarvisclaw/agent-intent-x402#readme
+Project-URL: Repository, https://github.com/api-jarvisclaw/agent-intent-x402
+Project-URL: Issues, https://github.com/api-jarvisclaw/agent-intent-x402/issues
+Project-URL: Protocol, https://github.com/api-jarvisclaw/agent-intent-protocol
+Project-URL: x402, https://x402.org
+Author-email: JarvisClaw <dev@jarvisclaw.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,eip-3009,http-402,intent,llm,payments,usdc,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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.11.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-intent-x402
+
+Pay-per-request access to any service, for AI agents — over the open
+[x402](https://x402.org) protocol.
+
+Declare *what* you want, discover *who* provides it, and pay for the
+request on-chain with a single signature. No accounts, no API keys, no
+platform lock-in. Your agent carries a wallet; the service quotes a
+price with HTTP `402 Payment Required`; the client signs and settles.
+Because payment speaks the open x402 standard, the same client works
+against any compliant gateway.
+
+```bash
+pip install agent-intent-x402
+```
+
+## Quick start
+
+Give the client a wallet and it settles `402` challenges automatically —
+sign the payment, retry the request, return the result.
+
+```python
+from agent_intent_x402 import AIPClient, Wallet, IntentType
+
+wallet = Wallet(private_key="0x...")   # your agent's EVM key
+
+with AIPClient(wallet=wallet, endpoint="https://api.example.com") as client:
+    # Resolve an intent to the best-ranked provider. If the gateway
+    # answers 402, the wallet pays and the call transparently retries.
+    result = client.resolve(
+        IntentType.CHAT_COMPLETION,
+        constraints={"max_price_usd": 0.01},
+        preferences={"optimize_for": "cost"},
+    )
+    best = result.best_match
+    print(f"{best.provider_id} · {best.model} · score={best.score}")
+```
+
+The private key can also be supplied via the `AIP_WALLET_KEY`
+environment variable, in which case `Wallet()` needs no arguments.
+
+## How payment works
+
+x402 turns HTTP `402 Payment Required` into a usable payment step:
+
+1. The client makes a normal request.
+2. If payment is due, the gateway replies `402` with the accepted terms
+   (amount, asset, recipient, network) in the body.
+3. The wallet signs an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009)
+   `TransferWithAuthorization` for those exact terms — an EIP-712 typed
+   signature, no gas, no on-chain transaction from your side.
+4. The client retries with a `PAYMENT-SIGNATURE` header. The gateway
+   verifies and settles on-chain, then serves the response.
+
+Payments default to USDC on Base (`eip155:8453`); the network and asset
+come from the gateway's `402` terms, so the wallet always signs exactly
+what it is asked to pay.
+
+## Resolve, then execute
+
+`resolve` returns ranked matches so you can inspect price and score
+before committing. `execute` resolves *and* runs the intent in one call,
+proxying the provider response back:
+
+```python
+response = client.execute(
+    IntentType.CHAT_COMPLETION,
+    payload={"messages": [{"role": "user", "content": "Hello"}]},
+    preferences={"optimize_for": "quality"},
+)
+```
+
+## Natural-language intents
+
+Let the gateway interpret a free-form request. It may resolve directly
+or reply with a clarifying question for a multi-turn exchange:
+
+```python
+reply = client.resolve_natural("I need to transcribe an audio file cheaply")
+if reply.get("status") == "clarify":
+    print(reply["message"])   # follow-up question
+else:
+    print(reply["matches"])   # resolved providers
+```
+
+## Discovery
+
+```python
+# Every intent type the gateway understands.
+client.list_intent_types()
+
+# Providers available for a given intent.
+client.discover(intent_type=IntentType.IMAGE_GENERATION)
+
+# The full provider catalogue.
+client.list_providers()
+```
+
+## Intent types
+
+`chat_completion`, `image_generation`, `video_generation`,
+`text_to_speech`, `web_search`, `knowledge_search`,
+`prompt_optimization`, `document_processing`, `utility`,
+`code_execution`, `data_analysis`, `translation`, `code_generation`.
+
+## Errors
+
+All exceptions derive from `AIPError`:
+
+- `AIPConnectionError` — the request never reached the gateway.
+- `AIPAuthError` — `401`/`403`, missing or invalid credentials.
+- `AIPPaymentRequiredError` — `402`, payment required and no wallet was
+  configured (or the payment was rejected).
+- `AIPAPIError` — any other non-2xx response (`status_code`, `detail`, `body`).
+
+`WalletError` is raised when a `402` challenge cannot be signed (missing
+key, malformed terms).
+
+## Protocol
+
+The intent wire format and endpoint contract are defined in the
+[Agent Intent Protocol specification](https://github.com/api-jarvisclaw/agent-intent-protocol).
+The payment layer follows the open [x402](https://x402.org) protocol.
+
+## License
+
+MIT

agent_intent_x402-0.2.0/README.md

@@ -0,0 +1,127 @@
+# agent-intent-x402
+
+Pay-per-request access to any service, for AI agents — over the open
+[x402](https://x402.org) protocol.
+
+Declare *what* you want, discover *who* provides it, and pay for the
+request on-chain with a single signature. No accounts, no API keys, no
+platform lock-in. Your agent carries a wallet; the service quotes a
+price with HTTP `402 Payment Required`; the client signs and settles.
+Because payment speaks the open x402 standard, the same client works
+against any compliant gateway.
+
+```bash
+pip install agent-intent-x402
+```
+
+## Quick start
+
+Give the client a wallet and it settles `402` challenges automatically —
+sign the payment, retry the request, return the result.
+
+```python
+from agent_intent_x402 import AIPClient, Wallet, IntentType
+
+wallet = Wallet(private_key="0x...")   # your agent's EVM key
+
+with AIPClient(wallet=wallet, endpoint="https://api.example.com") as client:
+    # Resolve an intent to the best-ranked provider. If the gateway
+    # answers 402, the wallet pays and the call transparently retries.
+    result = client.resolve(
+        IntentType.CHAT_COMPLETION,
+        constraints={"max_price_usd": 0.01},
+        preferences={"optimize_for": "cost"},
+    )
+    best = result.best_match
+    print(f"{best.provider_id} · {best.model} · score={best.score}")
+```
+
+The private key can also be supplied via the `AIP_WALLET_KEY`
+environment variable, in which case `Wallet()` needs no arguments.
+
+## How payment works
+
+x402 turns HTTP `402 Payment Required` into a usable payment step:
+
+1. The client makes a normal request.
+2. If payment is due, the gateway replies `402` with the accepted terms
+   (amount, asset, recipient, network) in the body.
+3. The wallet signs an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009)
+   `TransferWithAuthorization` for those exact terms — an EIP-712 typed
+   signature, no gas, no on-chain transaction from your side.
+4. The client retries with a `PAYMENT-SIGNATURE` header. The gateway
+   verifies and settles on-chain, then serves the response.
+
+Payments default to USDC on Base (`eip155:8453`); the network and asset
+come from the gateway's `402` terms, so the wallet always signs exactly
+what it is asked to pay.
+
+## Resolve, then execute
+
+`resolve` returns ranked matches so you can inspect price and score
+before committing. `execute` resolves *and* runs the intent in one call,
+proxying the provider response back:
+
+```python
+response = client.execute(
+    IntentType.CHAT_COMPLETION,
+    payload={"messages": [{"role": "user", "content": "Hello"}]},
+    preferences={"optimize_for": "quality"},
+)
+```
+
+## Natural-language intents
+
+Let the gateway interpret a free-form request. It may resolve directly
+or reply with a clarifying question for a multi-turn exchange:
+
+```python
+reply = client.resolve_natural("I need to transcribe an audio file cheaply")
+if reply.get("status") == "clarify":
+    print(reply["message"])   # follow-up question
+else:
+    print(reply["matches"])   # resolved providers
+```
+
+## Discovery
+
+```python
+# Every intent type the gateway understands.
+client.list_intent_types()
+
+# Providers available for a given intent.
+client.discover(intent_type=IntentType.IMAGE_GENERATION)
+
+# The full provider catalogue.
+client.list_providers()
+```
+
+## Intent types
+
+`chat_completion`, `image_generation`, `video_generation`,
+`text_to_speech`, `web_search`, `knowledge_search`,
+`prompt_optimization`, `document_processing`, `utility`,
+`code_execution`, `data_analysis`, `translation`, `code_generation`.
+
+## Errors
+
+All exceptions derive from `AIPError`:
+
+- `AIPConnectionError` — the request never reached the gateway.
+- `AIPAuthError` — `401`/`403`, missing or invalid credentials.
+- `AIPPaymentRequiredError` — `402`, payment required and no wallet was
+  configured (or the payment was rejected).
+- `AIPAPIError` — any other non-2xx response (`status_code`, `detail`, `body`).
+
+`WalletError` is raised when a `402` challenge cannot be signed (missing
+key, malformed terms).
+
+## Protocol
+
+The intent wire format and endpoint contract are defined in the
+[Agent Intent Protocol specification](https://github.com/api-jarvisclaw/agent-intent-protocol).
+The payment layer follows the open [x402](https://x402.org) protocol.
+
+## License
+
+MIT

agent_intent_x402-0.2.0/agent_intent_x402/__init__.py

@@ -0,0 +1,57 @@
+"""agent-intent-x402 — pay-per-request access for AI agents over x402.
+
+Declare *what* you want, discover *who* provides it, and pay for the
+request on-chain with a single signature — no accounts, no API keys, no
+platform lock-in. Payment speaks the open `x402 <https://x402.org>`_
+protocol, so the same client works against any compliant gateway.
+
+    from agent_intent_x402 import AIPClient, IntentType, Wallet
+
+    # A wallet lets the client answer HTTP 402 challenges automatically.
+    wallet = Wallet(private_key="0x...")
+    with AIPClient(wallet=wallet) as client:
+        result = client.resolve(IntentType.CHAT_COMPLETION)
+        print(result.best_match.provider_id)
+"""
+
+from .client import DEFAULT_ENDPOINT, AIPClient
+from .errors import (
+    AIPAPIError,
+    AIPAuthError,
+    AIPConnectionError,
+    AIPError,
+    AIPPaymentRequiredError,
+)
+from .models import (
+    Constraints,
+    IntentType,
+    Match,
+    OptimizeFor,
+    Preferences,
+    Pricing,
+    Provider,
+    ResolveResult,
+)
+from .wallet import Wallet, WalletError
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AIPClient",
+    "DEFAULT_ENDPOINT",
+    "Wallet",
+    "WalletError",
+    "AIPError",
+    "AIPAPIError",
+    "AIPAuthError",
+    "AIPConnectionError",
+    "AIPPaymentRequiredError",
+    "IntentType",
+    "OptimizeFor",
+    "Constraints",
+    "Preferences",
+    "Pricing",
+    "Match",
+    "ResolveResult",
+    "Provider",
+]