2608 Typing B1ef9c8b

Typing

Alloy provides precise static types for commands and ask via .pyi stubs.

• Use @command(output=T) for a typed result T.
• If you omit output, the command returns str (and Awaitable[str] for async).
• Parameters are preserved (ParamSpec), so your decorated command keeps the same args.
• Streaming always yields text chunks (str).

Basics

from alloy import command, ask

@command(output=float)
def extract_price(text: str) -> str:
    return f"Extract price from: {text}"

price: float = extract_price("the price is 5.99")

# No output → str
@command
def summarize(text: str) -> str:
    return f"Summarize: {text}"

summary: str = summarize("hello")

Async

from dataclasses import dataclass
from typing import Awaitable, AsyncIterable
from alloy import command

@dataclass
class User:
    name: str
    id: int

@command(output=User)
async def fetch_user(name: str) -> str:
    return f"Find user named {name} and return JSON"

user_awaitable: Awaitable[User] = fetch_user()
# after await -> User

# Streaming
chunks: AsyncIterable[str] = fetch_user.stream()

# Convenience
user_awaitable2: Awaitable[User] = fetch_user.async_()

Ask namespace

from typing import Iterable, AsyncIterable
from alloy import ask

text: str = ask("Explain in one sentence.")
sync_stream: Iterable[str] = ask.stream("Explain briefly.")
async_stream: AsyncIterable[str] = ask.stream_async("Explain briefly.")

Notes

• Import from alloy: from alloy import command, ask. Importing through submodules bypasses the stubs.
• Alloy does not infer from your function’s return annotation. The decorated function must be annotated -> str (it returns a prompt string). The decorator’s output parameter controls the command’s return type; when omitted, the return type is str.

IDE Experience

from dataclasses import dataclass
from alloy import command

@dataclass
class ArticleSummary:
    title: str
    key_points: list[str]
    reading_time_minutes: int

@command(output=ArticleSummary)
def summarize(text: str) -> str:  # returns a prompt string
    return f"Summarize: {text}"

result = summarize("...")
result.  # IDE autocompletes: title, key_points, reading_time_minutes