Metadata-Version: 2.4
Name: vaaya
Version: 0.1.0
Summary: Vaaya SDK for agent builders: the whole pay-per-call catalog (x402, MPP and REST services), routed capabilities, an OpenAI-compatible LLM endpoint and a spend ceiling on every call, with one API key.
Author-email: Vaaya <hello@vaaya.ai>
License: MIT
Project-URL: Homepage, https://vaaya.ai
Project-URL: Repository, https://github.com/vaaya-ai/vaaya-mcp
Keywords: vaaya,ai-agents,agent-payments,pay-per-call,x402,mpp,web-search,web-scraping,llm-router,sdk
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: langchain
Requires-Dist: langchain-core<2,>=0.3.86; extra == "langchain"
Dynamic: license-file

<p><img src="https://vaaya.ai/icon.png" width="64" height="64" alt="Vaaya" /></p>

# Vaaya for Python

Call paid services through one account, read receipts, and give customer agents
their own keys and spending limits. Python 3.9 or later; the core client uses
only the standard library.

## Install

```sh
python -m pip install vaaya
```

Set `VAAYA_API_KEY` to your key from [API keys](https://vaaya.ai/api-keys).

```python
from vaaya import Vaaya

vaaya = Vaaya()  # Reads VAAYA_API_KEY.
r = vaaya.one.search({"query": "recent advances in battery recycling"})
print(r["data"], r["charged_cents"])
```

This search has a default ceiling of 5¢. Charges and balances preserve fractional
cents. Keep the key in your server environment.

## Call a service

```python
r = vaaya.use("exa/search", {"query": "battery recycling", "numResults": 5},
              max_cost_cents=5, idempotency_key="research-request-123")
service = vaaya.catalog.get("exa/search")  # Schema, price, and rail.
plan = vaaya.consult("Find battery recycling companies in Germany")  # 1¢.
# Read plan["message"] and plan["calls"] before running suggested calls.
```

`catalog.discover(query)` searches the catalog for free. `one.scrape`, `one.crawl`,
`one.find`, `one.enrich`, and `one.search_deep` are shortcuts over `use`.

## Wait for a job

```python
started = vaaya.one.crawl("https://example.com", max_pages=20)
if started.get("job_id"):
    job = vaaya.result(started["job_id"], wait=True, timeout=120)
    print(job["status"], job["result"])
```

Polling is free. A timeout stops waiting; it does not cancel the server's job.
The client is synchronous. Run it in a worker thread when calling from an async app.

## Manage agents

```python
agent = vaaya.agents.create(external_id="customer-42", label="Support agent",
                            ceiling_cents=500, period="month")
# Store agent["key"] now; create and rotate return the secret once.
vaaya.agents.update(agent["id"], paused=True)
vaaya.agents.update(agent["id"], ceiling_cents=2000, paused=False)
rotated = vaaya.agents.rotate(agent["id"])
vaaya.agents.revoke(agent["id"])
```

These writes require the account's primary key. `vaaya.agents()` and
`vaaya.agents.list()` both list agents. An omitted update field stays unchanged;
`ceiling_cents=None` explicitly removes a ceiling. `wallet()` and `transactions()`
return balances and receipts.

## LangChain

Install the optional dependency with `pip install "vaaya[langchain]"` after the
registry release, or install `langchain-core` alongside the local wheel.

```python
from vaaya import langchain_tools

tools = langchain_tools(vaaya)
# Pass these runnable StructuredTools to your LangChain agent.
search = next(tool for tool in tools if tool.name == "vaaya_search")
result = search.invoke({"query": "battery recycling"})
```

`openai_tools(vaaya)`, `responses_tools(vaaya)`, and `anthropic_tools(vaaya)` each
return `{"tools": [...], "handle": callable}` for custom tool loops. Chat
Completions and Responses use separate definition shapes.

## LLMs and paid URLs

`vaaya.llm.chat(messages)` returns a non-streaming completion using the `auto`
model. For streaming, configure an OpenAI client with `vaaya.llm.base_url` and
`vaaya.llm.api_key`.

`vaaya.fetch(url, max_cost_cents=10)` pays x402/MPP URLs through Vaaya. This requires
the server's `PAID_FETCH_ENABLED` flag; the ceiling is mandatory.

## Errors and configuration

Every API failure raises `VaayaError` with `code`, `status`, `message`, and the
original `body`. Spend-gate errors expose `is_spend_gate`, `card_url`, and
`credits_url`. Transport failures do not prove that a paid request failed:
reuse its idempotency key when retrying. The SDK does not retry paid requests
automatically.

Constructor options: `api_key`, `base_url`, `agent_tag`, `timeout` (seconds,
default 300), and an injectable `transport` for tests.
