cognitive-modules-cli 1.2.0 → 1.4.0

package/src/server/http.ts

@@ -0,0 +1,316 @@
+/**
+ * Cognitive Modules HTTP API Server
+ * 
+ * Provides RESTful API interface for workflow platform integration.
+ * 
+ * Start with:
+ *   cog serve --port 8000
+ * 
+ * Environment variables:
+ *   COGNITIVE_API_KEY - API Key authentication (optional)
+ *   OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. - LLM provider keys
+ */
+
+import http from 'node:http';
+import { URL } from 'node:url';
+import { loadModule, findModule, listModules, getDefaultSearchPaths } from '../modules/loader.js';
+import { runModule } from '../modules/runner.js';
+import { getProvider } from '../providers/index.js';
+import type { CognitiveModule, Provider } from '../types.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface RunRequest {
+  module: string;
+  args: string;
+  provider?: string;
+  model?: string;
+}
+
+interface RunResponse {
+  ok: boolean;
+  data?: unknown;
+  meta?: unknown;
+  error?: string;
+  module: string;
+  provider?: string;
+}
+
+interface ModuleInfo {
+  name: string;
+  version?: string;
+  description?: string;
+  format: string;
+  path: string;
+  responsibility?: string;
+  tier?: string;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function jsonResponse(res: http.ServerResponse, status: number, data: unknown): void {
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+  });
+  res.end(JSON.stringify(data, null, 2));
+}
+
+function parseBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', (chunk) => (body += chunk));
+    req.on('end', () => resolve(body));
+    req.on('error', reject);
+  });
+}
+
+function verifyApiKey(req: http.IncomingMessage): boolean {
+  const expectedKey = process.env.COGNITIVE_API_KEY;
+  if (!expectedKey) return true; // No auth required
+  
+  const authHeader = req.headers.authorization;
+  if (!authHeader) return false;
+  
+  const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : authHeader;
+  return token === expectedKey;
+}
+
+// =============================================================================
+// Request Handlers
+// =============================================================================
+
+async function handleRoot(res: http.ServerResponse): Promise<void> {
+  jsonResponse(res, 200, {
+    name: 'Cognitive Modules API',
+    version: '1.3.0',
+    docs: '/docs',
+    endpoints: {
+      run: 'POST /run',
+      modules: 'GET /modules',
+      module_info: 'GET /modules/{name}',
+      health: 'GET /health',
+    },
+  });
+}
+
+async function handleHealth(res: http.ServerResponse): Promise<void> {
+  const providers = {
+    openai: Boolean(process.env.OPENAI_API_KEY),
+    anthropic: Boolean(process.env.ANTHROPIC_API_KEY),
+    minimax: Boolean(process.env.MINIMAX_API_KEY),
+    deepseek: Boolean(process.env.DEEPSEEK_API_KEY),
+    gemini: Boolean(process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY),
+    qwen: Boolean(process.env.QWEN_API_KEY || process.env.DASHSCOPE_API_KEY),
+  };
+  
+  jsonResponse(res, 200, {
+    status: 'healthy',
+    version: '1.3.0',
+    providers,
+  });
+}
+
+async function handleModules(
+  res: http.ServerResponse,
+  searchPaths: string[]
+): Promise<void> {
+  const modules = await listModules(searchPaths);
+  
+  const moduleInfos: ModuleInfo[] = modules.map((m) => ({
+    name: m.name,
+    version: m.version,
+    description: m.responsibility,
+    format: m.format,
+    path: m.location,
+    responsibility: m.responsibility,
+    tier: m.tier,
+  }));
+  
+  jsonResponse(res, 200, {
+    modules: moduleInfos,
+    count: moduleInfos.length,
+  });
+}
+
+async function handleModuleInfo(
+  res: http.ServerResponse,
+  moduleName: string,
+  searchPaths: string[]
+): Promise<void> {
+  const moduleData = await findModule(moduleName, searchPaths);
+  
+  if (!moduleData) {
+    jsonResponse(res, 404, { error: `Module '${moduleName}' not found` });
+    return;
+  }
+  
+  jsonResponse(res, 200, {
+    name: moduleData.name,
+    version: moduleData.version,
+    description: moduleData.responsibility,
+    format: moduleData.format,
+    path: moduleData.location,
+    responsibility: moduleData.responsibility,
+    tier: moduleData.tier,
+    inputSchema: moduleData.inputSchema,
+    outputSchema: moduleData.outputSchema,
+  });
+}
+
+async function handleRun(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  searchPaths: string[]
+): Promise<void> {
+  // Verify API key
+  if (!verifyApiKey(req)) {
+    jsonResponse(res, 401, {
+      error: 'Missing or invalid API Key. Use header: Authorization: Bearer <your-api-key>',
+    });
+    return;
+  }
+  
+  // Parse request body
+  let request: RunRequest;
+  try {
+    const body = await parseBody(req);
+    request = JSON.parse(body);
+  } catch {
+    jsonResponse(res, 400, { error: 'Invalid JSON body' });
+    return;
+  }
+  
+  // Validate request
+  if (!request.module || !request.args) {
+    jsonResponse(res, 400, { error: 'Missing required fields: module, args' });
+    return;
+  }
+  
+  // Find module
+  const moduleData = await findModule(request.module, searchPaths);
+  if (!moduleData) {
+    jsonResponse(res, 404, { error: `Module '${request.module}' not found` });
+    return;
+  }
+  
+  try {
+    // Create provider
+    const provider = getProvider(request.provider, request.model);
+    
+    // Run module
+    const result = await runModule(moduleData, provider, {
+      input: { query: request.args, code: request.args },
+      useV22: true,
+    });
+    
+    const response: RunResponse = {
+      ok: result.ok,
+      module: request.module,
+      provider: request.provider || process.env.LLM_PROVIDER || 'openai',
+    };
+    
+    if (result.ok) {
+      if ('meta' in result) response.meta = result.meta;
+      if ('data' in result) response.data = result.data;
+    } else {
+      if ('error' in result) response.error = result.error?.message;
+    }
+    
+    jsonResponse(res, 200, response);
+  } catch (error) {
+    jsonResponse(res, 500, {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+      module: request.module,
+    });
+  }
+}
+
+// =============================================================================
+// Server
+// =============================================================================
+
+export interface ServeOptions {
+  host?: string;
+  port?: number;
+  cwd?: string;
+}
+
+export function createServer(options: ServeOptions = {}): http.Server {
+  const { cwd = process.cwd() } = options;
+  const searchPaths = getDefaultSearchPaths(cwd);
+  
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url || '/', `http://${req.headers.host}`);
+    const path = url.pathname;
+    const method = req.method?.toUpperCase();
+    
+    // Handle CORS preflight
+    if (method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+      });
+      res.end();
+      return;
+    }
+    
+    try {
+      // Route requests
+      if (path === '/' && method === 'GET') {
+        await handleRoot(res);
+      } else if (path === '/health' && method === 'GET') {
+        await handleHealth(res);
+      } else if (path === '/modules' && method === 'GET') {
+        await handleModules(res, searchPaths);
+      } else if (path.startsWith('/modules/') && method === 'GET') {
+        const moduleName = path.slice('/modules/'.length);
+        await handleModuleInfo(res, moduleName, searchPaths);
+      } else if (path === '/run' && method === 'POST') {
+        await handleRun(req, res, searchPaths);
+      } else {
+        jsonResponse(res, 404, { error: 'Not found' });
+      }
+    } catch (error) {
+      console.error('Server error:', error);
+      jsonResponse(res, 500, {
+        error: error instanceof Error ? error.message : 'Internal server error',
+      });
+    }
+  });
+  
+  return server;
+}
+
+export async function serve(options: ServeOptions = {}): Promise<void> {
+  const { host = '0.0.0.0', port = 8000 } = options;
+  
+  const server = createServer(options);
+  
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, host, () => {
+      console.log(`Cognitive Modules HTTP Server running at http://${host}:${port}`);
+      console.log('Endpoints:');
+      console.log('  GET  /          - API info');
+      console.log('  GET  /health    - Health check');
+      console.log('  GET  /modules   - List modules');
+      console.log('  GET  /modules/:name - Module info');
+      console.log('  POST /run       - Run module');
+      resolve();
+    });
+  });
+}
+
+// Allow running directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  serve().catch(console.error);
+}

package/src/server/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Server - Re-export all server functionality
+ */
+
+export { serve, createServer } from './http.js';
+export type { ServeOptions } from './http.js';

package/src/types.ts

@@ -1,6 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.2 - With Control/Data plane separation, tier, overflow, extensible enums
+ * Version 2.5 - With streaming response and multimodal support
  */
 
 // =============================================================================
@@ -493,3 +493,321 @@ export function shouldEscalate<T>(
   
   return false;
 }
+
+// =============================================================================
+// v2.5 Streaming Types
+// =============================================================================
+
+/** Response mode configuration */
+export type ResponseMode = 'sync' | 'streaming' | 'both';
+
+/** Chunk type for streaming */
+export type ChunkType = 'delta' | 'snapshot';
+
+/** Response configuration in module.yaml */
+export interface ResponseConfig {
+  mode: ResponseMode;
+  chunk_type?: ChunkType;
+  buffer_size?: number;
+  heartbeat_interval_ms?: number;
+  max_duration_ms?: number;
+}
+
+/** Meta chunk - initial streaming response */
+export interface MetaChunk {
+  ok: true;
+  streaming: true;
+  session_id: string;
+  meta: Partial<EnvelopeMeta>;
+}
+
+/** Delta chunk - incremental content */
+export interface DeltaChunk {
+  chunk: {
+    seq: number;
+    type: 'delta';
+    field?: string;
+    delta: string;
+  };
+}
+
+/** Snapshot chunk - full state replacement */
+export interface SnapshotChunk {
+  chunk: {
+    seq: number;
+    type: 'snapshot';
+    field?: string;
+    data: unknown;
+  };
+}
+
+/** Progress chunk - progress update */
+export interface ProgressChunk {
+  progress: {
+    percent: number;
+    stage?: string;
+    message?: string;
+  };
+}
+
+/** Final chunk - completion signal */
+export interface FinalChunk {
+  final: true;
+  meta: EnvelopeMeta;
+  data: ModuleResultData;
+  usage?: {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/** Error chunk during streaming */
+export interface ErrorChunk {
+  ok: false;
+  streaming: true;
+  session_id?: string;
+  error: {
+    code: string;
+    message: string;
+    recoverable?: boolean;
+  };
+  partial_data?: unknown;
+}
+
+/** Union of all streaming chunk types */
+export type StreamingChunk = 
+  | MetaChunk 
+  | DeltaChunk 
+  | SnapshotChunk 
+  | ProgressChunk 
+  | FinalChunk 
+  | ErrorChunk;
+
+/** Streaming session state */
+export interface StreamingSession {
+  session_id: string;
+  module_name: string;
+  started_at: number;
+  chunks_sent: number;
+  accumulated_data: Record<string, unknown>;
+  accumulated_text: Record<string, string>;
+}
+
+// =============================================================================
+// v2.5 Multimodal Types
+// =============================================================================
+
+/** Supported modality types */
+export type ModalityType = 'text' | 'image' | 'audio' | 'video' | 'document';
+
+/** Modalities configuration in module.yaml */
+export interface ModalitiesConfig {
+  input: ModalityType[];
+  output: ModalityType[];
+  constraints?: MediaConstraints;
+}
+
+/** Media size/duration constraints */
+export interface MediaConstraints {
+  max_image_size_mb?: number;
+  max_audio_size_mb?: number;
+  max_video_size_mb?: number;
+  max_audio_duration_s?: number;
+  max_video_duration_s?: number;
+  allowed_image_types?: string[];
+  allowed_audio_types?: string[];
+  allowed_video_types?: string[];
+}
+
+/** Media input - URL reference */
+export interface UrlMediaInput {
+  type: 'url';
+  url: string;
+  media_type?: string;
+}
+
+/** Media input - Base64 inline */
+export interface Base64MediaInput {
+  type: 'base64';
+  media_type: string;
+  data: string;
+}
+
+/** Media input - File path */
+export interface FileMediaInput {
+  type: 'file';
+  path: string;
+}
+
+/** Union of media input types */
+export type MediaInput = UrlMediaInput | Base64MediaInput | FileMediaInput;
+
+/** Media output with metadata */
+export interface MediaOutput {
+  type: 'url' | 'base64' | 'file';
+  media_type: string;
+  url?: string;
+  data?: string;
+  path?: string;
+  width?: number;
+  height?: number;
+  duration_ms?: number;
+  expires_at?: string;
+  generation_params?: Record<string, unknown>;
+}
+
+/** Supported image MIME types */
+export const SUPPORTED_IMAGE_TYPES = [
+  'image/jpeg',
+  'image/png',
+  'image/webp',
+  'image/gif'
+] as const;
+
+/** Supported audio MIME types */
+export const SUPPORTED_AUDIO_TYPES = [
+  'audio/mpeg',
+  'audio/wav',
+  'audio/ogg',
+  'audio/webm'
+] as const;
+
+/** Supported video MIME types */
+export const SUPPORTED_VIDEO_TYPES = [
+  'video/mp4',
+  'video/webm',
+  'video/quicktime'
+] as const;
+
+// =============================================================================
+// v2.5 Error Codes
+// =============================================================================
+
+/** v2.5 Error codes for streaming and multimodal */
+export const ErrorCodesV25 = {
+  // Media errors (E1xxx)
+  UNSUPPORTED_MEDIA_TYPE: 'E1010',
+  MEDIA_TOO_LARGE: 'E1011',
+  MEDIA_FETCH_FAILED: 'E1012',
+  MEDIA_DECODE_FAILED: 'E1013',
+  
+  // Streaming errors (E2xxx)
+  STREAM_INTERRUPTED: 'E2010',
+  STREAM_TIMEOUT: 'E2011',
+  
+  // Capability errors (E4xxx)
+  STREAMING_NOT_SUPPORTED: 'E4010',
+  MULTIMODAL_NOT_SUPPORTED: 'E4011',
+} as const;
+
+export type ErrorCodeV25 = typeof ErrorCodesV25[keyof typeof ErrorCodesV25];
+
+// =============================================================================
+// v2.5 Runtime Capabilities
+// =============================================================================
+
+/** Runtime capability declaration */
+export interface RuntimeCapabilities {
+  streaming: boolean;
+  multimodal: {
+    input: ModalityType[];
+    output: ModalityType[];
+  };
+  max_media_size_mb: number;
+  supported_transports: ('sse' | 'websocket' | 'ndjson')[];
+}
+
+/** Default runtime capabilities */
+export const DEFAULT_RUNTIME_CAPABILITIES: RuntimeCapabilities = {
+  streaming: true,
+  multimodal: {
+    input: ['text', 'image'],
+    output: ['text']
+  },
+  max_media_size_mb: 20,
+  supported_transports: ['sse', 'ndjson']
+};
+
+// =============================================================================
+// v2.5 Extended Provider Interface
+// =============================================================================
+
+/** Extended invoke params with streaming support */
+export interface InvokeParamsV25 extends InvokeParams {
+  stream?: boolean;
+  images?: MediaInput[];
+  audio?: MediaInput[];
+  video?: MediaInput[];
+}
+
+/** Streaming invoke result */
+export interface StreamingInvokeResult {
+  stream: AsyncIterable<string>;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+/** Extended provider interface for v2.5 */
+export interface ProviderV25 extends Provider {
+  /** Check if provider supports streaming */
+  supportsStreaming?(): boolean;
+  
+  /** Check if provider supports multimodal input */
+  supportsMultimodal?(): { input: ModalityType[]; output: ModalityType[] };
+  
+  /** Invoke with streaming */
+  invokeStream?(params: InvokeParamsV25): Promise<StreamingInvokeResult>;
+}
+
+/** Type guard for v2.5 provider */
+export function isProviderV25(provider: Provider): provider is ProviderV25 {
+  return 'invokeStream' in provider || 'supportsStreaming' in provider;
+}
+
+// =============================================================================
+// v2.5 Module Configuration Extensions
+// =============================================================================
+
+/** Extended module interface for v2.5 */
+export interface CognitiveModuleV25 extends CognitiveModule {
+  /** v2.5: Response configuration */
+  response?: ResponseConfig;
+  
+  /** v2.5: Modalities configuration */
+  modalities?: ModalitiesConfig;
+}
+
+/** Type guard for v2.5 module */
+export function isModuleV25(module: CognitiveModule): module is CognitiveModuleV25 {
+  return 'response' in module || 'modalities' in module;
+}
+
+/** Check if module supports streaming */
+export function moduleSupportsStreaming(module: CognitiveModule): boolean {
+  if (!isModuleV25(module)) return false;
+  const mode = module.response?.mode;
+  return mode === 'streaming' || mode === 'both';
+}
+
+/** Check if module supports multimodal input */
+export function moduleSupportsMultimodal(module: CognitiveModule): boolean {
+  if (!isModuleV25(module)) return false;
+  const modalities = module.modalities?.input ?? ['text'];
+  return modalities.some(m => m !== 'text');
+}
+
+/** Get supported input modalities for module */
+export function getModuleInputModalities(module: CognitiveModule): ModalityType[] {
+  if (!isModuleV25(module)) return ['text'];
+  return module.modalities?.input ?? ['text'];
+}
+
+/** Get supported output modalities for module */
+export function getModuleOutputModalities(module: CognitiveModule): ModalityType[] {
+  if (!isModuleV25(module)) return ['text'];
+  return module.modalities?.output ?? ['text'];
+}