ooai_llm.metadata¶

Unified LangChain + LiteLLM model information.

Purpose:

Combine LangChain model profile data with LiteLLM pricing metadata and optional message-derived estimates to expose one normalized object for capability checks, cost estimation, and post-call accounting.

Design:

LangChain profile is treated as the capability/limits source.
LiteLLM is treated as the pricing and provider-string normalization source.
LangChain usage_metadata is treated as the usage source of truth after invocation.
Optional message input is normalized lazily and used for best-effort token/context estimates when a LangChain model instance is available.

Examples

>>> identity = ResolvedModelIdentity.from_model("openai:gpt-5.4-mini")
>>> identity.litellm_model
'openai/gpt-5.4-mini'
>>> usage = UsageSnapshot(input_tokens=100, output_tokens=50)
>>> usage.resolved_total_tokens
150

Attributes¶

`DEFAULT_PROVIDER_PREFIXES`
`ResolvedModelMeta`
`normalize_model_name`
`build_model_profile`

Classes¶

`PriceEntry`	Normalized token pricing for a model.
`CapabilityProfile`	Normalized capability view derived from LangChain `profile`.
`UsageSnapshot`	Normalized usage metadata from LangChain.
`ResolvedModelIdentity`	Normalized model identity across LangChain and LiteLLM naming styles.
`ModelInfo`	Merged capability and pricing metadata for one model identity.
`CreatedLLMBundle`	Convenience bundle combining a model instance with resolved metadata.

Functions¶

`normalize_langchain_model_name`(→ tuple[str \| None, str])	Split a LangChain model spec into provider and model parts.
`build_capability_profile`(→ CapabilityProfile)	Build a normalized capability profile from LangChain `profile`.
`build_usage_snapshot`(→ UsageSnapshot)	Build a normalized usage snapshot from LangChain usage metadata.
`calculate_cost`(→ decimal.Decimal)	Calculate actual post-call cost from normalized usage.
`resolve_litellm_model_name`(→ str)	Return the LiteLLM-style model string for a model.
`resolve_model_meta`(→ ResolvedModelMeta)	Resolve merged LangChain capability and LiteLLM pricing metadata.
`get_model_info`(→ ModelInfo)	Return normalized model information.
`resolve_model_meta_from_langchain_model`(→ ModelInfo)	Resolve metadata for an existing LangChain model instance.
`resolve_litellm_price_entry`(→ PriceEntry)	Resolve pricing metadata for a model through native LiteLLM.

Module Contents¶

ooai_llm.metadata.DEFAULT_PROVIDER_PREFIXES: dict[str, str][source]¶

class ooai_llm.metadata.PriceEntry(/, **data: Any)[source]¶

Bases: pydantic.BaseModel

Normalized token pricing for a model.

Parameters:

input_cost_per_token – USD cost per input token.
output_cost_per_token – USD cost per output token.
max_tokens – Maximum supported total/context tokens if known.
billing_model_name – Model name used for billing or pricing lookup.
source – Where this pricing entry came from.
raw_info – Original LiteLLM pricing payload when available.

model_config[source]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

input_cost_per_token: decimal.Decimal = None[source]¶

output_cost_per_token: decimal.Decimal = None[source]¶

max_tokens: int | None = None[source]¶

billing_model_name: str | None = None[source]¶

source: str = 'unknown'[source]¶

raw_info: dict[str, Any] = None[source]¶

class ooai_llm.metadata.CapabilityProfile(/, **data: Any)[source]¶

Bases: pydantic.BaseModel

Normalized capability view derived from LangChain profile.

Parameters:

max_input_tokens – Maximum input/context size if known.
max_output_tokens – Maximum output size if known.
tool_calling – Whether tool calling is supported.
tool_choice – Whether tool choice is supported.
parallel_tool_calls – Whether parallel tool calls are supported.
structured_output – Whether native/provider structured output is supported.
reasoning_output – Whether reasoning output is supported.
field_sources – Per-field provenance, such as profile or heuristic.
notes – Optional explanatory notes for inferred capability values.
raw_profile – Original LangChain profile dictionary.

model_config[source]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

max_input_tokens: int | None = None[source]¶

max_output_tokens: int | None = None[source]¶

tool_calling: bool | None = None[source]¶

tool_choice: bool | None = None[source]¶

parallel_tool_calls: bool | None = None[source]¶

structured_output: bool | None = None[source]¶

reasoning_output: bool | None = None[source]¶

field_sources: dict[str, str] = None[source]¶

notes: list[str] = None[source]¶

raw_profile: dict[str, Any] = None[source]¶

class ooai_llm.metadata.UsageSnapshot(/, **data: Any)[source]¶

Bases: pydantic.BaseModel

Normalized usage metadata from LangChain.

Parameters:

input_tokens – Input token count.
output_tokens – Output token count.
total_tokens – Total token count if already provided.
raw_usage – Original usage metadata dictionary.

model_config[source]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

input_tokens: int = 0[source]¶

output_tokens: int = 0[source]¶

total_tokens: int | None = None[source]¶

raw_usage: dict[str, Any] = None[source]¶

property resolved_total_tokens: int[source]¶: Return total tokens, inferring when absent.

class ooai_llm.metadata.ResolvedModelIdentity(/, **data: Any)[source]¶

Bases: pydantic.BaseModel

Normalized model identity across LangChain and LiteLLM naming styles.

model_config[source]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

provider: ooai_llm.providers.Provider | None = None[source]¶

model_name: str[source]¶

langchain_model: str[source]¶

litellm_model: str[source]¶

classmethod from_model(model: str | ooai_llm.types.ModelString, *, provider: ooai_llm.providers.Provider | str | None = None, settings: ooai_llm.settings.AppSettings | None = None) → ResolvedModelIdentity[source]¶: Build a resolved model identity from a model string.

class ooai_llm.metadata.ModelInfo(/, **data: Any)[source]¶

Bases: pydantic.BaseModel

Merged capability and pricing metadata for one model identity.

model_config[source]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

identity: ResolvedModelIdentity[source]¶

capabilities: CapabilityProfile[source]¶

pricing: PriceEntry[source]¶

message_estimate: ooai_llm.messages.MessageEstimate | None = None[source]¶

property provider: ooai_llm.providers.Provider | None[source]¶: Return the canonical provider when known.

property model_name: str[source]¶: Return the bare model name.

property billing_model_name: str[source]¶: Return the model name used for pricing lookup.

property max_input_tokens: int | None[source]¶: Prefer LangChain profile, then pricing metadata.

ooai_llm.metadata.ResolvedModelMeta[source]¶

class ooai_llm.metadata.CreatedLLMBundle[source]¶

Convenience bundle combining a model instance with resolved metadata.

model: ooai_llm.types.ModelString[source]¶

llm: Any[source]¶

metadata: ModelInfo[source]¶

reasoning: ooai_llm.reasoning.ReasoningResolution | None = None[source]¶

ooai_llm.metadata.normalize_langchain_model_name(raw_model: str | ooai_llm.types.ModelString) → tuple[str | None, str][source]¶: Split a LangChain model spec into provider and model parts.

ooai_llm.metadata.normalize_model_name[source]¶

ooai_llm.metadata.build_capability_profile(profile: collections.abc.Mapping[str, Any] | None, *, llm: Any | None = None, provider: ooai_llm.providers.Provider | str | None = None) → CapabilityProfile[source]¶: Build a normalized capability profile from LangChain profile.

ooai_llm.metadata.build_model_profile[source]¶

ooai_llm.metadata.build_usage_snapshot(usage_metadata: collections.abc.Mapping[str, Any] | None) → UsageSnapshot[source]¶: Build a normalized usage snapshot from LangChain usage metadata.

ooai_llm.metadata.calculate_cost(meta: ModelInfo, usage: UsageSnapshot) → decimal.Decimal[source]¶: Calculate actual post-call cost from normalized usage.

ooai_llm.metadata.resolve_litellm_model_name(model: str | ooai_llm.types.ModelString, *, settings: ooai_llm.settings.AppSettings | None = None, provider: ooai_llm.providers.Provider | str | None = None) → str[source]¶: Return the LiteLLM-style model string for a model.

ooai_llm.metadata.resolve_model_meta(model: str | ooai_llm.types.ModelString, *, settings: ooai_llm.settings.AppSettings | None = None, provider: ooai_llm.providers.Provider | str | None = None, profile: collections.abc.Mapping[str, Any] | None = None, billing_model_name: str | None = None, llm: Any | None = None, messages: ooai_llm.messages.MessagesLike | None = None, tools: collections.abc.Sequence[Any] | None = None) → ResolvedModelMeta[source]¶: Resolve merged LangChain capability and LiteLLM pricing metadata.

Return normalized model information.

Parameters:

model – Explicit model string.
llm – Existing LangChain model instance.
profile – Optional explicit profile mapping.
settings – Optional application settings.
provider – Optional provider override.
billing_model_name – Optional explicit LiteLLM billing model.
messages – Optional message input for best-effort token estimation.
tools – Optional tool schema list used in token estimation.

Returns:

Normalized model information.

Raises:

ValueError – If no model name can be determined.

ooai_llm.metadata.resolve_model_meta_from_langchain_model(llm: Any, *, model: str | ooai_llm.types.ModelString | None = None, settings: ooai_llm.settings.AppSettings | None = None, provider: ooai_llm.providers.Provider | str | None = None, billing_model_name: str | None = None, messages: ooai_llm.messages.MessagesLike | None = None, tools: collections.abc.Sequence[Any] | None = None) → ModelInfo[source]¶

Resolve metadata for an existing LangChain model instance.

Deprecated:: Use get_model_info() for new code.

ooai_llm.metadata.resolve_litellm_price_entry(identity: ResolvedModelIdentity, *, settings: ooai_llm.settings.AppSettings, billing_model_name: str | None = None) → PriceEntry[source]¶: Resolve pricing metadata for a model through native LiteLLM.