Python for logic. English for intelligence.
from alloy import command @command(output=float) def extract_price(text: str) -> str: return f"Extract the price from: {text}" print(extract_price("This costs $49.99")) # 49.99Write typed AI functions that feel like normal Python. No framework, no abstractions — just functions that happen to use AI.
Install • Tutorial • Examples • Docs
pip install alloy-ai # OpenAI only pip install 'alloy-ai[anthropic]' # With Anthropic pip install 'alloy-ai[providers]' # All providersQuick start (OpenAI):
export OPENAI_API_KEY=sk-... python -c "from alloy import ask; print(ask('Say hello'))"🎯 Types you can trust: Provider‑enforced structured outputs. Get a real float, not a string to parse.
🐍 Just Python: Commands are functions. Tools are functions. Everything composes.
⚡ Production‑ready: Retries, contracts, streaming, cross‑provider support — batteries included.
🔍 Zero magic: See what’s happening. Control what’s happening. No hidden state.
Exploration with ask — Quick one‑offs and streaming
from alloy import ask # One‑liner exploration print(ask("List 3 reasons Alloy is useful.")) # Stream text output (text‑only streaming) for chunk in ask.stream("Write a two‑sentence pitch for Alloy."): print(chunk, end="")Typed outputs — Get back real Python objects
from dataclasses import dataclass from alloy import command @dataclass class Analysis: sentiment: str score: float keywords: list[str] @command(output=Analysis) def analyze(text: str) -> str: return f"Analyze this text: {text}" result = analyze("Alloy is amazing!") print(result.score) # 0.95TypedDict outputs are supported too:
from typing import TypedDict from alloy import command class Product(TypedDict): name: str price: float @command(output=Product) def make() -> str: return "Return a Product with name='Test' and price=9.99 (numeric literal)." print(make()["price"]) # 9.99Tools + Contracts — Safe multi‑step workflows
from alloy import command, tool, ensure, require @tool @ensure(lambda x: x > 0, "Result must be positive") def calculate(expression: str) -> float: return eval(expression) # simplified example @command(tools=[calculate]) def solve(problem: str) -> str: return f"Solve step by step: {problem}"See more in examples/ and the Examples guide.
📦 More installation options
# Specific providers pip install 'alloy-ai[anthropic]' pip install 'alloy-ai[gemini]' pip install 'alloy-ai[ollama]' # Development pip install -e '.[dev]'🔧 Configuration
export ALLOY_MODEL=gpt-5-mini export ALLOY_TEMPERATURE=0.2 export ALLOY_MAX_TOOL_TURNS=10Or in Python:
from alloy import configure configure(model="gpt-5-mini", temperature=0.2)🧪 Run examples offline
export ALLOY_BACKEND=fake make examples-quickWorks with major providers — same code, zero changes:
| Provider | Models (examples) | Setup |
|---|---|---|
| OpenAI | gpt‑5 | export OPENAI_API_KEY=... |
| Anthropic | claude‑4 | export ANTHROPIC_API_KEY=... |
| gemini | export GOOGLE_API_KEY=... | |
| Local | ollama | ollama run <model> + ALLOY_MODEL=ollama:<model> |
See the full provider guide.
New to Alloy? → 10‑minute tutorial
Ready to build? → Browse examples
Need details? → Read the docs
We welcome contributions! See .github/CONTRIBUTING.md.
MIT — see LICENSE.