openaiusage

func AnnotateProviderContext ¶

func AnnotateProviderContext(ev *lipapi.Event, providerRequestID, serviceContext string)

AnnotateProviderContext attaches identifiers that were actually surfaced by the provider response. Empty values remain absent; no request identifier is synthesized from a local call ID.

func ChatUsageEvent ¶

func ChatUsageEvent(usage openai.CompletionUsage) lipapi.Event

func NativeUsageEvidence ¶

func NativeUsageEvidence(raw string) []sdkmetering.SafeEvidenceField

NativeUsageEvidence returns bounded safe lexemes for the same native fields retained as measures. Provider-family nested fields and selected aliases retain their exact allowlisted wire path; no synthetic decomposition path is substituted for the provider's field identity. A present-but-malformed provider-family nested field has no safe numeric lexeme to retain, but it still claims its canonical component so a later flat alias cannot silently stand in for it; its typed unavailable status is carried by the measure.

func NativeUsageInclusionSchema ¶

func NativeUsageInclusionSchema() metering.ComponentSchema

NativeUsageInclusionSchema returns the frozen OpenAI Chat/Responses provider-family inclusion schema.

OpenAI reports prompt_tokens / completion_tokens (and the Responses input_tokens / output_tokens) as totals that include their directional prompt_tokens_details / completion_tokens_details (input_tokens_details / output_tokens_details) children. The native token partition is the directional text/audio pair, plus an optional image member for the vision-capable wire family: text_tokens + audio_tokens (+ the optional image_tokens) account for the ordinary token total. This schema declares that explicit parent/child inclusion so the accounting rater can select one disjoint partition or reject a tariff that prices both sides, instead of additively double-charging the same work.

Chat prompt_tokens_details additionally reports image_tokens (image input tokens present in the prompt) as a disjoint member of the prompt partition: text_tokens + audio_tokens + image_tokens account for the ordinary prompt total. The image member is declared as an OPTIONAL partition child. When the provider reports it, text+audio+image is the complete partition and a tariff pricing all three rates completely; when the provider omits it (an audio-only prompt) text+audio is still the complete reported partition, because an omitted optional member is not a provider-attested zero. A tariff that prices the ordinary aggregate alongside its included native image tokens is still rejected as a typed overlap, and a present-but-unpriced image member still fails closed, so optionality never weakens the double-charge guard.

The native Chat/Responses output detail has no image token member, so the only supported source of a native directional output image token is the recognized compatible-provider flat alias family (output_image_tokens / image_output_tokens / completion_image_tokens), which the adapter maps onto the same canonical output image_token component. That flat measure is a disjoint member of the ordinary completion/output total, so it gets the symmetric OUTPUT optional partition edge. The edge is bounded by construction: it can only bind when the adapter actually emitted that native output image token, which only the recognized flat vocabulary produces; no output image field is fabricated from a nested completion detail, and no provider is asserted to emit one.

cached_tokens and reasoning_tokens are likewise included prompt/completion subsets, so they get bounded subset edges against the ordinary aggregate: Chat prompt_tokens_details.cached_tokens and Responses input_tokens_details.cached_tokens are cached tokens "present in the prompt" (a subset of prompt_tokens/input_tokens), and completion_tokens_details.reasoning_tokens / output_tokens_details.reasoning_tokens are "still counted in the total completion tokens for purposes of billing, output, and context window limits" (a subset of completion_tokens/output_tokens). Because the adapter emits those two quantities under metering.DefaultInclusionSchemaID via providerTokenMeasures, the edges are declared in that same schema identity. They are subset children, not partition members: cached/reasoning tokens are not the text/audio partition, so an aggregate-only tariff stays complete and a child-only tariff over one of them can never prove the parent's complete coverage.

cache_write_tokens is the same kind of included input subset. The official OpenAI Chat CompletionUsagePromptTokensDetails and Responses ResponseUsageInputTokensDetails both carry a standard cache_write_tokens member ("The unadjusted number of prompt tokens written to cache"), and the adapter's native usage mapping recognizes it as an input cache_write_input_token detail under the native detail schema. Its edge is therefore declared against the native child key. The non-standard x_lip_cache_write_tokens extension is only a compatible-provider fallback and is emitted under the default inclusion schema, so a second, symmetric subset edge is declared for that default identity. The two edges can never bind the same observation at once: the adapter suppresses the extension whenever the standard member is present. Like the cached/reasoning edges they are subsets, not partition members.

The schema is deliberately narrow:

• accepted_prediction_tokens and rejected_prediction_tokens are overlapping/orthogonal output subsets and are left undeclared. A tariff pricing an aggregate plus one of these undeclared subsets remains additively double-billable until that relationship is declared.
• Only the provider-family text/audio partition children, the optional native image token partition members (input and output), and the included cached / reasoning / cache-write subsets are declared. Publication is opt-in per tariff (BuildTariffSnapshotWithSchemas); it is never auto-bound to unrelated providers or legacy schema-free tariffs.
• The rater still fails closed when a required partition child is absent, null or incomplete, when a present optional member is incomplete or unrated, or when two parents ambiguously share a child, because the generic complete-partition proof requires every required child present and rateable, and every present optional member complete and rateable, in the same scope.

func NativeUsageInclusionSchemas ¶

func NativeUsageInclusionSchemas() []metering.ComponentSchema

NativeUsageInclusionSchemas returns a fresh frozen schema slice suitable for economics.BuildTariffSnapshotWithSchemas. Each call returns a deep copy so a caller cannot mutate the package's provider-family declaration.

func NativeUsageMeasures ¶

func NativeUsageMeasures(raw string) []sdkmetering.Measure

NativeUsageMeasures returns only provider-reported native units. A malformed, negative, fractional discrete or overflow flat compatible alias is omitted, preserving an unavailable quantity rather than coercing it to zero or text tokens. A present provider-family nested field is authoritative: when its lexeme is malformed it becomes an explicit unavailable measure instead of being silently dropped, and it claims its canonical component so a later compatible flat alias cannot stand in for the unusable provider value.

func NewProviderEvidenceStream ¶

func NewProviderEvidenceStream(events []lipapi.Event, mapping string) lipapi.ManagedEventStream

NewProviderEvidenceStream wraps a complete family response with the same host-only V2 observation seam used by streaming adapters. It is intended for non-streaming provider responses only; no money is rated or posted here.

func ProviderEvidenceDraft ¶

func ProviderEvidenceDraft(ev lipapi.Event, mapping, sourceKey string) coremetering.ProviderEvidenceDraft

ProviderEvidenceDraft maps OpenAI-family usage into the host-only V2 seam. The family parser is intentionally kept here: core sees only neutral measures and cannot infer provider fields or prices.

func ResponsesUsageEvent ¶

func ResponsesUsageEvent(u responses.ResponseUsage) lipapi.Event