Metadata-Version: 2.4
Name: iwantfyi-llamaindex
Version: 0.1.1
Summary: LlamaIndex tools for iwant.fyi -- reference implementation of the iwant.fyi demand-side protocol v1.1. Lets any LlamaIndex agent express structured purchase intent and receive matched supply across multiple sources.
Project-URL: Homepage, https://iwant.fyi/protocol/v1
Project-URL: Repository, https://github.com/staugs/iwantfyi-llamaindex
Project-URL: Spec, https://iwant.fyi/protocol/v1
Project-URL: Bug Tracker, https://github.com/staugs/iwantfyi-llamaindex/issues
Author-email: "iwant.fyi" <hi@iwant.fyi>
License: Apache-2.0
Keywords: ai-agent,commerce,demand-protocol,iwant.fyi,llama-index,llamaindex,mcp,shopping
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: llama-index-core>=0.10.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# iwantfyi-llamaindex

LlamaIndex tools for [iwant.fyi](https://iwant.fyi) — the reference implementation of the [iwant.fyi demand-side protocol v1.1](https://iwant.fyi/protocol/v1). Lets any LlamaIndex agent express structured purchase intent and receive matched supply across multiple sources.

```bash
pip install iwantfyi-llamaindex
```

## Usage

```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from iwantfyi_llamaindex import get_iwant_tools

tools = get_iwant_tools(api_key="iwant_ak_...")

agent = FunctionAgent(
    tools=tools,
    llm=OpenAI(model="gpt-4o"),
    system_prompt="You help users find and buy things via iwant.fyi.",
)

response = await agent.run("Find me waterproof running shoes under $120")
print(response)
```

Get a free API key by registering an agent: `POST https://iwant.fyi/api/agents/register` (or see [/developers](https://iwant.fyi/developers)).

## Tools

| Tool | What it does |
|---|---|
| `demand_create_want` | Create a buyer Want (structured purchase intent) and return matches. |
| `demand_search` | Find matched supply for a query without persisting a Want. |
| `demand_get_want` | Retrieve a Want by id with its current matches. |
| `demand_record_outcome` | Report viewed/clicked/purchased for attribution + match-quality learning. |
| `demand_list_verticals` | Discover supported verticals + spec keys. |
| `demand_list_constraints` | Discover the constraint vocabulary. |
| `demand_health` | Liveness + active supply sources. |

## Options

`get_iwant_tools(...)`:

- `api_key` (required) — `iwant_ak_...`
- `base_url` — defaults to `https://iwant.fyi`
- `transport` — `"mcp"` (default) or `"http"` for the REST fallback
- `client` — reuse an existing `IwantClient` (testing / pooling)

## License

Apache-2.0. Full protocol spec: [iwant.fyi/protocol/v1](https://iwant.fyi/protocol/v1).
