illuma-agents 1.0.2

package/dist/types/specs/spec.utils.d.ts

@@ -0,0 +1 @@
+export declare function capitalizeFirstLetter(string: string): string;

package/dist/types/splitStream.d.ts

@@ -0,0 +1,37 @@
+import type * as t from '@/types';
+import { ContentTypes } from '@/common';
+export declare const SEPARATORS: string[];
+export declare class SplitStreamHandler {
+    private inCodeBlock;
+    private inThinkBlock;
+    private accumulate;
+    tokens: string[];
+    lastToken: string;
+    reasoningTokens: string[];
+    currentStepId?: string;
+    currentMessageId?: string;
+    currentType?: ContentTypes.TEXT | ContentTypes.THINK;
+    currentLength: number;
+    reasoningKey: 'reasoning_content' | 'reasoning';
+    currentIndex: number;
+    blockThreshold: number;
+    /** The run ID AKA the Message ID associated with the complete generation */
+    runId: string;
+    handlers?: t.SplitStreamHandlers;
+    constructor({ runId, handlers, accumulate, reasoningKey, blockThreshold, }: {
+        runId: string;
+        accumulate?: boolean;
+        handlers: t.SplitStreamHandlers;
+        blockThreshold?: number;
+        reasoningKey?: 'reasoning_content' | 'reasoning';
+    });
+    getMessageId: () => string | undefined;
+    createMessageStep: (type?: ContentTypes.TEXT | ContentTypes.THINK) => [string, string];
+    dispatchRunStep: (stepId: string, stepDetails: t.StepDetails) => void;
+    dispatchMessageDelta: (stepId: string, delta: t.MessageDelta) => void;
+    dispatchReasoningDelta: (stepId: string, delta: t.ReasoningDelta) => void;
+    handleContent: (content: string, _type: ContentTypes.TEXT | ContentTypes.THINK) => void;
+    getDeltaContent(chunk?: t.CustomChunk): string;
+    getReasoningDelta(chunk?: t.CustomChunk): string;
+    handle(chunk?: t.CustomChunk): void;
+}

package/dist/types/stream.d.ts

@@ -0,0 +1,14 @@
+import type { AIMessageChunk } from '@langchain/core/messages';
+import type { Graph } from '@/graphs';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+export declare function getChunkContent({ chunk, provider, reasoningKey, }: {
+    chunk?: Partial<AIMessageChunk>;
+    provider?: Providers;
+    reasoningKey: 'reasoning_content' | 'reasoning';
+}): string | t.MessageContentComplex[] | undefined;
+export declare class ChatModelStreamHandler implements t.EventHandler {
+    handle(event: string, data: t.StreamEventData, metadata?: Record<string, unknown>, graph?: Graph): void;
+    handleReasoning(chunk: Partial<AIMessageChunk>, graph: Graph, provider?: Providers): void;
+}
+export declare function createContentAggregator(): t.ContentAggregatorResult;

package/dist/types/tools/CodeExecutor.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+export declare const imageExtRegex: RegExp;
+export declare const getCodeBaseURL: () => string;
+declare const CodeExecutionToolSchema: z.ZodObject<{
+    lang: z.ZodEnum<["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r"]>;
+    code: z.ZodString;
+    session_id: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    lang: "r" | "d" | "py" | "js" | "ts" | "c" | "cpp" | "java" | "php" | "rs" | "go" | "f90";
+    args?: string[] | undefined;
+    session_id?: string | undefined;
+}, {
+    code: string;
+    lang: "r" | "d" | "py" | "js" | "ts" | "c" | "cpp" | "java" | "php" | "rs" | "go" | "f90";
+    args?: string[] | undefined;
+    session_id?: string | undefined;
+}>;
+declare function createCodeExecutionTool(params?: t.CodeExecutionToolParams): DynamicStructuredTool<typeof CodeExecutionToolSchema>;
+export { createCodeExecutionTool };

package/dist/types/tools/ToolNode.d.ts

@@ -0,0 +1,22 @@
+import { END, MessagesAnnotation } from '@langchain/langgraph';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { RunnableCallable } from '@/utils';
+export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
+    tools: t.GenericTool[];
+    private toolMap;
+    private loadRuntimeTools?;
+    handleToolErrors: boolean;
+    toolCallStepIds?: Map<string, string>;
+    errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
+    private toolUsageCount;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, }: t.ToolNodeConstructorParams);
+    /**
+     * Returns a snapshot of the current tool usage counts.
+     * @returns A ReadonlyMap where keys are tool names and values are their usage counts.
+     */
+    getToolUsageCounts(): ReadonlyMap<string, number>;
+    protected run(input: any, config: RunnableConfig): Promise<T>;
+}
+export declare function toolsCondition(state: BaseMessage[] | typeof MessagesAnnotation.State, invokedToolIds?: Set<string>): 'tools' | typeof END;

package/dist/types/tools/example.d.ts

@@ -0,0 +1,78 @@
+import { TavilySearchResults } from '@langchain/community/tools/tavily_search';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+export declare const fetchRandomImageTool: DynamicStructuredTool<z.ZodObject<{
+    input: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    input?: string | undefined;
+}, {
+    input?: string | undefined;
+}>, {
+    input?: string | undefined;
+}, {
+    input?: string | undefined;
+}, (string | undefined)[] | ({
+    type: string;
+    text: string;
+}[] | {
+    content: {
+        type: string;
+        image_url: {
+            url: string;
+        };
+    }[];
+})[]>;
+export declare const fetchRandomImageURL: DynamicStructuredTool<z.ZodObject<{
+    input: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    input?: string | undefined;
+}, {
+    input?: string | undefined;
+}>, {
+    input?: string | undefined;
+}, {
+    input?: string | undefined;
+}, (string | undefined)[] | ({
+    type: string;
+    text: string;
+}[] | {
+    content: {
+        type: string;
+        image_url: {
+            url: string;
+        };
+    }[];
+})[]>;
+export declare const chartTool: DynamicStructuredTool<z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        label: string;
+    }, {
+        value: number;
+        label: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    data: {
+        value: number;
+        label: string;
+    }[];
+}, {
+    data: {
+        value: number;
+        label: string;
+    }[];
+}>, {
+    data: {
+        value: number;
+        label: string;
+    }[];
+}, {
+    data: {
+        value: number;
+        label: string;
+    }[];
+}, string>;
+export declare const tavilyTool: TavilySearchResults;

package/dist/types/tools/handlers.d.ts

@@ -0,0 +1,19 @@
+import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
+import type { Graph } from '@/graphs';
+import type * as t from '@/types';
+export declare function handleToolCallChunks({ graph, stepKey, toolCallChunks, }: {
+    graph: Graph;
+    stepKey: string;
+    toolCallChunks: ToolCallChunk[];
+}): void;
+export declare const handleToolCalls: (toolCalls?: ToolCall[], metadata?: Record<string, unknown>, graph?: Graph) => void;
+export declare const toolResultTypes: Set<string>;
+/**
+ * Handles the result of a server tool call; in other words, a provider's built-in tool.
+ * As of 2025-07-06, only Anthropic handles server tool calls with this pattern.
+ */
+export declare function handleServerToolResult({ content, metadata, graph, }: {
+    content?: string | t.MessageContentComplex[];
+    metadata?: Record<string, unknown>;
+    graph: Graph;
+}): boolean;

package/dist/types/tools/search/anthropic.d.ts

@@ -0,0 +1,16 @@
+import type { AnthropicTextBlockParam, AnthropicWebSearchResultBlockParam } from '@/llm/anthropic/types';
+import type { SearchResultData } from './types';
+/**
+ * Coerces Anthropic web search results to the SearchResultData format
+ * @param results - Array of Anthropic web search results
+ * @param turn - The turn number to associate with these results
+ * @returns SearchResultData with minimal ProcessedOrganic items
+ */
+export declare function coerceAnthropicSearchResults({ results, turn, }: {
+    results: (AnthropicTextBlockParam | AnthropicWebSearchResultBlockParam)[];
+    turn?: number;
+}): SearchResultData;
+/**
+ * Helper function to check if an object is an Anthropic web search result
+ */
+export declare function isAnthropicWebSearchResult(obj: unknown): obj is AnthropicWebSearchResultBlockParam;

package/dist/types/tools/search/content.d.ts

@@ -0,0 +1,4 @@
+import type { References } from './types';
+export declare function processContent(html: string, markdown: string): {
+    markdown: string;
+} & References;

package/dist/types/tools/search/firecrawl.d.ts

@@ -0,0 +1,54 @@
+import type * as t from './types';
+/**
+ * Firecrawl scraper implementation
+ * Uses the Firecrawl API to scrape web pages
+ */
+export declare class FirecrawlScraper implements t.BaseScraper {
+    private apiKey;
+    private apiUrl;
+    private version;
+    private defaultFormats;
+    private timeout;
+    private logger;
+    private includeTags?;
+    private excludeTags?;
+    private waitFor?;
+    private maxAge?;
+    private mobile?;
+    private skipTlsVerification?;
+    private blockAds?;
+    private removeBase64Images?;
+    private parsePDF?;
+    private storeInCache?;
+    private zeroDataRetention?;
+    private headers?;
+    private location?;
+    private onlyMainContent?;
+    private changeTrackingOptions?;
+    constructor(config?: t.FirecrawlScraperConfig);
+    /**
+     * Scrape a single URL
+     * @param url URL to scrape
+     * @param options Scrape options
+     * @returns Scrape response
+     */
+    scrapeUrl(url: string, options?: t.FirecrawlScrapeOptions): Promise<[string, t.FirecrawlScrapeResponse]>;
+    /**
+     * Extract content from scrape response
+     * @param response Scrape response
+     * @returns Extracted content or empty string if not available
+     */
+    extractContent(response: t.FirecrawlScrapeResponse): [string, undefined | t.References];
+    /**
+     * Extract metadata from scrape response
+     * @param response Scrape response
+     * @returns Metadata object
+     */
+    extractMetadata(response: t.FirecrawlScrapeResponse): t.ScrapeMetadata;
+}
+/**
+ * Create a Firecrawl scraper instance
+ * @param config Scraper configuration
+ * @returns Firecrawl scraper instance
+ */
+export declare const createFirecrawlScraper: (config?: t.FirecrawlScraperConfig) => FirecrawlScraper;

package/dist/types/tools/search/format.d.ts

@@ -0,0 +1,5 @@
+import type * as t from './types';
+export declare function formatResultsForLLM(turn: number, results: t.SearchResultData): {
+    output: string;
+    references: t.ResultReference[];
+};

package/dist/types/tools/search/highlights.d.ts

@@ -0,0 +1,13 @@
+import type * as t from './types';
+/**
+ * Expand highlights in search results using smart boundary detection.
+ *
+ * This implementation finds natural text boundaries like paragraphs, sentences,
+ * and phrases to provide context while maintaining readability.
+ *
+ * @param searchResults - Search results object
+ * @param mainExpandBy - Primary expansion size on each side (default: 300)
+ * @param separatorExpandBy - Additional range to look for separators (default: 150)
+ * @returns Copy of search results with expanded highlights and tracked references
+ */
+export declare function expandHighlights(searchResults: t.SearchResultData, mainExpandBy?: number, separatorExpandBy?: number): t.SearchResultData;

package/dist/types/tools/search/index.d.ts

@@ -0,0 +1,2 @@
+export * from './tool';
+export type * from './types';

package/dist/types/tools/search/rerankers.d.ts

@@ -0,0 +1,38 @@
+import type * as t from './types';
+export declare abstract class BaseReranker {
+    protected apiKey: string | undefined;
+    protected logger: t.Logger;
+    constructor(logger?: t.Logger);
+    abstract rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+    protected getDefaultRanking(documents: string[], topK: number): t.Highlight[];
+}
+export declare class JinaReranker extends BaseReranker {
+    private apiUrl;
+    constructor({ apiKey, apiUrl, logger, }: {
+        apiKey?: string;
+        apiUrl?: string;
+        logger?: t.Logger;
+    });
+    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+}
+export declare class CohereReranker extends BaseReranker {
+    constructor({ apiKey, logger, }: {
+        apiKey?: string;
+        logger?: t.Logger;
+    });
+    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+}
+export declare class InfinityReranker extends BaseReranker {
+    constructor(logger?: t.Logger);
+    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+}
+/**
+ * Creates the appropriate reranker based on type and configuration
+ */
+export declare const createReranker: (config: {
+    rerankerType: t.RerankerType;
+    jinaApiKey?: string;
+    jinaApiUrl?: string;
+    cohereApiKey?: string;
+    logger?: t.Logger;
+}) => BaseReranker | undefined;

package/dist/types/tools/search/schema.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare enum DATE_RANGE {
+    PAST_HOUR = "h",
+    PAST_24_HOURS = "d",
+    PAST_WEEK = "w",
+    PAST_MONTH = "m",
+    PAST_YEAR = "y"
+}
+export declare const DEFAULT_QUERY_DESCRIPTION: string;
+export declare const DEFAULT_COUNTRY_DESCRIPTION: string;
+export declare const querySchema: z.ZodString;
+export declare const dateSchema: z.ZodOptional<z.ZodNativeEnum<typeof DATE_RANGE>>;
+export declare const countrySchema: z.ZodOptional<z.ZodString>;
+export declare const imagesSchema: z.ZodOptional<z.ZodBoolean>;
+export declare const videosSchema: z.ZodOptional<z.ZodBoolean>;
+export declare const newsSchema: z.ZodOptional<z.ZodBoolean>;

package/dist/types/tools/search/search.d.ts

@@ -0,0 +1,8 @@
+import type * as t from './types';
+export declare const createSearchAPI: (config: t.SearchConfig) => {
+    getSources: (params: t.GetSourcesParams) => Promise<t.SearchResult>;
+};
+export declare const createSourceProcessor: (config?: t.ProcessSourcesConfig, scraperInstance?: t.BaseScraper) => {
+    processSources: (fields: t.ProcessSourcesFields) => Promise<t.SearchResultData>;
+    topResults: number;
+};

package/dist/types/tools/search/serper-scraper.d.ts

@@ -0,0 +1,59 @@
+import type * as t from './types';
+/**
+ * Serper scraper implementation
+ * Uses the Serper Scrape API (https://scrape.serper.dev) to scrape web pages
+ *
+ * Features:
+ * - Simple API with single endpoint
+ * - Returns both text and markdown content
+ * - Includes metadata from scraped pages
+ * - Credits-based pricing model
+ *
+ * @example
+ * ```typescript
+ * const scraper = createSerperScraper({
+ *   apiKey: 'your-serper-api-key',
+ *   includeMarkdown: true,
+ *   timeout: 10000
+ * });
+ *
+ * const [url, response] = await scraper.scrapeUrl('https://example.com');
+ * if (response.success) {
+ *   const [content] = scraper.extractContent(response);
+ *   console.log(content);
+ * }
+ * ```
+ */
+export declare class SerperScraper implements t.BaseScraper {
+    private apiKey;
+    private apiUrl;
+    private timeout;
+    private logger;
+    private includeMarkdown;
+    constructor(config?: t.SerperScraperConfig);
+    /**
+     * Scrape a single URL
+     * @param url URL to scrape
+     * @param options Scrape options
+     * @returns Scrape response
+     */
+    scrapeUrl(url: string, options?: t.SerperScrapeOptions): Promise<[string, t.SerperScrapeResponse]>;
+    /**
+     * Extract content from scrape response
+     * @param response Scrape response
+     * @returns Extracted content or empty string if not available
+     */
+    extractContent(response: t.SerperScrapeResponse): [string, undefined | t.References];
+    /**
+     * Extract metadata from scrape response
+     * @param response Scrape response
+     * @returns Metadata object
+     */
+    extractMetadata(response: t.SerperScrapeResponse): Record<string, string | number | boolean | null | undefined>;
+}
+/**
+ * Create a Serper scraper instance
+ * @param config Scraper configuration
+ * @returns Serper scraper instance
+ */
+export declare const createSerperScraper: (config?: t.SerperScraperConfig) => SerperScraper;

package/dist/types/tools/search/test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tools/search/tool.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from './types';
+import { DATE_RANGE } from './schema';
+/**
+ * Creates a search tool with a schema that dynamically includes the country field
+ * only when the searchProvider is 'serper'.
+ *
+ * Supports multiple scraper providers:
+ * - Firecrawl (default): Full-featured web scraping with multiple formats
+ * - Serper: Lightweight scraping using Serper's scrape API
+ *
+ * @example
+ * ```typescript
+ * // Using Firecrawl scraper (default)
+ * const searchTool = createSearchTool({
+ *   searchProvider: 'serper',
+ *   scraperProvider: 'firecrawl',
+ *   firecrawlApiKey: 'your-firecrawl-key'
+ * });
+ *
+ * // Using Serper scraper
+ * const searchTool = createSearchTool({
+ *   searchProvider: 'serper',
+ *   scraperProvider: 'serper',
+ *   serperApiKey: 'your-serper-key'
+ * });
+ * ```
+ *
+ * @param config - The search tool configuration
+ * @returns A DynamicStructuredTool with a schema that depends on the searchProvider
+ */
+export declare const createSearchTool: (config?: t.SearchToolConfig) => DynamicStructuredTool<z.ZodObject<{
+    query: z.ZodString;
+    date: z.ZodOptional<z.ZodNativeEnum<typeof DATE_RANGE>>;
+    country?: z.ZodOptional<z.ZodString>;
+    images: z.ZodOptional<z.ZodBoolean>;
+    videos: z.ZodOptional<z.ZodBoolean>;
+    news: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    date?: DATE_RANGE | undefined;
+    images?: boolean | undefined;
+    videos?: boolean | undefined;
+    news?: boolean | undefined;
+    country?: unknown;
+}, {
+    query: string;
+    date?: DATE_RANGE | undefined;
+    images?: boolean | undefined;
+    videos?: boolean | undefined;
+    news?: boolean | undefined;
+    country?: unknown;
+}>>;