Metadata-Version: 2.4
Name: url4
Version: 0.1
Summary: More accurate AI than any single model. The open protocol for AI model ensembles.
Author: Andrew Trask
License-Expression: Apache-2.0
Project-URL: Homepage, https://url4.ai
Project-URL: Repository, https://github.com/iamtrask/url4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.30.0
Requires-Dist: openai>=1.30.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: eval
Requires-Dist: datasets>=2.0.0; extra == "eval"
Dynamic: license-file

# url4

More accurate AI than any single model. The open protocol for AI model ensembles.

## Install

```bash
pip install url4
```

## Quick Start

```python
import asyncio
from url4 import Council

async def main():
    council = Council("claude-haiku|gpt-4o-mini")
    result = await council.ask("What causes auroras?")
    print(result.response)

asyncio.run(main())
```

## What It Does

url4 queries multiple AI models in parallel and synthesizes their responses into a single, more accurate answer. Like an ensemble in machine learning — but for LLMs.

```python
# Weighted ensemble with custom synthesis instruction
council = Council("0.5*claude-opus|0.3*gpt-4o|0.2*gemini-pro!synthesize the most accurate answer")
result = await council.ask("What is dark matter?")

# Streaming output
async for chunk in council.ask_stream("Explain quantum computing"):
    print(chunk, end="", flush=True)

# Cost estimation before running
estimate = council.estimate("any prompt")
print(f"Estimated cost: ${estimate.total_cost:.4f}")
```

## Features

- **Multi-model ensembles** — query any combination of Claude, GPT, Gemini, Llama, Mistral, DeepSeek
- **Weighted synthesis** — control how much each model contributes
- **Streaming** — stream the synthesis output token by token
- **Caching** — responses are cached locally so repeated queries are free
- **Nested councils** — councils of councils for multi-level synthesis
- **Progressive reduce** — synthesize at checkpoints as models respond
- **Cost estimation** — estimate costs before executing
- **CLI** — `url4 ask "claude|gpt-4o" "your question"`
- **Eval harness** — benchmark councils against HLE and other datasets

## CLI

```bash
url4 ask "claude-haiku|gpt-4o-mini" "What is 2+2?"
url4 estimate "claude-opus|gpt-4o" "anything"
url4 models
url4 cache-stats
```

## API Keys

Set the API keys for the providers you want to use:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export OPENROUTER_API_KEY=sk-or-...  # optional: routes to 200+ models
```

If you have Claude Code installed, url4 can use it as a zero-config fallback — no API keys needed.

## The Protocol

url4 is a URL-based grammar for composing AI queries:

```
claude-haiku|gpt-4o!What is the meaning of life?
```

Sources left of `!`, prompt right of `!`. Pipe `|` separates sources. Weights with `*`, nesting with `[]`:

```
0.5*claude-opus|0.3*[gpt-4o|gemini!draft]|0.2*deepseek!final synthesis
```

Full spec: [url4.ai/spec.html](https://url4.ai/spec.html)

## License

Apache 2.0
