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
