langwatch 0.33.2 → 0.35.0

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import { L as Logger, C as ConsoleLogger, N as NoOpLogger } from './index-D7rKIGrO.js';
-export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, d as getLangWatchTracer } from './implementation-Cbelb5TK.js';
+export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, a as getLangWatchTracer } from './implementation-CMWs8g5L.js';
 import { z } from 'zod';
-import { p as paths, P as PromptResponse, g as CreatePromptBody, U as UpdatePromptBody, T as TagDefinition, h as CreatedTag, o as operations, i as PromptData, F as FetchPolicy, j as Prompt, a as LangWatchSpan, k as components } from './types-CmMOt86P.js';
+import { p as paths, P as PromptResponse, C as CreatePromptBody, U as UpdatePromptBody, T as TagDefinition, a as CreatedTag, o as operations, b as PromptData, F as FetchPolicy, c as Prompt, L as LangWatchSpan, d as components } from './types-D-yAkWoC.js';
 import openApiCreateClient from 'openapi-fetch';
-export { l as attributes } from './types-BvCQH8F1.js';
+export { l as attributes } from './types-VOZv9LYO.js';
+import { CliHandledErrorReason, CliHandledError } from '@langwatch/langy/cards/handled-error';
+export { CliHandledErrorReason as LangWatchHandledErrorReason, CliHandledError as LangWatchHandledErrorShape } from '@langwatch/langy/cards/handled-error';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/exporter-trace-otlp-http';
 import '@opentelemetry/core';
@@ -12,14 +14,6 @@ import '@opentelemetry/api';
 import '@opentelemetry/semantic-conventions';
 import '@opentelemetry/semantic-conventions/incubating';
 
-type PromptDependency = string | {
-    version?: string;
-    file?: string;
-};
-type PromptsConfig = {
-    prompts: Record<string, PromptDependency>;
-};
-type RuntimeParameters = Record<string, unknown>;
 declare const localPromptConfigSchema: z.ZodObject<{
     model: z.ZodString;
     modelParameters: z.ZodOptional<z.ZodObject<{
@@ -37,6 +31,15 @@ declare const localPromptConfigSchema: z.ZodObject<{
     parameters: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
 }, z.core.$loose>;
 type LocalPromptConfig = z.infer<typeof localPromptConfigSchema>;
+
+type PromptDependency = string | {
+    version?: string;
+    file?: string;
+};
+type PromptsConfig = {
+    prompts: Record<string, PromptDependency>;
+};
+type RuntimeParameters = Record<string, unknown>;
 type MaterializedPrompt = {
     id: string;
     name: string;
@@ -257,8 +260,19 @@ declare class FileManager {
     private static readonly PROMPTS_DIR;
     private static readonly MATERIALIZED_DIR;
     private static _projectRoot;
+    /**
+     * The cwd `_projectRoot` was derived from.
+     *
+     * The cache MUST be keyed by it. Memoising a cwd-derived path without that key
+     * is correct only in a process that serves exactly one command and then dies;
+     * in a process that serves many from different directories (the CLI daemon, a
+     * test runner, an embedding host), the second caller silently inherits the
+     * first caller's project root and reads or writes the wrong prompts.json.
+     */
+    private static _projectRootCwd;
     /** Reset the cached project root. Tests use this to exercise different cwds. */
     static _resetProjectRootCache(): void;
+    private static cacheProjectRoot;
     private static readonly PROJECT_MARKERS;
     private static hasProjectMarker;
     private static findProjectRoot;
@@ -1268,6 +1282,87 @@ type RunExperimentOptions = {
      */
     onProgress?: (progress: number, total: number) => void;
 };
+/**
+ * Inputs that override a platform experiment or workflow run on the server.
+ *
+ * `data` and `datasetId` are mutually exclusive (the backend rejects passing
+ * both). `parameters` overrides target parameters (e.g. prompt variables) and
+ * `rowIndices` restricts execution to a subset of the configured dataset.
+ */
+type RunWithResultsOptions = {
+    /**
+     * Inline rows to evaluate. Mutually exclusive with `datasetId`.
+     */
+    data?: Array<Record<string, unknown>>;
+    /**
+     * Id of a saved dataset to evaluate. Mutually exclusive with `data`.
+     */
+    datasetId?: string;
+    /**
+     * Target parameter overrides (e.g. prompt variables, model settings).
+     */
+    parameters?: Record<string, string | number | boolean>;
+    /**
+     * Subset of dataset row indices to run.
+     */
+    rowIndices?: number[];
+} & RunExperimentOptions;
+/**
+ * A single per-row result, mirroring one row of the python SDK's results
+ * DataFrame (`_build_df_from_platform`).
+ */
+type ExperimentRowResult = {
+    /**
+     * Index of the dataset row this result belongs to.
+     */
+    index: number;
+    /**
+     * Target id, present only for multi-target runs.
+     */
+    target?: string;
+    /**
+     * Flattened dataset entry fields for this row.
+     */
+    input: Record<string, unknown>;
+    /**
+     * Output produced by the target (`predicted.output`).
+     */
+    output: unknown;
+    /**
+     * Trace id of the target execution for this row.
+     */
+    traceId: string;
+    /**
+     * Cost of the target execution, when measured.
+     */
+    cost?: number;
+    /**
+     * Duration of the target execution in milliseconds, when measured.
+     */
+    duration?: number;
+    /**
+     * Error message for this row, when the target execution failed.
+     */
+    error?: string;
+    /**
+     * Evaluation results for this row keyed by evaluator name.
+     */
+    evaluations: Record<string, {
+        score?: number;
+        passed?: boolean;
+    }>;
+};
+/**
+ * Result of a platform experiment or workflow run, including per-row results
+ * and a link to the run in LangWatch.
+ */
+type ExperimentRunWithResults = {
+    runId: string;
+    runUrl: string;
+    status: string;
+    summary: ExperimentRunSummary;
+    rows: ExperimentRowResult[];
+};
 /**
  * Final result of a platform experiment run
  */
@@ -1310,6 +1405,7 @@ type ExperimentsFacadeConfig = {
  */
 declare class ExperimentsFacade {
     private readonly config;
+    private readonly apiService;
     constructor(config: ExperimentsFacadeConfig);
     /**
      * Initialize a new experiment session (SDK-defined)
@@ -1351,6 +1447,31 @@ declare class ExperimentsFacade {
      * ```
      */
     run(slug: string, options?: RunExperimentOptions): Promise<ExperimentRunResult>;
+    /**
+     * Run a platform experiment and return per-row structured results.
+     *
+     * Starts the run through the unified evaluations-v3 backend (optionally
+     * overriding the configured inputs via `data` / `datasetId` / `parameters` /
+     * `rowIndices`), polls to completion, fetches the per-row results, and maps
+     * them to the same row structure as the python SDK's results DataFrame.
+     *
+     * @param slug - The slug of the experiment (found in the experiment URL)
+     * @param options - Optional inputs and polling configuration
+     * @returns The run id, results URL, status, summary, and per-row results
+     *
+     * @example
+     * ```typescript
+     * const langwatch = new LangWatch();
+     * const { rows, runUrl } = await langwatch.experiments.runWithResults(
+     *   "my-experiment-slug",
+     *   { data: [{ question: "What is 2 + 2?" }] },
+     * );
+     * for (const row of rows) {
+     *   console.log(row.output, row.evaluations);
+     * }
+     * ```
+     */
+    runWithResults(slug: string, options?: RunWithResultsOptions): Promise<ExperimentRunWithResults>;
     /**
      * Run an experiment and wait for completion using polling
      */
@@ -1363,15 +1484,13 @@ declare class ExperimentsFacade {
      * Get the status of a run
      */
     private getRunStatus;
+    private handleStartRunError;
+    private handleRunStatusError;
     /**
      * Build the result object from API response
      */
     private buildResult;
     private sleep;
-    /**
-     * Replace the domain of a URL with a new base URL, preserving the path
-     */
-    private replaceUrlDomain;
 }
 
 /**
@@ -1660,11 +1779,41 @@ type WorkflowResponse = NonNullable<paths["/api/workflows"]["get"]["responses"][
 type WorkflowDeleteResponse = paths["/api/workflows/{id}"]["delete"]["responses"]["200"]["content"]["application/json"];
 declare class WorkflowsApiService {
     private readonly apiClient;
-    constructor(config?: Pick<InternalConfig, "langwatchApiClient">);
+    private readonly experimentsApiService;
+    private readonly endpoint;
+    constructor(config?: Pick<InternalConfig, "langwatchApiClient"> & {
+        endpoint?: string;
+    });
     private handleApiError;
+    private postUndeclaredEndpoint;
     getAll(): Promise<WorkflowResponse[]>;
     get(id: string): Promise<WorkflowResponse>;
     delete(id: string): Promise<WorkflowDeleteResponse>;
+    /**
+     * Run a studio workflow evaluation and return per-row structured results.
+     *
+     * Starts the evaluation through the unified evaluations-v3 backend
+     * (`POST /api/workflows/{workflowId}/evaluate`), polls to completion, fetches
+     * the per-row results, and maps them to the same row structure as the python
+     * SDK's results DataFrame.
+     *
+     * @param workflowId - The studio workflow id
+     * @param options - Optional inputs, committed version override, and polling
+     *                   configuration. `data` and `datasetId` are mutually
+     *                   exclusive.
+     * @returns The run id, results URL, status, summary, and per-row results
+     *
+     * @example
+     * ```typescript
+     * const langwatch = new LangWatch();
+     * const { rows, runUrl } = await langwatch.workflows.run("workflow_123", {
+     *   data: [{ question: "What is 2 + 2?" }],
+     * });
+     * ```
+     */
+    run(workflowId: string, options?: RunWithResultsOptions & {
+        versionId?: string;
+    }): Promise<ExperimentRunWithResults>;
 }
 
 interface AgentResponse {
@@ -1990,9 +2139,106 @@ declare class LangWatch {
     get apiClient(): LangwatchApiClient;
 }
 
+/**
+ * A failure the platform NAMED.
+ *
+ * The API does not merely fail — when it declines a request it says precisely
+ * why, as a `HandledError` with a serialisable `kind` (`dataset_not_found`,
+ * `validation_error`), the HTTP status it answers with, and a `meta` bag of the
+ * context that makes the failure actionable. Until now the SDK collapsed all of
+ * that into an English sentence on a generic error, so a caller could read the
+ * failure but never react to it: a 404 "dataset not found" — a fact you can
+ * offer to fix — was indistinguishable from a 500.
+ *
+ * This is that structure, kept. Narrow with {@link isLangWatchHandledError} (or
+ * `instanceof`) and switch on `code`; `body` is the escape hatch to whatever the
+ * platform sent that this class did not model.
+ *
+ * ```ts
+ * try {
+ *   await langwatch.datasets.get("nope");
+ * } catch (error) {
+ *   if (isLangWatchHandledError(error) && error.code === "dataset_not_found") {
+ *     // Actionable: we know WHAT was not found, and can offer the list.
+ *     console.error(error.meta.id, error.traceId);
+ *   }
+ *   throw error;
+ * }
+ * ```
+ *
+ * ONLY raised for a failure the platform named. An infrastructure failure — a
+ * 5xx, a dead socket, a proxy's HTML error page — still raises the generic
+ * service error it always did, because presenting one of those as a domain
+ * error would blame the user for our outage.
+ */
+declare class LangWatchHandledError extends Error {
+    /**
+     * The discriminant. A boolean brand rather than `instanceof` alone because a
+     * bundled CLI and a consumer's `node_modules` copy of the SDK can hold two
+     * different copies of this class, and `instanceof` is false across that seam —
+     * the same reason the platform's own error handler tests for `code` rather
+     * than class identity.
+     */
+    readonly isLangWatchHandledError: true;
+    /** The platform's serialisable discriminant, e.g. `dataset_not_found`. */
+    readonly code: string;
+    /**
+     * @deprecated Back-compat alias of `code`, kept while the platform's
+     * `DomainError` → `HandledError` rename rolls out. Read `code` in new code.
+     */
+    readonly kind: string;
+    /** The status the platform answered with. */
+    readonly httpStatus: number;
+    /** The context the platform attached: ids, field errors — whatever makes it actionable. */
+    readonly meta: Record<string, unknown>;
+    /** The OTel trace to quote at support. Absent unless the route sent one. */
+    readonly traceId: string | undefined;
+    /** A clickable link to that trace, when the route sent one. */
+    readonly traceUrl: string | undefined;
+    /** A clickable link to the logs for that trace, when the route sent one. */
+    readonly logsUrl: string | undefined;
+    /** The failure behind the failure, when the route sent the chain. */
+    readonly reasons: CliHandledErrorReason[] | undefined;
+    /** What the user can DO about it, when the platform sent next steps. */
+    readonly suggestions: string[] | undefined;
+    /** The docs page that explains the failure, when the platform sent one. */
+    readonly docUrl: string | undefined;
+    /** The raw response body, verbatim — the escape hatch for anything unmodelled. */
+    readonly body: unknown;
+    /** What the SDK was doing, e.g. `get dataset "abc"`. */
+    readonly operation: string | undefined;
+    /**
+     * Alias of {@link httpStatus}, and the raw body again under the name the
+     * per-service `*ApiError` classes use.
+     *
+     * Not redundancy for its own sake: this class is thrown from the SAME code
+     * path that used to throw `TracesApiError` & friends, so anything that reads
+     * `.status` or `.originalError` off a caught SDK error — including the CLI's
+     * own telemetry reader — keeps working unchanged.
+     */
+    readonly status: number;
+    readonly originalError: unknown;
+    constructor({ handled, body, operation, message, }: {
+        handled: CliHandledError;
+        body: unknown;
+        operation?: string;
+        message: string;
+    });
+}
+/** Narrows any caught value to a {@link LangWatchHandledError}. */
+declare const isLangWatchHandledError: (error: unknown) => error is LangWatchHandledError;
+declare class LangWatchApiError extends Error {
+    readonly httpStatus: number;
+    readonly httpStatusText: string;
+    apiError: string | undefined;
+    body: unknown;
+    constructor(message: string, response: Response);
+    safeParseBody(response: Response): Promise<void>;
+}
+
 declare const logger: {
     ConsoleLogger: typeof ConsoleLogger;
     NoOpLogger: typeof NoOpLogger;
 };
 
-export { type BatchCreateRecordsResponse, type CreateDatasetOptions, type CreateEvaluatorBody, type CreateFromUploadResponse, type Dataset, DatasetApiError, type DatasetColumnType, type DatasetEntry, DatasetError, type DatasetListItem, type DatasetMetadata, DatasetNotFoundError, DatasetPlanLimitError, type DatasetRecordResponse, DatasetValidationError, DatasetsFacade, type DeleteRecordsResponse, type EvaluateOptions, type EvaluationCost, EvaluationError, type EvaluationResult, type EvaluationStatus, EvaluationsApiError, EvaluationsFacade, EvaluatorCallError, EvaluatorError, type EvaluatorField, EvaluatorNotFoundError, type EvaluatorResponse, EvaluatorsApiError, EvaluatorsApiService, Experiment, ExperimentApiError, ExperimentError, type EvaluateOptions$1 as ExperimentEvaluateOptions, type EvaluationResult$1 as ExperimentEvaluationResult, type EvaluationStatus$1 as ExperimentEvaluationStatus, ExperimentInitError, type ExperimentInitOptions, ExperimentsFacade, FetchPolicy, type GetDatasetOptions, type GetPromptOptions, LangWatch, type ListDatasetsApiResponse, type ListDatasetsOptions, type ListRecordsApiResponse, type ListRecordsOptions, type LogOptions, type PaginatedResponse, type Pagination, type RunCallback, type RunContext, type RunOptions, type TargetInfo, type TargetMetadata, TargetMetadataConflictError, type TargetType, type UpdateDatasetOptions, type UploadResponse, logger };
+export { type BatchCreateRecordsResponse, type CreateDatasetOptions, type CreateEvaluatorBody, type CreateFromUploadResponse, type Dataset, DatasetApiError, type DatasetColumnType, type DatasetEntry, DatasetError, type DatasetListItem, type DatasetMetadata, DatasetNotFoundError, DatasetPlanLimitError, type DatasetRecordResponse, DatasetValidationError, DatasetsFacade, type DeleteRecordsResponse, type EvaluateOptions, type EvaluationCost, EvaluationError, type EvaluationResult, type EvaluationStatus, EvaluationsApiError, EvaluationsFacade, EvaluatorCallError, EvaluatorError, type EvaluatorField, EvaluatorNotFoundError, type EvaluatorResponse, EvaluatorsApiError, EvaluatorsApiService, Experiment, ExperimentApiError, ExperimentError, type EvaluateOptions$1 as ExperimentEvaluateOptions, type EvaluationResult$1 as ExperimentEvaluationResult, type EvaluationStatus$1 as ExperimentEvaluationStatus, ExperimentInitError, type ExperimentInitOptions, type ExperimentRowResult, type ExperimentRunWithResults, ExperimentsFacade, FetchPolicy, type GetDatasetOptions, type GetPromptOptions, LangWatch, LangWatchApiError, LangWatchHandledError, type ListDatasetsApiResponse, type ListDatasetsOptions, type ListRecordsApiResponse, type ListRecordsOptions, type LogOptions, type PaginatedResponse, type Pagination, type RunCallback, type RunContext, type RunOptions, type RunWithResultsOptions, type TargetInfo, type TargetMetadata, TargetMetadataConflictError, type TargetType, type UpdateDatasetOptions, type UploadResponse, isLangWatchHandledError, logger };