Metadata-Version: 2.4
Name: crewai-x402-sagg
Version: 0.1.0
Summary: A CrewAI tool that pays per-request for SAGG LLM chat completions via the x402 protocol - no API key needed.
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: eth-account>=0.13
Requires-Dist: requests>=2.31
Provides-Extra: crewai
Requires-Dist: crewai>=0.11; extra == "crewai"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# crewai-x402-sagg

A [CrewAI](https://www.crewai.com/) tool that pays for SAGG chat-completion requests
**per-request, via the [x402 protocol](https://x402.org/)** (a signed crypto
micropayment) instead of an API key - the same idea as this repo's sibling package,
[`langchain-x402-sagg`](../langchain-x402-sagg), adapted to CrewAI's own tool idiom.

**Status: testnet only (Base Sepolia) - this package specifically has never been run
against mainnet (the sibling `langchain-x402-sagg` has, with one real successful
payment; this one shares its payment logic but has not itself been exercised there).
Not published to PyPI or GitHub - prepared for review, not distributed.**

## Same architectural decision as the LangChain package, still justified here

Like `langchain-x402-sagg`, this package reimplements EIP-712/EIP-3009 signing
natively in Python (`eth_account`) rather than wrapping the existing Go client
(`x402module/poc`) via a subprocess/HTTP bridge. The reasoning carries over
unchanged: EIP-712 is an open standard with a mature Python implementation already,
and a Go-binary bridge would add real packaging/distribution friction for what
should be a lightweight, `pip install`-able tool. See the LangChain package's own
README for the fuller comparison - it wasn't re-litigated here since nothing about
CrewAI specifically changes that calculus.

**What IS adapted, not copied**: CrewAI's own tool-definition idiom. Verified
directly against CrewAI's official docs
(`docs.crewai.com/en/learn/create-custom-tools`) rather than assumed from the
LangChain package's own pattern - CrewAI's simplest, most idiomatic shape for a
single-string-argument tool is a plain function decorated with
`crewai.tools.tool("Name")`, not a pydantic `BaseTool` subclass (that also exists,
for tools needing a structured multi-field schema) and not LangChain's
`StructuredTool.from_function`. `tool.py` uses the `@tool`-decorated-function form.

## Known environment issue - disclosed honestly, not routed around

**This package's own development environment could not get a working `crewai`
install to actually run `tool.py` against.** The only `crewai` version this
environment's package index served (`0.11.2`) eagerly imports a legacy
`langchain<0.2.0` dependency chain at `import crewai`, which pins `numpy<2` -
a version with no prebuilt wheel for Python 3.14 (this environment's Python), so
installing it requires building numpy from source, which in turn needs a C/C++
compiler toolchain not present in this environment. Installing a full build
toolchain just to import a Tool base class was judged disproportionate effort for
this task, not attempted.

**What this does and does not affect**: `client.py`/`signer.py` - the actual x402
payment logic (signing, the 402 challenge/retry flow) - depend only on
`eth_account`/`requests`, not on `crewai` at all, and are fully installable, unit-
tested, AND live-tested in this same environment (see below) - a real, working,
independently-verified payment client. `tool.py`'s own ~15-line `@tool`-decorated
wrapper around that client was written and reviewed against CrewAI's real, current
documentation, but could not itself be imported/instantiated in this session to
confirm it runs against an actual `crewai` `Agent`. Given `crewai`'s own
dependency tree is heavy and evidently version-sensitive, this package
deliberately keeps `crewai` as an OPTIONAL install extra (`pip install
crewai-x402-sagg[crewai]`) rather than a hard dependency - so the core payment
logic stays usable even in an environment where the full `crewai` framework
itself can't install, which is exactly the situation this session hit.

If you have a working `crewai` environment, `tool.py`'s own ~15 lines are short
enough to read and verify by inspection against the docs snippet quoted above; this
README does not claim more live confidence in that specific file than was actually
established.

## Installation

```bash
pip install -e .              # core payment client only
pip install -e ".[crewai]"    # + the actual crewai framework, if your environment supports it
```

## Usage

```python
from crewai_x402_sagg.tool import make_sagg_x402_tool
from crewai import Agent

tool = make_sagg_x402_tool(
    private_key="0x...",              # a Base Sepolia testnet EVM private key, funded with testnet USDC
    sagg_url="https://your-sagg-gateway.example.com",
)

agent = Agent(
    role="Researcher",
    goal="...",
    backstory="...",
    tools=[tool],
)
```

### Configuration

Same as `langchain-x402-sagg` - see that package's README for the full table
(`private_key`, `sagg_url`, `model`, `max_amount_atomic`, `network`).

## Testing

```bash
pip install -e ".[dev]"
pytest tests/test_signer.py tests/test_client.py -v   # fast, no network - signing + network-validation logic
```

Live end-to-end (moves real testnet funds, opt-in):

```bash
SAGG_X402_TEST_PRIVATE_KEY=0x... \
SAGG_X402_TEST_URL=http://localhost:18080 \
RUN_LIVE_X402_TEST=1 \
pytest tests/test_live_sagg_x402.py -v -s
```

This exercises `SaggX402Client` directly (the same code `tool.py` calls) - not the
CrewAI-specific wrapper itself, per the environment limitation above. Run for real
during this package's own development against a locally-running SAGG gateway
instance (Base Sepolia, real facilitator, real on-chain settlement): `200 OK`, a
real ceiling settlement and a real refund, both independently confirmed on-chain
(`eth_getTransactionReceipt`, `status: 0x1` for both) rather than trusted from the
gateway's own response.

## Security

Same underlying client as `langchain-x402-sagg` (private key held in plain Python
process memory, `max_amount_atomic` a real enforced ceiling that only protects against
this client's own over-payment, not a malicious server's pricing below that ceiling),
including the same network-validation check: `post_with_payment` refuses to sign,
before any signature is produced, if the server's own 402 challenge names a different
`network` than this client was configured for - added after a real failure discovered
in the sibling package (a client signing with the wrong chain id for the server it was
actually talking to). Unlike that sibling package, **this one has only ever been run
against testnet** - see the Status note above.

## What this package does NOT do

- Publish itself anywhere (no PyPI, no GitHub).
- Guarantee it runs against any specific `crewai` version's `Agent`/`Tool` runtime
  end-to-end - see "Known environment issue" above.
- Support streaming responses or provider failover - a minimal, first-version client.
