cognitive-runtime 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# Cognitive Runtime
+
+**Structured AI Task Execution**
+
+Cognitive Runtime is the next-generation execution engine for Cognitive Modules. It provides a clean, provider-agnostic runtime that treats LLMs as interchangeable backends.
+
+## Philosophy
+
+Following the **Cognitive Runtime + Provider** architecture:
+
+```
+┌─────────────────────────────────────┐
+│         Cognitive Runtime           │
+│  ┌────────────────────────────────┐ │
+│  │     Module System              │ │
+│  │  (load, parse, validate)       │ │
+│  └────────────────────────────────┘ │
+│  ┌────────────────────────────────┐ │
+│  │     Execution Engine           │ │
+│  │  (prompt, schema, contract)    │ │
+│  └────────────────────────────────┘ │
+│  ┌────────────────────────────────┐ │
+│  │     Provider Abstraction       │ │
+│  │  (gemini, openai, anthropic)   │ │
+│  └────────────────────────────────┘ │
+└─────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+npm install -g cognitive-runtime
+```
+
+Or run directly:
+
+```bash
+npx cognitive-runtime --help
+```
+
+## Usage
+
+### Run a Module
+
+```bash
+cog run code-reviewer --args "def foo(): pass"
+```
+
+### List Modules
+
+```bash
+cog list
+```
+
+### Pipe Mode (stdin/stdout)
+
+```bash
+echo "review this code" | cog pipe --module code-reviewer
+```
+
+### Check Configuration
+
+```bash
+cog doctor
+```
+
+## Configuration
+
+Set one of these environment variables:
+
+```bash
+export GEMINI_API_KEY="your-key"      # Google Gemini
+export OPENAI_API_KEY="your-key"      # OpenAI
+export ANTHROPIC_API_KEY="your-key"   # Anthropic Claude
+```
+
+## Module Search Paths
+
+Modules are searched in order:
+
+1. `./cognitive/modules/` (project-local)
+2. `./.cognitive/modules/` (project-local, hidden)
+3. `~/.cognitive/modules/` (user-global)
+
+## Programmatic API
+
+```typescript
+import { getProvider, findModule, runModule } from 'cognitive-runtime';
+
+const provider = getProvider('gemini');
+const module = await findModule('code-reviewer', ['./cognitive/modules']);
+
+if (module) {
+  const result = await runModule(module, provider, {
+    args: 'def foo(): pass',
+  });
+  console.log(result.output);
+}
+```
+
+## Providers
+
+| Provider   | Environment Variable   | Model Default          |
+|------------|------------------------|------------------------|
+| Gemini     | `GEMINI_API_KEY`       | `gemini-2.0-flash`     |
+| OpenAI     | `OPENAI_API_KEY`       | `gpt-4o`               |
+| Anthropic  | `ANTHROPIC_API_KEY`    | `claude-sonnet-4`      |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run in development
+npm run dev -- run code-reviewer --args "..."
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Cognitive Runtime CLI
+ *
+ * cog run <module> --args "..."  - Run a module
+ * cog list                        - List available modules
+ * cog pipe --module <name>        - Pipe mode (stdin/stdout)
+ * cog doctor                      - Check configuration
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Cognitive Runtime CLI
+ *
+ * cog run <module> --args "..."  - Run a module
+ * cog list                        - List available modules
+ * cog pipe --module <name>        - Pipe mode (stdin/stdout)
+ * cog doctor                      - Check configuration
+ */
+import { parseArgs } from 'node:util';
+import { getProvider, listProviders } from './providers/index.js';
+import { run, list, pipe, init } from './commands/index.js';
+const VERSION = '0.1.0';
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === '--help' || command === '-h') {
+        printHelp();
+        process.exit(0);
+    }
+    if (command === '--version' || command === '-v') {
+        console.log(`Cognitive Runtime v${VERSION}`);
+        process.exit(0);
+    }
+    // Parse common options
+    const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+            args: { type: 'string', short: 'a' },
+            input: { type: 'string', short: 'i' },
+            module: { type: 'string', short: 'm' },
+            provider: { type: 'string', short: 'p' },
+            pretty: { type: 'boolean', default: false },
+            verbose: { type: 'boolean', short: 'V', default: false },
+            'no-validate': { type: 'boolean', default: false },
+        },
+        allowPositionals: true,
+    });
+    // Get provider
+    let provider;
+    try {
+        provider = getProvider(values.provider);
+    }
+    catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+    const ctx = {
+        cwd: process.cwd(),
+        provider,
+        verbose: values.verbose,
+    };
+    try {
+        switch (command) {
+            case 'run': {
+                const moduleName = args[1];
+                if (!moduleName || moduleName.startsWith('-')) {
+                    console.error('Usage: cog run <module> [--args "..."]');
+                    process.exit(1);
+                }
+                const result = await run(moduleName, ctx, {
+                    args: values.args,
+                    input: values.input,
+                    noValidate: values['no-validate'],
+                    pretty: values.pretty,
+                    verbose: values.verbose,
+                });
+                if (!result.success) {
+                    console.error(`Error: ${result.error}`);
+                    process.exit(1);
+                }
+                console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+                break;
+            }
+            case 'list': {
+                const result = await list(ctx);
+                if (!result.success) {
+                    console.error(`Error: ${result.error}`);
+                    process.exit(1);
+                }
+                const data = result.data;
+                if (data.modules.length === 0) {
+                    console.log('No modules found.');
+                }
+                else {
+                    console.log('Available Modules:');
+                    console.log('');
+                    for (const m of data.modules) {
+                        console.log(`  ${m.name} (v${m.version})`);
+                        console.log(`    ${m.responsibility}`);
+                        console.log(`    ${m.location}`);
+                        console.log('');
+                    }
+                }
+                break;
+            }
+            case 'pipe': {
+                const moduleName = values.module || args[1];
+                if (!moduleName) {
+                    console.error('Usage: cog pipe --module <name>');
+                    process.exit(1);
+                }
+                await pipe(ctx, {
+                    module: moduleName,
+                    noValidate: values['no-validate'],
+                });
+                break;
+            }
+            case 'init': {
+                const moduleName = args[1];
+                const result = await init(ctx, moduleName);
+                if (!result.success) {
+                    console.error(`Error: ${result.error}`);
+                    process.exit(1);
+                }
+                const data = result.data;
+                console.log(data.message);
+                console.log(`  Location: ${data.location}`);
+                if (data.files) {
+                    console.log(`  Files: ${data.files.join(', ')}`);
+                }
+                if (data.hint) {
+                    console.log(`  ${data.hint}`);
+                }
+                break;
+            }
+            case 'doctor': {
+                console.log('Cognitive Runtime - Environment Check\n');
+                console.log('Providers:');
+                for (const p of listProviders()) {
+                    const status = p.configured ? '✓ configured' : '– not configured';
+                    console.log(`  ${p.name}: ${status}`);
+                }
+                console.log('');
+                try {
+                    const provider = getProvider();
+                    console.log(`Active provider: ${provider.name}`);
+                }
+                catch {
+                    console.log('Active provider: none (set an API key)');
+                }
+                break;
+            }
+            default:
+                console.error(`Unknown command: ${command}`);
+                console.error('Run "cog --help" for usage.');
+                process.exit(1);
+        }
+    }
+    catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : e}`);
+        if (values.verbose && e instanceof Error) {
+            console.error(e.stack);
+        }
+        process.exit(1);
+    }
+}
+function printHelp() {
+    console.log(`
+Cognitive Runtime v${VERSION}
+Structured AI Task Execution
+
+USAGE:
+  cog <command> [options]
+
+COMMANDS:
+  run <module>      Run a Cognitive Module
+  list              List available modules
+  pipe              Pipe mode (stdin/stdout)
+  init [name]       Initialize project or create module
+  doctor            Check configuration
+
+OPTIONS:
+  -a, --args <str>      Arguments to pass to module
+  -i, --input <json>    JSON input for module
+  -m, --module <name>   Module name (for pipe)
+  -p, --provider <name> LLM provider (gemini, openai, anthropic)
+  --pretty              Pretty-print JSON output
+  -V, --verbose         Verbose output
+  --no-validate         Skip schema validation
+  -v, --version         Show version
+  -h, --help            Show this help
+
+EXAMPLES:
+  cog run code-reviewer --args "def foo(): pass"
+  cog list
+  echo "review this code" | cog pipe --module code-reviewer
+  cog init my-module
+  cog doctor
+
+ENVIRONMENT:
+  GEMINI_API_KEY      Google Gemini API key
+  OPENAI_API_KEY      OpenAI API key
+  ANTHROPIC_API_KEY   Anthropic API key
+`);
+}
+main().catch(e => {
+    console.error('Fatal error:', e);
+    process.exit(1);
+});

package/dist/commands/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Commands - Re-export all commands
+ */
+export * from './run.js';
+export * from './list.js';
+export * from './pipe.js';
+export * from './init.js';

package/dist/commands/index.js

@@ -0,0 +1,7 @@
+/**
+ * Commands - Re-export all commands
+ */
+export * from './run.js';
+export * from './list.js';
+export * from './pipe.js';
+export * from './init.js';

package/dist/commands/init.d.ts

@@ -0,0 +1,5 @@
+/**
+ * cog init - Initialize a new Cognitive project
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export declare function init(ctx: CommandContext, moduleName?: string): Promise<CommandResult>;

package/dist/commands/init.js

@@ -0,0 +1,78 @@
+/**
+ * cog init - Initialize a new Cognitive project
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+const EXAMPLE_MODULE_MD = `---
+name: my-module
+version: 1.0.0
+responsibility: Describe what this module does
+excludes:
+  - Do not do X
+  - Do not do Y
+---
+
+Analyze the following input and provide a structured response:
+
+$ARGUMENTS
+
+Return a JSON object with your analysis.
+`;
+const EXAMPLE_SCHEMA_JSON = `{
+  "type": "object",
+  "properties": {
+    "result": {
+      "type": "string",
+      "description": "The main result of the analysis"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Confidence score"
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Explanation of the reasoning"
+    }
+  },
+  "required": ["result", "confidence", "rationale"]
+}
+`;
+export async function init(ctx, moduleName) {
+    const cognitiveDir = path.join(ctx.cwd, 'cognitive', 'modules');
+    try {
+        // Create directory structure
+        await fs.mkdir(cognitiveDir, { recursive: true });
+        // If module name provided, create a new module
+        if (moduleName) {
+            const moduleDir = path.join(cognitiveDir, moduleName);
+            await fs.mkdir(moduleDir, { recursive: true });
+            await fs.writeFile(path.join(moduleDir, 'MODULE.md'), EXAMPLE_MODULE_MD.replace('my-module', moduleName));
+            await fs.writeFile(path.join(moduleDir, 'schema.json'), EXAMPLE_SCHEMA_JSON);
+            return {
+                success: true,
+                data: {
+                    message: `Created module: ${moduleName}`,
+                    location: moduleDir,
+                    files: ['MODULE.md', 'schema.json'],
+                },
+            };
+        }
+        // Just initialize the directory
+        return {
+            success: true,
+            data: {
+                message: 'Cognitive project initialized',
+                location: cognitiveDir,
+                hint: 'Run "cog init <module-name>" to create a new module',
+            },
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,5 @@
+/**
+ * cog list - List available Cognitive Modules
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export declare function list(ctx: CommandContext): Promise<CommandResult>;

package/dist/commands/list.js

@@ -0,0 +1,28 @@
+/**
+ * cog list - List available Cognitive Modules
+ */
+import { listModules, getDefaultSearchPaths } from '../modules/index.js';
+export async function list(ctx) {
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    const modules = await listModules(searchPaths);
+    if (modules.length === 0) {
+        return {
+            success: true,
+            data: {
+                modules: [],
+                message: `No modules found in: ${searchPaths.join(', ')}`,
+            },
+        };
+    }
+    return {
+        success: true,
+        data: {
+            modules: modules.map(m => ({
+                name: m.name,
+                version: m.version,
+                responsibility: m.responsibility,
+                location: m.location,
+            })),
+        },
+    };
+}

package/dist/commands/pipe.d.ts

@@ -0,0 +1,9 @@
+/**
+ * cog pipe - Pipe mode for stdin/stdout integration
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface PipeOptions {
+    module: string;
+    noValidate?: boolean;
+}
+export declare function pipe(ctx: CommandContext, options: PipeOptions): Promise<CommandResult>;

package/dist/commands/pipe.js

@@ -0,0 +1,57 @@
+/**
+ * cog pipe - Pipe mode for stdin/stdout integration
+ */
+import * as readline from 'node:readline';
+import { findModule, getDefaultSearchPaths, runModule } from '../modules/index.js';
+export async function pipe(ctx, options) {
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    // Find module
+    const module = await findModule(options.module, searchPaths);
+    if (!module) {
+        return {
+            success: false,
+            error: `Module not found: ${options.module}`,
+        };
+    }
+    // Read from stdin
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false,
+    });
+    const lines = [];
+    for await (const line of rl) {
+        lines.push(line);
+    }
+    const input = lines.join('\n');
+    try {
+        // Check if input is JSON
+        let inputData;
+        try {
+            inputData = JSON.parse(input);
+        }
+        catch {
+            // Not JSON, use as args
+        }
+        const result = await runModule(module, ctx.provider, {
+            args: inputData ? undefined : input,
+            input: inputData,
+            validateInput: !options.noValidate,
+            validateOutput: !options.noValidate,
+        });
+        // Output JSON to stdout
+        console.log(JSON.stringify(result.output));
+        return {
+            success: true,
+            data: result,
+        };
+    }
+    catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        console.error(JSON.stringify({ error }));
+        return {
+            success: false,
+            error,
+        };
+    }
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,12 @@
+/**
+ * cog run - Run a Cognitive Module
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface RunOptions {
+    args?: string;
+    input?: string;
+    noValidate?: boolean;
+    pretty?: boolean;
+    verbose?: boolean;
+}
+export declare function run(moduleName: string, ctx: CommandContext, options?: RunOptions): Promise<CommandResult>;

package/dist/commands/run.js

@@ -0,0 +1,48 @@
+/**
+ * cog run - Run a Cognitive Module
+ */
+import { findModule, getDefaultSearchPaths, runModule } from '../modules/index.js';
+export async function run(moduleName, ctx, options = {}) {
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    // Find module
+    const module = await findModule(moduleName, searchPaths);
+    if (!module) {
+        return {
+            success: false,
+            error: `Module not found: ${moduleName}\nSearch paths: ${searchPaths.join(', ')}`,
+        };
+    }
+    try {
+        // Parse input if provided as JSON
+        let inputData;
+        if (options.input) {
+            try {
+                inputData = JSON.parse(options.input);
+            }
+            catch {
+                return {
+                    success: false,
+                    error: `Invalid JSON input: ${options.input}`,
+                };
+            }
+        }
+        // Run module
+        const result = await runModule(module, ctx.provider, {
+            args: options.args,
+            input: inputData,
+            validateInput: !options.noValidate,
+            validateOutput: !options.noValidate,
+            verbose: options.verbose || ctx.verbose,
+        });
+        return {
+            success: true,
+            data: options.pretty ? result : result.output,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Cognitive Runtime - Main Entry Point
+ *
+ * Exports all public APIs for programmatic use.
+ */
+export type { Provider, InvokeParams, InvokeResult, Message, CognitiveModule, ModuleResult, CommandContext, CommandResult, } from './types.js';
+export { getProvider, listProviders, GeminiProvider, OpenAIProvider, AnthropicProvider, BaseProvider, } from './providers/index.js';
+export { loadModule, findModule, listModules, getDefaultSearchPaths, runModule, } from './modules/index.js';
+export { run, list, pipe } from './commands/index.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Cognitive Runtime - Main Entry Point
+ *
+ * Exports all public APIs for programmatic use.
+ */
+// Providers
+export { getProvider, listProviders, GeminiProvider, OpenAIProvider, AnthropicProvider, BaseProvider, } from './providers/index.js';
+// Modules
+export { loadModule, findModule, listModules, getDefaultSearchPaths, runModule, } from './modules/index.js';
+// Commands
+export { run, list, pipe } from './commands/index.js';

package/dist/modules/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Modules - Re-export all module functionality
+ */
+export * from './loader.js';
+export * from './runner.js';

package/dist/modules/index.js

@@ -0,0 +1,5 @@
+/**
+ * Modules - Re-export all module functionality
+ */
+export * from './loader.js';
+export * from './runner.js';

package/dist/modules/loader.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Module Loader - Load and parse Cognitive Modules
+ */
+import type { CognitiveModule } from '../types.js';
+export declare function loadModule(modulePath: string): Promise<CognitiveModule>;
+export declare function findModule(name: string, searchPaths: string[]): Promise<CognitiveModule | null>;
+export declare function listModules(searchPaths: string[]): Promise<CognitiveModule[]>;
+export declare function getDefaultSearchPaths(cwd: string): string[];