@zespan/sdk 1.3.1 → 1.3.4

package/dist/index.d.mts

@@ -8,13 +8,30 @@ import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { Serialized } from '@langchain/core/load/serializable';
 import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 
-interface ZespanOptions {
+type PiiPreset = "gdpr" | "hipaa" | "ccpa" | "pci-dss" | "soc2" | "finance" | "education" | "transportation";
+type PiiCategory = "personal" | "financial" | "government_ids" | "healthcare" | "digital_identity";
+type PiiRedactionMode = "placeholder" | "mask-middle" | "mask-all";
+interface ZespanPiiConfig {
+    piiPreset?: PiiPreset;
+    piiCategories?: PiiCategory[];
+    piiIncludeNames?: boolean;
+    piiIncludeEmails?: boolean;
+    piiIncludePhones?: boolean;
+    piiIncludeAddresses?: boolean;
+    piiConfidenceThreshold?: number;
+    piiRedactionMode?: PiiRedactionMode;
+    piiWhitelist?: string[];
+    piiCustomPatterns?: RegExp[];
+}
+interface ZespanOptions extends ZespanPiiConfig {
     apiKey: string;
     endpoint?: string;
     baseURL?: string;
     environment?: string;
     storePrompts?: boolean;
     redactKeys?: string[];
+    /** Pattern-based PII detection via openredaction. OFF by default — must opt in. */
+    redactPii?: boolean;
     sampleRate?: number;
     debug?: boolean;
     batchSize?: number;
@@ -53,6 +70,11 @@ interface PromptOptions {
     version?: number;
     label?: string;
     cache?: boolean;
+    fallback?: {
+        type?: "text" | "chat";
+        prompt: any;
+        config?: any;
+    };
 }
 interface Prompt {
     id: string;
@@ -67,6 +89,11 @@ interface Prompt {
     createdAt: string;
     updatedAt: string;
     promptHash: string;
+    isFallback?: boolean;
+}
+interface ChatMessage {
+    role: string;
+    content: string;
 }
 declare class PromptClient {
     private client;
@@ -99,9 +126,12 @@ declare class PromptClient {
      */
     updateLabels(name: string, version: number, labels: string[]): Promise<Prompt>;
     /**
-     * Compile a prompt with variables
+     * Compile a prompt with `{{var}}` substitution and chat message placeholders.
+     * - text prompt -> substituted string.
+     * - chat prompt -> message array with placeholders spliced in order
+     *   (unfilled dropped) and vars substituted across all message contents.
      */
-    compile(prompt: Prompt, variables: Record<string, string>): string;
+    compile(prompt: Prompt, variables?: Record<string, string>, placeholders?: Record<string, ChatMessage[]>): string | ChatMessage[];
     /**
      * Clear cache for a specific prompt or all prompts
      */
@@ -110,6 +140,40 @@ declare class PromptClient {
     private invalidateCache;
 }
 
+interface DatasetItem {
+    id: string;
+    datasetId: string;
+    input: unknown;
+    expectedOutput?: unknown;
+    metadata?: Record<string, unknown>;
+}
+interface DatasetRun {
+    id: string;
+    datasetId: string;
+    name: string;
+    description: string | null;
+}
+declare class DatasetRunHandle {
+    private client;
+    private datasetId;
+    readonly run: DatasetRun;
+    constructor(client: ZespanClient, datasetId: string, run: DatasetRun);
+    /** Links a dataset item to this run via the trace your own code just produced. */
+    link(datasetItemId: string, traceId: string, observationId?: string): Promise<void>;
+}
+declare class DatasetsClient {
+    private client;
+    private datasetIdByName;
+    constructor(client: ZespanClient);
+    private resolveDatasetId;
+    /** Lists a dataset's items by dataset name. */
+    getItems(datasetName: string): Promise<DatasetItem[]>;
+    /** Creates or fetches a named run (idempotent — safe to call every time a job starts). */
+    createRun(datasetName: string, runName: string, opts?: {
+        description?: string;
+    }): Promise<DatasetRunHandle>;
+}
+
 /**
  * SDK ConfigClient — zero-infra runtime configuration client.
  *
@@ -246,10 +310,12 @@ declare class ZespanClient {
     readonly environment: string;
     readonly storePrompts: boolean;
     readonly redactKeys: string[];
+    readonly redactPii: boolean;
     readonly sampleRate: number;
     readonly debug: boolean;
     readonly enableOTel: boolean;
     readonly prompts: PromptClient;
+    readonly datasets: DatasetsClient;
     readonly configClient: ConfigClient | null;
     readonly projectId: string | undefined;
     private batch;
@@ -258,6 +324,9 @@ declare class ZespanClient {
     constructor(opts: ZespanOptions);
     enqueue(event: ZespanEvent): void;
     redactForStorage(value: unknown): string;
+    redactValueAsync(value: unknown): Promise<string>;
+    redactTextAsync(text: string): Promise<string>;
+    redactObjectAsync(obj: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
     private resolveGuardrailsUrl;
     checkGuardrails(input: GuardrailCheckInput): Promise<GuardrailCheckResponse>;
     flush(): Promise<void>;
@@ -452,6 +521,8 @@ interface AgentOptions {
     name: string;
     role?: string;
     framework?: string;
+    version?: string;
+    description?: string;
     tools?: ToolDefinition[];
     metadata?: Record<string, unknown>;
 }
@@ -558,6 +629,8 @@ declare const zespan: {
     createSpan: typeof createSpan;
     withSpan: typeof withSpan;
     PromptClient: typeof PromptClient;
+    DatasetsClient: typeof DatasetsClient;
+    DatasetRunHandle: typeof DatasetRunHandle;
     CallbackHandler: typeof ZespanCallbackHandler;
     ADKCallbackHandler: typeof ZespanADKCallbackHandler;
     autopatch: typeof autopatch;
@@ -568,4 +641,4 @@ declare const zespan: {
     ZespanLlamaIndexHandler: typeof ZespanLlamaIndexHandler;
 };
 
-export { type ADKAgentOptions, type ADKRunnerOptions, AgentContext, type AgentOptions, BaggageSpanProcessor, CREWAI_OTEL_ENV, GuardrailBlockedError, type GuardrailCheckInput, type GuardrailCheckResponse, type GuardrailResult, type InstrumentADKOptions, type OTelConfig, type Prompt, PromptClient, type PromptOptions, type ResolvedWrapperGuardrailsSettings, type WrapperGuardrailsOptions, type WrapperGuardrailsSettings, ZespanADKCallbackHandler, ZespanCallbackHandler, ZespanClient, type ZespanContextOptions, ZespanLlamaIndexHandler, attachTraceToAutoGenMessage, autopatch, createSpan, extractAgentContext, extractAgentContext as extractAutoGenContext, extractTraceFromAutoGenMessage, getCrewAIInstrumentationGuide, getPydanticAIConfig, getTracer, getZespanClient, getZespanVercelTelemetry, init, initOTel, initZespan, injectAgentContext, injectAgentContext as injectAutoGenContext, instrumentADK, instrumentVercelAI, markFrameworkActive, markFrameworkInactive, startSpan, withAgent, withSpan, withZespan, withZespanContext, withZespanTrace, wrapADKAgent, wrapADKRunner, wrapAnthropic, wrapBedrock, wrapGoogle, wrapGoogleGenAI, wrapGroq, wrapLiteLLM, wrapMistral, wrapOpenAI, wrapOpenRouter, wrapZespanADKAgent, zespan };
+export { type ADKAgentOptions, type ADKRunnerOptions, AgentContext, type AgentOptions, BaggageSpanProcessor, CREWAI_OTEL_ENV, type DatasetItem, type DatasetRun, DatasetRunHandle, DatasetsClient, GuardrailBlockedError, type GuardrailCheckInput, type GuardrailCheckResponse, type GuardrailResult, type InstrumentADKOptions, type OTelConfig, type PiiCategory, type PiiPreset, type PiiRedactionMode, type Prompt, PromptClient, type PromptOptions, type ResolvedWrapperGuardrailsSettings, type WrapperGuardrailsOptions, type WrapperGuardrailsSettings, ZespanADKCallbackHandler, ZespanCallbackHandler, ZespanClient, type ZespanContextOptions, ZespanLlamaIndexHandler, type ZespanOptions, type ZespanPiiConfig, attachTraceToAutoGenMessage, autopatch, createSpan, extractAgentContext, extractAgentContext as extractAutoGenContext, extractTraceFromAutoGenMessage, getCrewAIInstrumentationGuide, getPydanticAIConfig, getTracer, getZespanClient, getZespanVercelTelemetry, init, initOTel, initZespan, injectAgentContext, injectAgentContext as injectAutoGenContext, instrumentADK, instrumentVercelAI, markFrameworkActive, markFrameworkInactive, startSpan, withAgent, withSpan, withZespan, withZespanContext, withZespanTrace, wrapADKAgent, wrapADKRunner, wrapAnthropic, wrapBedrock, wrapGoogle, wrapGoogleGenAI, wrapGroq, wrapLiteLLM, wrapMistral, wrapOpenAI, wrapOpenRouter, wrapZespanADKAgent, zespan };

package/dist/index.d.ts

@@ -8,13 +8,30 @@ import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { Serialized } from '@langchain/core/load/serializable';
 import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 
-interface ZespanOptions {
+type PiiPreset = "gdpr" | "hipaa" | "ccpa" | "pci-dss" | "soc2" | "finance" | "education" | "transportation";
+type PiiCategory = "personal" | "financial" | "government_ids" | "healthcare" | "digital_identity";
+type PiiRedactionMode = "placeholder" | "mask-middle" | "mask-all";
+interface ZespanPiiConfig {
+    piiPreset?: PiiPreset;
+    piiCategories?: PiiCategory[];
+    piiIncludeNames?: boolean;
+    piiIncludeEmails?: boolean;
+    piiIncludePhones?: boolean;
+    piiIncludeAddresses?: boolean;
+    piiConfidenceThreshold?: number;
+    piiRedactionMode?: PiiRedactionMode;
+    piiWhitelist?: string[];
+    piiCustomPatterns?: RegExp[];
+}
+interface ZespanOptions extends ZespanPiiConfig {
     apiKey: string;
     endpoint?: string;
     baseURL?: string;
     environment?: string;
     storePrompts?: boolean;
     redactKeys?: string[];
+    /** Pattern-based PII detection via openredaction. OFF by default — must opt in. */
+    redactPii?: boolean;
     sampleRate?: number;
     debug?: boolean;
     batchSize?: number;
@@ -53,6 +70,11 @@ interface PromptOptions {
     version?: number;
     label?: string;
     cache?: boolean;
+    fallback?: {
+        type?: "text" | "chat";
+        prompt: any;
+        config?: any;
+    };
 }
 interface Prompt {
     id: string;
@@ -67,6 +89,11 @@ interface Prompt {
     createdAt: string;
     updatedAt: string;
     promptHash: string;
+    isFallback?: boolean;
+}
+interface ChatMessage {
+    role: string;
+    content: string;
 }
 declare class PromptClient {
     private client;
@@ -99,9 +126,12 @@ declare class PromptClient {
      */
     updateLabels(name: string, version: number, labels: string[]): Promise<Prompt>;
     /**
-     * Compile a prompt with variables
+     * Compile a prompt with `{{var}}` substitution and chat message placeholders.
+     * - text prompt -> substituted string.
+     * - chat prompt -> message array with placeholders spliced in order
+     *   (unfilled dropped) and vars substituted across all message contents.
      */
-    compile(prompt: Prompt, variables: Record<string, string>): string;
+    compile(prompt: Prompt, variables?: Record<string, string>, placeholders?: Record<string, ChatMessage[]>): string | ChatMessage[];
     /**
      * Clear cache for a specific prompt or all prompts
      */
@@ -110,6 +140,40 @@ declare class PromptClient {
     private invalidateCache;
 }
 
+interface DatasetItem {
+    id: string;
+    datasetId: string;
+    input: unknown;
+    expectedOutput?: unknown;
+    metadata?: Record<string, unknown>;
+}
+interface DatasetRun {
+    id: string;
+    datasetId: string;
+    name: string;
+    description: string | null;
+}
+declare class DatasetRunHandle {
+    private client;
+    private datasetId;
+    readonly run: DatasetRun;
+    constructor(client: ZespanClient, datasetId: string, run: DatasetRun);
+    /** Links a dataset item to this run via the trace your own code just produced. */
+    link(datasetItemId: string, traceId: string, observationId?: string): Promise<void>;
+}
+declare class DatasetsClient {
+    private client;
+    private datasetIdByName;
+    constructor(client: ZespanClient);
+    private resolveDatasetId;
+    /** Lists a dataset's items by dataset name. */
+    getItems(datasetName: string): Promise<DatasetItem[]>;
+    /** Creates or fetches a named run (idempotent — safe to call every time a job starts). */
+    createRun(datasetName: string, runName: string, opts?: {
+        description?: string;
+    }): Promise<DatasetRunHandle>;
+}
+
 /**
  * SDK ConfigClient — zero-infra runtime configuration client.
  *
@@ -246,10 +310,12 @@ declare class ZespanClient {
     readonly environment: string;
     readonly storePrompts: boolean;
     readonly redactKeys: string[];
+    readonly redactPii: boolean;
     readonly sampleRate: number;
     readonly debug: boolean;
     readonly enableOTel: boolean;
     readonly prompts: PromptClient;
+    readonly datasets: DatasetsClient;
     readonly configClient: ConfigClient | null;
     readonly projectId: string | undefined;
     private batch;
@@ -258,6 +324,9 @@ declare class ZespanClient {
     constructor(opts: ZespanOptions);
     enqueue(event: ZespanEvent): void;
     redactForStorage(value: unknown): string;
+    redactValueAsync(value: unknown): Promise<string>;
+    redactTextAsync(text: string): Promise<string>;
+    redactObjectAsync(obj: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
     private resolveGuardrailsUrl;
     checkGuardrails(input: GuardrailCheckInput): Promise<GuardrailCheckResponse>;
     flush(): Promise<void>;
@@ -452,6 +521,8 @@ interface AgentOptions {
     name: string;
     role?: string;
     framework?: string;
+    version?: string;
+    description?: string;
     tools?: ToolDefinition[];
     metadata?: Record<string, unknown>;
 }
@@ -558,6 +629,8 @@ declare const zespan: {
     createSpan: typeof createSpan;
     withSpan: typeof withSpan;
     PromptClient: typeof PromptClient;
+    DatasetsClient: typeof DatasetsClient;
+    DatasetRunHandle: typeof DatasetRunHandle;
     CallbackHandler: typeof ZespanCallbackHandler;
     ADKCallbackHandler: typeof ZespanADKCallbackHandler;
     autopatch: typeof autopatch;
@@ -568,4 +641,4 @@ declare const zespan: {
     ZespanLlamaIndexHandler: typeof ZespanLlamaIndexHandler;
 };
 
-export { type ADKAgentOptions, type ADKRunnerOptions, AgentContext, type AgentOptions, BaggageSpanProcessor, CREWAI_OTEL_ENV, GuardrailBlockedError, type GuardrailCheckInput, type GuardrailCheckResponse, type GuardrailResult, type InstrumentADKOptions, type OTelConfig, type Prompt, PromptClient, type PromptOptions, type ResolvedWrapperGuardrailsSettings, type WrapperGuardrailsOptions, type WrapperGuardrailsSettings, ZespanADKCallbackHandler, ZespanCallbackHandler, ZespanClient, type ZespanContextOptions, ZespanLlamaIndexHandler, attachTraceToAutoGenMessage, autopatch, createSpan, extractAgentContext, extractAgentContext as extractAutoGenContext, extractTraceFromAutoGenMessage, getCrewAIInstrumentationGuide, getPydanticAIConfig, getTracer, getZespanClient, getZespanVercelTelemetry, init, initOTel, initZespan, injectAgentContext, injectAgentContext as injectAutoGenContext, instrumentADK, instrumentVercelAI, markFrameworkActive, markFrameworkInactive, startSpan, withAgent, withSpan, withZespan, withZespanContext, withZespanTrace, wrapADKAgent, wrapADKRunner, wrapAnthropic, wrapBedrock, wrapGoogle, wrapGoogleGenAI, wrapGroq, wrapLiteLLM, wrapMistral, wrapOpenAI, wrapOpenRouter, wrapZespanADKAgent, zespan };
+export { type ADKAgentOptions, type ADKRunnerOptions, AgentContext, type AgentOptions, BaggageSpanProcessor, CREWAI_OTEL_ENV, type DatasetItem, type DatasetRun, DatasetRunHandle, DatasetsClient, GuardrailBlockedError, type GuardrailCheckInput, type GuardrailCheckResponse, type GuardrailResult, type InstrumentADKOptions, type OTelConfig, type PiiCategory, type PiiPreset, type PiiRedactionMode, type Prompt, PromptClient, type PromptOptions, type ResolvedWrapperGuardrailsSettings, type WrapperGuardrailsOptions, type WrapperGuardrailsSettings, ZespanADKCallbackHandler, ZespanCallbackHandler, ZespanClient, type ZespanContextOptions, ZespanLlamaIndexHandler, type ZespanOptions, type ZespanPiiConfig, attachTraceToAutoGenMessage, autopatch, createSpan, extractAgentContext, extractAgentContext as extractAutoGenContext, extractTraceFromAutoGenMessage, getCrewAIInstrumentationGuide, getPydanticAIConfig, getTracer, getZespanClient, getZespanVercelTelemetry, init, initOTel, initZespan, injectAgentContext, injectAgentContext as injectAutoGenContext, instrumentADK, instrumentVercelAI, markFrameworkActive, markFrameworkInactive, startSpan, withAgent, withSpan, withZespan, withZespanContext, withZespanTrace, wrapADKAgent, wrapADKRunner, wrapAnthropic, wrapBedrock, wrapGoogle, wrapGoogleGenAI, wrapGroq, wrapLiteLLM, wrapMistral, wrapOpenAI, wrapOpenRouter, wrapZespanADKAgent, zespan };