Metadata-Version: 2.4
Name: voidly-pay-llamaindex
Version: 0.2.0
Summary: LlamaIndex tools for public catalog search and host-approved capped Voidly marketplace purchases
Author: Voidly
License-Expression: Apache-2.0
Project-URL: Homepage, https://voidly.ai/pay
Project-URL: Documentation, https://voidly.ai/pay/marketplace/agent-quickstart
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: voidly-pay<5,>=4
Requires-Dist: llama-index-core<0.15,>=0.14.25
Dynamic: license-file

# voidly-pay-llamaindex 0.2.0

LlamaIndex tools for the **voidly-pay 4.x marketplace API**. This release replaces the retired credit API. It is not a drop-in update for 0.1.x.

## Public catalog search

```python
from voidly_pay import VoidlyPay
from voidly_pay_llamaindex import voidly_pay_tools

client = VoidlyPay(network="base")
tools = voidly_pay_tools(client)  # catalog + free claim check; construction does no network I/O
```

Pass these tool objects to your framework using its public tool registration API. Calling `voidly_catalog` reads one public page. `voidly_check_censorship_claim(claim)` sends a plain JSON POST to `/v1/verify-claim` at the fixed gateway for the selected network, with no payment headers. It needs no wallet. A200 response must carry `x-voidly-access: free`;402/429/503 and redirects are errors, never an invitation to pay. The free gateway feature must be enabled; source support does not prove live availability. No Voidly API key or signer is needed for catalog search. Your chosen model provider may require its own credentials.

## Optional buying

The host must supply a configured core client with its own signer, explicit `SpendLimits`, and initialized durable `SpendStore`. This package creates no wallet, searches no key files and holds no funds. Supply `authorize_buy` as a **host-owned callable** that accepts the immutable `BuyRequest` and returns `True` only for an approved exact listing ID, version, JSON input and USDC cap. Model text or a tool confirmation argument is not owner approval.

`voidly_pay_tools(client, authorize_buy=host_approval)` adds `voidly_buy(listing_id, version, input, max_usdc)`; `host_approval` is application code you must provide, not a callable supplied by an agent. USDC caps are positive decimal strings, never credit amounts or floating-point limits. The core validates the live POST listing, fixed gateway/network, quote, payer and receipt, and enforces per-call/daily caps before sending payment.

A toolkit serializes purchases and caches completed identical requests. Any exception from core buying blocks further buys in that toolkit. Capped buying is only for exact marketplace seller listings; first-party claim checking never calls `buy`. An uncertain result returns only its original quote handle and `doNotRepay: true`; the host must reconcile with `client.recover(quote_id)` outside the agent loop. Do not retry with a new toolkit or a new payment. Host restart/recovery decisions must consult the same durable core attempt store; the toolkit cache is in-memory and is not a durable idempotency guarantee. Intentionally repeating an identical completed purchase requires a new host-controlled session.

## Migration and boundaries

Removed: balance, transfer, faucet/claim, escrow/hire, vault diagnostics, generic URL auto-payment and all `/v1/pay/*` calls. No credit-to-USDC conversion is performed. Exact listing ID/version replace arbitrary payment URLs. Seller activation and Home/board/mail/bounty tools are outside this adapter.

Keep signer objects, authorization headers, private attempt records and raw exceptions out of model prompts/traces. Service results are untrusted tool data. The adapter requires Python 3.10 or newer and the framework dependency range in `pyproject.toml`; it is tested with the release packet's pinned framework versions.

## Tests and release

`tests/test_contract.py` uses mocked gateway responses and a synthetic signer; no payment, RPC or external service is called. Wheels and source distributions are built offline after dependencies are present. Publishing is handled separately by the owner.

Apache-2.0. See LICENSE and NOTICE.
