@insightfactory.ai/insightfactory-databricks-langgraph-tracer 1.0.0-dev.0

package/CHANGELOG.md

@@ -0,0 +1,176 @@
+# Changelog
+
+All notable changes to the TypeScript package
+(`@insightfactory.ai/insightfactory-databricks-langgraph-tracer`) are documented here. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+See [`../python/CHANGELOG.md`](../python/CHANGELOG.md) for changes to the
+separately versioned Python package.
+
+<!--
+Releasing: add changes under [Unreleased] as you go. To cut a release, move those
+items into a new `## [x.y.z] - YYYY-MM-DD` section, bump `version` in package.json,
+and add the version's link reference at the bottom. CI requires a matching
+`## [x.y.z]` section whenever package.json is version-bumped on a PR to main.
+Pushing the resulting `typescript-vx.y.z` tag from main publishes the stable npm
+package and opens its GitHub Release; pushes to develop publish a `dev`
+prerelease from this section.
+-->
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-02
+### Changed
+- Renamed the npm package from `@insightfactory-ai/databricks-langgraph-tracer` to
+  `@insightfactory.ai/insightfactory-databricks-langgraph-tracer`, matching the Python
+  distribution name. Update the import specifier when upgrading.
+- Published the stable package on public npm.
+- License and third-party notices now ship inside the tarball (`LICENSE`,
+  `THIRD_PARTY_NOTICES`).
+- `@langchain/core` and `@mlflow/core` became peer dependencies instead of
+  direct dependencies, so consumers control their own versions.
+- Removed internal client-project and issue-tracker references from shipped
+  comments and docs.
+
+### Removed
+- The GitHub Packages deprecation warning added in 0.6.2. The stable public
+  package does not warn on import.
+- `@langchain/langgraph` and the unused `zod` dependency, dropped from the
+  published dependency set: neither is imported by `src/`, so they no longer
+  ship as a peer or direct dependency (`@langchain/langgraph` remains a
+  devDependency for tests).
+
+## [0.6.2] - 2026-09-02
+### Deprecated
+- The GitHub Packages `@insightfactory-ai/databricks-langgraph-tracer` build is deprecated and
+  will no longer receive updates. Importing it now emits a `console.warn` directing consumers
+  to install `@insightfactory.ai/insightfactory-databricks-langgraph-tracer` from public npm instead.
+
+## [0.6.1] - 2026-07-29
+### Changed
+- Refreshed the vendored LiteLLM pricing catalog (2,719 → 2,984 entries), adding cost
+  coverage for the latest Foundry / Azure OpenAI models — notably the **GPT-5.6 series**
+  (`gpt-5.6`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, plus their `azure/us/` and
+  `azure/eu/` regional variants). Deployments named after these models now resolve to a
+  pricing key and are costed, rather than being tagged `cost.unknown_model`. The manual
+  `azure_ai/deepseek-v4-flash` / `azure_ai/deepseek-v4-pro` overrides survive the refresh
+  unchanged.
+- The refresh is not purely additive: upstream also revised rates for 21 non-Azure
+  entries (e.g. `sambanova/gpt-oss-120b`, `mistral/mistral-medium-latest`) and dropped
+  two `fireworks_ai/...whisper-v3*` keys. **No `azure/` or `azure_ai/` rate changed**, and
+  `resolvePricingKey` only probes those two prefixes, so default-path costs are
+  unaffected; consumers passing an explicit pricing key may see reported costs move.
+
+### Known limitations
+- Long-context tiering is still not applied: `calculateLlmCost` reads only the flat
+  per-token rates, never `input_cost_per_token_above_272k_tokens` or the `_priority`
+  rates. Pre-existing and affecting all of gpt-5.x, but easier to reach now that the
+  GPT-5.6 entries carry 1,050,000-token windows — a 400k-input call under-reports by
+  roughly half.
+
+## [0.6.0] - 2026-06-25
+### Added
+- `maxStringChars` option on `DatabricksLangGraphTracer` and
+  `initDatabricksTracing(...)` (env fallback `DATABRICKS_TRACING_MAX_STRING_CHARS`).
+  Opt-in (default off): when set, any plain-text string leaf longer than the
+  threshold in a span's inputs **or** outputs is replaced with a compact
+  `{ _truncated: true, chars: N, bytes: M, preview: "…" }` placeholder, so large
+  text (not just multimodal bytes) cannot push a Unity Catalog trace past the SQL
+  inline read limit (issue #23). It caps string values only — never keys or
+  structural fields — and is a per-leaf mitigation, not a hard per-trace budget, so
+  pair it with consumer-side payload reduction for the heaviest spans. A **distinct**
+  knob from the removed multimodal `maxContentPartBytes`: that gated inline binary
+  payloads; this caps arbitrary text.
+
+### Changed
+- The text cap now also applies to span **outputs**, not only inputs — the spans that
+  breach the inline read limit in the reported case (`final_output` /
+  `aggregate_results`) are output-side. Multimodal payload externalization stays
+  **input-only**: outputs are arbitrary chain / tool JSON, so running the
+  `data`/`base64` probe on them would mis-strip legitimate non-binary output. Runs on
+  a copy; the live values are untouched.
+
+## [0.5.0] - 2026-06-24
+### Added
+- `contentRefResolver` option on `DatabricksLangGraphTracer` and
+  `initDatabricksTracing(...)`. It is called once per multimodal content
+  part (image / PDF / file) with the part and a `ContentPartContext` (part
+  index/page, inline byte length, and a shallow copy of the run metadata), and
+  returns the reference object to store in the trace — e.g. a Unity Catalog volume
+  path — or `undefined` to fall back to the placeholder (issue #21).
+
+### Changed
+- Inline base64 payloads of multimodal parts are now **never** stored in the trace:
+  they are always stripped before recording and replaced with a lightweight
+  reference (a `contentRefResolver` result, otherwise a
+  `{ type: ..., _omitted: true, bytes: N }` placeholder), keeping Unity Catalog
+  trace reads under the SQL inline limit. Remote `http(s)://` image URLs are kept
+  verbatim. The transform runs on a copy, so the cache-stable message is untouched.
+
+### Removed
+- The per-content-part byte cap, including the
+  `DATABRICKS_TRACING_MAX_CONTENT_PART_BYTES` env var and the
+  `maxContentPartBytes` option. Inline payloads are now always externalized, so the
+  cap is obsolete.
+
+### Security
+- A resolver result that would re-introduce an inline payload — a `data:` URI, a
+  recognized base64 content part, or the part's raw base64 echoed back — is rejected
+  and the placeholder is used instead, guaranteeing no inline image bytes are
+  persisted. `ctx.metadata` is a shallow copy, so a resolver cannot corrupt run
+  state.
+
+## [0.4.0] - 2026-06-22
+### Added
+- Capture multimodal chat-model inputs (image / PDF / file content blocks) on LLM
+  spans.
+
+### Fixed
+- Keep multimodal content inline when exporting to Unity Catalog table-backed
+  experiments, instead of dropping it to an attachment reference.
+
+## [0.3.0] - 2026-06-17
+### Added
+- Trace-level per-model cost and token rollup, written to the `cost.by_model` tag
+  on the live trace before the root span ends. Unpriceable-but-resolved models
+  still contribute their token split (zero cost) so the totals stay complete.
+
+## [0.2.2] - 2026-06-09
+### Changed
+- Emit OpenInference-style `llm.*` span keys so the Databricks dashboard cost
+  charts read token usage and cost correctly.
+
+## [0.2.1] - 2026-06-04
+### Fixed
+- Chunk the Unity Catalog OTLP span export so payloads stay under the 10 MiB
+  ingest cap.
+
+## [0.2.0] - 2026-06-04
+### Added
+- Export spans to Unity Catalog table-backed experiments.
+
+## [0.1.0] - 2026-06-01
+### Added
+- Initial release: TypeScript port of the shared LangGraph → Databricks MLflow
+  tracer, with a cross-language parity suite asserting the TypeScript generated
+  keys equal the shared schema and the committed Python key set. Per-model pricing
+  comes from a vendored LiteLLM catalog with overrides and a refresh script.
+
+<!-- Historical links (0.1.0-0.4.0) use commit SHAs: those release tags were
+reserved by the repo's immutable-releases policy and cannot be created. Restore
+typescript-vX.Y.Z tag links if the names are ever reclaimed. 0.5.0's tag is
+created out-of-band (its bump predates the release workflow); 0.5.1+ tags are
+minted by release.yml on push to main. -->
+[Unreleased]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/typescript-v1.0.0...HEAD
+[1.0.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/typescript-v0.6.2...typescript-v1.0.0
+[0.6.2]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/typescript-v0.6.1...typescript-v0.6.2
+[0.6.1]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/typescript-v0.6.0...typescript-v0.6.1
+[0.6.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/typescript-v0.5.0...typescript-v0.6.0
+[0.5.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/99462dbc95c43f20085cae0bfd7a2dc0aab319b1...typescript-v0.5.0
+[0.4.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/951a9299c4beffcdd23fc7442bd79b49e2d9b52f...99462dbc95c43f20085cae0bfd7a2dc0aab319b1
+[0.3.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/1e4130acb98eb947f65302e060d6a017da0f2feb...951a9299c4beffcdd23fc7442bd79b49e2d9b52f
+[0.2.2]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/1a868d88a6227a0528e5725c49b63848f0e03aa9...1e4130acb98eb947f65302e060d6a017da0f2feb
+[0.2.1]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/03e34a320a8e90e046d574dab0e58cdfe58ab738...1a868d88a6227a0528e5725c49b63848f0e03aa9
+[0.2.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/83c62e28dbd04ef8e987689983e1e5a53e9d204f...03e34a320a8e90e046d574dab0e58cdfe58ab738
+[0.1.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/commit/83c62e28dbd04ef8e987689983e1e5a53e9d204f

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2026 insightfactory.ai. All rights reserved.
+
+This software is proprietary. No permission is granted to use, copy, modify,
+distribute, sublicense, or sell it except under a separate written agreement
+with insightfactory.ai.

package/README.md

@@ -0,0 +1,160 @@
+# @insightfactory.ai/insightfactory-databricks-langgraph-tracer
+
+LangGraph tracer for Databricks MLflow (TypeScript). It uses a custom `@mlflow/core`
+`BaseTracer` to write trace fields, token usage, and a cost rollup on the live trace before
+the root span ends.
+
+## Install
+
+Published on public npm:
+
+```bash
+yarn add @insightfactory.ai/insightfactory-databricks-langgraph-tracer
+# or: npm install @insightfactory.ai/insightfactory-databricks-langgraph-tracer
+```
+
+ESM-only. Install the runtime peer dependencies alongside it: `@langchain/core`,
+`@mlflow/core`.
+
+## Quickstart
+
+```ts
+import {
+  initDatabricksTracing,
+  getTracingCallbacks,
+} from "@insightfactory.ai/insightfactory-databricks-langgraph-tracer";
+
+// 1. Bootstrap once at startup (reads env-first; options override).
+initDatabricksTracing({ experimentId: "<mlflow-experiment-id>", source: "my-agent" });
+
+// 2. Attach the callbacks to your LangGraph / LangChain run.
+await graph.invoke(state, { callbacks: getTracingCallbacks() });
+```
+
+## Configuration
+
+Env-first; `InitOptions` override the matching env var.
+
+| Setting | Env var | Notes |
+|---------|---------|-------|
+| Tracking URI | `MLFLOW_TRACKING_URI` | `databricks` or `databricks://<profile>` (required) |
+| Experiment | `MLFLOW_EXPERIMENT_ID` | by **id** only (required) |
+| Source tag | — | `source` option, default `langgraph` |
+| Multimodal refs | — | inline image/PDF/file bytes are externalized to a reference; `contentRefResolver` chooses it — see below |
+| Text cap | `DATABRICKS_TRACING_MAX_STRING_CHARS` | opt-in; `maxStringChars` truncates over-long plain-text span content — see below |
+| Disable | `TESTING` / `BUILDING` = `true`, or `enabled: false` | no-op — the only non-throwing path |
+
+Missing required config **throws** `DatabricksTracingConfigurationError` (fail-fast) — disable
+explicitly for local/dev runs. `initDatabricksTracing` is idempotent (repeat calls return the
+same configuration).
+
+### Multimodal inputs (image / PDF / file)
+
+Chat-model spans record their inputs as **structured messages**, preserving the
+multimodal content parts a graph sends to the model — OpenAI / LangChain
+`image_url`, OpenAI `file`, and Anthropic `image` / `document`.
+
+The inline base64 of each such part is **never stored** in the trace: it is removed
+before recording and replaced with a lightweight reference, so the Unity Catalog
+trace tables stay readable (multi-MB data URIs previously pushed large invoice
+traces past the SQL inline read limit). A remote `http(s)://` image URL
+is already a small reference, so this step keeps it verbatim (but see the text cap
+below — if enabled, it still truncates *any* string over its threshold, URLs
+included). The transform runs on a copy of the inputs, so the live message sent to
+the model is untouched and prompt caching is unaffected.
+
+By default a part becomes a `{ type: ..., _omitted: true, bytes: N }` placeholder.
+To store a meaningful reference instead — e.g. the Unity Catalog volume path the
+image was loaded from, so it can be re-fetched at runtime — pass a
+`contentRefResolver`:
+
+```ts
+import {
+  type ContentPartContext,
+  initDatabricksTracing,
+} from "@insightfactory.ai/insightfactory-databricks-langgraph-tracer";
+
+const imageRef = (part: Record<string, unknown>, ctx: ContentPartContext) => {
+  // ctx.metadata is the run metadata — pass per-run data (e.g. a source volume
+  // path) via the invoke config's `metadata`, which propagates to the LLM run.
+  const path = ctx.metadata.encoded_images_path;
+  return typeof path === "string"
+    ? { type: part.type, ref: path, page: ctx.index }
+    : null; // fall back to the default placeholder
+};
+
+initDatabricksTracing({ experimentId: "...", contentRefResolver: imageRef });
+```
+
+The resolver is called once per multimodal part with the part and a
+`ContentPartContext` — `index` (position within the message content array, i.e. the
+page number for a one-image-per-page invoice), `bytes` (the inline payload length),
+and the run `metadata`. Return an object to store as the reference, or
+`undefined` / `null` for the default placeholder. It is also accepted by
+`new DatabricksLangGraphTracer({ contentRefResolver })` for per-graph wiring.
+
+The library guarantees no inline image bytes are stored: if a resolver result
+re-introduces an inline payload (a `data:` URI, a recognized base64 content part, or
+the part's own payload echoed back under any key — anywhere in the returned object),
+it is rejected and the placeholder is used. Beyond that, keep the reference
+**compact** — a *fabricated* large string under a custom key is the consumer's
+responsibility (the library strips inline payloads but does not otherwise bound what
+a resolver returns).
+`ctx.metadata` is a shallow copy of the run metadata, so a resolver cannot corrupt run
+state by setting top-level keys (don't mutate its nested values, which are shared).
+
+### Capping large text
+
+Multimodal externalization handles inline *bytes*, but large **plain text** can also
+push a trace past the SQL inline read limit — e.g. a classification vocabulary or
+aggregated result set threaded through every fan-out span's inputs and outputs. Set
+`maxStringChars` (or `DATABRICKS_TRACING_MAX_STRING_CHARS`) to truncate it:
+
+```ts
+initDatabricksTracing({ experimentId: "...", maxStringChars: 50_000 });
+```
+
+When set, any string **value** longer than the threshold — in a span's inputs *or*
+outputs — is replaced with a compact placeholder:
+
+```json
+{ "_truncated": true, "chars": 812345, "bytes": 812345, "preview": "first 256 chars…" }
+```
+
+It is **opt-in / off by default** (generic truncation costs debuggability, so you
+choose the threshold). It caps string values only — never keys or structural fields —
+and runs on a copy, so the live messages are untouched. Also accepted by
+`new DatabricksLangGraphTracer({ maxStringChars })` for per-graph wiring.
+
+This is a **distinct** knob from the multimodal handling above: `contentRefResolver`
+chooses references for inline image/PDF/file bytes; `maxStringChars` caps arbitrary
+text (and never truncates a resolver's reference). Because it is generic, it also
+truncates any other over-threshold string — including a remote `http(s)://` image URL
+the multimodal step keeps verbatim — so set the threshold comfortably above your
+reference / URL lengths. Note it is a **per-leaf** mitigation, not a hard per-trace
+byte budget — enough sub-threshold leaves can still sum past the limit — so for the
+heaviest spans also reduce what you record (pass ids/references through node state
+rather than full payloads).
+
+The threshold counts **characters** (UTF-16 units here; the Python package counts
+code points, so the two can differ on non-BMP text), while the inline limit is in
+bytes — multibyte text can be up to ~4× larger in bytes than characters, so for
+CJK/emoji-heavy content size the cap below `limit / 4`. The placeholder's `bytes`
+field always reports the exact UTF-8 size of the original.
+
+## Development
+
+Built and tested with **Yarn 4**:
+
+```bash
+cd typescript
+yarn install
+yarn build              # tsc -> dist/ + copy vendored pricing data
+yarn test               # vitest (incl. cross-language schema parity)
+yarn keys:check         # fail if generated-keys.ts drifts from the schema
+yarn pricing:update     # refresh the vendored LiteLLM pricing catalog
+```
+
+## Changelog
+
+See [`CHANGELOG.md`](CHANGELOG.md).

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,26 @@
+LiteLLM model pricing data
+==========================
+
+This package includes model pricing data derived from LiteLLM.
+
+MIT License
+
+Copyright (c) 2023 Berri AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cost.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Normalized token usage extracted from an LLM run end payload.
+ *
+ * `cached_tokens` (cache-read) and `cache_creation_tokens` (Anthropic
+ * cache-write) are both **subsets** of `input_tokens` after LangChain
+ * normalization — see `langchain-anthropic` `_create_usage_metadata`, which adds
+ * cache tokens onto Anthropic's cache-excluding base count so the final
+ * `input_tokens` is the true total (matching OpenAI's convention).
+ */
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    cached_tokens: number;
+    cache_creation_tokens: number;
+    reasoning_tokens: number;
+}
+export interface LLMCost {
+    input_cost: number;
+    output_cost: number;
+    total_cost: number;
+    cached_input_cost: number;
+    cache_creation_cost: number;
+}
+/** The reserved 3-key `mlflow.llm.cost` / `mlflow.trace.cost` payload. */
+export interface ReservedCostPayload {
+    input_cost: number;
+    output_cost: number;
+    total_cost: number;
+}
+/**
+ * The reserved 3-key cost payload (MLflow `CostKey`). The cache-read /
+ * cache-creation cost split is written separately to the non-reserved
+ * `gen_ai.usage.input_tokens.cached_cost` / `.cache_creation_cost` span
+ * attributes — both `total_cost` and those line-items already account for the
+ * cached discount and cache-creation premium.
+ */
+export declare function spanCostPayload(cost: LLMCost): ReservedCostPayload;
+/** Cheap key-presence probe against the vendored LiteLLM catalog. */
+export declare function hasPricingEntry(key: string): boolean;
+/** Return the catalog entry's `litellm_provider` (`azure`/`azure_ai`). */
+export declare function getPricingProvider(pricingKey: string): string | undefined;
+/**
+ * Compute per-call LLM cost in USD from the vendored catalog.
+ *
+ * Returns `null` when the model is absent from the catalog or the entry lacks
+ * the per-token rates needed to price it (e.g. LiteLLM's `sample_spec` schema
+ * blob or flat-fee container entries). `null` lets callers distinguish
+ * unknown/unpriceable models from genuine zero-cost models.
+ *
+ * Cache-read and cache-creation tokens are both subsets of `input_tokens`; each
+ * is subtracted from the regular input pool and billed at its own catalog rate
+ * (`cache_read_input_token_cost` — a discount; and
+ * `cache_creation_input_token_cost` — Anthropic's premium), each falling back to
+ * the input rate when the catalog has none. OpenAI has no cache-creation charge
+ * and returns no cache-creation tokens, so its cache-creation cost is zero.
+ */
+export declare function calculateLLMCost(pricingKey: string, usage: TokenUsage): LLMCost | null;
+/**
+ * Resolve a model name to its LiteLLM catalog key.
+ *
+ * Precedence: explicit override → `azure/<name>` (Azure OpenAI) →
+ * `azure_ai/<name>` (Azure AI Foundry) → `undefined` (callers surface this via
+ * the `cost.unknown_model` trace tag).
+ */
+export declare function resolvePricingKey(modelName: string, explicit?: string): string | undefined;
+/**
+ * Qualify a deployment name to its catalog key.
+ *
+ * Already-qualified `azure/` / `azure_ai/` names pass through unchanged.
+ * Otherwise {@link resolvePricingKey} is tried, falling back to `azure/<name>`
+ * so unknown models still surface a stable identifier for the
+ * `cost.unknown_model` aggregation tag.
+ */
+export declare function qualifyDeploymentName(name: string): string;
+//# sourceMappingURL=cost.d.ts.map

package/dist/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAiCA;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,OAAO;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IAGnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,CAMlE;AAMD,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,IAAI,CAiCtF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK1F;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG1D"}

package/dist/cost.js

@@ -0,0 +1,124 @@
+/**
+ * Per-call LLM cost computation against the vendored LiteLLM pricing catalog.
+ *
+ * Aligned with the Python `cost.py` (the shared contract). The catalog stores
+ * **per-token** rates (`input_cost_per_token`), so the formula multiplies tokens
+ * by the rate directly (no `/1e6`).
+ *
+ * Reserved cost keys are 3-key by MLflow's `CostKey` schema (Databricks strips
+ * extras on ingestion): the span `mlflow.llm.cost` payload — and the trace-level
+ * `mlflow.trace.cost` rollup — are both exactly
+ * `{ input_cost, output_cost, total_cost }` via {@link spanCostPayload}. The
+ * cache-read / cache-creation cost split (`cached_input_cost` /
+ * `cache_creation_cost`) is persisted separately as **non-reserved span
+ * attributes** (`gen_ai.usage.input_tokens.cached_cost` / `.cache_creation_cost`
+ * — Option B), which survive Databricks normalization.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const PRICING_URL = new URL("./pricing/model-pricing.json", import.meta.url);
+const pricing = JSON.parse(readFileSync(fileURLToPath(PRICING_URL), "utf8"));
+/**
+ * The reserved 3-key cost payload (MLflow `CostKey`). The cache-read /
+ * cache-creation cost split is written separately to the non-reserved
+ * `gen_ai.usage.input_tokens.cached_cost` / `.cache_creation_cost` span
+ * attributes — both `total_cost` and those line-items already account for the
+ * cached discount and cache-creation premium.
+ */
+export function spanCostPayload(cost) {
+    return {
+        input_cost: cost.input_cost,
+        output_cost: cost.output_cost,
+        total_cost: cost.total_cost,
+    };
+}
+function isFiniteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+/** Cheap key-presence probe against the vendored LiteLLM catalog. */
+export function hasPricingEntry(key) {
+    return Object.hasOwn(pricing, key);
+}
+/** Return the catalog entry's `litellm_provider` (`azure`/`azure_ai`). */
+export function getPricingProvider(pricingKey) {
+    const entry = pricing[pricingKey];
+    return typeof entry?.litellm_provider === "string" ? entry.litellm_provider : undefined;
+}
+/**
+ * Compute per-call LLM cost in USD from the vendored catalog.
+ *
+ * Returns `null` when the model is absent from the catalog or the entry lacks
+ * the per-token rates needed to price it (e.g. LiteLLM's `sample_spec` schema
+ * blob or flat-fee container entries). `null` lets callers distinguish
+ * unknown/unpriceable models from genuine zero-cost models.
+ *
+ * Cache-read and cache-creation tokens are both subsets of `input_tokens`; each
+ * is subtracted from the regular input pool and billed at its own catalog rate
+ * (`cache_read_input_token_cost` — a discount; and
+ * `cache_creation_input_token_cost` — Anthropic's premium), each falling back to
+ * the input rate when the catalog has none. OpenAI has no cache-creation charge
+ * and returns no cache-creation tokens, so its cache-creation cost is zero.
+ */
+export function calculateLLMCost(pricingKey, usage) {
+    // `sample_spec` is LiteLLM's schema/example blob, not a real model.
+    if (pricingKey === "sample_spec")
+        return null;
+    const entry = pricing[pricingKey];
+    if (!entry)
+        return null;
+    const inputRate = entry.input_cost_per_token;
+    const outputRate = entry.output_cost_per_token;
+    if (!isFiniteNumber(inputRate) || !isFiniteNumber(outputRate))
+        return null;
+    const cachedRate = isFiniteNumber(entry.cache_read_input_token_cost)
+        ? entry.cache_read_input_token_cost
+        : inputRate;
+    const creationRate = isFiniteNumber(entry.cache_creation_input_token_cost)
+        ? entry.cache_creation_input_token_cost
+        : inputRate;
+    const cached = Math.max(0, usage.cached_tokens || 0);
+    const creation = Math.max(0, usage.cache_creation_tokens || 0);
+    // Both cache categories are subtracted from the input pool and billed apart.
+    const regular = Math.max(0, (usage.input_tokens || 0) - cached - creation);
+    const cachedInputCost = cached * cachedRate;
+    const cacheCreationCost = creation * creationRate;
+    const inputCost = regular * inputRate + cachedInputCost + cacheCreationCost;
+    const outputCost = (usage.output_tokens || 0) * outputRate;
+    return {
+        input_cost: inputCost,
+        output_cost: outputCost,
+        total_cost: inputCost + outputCost,
+        cached_input_cost: cachedInputCost,
+        cache_creation_cost: cacheCreationCost,
+    };
+}
+/**
+ * Resolve a model name to its LiteLLM catalog key.
+ *
+ * Precedence: explicit override → `azure/<name>` (Azure OpenAI) →
+ * `azure_ai/<name>` (Azure AI Foundry) → `undefined` (callers surface this via
+ * the `cost.unknown_model` trace tag).
+ */
+export function resolvePricingKey(modelName, explicit) {
+    if (explicit)
+        return explicit;
+    if (hasPricingEntry(`azure/${modelName}`))
+        return `azure/${modelName}`;
+    if (hasPricingEntry(`azure_ai/${modelName}`))
+        return `azure_ai/${modelName}`;
+    return undefined;
+}
+/**
+ * Qualify a deployment name to its catalog key.
+ *
+ * Already-qualified `azure/` / `azure_ai/` names pass through unchanged.
+ * Otherwise {@link resolvePricingKey} is tried, falling back to `azure/<name>`
+ * so unknown models still surface a stable identifier for the
+ * `cost.unknown_model` aggregation tag.
+ */
+export function qualifyDeploymentName(name) {
+    if (name.startsWith("azure/") || name.startsWith("azure_ai/"))
+        return name;
+    return resolvePricingKey(name) ?? `azure/${name}`;
+}
+//# sourceMappingURL=cost.js.map

package/dist/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"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"}