langwatch 0.3.1 → 0.4.0

package/dist/{prompt-D-jpMrLS.d.mts → types-1q5wIYP5.d.mts}

@@ -1,3 +1,88 @@
+import { SpanOptions, Span, AttributeValue, Tracer, Context } from '@opentelemetry/api';
+import { S as SemConvAttributes } from './types-DRiQaKFG.mjs';
+
+type ChatRole = "system" | "user" | "assistant" | "function" | "tool" | "unknown";
+interface FunctionCall {
+    name?: string;
+    arguments?: string;
+}
+interface ToolCall {
+    id: string;
+    type: string;
+    function: FunctionCall;
+}
+interface ChatMessage {
+    role?: ChatRole;
+    content?: string | ChatRichContent[] | null;
+    function_call?: FunctionCall | null;
+    tool_calls?: ToolCall[] | null;
+    tool_call_id?: string | null;
+    name?: string | null;
+}
+type ChatRichContent = {
+    type: "text";
+    text?: string;
+} | {
+    text: string;
+} | {
+    type: "image_url";
+    image_url?: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+} | {
+    type: "tool_call";
+    toolName?: string;
+    toolCallId?: string;
+    args?: string;
+} | {
+    type: "tool_result";
+    toolName?: string;
+    toolCallId?: string;
+    result?: any;
+};
+interface TypedValueChatMessages {
+    type: "chat_messages";
+    value: ChatMessage[];
+}
+interface TypedValueText {
+    type: "text";
+    value: string;
+}
+interface TypedValueRaw {
+    type: "raw";
+    value: string;
+}
+type JSONSerializable = string | number | boolean | null | Record<string, any> | any[];
+interface TypedValueJson {
+    type: "json";
+    value: JSONSerializable;
+}
+type Money = {
+    currency: string;
+    amount: number;
+};
+interface EvaluationResult {
+    status: "processed" | "skipped" | "error";
+    passed?: boolean | null;
+    score?: number | null;
+    label?: string | null;
+    details?: string | null;
+    cost?: Money | null;
+}
+interface TypedValueGuardrailResult {
+    type: "guardrail_result";
+    value: EvaluationResult;
+}
+interface TypedValueEvaluationResult {
+    type: "evaluation_result";
+    value: EvaluationResult;
+}
+type SpanInputOutput = TypedValueText | TypedValueChatMessages | TypedValueGuardrailResult | TypedValueEvaluationResult | TypedValueJson | TypedValueRaw | {
+    type: "list";
+    value: SpanInputOutput[];
+};
+
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
@@ -923,6 +1008,8 @@ interface operations {
                         handle: string | null;
                         /** @enum {string} */
                         scope: "ORGANIZATION" | "PROJECT";
+                        projectId: string;
+                        organizationId: string;
                     }[];
                 };
             };
@@ -973,13 +1060,35 @@ interface operations {
         requestBody?: {
             content: {
                 "application/json": {
-                    name: string;
-                    handle?: string;
+                    name?: string;
+                    handle: string;
                     /**
                      * @default PROJECT
                      * @enum {string}
                      */
                     scope?: "ORGANIZATION" | "PROJECT";
+                    authorId?: string;
+                    prompt?: string;
+                    messages?: {
+                        /** @enum {string} */
+                        role: "user" | "assistant" | "system";
+                        content: string;
+                    }[];
+                    inputs?: {
+                        identifier: string;
+                        /** @enum {string} */
+                        type: "str" | "float" | "bool" | "image" | "list[str]" | "list[float]" | "list[int]" | "list[bool]" | "dict";
+                    }[];
+                    outputs?: {
+                        identifier: string;
+                        /** @enum {string} */
+                        type: "str" | "float" | "bool" | "json_schema";
+                        json_schema?: {
+                            type: string;
+                        } & {
+                            [key: string]: unknown;
+                        };
+                    }[];
                 };
             };
         };
@@ -1017,6 +1126,8 @@ interface operations {
                         handle: string | null;
                         /** @enum {string} */
                         scope: "ORGANIZATION" | "PROJECT";
+                        projectId: string;
+                        organizationId: string;
                     };
                 };
             };
@@ -2161,15 +2272,8 @@ interface operations {
 
 type PromptResponse = NonNullable<paths["/api/prompts/{id}"]["get"]["responses"]["200"]["content"]["application/json"]>;
 type TemplateVariables = Record<string, string | number | boolean | object | null>;
-/**
- * Error class for template compilation issues
- */
-declare class PromptCompilationError extends Error {
-    readonly template: string;
-    readonly originalError?: any | undefined;
-    constructor(message: string, template: string, originalError?: any | undefined);
-}
 declare class Prompt implements PromptResponse {
+    private readonly promptData;
     readonly id: string;
     readonly handle: string | null;
     readonly scope: "ORGANIZATION" | "PROJECT";
@@ -2201,12 +2305,522 @@ declare class Prompt implements PromptResponse {
      */
     compileStrict(variables: TemplateVariables): CompiledPrompt;
 }
-/**
- * Represents a compiled prompt that extends Prompt with reference to the original template
- */
 declare class CompiledPrompt extends Prompt {
     readonly original: Prompt;
     constructor(compiledData: PromptResponse, original: Prompt);
 }
 
-export { CompiledPrompt as C, Prompt as P, type TemplateVariables as T, PromptCompilationError as a };
+/**
+ * Simple chat message type with just role and content
+ */
+interface SimpleChatMessage {
+    role: string;
+    content: unknown;
+}
+/**
+ * Valid input/output types for span data
+ */
+declare const INPUT_OUTPUT_TYPES: readonly ["text", "raw", "chat_messages", "list", "json", "guardrail_result", "evaluation_result"];
+type InputOutputType = typeof INPUT_OUTPUT_TYPES[number];
+type JsonSerializable = string | number | boolean | null | JsonSerializable[] | Record<string, any>;
+
+/**
+ * Supported types of spans for LangWatch observability. These types categorize the nature of the span for downstream analysis and visualization.
+ *
+ * @example
+ * import { spanTypes, SpanType } from './span';
+ * const myType: SpanType = 'llm';
+ */
+declare const spanTypes: readonly ["span", "llm", "chain", "tool", "agent", "guardrail", "evaluation", "rag", "prompt", "workflow", "component", "module", "server", "client", "producer", "consumer", "task", "unknown"];
+type SpanType = (typeof spanTypes)[number];
+/**
+ * Context for a RAG (Retrieval-Augmented Generation) span.
+ *
+ * This structure is used to record which document and chunk were retrieved and used as context for a generation.
+ *
+ * @property document_id - Unique identifier for the source document.
+ * @property chunk_id - Unique identifier for the chunk within the document.
+ * @property content - The actual content of the chunk provided to the model.
+ *
+ * @example
+ * const ragContext: LangWatchSpanRAGContext = {
+ *   document_id: 'doc-123',
+ *   chunk_id: 'chunk-456',
+ *   content: 'Relevant passage from the document.'
+ * };
+ */
+interface LangWatchSpanRAGContext {
+    document_id: string;
+    chunk_id: string;
+    content: string;
+}
+/**
+ * Metrics for a LangWatch span.
+ *
+ * @property promptTokens - The number of prompt tokens used.
+ * @property completionTokens - The number of completion tokens used.
+ * @property cost - The cost of the span.
+ */
+interface LangWatchSpanMetrics {
+    /** The number of prompt tokens used */
+    promptTokens?: number;
+    /** The number of completion tokens used */
+    completionTokens?: number;
+    /** The cost of the span */
+    cost?: number;
+}
+/**
+ * Options for creating a LangWatch span.
+ *
+ * @param attributes - Additional attributes to add to the span.
+ */
+interface LangWatchSpanOptions extends SpanOptions {
+    /** Additional attributes to add to the span. */
+    attributes?: SemConvAttributes;
+}
+/**
+ * Extension of OpenTelemetry's Span with LangWatch-specific helpers for LLM, RAG, and GenAI tracing.
+ *
+ * This interface provides ergonomic methods for recording structured LLM/GenAI data, such as inputs, outputs, RAG contexts, and message events.
+ *
+ * All methods return `this` for chaining.
+ *
+ * @example
+ * const span = createLangWatchSpan(otelSpan);
+ * span
+ *   .setType('llm')
+ *   .setInput({ prompt: 'Hello' })
+ *   .setOutput('Hi!')
+ *   .addGenAIUserMessageEvent({ content: 'Hello' })
+ *   .addGenAIAssistantMessageEvent({ content: 'Hi!' });
+ */
+interface LangWatchSpan extends Span {
+    /**
+     * Set multiple attributes for the span.
+     *
+     * @param attributes - The attributes object
+     * @returns this
+     */
+    setAttributes(attributes: SemConvAttributes): this;
+    /**
+     * Set a single attribute for the span.
+     *
+     * @param key - The attribute key
+     * @param value - The attribute value
+     * @returns this
+     */
+    setAttribute(key: keyof SemConvAttributes, value: AttributeValue): this;
+    /**
+     * Set the type of the span (e.g., 'llm', 'rag', 'tool', etc).
+     *
+     * This is used for downstream filtering and analytics.
+     *
+     * @param type - The span type (see SpanType)
+     * @returns this
+     */
+    setType(type: SpanType): this;
+    /**
+     * Set the request model name for the span.
+     *
+     * This is typically the model name sent in the API request (e.g., 'gpt-4', 'claude-3').
+     *
+     * @param model - The request model name
+     * @returns this
+     */
+    setRequestModel(model: string): this;
+    /**
+     * Set the response model name for the span.
+     *
+     * This is the model name returned in the API response, if different from the request.
+     *
+     * @param model - The response model name
+     * @returns this
+     */
+    setResponseModel(model: string): this;
+    /**
+     * Set multiple RAG contexts for the span.
+     *
+     * Use this to record all retrieved documents/chunks used as context for a generation.
+     *
+     * @param ragContexts - Array of RAG context objects
+     * @returns this
+     */
+    setRAGContexts(ragContexts: LangWatchSpanRAGContext[]): this;
+    /**
+     * Set a single RAG context for the span.
+     *
+     * Use this if only one context was retrieved.
+     *
+     * @param ragContext - The RAG context object
+     * @returns this
+     */
+    setRAGContext(ragContext: LangWatchSpanRAGContext): this;
+    /**
+     * Set the metrics for the span.
+     *
+     * @param metrics - The metrics object
+     * @returns this
+     */
+    setMetrics(metrics: LangWatchSpanMetrics): this;
+    /**
+     * Set the selected prompt for the span. This will attach this prompt to the trace. If
+     * this is set on multiple spans, the last one will be used.
+     *
+     * @param prompt - The prompt object
+     * @returns this
+     */
+    setSelectedPrompt(prompt: Prompt): this;
+    /**
+     * Record the input to the span with explicit type control.
+     *
+     * @param type - Force as "text" type
+     * @param input - String input value
+     * @returns this
+     */
+    setInput(type: "text", input: string): this;
+    /**
+     * Record the input to the span with explicit type control.
+     *
+     * @param type - Force as "raw" type
+     * @param input - Any input value
+     * @returns this
+     */
+    setInput(type: "raw", input: unknown): this;
+    /**
+     * Record the input to the span with explicit type control.
+     *
+     * @param type - Force as "chat_messages" type
+     * @param input - Chat messages array (supports both ChatMessage[] and SimpleChatMessage[])
+     * @returns this
+     */
+    setInput(type: "chat_messages", input: ChatMessage[] | SimpleChatMessage[]): this;
+    /**
+     * Record the input to the span with explicit type control.
+     *
+     * @param type - Force as "list" type
+     * @param input - SpanInputOutput array
+     * @returns this
+     */
+    setInput(type: "list", input: SpanInputOutput[]): this;
+    /**
+     * Record the input to the span with explicit type control.
+     *
+     * @param type - Force as "json" type
+     * @param input - Any JSON-serializable value
+     * @returns this
+     */
+    setInput(type: "json", input: unknown): this;
+    /**
+     * Record the input to the span with explicit type control.
+     *
+     * @param type - Force as "guardrail_result" type
+     * @param input - Guardrail result value
+     * @returns this
+     */
+    setInput(type: "guardrail_result", input: unknown): this;
+    /**
+     * Record the input to the span with explicit type control.
+     *
+     * @param type - Force as "evaluation_result" type
+     * @param input - Evaluation result value
+     * @returns this
+     */
+    setInput(type: "evaluation_result", input: unknown): this;
+    /**
+     * Record the input to the span with automatic type detection.
+     *
+     * Automatically detects: strings → text, ChatMessage[] → chat_messages,
+     * arrays → list, objects → json.
+     *
+     * @param input - The input value (auto-detected type)
+     * @returns this
+     */
+    setInput(input: unknown): this;
+    /**
+     * Record the output from the span with explicit type control.
+     *
+     * @param type - Force as "text" type
+     * @param output - String output value
+     * @returns this
+     */
+    setOutput(type: "text", output: string): this;
+    /**
+     * Record the output from the span with explicit type control.
+     *
+     * @param type - Force as "raw" type
+     * @param output - Any output value
+     * @returns this
+     */
+    setOutput(type: "raw", output: unknown): this;
+    /**
+     * Record the output from the span with explicit type control.
+     *
+     * @param type - Force as "chat_messages" type
+     * @param output - Chat messages array (supports both ChatMessage[] and SimpleChatMessage[])
+     * @returns this
+     */
+    setOutput(type: "chat_messages", output: ChatMessage[] | SimpleChatMessage[]): this;
+    /**
+     * Record the output from the span with explicit type control.
+     *
+     * @param type - Force as "list" type
+     * @param output - SpanInputOutput array
+     * @returns this
+     */
+    setOutput(type: "list", output: SpanInputOutput[]): this;
+    /**
+     * Record the output from the span with explicit type control.
+     *
+     * @param type - Force as "json" type
+     * @param output - Any JSON-serializable value
+     * @returns this
+     */
+    setOutput(type: "json", output: unknown): this;
+    /**
+     * Record the output from the span with explicit type control.
+     *
+     * @param type - Force as "guardrail_result" type
+     * @param output - Guardrail result value
+     * @returns this
+     */
+    setOutput(type: "guardrail_result", output: unknown): this;
+    /**
+     * Record the output from the span with explicit type control.
+     *
+     * @param type - Force as "evaluation_result" type
+     * @param output - Evaluation result value
+     * @returns this
+     */
+    setOutput(type: "evaluation_result", output: unknown): this;
+    /**
+     * Record the output from the span with automatic type detection.
+     *
+     * Automatically detects: strings → text, ChatMessage[] → chat_messages,
+     * arrays → list, objects → json.
+     *
+     * @param output - The output value (auto-detected type)
+     * @returns this
+     */
+    setOutput(output: unknown): this;
+}
+
+/**
+ * Enhanced LangWatch tracer interface that extends OpenTelemetry's Tracer.
+ *
+ * This tracer provides additional functionality beyond the standard OpenTelemetry tracer:
+ * - Returns LangWatchSpan instances instead of standard OpenTelemetry Spans
+ * - Includes a custom `withActiveSpan` method for simplified span lifecycle management
+ * - Automatic error handling and span status management in `withActiveSpan`
+ * - Enhanced type safety with strongly-typed callback functions
+ *
+ * @example Basic usage
+ * ```typescript
+ * const tracer = getLangWatchTracer('my-service', '1.0.0');
+ *
+ * // Create and manage spans manually
+ * const span = tracer.startSpan('operation');
+ * span.setAttributes({ key: 'value' });
+ * span.end();
+ *
+ * // Use active span with automatic lifecycle management
+ * const result = await tracer.startActiveSpan('async-operation', async (span) => {
+ *   span.setAttributes({ userId: '123' });
+ *   return await someAsyncWork();
+ * });
+ *
+ * // Use withActiveSpan for automatic error handling and span cleanup
+ * const result = await tracer.withActiveSpan('safe-operation', async (span) => {
+ *   // Span is automatically ended and errors are properly recorded
+ *   return await riskyOperation();
+ * });
+ * ```
+ */
+interface LangWatchTracer extends Tracer {
+    /**
+     * Starts a new LangWatchSpan without setting it as the active span.
+     *
+     * **Enhanced from OpenTelemetry**: Returns a LangWatchSpan instead of a standard Span,
+     * providing additional LangWatch-specific functionality like structured input/output
+     * recording and enhanced attribute management.
+     *
+     * @param name - The name of the span
+     * @param options - Optional span configuration options
+     * @param context - Optional context to use for extracting parent span information
+     * @returns A new LangWatchSpan instance
+     *
+     * @example
+     * ```typescript
+     * const span = tracer.startSpan('database-query');
+     * span.setAttributes({
+     *   'db.statement': 'SELECT * FROM users',
+     *   'db.operation': 'select'
+     * });
+     *
+     * try {
+     *   const result = await database.query('SELECT * FROM users');
+     *   span.setStatus({ code: SpanStatusCode.OK });
+     *   return result;
+     * } catch (error) {
+     *   span.setStatus({
+     *     code: SpanStatusCode.ERROR,
+     *     message: error.message
+     *   });
+     *   span.recordException(error);
+     *   throw error;
+     * } finally {
+     *   span.end();
+     * }
+     * ```
+     */
+    startSpan(name: string, options?: LangWatchSpanOptions, context?: Context): LangWatchSpan;
+    /**
+     * Starts a new active LangWatchSpan and executes the provided function within its context.
+     *
+     * **Same as OpenTelemetry** but with LangWatchSpan: The span is automatically set as active
+     * in the current context for the duration of the function execution. The span must be
+     * manually ended within the callback function.
+     *
+     * @param name - The name of the span
+     * @param fn - Function to execute with the active span
+     * @returns The return value of the provided function
+     *
+     * @example
+     * ```typescript
+     * const result = tracer.startActiveSpan('user-operation', (span) => {
+     *   span.setAttributes({ userId: '123' });
+     *
+     *   try {
+     *     const userData = fetchUserData();
+     *     span.setStatus({ code: SpanStatusCode.OK });
+     *     return userData;
+     *   } catch (error) {
+     *     span.setStatus({
+     *       code: SpanStatusCode.ERROR,
+     *       message: error.message
+     *     });
+     *     throw error;
+     *   } finally {
+     *     span.end(); // Must manually end the span
+     *   }
+     * });
+     * ```
+     */
+    startActiveSpan<F extends (span: LangWatchSpan) => unknown>(name: string, fn: F): ReturnType<F>;
+    /**
+     * Starts a new active LangWatchSpan with options and executes the provided function.
+     *
+     * @param name - The name of the span
+     * @param options - Span configuration options
+     * @param fn - Function to execute with the active span
+     * @returns The return value of the provided function
+     */
+    startActiveSpan<F extends (span: LangWatchSpan) => unknown>(name: string, options: LangWatchSpanOptions, fn: F): ReturnType<F>;
+    /**
+     * Starts a new active LangWatchSpan with options and context, then executes the function.
+     *
+     * @param name - The name of the span
+     * @param options - Span configuration options
+     * @param context - Context to use for extracting parent span information
+     * @param fn - Function to execute with the active span
+     * @returns The return value of the provided function
+     */
+    startActiveSpan<F extends (span: LangWatchSpan) => unknown>(name: string, options: LangWatchSpanOptions, context: Context, fn: F): ReturnType<F>;
+    /**
+     * **LangWatch Enhancement**: Creates and manages a span with **automatic lifecycle and error handling**.
+     *
+     * 🚀 **Automatic span management, batteries included**:
+     * - ✅ **Span automatically ends** when your function completes (success or failure)
+     * - ✅ **Errors automatically handled** - exceptions are caught, recorded, and span marked as ERROR
+     * - ✅ **No need to call `span.end()`** - completely managed for you
+     * - ✅ **No try/catch needed** - error recording is automatic
+     *
+     * **Key differences from OpenTelemetry's startActiveSpan**:
+     * - Automatically ends the span when the function completes
+     * - Automatically sets span status to ERROR and records exceptions on thrown errors
+     * - Handles both synchronous and asynchronous functions seamlessly
+     * - Provides a safer, more convenient API for span management
+     *
+     * **Perfect for**: Operations where you want zero boilerplate span management.
+     * Just focus on your business logic - span lifecycle is handled automatically.
+     *
+     * @param name - The name of the span
+     * @param fn - Function to execute with the managed span (can be sync or async)
+     * @returns A promise that resolves to the return value of the provided function
+     *
+     * @example ✅ Clean code - NO manual span management needed
+     * ```typescript
+     * // ✅ AUTOMATIC span ending and error handling
+     * const result = await tracer.withActiveSpan('risky-operation', async (span) => {
+     *   span.setAttributes({ operation: 'data-processing' });
+     *
+     *   if (Math.random() > 0.5) {
+     *     throw new Error('Random failure'); // ✅ Automatically recorded, span marked as ERROR
+     *   }
+     *
+     *   return 'success';
+     *   // ✅ NO span.end() needed - automatically handled!
+     *   // ✅ NO try/catch needed - errors automatically recorded!
+     * });
+     * ```
+     *
+     * @example ❌ vs ✅ Compare with manual span management
+     * ```typescript
+     * // ❌ Manual span management (what you DON'T need to do)
+     * const span = tracer.startSpan('operation');
+     * try {
+     *   span.setAttributes({ key: 'value' });
+     *   const result = await doWork();
+     *   span.setStatus({ code: SpanStatusCode.OK });
+     *   return result;
+     * } catch (error) {
+     *   span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+     *   span.recordException(error);
+     *   throw error;
+     * } finally {
+     *   span.end(); // Must remember to end!
+     * }
+     *
+     * // ✅ With withActiveSpan (clean and automatic)
+     * const result = await tracer.withActiveSpan('operation', async (span) => {
+     *   span.setAttributes({ key: 'value' });
+     *   return await doWork(); // That's it! Everything else is automatic
+     * });
+     * ```
+     *
+     * @example ✅ Synchronous operations (no async/await needed)
+     * ```typescript
+     * const result = await tracer.withActiveSpan('sync-calc', (span) => {
+     *   span.setAttributes({ calculation: 'fibonacci' });
+     *   return fibonacci(10); // ✅ Synchronous function - span ends automatically
+     * });
+     *
+     * // ✅ Even with operations that might throw
+     * const data = await tracer.withActiveSpan('read-config', (span) => {
+     *   span.setAttributes({ file: 'config.json' });
+     *   return JSON.parse(fs.readFileSync('config.json', 'utf8')); // ✅ Errors auto-handled
+     * });
+     * ```
+     */
+    withActiveSpan<F extends (span: LangWatchSpan) => unknown>(name: string, fn: F): ReturnType<F>;
+    /**
+     * Creates and manages a span with options and automatic lifecycle management.
+     *
+     * @param name - The name of the span
+     * @param options - Span configuration options
+     * @param fn - Function to execute with the managed span (can be sync or async)
+     * @returns A promise that resolves to the return value of the provided function
+     */
+    withActiveSpan<F extends (span: LangWatchSpan) => unknown>(name: string, options: LangWatchSpanOptions, fn: F): ReturnType<F>;
+    /**
+     * Creates and manages a span with options, context, and automatic lifecycle management.
+     *
+     * @param name - The name of the span
+     * @param options - Span configuration options
+     * @param context - Context to use for extracting parent span information
+     * @param fn - Function to execute with the managed span (can be sync or async)
+     * @returns A promise that resolves to the return value of the provided function
+     */
+    withActiveSpan<F extends (span: LangWatchSpan) => unknown>(name: string, options: LangWatchSpanOptions, context: Context, fn: F): ReturnType<F>;
+}
+
+export { type ChatMessage as C, type InputOutputType as I, type JsonSerializable as J, type LangWatchSpan as L, type PromptResponse as P, type SpanType as S, type LangWatchTracer as a, type LangWatchSpanMetrics as b, type LangWatchSpanRAGContext as c, type LangWatchSpanOptions as d, type SimpleChatMessage as e, INPUT_OUTPUT_TYPES as f, Prompt as g, type paths as p, spanTypes as s };