@jaypie/llm 1.2.39 → 1.2.41

package/dist/esm/observability/llmobs.d.ts

@@ -0,0 +1,72 @@
+/**
+ * LLM Observability span kinds supported by Datadog's `llmobs` SDK.
+ * @see https://docs.datadoghq.com/llm_observability/setup/sdk/nodejs/
+ */
+export type LlmObsSpanKind = "agent" | "embedding" | "llm" | "retrieval" | "task" | "tool" | "workflow";
+export interface LlmObsSpanOptions {
+    kind: LlmObsSpanKind;
+    modelName?: string;
+    modelProvider?: string;
+    name: string;
+}
+export interface LlmObsAnnotation {
+    inputData?: unknown;
+    metadata?: Record<string, unknown>;
+    metrics?: Record<string, number>;
+    outputData?: unknown;
+    tags?: Record<string, unknown>;
+}
+/** Manual span handle for streaming, where a callback cannot enclose the work. */
+export interface LlmObsSpanHandle {
+    annotate: (annotation: LlmObsAnnotation) => void;
+    finish: () => void;
+}
+/** Minimal shape of the dd-trace `llmobs` SDK surface this module uses. */
+interface LlmObsSdk {
+    annotate: (span: unknown, annotation: LlmObsAnnotation) => void;
+    trace: (options: LlmObsSpanOptions, fn: (span: unknown) => unknown) => unknown;
+}
+/** Reset the cached SDK resolution. Exposed for tests. */
+export declare function _resetLlmObs(): void;
+/**
+ * Inject an SDK to bypass dd-trace resolution. Test-only: dd-trace is not a
+ * dependency, so the enabled path cannot otherwise be exercised in unit tests.
+ */
+export declare function _setLlmObs(sdk: LlmObsSdk | null): void;
+/**
+ * True when LLM Observability emission is opted in via `DD_LLMOBS_ENABLED`.
+ * Accepts any truthy value except "false"/"0".
+ */
+export declare function isLlmObsEnabled(): boolean;
+/**
+ * Run `fn` inside an LLM Observability span. When emission is disabled or
+ * dd-trace is absent, `fn` is invoked directly with no overhead. The active
+ * span is established for the duration of `fn`, so nested `withLlmObsSpan`
+ * calls (and `annotateLlmObs`) attach as children/annotations automatically.
+ */
+export declare function withLlmObsSpan<T>(options: LlmObsSpanOptions, fn: () => Promise<T>): Promise<T>;
+/**
+ * Annotate the currently active LLM Observability span. No-op when disabled.
+ */
+export declare function annotateLlmObs(annotation: LlmObsAnnotation): void;
+/**
+ * Open a manual span that is finished later. Used by streaming, where work is
+ * yielded incrementally and cannot be enclosed in a single callback. The span
+ * is kept open via a deferred promise resolved by `finish()`. Returns null when
+ * emission is disabled or dd-trace is absent.
+ *
+ * Note: because the span is held open across `yield` boundaries (outside the
+ * SDK's AsyncLocalStorage scope), manual spans are emitted flat rather than
+ * nested. Annotations are applied to the explicit span reference.
+ */
+export declare function openLlmObsSpan(options: LlmObsSpanOptions): LlmObsSpanHandle | null;
+/**
+ * Sum an `LlmUsage` array into LLM Observability metric keys. Returns undefined
+ * when there is no usage data so callers can omit the `metrics` field.
+ */
+export declare function usageToLlmObsMetrics(usage?: Array<{
+    input?: number;
+    output?: number;
+    total?: number;
+}>): Record<string, number> | undefined;
+export {};

package/dist/esm/operate/OperateLoop.d.ts

@@ -34,6 +34,12 @@ export declare class OperateLoop {
     private createContext;
     private buildInitialRequest;
     private executeOneTurn;
+    /**
+     * Backfill declared array fields when a `format` is supplied. A declared
+     * `format` is a schema contract: an empty array field should surface as `[]`
+     * rather than be dropped by a provider/model that omits empty lists.
+     */
+    private applyFormatArrayDefaults;
     /**
      * Sync the current input state from the updated provider request.
      * This is necessary because appendToolResult modifies the provider-specific request,

package/dist/esm/util/fillFormatArrays.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod/v4";
+import { JsonObject, NaturalSchema } from "@jaypie/types";
+type Format = JsonObject | NaturalSchema | z.ZodType;
+/**
+ * Ensure every array field declared in `format` is present in `content` as an
+ * array. A declared `format` is a schema contract: an empty list should surface
+ * as `[]`, not be dropped from the response. Some providers/models omit empty
+ * array fields entirely, leaving consumers to read `.length` on `undefined`.
+ *
+ * Only mutates a (cloned) structured object; strings and non-objects pass
+ * through untouched.
+ */
+export declare function fillFormatArrays({ content, format, }: {
+    content: JsonObject;
+    format: Format;
+}): JsonObject;
+export {};

package/dist/esm/util/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./determineModelProvider.js";
 export * from "./extractReasoning.js";
+export * from "./fillFormatArrays.js";
 export * from "./formatOperateInput.js";
 export * from "./formatOperateMessage.js";
 export * from "./jsonSchemaToOpenApi3.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/llm",
-  "version": "1.2.39",
+  "version": "1.2.41",
   "description": "Large language model utilities",
   "repository": {
     "type": "git",