ddg-langchain 0.1.0__tar.gz

ddg_langchain-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

ddg_langchain-0.1.0/LICENSE

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

ddg_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: ddg-langchain
+Version: 0.1.0
+Summary: LangChain + CrewAI tools for DDG Agent Services (x402-payable, USDC on Base, no API key)
+Project-URL: Homepage, https://agents.daedalusdevelopmentgroup.com
+Project-URL: Repository, https://github.com/daedalusdevelopmentgroup/ddg-agent-payable-services
+Author: Daedalus Development Group
+License: MIT
+License-File: LICENSE
+Keywords: agents,crewai,langchain,llm,payments,tools,x402
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: pydantic>=2.5
+Requires-Dist: requests>=2.31
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.60; extra == 'crewai'
+Requires-Dist: langchain-core>=0.3; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: crewai>=0.60; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: x402[evm,requests]>=2.0; extra == 'dev'
+Provides-Extra: x402
+Requires-Dist: x402[evm,requests]>=2.0; extra == 'x402'
+Description-Content-Type: text/markdown
+
+# ddg-langchain
+
+LangChain + CrewAI tools for **[DDG Agent Services](https://agents.daedalusdevelopmentgroup.com)**
+— 376 pay-per-call x402 API routes on Base. Priced per call in USDC, no API
+key, no account, no KYC.
+
+This package wraps three flagship routes as agent tools:
+
+| Tool | Route | Price | Notes |
+| --- | --- | --- | --- |
+| `ddg_web_search` | `POST /v1/web-search` | $0.005 | 20+ engines, structured JSON. First call/agent/day free. |
+| `ddg_price_feed` | `POST /v1/price-feed` | $0.005 | Crypto / forex / stock. First call/agent/day free. |
+| `ddg_site_audit` | `POST /v1/site-audit` | $0.01 | Read-only public-site audit, up to 120 s. |
+
+## Install
+
+```bash
+pip install ddg-langchain                      # LangChain tools (no payment signing)
+pip install "ddg-langchain[x402]"              # + automatic x402 settlement (EVM key)
+pip install "ddg-langchain[crewai]"            # + CrewAI toolkit
+pip install "ddg-langchain[dev]"               # everything + pytest
+```
+
+## Quickstart — LangChain
+
+```python
+from ddg_langchain import build_tools
+
+tools = build_tools()          # 3 StructuredTools, ready for any agent
+price = tools[1].invoke({"asset": "BTC"})
+print(price["price"], price["_ddg"])
+```
+
+## Quickstart — CrewAI
+
+```python
+from ddg_langchain.crewai import DdgCrewAIToolkit
+from crewai import Agent, Crew, Task, Process
+
+toolkit = DdgCrewAIToolkit()
+researcher = Agent(role="Researcher", goal="...", tools=toolkit.tools)
+crew = Crew(agents=[researcher], tasks=[Task(..., agent=researcher)], process=Process.sequential)
+```
+
+## Payment (x402) — how it settles
+
+There is no API key. A route outside the free tier answers `402` with an x402
+challenge; this package offers three behaviours:
+
+### 1. Automatic settlement (recommended)
+
+Set an EVM key. The client builds a `requests.Session` through the **official
+x402 Python SDK** (`x402.x402ClientSync` + `x402_requests` + `EthAccountSigner`),
+registers the *exact* EVM scheme pinned to Base (`eip155:8453`), and the SDK
+answers the 402, signs the EIP-3009 authorization, retries, and exposes the
+settle response.
+
+```bash
+export DDG_AGENT_ID=acme-research-agent      # stable identity -> X-Agent-Id (free tier key)
+export DDG_EVM_PRIVATE_KEY=0x...             # wallet that pays the USDC
+export DDG_MAX_PRICE_USD=0.05                # per-call cap (default 0.05)
+python examples/langchain_agent.py
+```
+
+The wallet address is the payer; it needs USDC on Base (`0x833589fC...02913`).
+`<amount>` values in challenges are **atomic USDC (6 decimals)**: `5000` = $0.005.
+
+### 2. Out-of-band signature
+
+Settle with any other x402 client (TypeScript `x402-fetch`, a facilitator, a
+hardware wallet flow) and hand the proof over:
+
+```bash
+export DDG_PAYMENT_SIGNATURE=<base64 PAYMENT-SIGNATURE>
+```
+
+### 3. Challenge-only (no key)
+
+Tools still run, free tier works, and any paid call returns a JSON payload
+instead of raising:
+
+```json
+{
+  "status": "payment_required",
+  "route": "/v1/price-feed",
+  "accepts": [{ "network": "eip155:8453", "asset": "0x833589...02913",
+                "amount": "5000", "payTo": "0x8AfBD522...30Bc6",
+                "extra": { "name": "USD Coin", "version": "2" } }],
+  "how_to_settle": "Set DDG_EVM_PRIVATE_KEY ... or send the base64 PAYMENT-SIGNATURE."
+}
+```
+
+That is deliberate: an agent should be able to *report* a paywall rather than
+crash a crew. Programmatic callers who want the exception can use the client
+directly — `DdgClient().price_feed("BTC")` raises `DdgPaymentRequired`.
+
+### Spend cap
+
+When a key is configured, every call is **pre-flighted** with a keyless request
+so the real challenge price is known *before* anything is signed. A quote above
+`DDG_MAX_PRICE_USD` raises `DdgSpendLimitExceeded` and nothing is paid.
+
+## API
+
+```python
+from ddg_langchain import DdgClient, DdgConfig, build_tools, describe_routes
+
+client = DdgClient(DdgConfig(
+    base_url="https://agents.daedalusdevelopmentgroup.com",
+    agent_id="acme-research-agent",
+    private_key=None,        # or "0x..."
+    max_price_usd=0.05,
+    timeout=180,
+))
+
+client.web_search("x402 protocol", limit=5)
+client.price_feed("BTC")
+client.site_audit("https://example.com", business_type="saas", market="us-b2b")
+client.last_settlement        # settle response from the last paid call, if any
+```
+
+Every successful return carries a `_ddg` metadata block:
+
+```json
+"_ddg": {
+  "route": "/v1/web-search",
+  "status_code": 200,
+  "price_usd": "$0.005",
+  "payment_receipt": "ft-9ee46d0a911229b8-4684b8d3",
+  "free_tier": true,
+  "settled": false,
+  "settlement": null
+}
+```
+
+Environment variables: `DDG_BASE_URL`, `DDG_AGENT_ID`, `DDG_EVM_PRIVATE_KEY`,
+`DDG_PAYMENT_SIGNATURE`, `DDG_MAX_PRICE_USD`, `DDG_TIMEOUT`.
+
+## Tests
+
+```bash
+pytest                 # offline: fake transport, no keys, no network
+pytest -m live         # real edge, free tier only (costs nothing)
+```
+
+The live tests assert that a fresh agent id gets a real `200` on the free tier
+and that the second call on the same identity returns a genuine 402 challenge
+with `accepts[0].network == "eip155:8453"`.
+
+## Honest status / what is missing to go live
+
+* **Code is verified, the paid path is not.** The offline suite passes, and the
+  live tests drive the real edge end-to-end — but only on the free tier and the
+  challenge path. No paid settlement has been executed by this package against
+  the live edge, because that needs a funded Base wallet key.
+* **To go live you need:** a wallet with USDC on Base, funded with at least
+  `DDG_MAX_PRICE_USD` per call, exported as `DDG_EVM_PRIVATE_KEY`; the
+  `x402[evm]` extra installed (`pip install "ddg-langchain[x402]"`).
+* **Untested against real x402 settlement:** the pre-flight-then-pay flow, the
+  EIP-3009 signature the SDK produces for DDG's `payTo`, and
+  `last_settlement` decoding. All three are exercised only with the fake
+  transport today.
+* **Facilitator behaviour is DDG-side.** If a settle ever fails (gas, rate
+  limit, stale challenge), the failure surfaces as an HTTP error from the edge —
+  see DDG's x402 debugger notes for the failure taxonomy.
+* **CrewAI** is exercised only if the extra is installed; otherwise the whole
+  `tests/test_crewai.py` module is skipped, and the toolkit's lazy import keeps
+  LangChain-only installs lean.
+* **Not published** to PyPI.
+
+## License
+
+MIT

ddg_langchain-0.1.0/README.md

@@ -0,0 +1,173 @@
+# ddg-langchain
+
+LangChain + CrewAI tools for **[DDG Agent Services](https://agents.daedalusdevelopmentgroup.com)**
+— 376 pay-per-call x402 API routes on Base. Priced per call in USDC, no API
+key, no account, no KYC.
+
+This package wraps three flagship routes as agent tools:
+
+| Tool | Route | Price | Notes |
+| --- | --- | --- | --- |
+| `ddg_web_search` | `POST /v1/web-search` | $0.005 | 20+ engines, structured JSON. First call/agent/day free. |
+| `ddg_price_feed` | `POST /v1/price-feed` | $0.005 | Crypto / forex / stock. First call/agent/day free. |
+| `ddg_site_audit` | `POST /v1/site-audit` | $0.01 | Read-only public-site audit, up to 120 s. |
+
+## Install
+
+```bash
+pip install ddg-langchain                      # LangChain tools (no payment signing)
+pip install "ddg-langchain[x402]"              # + automatic x402 settlement (EVM key)
+pip install "ddg-langchain[crewai]"            # + CrewAI toolkit
+pip install "ddg-langchain[dev]"               # everything + pytest
+```
+
+## Quickstart — LangChain
+
+```python
+from ddg_langchain import build_tools
+
+tools = build_tools()          # 3 StructuredTools, ready for any agent
+price = tools[1].invoke({"asset": "BTC"})
+print(price["price"], price["_ddg"])
+```
+
+## Quickstart — CrewAI
+
+```python
+from ddg_langchain.crewai import DdgCrewAIToolkit
+from crewai import Agent, Crew, Task, Process
+
+toolkit = DdgCrewAIToolkit()
+researcher = Agent(role="Researcher", goal="...", tools=toolkit.tools)
+crew = Crew(agents=[researcher], tasks=[Task(..., agent=researcher)], process=Process.sequential)
+```
+
+## Payment (x402) — how it settles
+
+There is no API key. A route outside the free tier answers `402` with an x402
+challenge; this package offers three behaviours:
+
+### 1. Automatic settlement (recommended)
+
+Set an EVM key. The client builds a `requests.Session` through the **official
+x402 Python SDK** (`x402.x402ClientSync` + `x402_requests` + `EthAccountSigner`),
+registers the *exact* EVM scheme pinned to Base (`eip155:8453`), and the SDK
+answers the 402, signs the EIP-3009 authorization, retries, and exposes the
+settle response.
+
+```bash
+export DDG_AGENT_ID=acme-research-agent      # stable identity -> X-Agent-Id (free tier key)
+export DDG_EVM_PRIVATE_KEY=0x...             # wallet that pays the USDC
+export DDG_MAX_PRICE_USD=0.05                # per-call cap (default 0.05)
+python examples/langchain_agent.py
+```
+
+The wallet address is the payer; it needs USDC on Base (`0x833589fC...02913`).
+`<amount>` values in challenges are **atomic USDC (6 decimals)**: `5000` = $0.005.
+
+### 2. Out-of-band signature
+
+Settle with any other x402 client (TypeScript `x402-fetch`, a facilitator, a
+hardware wallet flow) and hand the proof over:
+
+```bash
+export DDG_PAYMENT_SIGNATURE=<base64 PAYMENT-SIGNATURE>
+```
+
+### 3. Challenge-only (no key)
+
+Tools still run, free tier works, and any paid call returns a JSON payload
+instead of raising:
+
+```json
+{
+  "status": "payment_required",
+  "route": "/v1/price-feed",
+  "accepts": [{ "network": "eip155:8453", "asset": "0x833589...02913",
+                "amount": "5000", "payTo": "0x8AfBD522...30Bc6",
+                "extra": { "name": "USD Coin", "version": "2" } }],
+  "how_to_settle": "Set DDG_EVM_PRIVATE_KEY ... or send the base64 PAYMENT-SIGNATURE."
+}
+```
+
+That is deliberate: an agent should be able to *report* a paywall rather than
+crash a crew. Programmatic callers who want the exception can use the client
+directly — `DdgClient().price_feed("BTC")` raises `DdgPaymentRequired`.
+
+### Spend cap
+
+When a key is configured, every call is **pre-flighted** with a keyless request
+so the real challenge price is known *before* anything is signed. A quote above
+`DDG_MAX_PRICE_USD` raises `DdgSpendLimitExceeded` and nothing is paid.
+
+## API
+
+```python
+from ddg_langchain import DdgClient, DdgConfig, build_tools, describe_routes
+
+client = DdgClient(DdgConfig(
+    base_url="https://agents.daedalusdevelopmentgroup.com",
+    agent_id="acme-research-agent",
+    private_key=None,        # or "0x..."
+    max_price_usd=0.05,
+    timeout=180,
+))
+
+client.web_search("x402 protocol", limit=5)
+client.price_feed("BTC")
+client.site_audit("https://example.com", business_type="saas", market="us-b2b")
+client.last_settlement        # settle response from the last paid call, if any
+```
+
+Every successful return carries a `_ddg` metadata block:
+
+```json
+"_ddg": {
+  "route": "/v1/web-search",
+  "status_code": 200,
+  "price_usd": "$0.005",
+  "payment_receipt": "ft-9ee46d0a911229b8-4684b8d3",
+  "free_tier": true,
+  "settled": false,
+  "settlement": null
+}
+```
+
+Environment variables: `DDG_BASE_URL`, `DDG_AGENT_ID`, `DDG_EVM_PRIVATE_KEY`,
+`DDG_PAYMENT_SIGNATURE`, `DDG_MAX_PRICE_USD`, `DDG_TIMEOUT`.
+
+## Tests
+
+```bash
+pytest                 # offline: fake transport, no keys, no network
+pytest -m live         # real edge, free tier only (costs nothing)
+```
+
+The live tests assert that a fresh agent id gets a real `200` on the free tier
+and that the second call on the same identity returns a genuine 402 challenge
+with `accepts[0].network == "eip155:8453"`.
+
+## Honest status / what is missing to go live
+
+* **Code is verified, the paid path is not.** The offline suite passes, and the
+  live tests drive the real edge end-to-end — but only on the free tier and the
+  challenge path. No paid settlement has been executed by this package against
+  the live edge, because that needs a funded Base wallet key.
+* **To go live you need:** a wallet with USDC on Base, funded with at least
+  `DDG_MAX_PRICE_USD` per call, exported as `DDG_EVM_PRIVATE_KEY`; the
+  `x402[evm]` extra installed (`pip install "ddg-langchain[x402]"`).
+* **Untested against real x402 settlement:** the pre-flight-then-pay flow, the
+  EIP-3009 signature the SDK produces for DDG's `payTo`, and
+  `last_settlement` decoding. All three are exercised only with the fake
+  transport today.
+* **Facilitator behaviour is DDG-side.** If a settle ever fails (gas, rate
+  limit, stale challenge), the failure surfaces as an HTTP error from the edge —
+  see DDG's x402 debugger notes for the failure taxonomy.
+* **CrewAI** is exercised only if the extra is installed; otherwise the whole
+  `tests/test_crewai.py` module is skipped, and the toolkit's lazy import keeps
+  LangChain-only installs lean.
+* **Not published** to PyPI.
+
+## License
+
+MIT

ddg_langchain-0.1.0/ddg_langchain/__init__.py

@@ -0,0 +1,62 @@
+"""ddg-langchain — DDG Agent Services tools for LangChain, LangGraph and CrewAI.
+
+Three flagship x402-payable routes (USDC on Base, no API key, no KYC) exposed as
+agent tools, with payment settlement via the official x402 Python SDK.
+
+    from ddg_langchain import build_tools
+    tools = build_tools()          # 3 LangChain StructuredTools
+
+    # CrewAI
+    from ddg_langchain.crewai import DdgCrewAIToolkit
+    tools = DdgCrewAIToolkit().tools
+
+Environment:
+    DDG_BASE_URL            default https://agents.daedalusdevelopmentgroup.com
+    DDG_AGENT_ID            stable agent identity -> X-Agent-Id (free tier key)
+    DDG_EVM_PRIVATE_KEY     EVM key; enables automatic x402 settlement
+    DDG_PAYMENT_SIGNATURE   pre-signed base64 PAYMENT-SIGNATURE (alternative)
+    DDG_MAX_PRICE_USD       per-call spend cap, default 0.05
+    DDG_TIMEOUT             HTTP timeout seconds, default 180
+"""
+
+from .client import DEFAULT_BASE_URL, DdgClient, DdgConfig, ROUTE_PRICES_USD, get_client, set_client
+from .errors import (
+    DdgError,
+    DdgPaymentRequired,
+    DdgRequestError,
+    DdgSpendLimitExceeded,
+)
+from .tools import (
+    DdgPriceFeedInput,
+    DdgSiteAuditInput,
+    DdgWebSearchInput,
+    build_tools,
+    ddg_price_feed,
+    ddg_site_audit,
+    ddg_web_search,
+    describe_routes,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "ROUTE_PRICES_USD",
+    "DdgClient",
+    "DdgConfig",
+    "DdgError",
+    "DdgPaymentRequired",
+    "DdgPriceFeedInput",
+    "DdgRequestError",
+    "DdgSiteAuditInput",
+    "DdgSpendLimitExceeded",
+    "DdgWebSearchInput",
+    "build_tools",
+    "ddg_price_feed",
+    "ddg_site_audit",
+    "ddg_web_search",
+    "describe_routes",
+    "get_client",
+    "set_client",
+    "__version__",
+]