graphlit-client 1.0.20250531005 → 1.0.20250610001

package/dist/model-mapping.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Get the actual model name for a given specification
+ * @param specification - The Graphlit specification object
+ * @returns The SDK-compatible model name
+ */
+export declare function getModelName(specification: any): string | undefined;
+/**
+ * Check if a service type supports streaming
+ * @param serviceType - The model service type
+ * @returns True if streaming is supported
+ */
+export declare function isStreamingSupported(serviceType?: string): boolean;
+/**
+ * Get the service type from specification
+ * @param specification - The specification object
+ * @returns The service type string
+ */
+export declare function getServiceType(specification: any): string | undefined;

package/dist/model-mapping.js

@@ -0,0 +1,95 @@
+import * as Types from "./generated/graphql-types.js";
+/**
+ * Model mapping utilities to convert Graphlit specification enums
+ * to actual model names used by LLM SDKs
+ */
+// OpenAI model mappings
+const OPENAI_MODEL_MAP = {
+    [Types.OpenAiModels.Gpt4]: "gpt-4",
+    [Types.OpenAiModels.Gpt4Turbo_128K]: "gpt-4-turbo",
+    [Types.OpenAiModels.Gpt4O_128K]: "gpt-4o",
+    [Types.OpenAiModels.Gpt4OMini_128K]: "gpt-4o-mini",
+    [Types.OpenAiModels.Gpt4OChat_128K]: "chatgpt-4o-latest",
+    [Types.OpenAiModels.Gpt35Turbo]: "gpt-3.5-turbo",
+    [Types.OpenAiModels.Gpt35Turbo_16K]: "gpt-3.5-turbo-16k",
+    [Types.OpenAiModels.Gpt41_1024K]: "gpt-4.1",
+    [Types.OpenAiModels.Gpt41Mini_1024K]: "gpt-4.1-mini",
+    [Types.OpenAiModels.Gpt41Nano_1024K]: "gpt-4.1-nano",
+    [Types.OpenAiModels.O3Mini_200K]: "o3-mini",
+    [Types.OpenAiModels.O3_200K]: "o3",
+    [Types.OpenAiModels.O4Mini_200K]: "o4-mini",
+};
+// Anthropic model mappings
+const ANTHROPIC_MODEL_MAP = {
+    [Types.AnthropicModels.Claude_3Opus]: "claude-3-opus-20240229",
+    [Types.AnthropicModels.Claude_3Sonnet]: "claude-3-sonnet-20240229",
+    [Types.AnthropicModels.Claude_3Haiku]: "claude-3-haiku-20240307",
+    [Types.AnthropicModels.Claude_3_5Sonnet]: "claude-3-5-sonnet-20241022",
+    [Types.AnthropicModels.Claude_3_5Haiku]: "claude-3-5-haiku-20241022",
+    [Types.AnthropicModels.Claude_3_7Sonnet]: "claude-3-7-sonnet-20250219",
+    [Types.AnthropicModels.Claude_4Opus]: "claude-4-opus-20250514",
+    [Types.AnthropicModels.Claude_4Sonnet]: "claude-4-sonnet-20250514",
+};
+// Google model mappings
+const GOOGLE_MODEL_MAP = {
+    [Types.GoogleModels.Gemini_1_5Pro]: "gemini-1.5-pro",
+    [Types.GoogleModels.Gemini_1_5Flash]: "gemini-1.5-flash",
+    [Types.GoogleModels.Gemini_1_5Flash_8B]: "gemini-1.5-flash-8b",
+    [Types.GoogleModels.Gemini_2_0Flash]: "gemini-2.0-flash-exp",
+    [Types.GoogleModels.Gemini_2_0FlashExperimental]: "gemini-2.0-flash-exp",
+    [Types.GoogleModels.Gemini_2_5FlashPreview]: "gemini-2.5-flash-preview-05-20",
+    [Types.GoogleModels.Gemini_2_5ProPreview]: "gemini-2.5-pro-preview-06-05",
+};
+/**
+ * Get the actual model name for a given specification
+ * @param specification - The Graphlit specification object
+ * @returns The SDK-compatible model name
+ */
+export function getModelName(specification) {
+    const serviceType = specification?.serviceType;
+    // Check for custom model names first
+    if (specification?.openAI?.modelName) {
+        return specification.openAI.modelName;
+    }
+    if (specification?.anthropic?.modelName) {
+        return specification.anthropic.modelName;
+    }
+    if (specification?.google?.modelName) {
+        return specification.google.modelName;
+    }
+    // Map based on service type and model enum
+    switch (serviceType) {
+        case Types.ModelServiceTypes.OpenAi:
+            const openAIModel = specification?.openAI?.model;
+            return openAIModel ? OPENAI_MODEL_MAP[openAIModel] : undefined;
+        case Types.ModelServiceTypes.Anthropic:
+            const anthropicModel = specification?.anthropic?.model;
+            return anthropicModel ? ANTHROPIC_MODEL_MAP[anthropicModel] : undefined;
+        case Types.ModelServiceTypes.Google:
+            const googleModel = specification?.google?.model;
+            return googleModel ? GOOGLE_MODEL_MAP[googleModel] : undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Check if a service type supports streaming
+ * @param serviceType - The model service type
+ * @returns True if streaming is supported
+ */
+export function isStreamingSupported(serviceType) {
+    const streamingServices = [
+        Types.ModelServiceTypes.OpenAi,
+        Types.ModelServiceTypes.Anthropic,
+        Types.ModelServiceTypes.Google,
+    ];
+    return streamingServices.includes(serviceType);
+}
+/**
+ * Get the service type from specification
+ * @param specification - The specification object
+ * @returns The service type string
+ */
+export function getServiceType(specification) {
+    return specification?.serviceType;
+}

package/dist/stream-helpers.d.ts

@@ -0,0 +1,106 @@
+import { StreamEvent } from "./client.js";
+import { ConversationRoleTypes } from "./generated/graphql-types.js";
+export declare class StreamEventAggregator {
+    private conversationId;
+    private messageBuffer;
+    private toolCallsBuffer;
+    private isFirstAssistantMessage;
+    private hasReceivedToolCalls;
+    private tokenBuffer;
+    /**
+     * Process a stream event and return any complete messages ready for the UI
+     */
+    processEvent(event: StreamEvent): AggregatedEvent | null;
+    /**
+     * Reset the aggregator for a new conversation
+     */
+    reset(): void;
+    /**
+     * Get current state (useful for debugging)
+     */
+    getState(): {
+        conversationId: string;
+        messageBuffer: string;
+        toolCallsCount: number;
+        hasReceivedToolCalls: boolean;
+        isFirstAssistantMessage: boolean;
+        tokenCount: number;
+    };
+}
+/**
+ * Aggregated event types that are ready for UI consumption
+ */
+export type AggregatedEvent = {
+    type: "conversationStarted";
+    conversationId: string;
+} | {
+    type: "token";
+    token: string;
+    accumulated: string;
+} | {
+    type: "assistantMessage";
+    message: {
+        message?: string | null;
+        role?: ConversationRoleTypes | null;
+        toolCalls?: any[];
+    };
+    isFinal: boolean;
+    conversationId?: string;
+} | {
+    type: "streamComplete";
+    conversationId?: string;
+} | {
+    type: "error";
+    error: string;
+};
+/**
+ * Helper to create an SSE response with proper formatting
+ */
+export declare function formatSSEEvent(data: any, eventName?: string): string;
+/**
+ * Helper to create a TransformStream for SSE with built-in ping support
+ */
+export declare function createSSEStream(options?: {
+    pingInterval?: number;
+}): {
+    readable: ReadableStream<any>;
+    sendEvent: (data: any, eventName?: string) => Promise<void>;
+    close: () => Promise<void>;
+    writer: WritableStreamDefaultWriter<any>;
+};
+/**
+ * Helper to wrap tool handlers with result emission
+ */
+export interface ToolResultEmitter {
+    (toolCallId: string, result: any, status: "complete" | "error" | "blocked", duration: number): void;
+}
+export declare function wrapToolHandlers(handlers: Record<string, (args: any) => Promise<any>>, emitResult: ToolResultEmitter): Record<string, (args: any) => Promise<any>>;
+/**
+ * Helper to enhance tool calls with server information
+ */
+export interface ServerMapping {
+    toolName: string;
+    serverName: string;
+    serverId: string;
+}
+export declare function enhanceToolCalls(toolCalls: any[], serverMappings: ServerMapping[]): any[];
+/**
+ * Helper to track conversation metrics
+ */
+export declare class ConversationMetrics {
+    private startTime;
+    private tokenCount;
+    private toolCallCount;
+    private errorCount;
+    recordToken(): void;
+    recordToolCall(): void;
+    recordError(): void;
+    getMetrics(): {
+        duration: number;
+        tokenCount: number;
+        toolCallCount: number;
+        errorCount: number;
+        tokensPerSecond: number;
+    };
+    reset(): void;
+}

package/dist/stream-helpers.js

@@ -0,0 +1,237 @@
+import { ConversationRoleTypes, } from "./generated/graphql-types.js";
+export class StreamEventAggregator {
+    conversationId = "";
+    messageBuffer = "";
+    toolCallsBuffer = new Map();
+    isFirstAssistantMessage = true;
+    hasReceivedToolCalls = false;
+    tokenBuffer = [];
+    /**
+     * Process a stream event and return any complete messages ready for the UI
+     */
+    processEvent(event) {
+        switch (event.type) {
+            case "start":
+                this.conversationId = event.conversationId;
+                return {
+                    type: "conversationStarted",
+                    conversationId: event.conversationId,
+                };
+            case "token":
+                this.messageBuffer += event.token;
+                this.tokenBuffer.push(event.token);
+                return {
+                    type: "token",
+                    token: event.token,
+                    accumulated: this.messageBuffer,
+                };
+            case "message":
+                // SDK provides accumulated message - we can use this instead of our buffer
+                this.messageBuffer = event.message;
+                return null; // Don't emit, wait for complete event
+            case "tool_call_start":
+                this.hasReceivedToolCalls = true;
+                this.toolCallsBuffer.set(event.toolCall.id, {
+                    id: event.toolCall.id,
+                    name: event.toolCall.name,
+                    argumentsBuffer: "",
+                    isComplete: false,
+                    startTime: Date.now(),
+                });
+                return null; // Buffer until complete
+            case "tool_call_delta":
+                const toolCall = this.toolCallsBuffer.get(event.toolCallId);
+                if (toolCall) {
+                    toolCall.argumentsBuffer += event.argumentDelta;
+                }
+                return null; // Buffer until complete
+            case "tool_call_complete":
+                const completeToolCall = this.toolCallsBuffer.get(event.toolCall.id);
+                if (completeToolCall) {
+                    completeToolCall.argumentsBuffer = event.toolCall.arguments;
+                    completeToolCall.isComplete = true;
+                }
+                // Check if all tool calls are complete
+                const allComplete = Array.from(this.toolCallsBuffer.values()).every((tc) => tc.isComplete);
+                if (allComplete &&
+                    this.hasReceivedToolCalls &&
+                    this.isFirstAssistantMessage) {
+                    // Emit complete assistant message with all tool calls
+                    const toolCalls = Array.from(this.toolCallsBuffer.values()).map((tc) => ({
+                        id: tc.id,
+                        name: tc.name,
+                        arguments: tc.argumentsBuffer,
+                        status: "pending",
+                    }));
+                    this.isFirstAssistantMessage = false;
+                    return {
+                        type: "assistantMessage",
+                        message: {
+                            message: this.messageBuffer,
+                            role: ConversationRoleTypes.Assistant,
+                            toolCalls,
+                        },
+                        isFinal: false,
+                    };
+                }
+                return null;
+            case "complete":
+                // If we haven't sent a message yet (no tool calls), send it now
+                if (this.isFirstAssistantMessage && !this.hasReceivedToolCalls) {
+                    return {
+                        type: "assistantMessage",
+                        message: {
+                            message: this.messageBuffer,
+                            role: ConversationRoleTypes.Assistant,
+                        },
+                        isFinal: true,
+                        conversationId: event.conversationId,
+                    };
+                }
+                return { type: "streamComplete", conversationId: event.conversationId };
+            case "error":
+                return { type: "error", error: event.error };
+            default:
+                return null;
+        }
+    }
+    /**
+     * Reset the aggregator for a new conversation
+     */
+    reset() {
+        this.conversationId = "";
+        this.messageBuffer = "";
+        this.toolCallsBuffer.clear();
+        this.isFirstAssistantMessage = true;
+        this.hasReceivedToolCalls = false;
+        this.tokenBuffer = [];
+    }
+    /**
+     * Get current state (useful for debugging)
+     */
+    getState() {
+        return {
+            conversationId: this.conversationId,
+            messageBuffer: this.messageBuffer,
+            toolCallsCount: this.toolCallsBuffer.size,
+            hasReceivedToolCalls: this.hasReceivedToolCalls,
+            isFirstAssistantMessage: this.isFirstAssistantMessage,
+            tokenCount: this.tokenBuffer.length,
+        };
+    }
+}
+/**
+ * Helper to create an SSE response with proper formatting
+ */
+export function formatSSEEvent(data, eventName = "message") {
+    if (typeof data === "string") {
+        return `event: ${eventName}\ndata: ${data}\n\n`;
+    }
+    return `event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+/**
+ * Helper to create a TransformStream for SSE with built-in ping support
+ */
+export function createSSEStream(options) {
+    const encoder = new TextEncoder();
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    let pingInterval = null;
+    if (options?.pingInterval) {
+        pingInterval = globalThis.setInterval(() => {
+            writer.write(encoder.encode(":\n\n")).catch(() => {
+                // Ignore errors on ping
+            });
+        }, options.pingInterval);
+    }
+    const sendEvent = (data, eventName = "message") => {
+        const formatted = formatSSEEvent(data, eventName);
+        return writer.write(encoder.encode(formatted));
+    };
+    const close = async () => {
+        if (pingInterval) {
+            globalThis.clearInterval(pingInterval);
+        }
+        await writer.close();
+    };
+    return {
+        readable,
+        sendEvent,
+        close,
+        writer,
+    };
+}
+export function wrapToolHandlers(handlers, emitResult) {
+    const wrapped = {};
+    Object.entries(handlers).forEach(([name, handler]) => {
+        wrapped[name] = async (args) => {
+            const toolCallId = `tool_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            const startTime = Date.now();
+            try {
+                const result = await handler(args);
+                const duration = Date.now() - startTime;
+                // Emit success result
+                emitResult(toolCallId, { status: "success", result }, "complete", duration);
+                return result;
+            }
+            catch (error) {
+                const duration = Date.now() - startTime;
+                // Emit error result
+                emitResult(toolCallId, {
+                    status: "error",
+                    error: error instanceof Error ? error.message : String(error),
+                }, "error", duration);
+                throw error;
+            }
+        };
+    });
+    return wrapped;
+}
+export function enhanceToolCalls(toolCalls, serverMappings) {
+    const mappingDict = serverMappings.reduce((acc, mapping) => {
+        acc[mapping.toolName] = {
+            serverName: mapping.serverName,
+            serverId: mapping.serverId,
+        };
+        return acc;
+    }, {});
+    return toolCalls.map((toolCall) => ({
+        ...toolCall,
+        serverName: mappingDict[toolCall.name]?.serverName,
+        serverId: mappingDict[toolCall.name]?.serverId,
+    }));
+}
+/**
+ * Helper to track conversation metrics
+ */
+export class ConversationMetrics {
+    startTime = Date.now();
+    tokenCount = 0;
+    toolCallCount = 0;
+    errorCount = 0;
+    recordToken() {
+        this.tokenCount++;
+    }
+    recordToolCall() {
+        this.toolCallCount++;
+    }
+    recordError() {
+        this.errorCount++;
+    }
+    getMetrics() {
+        const duration = Date.now() - this.startTime;
+        return {
+            duration,
+            tokenCount: this.tokenCount,
+            toolCallCount: this.toolCallCount,
+            errorCount: this.errorCount,
+            tokensPerSecond: this.tokenCount / (duration / 1000),
+        };
+    }
+    reset() {
+        this.startTime = Date.now();
+        this.tokenCount = 0;
+        this.toolCallCount = 0;
+        this.errorCount = 0;
+    }
+}

package/dist/streaming/chunk-buffer.d.ts

@@ -0,0 +1,25 @@
+export type ChunkingStrategy = "character" | "word" | "sentence" | ((text: string) => {
+    chunks: string[];
+    remainder: string;
+});
+export declare class ChunkBuffer {
+    private buffer;
+    private static readonly MAX_WORD_LEN;
+    private static readonly MAX_BUFFER_NO_BREAK;
+    private readonly graphemeSeg;
+    private readonly wordSeg;
+    private readonly sentenceSeg;
+    private readonly customChunker?;
+    private readonly strategy;
+    constructor(strategy: ChunkingStrategy);
+    /** Feed one LLM token, receive zero-or-more flushed chunks. */
+    addToken(token: string): string[];
+    /** Flush whatever is left in the buffer when the stream finishes. */
+    flush(): string[];
+    private flushGraphemes;
+    private flushWords;
+    private flushSentences;
+    /** Fallback guard to break up very long runs of text with no natural breaks. */
+    private flushLongRuns;
+    private flushCustom;
+}

package/dist/streaming/chunk-buffer.js

@@ -0,0 +1,170 @@
+export class ChunkBuffer {
+    buffer = "";
+    // ----- Configurable Guards -----
+    static MAX_WORD_LEN = 50; // Breaks up extremely long "words" (e.g., URLs, code).
+    static MAX_BUFFER_NO_BREAK = 400; // Hard limit for any run without a natural break.
+    // --------------------------------
+    graphemeSeg;
+    wordSeg;
+    sentenceSeg;
+    customChunker;
+    strategy;
+    constructor(strategy) {
+        if (typeof strategy === "function") {
+            this.customChunker = strategy;
+            this.strategy = "custom";
+        }
+        else {
+            this.strategy = strategy;
+        }
+        this.graphemeSeg = new Intl.Segmenter(undefined, {
+            granularity: "grapheme",
+        });
+        this.wordSeg = new Intl.Segmenter(undefined, { granularity: "word" });
+        this.sentenceSeg = new Intl.Segmenter(undefined, {
+            granularity: "sentence",
+        });
+    }
+    /** Feed one LLM token, receive zero-or-more flushed chunks. */
+    addToken(token) {
+        this.buffer += token;
+        if (this.customChunker) {
+            return this.flushCustom();
+        }
+        // Pre-emptively flush any overly long runs of text that haven't found a natural break.
+        const longRunChunks = this.flushLongRuns();
+        let newChunks = [];
+        switch (this.strategy) {
+            case "character":
+                newChunks = this.flushGraphemes();
+                break;
+            case "word":
+                newChunks = this.flushWords();
+                break;
+            case "sentence":
+                newChunks = this.flushSentences();
+                break;
+        }
+        return [...longRunChunks, ...newChunks];
+    }
+    /** Flush whatever is left in the buffer when the stream finishes. */
+    flush() {
+        if (!this.buffer)
+            return [];
+        let finalChunks = [];
+        if (this.customChunker) {
+            // For custom chunkers, flush everything by treating the whole buffer as input.
+            const { chunks, remainder } = this.customChunker(this.buffer);
+            finalChunks.push(...chunks);
+            if (remainder) {
+                finalChunks.push(remainder);
+            }
+        }
+        else {
+            // For built-in strategies, the remaining buffer is the final chunk.
+            finalChunks.push(this.buffer);
+        }
+        this.buffer = "";
+        // Ensure no empty strings are returned.
+        return finalChunks.filter((c) => c.length > 0);
+    }
+    // ────────────────────────────────────────────────────────────────
+    //  Internals
+    // ────────────────────────────────────────────────────────────────
+    flushGraphemes() {
+        const segments = Array.from(this.graphemeSeg.segment(this.buffer)).map((s) => s.segment);
+        // If there's only one segment, it might be incomplete. Wait for more.
+        if (segments.length <= 1) {
+            return [];
+        }
+        // Flush all but the last segment, which becomes the new buffer.
+        const chunksToFlush = segments.slice(0, -1);
+        this.buffer = segments[segments.length - 1];
+        return chunksToFlush;
+    }
+    flushWords() {
+        const chunks = [];
+        let currentWord = ""; // Accumulates the word part (e.g., "quick")
+        let currentNonWord = ""; // Accumulates trailing spaces/punctuation (e.g., " ")
+        // Iterate through all segments of the current buffer.
+        const segments = Array.from(this.wordSeg.segment(this.buffer));
+        // Process segments to form "word + non-word" chunks.
+        for (let i = 0; i < segments.length; i++) {
+            const part = segments[i];
+            if (part.isWordLike) {
+                // If we just finished a word and accumulated non-word characters,
+                // it means the previous "word + non-word" chunk is complete.
+                if (currentWord.length > 0 && currentNonWord.length > 0) {
+                    chunks.push(currentWord + currentNonWord);
+                    currentWord = "";
+                    currentNonWord = "";
+                }
+                currentWord += part.segment;
+            }
+            else {
+                // This is a non-word segment (space, punctuation).
+                currentNonWord += part.segment;
+            }
+            // Guard against extremely long words (e.g., a URL) that don't have natural breaks.
+            // This flushes the accumulated word part even if it's not followed by a non-word yet.
+            if (currentWord.length > ChunkBuffer.MAX_WORD_LEN) {
+                chunks.push(currentWord + currentNonWord);
+                currentWord = "";
+                currentNonWord = "";
+            }
+        }
+        // After the loop, whatever remains in currentWord and currentNonWord
+        // is the incomplete part of the stream. This becomes the new buffer.
+        this.buffer = currentWord + currentNonWord;
+        // Filter out any empty strings that might result from edge cases.
+        return chunks.filter((c) => c.length > 0);
+    }
+    flushSentences() {
+        // This hybrid approach is more robust for sentence-ending punctuation.
+        // 1. Use a regex to find the last definitive sentence boundary.
+        // This is more reliable than Intl.Segmenter alone for partial streams.
+        const sentenceBoundaryRegex = /.*?[.?!](\s+|$)/g;
+        let lastMatchIndex = -1;
+        let match;
+        while ((match = sentenceBoundaryRegex.exec(this.buffer)) !== null) {
+            lastMatchIndex = match.index + match[0].length;
+        }
+        if (lastMatchIndex === -1) {
+            // No definitive sentence boundary found yet.
+            return [];
+        }
+        // 2. The text to be flushed is everything up to that boundary.
+        const textToFlush = this.buffer.substring(0, lastMatchIndex);
+        this.buffer = this.buffer.substring(lastMatchIndex);
+        // 3. Now, use Intl.Segmenter on the confirmed text to correctly split it.
+        // This handles cases where `textToFlush` contains multiple sentences.
+        return Array.from(this.sentenceSeg.segment(textToFlush))
+            .map((s) => s.segment)
+            .filter((c) => c.length > 0);
+    }
+    /** Fallback guard to break up very long runs of text with no natural breaks. */
+    flushLongRuns() {
+        const chunks = [];
+        // If the buffer is very long and contains no spaces (e.g., a single long word/URL),
+        // force a break to prevent excessive buffering.
+        if (this.buffer.length > ChunkBuffer.MAX_BUFFER_NO_BREAK &&
+            !/\s/.test(this.buffer)) {
+            chunks.push(this.buffer.slice(0, ChunkBuffer.MAX_BUFFER_NO_BREAK));
+            this.buffer = this.buffer.slice(ChunkBuffer.MAX_BUFFER_NO_BREAK);
+        }
+        return chunks;
+    }
+    flushCustom() {
+        try {
+            const { chunks, remainder } = this.customChunker(this.buffer);
+            this.buffer = remainder;
+            return chunks;
+        }
+        catch (err) {
+            console.error("Custom chunker failed. Flushing entire buffer to avoid data loss.", err);
+            const all = this.buffer;
+            this.buffer = "";
+            return [all];
+        }
+    }
+}