Metadata-Version: 2.4
Name: iwantfyi-composio
Version: 0.1.1
Summary: Composio actions for iwant.fyi -- reference implementation of the iwant.fyi demand-side protocol v1.0. Lets any Composio-powered 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-composio
Project-URL: Spec, https://iwant.fyi/protocol/v1
Author-email: "iwant.fyi" <hi@iwant.fyi>
License: Apache-2.0
Keywords: ai-agent,commerce,composio,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: composio-core>=0.5
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-composio

[Composio](https://composio.dev) actions 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 Composio actions that any Composio-powered agent can use.

## Install

```bash
pip install iwantfyi-composio
```

## Quick start (Composio + OpenAI)

```python
from iwantfyi_composio import register_iwantfyi_actions
from composio_openai import ComposioToolSet
from openai import OpenAI

toolset = ComposioToolSet()
register_iwantfyi_actions(toolset, api_key="iwant_ak_...")  # get one at https://iwant.fyi

tools = toolset.get_tools(actions=["IWANTFYI_CREATE_WANT", "IWANTFYI_RECORD_OUTCOME"])

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    tools=tools,
    messages=[{"role": "user", "content": "Find me a torque wrench under $150"}],
)
```

## What you get

Seven Composio actions, one per iwant.fyi demand-side protocol v1.0 §8 tool:

| Action | Spec | Description |
|---|---|---|
| `IWANTFYI_CREATE_WANT` | §8.1 | Create a Want and run matching |
| `IWANTFYI_SEARCH` | §8.1 | Ephemeral matching, no persistence |
| `IWANTFYI_GET_WANT` | §8.1 | Retrieve a Want by ID |
| `IWANTFYI_RECORD_OUTCOME` | §8.1 | Report viewed/clicked/purchased outcome |
| `IWANTFYI_LIST_VERTICALS` | §8.2 | Discover supported verticals |
| `IWANTFYI_LIST_CONSTRAINTS` | §8.2 | Discover constraint vocabulary |
| `IWANTFYI_HEALTH` | §8.2 | Liveness + readiness |

All inputs are validated by Pydantic v2 schemas.

## Direct client (no Composio)

```python
from iwantfyi_composio 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")
```

## Manual registration (advanced)

Composio's SDK API has changed across versions. If `register_iwantfyi_actions()` doesn't match your version's expected pattern, you can get the raw action definitions and wire them yourself:

```python
from iwantfyi_composio import get_iwantfyi_action_definitions

defs = get_iwantfyi_action_definitions(api_key="iwant_ak_...")
for d in defs:
    print(d["name"], d["display_name"])
    # d["func"]    -- Callable[..., dict]
    # d["input_model"]  -- Pydantic BaseModel class
    # Register according to your Composio version's API
```

## 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 on the server side; replays are no-ops.

## Errors

Typed exceptions from `iwantfyi_composio.errors`:

```python
from iwantfyi_composio 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.

## Submitting to Composio's official catalog

This package provides client-side registration so any Composio user with our SDK installed gets the actions. The longer-term play is to submit iwant.fyi as an **official Composio app** (composio.dev/app/iwantfyi) so it's discoverable to all Composio users without installing our SDK.

Status: not yet submitted. The official-app submission requires going through Composio's review process and publishing an OpenAPI definition. Our [public OpenAPI](https://iwant.fyi/api/openapi.json) is the basis when we get there.

## License

Apache 2.0
