dominus-sdk-nodejs 1.2.44 → 1.3.1

package/dist/namespaces/ai.js

@@ -0,0 +1,683 @@
+/**
+ * AI Namespace - Unified agent-runtime operations.
+ *
+ * Provides agent execution, LLM completions, RAG corpus management,
+ * artifacts, speech services, and workflow orchestration.
+ *
+ * All operations go through /api/* endpoints on the agent-runtime service,
+ * proxied via the gateway at /svc/*.
+ *
+ * Usage:
+ *     import { dominus } from 'dominus-sdk-nodejs';
+ *
+ *     // Agent execution
+ *     const result = await dominus.ai.runAgent({
+ *         conversationId: "conv-123",
+ *         systemPrompt: "You are helpful.",
+ *         userPrompt: "Hello!"
+ *     });
+ *
+ *     // Streaming agent execution
+ *     for await (const chunk of dominus.ai.streamAgent({
+ *         conversationId: "conv-123",
+ *         systemPrompt: "You are helpful.",
+ *         userPrompt: "Tell me a story"
+ *     })) {
+ *         process.stdout.write(chunk.content || '');
+ *     }
+ *
+ *     // LLM completion
+ *     const result = await dominus.ai.complete({
+ *         messages: [{ role: "user", content: "Hello" }],
+ *         provider: "claude",
+ *         model: "claude-sonnet-4-5"
+ *     });
+ *
+ *     // RAG operations
+ *     await dominus.ai.rag.ensure("my-corpus");
+ *     await dominus.ai.rag.upsert("my-corpus", "doc-1", { content: "Important info" });
+ *     const results = await dominus.ai.rag.search("my-corpus", "important");
+ *
+ *     // Speech
+ *     const text = await dominus.ai.stt(audioBuffer, { format: "wav" });
+ *     const audio = await dominus.ai.tts("Hello world", { voice: "nova" });
+ */
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Convert snake_case keys to camelCase in an object (shallow)
+ */
+function snakeToCamel(str) {
+    return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+ * Normalize response object keys from snake_case to camelCase
+ */
+function normalizeResponse(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const camelKey = snakeToCamel(key);
+        result[camelKey] = value;
+        // Also keep original key for backward compatibility
+        if (camelKey !== key) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// ============================================================================
+// RAG Sub-namespace
+// ============================================================================
+export class RagSubNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** List all corpora */
+    async list() {
+        const result = await this.client.request({
+            endpoint: '/api/rag',
+            method: 'GET',
+            useGateway: true,
+        });
+        if (Array.isArray(result))
+            return result;
+        return result.corpora || [];
+    }
+    /** Ensure corpus exists (create if not) */
+    async ensure(slug, options) {
+        const body = {};
+        if (options?.description)
+            body.description = options.description;
+        if (options?.embeddingModel)
+            body.embedding_model = options.embeddingModel;
+        return this.client.request({
+            endpoint: `/api/rag/${slug}/ensure`,
+            body,
+            useGateway: true,
+        });
+    }
+    /** Get corpus statistics */
+    async stats(slug) {
+        return this.client.request({
+            endpoint: `/api/rag/${slug}/stats`,
+            method: 'GET',
+            useGateway: true,
+        });
+    }
+    /** Drop/delete a corpus */
+    async drop(slug) {
+        return this.client.request({
+            endpoint: `/api/rag/${slug}`,
+            method: 'DELETE',
+            useGateway: true,
+        });
+    }
+    /** List entries in a corpus */
+    async entries(slug, options) {
+        return this.client.request({
+            endpoint: `/api/rag/${slug}/entries`,
+            body: {
+                limit: options?.limit ?? 100,
+                offset: options?.offset ?? 0,
+                ...(options?.category && { category: options.category }),
+            },
+            useGateway: true,
+        });
+    }
+    /** Upsert a single entry */
+    async upsert(slug, identifier, options) {
+        const body = {
+            content_markdown: options.content, // Transform: content -> content_markdown
+        };
+        if (options.name)
+            body.name = options.name;
+        if (options.description)
+            body.description = options.description;
+        if (options.category)
+            body.category = options.category;
+        if (options.subcategory)
+            body.subcategory = options.subcategory;
+        if (options.sourceReference)
+            body.source_reference = options.sourceReference;
+        if (options.metadata)
+            body.metadata = options.metadata;
+        return this.client.request({
+            endpoint: `/api/rag/${slug}/${identifier}`,
+            method: 'PUT',
+            body,
+            useGateway: true,
+        });
+    }
+    /** Get a specific entry */
+    async get(slug, identifier) {
+        return this.client.request({
+            endpoint: `/api/rag/${slug}/${identifier}`,
+            method: 'GET',
+            useGateway: true,
+        });
+    }
+    /** Delete an entry */
+    async delete(slug, identifier) {
+        return this.client.request({
+            endpoint: `/api/rag/${slug}/${identifier}`,
+            method: 'DELETE',
+            useGateway: true,
+        });
+    }
+    /** Bulk upsert entries */
+    async bulkUpsert(slug, entries) {
+        // Transform 'content' to 'content_markdown' for API compatibility
+        const transformed = entries.map((entry) => {
+            const e = { ...entry };
+            if (e.content && !e.content_markdown) {
+                e.content_markdown = e.content;
+                delete e.content;
+            }
+            return e;
+        });
+        return this.client.request({
+            endpoint: `/api/rag/${slug}/bulk`,
+            body: { entries: transformed },
+            useGateway: true,
+        });
+    }
+    /** Semantic search */
+    async search(slug, query, options) {
+        const body = {
+            query,
+            limit: options?.limit ?? 10,
+        };
+        if (options?.threshold !== undefined)
+            body.threshold = options.threshold;
+        if (options?.category)
+            body.category = options.category;
+        if (options?.filters)
+            body.filters = options.filters;
+        const result = await this.client.request({
+            endpoint: `/api/rag/${slug}/search`,
+            body,
+            useGateway: true,
+        });
+        if (Array.isArray(result))
+            return result;
+        return result.results || [];
+    }
+    /** Semantic search with reranking */
+    async searchRerank(slug, query, options) {
+        const body = {
+            query,
+            limit: options?.limit ?? 10,
+        };
+        if (options?.rerankModel)
+            body.rerank_model = options.rerankModel;
+        const result = await this.client.request({
+            endpoint: `/api/rag/${slug}/search/rerank`,
+            body,
+            useGateway: true,
+        });
+        if (Array.isArray(result))
+            return result;
+        return result.results || [];
+    }
+    /** Ingest a document (PDF, DOCX, etc.) */
+    async ingest(slug, content, filename, options) {
+        return this.client.binaryUpload({
+            endpoint: `/api/rag/${slug}/ingest`,
+            fileBytes: content,
+            filename,
+            contentType: options?.contentType || 'application/octet-stream',
+            additionalFields: {
+                chunk_size: String(options?.chunkSize ?? 1000),
+                chunk_overlap: String(options?.chunkOverlap ?? 200),
+            },
+            useGateway: true,
+        });
+    }
+    /** Delete a document and all its chunks */
+    async deleteDocument(slug, documentId) {
+        return this.client.request({
+            endpoint: `/api/rag/${slug}/document/${documentId}`,
+            method: 'DELETE',
+            useGateway: true,
+        });
+    }
+}
+// ============================================================================
+// Artifacts Sub-namespace
+// ============================================================================
+export class ArtifactsSubNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Get artifact by ID */
+    async get(artifactId, conversationId) {
+        return this.client.request({
+            endpoint: `/api/agent/artifacts/${artifactId}?conversation_id=${conversationId}`,
+            method: 'GET',
+            useGateway: true,
+        });
+    }
+    /** Create a new artifact */
+    async create(options) {
+        return this.client.request({
+            endpoint: '/api/agent/artifacts',
+            body: {
+                key: options.name, // Transform: name -> key
+                content: options.content,
+                conversation_id: options.conversationId,
+                content_type: options.artifactType || 'text/plain', // Transform: artifactType -> content_type
+                is_base64: options.isBase64 || false,
+            },
+            useGateway: true,
+        });
+    }
+    /** List artifacts for a conversation */
+    async list(conversationId) {
+        const result = await this.client.request({
+            endpoint: `/api/agent/artifacts?conversation_id=${conversationId}`,
+            method: 'GET',
+            useGateway: true,
+        });
+        if (Array.isArray(result))
+            return result;
+        return result.artifacts || [];
+    }
+    /** Delete an artifact */
+    async delete(artifactId, conversationId) {
+        return this.client.request({
+            endpoint: `/api/agent/artifacts/${artifactId}?conversation_id=${conversationId}`,
+            method: 'DELETE',
+            useGateway: true,
+        });
+    }
+}
+// ============================================================================
+// Results Sub-namespace
+// ============================================================================
+export class ResultsSubNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Get async result by key */
+    async get(resultKey) {
+        return this.client.request({
+            endpoint: `/api/results/${resultKey}`,
+            method: 'GET',
+            useGateway: true,
+        });
+    }
+    /** Poll for result until completion or timeout */
+    async poll(resultKey, options) {
+        const interval = options?.interval ?? 1000;
+        const timeout = options?.timeout ?? 300000;
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const result = await this.get(resultKey);
+            if (result.status === 'completed') {
+                return result;
+            }
+            if (result.status === 'failed') {
+                throw new Error(`Operation failed: ${result.error || 'Unknown error'}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+        throw new Error(`Result polling timed out after ${timeout}ms`);
+    }
+}
+// ============================================================================
+// Workflow Sub-namespace
+// ============================================================================
+export class WorkflowSubNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Execute a multi-agent workflow */
+    async execute(options) {
+        const body = {
+            workflow_id: options.workflowId,
+            input: options.input,
+            mode: options.mode || 'blocking',
+        };
+        if (options.conversationId)
+            body.conversation_id = options.conversationId;
+        if (options.webhookUrl)
+            body.webhook_url = options.webhookUrl;
+        return this.client.request({
+            endpoint: '/api/orchestration/execute',
+            body,
+            useGateway: true,
+        });
+    }
+    /** Validate a workflow definition */
+    async validate(workflowDefinition) {
+        return this.client.request({
+            endpoint: '/api/orchestration/validate',
+            body: { definition: workflowDefinition },
+            useGateway: true,
+        });
+    }
+    /** Get messages from an execution */
+    async messages(executionId, options) {
+        const result = await this.client.request({
+            endpoint: `/api/orchestration/messages/${executionId}`,
+            body: { limit: options?.limit ?? 100, offset: options?.offset ?? 0 },
+            useGateway: true,
+        });
+        if (Array.isArray(result))
+            return result;
+        return result.messages || [];
+    }
+    /** Replay events from an execution */
+    async events(executionId, fromTimestamp) {
+        const body = {};
+        if (fromTimestamp)
+            body.from = fromTimestamp;
+        const result = await this.client.request({
+            endpoint: `/api/orchestration/events/${executionId}`,
+            body: Object.keys(body).length > 0 ? body : undefined,
+            useGateway: true,
+        });
+        if (Array.isArray(result))
+            return result;
+        return result.events || [];
+    }
+    /** Get execution status */
+    async status(executionId) {
+        return this.client.request({
+            endpoint: `/api/orchestration/status/${executionId}`,
+            method: 'GET',
+            useGateway: true,
+        });
+    }
+    /** Get final execution output */
+    async output(executionId) {
+        return this.client.request({
+            endpoint: `/api/orchestration/output/${executionId}`,
+            method: 'GET',
+            useGateway: true,
+        });
+    }
+}
+// ============================================================================
+// Main AI Namespace
+// ============================================================================
+export class AiNamespace {
+    client;
+    /** RAG corpus management */
+    rag;
+    /** Conversation artifacts */
+    artifacts;
+    /** Async result polling */
+    results;
+    /** Multi-agent workflow orchestration */
+    workflow;
+    constructor(client) {
+        this.client = client;
+        this.rag = new RagSubNamespace(client);
+        this.artifacts = new ArtifactsSubNamespace(client);
+        this.results = new ResultsSubNamespace(client);
+        this.workflow = new WorkflowSubNamespace(client);
+    }
+    // ========================================
+    // Agent Execution
+    // ========================================
+    /** Execute agent with blocking wait */
+    async runAgent(options) {
+        const body = {
+            conversation_id: options.conversationId,
+            system_prompt: options.systemPrompt,
+            user_prompt: options.userPrompt,
+            history_source: options.historySource || 'conversation_id',
+            model: options.model || 'claude-sonnet-4-5',
+        };
+        if (options.inlineHistory)
+            body.inline_history = options.inlineHistory;
+        if (options.preloadedContext)
+            body.preloaded_context = options.preloadedContext;
+        if (options.artifactRefs)
+            body.artifact_refs = options.artifactRefs;
+        if (options.toolAllowlist)
+            body.tool_allowlist = options.toolAllowlist;
+        if (options.guardrails)
+            body.guardrails = options.guardrails;
+        if (options.outputSchema)
+            body.output_schema = options.outputSchema;
+        if (options.toolEndpoint)
+            body.tool_endpoint = options.toolEndpoint;
+        const result = await this.client.request({
+            endpoint: '/api/agent/run',
+            body,
+            timeout: options.timeout,
+            useGateway: true,
+        });
+        // Normalize snake_case keys to camelCase
+        return normalizeResponse(result);
+    }
+    /** Execute agent with SSE streaming */
+    async *streamAgent(options) {
+        const body = {
+            conversation_id: options.conversationId,
+            system_prompt: options.systemPrompt,
+            user_prompt: options.userPrompt,
+            history_source: options.historySource || 'conversation_id',
+            model: options.model || 'claude-sonnet-4-5',
+        };
+        if (options.inlineHistory)
+            body.inline_history = options.inlineHistory;
+        if (options.preloadedContext)
+            body.preloaded_context = options.preloadedContext;
+        if (options.artifactRefs)
+            body.artifact_refs = options.artifactRefs;
+        if (options.toolAllowlist)
+            body.tool_allowlist = options.toolAllowlist;
+        if (options.guardrails)
+            body.guardrails = options.guardrails;
+        if (options.outputSchema)
+            body.output_schema = options.outputSchema;
+        if (options.toolEndpoint)
+            body.tool_endpoint = options.toolEndpoint;
+        for await (const chunk of this.client.streamRequest({
+            endpoint: '/api/agent/stream',
+            body,
+            onChunk: options.onChunk,
+            timeout: options.timeout || 300000,
+            useGateway: true,
+        })) {
+            // Normalize chunk and yield
+            const normalized = normalizeResponse(chunk);
+            yield normalized;
+        }
+    }
+    /** Fire-and-forget async execution */
+    async runAgentAsync(options) {
+        const body = {
+            conversation_id: options.conversationId,
+            system_prompt: options.systemPrompt,
+            user_prompt: options.userPrompt,
+            result_key: options.resultKey,
+            history_source: options.historySource || 'conversation_id',
+            model: options.model || 'claude-sonnet-4-5',
+        };
+        if (options.inlineHistory)
+            body.inline_history = options.inlineHistory;
+        if (options.preloadedContext)
+            body.preloaded_context = options.preloadedContext;
+        if (options.artifactRefs)
+            body.artifact_refs = options.artifactRefs;
+        if (options.toolAllowlist)
+            body.tool_allowlist = options.toolAllowlist;
+        if (options.guardrails)
+            body.guardrails = options.guardrails;
+        if (options.outputSchema)
+            body.output_schema = options.outputSchema;
+        if (options.toolEndpoint)
+            body.tool_endpoint = options.toolEndpoint;
+        if (options.webhookUrl)
+            body.webhook_url = options.webhookUrl;
+        return this.client.request({
+            endpoint: '/api/agent/run-async',
+            body,
+            useGateway: true,
+        });
+    }
+    // ========================================
+    // Conversation History
+    // ========================================
+    /** Get conversation history */
+    async history(conversationId, limit = 50) {
+        const result = await this.client.request({
+            endpoint: `/api/agent/history/${conversationId}?limit=${limit}`,
+            method: 'GET',
+            useGateway: true,
+        });
+        if (Array.isArray(result))
+            return result;
+        return result.messages || [];
+    }
+    // ========================================
+    // LLM Completions
+    // ========================================
+    /** Blocking LLM completion */
+    async complete(options) {
+        let systemPrompt = options.systemPrompt;
+        let userPrompt = options.userPrompt;
+        // Convert messages to system_prompt/user_prompt if needed
+        if (options.messages && !userPrompt) {
+            for (const msg of options.messages) {
+                if (msg.role === 'system') {
+                    systemPrompt = msg.content;
+                }
+                else if (msg.role === 'user') {
+                    userPrompt = msg.content;
+                }
+            }
+        }
+        if (!systemPrompt) {
+            systemPrompt = 'You are a helpful assistant.';
+        }
+        if (!userPrompt) {
+            throw new Error("Either 'messages' with a user message or 'userPrompt' is required");
+        }
+        const body = {
+            provider: options.provider || 'claude',
+            model: options.model || 'claude-sonnet-4-5',
+            system_prompt: systemPrompt,
+            user_prompt: userPrompt,
+            temperature: options.temperature ?? 0.7,
+        };
+        if (options.conversationId)
+            body.conversation_id = options.conversationId;
+        if (options.maxTokens)
+            body.max_tokens = options.maxTokens;
+        return this.client.request({
+            endpoint: '/api/llm/complete',
+            body,
+            timeout: options.timeout,
+            useGateway: true,
+        });
+    }
+    /** Streaming LLM completion */
+    async *completeStream(options) {
+        let systemPrompt = options.systemPrompt;
+        let userPrompt = options.userPrompt;
+        // Convert messages to system_prompt/user_prompt if needed
+        if (options.messages && !userPrompt) {
+            for (const msg of options.messages) {
+                if (msg.role === 'system') {
+                    systemPrompt = msg.content;
+                }
+                else if (msg.role === 'user') {
+                    userPrompt = msg.content;
+                }
+            }
+        }
+        if (!systemPrompt) {
+            systemPrompt = 'You are a helpful assistant.';
+        }
+        if (!userPrompt) {
+            throw new Error("Either 'messages' with a user message or 'userPrompt' is required");
+        }
+        const body = {
+            provider: options.provider || 'claude',
+            model: options.model || 'claude-sonnet-4-5',
+            system_prompt: systemPrompt,
+            user_prompt: userPrompt,
+            temperature: options.temperature ?? 0.7,
+        };
+        if (options.conversationId)
+            body.conversation_id = options.conversationId;
+        if (options.maxTokens)
+            body.max_tokens = options.maxTokens;
+        for await (const chunk of this.client.streamRequest({
+            endpoint: '/api/llm/stream',
+            body,
+            onChunk: options.onChunk,
+            timeout: options.timeout || 120000,
+            useGateway: true,
+        })) {
+            // Normalize chunk and yield
+            const normalized = normalizeResponse(chunk);
+            yield normalized;
+        }
+    }
+    // ========================================
+    // Speech Services
+    // ========================================
+    /** Speech-to-text conversion */
+    async stt(audio, options) {
+        const format = options?.format || 'wav';
+        const additionalFields = {};
+        if (options?.language)
+            additionalFields.language = options.language;
+        const result = await this.client.binaryUpload({
+            endpoint: '/api/agent/stt',
+            fileBytes: audio,
+            filename: `audio.${format}`,
+            contentType: `audio/${format}`,
+            additionalFields: Object.keys(additionalFields).length > 0 ? additionalFields : undefined,
+            useGateway: true,
+        });
+        return result;
+    }
+    /** Text-to-speech conversion */
+    async tts(text, options) {
+        return this.client.binaryDownload({
+            endpoint: '/api/agent/tts',
+            body: {
+                text,
+                voice: options?.voice || 'nova',
+                format: options?.format || 'mp3',
+                speed: options?.speed ?? 1.0,
+            },
+            useGateway: true,
+        });
+    }
+    // ========================================
+    // Pre-flight Setup
+    // ========================================
+    /** Pre-flight session setup */
+    async setup(options) {
+        const body = {
+            conversation_id: options.conversationId,
+        };
+        if (options.artifacts)
+            body.artifacts = options.artifacts;
+        if (options.ragCorpus)
+            body.rag_corpus = options.ragCorpus;
+        if (options.context)
+            body.context = options.context;
+        const result = await this.client.request({
+            endpoint: '/api/session/setup',
+            body,
+            useGateway: true,
+        });
+        // Normalize snake_case keys to camelCase
+        return normalizeResponse(result);
+    }
+}
+//# sourceMappingURL=ai.js.map