@reverbia/sdk 1.0.0-next.20251119170952 → 1.0.0-next.20251121094738

package/dist/react/index.d.mts

@@ -0,0 +1,244 @@
+/**
+ * ExtraFields contains additional metadata
+ */
+type LlmapiChatCompletionExtraFields = {
+    /**
+     * Latency is the request latency in milliseconds
+     */
+    latency?: number;
+    /**
+     * ModelRequested is the model that was requested
+     */
+    model_requested?: string;
+    /**
+     * Provider is the LLM provider used (e.g., "openai", "anthropic")
+     */
+    provider?: string;
+    /**
+     * RequestType is always "chat_completion"
+     */
+    request_type?: string;
+};
+type LlmapiChatCompletionResponse = {
+    /**
+     * Choices contains the completion choices
+     */
+    choices?: Array<LlmapiChoice>;
+    extra_fields?: LlmapiChatCompletionExtraFields;
+    /**
+     * ID is the completion ID
+     */
+    id?: string;
+    /**
+     * Model is the model used
+     */
+    model?: string;
+    usage?: LlmapiChatCompletionUsage;
+};
+/**
+ * Usage contains token usage information
+ */
+type LlmapiChatCompletionUsage = {
+    /**
+     * CompletionTokens is the number of tokens in the completion
+     */
+    completion_tokens?: number;
+    /**
+     * PromptTokens is the number of tokens in the prompt
+     */
+    prompt_tokens?: number;
+    /**
+     * TotalTokens is the total number of tokens used
+     */
+    total_tokens?: number;
+};
+type LlmapiChoice = {
+    /**
+     * FinishReason indicates why the completion stopped
+     */
+    finish_reason?: string;
+    /**
+     * Index is the choice index
+     */
+    index?: number;
+    message?: LlmapiMessage;
+};
+/**
+ * Message is the generated message
+ */
+type LlmapiMessage = {
+    /**
+     * Content is the message content
+     */
+    content?: string;
+    role?: LlmapiRole;
+};
+/**
+ * Role is the message role (system, user, assistant)
+ */
+type LlmapiRole = string;
+
+type SendMessageArgs = {
+    messages: LlmapiMessage[];
+    model: string;
+};
+type SendMessageResult = {
+    data: LlmapiChatCompletionResponse;
+    error: null;
+} | {
+    data: null;
+    error: string;
+};
+type UseChatOptions = {
+    getToken?: () => Promise<string | null>;
+};
+type UseChatResult = {
+    isLoading: boolean;
+    sendMessage: (args: SendMessageArgs) => Promise<SendMessageResult>;
+};
+/**
+ * A React hook for managing chat completions with authentication.
+ *
+ * This hook provides a convenient way to send chat messages to the LLM API
+ * with automatic token management and loading state handling.
+ *
+ * @param options - Optional configuration object
+ * @param options.getToken - An async function that returns an authentication token.
+ *   This token will be used as a Bearer token in the Authorization header.
+ *   If not provided, `sendMessage` will return an error.
+ *
+ * @returns An object containing:
+ *   - `isLoading`: A boolean indicating whether a request is currently in progress
+ *   - `sendMessage`: An async function to send chat messages
+ *
+ * @example
+ * ```tsx
+ * const { isLoading, sendMessage } = useChat({
+ *   getToken: async () => {
+ *     // Get your auth token from your auth provider
+ *     return await getAuthToken();
+ *   }
+ * });
+ *
+ * const handleSend = async () => {
+ *   const result = await sendMessage({
+ *     messages: [{ role: 'user', content: 'Hello!' }],
+ *     model: 'gpt-4o-mini'
+ *   });
+ *
+ *   if (result.error) {
+ *     console.error(result.error);
+ *   } else {
+ *     console.log(result.data);
+ *   }
+ * };
+ * ```
+ */
+declare function useChat(options?: UseChatOptions): UseChatResult;
+
+interface MemoryItem {
+    type: "identity" | "preference" | "project" | "skill" | "constraint";
+    namespace: string;
+    key: string;
+    value: string;
+    rawEvidence: string;
+    confidence: number;
+    pii: boolean;
+}
+interface MemoryExtractionResult {
+    items: MemoryItem[];
+}
+
+/**
+ * Extended MemoryItem with database fields
+ */
+interface StoredMemoryItem extends MemoryItem {
+    id?: number;
+    createdAt: number;
+    updatedAt: number;
+    compositeKey: string;
+    uniqueKey: string;
+    embedding?: number[];
+    embeddingModel?: string;
+}
+
+type UseMemoryOptions = {
+    /**
+     * The model to use for fact extraction (default: "openai/gpt-4o")
+     */
+    memoryModel?: string;
+    /**
+     * The model to use for generating embeddings (default: "openai/text-embedding-3-small")
+     * Set to null/undefined to disable embedding generation
+     */
+    embeddingModel?: string | null;
+    /**
+     * Whether to automatically generate embeddings for extracted memories (default: true)
+     */
+    generateEmbeddings?: boolean;
+    /**
+     * Callback when facts are extracted
+     */
+    onFactsExtracted?: (facts: MemoryExtractionResult) => void;
+    /**
+     * Custom function to get auth token for API calls
+     */
+    getToken?: () => Promise<string | null>;
+};
+type UseMemoryResult = {
+    extractMemoriesFromMessage: (options: {
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+        model: string;
+    }) => Promise<MemoryExtractionResult | null>;
+    /**
+     * Search for similar memories using semantic search
+     * @param query The text query to search for
+     * @param limit Maximum number of results (default: 10)
+     * @param minSimilarity Minimum similarity threshold 0-1 (default: 0.6)
+     *   Note: Embedding similarity scores are typically lower than expected.
+     *   A score of 0.6-0.7 is usually a good match, 0.5-0.6 is moderate.
+     * @returns Array of memories with similarity scores, sorted by relevance
+     */
+    searchMemories: (query: string, limit?: number, minSimilarity?: number) => Promise<Array<StoredMemoryItem & {
+        similarity: number;
+    }>>;
+};
+/**
+ * Standalone hook for extracting memories from user messages.
+ * Can be composed with other hooks like useChat, useFiles, etc.
+ */
+declare function useMemory(options?: UseMemoryOptions): UseMemoryResult;
+
+/**
+ * Format memories into a context string that can be included in chat messages
+ * @param memories Array of memories with similarity scores
+ * @param format Format style: "compact" (key-value pairs) or "detailed" (includes evidence)
+ * @returns Formatted string ready to include in system/user message
+ */
+declare const formatMemoriesForChat: (memories: Array<StoredMemoryItem & {
+    similarity?: number;
+}>, format?: "compact" | "detailed") => string;
+/**
+ * Create a system message that includes relevant memories
+ * @param memories Array of memories to include
+ * @param baseSystemPrompt Optional base system prompt (memories will be prepended)
+ * @returns System message content with memories
+ */
+declare const createMemoryContextSystemMessage: (memories: Array<StoredMemoryItem & {
+    similarity?: number;
+}>, baseSystemPrompt?: string) => string;
+/**
+ * Extract conversation context from messages for memory search
+ * @param messages Array of chat messages
+ * @param maxMessages Maximum number of recent messages to include (default: 3)
+ * @returns Combined text query for memory search
+ */
+declare const extractConversationContext: (messages: Array<{
+    role: string;
+    content: string;
+}>, maxMessages?: number) => string;
+
+export { createMemoryContextSystemMessage, extractConversationContext, formatMemoriesForChat, useChat, useMemory };

package/dist/react/index.d.ts

@@ -0,0 +1,244 @@
+/**
+ * ExtraFields contains additional metadata
+ */
+type LlmapiChatCompletionExtraFields = {
+    /**
+     * Latency is the request latency in milliseconds
+     */
+    latency?: number;
+    /**
+     * ModelRequested is the model that was requested
+     */
+    model_requested?: string;
+    /**
+     * Provider is the LLM provider used (e.g., "openai", "anthropic")
+     */
+    provider?: string;
+    /**
+     * RequestType is always "chat_completion"
+     */
+    request_type?: string;
+};
+type LlmapiChatCompletionResponse = {
+    /**
+     * Choices contains the completion choices
+     */
+    choices?: Array<LlmapiChoice>;
+    extra_fields?: LlmapiChatCompletionExtraFields;
+    /**
+     * ID is the completion ID
+     */
+    id?: string;
+    /**
+     * Model is the model used
+     */
+    model?: string;
+    usage?: LlmapiChatCompletionUsage;
+};
+/**
+ * Usage contains token usage information
+ */
+type LlmapiChatCompletionUsage = {
+    /**
+     * CompletionTokens is the number of tokens in the completion
+     */
+    completion_tokens?: number;
+    /**
+     * PromptTokens is the number of tokens in the prompt
+     */
+    prompt_tokens?: number;
+    /**
+     * TotalTokens is the total number of tokens used
+     */
+    total_tokens?: number;
+};
+type LlmapiChoice = {
+    /**
+     * FinishReason indicates why the completion stopped
+     */
+    finish_reason?: string;
+    /**
+     * Index is the choice index
+     */
+    index?: number;
+    message?: LlmapiMessage;
+};
+/**
+ * Message is the generated message
+ */
+type LlmapiMessage = {
+    /**
+     * Content is the message content
+     */
+    content?: string;
+    role?: LlmapiRole;
+};
+/**
+ * Role is the message role (system, user, assistant)
+ */
+type LlmapiRole = string;
+
+type SendMessageArgs = {
+    messages: LlmapiMessage[];
+    model: string;
+};
+type SendMessageResult = {
+    data: LlmapiChatCompletionResponse;
+    error: null;
+} | {
+    data: null;
+    error: string;
+};
+type UseChatOptions = {
+    getToken?: () => Promise<string | null>;
+};
+type UseChatResult = {
+    isLoading: boolean;
+    sendMessage: (args: SendMessageArgs) => Promise<SendMessageResult>;
+};
+/**
+ * A React hook for managing chat completions with authentication.
+ *
+ * This hook provides a convenient way to send chat messages to the LLM API
+ * with automatic token management and loading state handling.
+ *
+ * @param options - Optional configuration object
+ * @param options.getToken - An async function that returns an authentication token.
+ *   This token will be used as a Bearer token in the Authorization header.
+ *   If not provided, `sendMessage` will return an error.
+ *
+ * @returns An object containing:
+ *   - `isLoading`: A boolean indicating whether a request is currently in progress
+ *   - `sendMessage`: An async function to send chat messages
+ *
+ * @example
+ * ```tsx
+ * const { isLoading, sendMessage } = useChat({
+ *   getToken: async () => {
+ *     // Get your auth token from your auth provider
+ *     return await getAuthToken();
+ *   }
+ * });
+ *
+ * const handleSend = async () => {
+ *   const result = await sendMessage({
+ *     messages: [{ role: 'user', content: 'Hello!' }],
+ *     model: 'gpt-4o-mini'
+ *   });
+ *
+ *   if (result.error) {
+ *     console.error(result.error);
+ *   } else {
+ *     console.log(result.data);
+ *   }
+ * };
+ * ```
+ */
+declare function useChat(options?: UseChatOptions): UseChatResult;
+
+interface MemoryItem {
+    type: "identity" | "preference" | "project" | "skill" | "constraint";
+    namespace: string;
+    key: string;
+    value: string;
+    rawEvidence: string;
+    confidence: number;
+    pii: boolean;
+}
+interface MemoryExtractionResult {
+    items: MemoryItem[];
+}
+
+/**
+ * Extended MemoryItem with database fields
+ */
+interface StoredMemoryItem extends MemoryItem {
+    id?: number;
+    createdAt: number;
+    updatedAt: number;
+    compositeKey: string;
+    uniqueKey: string;
+    embedding?: number[];
+    embeddingModel?: string;
+}
+
+type UseMemoryOptions = {
+    /**
+     * The model to use for fact extraction (default: "openai/gpt-4o")
+     */
+    memoryModel?: string;
+    /**
+     * The model to use for generating embeddings (default: "openai/text-embedding-3-small")
+     * Set to null/undefined to disable embedding generation
+     */
+    embeddingModel?: string | null;
+    /**
+     * Whether to automatically generate embeddings for extracted memories (default: true)
+     */
+    generateEmbeddings?: boolean;
+    /**
+     * Callback when facts are extracted
+     */
+    onFactsExtracted?: (facts: MemoryExtractionResult) => void;
+    /**
+     * Custom function to get auth token for API calls
+     */
+    getToken?: () => Promise<string | null>;
+};
+type UseMemoryResult = {
+    extractMemoriesFromMessage: (options: {
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+        model: string;
+    }) => Promise<MemoryExtractionResult | null>;
+    /**
+     * Search for similar memories using semantic search
+     * @param query The text query to search for
+     * @param limit Maximum number of results (default: 10)
+     * @param minSimilarity Minimum similarity threshold 0-1 (default: 0.6)
+     *   Note: Embedding similarity scores are typically lower than expected.
+     *   A score of 0.6-0.7 is usually a good match, 0.5-0.6 is moderate.
+     * @returns Array of memories with similarity scores, sorted by relevance
+     */
+    searchMemories: (query: string, limit?: number, minSimilarity?: number) => Promise<Array<StoredMemoryItem & {
+        similarity: number;
+    }>>;
+};
+/**
+ * Standalone hook for extracting memories from user messages.
+ * Can be composed with other hooks like useChat, useFiles, etc.
+ */
+declare function useMemory(options?: UseMemoryOptions): UseMemoryResult;
+
+/**
+ * Format memories into a context string that can be included in chat messages
+ * @param memories Array of memories with similarity scores
+ * @param format Format style: "compact" (key-value pairs) or "detailed" (includes evidence)
+ * @returns Formatted string ready to include in system/user message
+ */
+declare const formatMemoriesForChat: (memories: Array<StoredMemoryItem & {
+    similarity?: number;
+}>, format?: "compact" | "detailed") => string;
+/**
+ * Create a system message that includes relevant memories
+ * @param memories Array of memories to include
+ * @param baseSystemPrompt Optional base system prompt (memories will be prepended)
+ * @returns System message content with memories
+ */
+declare const createMemoryContextSystemMessage: (memories: Array<StoredMemoryItem & {
+    similarity?: number;
+}>, baseSystemPrompt?: string) => string;
+/**
+ * Extract conversation context from messages for memory search
+ * @param messages Array of chat messages
+ * @param maxMessages Maximum number of recent messages to include (default: 3)
+ * @returns Combined text query for memory search
+ */
+declare const extractConversationContext: (messages: Array<{
+    role: string;
+    content: string;
+}>, maxMessages?: number) => string;
+
+export { createMemoryContextSystemMessage, extractConversationContext, formatMemoriesForChat, useChat, useMemory };