llmcapa

Lookup capabilities (context window, modalities, supported features) of various LLM models — fully offline by default.

Features

• Comprehensive Bundled Data: Offline capability data for OpenAI, Anthropic, Google (Gemini), Microsoft (Phi), Amazon (Nova/Titan), Meta (Llama), Mistral, Cohere (Command), Qwen, DeepSeek, xAI (Grok), NVIDIA, MoonshotAI (Kimi), zhipu-ai (GLM), Sakana AI (Fugu), Azure AI Foundry, Novita AI, Together AI (98 models), OpenRouter, HuggingFace (2,675 popular models), and Japanese domestic models (NTT tsuzumi, PFN PLaMo, ELYZA, SoftBank, NEC, Fujitsu, etc. adopted by the Digital Agency's "GENNAI" platform).
• Zero Runtime Dependencies: Built entirely on the Python standard library.
• Alias Resolution: Automatically resolves model aliases and provider-specific names (e.g., gpt-4o-2024-08-06 -> gpt-4o, gemini-1.5-pro-preview-0409 -> gemini-1.5-pro).
• Provider Aliases: Provider arguments accept common aliases and normalized forms (e.g., grok/x-ai → xai, bedrock/aws-bedrock/aws → amazon, vertexai → vertex-ai, open-ai → openai, google-ai → google, azure → azure-openai, hf → huggingface, alibaba/dashscope → qwen, lm-studio → lmstudio). Separators _. are treated as -.
• Advanced Feature Queries: Check support for vision, multimodal, chat_completion, responses_api, realtime, reasoning_effort, thinking_budget, and specific input/output modalities (e.g., image_input, audio_input, file_input, speech_input, embedding_output). PDF is treated as a subtype of file_input.
• High Performance: Evaluated feature checks are cached internally using memoization to avoid redundant calculations.
• Cost Estimation: Estimate API costs based on input and output token counts.
• Drop-in Replacement Checker: Check if a model can be safely replaced by another model based on context window and required features.
• Tokenizer Mapping: Access tokenizer names (e.g., o200k_base) directly from model capabilities.
• Extendable: Load your own local JSON model definitions.
• Ollama & HuggingFace Support: Full capability data for 1,638 Ollama models and 2,675 popular HuggingFace models across 236 base models with all size variants (codegemma, llama, qwen, mistral, deepseek, gemma, phi, etc.). Zero-cost local inference models included.
• FIM (Fill-in-the-Middle) Support: Check if a model supports code infilling via cap.supports('fim'). Supported for codegemma, codellama, starcoder2, deepseek-coder, qwen2.5-coder, and more.
• CLI Included: Query and list model capabilities directly from your terminal.

Install

pip install llmcapa

Or from source:

pip install .

Usage

Basic Lookup

import llmcapa

# Get model capabilities (case-insensitive, alias-resolved)
cap = llmcapa.get("gpt-4o")
# Provider aliases: grok→xai, bedrock→amazon, alibaba→qwen, lm-studio→lmstudio, ...
# cap = llmcapa.get("grok-4", provider="grok")
print(cap.context_window)       # 128000
print(cap.max_output_tokens)    # 16384
print(cap.tokenizer_name)       # "o200k_base"

# Check feature support (using strings or Feature enum)
from llmcapa import Feature, ReasoningEffort

print(cap.supports(Feature.LLMC_FEAT_VISION))             # True
print(cap.supports(Feature.LLMC_FEAT_RESPONSES_API))      # True
print(cap.supports(Feature.LLMC_FEAT_REASONING_EFFORT))   # False

# Use ReasoningEffort enum for models supporting reasoning_effort
print(ReasoningEffort.LLMC_EFFORT_HIGH)                   # "high"
# List all supported features
print(cap.features())
# ['chat_completion', 'file', 'file_input', 'function_calling', 'image', 'image_input', 'json_mode', 'multimodal', 'responses_api', 'streaming', 'text', 'text_input', 'text_output', 'vision']

Token & Cost Estimation

Roughly estimate the number of tokens for a given text (supporting 30+ major languages) and calculate API costs:

[!NOTE] Token estimation is a lightweight, offline approximation. For exact token counts, please use the official APIs or dedicated tokenizers from each provider.

gpt = llmcapa.get("gpt-4o")

# Estimate tokens for multilingual text
# If `tiktoken` is installed, it dynamically uses it for exact OpenAI token counts.
# Otherwise, it falls back to a highly-optimized, standard-library-only estimation.
text = "Hello world! こんにちは世界。"
tokens = gpt.estimate_tokens(text)
print(tokens)  # 10 (estimated tokens)

# Estimate API costs based on token counts (returns cost and currency)
res = gpt.estimate_cost(input_tokens=1500, output_tokens=500)
print(res)  # {'cost': 0.00875, 'currency': 'USD'}

Drop-in Replacement Checker

Check if a model can be safely replaced by another model. The replacement model must have a context window at least as large as the target model and support all required features.

gpt4o = llmcapa.get("gpt-4o")
gpt4o_mini = llmcapa.get("gpt-4o-mini")
gemini = llmcapa.get("gemini-3.5-flash")

# gpt-4o-mini has the same context window and supports all the same features
print(gpt4o.can_be_replaced_by(gpt4o_mini))  # True

# gemini-3.5-flash has a larger context window but lacks responses_api (which gpt-4o supports)
print(gpt4o.can_be_replaced_by(gemini))  # False

# If we only require vision and function_calling, gemini-3.5-flash can replace gpt-4o
print(gpt4o.can_be_replaced_by(gemini, required_features=["vision", "function_calling"]))  # True

Modality & Multimodal Checks

You can check specific input/output modalities or general multimodal support using Feature enum:

from llmcapa import Feature

gemini = llmcapa.get("gemini-3.5-flash")

print(gemini.supports(Feature.LLMC_FEAT_MULTIMODAL))    # True (supports multiple modalities)
print(gemini.supports(Feature.LLMC_FEAT_AUDIO_INPUT))   # True
print(gemini.supports(Feature.LLMC_FEAT_IMAGE_OUTPUT))  # False

Realtime and Additional Modality Checks

Use the Feature enum to query Realtime APIs, file inputs, speech input/output, and embedding outputs. PDF is treated as a subtype of file_input.

from llmcapa import Feature

realtime = llmcapa.get("gpt-realtime-2")
print(realtime.supports(Feature.LLMC_FEAT_REALTIME))        # True
print(realtime.supports(Feature.LLMC_FEAT_SPEECH_INPUT))   # True
print(realtime.supports(Feature.LLMC_FEAT_SPEECH_OUTPUT))  # True

pdf_model = llmcapa.get("muse-spark-1.1", provider="meta")
print(pdf_model.supports(Feature.LLMC_FEAT_FILE_INPUT))     # True

embedding = llmcapa.get("text-embedding-3-large", provider="openai")
print(embedding.supports(Feature.LLMC_FEAT_EMBEDDING_OUTPUT))  # True

bedrock resolves to Amazon. google and vertex-ai are separate providers.

nova = llmcapa.get("nova-sonic-v1", provider="bedrock")
gemini_live = llmcapa.get("gemini-3.1-flash-live-preview", provider="google")

Reasoning & Thinking Checks

See the full provider-neutral API specification in docs/API_SPECIFICATION.md.

Differentiate between OpenAI-style reasoning_effort and Anthropic-style thinking_budget using Feature enum:

from llmcapa import Feature

o1 = llmcapa.get("o1")
print(o1.supports(Feature.LLMC_FEAT_REASONING_EFFORT))  # True
print(o1.supports(Feature.LLMC_FEAT_THINKING_BUDGET))   # False

claude = llmcapa.get("claude-3-7-sonnet")
print(claude.supports(Feature.LLMC_FEAT_REASONING_EFFORT))  # False
print(claude.supports(Feature.LLMC_FEAT_THINKING_BUDGET))   # True

Reasoning Effort Values

Retrieve the list of valid reasoning_effort values supported by a specific model:

cap = llmcapa.get("gpt-5.5")
print(cap.get_reasoning_effort_values())
# ['none', 'minimal', 'low', 'medium', 'high', 'xhigh']

cap2 = llmcapa.get("o1")
print(cap2.get_reasoning_effort_values())
# ['none', 'low', 'medium', 'high']

# Models without reasoning_effort support return an empty list
cap3 = llmcapa.get("gpt-4o")
print(cap3.get_reasoning_effort_values())
# []

Thinking Budget Values

Retrieve information about valid thinking_budget values for models that support it:

cap = llmcapa.get("claude-sonnet-4-20250501")
print(cap.get_thinking_budget_values())
# {'type': 'token_range', 'min': 1024, 'max': 128000}

cap2 = llmcapa.get("deepseek-r1")
print(cap2.get_thinking_budget_values())
# {'type': 'token_range', 'min': 1024, 'max': 8192}

# Models without thinking_budget support return an empty dict
cap3 = llmcapa.get("gpt-4o")
print(cap3.get_thinking_budget_values())
# {}

Thinking Level Values

Gemini 3 and other APIs with discrete thinking controls use thinking_level, which is distinct from both reasoning_effort and numeric thinking_budget:

cap = llmcapa.get("gemini-3-flash-preview", provider="vertex-ai")
print(cap.supports(Feature.LLMC_FEAT_THINKING_LEVEL))  # True
print(cap.get_thinking_level_values())
# ['minimal', 'low', 'medium', 'high']

# For Gemini 2.5 / Vertex AI numeric budgets:
budget = llmcapa.get("gemini-2.5-flash", provider="vertex-ai")
print(budget.get_thinking_budget_values())
# {'type': 'token_range', 'min': 0, 'max': 24576}

llmcapa reports the provider-specific capability metadata; the application passes the selected thinking_level or thinking_budget to the provider API.

For provider-neutral request construction, use thinking_control:

control = cap.get_thinking_control()
# {'kind': 'level', 'parameter': 'thinking_level',
#  'values': ['minimal', 'low', 'medium', 'high']}

minimax = llmcapa.get("MiniMax-M3", provider="minimax")
print(minimax.get_thinking_control())
# {'kind': 'toggle', 'parameter': 'thinking',
#  'values': ['enabled', 'disabled'], ...}

This is additive and does not change the existing reasoning_effort or thinking_budget APIs.

Sakana Fugu (Multi-Agent Orchestration)

Sakana AI's Fugu is a multi-agent orchestration system presented as a single model. It dynamically coordinates frontier models to tackle complex tasks. llmcapa bundles capability data for both Fugu and Fugu Ultra.

import llmcapa

# Look up Fugu models (case-insensitive, alias-resolved)
fugu = llmcapa.get("fugu")
print(fugu.context_window)       # 272000
print(fugu.max_output_tokens)    # 128000
print(fugu.supports("vision"))   # True (text+image input)
print(fugu.pricing)              # {'input_per_1m': 5.0, 'output_per_1m': 30.0, ...}

fugu_ultra = llmcapa.get("fugu-ultra")
print(fugu_ultra.context_window) # 1000000 (1M tokens)
print(fugu_ultra.pricing)        # {'input_per_1m': 5.0, 'output_per_1m': 30.0, ...}

# List all Sakana models
for cap in llmcapa.list_models(provider="sakana"):
    print(cap.model_id, cap.context_window)

FIM (Fill-in-the-Middle) Support

Check if a model supports code infilling / Fill-in-the-Middle completion:

import llmcapa

cap = llmcapa.get("codegemma:2b", provider="ollama")
print(cap.supports("fim"))       # True
print(cap.supports("vision"))    # False
print("fim" in cap.features())   # True

cap2 = llmcapa.get("llama3.1", provider="ollama")
print(cap2.supports("fim"))      # False

The fim feature is available as a Feature enum member:

from llmcapa import Feature
cap = llmcapa.get("starcoder2", provider="ollama")
print(cap.supports(Feature.LLMC_FEAT_FIM))  # True

Listing & Searching Models

# List all models for a specific provider
for c in llmcapa.list_models(provider="anthropic"):
    print(c.model_id, c.context_window)

# Search models by prefix (provider optional; aliases accepted)
search_results = llmcapa.search("codegemma", provider="ollama")
search_results = llmcapa.search("gpt-4o")  # all providers

# OpenRouter route IDs are searched only in the OpenRouter catalog.
# Native catalogs retain a provider's own namespace (which may contain `/`).
openrouter_results = llmcapa.search("meta/muse-spark-1.3", provider="openrouter")
# This is not a generic alias for the Meta catalog:
# llmcapa.get("meta/muse-spark-1.3", provider="meta")  # not found
# A slash is valid when it is part of the native ID itself, for example:
native_model = llmcapa.get("baichuan/baichuan-m2-32b", provider="novita")
big_reasoning_models = llmcapa.find(
    supports_reasoning=True,
    min_context_window=200000
)

Novita AI (Bundled Provider)

Novita AI is a cloud platform offering 200+ open-source and proprietary models via a single API. llmcapa bundles capability data for 136 Novita AI models, including DeepSeek, Qwen, Meta Llama, GLM, Gemini, and many more, with Novita-specific pricing.

Use the provider="novita" parameter to scope lookups to Novita AI models:

import llmcapa

# Look up Novita AI models using provider scope
cap = llmcapa.get("deepseek/deepseek-v3.2", provider="novita")
print(cap.context_window)  # 163840
print(cap.pricing)         # {'input_per_1m': 0.0269, 'output_per_1m': 0.04, 'currency': 'USD'}

cap = llmcapa.get("qwen/qwen3.7-max", provider="novita")
print(cap.context_window)  # 1000000

# List all Novita AI models
for c in llmcapa.list_models(provider="novita"):
    print(c.model_id, c.context_window, c.pricing)

# List all providers including Novita
print(llmcapa.providers())
# ['...', 'novita', '...']

On-demand OpenRouter Integration (Caching)

To update model data or fetch the latest pricing, you can optionally fetch and register models from the OpenRouter API on-demand using fetch_openrouter(). The response is cached locally in ~/.llmcapa/openrouter_cache.json and automatically loaded on subsequent imports (if the cache is less than 24 hours old), keeping the library fully offline during regular usage.

# Fetch and register OpenRouter models dynamically
count = llmcapa.fetch_openrouter()
print(f"Registered {count} models from OpenRouter!")

# Lookup using OpenRouter model ID
cap = llmcapa.get("meta-llama/llama-3.3-70b-instruct")
print(cap.context_window)  # 131072
print(cap.pricing)         # {'input_per_1m': 0.1, 'output_per_1m': 0.32, 'currency': 'USD'}

On-demand HuggingFace Integration (Caching)

You can also fetch and register popular models from the HuggingFace API on-demand using fetch_huggingface(). This retrieves the most downloaded text-generation and image-text-to-text models, registers their basic capabilities, and caches the result locally in ~/.llmcapa/huggingface_cache.json.

# Fetch and register top 100 HuggingFace models dynamically
count = llmcapa.fetch_huggingface()
print(f"Registered {count} models from HuggingFace!")

# Lookup using HuggingFace model ID
cap = llmcapa.get("deepseek-ai/DeepSeek-V4-Flash")
print(cap.context_window)   # 4096 (estimated; exact value not available via HF API)
print(cap.supports_vision)  # False (text-generation pipeline)

# Fetch a different number of models
count = llmcapa.fetch_huggingface(limit=200)

Note: The HuggingFace listing API does not provide context window, pricing, or detailed capability data. The registered models have estimated context windows based on their model family (e.g., Llama 3: 8K, Qwen3: 128K). The bundled huggingface.json includes 2,675 popular text-generation models with improved context window estimates. For exact specifications, use fetch_openrouter() or official model cards.

Token Counting (Standalone)

Count tokens for a single text or a list of chat messages using the best available tokenizer for a given model.

# Count tokens for a text string
import llmcapa
tokens = llmcapa.count_tokens("Hello, world!", "gpt-4o")
print(tokens)  # exact count if tiktoken is installed, else estimation

# Count tokens for chat messages (includes overhead)
messages = [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"},
]
total = llmcapa.count_messages_tokens(messages, "gpt-4o")
print(total)

Programmatic Registration

Register a Capability directly without a JSON file:

from llmcapa import Capability

cap = Capability(
    provider="local",
    model_id="my-model",
    context_window=4096,
    max_output_tokens=1024,
    supports_function_calling=True,
    aliases=["mm"],
)
llmcapa.register(cap)

print(llmcapa.get("my-model").context_window)  # 4096

Note: llmcapa.get() raises ModelNotFoundError if the model is not found.

Custom Local Data

Load your own model definitions from a local JSON file:

llmcapa.load_extra("my_models.json")

my_models.json format:

{
  "models": [
    {
      "provider": "local",
      "model_id": "my-custom-model",
      "context_window": 32768,
      "max_output_tokens": 4096,
      "supports_function_calling": true,
      "aliases": ["my-model-latest"]
    }
  ]
}

Computer Use / CUA Capabilities

llmcapa can describe whether a model supports Computer Use (CUA) without executing computer actions itself. The capability is optional, so existing model records and callers remain compatible.

import llmcapa

cap = llmcapa.get("claude-opus-4-5", provider="anthropic")
computer = cap.computer_use

if computer and computer.supported:
    print(computer.native)
    print(computer.tool_type)
    print(computer.tool_version)
    print(computer.beta_header)
    print(sorted(computer.actions))

Convenience checks are also available:

llmcapa.supports_computer_use("claude-opus-4-5", provider="anthropic")
llmcapa.supports_computer_action("claude-opus-4-5", "zoom", provider="anthropic")
llmcapa.supports_computer_environment("claude-opus-4-5", "desktop", provider="anthropic")

Native and custom-harness support

• native=True: the provider exposes a native Computer Tool/API. For example, Anthropic uses computer_20251124 or computer_20250124 with the corresponding beta header.
• native=False: the model can be used with an external Computer Runtime or custom tool harness, but the provider does not expose a native Computer Tool through this route. This applies to examples such as Qwen visual agents, local models, and OpenRouter custom tool calling.

tool_version is the normalized Computer Tool version. tool_type is the provider/API value, and beta_header is the optional request header or body field. checked_at records when the support information was verified. Model version and Computer Tool version are tracked separately.

llmcapa only reports capability metadata. The application remains responsible for screenshots, mouse/keyboard execution, the agent loop, isolation, and human confirmation for high-impact actions.

Examples of registered routes

# Direct Anthropic API
anthropic = llmcapa.get("claude-opus-4-5", provider="anthropic")
assert anthropic.computer_use.tool_type == "computer_20251124"

# Amazon Bedrock-hosted Claude
bedrock = llmcapa.get("us.anthropic.claude-opus-4-7", provider="amazon")
assert bedrock.computer_use.tool_type == "computer_20251124"

# OpenAI Responses API
openai = llmcapa.get("gpt-5.4", provider="openai")
assert openai.computer_use.tool_type == "computer"

OpenRouter and similar gateways are represented separately from direct provider routes. Generic tool calling can be combined with a custom harness, but it should not automatically be treated as the provider's native Computer Tool.

Computer Use replacement checks

When checking model replacement, request Computer Use explicitly. The replacement check compares the provider/API-specific tool contract, including the tool/schema type, environments, and actions; tool versions are metadata and are not used as a compatibility gate. required_actions is currently applicable to Computer Use only. supports("computer_use") alone is not treated as cross-provider compatibility.

source.can_be_replaced_by(
    target,
    required_features=["vision"],
    required_actions=["screenshot", "left_click", "type"],
    required_environment="desktop",
)

Development

For details on how to extend the library, add new providers, or implement new feature flags, please refer to the DEVELOP.md guide.

CLI

# Show capabilities of a specific model
llmcapa show gpt-4o
llmcapa show gpt-4o --json

# List all known models
llmcapa list
llmcapa list --provider google
llmcapa list --json --no-deprecated

# List all known providers
llmcapa providers

# Count tokens for text or messages
llmcapa tokens gpt-4o "Hello, world!"
llmcapa tokens gpt-4o --messages '[{"role":"user","content":"Hi"}]'

# Load extra model data from a local JSON file on startup
llmcapa --extra my_models.json show gpt-4o

# Explicitly fetch and update the OpenRouter cache only
llmcapa update

# Development: refresh the OpenAI catalog from official documentation
python scripts/_update_all_providers.py --provider openai

# Fetch and register popular models from HuggingFace
llmcapa fetch-hf
llmcapa fetch-hf --limit 200

Notes

• Static Snapshot: Bundled capability data is a static snapshot. See docs/catalog_data_sources.md for details on each provider's data source and known SSR limitations (Azure AI Catalog). While we strive to keep it updated with the latest models (including GPT-5.5, Claude Fable, Gemini 3.5, DeepSeek V4, Sakana Fugu, etc.), providers change limits and pricing frequently. Use fetch_openrouter() or verify with official documentation when absolute accuracy is critical.
• HuggingFace Data Accuracy: The bundled huggingface.json includes 2,675 popular text-generation models with context windows estimated from model families. Models fetched via fetch_huggingface() at runtime have estimated defaults. For exact specifications, consult official model cards.

License

Apache License 2.0