iwantfyi-composio 0.1.1

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.

iwantfyi-composio

Composio actions for iwant.fyi — the reference implementation of the iwant.fyi demand-side protocol v1.0.

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

pip install iwantfyi-composio

Quick start (Composio + OpenAI)

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)

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:

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:

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:

from iwantfyi_composio import IwantError, UnauthorizedError, ValidationError, RateLimitedError

Specification

Full iwant.fyi demand-side protocol v1.0 spec: 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 is the basis when we get there.

License

Apache 2.0