Metadata-Version: 2.5
Name: udiagent
Version: 0.10.0
Summary: UDI Agent: LLM-powered data visualization orchestration library
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: openai>=3.33.0
Requires-Dist: pydantic>=2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.32.5
Provides-Extra: all
Requires-Dist: datasets>=5.0.1; extra == 'all'
Requires-Dist: duckdb>=1.0.0; extra == 'all'
Requires-Dist: fastapi[standard]>=0.143.0; extra == 'all'
Requires-Dist: huggingface-hub>=2.2.0; extra == 'all'
Requires-Dist: ijson>=3.4.0.post0; extra == 'all'
Requires-Dist: langfuse>=4; extra == 'all'
Requires-Dist: openai[bedrock]; extra == 'all'
Requires-Dist: pandas>=2.0.0; extra == 'all'
Requires-Dist: pydantic-settings>=2.0; extra == 'all'
Requires-Dist: pymysql>=1.1.0; extra == 'all'
Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
Requires-Dist: python-jose[cryptography]>=3.5.0; extra == 'all'
Requires-Dist: udi-grammar-py; extra == 'all'
Provides-Extra: bedrock
Requires-Dist: openai[bedrock]; extra == 'bedrock'
Provides-Extra: benchmark
Requires-Dist: datasets>=5.0.1; extra == 'benchmark'
Requires-Dist: huggingface-hub>=2.2.0; extra == 'benchmark'
Requires-Dist: ijson>=3.4.0.post0; extra == 'benchmark'
Provides-Extra: codegen
Requires-Dist: pandas>=2.0.0; extra == 'codegen'
Requires-Dist: udi-grammar-py; extra == 'codegen'
Provides-Extra: duckdb
Requires-Dist: duckdb>=1.0.0; extra == 'duckdb'
Provides-Extra: langfuse
Requires-Dist: langfuse>=4; extra == 'langfuse'
Provides-Extra: server
Requires-Dist: fastapi[standard]>=0.143.0; extra == 'server'
Requires-Dist: pydantic-settings>=2.0; extra == 'server'
Requires-Dist: python-dotenv>=1.0.0; extra == 'server'
Requires-Dist: python-jose[cryptography]>=3.5.0; extra == 'server'
Provides-Extra: starrocks
Requires-Dist: pymysql>=1.1.0; extra == 'starrocks'
Provides-Extra: test
Requires-Dist: cryptography>=42.0.0; extra == 'test'
Requires-Dist: duckdb>=1.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# UDIAgent

LLM-powered data visualization orchestration library for the Universal Discovery Interface (UDI).

UDIAgent orchestrates LLM calls to generate data visualization specs from natural language queries. It can be used as a **standalone Python library** or deployed as a **FastAPI microservice**.

## Installation

```bash
# Core library only
pip install udiagent

# With the reference FastAPI server
pip install udiagent[server]

# With LangFuse observability
pip install udiagent[langfuse]

# With Amazon Bedrock IAM-role (SigV4) authentication
pip install udiagent[bedrock]

# With benchmarking tools
pip install udiagent[benchmark]

# Everything
pip install udiagent[all]
```

For local development with `uv`:

```bash
uv sync --extra server --extra langfuse --extra test --extra bedrock   # server + dev
```

## Quick start

As a library:

```python
from udiagent import UDIAgent, Orchestrator

agent = UDIAgent(gpt_model_name="gpt-5.4", openai_api_key="sk-...")
result = Orchestrator(agent).run(
    messages=[{"role": "user", "content": "Show me a bar chart of donors by sex"}],
    data_schema='{"resources": [...]}',
    data_domains='[{"entity": "donors", "field": "sex", ...}]',
)
# result.tool_calls: the tool calls to apply (RenderVisualization, FilterData, ...)
```

As a server, for local development (from `packages/agent`):

```bash
INSECURE_DEV_MODE=1 uv run --extra server fastapi dev src/udiagent/server/app.py --port 8007
```

## Documentation

- [Library usage](docs/library.md): configuration, template sets, reasoning
  models, OpenAI-compatible backends, Amazon Bedrock, LangFuse.
- [Running the server](docs/server.md): environment variables, identity
  providers, server-side query backends, Docker.
- [Deployment guide](docs/deployment.md): standing the server up on a host.
- [How the agent works](docs/architecture.md): the request flow, chart
  templates, filters, and regenerating the generated template files.
- [Benchmarking](docs/benchmarking.md): measuring a server configuration.
- [Server-side data](src/udiagent/query/README.md): compiling the grammar to SQL.
- Reference: the [Python API](https://hms-dbmi.github.io/udi-yac/docs/backend/python-api/)
  and the [HTTP API](https://hms-dbmi.github.io/udi-yac/docs/backend/http-api/)
  (from [`openapi.json`](openapi.json)).

## License

MIT
