Metadata-Version: 2.4
Name: iwantfyi-crewai
Version: 0.1.1
Summary: CrewAI tools for iwant.fyi -- reference implementation of the iwant.fyi demand-side protocol v1.0. Lets any CrewAI agent express structured purchase intent and receive matched supply.
Project-URL: Homepage, https://iwant.fyi/protocol/v1
Project-URL: Repository, https://github.com/staugs/iwantfyi-crewai
Project-URL: Spec, https://iwant.fyi/protocol/v1
Author-email: "iwant.fyi" <hi@iwant.fyi>
License: Apache-2.0
Keywords: ai-agent,commerce,crewai,demand-protocol,iwant.fyi,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: crewai>=0.30
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# iwantfyi-crewai

[CrewAI](https://crewai.com) tools for [iwant.fyi](https://iwant.fyi) — the reference implementation of the [iwant.fyi demand-side protocol v1.0](https://iwant.fyi/protocol/v1).

> **iwant.fyi demand-side protocol** is an open standard for how AI agents express structured purchase intent on behalf of users, receive matched supply across multiple sources, and report outcomes back. This package wraps iwant.fyi as a set of CrewAI `BaseTool` subclasses that any CrewAI agent or crew can use.

## Install

```bash
pip install iwantfyi-crewai
```

## Quick start

```python
from iwantfyi_crewai import get_iwantfyi_crewai_tools
from crewai import Agent, Crew, Task

tools = get_iwantfyi_crewai_tools(api_key="iwant_ak_...")  # get one at https://iwant.fyi

shopper = Agent(
    role="Personal Shopping Assistant",
    goal="Find products matching the user's needs across multiple sources.",
    backstory="You have access to iwant.fyi which searches multiple merchants in one call.",
    tools=tools,
)

task = Task(
    description="Find me a 1/4-inch drive torque wrench under $150 in Brooklyn",
    agent=shopper,
    expected_output="Top 3 matches with prices and source merchants.",
)

crew = Crew(agents=[shopper], tasks=[task])
result = crew.kickoff()
```

## What you get

Seven CrewAI `BaseTool` subclasses, one per iwant.fyi demand-side protocol v1.0 §8 tool:

| Tool | Spec | Description |
|---|---|---|
| `demand_create_want` | §8.1 | Create a Want and run matching |
| `demand_search` | §8.1 | Ephemeral matching, no persistence |
| `demand_get_want` | §8.1 | Retrieve a Want by ID |
| `demand_record_outcome` | §8.1 | Report viewed/clicked/purchased outcome |
| `demand_list_verticals` | §8.2 | Discover supported verticals |
| `demand_list_constraints` | §8.2 | Discover constraint vocabulary |
| `demand_health` | §8.2 | Liveness + readiness |

Each tool uses a Pydantic v2 args schema; CrewAI will validate user inputs before invoking the underlying iwant.fyi API.

## Direct client (no CrewAI)

```python
from iwantfyi_crewai import IwantClient

with IwantClient(api_key="iwant_ak_...") as client:
    health = client.health()
    print(health["status"])

    response = client.create_want(
        title='Torque wrench, 1/4" drive, 25-100 ft-lb',
        price_cents=15000,
        vertical="tools",
    )
    print(f"Want {response['want']['id']} -> {response['matches']['match_count']} matches")
```

## Picking individual tools

If you only need a subset:

```python
from iwantfyi_crewai import CreateWantTool, RecordOutcomeTool, IwantClient

client = IwantClient(api_key="iwant_ak_...")
agent = Agent(
    role="...",
    goal="...",
    tools=[CreateWantTool(client=client), RecordOutcomeTool(client=client)],
)
```

## Transports

MCP over HTTP is the default. The REST fallback (§9 of the spec) is available:

```python
tools = get_iwantfyi_crewai_tools(api_key="...", transport="http")
```

## Outcome events

Outcome events feed match-quality learning and (eventually) revenue-share attribution:

```python
client.record_outcome(want_id=w_id, match_id=m_id, event="clicked")
client.record_outcome(want_id=w_id, match_id=m_id, event="purchased", value_cents=12500)
```

Idempotent server-side; replays are no-ops.

## Errors

Typed exceptions from `iwantfyi_crewai.errors`:

```python
from iwantfyi_crewai import IwantError, UnauthorizedError, ValidationError, RateLimitedError
```

## Specification

Full iwant.fyi demand-side protocol v1.0 spec: [iwant.fyi/protocol/v1](https://iwant.fyi/protocol/v1)

The protocol is open (Apache 2.0). iwant.fyi is the reference implementation; anyone may build their own.

## License

Apache 2.0
