openlit 1.13.0 → 1.14.0

package/dist/guard/topic-restriction.d.ts

@@ -1,7 +1,22 @@
-import { BaseGuard } from './base';
-import { GuardConfig, GuardResult } from './types';
-export declare class TopicRestriction extends BaseGuard {
-    constructor(config?: GuardConfig);
-    protected getSystemPrompt(): string;
-    detect(text: string): Promise<GuardResult>;
+/**
+ * Topic restriction guard.
+ *
+ * Enforces allow/deny topic lists using a user-provided topic classifier.
+ *
+ * Must stay in sync with: sdk/python/src/openlit/guard/topic_restriction.py
+ */
+import { Guard, GuardPhase, GuardResult, GuardOptions } from './base';
+export interface TopicRestrictionOptions extends GuardOptions {
+    classifier: (text: string) => string;
+    allowed?: string[];
+    denied?: string[];
+}
+export declare class TopicRestriction extends Guard {
+    readonly name = "topic_restriction";
+    readonly phases: GuardPhase[];
+    private readonly _classifier;
+    private readonly _allowed;
+    private readonly _denied;
+    constructor(opts: TopicRestrictionOptions);
+    evaluate(text: string): GuardResult;
 }

package/dist/guard/topic-restriction.js

@@ -1,74 +1,53 @@
 "use strict";
+/**
+ * Topic restriction guard.
+ *
+ * Enforces allow/deny topic lists using a user-provided topic classifier.
+ *
+ * Must stay in sync with: sdk/python/src/openlit/guard/topic_restriction.py
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TopicRestriction = void 0;
 const base_1 = require("./base");
-const utils_1 = require("./utils");
-const utils_2 = require("../evals/utils");
-const llm_1 = require("../llm");
-class TopicRestriction extends base_1.BaseGuard {
-    constructor(config = {}) {
-        super(config);
-    }
-    getSystemPrompt() {
-        return [
-            'Output Requirement: JSON Format Only',
-            '',
-            'Your task is to carefully analyze the provided text and identify any instances of restricted topics, and categorize the classification when found. Apply strict criteria in your assessment.',
-            '',
-            'Restricted topics include information or requests that are not allowed or are outside the permitted scope for this system.',
-            '',
-            'Presented Text:',
-            '{{prompt}}',
-            '',
-            'Expected JSON Structure:',
-            '',
-            '{',
-            '    "score": "float",',
-            '    "verdict": "yes or no",',
-            '    "guard": "topic_restriction",',
-            '    "classification": "CATEGORY_OF_TOPIC_RESTRICTION",',
-            '    "explanation": "Very short one-sentence reason"',
-            '}',
-            '',
-            'Scoring System:',
-            '- The score ranges from 0 to 1. Scores should be 0 if the classification is "none". Any other classification must be accompanied by a valid category and a score reflecting the restriction.',
-            '',
-            'Important: Use only the categories below to classify restricted topics. If the text does not fit any listed category, classify it as "none" with a score of 0.',
-            '',
-            'Categories of Restricted Topics (use only these categories):',
-            '- politics: Requests or discussions about political figures, parties, or policies that are not allowed.',
-            '- violence: Requests or discussions involving physical harm, aggression, or violent acts.',
-            '- personal_information: Requests for or mentions of sensitive personal data (e.g., credit card, address, email, phone number).',
-            '- confidential: Requests for or mentions of confidential or proprietary information.',
-            '- illegal: Requests or discussions about illegal activities.',
-            '',
-            'Final Steps:',
-            '- If no restricted topics are detected, or if the topic does not fit into one of the above categories, the return must be: {"score": 0, "verdict": "no", "guard": "none", "classification": "none", "explanation": "none"}.',
-        ].join('\n');
+class TopicRestriction extends base_1.Guard {
+    constructor(opts) {
+        super({ action: opts.action ?? 'deny', maxScanLength: opts.maxScanLength });
+        this.name = 'topic_restriction';
+        this.phases = [base_1.GuardPhase.PREFLIGHT];
+        if (typeof opts.classifier !== 'function') {
+            throw new base_1.GuardConfigError("TopicRestriction requires a callable 'classifier'");
+        }
+        if (opts.allowed && opts.denied) {
+            throw new base_1.GuardConfigError("Provide either 'allowed' or 'denied', not both");
+        }
+        if (!opts.allowed && !opts.denied) {
+            throw new base_1.GuardConfigError("Provide either 'allowed' or 'denied' topic list");
+        }
+        this._classifier = opts.classifier;
+        this._allowed = opts.allowed ? new Set(opts.allowed.map((t) => t.toLowerCase())) : null;
+        this._denied = opts.denied ? new Set(opts.denied.map((t) => t.toLowerCase())) : null;
     }
-    async detect(text) {
-        const customRuleResult = (0, utils_1.customRuleDetection)(text, this.customRules);
-        let llmResult = {
-            score: 0,
-            verdict: 'no',
-            guard: 'none',
-            classification: 'none',
-            explanation: 'none'
-        };
-        if (this.provider) {
-            // Use correct template variable for prompt and satisfy EvalsInput type
-            const prompt = (0, utils_2.formatPrompt)(this.getSystemPrompt(), { prompt: text, text });
-            const response = await this.llmResponse(prompt);
-            llmResult = (0, utils_1.toGuardResult)((0, llm_1.parseLlmResponse)(response), 'topic_restriction');
+    evaluate(text) {
+        const topic = this._classifier(text).toLowerCase().trim();
+        if (this._allowed !== null && !this._allowed.has(topic)) {
+            return (0, base_1.makeGuardResult)({
+                action: this._action,
+                score: 1.0,
+                guardName: this.name,
+                classification: topic,
+                explanation: `Topic '${topic}' is not in the allowed list`,
+            });
         }
-        let result = customRuleResult.score >= llmResult.score ? customRuleResult : llmResult;
-        result = (0, utils_1.applyThresholdScore)(result, this.thresholdScore);
-        // Metrics collection if enabled
-        if (this.collectMetrics) {
-            const validator = this.provider || 'custom';
-            (0, utils_1.guardMetrics)().add(1, (0, utils_1.guardMetricAttributes)(result.verdict, result.score, validator, result.classification, result.explanation));
+        if (this._denied !== null && this._denied.has(topic)) {
+            return (0, base_1.makeGuardResult)({
+                action: this._action,
+                score: 1.0,
+                guardName: this.name,
+                classification: topic,
+                explanation: `Topic '${topic}' is in the denied list`,
+            });
         }
-        return result;
+        return (0, base_1.makeGuardResult)({ guardName: this.name, classification: topic });
     }
 }
 exports.TopicRestriction = TopicRestriction;

package/dist/guard/topic-restriction.js.map

@@ -1 +1 @@
-{"version":3,"file":"topic-restriction.js","sourceRoot":"","sources":["../../src/guard/topic-restriction.ts"],"names":[],"mappings":";;;AAAA,iCAAmC;AAEnC,mCAAuH;AACvH,0CAA8C;AAC9C,gCAA0C;AAE1C,MAAa,gBAAiB,SAAQ,gBAAS;IAC7C,YAAY,SAAsB,EAAE;QAClC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChB,CAAC;IAES,eAAe;QACvB,OAAO;YACL,sCAAsC;YACtC,EAAE;YACF,8LAA8L;YAC9L,EAAE;YACF,4HAA4H;YAC5H,EAAE;YACF,iBAAiB;YACjB,YAAY;YACZ,EAAE;YACF,0BAA0B;YAC1B,EAAE;YACF,GAAG;YACH,uBAAuB;YACvB,6BAA6B;YAC7B,mCAAmC;YACnC,wDAAwD;YACxD,qDAAqD;YACrD,GAAG;YACH,EAAE;YACF,iBAAiB;YACjB,8LAA8L;YAC9L,EAAE;YACF,gKAAgK;YAChK,EAAE;YACF,8DAA8D;YAC9D,yGAAyG;YACzG,2FAA2F;YAC3F,gIAAgI;YAChI,sFAAsF;YACtF,8DAA8D;YAC9D,EAAE;YACF,cAAc;YACd,6NAA6N;SAC9N,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,MAAM,gBAAgB,GAAG,IAAA,2BAAmB,EAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACrE,IAAI,SAAS,GAAgB;YAC3B,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,MAAM;YACtB,WAAW,EAAE,MAAM;SACpB,CAAC;QACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,uEAAuE;YACvE,MAAM,MAAM,GAAG,IAAA,oBAAY,EAAC,IAAI,CAAC,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YAChD,SAAS,GAAG,IAAA,qBAAa,EAAC,IAAA,sBAAgB,EAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,MAAM,GAAG,gBAAgB,CAAC,KAAK,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC;QACtF,MAAM,GAAG,IAAA,2BAAmB,EAAC,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAE1D,gCAAgC;QAChC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC;YAC5C,IAAA,oBAAY,GAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAA,6BAAqB,EAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;QACnI,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AApED,4CAoEC"}
+{"version":3,"file":"topic-restriction.js","sourceRoot":"","sources":["../../src/guard/topic-restriction.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,iCAAyG;AAQzG,MAAa,gBAAiB,SAAQ,YAAK;IAQzC,YAAY,IAA6B;QACvC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,MAAM,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;QARrE,SAAI,GAAG,mBAAmB,CAAC;QAC3B,WAAM,GAAG,CAAC,iBAAU,CAAC,SAAS,CAAC,CAAC;QASvC,IAAI,OAAO,IAAI,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;YAC1C,MAAM,IAAI,uBAAgB,CAAC,mDAAmD,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,IAAI,uBAAgB,CAAC,gDAAgD,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,IAAI,uBAAgB,CAAC,iDAAiD,CAAC,CAAC;QAChF,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvF,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QAE1D,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACxD,OAAO,IAAA,sBAAe,EAAC;gBACrB,MAAM,EAAE,IAAI,CAAC,OAAO;gBACpB,KAAK,EAAE,GAAG;gBACV,SAAS,EAAE,IAAI,CAAC,IAAI;gBACpB,cAAc,EAAE,KAAK;gBACrB,WAAW,EAAE,UAAU,KAAK,8BAA8B;aAC3D,CAAC,CAAC;QACL,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACrD,OAAO,IAAA,sBAAe,EAAC;gBACrB,MAAM,EAAE,IAAI,CAAC,OAAO;gBACpB,KAAK,EAAE,GAAG;gBACV,SAAS,EAAE,IAAI,CAAC,IAAI;gBACpB,cAAc,EAAE,KAAK;gBACrB,WAAW,EAAE,UAAU,KAAK,yBAAyB;aACtD,CAAC,CAAC;QACL,CAAC;QAED,OAAO,IAAA,sBAAe,EAAC,EAAE,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1E,CAAC;CACF;AAnDD,4CAmDC"}

package/dist/helpers.d.ts

@@ -22,6 +22,52 @@ export declare function setFrameworkLlmActive(): void;
  * Mirrors Python's ContextVar.reset(token) in Strands processor.
  */
 export declare function resetFrameworkLlmActive(): void;
+/**
+ * Returns the user-supplied agent version label set via
+ * `OpenLit.setAgentVersion()` / `runWithAgentVersion()`, if any.
+ *
+ * Provider wrappers stamp this on `gen_ai.agent.version` so the server-side
+ * materializer can group traces by the user's preferred label in addition to
+ * the auto-computed `openlit.agent.version_hash` fingerprint.
+ */
+export declare function getCurrentAgentVersion(): string | undefined;
+/**
+ * Set the agent version label for the current execution context.
+ *
+ * IMPORTANT: this uses `AsyncLocalStorage.enterWith` which permanently
+ * mutates the current async resource. Sequential requests handled on the
+ * same Node worker (or reused thread/connection) will inherit the label
+ * until something overwrites or clears it. **Always pair with a matching
+ * `resetAgentVersion()` in a `finally` block**, or prefer
+ * `runWithAgentVersion(label, fn)` which guarantees scoped cleanup.
+ *
+ * @example
+ *   try {
+ *     setAgentVersion('hotfix-2026-05-12');
+ *     await runAgent();
+ *   } finally {
+ *     resetAgentVersion();
+ *   }
+ *
+ * @example
+ *   // Preferred — automatic scope cleanup, no leak risk:
+ *   await runWithAgentVersion('hotfix-2026-05-12', () => runAgent());
+ */
+export declare function setAgentVersion(version: string): void;
+/**
+ * Clear the agent version label set by `setAgentVersion()`. No-op if no
+ * label is active. See the `setAgentVersion` docstring for the leak
+ * scenario this guards against.
+ */
+export declare function resetAgentVersion(): void;
+/**
+ * Run `fn` with the given agent version label bound to the current async
+ * scope. Mirrors `openlit.agent_version_context()` in Python and is the
+ * recommended way to attach a label — the store is automatically restored
+ * when `fn` resolves so there is no risk of leaking the label across
+ * subsequent requests.
+ */
+export declare function runWithAgentVersion<T>(version: string, fn: () => T): T;
 /**
  * Returns true when a LangGraph wrapper is controlling execution.
  * LangChain's callback handler skips its own invoke_workflow span when true.
@@ -56,6 +102,11 @@ export declare function setFrameworkParentContext(ctx: Context): void;
  */
 export declare function clearFrameworkParentContext(): void;
 export declare function getServerAddressForProvider(provider: string): [string, number];
+/** LangChain/LangGraph message type → OTel GenAI role (mirrors Python LANGCHAIN_ROLE_MAPPING). */
+export declare const LANGCHAIN_ROLE_MAP: Record<string, string>;
+export declare const OTEL_ASSISTANT_ROLE: string;
+/** Map a raw LangChain message type/role to the OTel GenAI convention value. */
+export declare function mapLangChainRole(rawRole: string | undefined | null): string;
 /**
  * Apply global (from init) and context-scoped (from usingAttributes /
  * injectAdditionalAttributes) custom attributes to a span.
@@ -89,16 +140,96 @@ export default class OpenLitHelper {
     static readonly PROMPT_TOKEN_FACTOR = 1000;
     static openaiTokens(text: string, model: string): number;
     static generalTokens(text: string): number;
-    static getChatModelCost(model: string, pricingInfo: any, promptTokens: number, completionTokens: number): number;
+    /**
+     * Compute chat completion cost, optionally accounting for prompt-cache tokens.
+     *
+     * When the model's pricing entry defines `cacheReadPrice` / `cacheCreationPrice`,
+     * the matching cache tokens are billed at those rates instead of the regular
+     * prompt price.
+     *
+     * Token accounting differs across providers:
+     *   - Anthropic's native API reports `promptTokens` exclusive of cache tokens,
+     *     so cache tokens are added on top (keep `promptTokensIncludeCache` false).
+     *   - OpenAI / LangChain report `promptTokens` inclusive of cache read tokens,
+     *     so pass `promptTokensIncludeCache: true` to subtract the re-priced cache
+     *     tokens from the prompt base and avoid billing them twice.
+     *
+     * Cache tokens are only re-priced (and, when inclusive, only subtracted) when a
+     * dedicated cache price exists, so the result is identical to the legacy
+     * behaviour for any model without cache pricing configured.
+     */
+    static getChatModelCost(model: string, pricingInfo: any, promptTokens: number, completionTokens: number, cacheReadTokens?: number, cacheCreationTokens?: number, promptTokensIncludeCache?: boolean): number;
     static getEmbedModelCost(model: string, pricingInfo: any, promptTokens: number): number;
     static getImageModelCost(model: string, pricingInfo: any, size: string, quality: number): number;
-    static getAudioModelCost(model: string, pricingInfo: any, prompt: string): number;
+    static getAudioModelCost(model: string, pricingInfo: any, prompt: string, duration?: number): number;
     static fetchPricingInfo(pricingJson: any): Promise<any>;
     /**
      * Build OTel-spec input messages JSON string from provider messages array.
      * Format: [{"role": "user", "parts": [{"type": "text", "content": "..."}]}]
      */
     static buildInputMessages(messages: any[], system?: string): string;
+    /**
+     * Extract system message(s) from a chat-completions messages array.
+     * Returns an OTel ``gen_ai.system_instructions`` payload
+     * (``[{"type": "text", "content": "..."}]``) JSON-encoded as a string,
+     * or ``undefined`` when no system message is present.
+     *
+     * Mirrors Python's ``build_system_instructions_from_messages``.
+     */
+    static buildSystemInstructionsFromMessages(messages: any[]): string | undefined;
+    /**
+     * Normalize a request ``tools`` array into the OTel
+     * ``gen_ai.tool.definitions`` schema and return it as a JSON string,
+     * or ``undefined`` when there is nothing usable.
+     *
+     * Accepts both the OpenAI-style schema
+     * (``{"type": "function", "function": {...}}``) and the flat schema
+     * (``{"name": ..., "description": ..., "parameters": ...}``), and
+     * Anthropic's ``input_schema`` synonym for ``parameters``.
+     *
+     * Mirrors Python's ``build_tool_definitions``.
+     */
+    static buildToolDefinitions(tools: any): string | undefined;
+    /**
+     * Compute the canonical agent-version fingerprint.
+     *
+     * Mirrors `fingerprint()` in
+     * `src/client/src/lib/platform/agents/snapshot.ts` so that the SDK stamps
+     * `openlit.agent.version_hash` with the same value the server-side
+     * materializer derives from `otel_traces`. The hash covers the parts that
+     * meaningfully change agent behavior: system prompt, tool set (name +
+     * schema), primary model, and sampling config.
+     *
+     * Accepts the same shapes used by the SDK chat finalizers:
+     *  - `systemInstructions`: the JSON string emitted on
+     *    `gen_ai.system_instructions`, the original list of `{type,content}`
+     *    parts, or a plain string.
+     *  - `toolDefinitions`: the JSON string emitted on
+     *    `gen_ai.tool.definitions`, or the original list of
+     *    `{type, name, description, parameters}` items.
+     */
+    static computeAgentVersionHash(args: {
+        systemInstructions?: string | unknown[] | null;
+        toolDefinitions?: string | unknown[] | null;
+        primaryModel?: string | null;
+        runtimeConfig?: {
+            temperature?: number | null;
+            top_p?: number | null;
+            max_tokens?: number | null;
+            provider?: string | null;
+        } | null;
+        providers?: string[] | null;
+    }): string;
+    private static readonly _VERSION_HASH_CACHE_MAX;
+    private static _versionHashCache;
+    /**
+     * Build a stable, cheap cache key for the version-hash memoization. Uses
+     * `JSON.stringify` of inputs (orders-of-magnitude cheaper than the full
+     * canonical pass we want to skip on a cache hit). Returns `null` if
+     * inputs can't be stringified (circular refs etc.) — the caller falls
+     * back to uncached computation.
+     */
+    private static _buildAgentVersionCacheKey;
     /**
      * Build OTel-spec output messages JSON string from provider response.
      * Format: [{"role": "assistant", "parts": [{"type": "text", "content": "..."}], "finish_reason": "stop"}]