Metadata-Version: 2.5
Name: llama-index-tools-treza
Version: 0.1.0
Summary: Treza tools for LlamaIndex: generate AI pictures and videos and run Treza pipelines, with a price cap on every render.
Project-URL: Homepage, https://www.trezalabs.com
Project-URL: Repository, https://github.com/treza-labs/llama-index-tools-treza
Project-URL: Issues, https://github.com/treza-labs/llama-index-tools-treza/issues
Author-email: "Treza Labs, Inc." <hello@trezalabs.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai video,image generation,llama-index,llamaindex,tools,treza,video generation
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: llama-index-core<0.15,>=0.12.0
Requires-Dist: requests<3,>=2.31
Description-Content-Type: text/markdown

# llama-index-tools-treza

[Treza](https://www.trezalabs.com) tools for LlamaIndex. An agent can generate AI pictures and video clips and run your saved Treza pipelines. Treza prices every render first, and a `max_cost_usd` you set stops any render that costs more, with nothing spent.

## Install

```bash
pip install -U llama-index-tools-treza
```

Create a Treza account at https://www.trezalabs.com, add credits, and make an API key at https://www.trezalabs.com/platform/api-keys with the `pipelines:read`, `pipelines:write` and `pipelines:run` permissions. Then:

```bash
export TREZA_API_KEY="treza_live_..."
```

The package is free. Renders are paid from your prepaid Treza credits; there is no subscription.

## Tools

`TrezaToolSpec` gives an agent five tools:

| Tool | What it does | Cost |
| --- | --- | --- |
| `generate_image` | A picture from a prompt, optionally from reference pictures. | Treza credits |
| `generate_video` | A video clip from a prompt, optionally opening or ending on a picture. | Treza credits |
| `run_pipeline` | Runs one of your saved Treza pipelines, with new inputs if given. | Treza credits |
| `get_run` | Looks up a render that was still going when its tool stopped waiting. | Free |
| `get_balance` | The credits left on the account. | Free |

A finished render comes back as JSON:

```json
{"url": "https://media.trezalabs.com/...mp4", "status": "success", "finished": true,
 "price_usd": 0.28, "model": "google/veo-3.1-lite", "render_seconds": 56.0,
 "run_id": "...", "pipeline_id": "pipeline_..."}
```

## Use it

```python
from llama_index.tools.treza import TrezaToolSpec

treza = TrezaToolSpec(max_cost_usd=1.00)
print(treza.generate_video("A red fox trots through fresh snow", aspect_ratio="9:16", duration_sec=4))
```

## Give the tools to an agent

```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.anthropic import Anthropic
from llama_index.tools.treza import TrezaToolSpec

agent = FunctionAgent(
    tools=TrezaToolSpec(max_cost_usd=1.00).to_tool_list(),
    llm=Anthropic(model="claude-sonnet-5-5"),
)
response = await agent.run("Make a 4 second vertical clip of a fox in snow.")
```

Pass `spec_functions=[...]` to `to_tool_list` to hand over only some of the tools.

## Spending

- `max_cost_usd` is set in your code. The model cannot see or change it, and it cannot see the API key.
- With a cap set, Treza prices the render first. If the price is higher, the tool answers "This render costs $X, over the Max cost of $Y. Nothing was spent." and starts nothing.
- With no cap (`None`, the default), a render runs at Treza's quoted price as long as the balance covers it. **Set a cap on tools you give to an agent.**
- A render never starts when the balance does not cover its price.

## Long renders

Pictures usually take under a minute and videos one to five minutes. Each tool waits up to `wait_seconds` (300 by default). A render still going after that comes back with `"status": "running"` and its `run_id` and `pipeline_id`, not as an error, and nothing is started twice. The get-run tool returns the file once it is done.

## Errors

Refusals (over the cap, low balance, a bad key, a render that broke) go back to the agent as text, so it can react. Pass `raise_on_refusal=True` to have them raise `TrezaError` instead.

## Network and privacy

The tools call Treza's API over HTTPS at `www.trezalabs.com`. They send the prompt and settings with your API key, and store nothing. Privacy policy: https://docs.trezalabs.com/terms-and-privacy/privacy

## Development

```bash
pip install -e . pytest
pytest
```

The tests run against a scripted stand-in for Treza's API.

## Support

Issues: https://github.com/treza-labs/llama-index-tools-treza/issues · Email: hello@trezalabs.com

MIT licensed.
