cognitive-runtime 0.1.0

package/dist/modules/loader.js

@@ -0,0 +1,91 @@
+/**
+ * Module Loader - Load and parse Cognitive Modules
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
+export async function loadModule(modulePath) {
+    const moduleFile = path.join(modulePath, 'MODULE.md');
+    const schemaFile = path.join(modulePath, 'schema.json');
+    // Read MODULE.md
+    const moduleContent = await fs.readFile(moduleFile, 'utf-8');
+    // Parse frontmatter
+    const match = moduleContent.match(FRONTMATTER_REGEX);
+    if (!match) {
+        throw new Error(`Invalid MODULE.md: missing YAML frontmatter in ${moduleFile}`);
+    }
+    const frontmatter = yaml.load(match[1]);
+    const prompt = (match[2] || '').trim();
+    // Read schema.json
+    let inputSchema;
+    let outputSchema;
+    try {
+        const schemaContent = await fs.readFile(schemaFile, 'utf-8');
+        const schema = JSON.parse(schemaContent);
+        inputSchema = schema.input;
+        outputSchema = schema.output;
+    }
+    catch {
+        // Schema file is optional
+    }
+    return {
+        name: frontmatter.name || path.basename(modulePath),
+        version: frontmatter.version || '1.0.0',
+        responsibility: frontmatter.responsibility || '',
+        excludes: frontmatter.excludes || [],
+        context: frontmatter.context,
+        prompt,
+        inputSchema,
+        outputSchema,
+        location: modulePath,
+    };
+}
+export async function findModule(name, searchPaths) {
+    for (const basePath of searchPaths) {
+        const modulePath = path.join(basePath, name);
+        const moduleFile = path.join(modulePath, 'MODULE.md');
+        try {
+            await fs.access(moduleFile);
+            return await loadModule(modulePath);
+        }
+        catch {
+            // Module not found in this path, continue
+        }
+    }
+    return null;
+}
+export async function listModules(searchPaths) {
+    const modules = [];
+    for (const basePath of searchPaths) {
+        try {
+            const entries = await fs.readdir(basePath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const modulePath = path.join(basePath, entry.name);
+                    const moduleFile = path.join(modulePath, 'MODULE.md');
+                    try {
+                        await fs.access(moduleFile);
+                        const module = await loadModule(modulePath);
+                        modules.push(module);
+                    }
+                    catch {
+                        // Not a valid module, skip
+                    }
+                }
+            }
+        }
+        catch {
+            // Path doesn't exist, skip
+        }
+    }
+    return modules;
+}
+export function getDefaultSearchPaths(cwd) {
+    const home = process.env.HOME || '';
+    return [
+        path.join(cwd, 'cognitive', 'modules'),
+        path.join(cwd, '.cognitive', 'modules'),
+        path.join(home, '.cognitive', 'modules'),
+    ];
+}

package/dist/modules/runner.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Module Runner - Execute Cognitive Modules
+ */
+import type { Provider, CognitiveModule, ModuleResult } from '../types.js';
+export interface RunOptions {
+    args?: string;
+    input?: Record<string, unknown>;
+    validateInput?: boolean;
+    validateOutput?: boolean;
+    verbose?: boolean;
+}
+export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;

package/dist/modules/runner.js

@@ -0,0 +1,93 @@
+/**
+ * Module Runner - Execute Cognitive Modules
+ */
+export async function runModule(module, provider, options = {}) {
+    const { args, input, verbose = false } = options;
+    // Build input data
+    let inputData = 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 = [
+        {
+            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;
+    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;
+    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, inputData) {
+    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/dist/providers/anthropic.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Anthropic Provider - Claude API
+ */
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+export declare class AnthropicProvider extends BaseProvider {
+    name: string;
+    private apiKey;
+    private model;
+    private baseUrl;
+    constructor(apiKey?: string, model?: string);
+    isConfigured(): boolean;
+    invoke(params: InvokeParams): Promise<InvokeResult>;
+}

package/dist/providers/anthropic.js

@@ -0,0 +1,70 @@
+/**
+ * Anthropic Provider - Claude API
+ */
+import { BaseProvider } from './base.js';
+export class AnthropicProvider extends BaseProvider {
+    name = 'anthropic';
+    apiKey;
+    model;
+    baseUrl = 'https://api.anthropic.com/v1';
+    constructor(apiKey, model = 'claude-sonnet-4-20250514') {
+        super();
+        this.apiKey = apiKey || process.env.ANTHROPIC_API_KEY || '';
+        this.model = model;
+    }
+    isConfigured() {
+        return !!this.apiKey;
+    }
+    async invoke(params) {
+        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 = {
+            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();
+        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/dist/providers/base.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Base Provider - Abstract class for all LLM providers
+ */
+import type { Provider, InvokeParams, InvokeResult } from '../types.js';
+export declare abstract class BaseProvider implements Provider {
+    abstract name: string;
+    abstract invoke(params: InvokeParams): Promise<InvokeResult>;
+    abstract isConfigured(): boolean;
+    protected buildJsonPrompt(schema: object): string;
+    protected parseJsonResponse(content: string): unknown;
+}

package/dist/providers/base.js

@@ -0,0 +1,19 @@
+/**
+ * Base Provider - Abstract class for all LLM providers
+ */
+export class BaseProvider {
+    buildJsonPrompt(schema) {
+        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.`;
+    }
+    parseJsonResponse(content) {
+        // 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/dist/providers/gemini.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Gemini Provider - Google Gemini API
+ */
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+export declare class GeminiProvider extends BaseProvider {
+    name: string;
+    private apiKey;
+    private model;
+    private baseUrl;
+    constructor(apiKey?: string, model?: string);
+    isConfigured(): boolean;
+    /**
+     * Clean JSON Schema for Gemini API compatibility
+     * Removes unsupported fields like additionalProperties
+     */
+    private cleanSchemaForGemini;
+    invoke(params: InvokeParams): Promise<InvokeResult>;
+}

package/dist/providers/gemini.js

@@ -0,0 +1,94 @@
+/**
+ * Gemini Provider - Google Gemini API
+ */
+import { BaseProvider } from './base.js';
+export class GeminiProvider extends BaseProvider {
+    name = 'gemini';
+    apiKey;
+    model;
+    baseUrl = 'https://generativelanguage.googleapis.com/v1beta';
+    constructor(apiKey, model = 'gemini-2.0-flash') {
+        super();
+        this.apiKey = apiKey || process.env.GEMINI_API_KEY || '';
+        this.model = model;
+    }
+    isConfigured() {
+        return !!this.apiKey;
+    }
+    /**
+     * Clean JSON Schema for Gemini API compatibility
+     * Removes unsupported fields like additionalProperties
+     */
+    cleanSchemaForGemini(schema) {
+        const unsupportedFields = ['additionalProperties', '$schema', 'default', 'examples'];
+        const clean = (obj) => {
+            if (Array.isArray(obj)) {
+                return obj.map(clean);
+            }
+            if (obj && typeof obj === 'object') {
+                const result = {};
+                for (const [key, value] of Object.entries(obj)) {
+                    if (!unsupportedFields.includes(key)) {
+                        result[key] = clean(value);
+                    }
+                }
+                return result;
+            }
+            return obj;
+        };
+        return clean(schema);
+    }
+    async invoke(params) {
+        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 = {
+            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,
+                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();
+        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/dist/providers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Provider Registry
+ */
+import type { Provider } from '../types.js';
+export { BaseProvider } from './base.js';
+export { GeminiProvider } from './gemini.js';
+export { OpenAIProvider } from './openai.js';
+export { AnthropicProvider } from './anthropic.js';
+export declare function getProvider(name?: string): Provider;
+export declare function listProviders(): Array<{
+    name: string;
+    configured: boolean;
+}>;

package/dist/providers/index.js

@@ -0,0 +1,38 @@
+/**
+ * Provider Registry
+ */
+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 = {
+    gemini: () => new GeminiProvider(),
+    openai: () => new OpenAIProvider(),
+    anthropic: () => new AnthropicProvider(),
+};
+export function getProvider(name) {
+    // 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() {
+    return Object.entries(providers).map(([name, factory]) => ({
+        name,
+        configured: factory().isConfigured(),
+    }));
+}

package/dist/providers/openai.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenAI Provider - OpenAI API (and compatible APIs)
+ */
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+export declare class OpenAIProvider extends BaseProvider {
+    name: string;
+    private apiKey;
+    private model;
+    private baseUrl;
+    constructor(apiKey?: string, model?: string, baseUrl?: string);
+    isConfigured(): boolean;
+    invoke(params: InvokeParams): Promise<InvokeResult>;
+}

package/dist/providers/openai.js

@@ -0,0 +1,67 @@
+/**
+ * OpenAI Provider - OpenAI API (and compatible APIs)
+ */
+import { BaseProvider } from './base.js';
+export class OpenAIProvider extends BaseProvider {
+    name = 'openai';
+    apiKey;
+    model;
+    baseUrl;
+    constructor(apiKey, 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() {
+        return !!this.apiKey;
+    }
+    async invoke(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,
+        };
+        // 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();
+        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/dist/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Cognitive Runtime - Core Types
+ */
+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;
+    };
+}
+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;
+}
+export interface CommandContext {
+    cwd: string;
+    provider: Provider;
+    verbose?: boolean;
+}
+export interface CommandResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Cognitive Runtime - Core Types
+ */
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cognitive-runtime",
+  "version": "0.1.0",
+  "description": "Cognitive Runtime - Structured AI Task Execution",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "cog": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsx src/cli.ts"
+  },
+  "keywords": [
+    "cognitive",
+    "ai",
+    "llm",
+    "structured",
+    "modules"
+  ],
+  "license": "MIT",
+  "author": "",
+  "dependencies": {
+    "js-yaml": "^4.1.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.1.0"
+  }
+}