@illuma-ai/agents 1.0.81

package/src/graphs/__tests__/structured-output.test.ts

@@ -0,0 +1,183 @@
+// src/graphs/__tests__/structured-output.test.ts
+import { StructuredOutputRefusalError, StructuredOutputTruncatedError } from '@/types/graph';
+import { prepareSchemaForProvider } from '@/schemas/validate';
+import { Providers } from '@/common';
+
+/**
+ * Unit tests for the structured output logic in Graph.ts.
+ * These test individual components and error classes without instantiating the full Graph.
+ * Integration tests with real models are in structured-output.integration.test.ts.
+ */
+
+describe('StructuredOutputRefusalError', () => {
+  it('creates error with refusal text', () => {
+    const error = new StructuredOutputRefusalError('I cannot produce that output');
+    expect(error.name).toBe('StructuredOutputRefusalError');
+    expect(error.refusalText).toBe('I cannot produce that output');
+    expect(error.message).toContain('Model refused');
+    expect(error.message).toContain('I cannot produce that output');
+    expect(error instanceof Error).toBe(true);
+  });
+});
+
+describe('StructuredOutputTruncatedError', () => {
+  it('creates error with stop reason', () => {
+    const error = new StructuredOutputTruncatedError('max_tokens');
+    expect(error.name).toBe('StructuredOutputTruncatedError');
+    expect(error.stopReason).toBe('max_tokens');
+    expect(error.message).toContain('truncated');
+    expect(error.message).toContain('max_tokens');
+    expect(error.message).toContain('Increase max_tokens');
+    expect(error instanceof Error).toBe(true);
+  });
+
+  it('works with OpenAI-style length stop reason', () => {
+    const error = new StructuredOutputTruncatedError('length');
+    expect(error.stopReason).toBe('length');
+    expect(error.message).toContain('length');
+  });
+});
+
+describe('Error handling in structured output', () => {
+  it('StructuredOutputRefusalError is catchable as Error', () => {
+    try {
+      throw new StructuredOutputRefusalError('safety refusal');
+    } catch (e) {
+      expect(e instanceof Error).toBe(true);
+      expect(e instanceof StructuredOutputRefusalError).toBe(true);
+    }
+  });
+
+  it('StructuredOutputTruncatedError is catchable as Error', () => {
+    try {
+      throw new StructuredOutputTruncatedError('max_tokens');
+    } catch (e) {
+      expect(e instanceof Error).toBe(true);
+      expect(e instanceof StructuredOutputTruncatedError).toBe(true);
+    }
+  });
+
+  it('errors are distinguishable from generic errors', () => {
+    const refusal = new StructuredOutputRefusalError('nope');
+    const truncated = new StructuredOutputTruncatedError('max_tokens');
+    const generic = new Error('generic');
+
+    expect(refusal instanceof StructuredOutputTruncatedError).toBe(false);
+    expect(truncated instanceof StructuredOutputRefusalError).toBe(false);
+    expect(generic instanceof StructuredOutputRefusalError).toBe(false);
+    expect(generic instanceof StructuredOutputTruncatedError).toBe(false);
+  });
+});
+
+describe('Schema preparation for native structured output', () => {
+  const testSchema = {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      age: { type: 'number', minimum: 0, maximum: 150 },
+      tags: { type: 'array', items: { type: 'string' }, minItems: 1 },
+      address: {
+        type: 'object',
+        properties: {
+          street: { type: 'string', maxLength: 200 },
+          zip: { type: 'string', pattern: '^\\d{5}$' },
+        },
+      },
+    },
+    required: ['name'],
+  };
+
+  it('prepares schema for Anthropic native mode', () => {
+    const { schema, warnings } = prepareSchemaForProvider(
+      testSchema,
+      Providers.ANTHROPIC,
+    );
+
+    // Root level
+    expect(schema.additionalProperties).toBe(false);
+    expect(schema.required).toEqual(
+      expect.arrayContaining(['name', 'age', 'tags', 'address']),
+    );
+
+    // Numeric constraints stripped
+    const ageProp = (schema.properties as Record<string, Record<string, unknown>>).age;
+    expect(ageProp.minimum).toBeUndefined();
+    expect(ageProp.maximum).toBeUndefined();
+    expect(ageProp.description).toContain('minimum');
+    expect(ageProp.description).toContain('maximum');
+
+    // Array constraints stripped
+    const tagsProp = (schema.properties as Record<string, Record<string, unknown>>).tags;
+    expect(tagsProp.minItems).toBeUndefined();
+
+    // Nested object prepared
+    const addressProp = (schema.properties as Record<string, Record<string, unknown>>).address;
+    expect(addressProp.additionalProperties).toBe(false);
+    expect(addressProp.required).toEqual(
+      expect.arrayContaining(['street', 'zip']),
+    );
+
+    // String constraints stripped
+    const streetProp = (addressProp.properties as Record<string, Record<string, unknown>>).street;
+    expect(streetProp.maxLength).toBeUndefined();
+
+    const zipProp = (addressProp.properties as Record<string, Record<string, unknown>>).zip;
+    expect(zipProp.pattern).toBeUndefined();
+
+    // Should have multiple warnings
+    expect(warnings.length).toBeGreaterThan(0);
+  });
+
+  it('prepares schema for OpenAI native mode', () => {
+    const { schema } = prepareSchemaForProvider(
+      testSchema,
+      Providers.OPENAI,
+    );
+
+    // Same constraints as Anthropic
+    expect(schema.additionalProperties).toBe(false);
+
+    const ageProp = (schema.properties as Record<string, Record<string, unknown>>).age;
+    expect(ageProp.minimum).toBeUndefined();
+  });
+
+  it('prepares schema for Bedrock', () => {
+    const { schema } = prepareSchemaForProvider(
+      testSchema,
+      Providers.BEDROCK,
+    );
+
+    // Same treatment
+    expect(schema.additionalProperties).toBe(false);
+    const ageProp = (schema.properties as Record<string, Record<string, unknown>>).age;
+    expect(ageProp.minimum).toBeUndefined();
+  });
+});
+
+describe('Stream aggregation behavior', () => {
+  it('synthetic tool call names are correctly identified', () => {
+    // These names should be filtered by stream.ts
+    const structuredOutputToolNames = ['response', 'structuredresponse', 'structured_response'];
+
+    for (const name of structuredOutputToolNames) {
+      expect(
+        name === 'response' ||
+        name === 'structuredresponse' ||
+        name === 'structured_response',
+      ).toBe(true);
+    }
+  });
+
+  it('regular tool names are not confused with structured output', () => {
+    const regularToolNames = ['web_search', 'calculator', 'my_response_handler'];
+
+    for (const name of regularToolNames) {
+      const lower = name.toLowerCase();
+      const isStructured =
+        lower === 'response' ||
+        lower === 'structuredresponse' ||
+        lower === 'structured_response';
+      expect(isStructured).toBe(false);
+    }
+  });
+});

package/src/graphs/index.ts

@@ -0,0 +1,2 @@
+export * from './Graph';
+export * from './MultiAgentGraph';

package/src/index.ts

@@ -0,0 +1,34 @@
+/* Main Operations */
+export * from './run';
+export * from './stream';
+export * from './splitStream';
+export * from './events';
+export * from './messages';
+
+/* Graphs */
+export * from './graphs';
+
+/* Tools */
+export * from './tools/Calculator';
+export * from './tools/CodeExecutor';
+export * from './tools/BrowserTools';
+export * from './tools/ProgrammaticToolCalling';
+export * from './tools/ToolSearch';
+export * from './tools/ToolNode';
+export * from './tools/schema';
+export * from './tools/handlers';
+export * from './tools/search';
+
+/* Schemas */
+export * from './schemas';
+
+/* Misc. */
+export * from './common';
+export * from './utils';
+
+/* Types */
+export type * from './types';
+
+/* LLM */
+export { CustomOpenAIClient } from './llm/openai';
+export { getChatModelClass, llmProviders } from './llm/providers';

package/src/instrumentation.ts

@@ -0,0 +1,22 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { LangfuseSpanProcessor } from '@langfuse/otel';
+import { isPresent } from '@/utils/misc';
+
+if (
+  isPresent(process.env.LANGFUSE_SECRET_KEY) &&
+  isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&
+  isPresent(process.env.LANGFUSE_BASE_URL)
+) {
+  const langfuseSpanProcessor = new LangfuseSpanProcessor({
+    publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+    secretKey: process.env.LANGFUSE_SECRET_KEY,
+    baseUrl: process.env.LANGFUSE_BASE_URL,
+    environment: process.env.LANGFUSE_TRACING_ENVIRONMENT ?? process.env.NODE_ENV ?? 'development',
+  });
+
+  const sdk = new NodeSDK({
+    spanProcessors: [langfuseSpanProcessor],
+  });
+
+  sdk.start();
+}

package/src/llm/anthropic/index.ts

@@ -0,0 +1,413 @@
+import { AIMessageChunk } from '@langchain/core/messages';
+import { ChatAnthropicMessages } from '@langchain/anthropic';
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { BaseChatModelParams } from '@langchain/core/language_models/chat_models';
+import type {
+  BaseMessage,
+  UsageMetadata,
+  MessageContentComplex,
+} from '@langchain/core/messages';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import type { AnthropicInput } from '@langchain/anthropic';
+import type { Anthropic } from '@anthropic-ai/sdk';
+import type {
+  AnthropicMessageCreateParams,
+  AnthropicStreamingMessageCreateParams,
+  AnthropicStreamUsage,
+  AnthropicMessageStartEvent,
+  AnthropicMessageDeltaEvent,
+} from '@/llm/anthropic/types';
+import { _makeMessageChunkFromAnthropicEvent } from './utils/message_outputs';
+import { _convertMessagesToAnthropicPayload } from './utils/message_inputs';
+import { handleToolChoice } from './utils/tools';
+import { TextStream } from '@/llm/text';
+
+function _toolsInParams(
+  params: AnthropicMessageCreateParams | AnthropicStreamingMessageCreateParams
+): boolean {
+  return !!(params.tools && params.tools.length > 0);
+}
+function _documentsInParams(
+  params: AnthropicMessageCreateParams | AnthropicStreamingMessageCreateParams
+): boolean {
+  for (const message of params.messages ?? []) {
+    if (typeof message.content === 'string') {
+      continue;
+    }
+    for (const block of message.content ?? []) {
+      if (
+        typeof block === 'object' &&
+        block != null &&
+        block.type === 'document' &&
+        typeof block.citations === 'object' &&
+        block.citations.enabled
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function _thinkingInParams(
+  params: AnthropicMessageCreateParams | AnthropicStreamingMessageCreateParams
+): boolean {
+  return !!(params.thinking && params.thinking.type === 'enabled');
+}
+
+function extractToken(
+  chunk: AIMessageChunk
+): [string, 'string' | 'input' | 'content'] | [undefined] {
+  if (typeof chunk.content === 'string') {
+    return [chunk.content, 'string'];
+  } else if (
+    Array.isArray(chunk.content) &&
+    chunk.content.length >= 1 &&
+    'input' in chunk.content[0]
+  ) {
+    return typeof chunk.content[0].input === 'string'
+      ? [chunk.content[0].input, 'input']
+      : [JSON.stringify(chunk.content[0].input), 'input'];
+  } else if (
+    Array.isArray(chunk.content) &&
+    chunk.content.length >= 1 &&
+    'text' in chunk.content[0]
+  ) {
+    return [chunk.content[0].text, 'content'];
+  } else if (
+    Array.isArray(chunk.content) &&
+    chunk.content.length >= 1 &&
+    'thinking' in chunk.content[0]
+  ) {
+    return [chunk.content[0].thinking, 'content'];
+  }
+  return [undefined];
+}
+
+function cloneChunk(
+  text: string,
+  tokenType: string,
+  chunk: AIMessageChunk
+): AIMessageChunk {
+  if (tokenType === 'string') {
+    return new AIMessageChunk(Object.assign({}, chunk, { content: text }));
+  } else if (tokenType === 'input') {
+    return chunk;
+  }
+  const content = chunk.content[0] as MessageContentComplex;
+  if (tokenType === 'content' && content.type === 'text') {
+    return new AIMessageChunk(
+      Object.assign({}, chunk, {
+        content: [Object.assign({}, content, { text })],
+      })
+    );
+  } else if (tokenType === 'content' && content.type === 'text_delta') {
+    return new AIMessageChunk(
+      Object.assign({}, chunk, {
+        content: [Object.assign({}, content, { text })],
+      })
+    );
+  } else if (tokenType === 'content' && content.type?.startsWith('thinking')) {
+    return new AIMessageChunk(
+      Object.assign({}, chunk, {
+        content: [Object.assign({}, content, { thinking: text })],
+      })
+    );
+  }
+
+  return chunk;
+}
+
+export type CustomAnthropicInput = AnthropicInput & {
+  _lc_stream_delay?: number;
+} & BaseChatModelParams;
+
+/**
+ * A type representing additional parameters that can be passed to the
+ * Anthropic API.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Kwargs = Record<string, any>;
+
+export class CustomAnthropic extends ChatAnthropicMessages {
+  _lc_stream_delay: number;
+  private message_start: AnthropicMessageStartEvent | undefined;
+  private message_delta: AnthropicMessageDeltaEvent | undefined;
+  private tools_in_params?: boolean;
+  private emitted_usage?: boolean;
+  top_k: number | undefined;
+  constructor(fields?: CustomAnthropicInput) {
+    super(fields);
+    this.resetTokenEvents();
+    this.setDirectFields(fields);
+    this._lc_stream_delay = fields?._lc_stream_delay ?? 25;
+  }
+
+  static lc_name(): 'IllumaAnthropic' {
+    return 'IllumaAnthropic';
+  }
+
+  /**
+   * Get the parameters used to invoke the model
+   */
+  override invocationParams(
+    options?: this['ParsedCallOptions']
+  ): Omit<
+    AnthropicMessageCreateParams | AnthropicStreamingMessageCreateParams,
+    'messages'
+  > &
+    Kwargs {
+    const tool_choice:
+      | Anthropic.Messages.ToolChoiceAuto
+      | Anthropic.Messages.ToolChoiceAny
+      | Anthropic.Messages.ToolChoiceTool
+      | undefined = handleToolChoice(options?.tool_choice);
+
+    if (this.thinking.type === 'enabled') {
+      if (this.top_k !== -1 && (this.top_k as number | undefined) != null) {
+        throw new Error('topK is not supported when thinking is enabled');
+      }
+      if (this.topP !== -1 && (this.topP as number | undefined) != null) {
+        throw new Error('topP is not supported when thinking is enabled');
+      }
+      if (
+        this.temperature !== 1 &&
+        (this.temperature as number | undefined) != null
+      ) {
+        throw new Error(
+          'temperature is not supported when thinking is enabled'
+        );
+      }
+
+      return {
+        model: this.model,
+        stop_sequences: options?.stop ?? this.stopSequences,
+        stream: this.streaming,
+        max_tokens: this.maxTokens,
+        tools: this.formatStructuredToolToAnthropic(options?.tools),
+        tool_choice,
+        thinking: this.thinking,
+        ...this.invocationKwargs,
+      };
+    }
+    return {
+      model: this.model,
+      temperature: this.temperature,
+      top_k: this.top_k,
+      top_p: this.topP,
+      stop_sequences: options?.stop ?? this.stopSequences,
+      stream: this.streaming,
+      max_tokens: this.maxTokens,
+      tools: this.formatStructuredToolToAnthropic(options?.tools),
+      tool_choice,
+      thinking: this.thinking,
+      ...this.invocationKwargs,
+    };
+  }
+
+  /**
+   * Get stream usage as returned by this client's API response.
+   * @returns The stream usage object.
+   */
+  getStreamUsage(): UsageMetadata | undefined {
+    if (this.emitted_usage === true) {
+      return;
+    }
+    const inputUsage = this.message_start?.message.usage as
+      | undefined
+      | AnthropicStreamUsage;
+    const outputUsage = this.message_delta?.usage as
+      | undefined
+      | Partial<AnthropicStreamUsage>;
+    if (!outputUsage) {
+      return;
+    }
+    const totalUsage: UsageMetadata = {
+      input_tokens: inputUsage?.input_tokens ?? 0,
+      output_tokens: outputUsage.output_tokens ?? 0,
+      total_tokens:
+        (inputUsage?.input_tokens ?? 0) + (outputUsage.output_tokens ?? 0),
+    };
+
+    if (
+      inputUsage?.cache_creation_input_tokens != null ||
+      inputUsage?.cache_read_input_tokens != null
+    ) {
+      totalUsage.input_token_details = {
+        cache_creation: inputUsage.cache_creation_input_tokens ?? 0,
+        cache_read: inputUsage.cache_read_input_tokens ?? 0,
+      };
+    }
+
+    this.emitted_usage = true;
+    return totalUsage;
+  }
+
+  resetTokenEvents(): void {
+    this.message_start = undefined;
+    this.message_delta = undefined;
+    this.emitted_usage = undefined;
+    this.tools_in_params = undefined;
+  }
+
+  setDirectFields(fields?: CustomAnthropicInput): void {
+    this.temperature = fields?.temperature ?? undefined;
+    this.topP = fields?.topP ?? undefined;
+    this.top_k = fields?.topK;
+    if (this.temperature === -1 || this.temperature === 1) {
+      this.temperature = undefined;
+    }
+    if (this.topP === -1) {
+      this.topP = undefined;
+    }
+    if (this.top_k === -1) {
+      this.top_k = undefined;
+    }
+  }
+
+  private createGenerationChunk({
+    token,
+    chunk,
+    usageMetadata,
+    shouldStreamUsage,
+  }: {
+    token?: string;
+    chunk: AIMessageChunk;
+    shouldStreamUsage: boolean;
+    usageMetadata?: UsageMetadata;
+  }): ChatGenerationChunk {
+    const usage_metadata = shouldStreamUsage
+      ? (usageMetadata ?? chunk.usage_metadata)
+      : undefined;
+    return new ChatGenerationChunk({
+      message: new AIMessageChunk({
+        // Just yield chunk as it is and tool_use will be concat by BaseChatModel._generateUncached().
+        content: chunk.content,
+        additional_kwargs: chunk.additional_kwargs,
+        tool_call_chunks: chunk.tool_call_chunks,
+        response_metadata: chunk.response_metadata,
+        usage_metadata,
+        id: chunk.id,
+      }),
+      text: token ?? '',
+    });
+  }
+
+  async *_streamResponseChunks(
+    messages: BaseMessage[],
+    options: this['ParsedCallOptions'],
+    runManager?: CallbackManagerForLLMRun
+  ): AsyncGenerator<ChatGenerationChunk> {
+    this.resetTokenEvents();
+    const params = this.invocationParams(options);
+    const formattedMessages = _convertMessagesToAnthropicPayload(messages);
+    const payload = {
+      ...params,
+      ...formattedMessages,
+      stream: true,
+    } as const;
+    const coerceContentToString =
+      !_toolsInParams(payload) &&
+      !_documentsInParams(payload) &&
+      !_thinkingInParams(payload);
+
+    const stream = await this.createStreamWithRetry(payload, {
+      headers: options.headers,
+    });
+
+    const shouldStreamUsage = this.streamUsage ?? options.streamUsage;
+
+    for await (const data of stream) {
+      if (options.signal?.aborted === true) {
+        stream.controller.abort();
+        throw new Error('AbortError: User aborted the request.');
+      }
+
+      if (data.type === 'message_start') {
+        this.message_start = data as AnthropicMessageStartEvent;
+      } else if (data.type === 'message_delta') {
+        this.message_delta = data as AnthropicMessageDeltaEvent;
+      }
+
+      let usageMetadata: UsageMetadata | undefined;
+      if (this.tools_in_params !== true && this.emitted_usage !== true) {
+        usageMetadata = this.getStreamUsage();
+      }
+
+      const result = _makeMessageChunkFromAnthropicEvent(data, {
+        streamUsage: shouldStreamUsage,
+        coerceContentToString,
+      });
+      if (!result) continue;
+
+      const { chunk } = result;
+      const [token = '', tokenType] = extractToken(chunk);
+
+      if (
+        !tokenType ||
+        tokenType === 'input' ||
+        (token === '' && (usageMetadata != null || chunk.id != null))
+      ) {
+        const generationChunk = this.createGenerationChunk({
+          token,
+          chunk,
+          usageMetadata,
+          shouldStreamUsage,
+        });
+        yield generationChunk;
+        await runManager?.handleLLMNewToken(
+          token,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          { chunk: generationChunk }
+        );
+        continue;
+      }
+
+      const textStream = new TextStream(token, {
+        delay: this._lc_stream_delay,
+        firstWordChunk: true,
+        minChunkSize: 4,
+        maxChunkSize: 8,
+      });
+
+      const generator = textStream.generateText(options.signal);
+      try {
+        let emittedUsage = false;
+        for await (const currentToken of generator) {
+          if ((options.signal as AbortSignal | undefined)?.aborted === true) {
+            break;
+          }
+          const newChunk = cloneChunk(currentToken, tokenType, chunk);
+
+          const generationChunk = this.createGenerationChunk({
+            token: currentToken,
+            chunk: newChunk,
+            usageMetadata: emittedUsage ? undefined : usageMetadata,
+            shouldStreamUsage,
+          });
+
+          if (usageMetadata && !emittedUsage) {
+            emittedUsage = true;
+          }
+          yield generationChunk;
+
+          await runManager?.handleLLMNewToken(
+            currentToken,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            { chunk: generationChunk }
+          );
+        }
+      } finally {
+        await generator.return();
+      }
+    }
+
+    this.resetTokenEvents();
+  }
+}