cognitive-modules-cli 2.2.1 → 2.2.7

package/dist/providers/ollama.js

@@ -1,5 +1,7 @@
 /**
  * Ollama Provider - Local LLM via Ollama
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 export class OllamaProvider extends BaseProvider {
@@ -14,8 +16,16 @@ export class OllamaProvider extends BaseProvider {
     isConfigured() {
         return true; // Ollama doesn't need API key
     }
-    async invoke(params) {
-        const url = `${this.baseUrl}/api/chat`;
+    /**
+     * Ollama supports streaming.
+     */
+    supportsStreaming() {
+        return true;
+    }
+    /**
+     * Build request body for Ollama API
+     */
+    buildRequestBody(params, stream) {
         let messages = params.messages.map(m => ({ role: m.role, content: m.content }));
         // Add JSON mode if schema provided
         if (params.jsonSchema) {
@@ -31,7 +41,7 @@ export class OllamaProvider extends BaseProvider {
         const body = {
             model: this.model,
             messages,
-            stream: false,
+            stream,
             options: {
                 temperature: params.temperature ?? 0.7,
                 num_predict: params.maxTokens ?? 4096,
@@ -41,6 +51,11 @@ export class OllamaProvider extends BaseProvider {
         if (params.jsonSchema) {
             body.format = 'json';
         }
+        return body;
+    }
+    async invoke(params) {
+        const url = `${this.baseUrl}/api/chat`;
+        const body = this.buildRequestBody(params, false);
         const response = await fetch(url, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -61,4 +76,97 @@ export class OllamaProvider extends BaseProvider {
             },
         };
     }
+    /**
+     * Stream-based invoke using Ollama's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    async *invokeStream(params) {
+        const url = `${this.baseUrl}/api/chat`;
+        const body = this.buildRequestBody(params, true);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Ollama API error: ${response.status} - ${error}`);
+        }
+        if (!response.body) {
+            throw new Error('Ollama API returned no body for streaming request');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        const collectedChunks = [];
+        let promptTokens = 0;
+        let completionTokens = 0;
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete lines from the buffer (NDJSON format)
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    try {
+                        const data = JSON.parse(trimmed);
+                        // Extract content chunk
+                        const content = data.message?.content;
+                        if (content) {
+                            collectedChunks.push(content);
+                            yield content;
+                        }
+                        // Extract usage info (in the final message when done=true)
+                        if (data.done) {
+                            promptTokens = data.prompt_eval_count || 0;
+                            completionTokens = data.eval_count || 0;
+                        }
+                    }
+                    catch {
+                        // Skip invalid JSON lines
+                    }
+                }
+            }
+            // Flush decoder and process trailing buffered data even without trailing newline.
+            buffer += decoder.decode();
+            for (const line of buffer.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const data = JSON.parse(trimmed);
+                    const content = data.message?.content;
+                    if (content) {
+                        collectedChunks.push(content);
+                        yield content;
+                    }
+                    if (data.done) {
+                        promptTokens = data.prompt_eval_count || 0;
+                        completionTokens = data.eval_count || 0;
+                    }
+                }
+                catch {
+                    // Skip invalid JSON lines
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const fullContent = collectedChunks.join('');
+        return {
+            content: fullContent,
+            usage: {
+                promptTokens,
+                completionTokens,
+                totalTokens: promptTokens + completionTokens,
+            },
+        };
+    }
 }

package/dist/providers/openai.d.ts

@@ -1,5 +1,7 @@
 /**
  * OpenAI Provider - OpenAI API (and compatible APIs)
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 import type { InvokeParams, InvokeResult } from '../types.js';
@@ -10,5 +12,14 @@ export declare class OpenAIProvider extends BaseProvider {
     private baseUrl;
     constructor(apiKey?: string, model?: string, baseUrl?: string);
     isConfigured(): boolean;
+    /**
+     * OpenAI supports streaming.
+     */
+    supportsStreaming(): boolean;
     invoke(params: InvokeParams): Promise<InvokeResult>;
+    /**
+     * Stream-based invoke using OpenAI's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    invokeStream(params: InvokeParams): AsyncGenerator<string, InvokeResult, unknown>;
 }

package/dist/providers/openai.js

@@ -1,5 +1,7 @@
 /**
  * OpenAI Provider - OpenAI API (and compatible APIs)
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 export class OpenAIProvider extends BaseProvider {
@@ -16,6 +18,12 @@ export class OpenAIProvider extends BaseProvider {
     isConfigured() {
         return !!this.apiKey;
     }
+    /**
+     * OpenAI supports streaming.
+     */
+    supportsStreaming() {
+        return true;
+    }
     async invoke(params) {
         if (!this.isConfigured()) {
             throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY environment variable.');
@@ -64,4 +72,129 @@ export class OpenAIProvider extends BaseProvider {
             } : undefined,
         };
     }
+    /**
+     * Stream-based invoke using OpenAI's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    async *invokeStream(params) {
+        if (!this.isConfigured()) {
+            throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY environment variable.');
+        }
+        const url = `${this.baseUrl}/chat/completions`;
+        const body = {
+            model: this.model,
+            messages: params.messages,
+            temperature: params.temperature ?? 0.7,
+            max_tokens: params.maxTokens ?? 4096,
+            stream: true,
+            stream_options: { include_usage: true },
+        };
+        // Add JSON mode if schema provided
+        if (params.jsonSchema) {
+            body.response_format = { type: 'json_object' };
+            // Append schema instruction to last user message
+            const lastUserIdx = params.messages.findLastIndex(m => m.role === 'user');
+            if (lastUserIdx >= 0) {
+                const messages = [...params.messages];
+                messages[lastUserIdx] = {
+                    ...messages[lastUserIdx],
+                    content: messages[lastUserIdx].content + this.buildJsonPrompt(params.jsonSchema),
+                };
+                body.messages = messages;
+            }
+        }
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`OpenAI API error: ${response.status} - ${error}`);
+        }
+        if (!response.body) {
+            throw new Error('OpenAI API returned no body for streaming request');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        const collectedChunks = [];
+        let usage;
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete lines from the buffer
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed === 'data: [DONE]')
+                        continue;
+                    if (trimmed.startsWith('data: ')) {
+                        try {
+                            const data = JSON.parse(trimmed.slice(6));
+                            // Extract content chunk
+                            const content = data.choices?.[0]?.delta?.content;
+                            if (content) {
+                                collectedChunks.push(content);
+                                yield content;
+                            }
+                            // Extract usage info (usually in the last chunk)
+                            if (data.usage) {
+                                usage = {
+                                    promptTokens: data.usage.prompt_tokens || 0,
+                                    completionTokens: data.usage.completion_tokens || 0,
+                                    totalTokens: data.usage.total_tokens || 0,
+                                };
+                            }
+                        }
+                        catch {
+                            // Skip invalid JSON chunks
+                        }
+                    }
+                }
+            }
+            // Flush decoder and process trailing buffered data even without trailing newline.
+            buffer += decoder.decode();
+            for (const line of buffer.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed === 'data: [DONE]')
+                    continue;
+                if (trimmed.startsWith('data: ')) {
+                    try {
+                        const data = JSON.parse(trimmed.slice(6));
+                        const content = data.choices?.[0]?.delta?.content;
+                        if (content) {
+                            collectedChunks.push(content);
+                            yield content;
+                        }
+                        if (data.usage) {
+                            usage = {
+                                promptTokens: data.usage.prompt_tokens || 0,
+                                completionTokens: data.usage.completion_tokens || 0,
+                                totalTokens: data.usage.total_tokens || 0,
+                            };
+                        }
+                    }
+                    catch {
+                        // Skip invalid JSON chunks
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const fullContent = collectedChunks.join('');
+        return {
+            content: fullContent,
+            usage,
+        };
+    }
 }

package/dist/registry/client.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Registry Client - Fetch and manage modules from Cognitive Modules Registry
+ *
+ * Supports both v1 and v2 registry formats.
+ *
+ * Usage:
+ *   const client = new RegistryClient();
+ *   const modules = await client.listModules();
+ *   const module = await client.getModule('code-reviewer');
+ */
+/** v1 Registry Format (current cognitive-registry.json) */
+export interface RegistryV1 {
+    $schema?: string;
+    version: string;
+    updated: string;
+    modules: {
+        [name: string]: {
+            description: string;
+            version: string;
+            source: string;
+            tags: string[];
+            author: string;
+        };
+    };
+    categories?: {
+        [key: string]: {
+            name: string;
+            description: string;
+            modules: string[];
+        };
+    };
+}
+/** v2 Registry Format (new format per REGISTRY-PROTOCOL.md) */
+export interface RegistryV2 {
+    $schema?: string;
+    version: string;
+    updated: string;
+    modules: {
+        [name: string]: RegistryEntryV2;
+    };
+    categories?: {
+        [key: string]: {
+            name: string;
+            name_zh?: string;
+            description: string;
+            modules: string[];
+        };
+    };
+    featured?: string[];
+    stats?: {
+        total_modules: number;
+        total_downloads: number;
+        last_updated: string;
+    };
+}
+/** v2 Registry Entry */
+export interface RegistryEntryV2 {
+    identity: {
+        name: string;
+        namespace: string;
+        version: string;
+        spec_version: string;
+    };
+    metadata: {
+        description: string;
+        description_zh?: string;
+        author: string;
+        license?: string;
+        repository?: string;
+        documentation?: string;
+        homepage?: string;
+        keywords?: string[];
+        tier?: 'exec' | 'decision' | 'exploration';
+    };
+    quality?: {
+        conformance_level?: number;
+        test_coverage?: number;
+        test_vector_pass?: boolean;
+        verified?: boolean;
+        verified_by?: string;
+        verified_at?: string;
+        downloads_30d?: number;
+        stars?: number;
+        badges?: string[];
+        deprecated?: boolean;
+        successor?: string;
+        deprecation_reason?: string;
+    };
+    dependencies: {
+        runtime_min: string;
+        modules: Array<{
+            name: string;
+            version?: string;
+            optional?: boolean;
+        }>;
+    };
+    distribution: {
+        tarball: string;
+        checksum: string;
+        size_bytes?: number;
+        files?: string[];
+        signature?: string;
+        signing_key?: string;
+    };
+    timestamps?: {
+        created_at?: string;
+        updated_at?: string;
+        deprecated_at?: string;
+    };
+}
+/** Normalized module info (works with both v1 and v2) */
+export interface ModuleInfo {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    source: string;
+    tarball?: string;
+    checksum?: string;
+    keywords: string[];
+    tier?: string;
+    namespace?: string;
+    license?: string;
+    repository?: string;
+    conformance_level?: number;
+    verified?: boolean;
+    deprecated?: boolean;
+}
+/** Search result */
+export interface SearchResult {
+    name: string;
+    description: string;
+    version: string;
+    score: number;
+    keywords: string[];
+}
+export declare class RegistryClient {
+    private registryUrl;
+    private cache;
+    constructor(registryUrl?: string);
+    private parseRegistryResponse;
+    /**
+     * Generate a unique cache filename based on registry URL
+     */
+    private getCacheFileName;
+    /**
+     * Fetch registry index (with caching)
+     */
+    fetchRegistry(forceRefresh?: boolean): Promise<RegistryV1 | RegistryV2>;
+    /**
+     * Check if registry is v2 format
+     */
+    private isV2Registry;
+    /**
+     * Normalize module entry to unified format
+     */
+    private normalizeModule;
+    /**
+     * List all modules in registry
+     */
+    listModules(): Promise<ModuleInfo[]>;
+    /**
+     * Get a specific module by name
+     */
+    getModule(name: string): Promise<ModuleInfo | null>;
+    /**
+     * Search modules by query
+     */
+    search(query: string): Promise<SearchResult[]>;
+    /**
+     * Get categories
+     */
+    getCategories(): Promise<{
+        [key: string]: {
+            name: string;
+            description: string;
+            modules: string[];
+        };
+    }>;
+    /**
+     * Parse GitHub source string
+     * Format: github:<owner>/<repo>[/<path>][@<ref>]
+     */
+    parseGitHubSource(source: string): {
+        org: string;
+        repo: string;
+        path?: string;
+        ref?: string;
+    } | null;
+    /**
+     * Verify checksum of downloaded file
+     */
+    verifyChecksum(filePath: string, expected: string): Promise<boolean>;
+    /**
+     * Get the download URL for a module
+     */
+    getDownloadUrl(moduleName: string): Promise<{
+        url: string;
+        checksum?: string;
+        isGitHub: boolean;
+        githubInfo?: {
+            org: string;
+            repo: string;
+            path?: string;
+            ref?: string;
+        };
+    }>;
+}
+export declare const defaultRegistry: RegistryClient;
+export declare function listRegistryModules(): Promise<ModuleInfo[]>;
+export declare function getRegistryModule(name: string): Promise<ModuleInfo | null>;
+export declare function searchRegistry(query: string): Promise<SearchResult[]>;