cognitive-runtime 0.1.0

package/src/modules/runner.ts

@@ -0,0 +1,121 @@
+/**
+ * Module Runner - Execute Cognitive Modules
+ */
+
+import type { Provider, CognitiveModule, ModuleResult, Message } from '../types.js';
+
+export interface RunOptions {
+  args?: string;
+  input?: Record<string, unknown>;
+  validateInput?: boolean;
+  validateOutput?: boolean;
+  verbose?: boolean;
+}
+
+export async function runModule(
+  module: CognitiveModule,
+  provider: Provider,
+  options: RunOptions = {}
+): Promise<ModuleResult> {
+  const { args, input, verbose = false } = options;
+
+  // Build input data
+  let inputData: Record<string, unknown> = input || {};
+  if (args) {
+    inputData = { $ARGUMENTS: args, query: args };
+  }
+
+  // Build prompt
+  const prompt = buildPrompt(module, inputData);
+
+  if (verbose) {
+    console.error('--- Prompt ---');
+    console.error(prompt);
+    console.error('--- End Prompt ---');
+  }
+
+  // Build messages
+  const messages: Message[] = [
+    {
+      role: 'system',
+      content: `You are executing the "${module.name}" Cognitive Module.
+
+RESPONSIBILITY: ${module.responsibility}
+
+YOU MUST NOT:
+${module.excludes.map(e => `- ${e}`).join('\n')}
+
+REQUIRED OUTPUT FORMAT:
+You MUST respond with a valid JSON object. Include these fields:
+- All fields required by the output schema
+- "confidence": a number between 0 and 1
+- "rationale": a string explaining your reasoning
+
+Respond with ONLY valid JSON, no markdown code blocks.`,
+    },
+    {
+      role: 'user',
+      content: prompt,
+    },
+  ];
+
+  // Invoke provider
+  const result = await provider.invoke({
+    messages,
+    jsonSchema: module.outputSchema,
+    temperature: 0.3,
+  });
+
+  if (verbose) {
+    console.error('--- Response ---');
+    console.error(result.content);
+    console.error('--- End Response ---');
+  }
+
+  // Parse response
+  let output: unknown;
+  try {
+    // Try to extract JSON from markdown code blocks
+    const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
+    output = JSON.parse(jsonStr.trim());
+  } catch {
+    throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
+  }
+
+  // Extract confidence and rationale
+  const outputObj = output as Record<string, unknown>;
+  const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
+  const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
+
+  return {
+    output,
+    confidence,
+    rationale,
+    raw: result.content,
+  };
+}
+
+function buildPrompt(module: CognitiveModule, inputData: Record<string, unknown>): string {
+  let prompt = module.prompt;
+
+  // Substitute $ARGUMENTS
+  const argsValue = String(inputData.$ARGUMENTS || inputData.query || '');
+  prompt = prompt.replace(/\$ARGUMENTS/g, argsValue);
+
+  // Substitute $N placeholders
+  const argsList = argsValue.split(/\s+/);
+  argsList.forEach((arg, i) => {
+    prompt = prompt.replace(new RegExp(`\\$${i}`, 'g'), arg);
+    prompt = prompt.replace(new RegExp(`\\$ARGUMENTS\\[${i}\\]`, 'g'), arg);
+  });
+
+  // Substitute other input fields
+  for (const [key, value] of Object.entries(inputData)) {
+    if (key !== '$ARGUMENTS' && key !== 'query') {
+      prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), String(value));
+    }
+  }
+
+  return prompt;
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,89 @@
+/**
+ * Anthropic Provider - Claude API
+ */
+
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+
+export class AnthropicProvider extends BaseProvider {
+  name = 'anthropic';
+  private apiKey: string;
+  private model: string;
+  private baseUrl = 'https://api.anthropic.com/v1';
+
+  constructor(apiKey?: string, model = 'claude-sonnet-4-20250514') {
+    super();
+    this.apiKey = apiKey || process.env.ANTHROPIC_API_KEY || '';
+    this.model = model;
+  }
+
+  isConfigured(): boolean {
+    return !!this.apiKey;
+  }
+
+  async invoke(params: InvokeParams): Promise<InvokeResult> {
+    if (!this.isConfigured()) {
+      throw new Error('Anthropic API key not configured. Set ANTHROPIC_API_KEY environment variable.');
+    }
+
+    const url = `${this.baseUrl}/messages`;
+
+    // Extract system message
+    const systemMessage = params.messages.find(m => m.role === 'system');
+    const otherMessages = params.messages.filter(m => m.role !== 'system');
+
+    // Add JSON schema instruction if provided
+    let messages = otherMessages;
+    if (params.jsonSchema) {
+      const lastUserIdx = messages.findLastIndex(m => m.role === 'user');
+      if (lastUserIdx >= 0) {
+        messages = [...messages];
+        messages[lastUserIdx] = {
+          ...messages[lastUserIdx],
+          content: messages[lastUserIdx].content + this.buildJsonPrompt(params.jsonSchema),
+        };
+      }
+    }
+
+    const body: Record<string, unknown> = {
+      model: this.model,
+      messages: messages.map(m => ({ role: m.role, content: m.content })),
+      max_tokens: params.maxTokens ?? 4096,
+    };
+
+    if (systemMessage) {
+      body.system = systemMessage.content;
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': this.apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Anthropic API error: ${response.status} - ${error}`);
+    }
+
+    const data = await response.json() as {
+      content?: Array<{ text?: string }>;
+      usage?: { input_tokens?: number; output_tokens?: number };
+    };
+    
+    const content = data.content?.[0]?.text || '';
+    
+    return {
+      content,
+      usage: data.usage ? {
+        promptTokens: data.usage.input_tokens || 0,
+        completionTokens: data.usage.output_tokens || 0,
+        totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+      } : undefined,
+    };
+  }
+}

package/src/providers/base.ts

@@ -0,0 +1,29 @@
+/**
+ * Base Provider - Abstract class for all LLM providers
+ */
+
+import type { Provider, InvokeParams, InvokeResult } from '../types.js';
+
+export abstract class BaseProvider implements Provider {
+  abstract name: string;
+  
+  abstract invoke(params: InvokeParams): Promise<InvokeResult>;
+  
+  abstract isConfigured(): boolean;
+
+  protected buildJsonPrompt(schema: object): string {
+    return `\n\nYou MUST respond with valid JSON matching this schema:\n${JSON.stringify(schema, null, 2)}\n\nRespond with ONLY the JSON, no markdown code blocks.`;
+  }
+
+  protected parseJsonResponse(content: string): unknown {
+    // Try to extract JSON from markdown code blocks
+    const jsonMatch = content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    const jsonStr = jsonMatch ? jsonMatch[1] : content;
+    
+    try {
+      return JSON.parse(jsonStr.trim());
+    } catch {
+      throw new Error(`Failed to parse JSON response: ${content.substring(0, 200)}`);
+    }
+  }
+}

package/src/providers/gemini.ts

@@ -0,0 +1,117 @@
+/**
+ * Gemini Provider - Google Gemini API
+ */
+
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+
+export class GeminiProvider extends BaseProvider {
+  name = 'gemini';
+  private apiKey: string;
+  private model: string;
+  private baseUrl = 'https://generativelanguage.googleapis.com/v1beta';
+
+  constructor(apiKey?: string, model = 'gemini-2.0-flash') {
+    super();
+    this.apiKey = apiKey || process.env.GEMINI_API_KEY || '';
+    this.model = model;
+  }
+
+  isConfigured(): boolean {
+    return !!this.apiKey;
+  }
+
+  /**
+   * Clean JSON Schema for Gemini API compatibility
+   * Removes unsupported fields like additionalProperties
+   */
+  private cleanSchemaForGemini(schema: object): object {
+    const unsupportedFields = ['additionalProperties', '$schema', 'default', 'examples'];
+    
+    const clean = (obj: unknown): unknown => {
+      if (Array.isArray(obj)) {
+        return obj.map(clean);
+      }
+      if (obj && typeof obj === 'object') {
+        const result: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(obj)) {
+          if (!unsupportedFields.includes(key)) {
+            result[key] = clean(value);
+          }
+        }
+        return result;
+      }
+      return obj;
+    };
+    
+    return clean(schema) as object;
+  }
+
+  async invoke(params: InvokeParams): Promise<InvokeResult> {
+    if (!this.isConfigured()) {
+      throw new Error('Gemini API key not configured. Set GEMINI_API_KEY environment variable.');
+    }
+
+    const url = `${this.baseUrl}/models/${this.model}:generateContent?key=${this.apiKey}`;
+
+    // Convert messages to Gemini format
+    const contents = params.messages
+      .filter(m => m.role !== 'system')
+      .map(m => ({
+        role: m.role === 'assistant' ? 'model' : 'user',
+        parts: [{ text: m.content }]
+      }));
+
+    // Add system instruction if present
+    const systemMessage = params.messages.find(m => m.role === 'system');
+    
+    const body: Record<string, unknown> = {
+      contents,
+      generationConfig: {
+        temperature: params.temperature ?? 0.7,
+        maxOutputTokens: params.maxTokens ?? 8192,
+      }
+    };
+
+    if (systemMessage) {
+      body.systemInstruction = { parts: [{ text: systemMessage.content }] };
+    }
+
+    // Add JSON schema constraint if provided
+    if (params.jsonSchema) {
+      const cleanedSchema = this.cleanSchemaForGemini(params.jsonSchema);
+      body.generationConfig = {
+        ...body.generationConfig as object,
+        responseMimeType: 'application/json',
+        responseSchema: cleanedSchema,
+      };
+    }
+
+    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(`Gemini API error: ${response.status} - ${error}`);
+    }
+
+    const data = await response.json() as {
+      candidates?: Array<{ content?: { parts?: Array<{ text?: string }> } }>;
+      usageMetadata?: { promptTokenCount?: number; candidatesTokenCount?: number; totalTokenCount?: number };
+    };
+    
+    const content = data.candidates?.[0]?.content?.parts?.[0]?.text || '';
+    
+    return {
+      content,
+      usage: data.usageMetadata ? {
+        promptTokens: data.usageMetadata.promptTokenCount || 0,
+        completionTokens: data.usageMetadata.candidatesTokenCount || 0,
+        totalTokens: data.usageMetadata.totalTokenCount || 0,
+      } : undefined,
+    };
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Provider Registry
+ */
+
+import type { Provider } from '../types.js';
+import { GeminiProvider } from './gemini.js';
+import { OpenAIProvider } from './openai.js';
+import { AnthropicProvider } from './anthropic.js';
+
+export { BaseProvider } from './base.js';
+export { GeminiProvider } from './gemini.js';
+export { OpenAIProvider } from './openai.js';
+export { AnthropicProvider } from './anthropic.js';
+
+const providers: Record<string, () => Provider> = {
+  gemini: () => new GeminiProvider(),
+  openai: () => new OpenAIProvider(),
+  anthropic: () => new AnthropicProvider(),
+};
+
+export function getProvider(name?: string): Provider {
+  // Auto-detect if not specified
+  if (!name) {
+    if (process.env.GEMINI_API_KEY) return new GeminiProvider();
+    if (process.env.OPENAI_API_KEY) return new OpenAIProvider();
+    if (process.env.ANTHROPIC_API_KEY) return new AnthropicProvider();
+    throw new Error('No LLM provider configured. Set GEMINI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY.');
+  }
+
+  const factory = providers[name.toLowerCase()];
+  if (!factory) {
+    throw new Error(`Unknown provider: ${name}. Available: ${Object.keys(providers).join(', ')}`);
+  }
+
+  return factory();
+}
+
+export function listProviders(): Array<{ name: string; configured: boolean }> {
+  return Object.entries(providers).map(([name, factory]) => ({
+    name,
+    configured: factory().isConfigured(),
+  }));
+}

package/src/providers/openai.ts

@@ -0,0 +1,84 @@
+/**
+ * OpenAI Provider - OpenAI API (and compatible APIs)
+ */
+
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+
+export class OpenAIProvider extends BaseProvider {
+  name = 'openai';
+  private apiKey: string;
+  private model: string;
+  private baseUrl: string;
+
+  constructor(apiKey?: string, model = 'gpt-4o', baseUrl = 'https://api.openai.com/v1') {
+    super();
+    this.apiKey = apiKey || process.env.OPENAI_API_KEY || '';
+    this.model = model;
+    this.baseUrl = baseUrl;
+  }
+
+  isConfigured(): boolean {
+    return !!this.apiKey;
+  }
+
+  async invoke(params: InvokeParams): Promise<InvokeResult> {
+    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: Record<string, unknown> = {
+      model: this.model,
+      messages: params.messages,
+      temperature: params.temperature ?? 0.7,
+      max_tokens: params.maxTokens ?? 4096,
+    };
+
+    // 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}`);
+    }
+
+    const data = await response.json() as {
+      choices?: Array<{ message?: { content?: string } }>;
+      usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+    };
+    
+    const content = data.choices?.[0]?.message?.content || '';
+    
+    return {
+      content,
+      usage: data.usage ? {
+        promptTokens: data.usage.prompt_tokens || 0,
+        completionTokens: data.usage.completion_tokens || 0,
+        totalTokens: data.usage.total_tokens || 0,
+      } : undefined,
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Cognitive Runtime - Core Types
+ */
+
+// Provider interface - all LLM providers implement this
+export interface Provider {
+  name: string;
+  invoke(params: InvokeParams): Promise<InvokeResult>;
+  isConfigured(): boolean;
+}
+
+export interface InvokeParams {
+  messages: Message[];
+  jsonSchema?: object;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface Message {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface InvokeResult {
+  content: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+// Module types
+export interface CognitiveModule {
+  name: string;
+  version: string;
+  responsibility: string;
+  excludes: string[];
+  context?: 'fork' | 'main';
+  prompt: string;
+  inputSchema?: object;
+  outputSchema?: object;
+  location: string;
+}
+
+export interface ModuleResult {
+  output: unknown;
+  confidence: number;
+  rationale: string;
+  raw?: string;
+}
+
+// Command types
+export interface CommandContext {
+  cwd: string;
+  provider: Provider;
+  verbose?: boolean;
+}
+
+export interface CommandResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}