Examples

Runnable examples live in examples/.

Basic model creation

python examples/basic_usage.py

This loads AppSettings, configures the default SQLite-backed LangChain cache, and creates the configured testing chat model.

Model strings

python examples/model_string_usage.py

This demonstrates provider inference and conversion between bare, LangChain, and LiteLLM model-string styles.

Factory usage

python examples/factory_usage.py

This demonstrates the recommended runtime entry points: create_llm(...) for model construction and create_llm_bundle(...) when the caller also needs metadata.

Profiles and runtime

python examples/profile_usage.py
python examples/llm_runtime_usage.py

These show JSON-serializable ChatModelProfile configuration, profile resolution, namespaced cache keys, typed generation controls, optional logging, and the lazy LLM runtime id/uuid plus usage summary.

DSPy LM substrate

python examples/dspy_lm_usage.py

This optional example creates a native DSPy LM from ChatModelProfile and prints the resolved LiteLLM model name plus OOAI trace metadata. Install the extra first:

pip install "ooai-llm[dspy]"

ooai-llm stops at the LM substrate. DSPy signatures, modules, runnables, LangGraph nodes, optimizers, and artifact workflows belong in ooai-agents.

Live model discovery

python examples/model_discovery.py

The example lists a few OpenAI models by default. Change the provider argument in the file or pass a configured provider to list_available_models(...).

For a local provider sweep that skips missing credentials and defaults to OpenAI, Anthropic, DeepSeek, and Mistral:

python examples/live_provider_matrix.py

Override the provider list when needed:

OOAI_EXAMPLE_PROVIDERS=openai,anthropic,deepseek,mistral python examples/live_provider_matrix.py

Refresh convenience defaults from live provider catalogs or LiteLLM metadata:

python examples/model_defaults_refresh.py
ooai-llm models update --source litellm --providers openai,anthropic,mistral
OOAI_LLM__AUTO_REFRESH_MODELS__ENABLED=true \
OOAI_LLM__AUTO_REFRESH_MODELS__SOURCE=litellm \
OOAI_LLM__AUTO_REFRESH_MODELS__PROVIDERS='["openai"]' \
python examples/basic_usage.py

Filter the cross-provider model catalog by capability, date, context, and cost:

python examples/model_catalog_filters.py
ooai-llm models list \
  --source litellm \
  --tool-calling-only \
  --structured-output-only \
  --min-output-tokens 8000 \
  --sort output_tokens
ooai-llm models list --source litellm --providers openai,mistral --limit 5
ooai-llm models list --source litellm --providers openai,mistral --limit 5 --format json
ooai-llm models list --all-litellm --limit 0 --format json
ooai-llm models list --all-litellm --providers openrouter,fireworks_ai --limit 0

Compare catalog models by an explicit call shape:

python examples/catalog_insights.py
ooai-llm models cheapest \
  --source litellm \
  --providers mistral \
  --input-tokens 10000 \
  --output-tokens 2000 \
  --budget-usd 10
ooai-llm models coding \
  --source litellm \
  --providers openai,anthropic,google,deepseek,mistral \
  --tool-calling-only \
  --structured-output-only \
  --per-provider
ooai-llm models compare \
  --source litellm \
  --providers openai,anthropic,google,deepseek,mistral \
  --input-tokens 10000 \
  --output-tokens 2000 \
  --per-provider
ooai-llm models compare --source litellm --coding-only --baseline openai:gpt-5-mini
ooai-llm models compare \
  --source litellm \
  --providers openai,mistral \
  --structured-output-only \
  --min-output-tokens 8000 \
  --sort output_tokens \
  --baseline openai:gpt-5-mini \
  --limit 10 \
  --format csv

Print guided CLI and package recipes:

python examples/cli_tui_workflows.py
ooai-llm recipes --topic cheapest
ooai-llm recipes --topic coding
ooai-llm recipes --topic runtime --format markdown

Build reusable suites for model comparisons or LangGraph-style variants:

python examples/model_suites.py
ooai-llm models suite --suite comparison --providers openai,anthropic,mistral
ooai-llm models suite \
  --from-catalog \
  --source litellm \
  --tool-calling-only \
  --structured-output-only \
  --sort output_tokens \
  --limit 5
ooai-llm models suite --suite comparison --providers openai,mistral --no-rich

Planned Agentic Integration Examples

The agentic integration API is planned on the feat/agetns branch and is not implemented yet. The design target is that ooai-llm supplies configured model runtimes and accounting, while ooai-agents owns orchestration.

LangChain create_agent target:

from langchain.agents import create_agent
from ooai_llm import ChatModelProfile, LLMRegistry
from ooai_llm.agentic import ContextBudget, PromptPolicy, ToolPolicy

registry = LLMRegistry.from_profiles(
    {
        "cheap": ChatModelProfile(model="openai:gpt-5.4-mini", temperature=0),
        "coding": ChatModelProfile(model="anthropic:claude-sonnet-4.6"),
    }
)

augmented = registry.augment(
    "coding",
    prompt=PromptPolicy.static("Review code and return concrete fixes."),
    tools=ToolPolicy(
        tools=[read_file, edit_file, run_tests],
        allow_parallel_tool_calls=False,
        max_tool_retries=2,
    ),
    context=ContextBudget(max_used_percent=80, reserve_output_tokens=2_000),
)

agent = create_agent(**augmented.to_create_agent_kwargs())

Raw LangGraph node target:

async def coding_node(state, config):
    runtime = registry["coding"]
    snapshot = runtime.context_snapshot(
        messages=state["messages"],
        reserve_output_tokens=2_000,
    )

    if snapshot.context_used_percent > 85:
        state = await summarize_or_trim(state, snapshot=snapshot)

    response = await runtime.ainvoke(state["messages"], config=config)
    return {"messages": [response]}

Deep Agents target:

from deepagents import create_deep_agent

research = registry.augment(
    "research",
    prompt=PromptPolicy.static("Research only. Return citations."),
    tools=ToolPolicy(tools=[web_search, read_file]),
)

agent = create_deep_agent(
    **registry.augment("default").to_deep_agent_kwargs(
        subagents=[research.to_subagent(name="research-agent")],
    ),
    backend=backend,
    store=store,
)

The table commands render Rich panels and compact tables when Rich is installed. Use --format json or --format csv for machine-readable output and --no-rich when you need a plain fixed-width table.

Use the terminal recipe when you want copy/paste Rich and TUI examples, including TUI theme choices:

ooai-llm recipes --topic rich
pdm run ooai-llm tui --theme paper
pdm run ooai-llm tui --providers mistral --views cheapest,catalog --limit 10
pdm run ooai-llm tui --catalog-all
pdm run ooai-llm tui --theme mono --refresh-cooldown 0

Explore optional benchmark data from the segmented benchmarks namespace:

python examples/livecodebench_pro_explorer.py
ooai-llm benchmarks lcb-pro summary
ooai-llm benchmarks lcb-pro models --status active --limit 10
ooai-llm benchmarks lcb-pro difficulty --difficulty hard --provider openai

LiveCodeBench Pro uses an undocumented public leaderboard backend, so treat these examples as exploratory rather than provider-grade catalog APIs.

Inspect and set parallel tool-call controls:

python examples/tool_calling_controls.py
ooai-llm models suite --suite comparison --parallel-tool-calls false

Launch the optional Textual explorer:

ooai-llm tui --providers openai,anthropic,mistral --source litellm
ooai-llm tui --catalog-all

Install it with ooai-llm[tui] if Textual is not already available. Use --catalog-all when you want the broad raw LiteLLM registry rather than only ooai’s first-class supported providers.

Reasoning

python examples/reasoning_usage.py

This prints provider-specific constructor kwargs produced from semantic reasoning presets.

Metadata and callbacks

python examples/litellm_metadata_usage.py

This shows the metadata-aware bundle helper and the LiteLLM usage/cost callback factory.