shield360 1.0.0

package/dist/guard/sensitive-topic.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Sensitive topic detection guard.
+ *
+ * Uses keyword/regex dictionaries for fast-path detection of sensitive
+ * content categories. An optional user-provided classifier handles
+ * ambiguous cases.
+ *
+ * Patterns must stay in sync with: sdk/python/src/shield360/guard/sensitive_topic.py
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SensitiveTopic = void 0;
+const base_1 = require("./base");
+const DEFAULT_CATEGORIES = {
+    violence: [
+        /\b(?:kill|murder|assault|attack|weapon|bomb|shoot|stab|torture|terrorism|massacre|genocide)\b/i,
+    ],
+    politics: [
+        /\b(?:democrat|republican|election\s+fraud|political\s+party|vote\s+rigging|coup|insurrection)\b/i,
+    ],
+    substance_use: [
+        /\b(?:cocaine|heroin|methamphetamine|fentanyl|drug\s+(?:deal|traffick)|overdose|illegal\s+drugs)\b/i,
+    ],
+    mental_health: [
+        /\b(?:suicid(?:e|al)|self[- ]harm|eating\s+disorder|anorexia|bulimia)\b/i,
+    ],
+    discrimination: [
+        /\b(?:racial\s+slur|white\s+supremac|ethnic\s+cleansing|hate\s+(?:speech|crime))\b/i,
+    ],
+    adult_content: [
+        /\b(?:pornograph|explicit\s+sexual|nude\s+images|sex\s+trafficking)\b/i,
+    ],
+};
+class SensitiveTopic extends base_1.Guard {
+    constructor(opts = {}) {
+        super({ action: opts.action ?? 'warn', maxScanLength: opts.maxScanLength });
+        this.name = 'sensitive_topic';
+        this.phases = [base_1.GuardPhase.PREFLIGHT, base_1.GuardPhase.POSTFLIGHT];
+        this._classifier = opts.classifier;
+        const allowedCategories = opts.categories
+            ? new Set(opts.categories)
+            : null;
+        this._patterns = {};
+        for (const [cat, pats] of Object.entries(DEFAULT_CATEGORIES)) {
+            if (allowedCategories === null || allowedCategories.has(cat)) {
+                this._patterns[cat] = [...pats];
+            }
+        }
+        if (opts.customCategories) {
+            for (const [cat, rawPats] of Object.entries(opts.customCategories)) {
+                const compiled = rawPats.map((p) => new RegExp(p, 'i'));
+                if (!this._patterns[cat]) {
+                    this._patterns[cat] = [];
+                }
+                this._patterns[cat].push(...compiled);
+            }
+        }
+    }
+    evaluate(text) {
+        const detected = [];
+        for (const [cat, patterns] of Object.entries(this._patterns)) {
+            for (const pat of patterns) {
+                if (pat.test(text)) {
+                    detected.push(cat);
+                    break;
+                }
+            }
+        }
+        if (detected.length === 0 && this._classifier) {
+            const result = this._classifier(text);
+            if (result) {
+                detected.push(result);
+            }
+        }
+        if (detected.length > 0) {
+            const classification = [...detected].sort().join(', ');
+            return (0, base_1.makeGuardResult)({
+                action: this._action,
+                score: Math.round(Math.min(1.0, detected.length * 0.3 + 0.4) * 100) / 100,
+                guardName: this.name,
+                classification,
+                explanation: `Sensitive topic(s) detected: ${classification}`,
+            });
+        }
+        return (0, base_1.makeGuardResult)({ guardName: this.name });
+    }
+}
+exports.SensitiveTopic = SensitiveTopic;
+//# sourceMappingURL=sensitive-topic.js.map

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * Topic restriction guard.
+ *
+ * Enforces allow/deny topic lists using a user-provided topic classifier.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/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

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Topic restriction guard.
+ *
+ * Enforces allow/deny topic lists using a user-provided topic classifier.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/guard/topic_restriction.py
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopicRestriction = void 0;
+const base_1 = require("./base");
+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;
+    }
+    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`,
+            });
+        }
+        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 (0, base_1.makeGuardResult)({ guardName: this.name, classification: topic });
+    }
+}
+exports.TopicRestriction = TopicRestriction;
+//# sourceMappingURL=topic-restriction.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,246 @@
+import { Attributes, Context, Span } from '@opentelemetry/api';
+/**
+ * Returns true when a framework instrumentor (LangChain, LiteLLM, etc.)
+ * owns the current LLM span. Provider-level wrappers (OpenAI, Anthropic, …)
+ * must skip their own span creation when this returns true.
+ */
+export declare function isFrameworkLlmActive(): boolean;
+/**
+ * Run `fn` with the framework-LLM-active flag set. All provider wrappers
+ * invoked inside `fn` will see `isFrameworkLlmActive() === true`.
+ */
+export declare function runWithFrameworkLlm<T>(fn: () => T): T;
+/**
+ * Set framework-LLM-active flag in the current execution context.
+ * Used by SpanProcessor-based instrumentations (Strands) where
+ * the processor observes spans rather than controlling execution.
+ * Mirrors Python's ContextVar.set(True) in Strands processor.
+ */
+export declare function setFrameworkLlmActive(): void;
+/**
+ * Reset framework-LLM-active flag in the current execution context.
+ * Mirrors Python's ContextVar.reset(token) in Strands processor.
+ */
+export declare function resetFrameworkLlmActive(): void;
+/**
+ * Returns the user-supplied agent version label set via
+ * `Shield360.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 `shield360.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 `shield360.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.
+ */
+export declare function isLangGraphActive(): boolean;
+export declare function runWithLangGraph<T>(fn: () => T): T;
+/**
+ * Returns true when a create_agent span is already being handled
+ * (prevents duplicate spans between LangChain and LangGraph).
+ */
+export declare function isCreateAgentActive(): boolean;
+export declare function runWithCreateAgent<T>(fn: () => T): T;
+/**
+ * Propagate conversation ID from invoke_workflow to child node spans.
+ * Mirrors Python's set_langgraph_conversation_id / get_langgraph_conversation_id.
+ */
+export declare function getLangGraphConversationId(): string | undefined;
+export declare function runWithLangGraphConversationId<T>(conversationId: string, fn: () => T): T;
+/**
+ * Returns the OTel context set by a framework processor (OpenAI Agents, etc.)
+ * so that provider wrappers can create spans as children of framework spans.
+ * Mirrors Python's context_api.attach(set_span_in_context(span)).
+ */
+export declare function getFrameworkParentContext(): Context | undefined;
+/**
+ * Set the OTel parent context for provider span creation.
+ * Called by processor-based frameworks that cannot use context.with().
+ */
+export declare function setFrameworkParentContext(ctx: Context): void;
+/**
+ * Clear the framework parent context.
+ */
+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.
+ * Global attributes are applied first; context attributes override on conflict.
+ * Matches Python's _apply_custom_span_attributes().
+ */
+export declare function applyCustomSpanAttributes(span: Span): void;
+/**
+ * Get merged custom attributes (global + context) for use in events.
+ * Returns a flat object; context attributes override global on conflict.
+ */
+export declare function getMergedCustomAttributes(): Record<string, any>;
+/**
+ * Run a function with custom span attributes attached to all
+ * auto-instrumented spans created during its execution.
+ * Matches Python's shield360.inject_additional_attributes().
+ */
+export declare function injectAdditionalAttributes<T>(fn: () => T, attributes: Record<string, any>): T;
+/**
+ * Context wrapper that adds custom attributes to all auto-instrumented
+ * spans created within its callback scope.
+ * Matches Python's shield360.using_attributes() context manager.
+ *
+ * Usage:
+ *   await usingAttributes({"user.id": "u1", "team": "ml"}, async () => {
+ *     await client.chat.completions.create(...);
+ *   });
+ */
+export declare function usingAttributes<T>(attributes: Record<string, any>, fn: () => T): T;
+export default class Shield360Helper {
+    static readonly PROMPT_TOKEN_FACTOR = 1000;
+    static openaiTokens(text: string, model: string): number;
+    static generalTokens(text: string): 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, 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
+     * `shield360.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"}]
+     */
+    static buildOutputMessages(text: string, finishReason: string, toolCalls?: any[]): string;
+    /**
+     * Emit an inference event via the LoggerProvider, matching Python SDK's
+     * gen_ai.client.inference.operation.details event.
+     * Falls back to span.addEvent if LoggerProvider is not available.
+     */
+    static emitInferenceEvent(span: Span, attrs: Attributes): void;
+    static handleException(span: Span, error: Error): void;
+    static createStreamProxy(stream: any, generatorFuncResponse: any): Promise<any>;
+}