openrag-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,516 @@
+/**
+ * OpenRAG SDK types.
+ */
+interface Source {
+    filename: string;
+    text: string;
+    score: number;
+    page?: number | null;
+    mimetype?: string | null;
+}
+interface ChatResponse {
+    response: string;
+    chatId?: string | null;
+    sources: Source[];
+}
+interface ContentEvent {
+    type: "content";
+    delta: string;
+}
+interface SourcesEvent {
+    type: "sources";
+    sources: Source[];
+}
+interface DoneEvent {
+    type: "done";
+    chatId?: string | null;
+}
+type StreamEvent = ContentEvent | SourcesEvent | DoneEvent;
+interface SearchResult {
+    filename: string;
+    text: string;
+    score: number;
+    page?: number | null;
+    mimetype?: string | null;
+}
+interface SearchResponse {
+    results: SearchResult[];
+}
+interface SearchFilters {
+    data_sources?: string[];
+    document_types?: string[];
+}
+interface IngestResponse {
+    task_id: string;
+    status?: string | null;
+    filename?: string | null;
+}
+interface IngestTaskStatus {
+    task_id: string;
+    status: string;
+    total_files: number;
+    processed_files: number;
+    successful_files: number;
+    failed_files: number;
+    files: Record<string, unknown>;
+}
+interface DeleteDocumentResponse {
+    success: boolean;
+    deleted_chunks: number;
+}
+interface Message {
+    role: string;
+    content: string;
+    timestamp?: string | null;
+}
+interface Conversation {
+    chatId: string;
+    title: string;
+    createdAt?: string | null;
+    lastActivity?: string | null;
+    messageCount: number;
+}
+interface ConversationDetail extends Conversation {
+    messages: Message[];
+}
+interface ConversationListResponse {
+    conversations: Conversation[];
+}
+interface AgentSettings {
+    llm_provider?: string | null;
+    llm_model?: string | null;
+}
+interface KnowledgeSettings {
+    embedding_provider?: string | null;
+    embedding_model?: string | null;
+    chunk_size?: number | null;
+    chunk_overlap?: number | null;
+}
+interface SettingsResponse {
+    agent: AgentSettings;
+    knowledge: KnowledgeSettings;
+}
+/** Options for updating settings. */
+interface SettingsUpdateOptions {
+    /** LLM model name. */
+    llm_model?: string;
+    /** LLM provider (openai, anthropic, watsonx, ollama). */
+    llm_provider?: string;
+    /** System prompt for the agent. */
+    system_prompt?: string;
+    /** Embedding model name. */
+    embedding_model?: string;
+    /** Embedding provider (openai, watsonx, ollama). */
+    embedding_provider?: string;
+    /** Chunk size for document splitting. */
+    chunk_size?: number;
+    /** Chunk overlap for document splitting. */
+    chunk_overlap?: number;
+    /** Enable table structure parsing. */
+    table_structure?: boolean;
+    /** Enable OCR for text extraction. */
+    ocr?: boolean;
+    /** Enable picture descriptions. */
+    picture_descriptions?: boolean;
+}
+/** Response from settings update. */
+interface SettingsUpdateResponse {
+    message: string;
+}
+/** Query configuration stored in a knowledge filter. */
+interface KnowledgeFilterQueryData {
+    /** Semantic search query text. */
+    query?: string;
+    /** Filter criteria for documents. */
+    filters?: {
+        data_sources?: string[];
+        document_types?: string[];
+        owners?: string[];
+        connector_types?: string[];
+    };
+    /** Maximum number of results. */
+    limit?: number;
+    /** Minimum relevance score threshold. */
+    scoreThreshold?: number;
+    /** UI color for the filter. */
+    color?: string;
+    /** UI icon for the filter. */
+    icon?: string;
+}
+/** A knowledge filter definition. */
+interface KnowledgeFilter {
+    id: string;
+    name: string;
+    description?: string;
+    queryData: KnowledgeFilterQueryData;
+    owner?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** Options for creating a knowledge filter. */
+interface CreateKnowledgeFilterOptions {
+    /** Filter name (required). */
+    name: string;
+    /** Filter description. */
+    description?: string;
+    /** Query configuration for the filter. */
+    queryData: KnowledgeFilterQueryData;
+}
+/** Options for updating a knowledge filter. */
+interface UpdateKnowledgeFilterOptions {
+    /** New filter name. */
+    name?: string;
+    /** New filter description. */
+    description?: string;
+    /** New query configuration. */
+    queryData?: KnowledgeFilterQueryData;
+}
+/** Response from creating a knowledge filter. */
+interface CreateKnowledgeFilterResponse {
+    success: boolean;
+    id?: string;
+    error?: string;
+}
+/** Response from searching knowledge filters. */
+interface KnowledgeFilterSearchResponse {
+    success: boolean;
+    filters: KnowledgeFilter[];
+}
+/** Response from getting a knowledge filter. */
+interface GetKnowledgeFilterResponse {
+    success: boolean;
+    filter?: KnowledgeFilter;
+    error?: string;
+}
+/** Response from deleting a knowledge filter. */
+interface DeleteKnowledgeFilterResponse {
+    success: boolean;
+    error?: string;
+}
+interface OpenRAGClientOptions {
+    /** API key for authentication. Falls back to OPENRAG_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for the API. Falls back to OPENRAG_URL env var. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default 30000). */
+    timeout?: number;
+}
+interface ChatCreateOptions {
+    message: string;
+    stream?: boolean;
+    chatId?: string;
+    filters?: SearchFilters;
+    limit?: number;
+    scoreThreshold?: number;
+    /** Knowledge filter ID to apply to the chat. */
+    filterId?: string;
+}
+interface SearchQueryOptions {
+    query: string;
+    filters?: SearchFilters;
+    limit?: number;
+    scoreThreshold?: number;
+    /** Knowledge filter ID to apply to the search. */
+    filterId?: string;
+}
+declare class OpenRAGError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+declare class AuthenticationError extends OpenRAGError {
+    constructor(message: string, statusCode?: number);
+}
+declare class NotFoundError extends OpenRAGError {
+    constructor(message: string, statusCode?: number);
+}
+declare class ValidationError extends OpenRAGError {
+    constructor(message: string, statusCode?: number);
+}
+declare class RateLimitError extends OpenRAGError {
+    constructor(message: string, statusCode?: number);
+}
+declare class ServerError extends OpenRAGError {
+    constructor(message: string, statusCode?: number);
+}
+
+/**
+ * OpenRAG SDK chat client with streaming support.
+ */
+
+/**
+ * Streaming chat response with helpers.
+ *
+ * Usage:
+ * ```typescript
+ * using stream = await client.chat.stream({ message: "Hello" });
+ * for await (const event of stream) {
+ *   if (event.type === "content") console.log(event.delta);
+ * }
+ * console.log(stream.chatId);
+ * console.log(stream.text);
+ * ```
+ */
+declare class ChatStream implements AsyncIterable<StreamEvent>, Disposable {
+    private client;
+    private options;
+    private _text;
+    private _chatId;
+    private _sources;
+    private _consumed;
+    private _reader;
+    private _response;
+    constructor(client: OpenRAGClient, options: ChatCreateOptions);
+    /** The accumulated text from content events. */
+    get text(): string;
+    /** The chat ID for continuing the conversation. */
+    get chatId(): string | null;
+    /** The sources retrieved during the conversation. */
+    get sources(): Source[];
+    /** @internal Initialize the stream. */
+    _init(): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
+    /**
+     * Iterate over just the text deltas.
+     */
+    get textStream(): AsyncIterable<string>;
+    /**
+     * Consume the stream and return the complete text.
+     */
+    finalText(): Promise<string>;
+    /** Clean up resources. */
+    [Symbol.dispose](): void;
+    /** Close the stream. */
+    close(): void;
+}
+declare class ChatClient {
+    private client;
+    constructor(client: OpenRAGClient);
+    /**
+     * Send a chat message (non-streaming).
+     */
+    create(options: ChatCreateOptions & {
+        stream?: false;
+    }): Promise<ChatResponse>;
+    /**
+     * Send a chat message (streaming).
+     */
+    create(options: ChatCreateOptions & {
+        stream: true;
+    }): Promise<AsyncIterable<StreamEvent>>;
+    private _createNonStreaming;
+    private _createStreamingIterator;
+    /**
+     * Create a streaming chat context manager.
+     *
+     * @param options - Chat options.
+     * @returns ChatStream with helpers.
+     */
+    stream(options: Omit<ChatCreateOptions, "stream">): Promise<ChatStream>;
+    /**
+     * List all conversations.
+     */
+    list(): Promise<ConversationListResponse>;
+    /**
+     * Get a specific conversation with full message history.
+     *
+     * @param chatId - The ID of the conversation to retrieve.
+     */
+    get(chatId: string): Promise<ConversationDetail>;
+    /**
+     * Delete a conversation.
+     *
+     * @param chatId - The ID of the conversation to delete.
+     */
+    delete(chatId: string): Promise<boolean>;
+}
+
+/**
+ * OpenRAG SDK documents client.
+ */
+
+interface IngestOptions {
+    /** Path to file (Node.js only). */
+    filePath?: string;
+    /** File object (browser or Node.js). */
+    file?: File | Blob;
+    /** Filename when providing file/blob. */
+    filename?: string;
+    /** If true, poll until ingestion completes. Default: true. */
+    wait?: boolean;
+    /** Seconds between status checks when waiting. Default: 1. */
+    pollInterval?: number;
+    /** Maximum seconds to wait for completion. Default: 300. */
+    timeout?: number;
+}
+declare class DocumentsClient {
+    private client;
+    constructor(client: OpenRAGClient);
+    /**
+     * Ingest a document into the knowledge base.
+     *
+     * @param options - Ingest options (filePath or file+filename).
+     * @returns IngestTaskStatus with final status if wait=true, IngestResponse with task_id if wait=false.
+     */
+    ingest(options: IngestOptions): Promise<IngestResponse | IngestTaskStatus>;
+    /**
+     * Get the status of an ingestion task.
+     *
+     * @param taskId - The task ID returned from ingest().
+     * @returns IngestTaskStatus with current task status.
+     */
+    getTaskStatus(taskId: string): Promise<IngestTaskStatus>;
+    /**
+     * Wait for an ingestion task to complete.
+     *
+     * @param taskId - The task ID to wait for.
+     * @param pollInterval - Seconds between status checks.
+     * @param timeout - Maximum seconds to wait.
+     * @returns IngestTaskStatus with final status.
+     */
+    waitForTask(taskId: string, pollInterval?: number, timeout?: number): Promise<IngestTaskStatus>;
+    private sleep;
+    /**
+     * Delete a document from the knowledge base.
+     *
+     * @param filename - Name of the file to delete.
+     * @returns DeleteDocumentResponse with deleted chunk count.
+     */
+    delete(filename: string): Promise<DeleteDocumentResponse>;
+}
+
+/**
+ * OpenRAG SDK search client.
+ */
+
+declare class SearchClient {
+    private client;
+    constructor(client: OpenRAGClient);
+    /**
+     * Perform semantic search on documents.
+     *
+     * @param query - The search query text.
+     * @param options - Optional search options.
+     * @returns SearchResponse containing the search results.
+     */
+    query(query: string, options?: Omit<SearchQueryOptions, "query">): Promise<SearchResponse>;
+}
+
+/**
+ * OpenRAG SDK knowledge filters client.
+ */
+
+declare class KnowledgeFiltersClient {
+    private client;
+    constructor(client: OpenRAGClient);
+    /**
+     * Create a new knowledge filter.
+     *
+     * @param options - The filter options including name and queryData.
+     * @returns The created filter response with ID.
+     */
+    create(options: CreateKnowledgeFilterOptions): Promise<CreateKnowledgeFilterResponse>;
+    /**
+     * Search for knowledge filters by name, description, or query content.
+     *
+     * @param query - Optional search query text.
+     * @param limit - Maximum number of results (default 20).
+     * @returns List of matching knowledge filters.
+     */
+    search(query?: string, limit?: number): Promise<KnowledgeFilter[]>;
+    /**
+     * Get a specific knowledge filter by ID.
+     *
+     * @param filterId - The ID of the filter to retrieve.
+     * @returns The knowledge filter or null if not found.
+     */
+    get(filterId: string): Promise<KnowledgeFilter | null>;
+    /**
+     * Update an existing knowledge filter.
+     *
+     * @param filterId - The ID of the filter to update.
+     * @param options - The fields to update.
+     * @returns Success status.
+     */
+    update(filterId: string, options: UpdateKnowledgeFilterOptions): Promise<boolean>;
+    /**
+     * Delete a knowledge filter.
+     *
+     * @param filterId - The ID of the filter to delete.
+     * @returns Success status.
+     */
+    delete(filterId: string): Promise<boolean>;
+    /**
+     * Parse a filter from API response, handling JSON-stringified queryData.
+     */
+    private _parseFilter;
+}
+
+/**
+ * OpenRAG SDK client.
+ */
+
+declare class SettingsClient {
+    private client;
+    constructor(client: OpenRAGClient);
+    /**
+     * Get current OpenRAG configuration.
+     */
+    get(): Promise<SettingsResponse>;
+    /**
+     * Update OpenRAG configuration.
+     *
+     * @param options - The settings to update.
+     * @returns Success response with message.
+     */
+    update(options: SettingsUpdateOptions): Promise<SettingsUpdateResponse>;
+}
+interface RequestOptions {
+    body?: string | FormData;
+    isMultipart?: boolean;
+    stream?: boolean;
+}
+/**
+ * OpenRAG API client.
+ *
+ * The client can be configured via constructor arguments or environment variables:
+ * - OPENRAG_API_KEY: API key for authentication
+ * - OPENRAG_URL: Base URL for the OpenRAG API (default: http://localhost:8080)
+ *
+ * @example
+ * ```typescript
+ * // Using environment variables
+ * const client = new OpenRAGClient();
+ * const response = await client.chat.create({ message: "Hello" });
+ *
+ * // Using explicit arguments
+ * const client = new OpenRAGClient({
+ *   apiKey: "orag_...",
+ *   baseUrl: "https://api.example.com"
+ * });
+ * ```
+ */
+declare class OpenRAGClient {
+    private static readonly DEFAULT_BASE_URL;
+    private readonly _apiKey;
+    private readonly _baseUrl;
+    private readonly _timeout;
+    /** Chat client for conversations. */
+    readonly chat: ChatClient;
+    /** Search client for semantic search. */
+    readonly search: SearchClient;
+    /** Documents client for ingestion and deletion. */
+    readonly documents: DocumentsClient;
+    /** Settings client for configuration. */
+    readonly settings: SettingsClient;
+    /** Knowledge filters client for managing filters. */
+    readonly knowledgeFilters: KnowledgeFiltersClient;
+    constructor(options?: OpenRAGClientOptions);
+    /** @internal Get request headers with authentication. */
+    _getHeaders(isMultipart?: boolean): Record<string, string>;
+    /** @internal Make an authenticated request to the API. */
+    _request(method: string, path: string, options?: RequestOptions): Promise<Response>;
+    /** @internal Handle error responses. */
+    _handleError(response: Response): void;
+}
+
+export { type AgentSettings, AuthenticationError, ChatClient, type ChatCreateOptions, type ChatResponse, ChatStream, type ContentEvent, type Conversation, type ConversationDetail, type ConversationListResponse, type CreateKnowledgeFilterOptions, type CreateKnowledgeFilterResponse, type DeleteDocumentResponse, type DeleteKnowledgeFilterResponse, DocumentsClient, type DoneEvent, type GetKnowledgeFilterResponse, type IngestResponse, type KnowledgeFilter, type KnowledgeFilterQueryData, type KnowledgeFilterSearchResponse, KnowledgeFiltersClient, type KnowledgeSettings, type Message, NotFoundError, OpenRAGClient, type OpenRAGClientOptions, OpenRAGError, RateLimitError, SearchClient, type SearchFilters, type SearchQueryOptions, type SearchResponse, type SearchResult, ServerError, type SettingsResponse, type SettingsUpdateOptions, type SettingsUpdateResponse, type Source, type SourcesEvent, type StreamEvent, type UpdateKnowledgeFilterOptions, ValidationError };