confused-ai-core 0.1.0

package/src/artifacts/media.ts

@@ -0,0 +1,304 @@
+/**
+ * Media Artifacts - Agno-Style Image, Audio, Video Support
+ *
+ * Production-grade media handling:
+ * - Image generation and storage
+ * - Audio transcription and synthesis artifacts
+ * - Video processing artifacts
+ * - URL and base64 support
+ */
+
+import type { ArtifactStorage, BinaryArtifact, ArtifactMetadata } from './artifact.js';
+
+/** Image generation result */
+export interface ImageArtifact extends Omit<BinaryArtifact, 'type'> {
+    type: 'image';
+    /** Image width in pixels */
+    readonly width?: number;
+    /** Image height in pixels */
+    readonly height?: number;
+    /** Generation prompt (if AI-generated) */
+    readonly prompt?: string;
+    /** Negative prompt (if applicable) */
+    readonly negativePrompt?: string;
+    /** Model used for generation */
+    readonly model?: string;
+    /** Seed for reproducibility */
+    readonly seed?: number;
+}
+
+/** Audio artifact */
+export interface AudioArtifact extends Omit<BinaryArtifact, 'type'> {
+    type: 'audio';
+    /** Duration in seconds */
+    readonly durationSeconds?: number;
+    /** Sample rate in Hz */
+    readonly sampleRate?: number;
+    /** Number of channels */
+    readonly channels?: number;
+    /** Transcript (if available) */
+    readonly transcript?: string;
+    /** Voice ID (for TTS) */
+    readonly voiceId?: string;
+}
+
+/** Video artifact */
+export interface VideoArtifact extends Omit<BinaryArtifact, 'type'> {
+    type: 'video';
+    /** Duration in seconds */
+    readonly durationSeconds?: number;
+    /** Width in pixels */
+    readonly width?: number;
+    /** Height in pixels */
+    readonly height?: number;
+    /** Frame rate */
+    readonly fps?: number;
+    /** Thumbnail URL */
+    readonly thumbnailUrl?: string;
+}
+
+// --- Media Artifact Helpers ---
+
+/**
+ * Create an image artifact from URL
+ */
+export function createImageFromUrl(
+    name: string,
+    url: string,
+    options?: {
+        width?: number;
+        height?: number;
+        prompt?: string;
+        model?: string;
+        tags?: string[];
+    }
+): Omit<ImageArtifact, 'id' | 'createdAt' | 'updatedAt' | 'version'> {
+    return {
+        name,
+        type: 'image',
+        content: url,
+        url,
+        mimeType: guessImageMimeType(url),
+        width: options?.width,
+        height: options?.height,
+        prompt: options?.prompt,
+        model: options?.model,
+        tags: options?.tags,
+    };
+}
+
+/**
+ * Create an image artifact from base64
+ */
+export function createImageFromBase64(
+    name: string,
+    base64: string,
+    mimeType: string,
+    options?: {
+        width?: number;
+        height?: number;
+        prompt?: string;
+        model?: string;
+        tags?: string[];
+    }
+): Omit<ImageArtifact, 'id' | 'createdAt' | 'updatedAt' | 'version'> {
+    return {
+        name,
+        type: 'image',
+        content: base64,
+        base64,
+        mimeType,
+        width: options?.width,
+        height: options?.height,
+        prompt: options?.prompt,
+        model: options?.model,
+        tags: options?.tags,
+    };
+}
+
+/**
+ * Create an audio artifact from URL
+ */
+export function createAudioFromUrl(
+    name: string,
+    url: string,
+    options?: {
+        durationSeconds?: number;
+        transcript?: string;
+        voiceId?: string;
+        tags?: string[];
+    }
+): Omit<AudioArtifact, 'id' | 'createdAt' | 'updatedAt' | 'version'> {
+    return {
+        name,
+        type: 'audio',
+        content: url,
+        url,
+        mimeType: guessAudioMimeType(url),
+        durationSeconds: options?.durationSeconds,
+        transcript: options?.transcript,
+        voiceId: options?.voiceId,
+        tags: options?.tags,
+    };
+}
+
+/**
+ * Create a video artifact from URL
+ */
+export function createVideoFromUrl(
+    name: string,
+    url: string,
+    options?: {
+        durationSeconds?: number;
+        width?: number;
+        height?: number;
+        fps?: number;
+        thumbnailUrl?: string;
+        tags?: string[];
+    }
+): Omit<VideoArtifact, 'id' | 'createdAt' | 'updatedAt' | 'version'> {
+    return {
+        name,
+        type: 'video',
+        content: url,
+        url,
+        mimeType: guessVideoMimeType(url),
+        durationSeconds: options?.durationSeconds,
+        width: options?.width,
+        height: options?.height,
+        fps: options?.fps,
+        thumbnailUrl: options?.thumbnailUrl,
+        tags: options?.tags,
+    };
+}
+
+// --- Media Manager ---
+
+/**
+ * MediaManager - handles media artifact operations
+ */
+export class MediaManager {
+    constructor(private readonly storage: ArtifactStorage) { }
+
+    /** Save an image artifact */
+    async saveImage(
+        name: string,
+        source: string | { base64: string; mimeType: string },
+        options?: {
+            width?: number;
+            height?: number;
+            prompt?: string;
+            model?: string;
+            tags?: string[];
+        }
+    ): Promise<ImageArtifact> {
+        const artifact = typeof source === 'string'
+            ? createImageFromUrl(name, source, options)
+            : createImageFromBase64(name, source.base64, source.mimeType, options);
+
+        return await this.storage.save(artifact) as ImageArtifact;
+    }
+
+    /** Save an audio artifact */
+    async saveAudio(
+        name: string,
+        url: string,
+        options?: {
+            durationSeconds?: number;
+            transcript?: string;
+            voiceId?: string;
+            tags?: string[];
+        }
+    ): Promise<AudioArtifact> {
+        const artifact = createAudioFromUrl(name, url, options);
+        return await this.storage.save(artifact) as AudioArtifact;
+    }
+
+    /** Save a video artifact */
+    async saveVideo(
+        name: string,
+        url: string,
+        options?: {
+            durationSeconds?: number;
+            width?: number;
+            height?: number;
+            fps?: number;
+            thumbnailUrl?: string;
+            tags?: string[];
+        }
+    ): Promise<VideoArtifact> {
+        const artifact = createVideoFromUrl(name, url, options);
+        return await this.storage.save(artifact) as VideoArtifact;
+    }
+
+    /** Get an image by ID */
+    async getImage(id: string): Promise<ImageArtifact | null> {
+        return await this.storage.get<ImageArtifact['content']>(id) as ImageArtifact | null;
+    }
+
+    /** Get an audio by ID */
+    async getAudio(id: string): Promise<AudioArtifact | null> {
+        return await this.storage.get<AudioArtifact['content']>(id) as AudioArtifact | null;
+    }
+
+    /** Get a video by ID */
+    async getVideo(id: string): Promise<VideoArtifact | null> {
+        return await this.storage.get<VideoArtifact['content']>(id) as VideoArtifact | null;
+    }
+
+    /** List all images */
+    async listImages(limit?: number): Promise<ArtifactMetadata[]> {
+        return await this.storage.list({ type: 'image', limit });
+    }
+
+    /** List all audio */
+    async listAudio(limit?: number): Promise<ArtifactMetadata[]> {
+        return await this.storage.list({ type: 'audio', limit });
+    }
+
+    /** List all videos */
+    async listVideos(limit?: number): Promise<ArtifactMetadata[]> {
+        return await this.storage.list({ type: 'video', limit });
+    }
+}
+
+// --- Helpers ---
+
+function guessImageMimeType(url: string): string {
+    const ext = url.split('.').pop()?.toLowerCase();
+    const mimeTypes: Record<string, string> = {
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        png: 'image/png',
+        gif: 'image/gif',
+        webp: 'image/webp',
+        svg: 'image/svg+xml',
+        bmp: 'image/bmp',
+    };
+    return mimeTypes[ext ?? ''] ?? 'image/png';
+}
+
+function guessAudioMimeType(url: string): string {
+    const ext = url.split('.').pop()?.toLowerCase();
+    const mimeTypes: Record<string, string> = {
+        mp3: 'audio/mpeg',
+        wav: 'audio/wav',
+        ogg: 'audio/ogg',
+        flac: 'audio/flac',
+        aac: 'audio/aac',
+        m4a: 'audio/mp4',
+    };
+    return mimeTypes[ext ?? ''] ?? 'audio/mpeg';
+}
+
+function guessVideoMimeType(url: string): string {
+    const ext = url.split('.').pop()?.toLowerCase();
+    const mimeTypes: Record<string, string> = {
+        mp4: 'video/mp4',
+        webm: 'video/webm',
+        mov: 'video/quicktime',
+        avi: 'video/x-msvideo',
+        mkv: 'video/x-matroska',
+    };
+    return mimeTypes[ext ?? ''] ?? 'video/mp4';
+}

package/src/cli/index.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for Agent Framework
+ */
+
+import { Command } from 'commander';
+import { VERSION } from '../index.js';
+
+const program = new Command();
+
+program
+    .name('agent-framework')
+    .description('CLI for Agent Framework - A production-grade TypeScript agent framework')
+    .version(VERSION);
+
+// Create agent command
+program
+    .command('create')
+    .description('Create a new agent project')
+    .argument('<name>', 'Project name')
+    .option('-t, --template <template>', 'Project template', 'basic')
+    .option('-d, --directory <directory>', 'Target directory')
+    .action(async (name, options) => {
+        console.log(`Creating new agent project: ${name}`);
+        console.log(`Template: ${options.template}`);
+        console.log(`Directory: ${options.directory ?? name}`);
+        // TODO: Implement project scaffolding
+    });
+
+// Run agent command
+program
+    .command('run')
+    .description('Run an agent')
+    .argument('<file>', 'Agent file path')
+    .option('-i, --input <input>', 'Input prompt')
+    .option('-w, --watch', 'Watch for changes', false)
+    .action(async (file, options) => {
+        console.log(`Running agent: ${file}`);
+        if (options.input) {
+            console.log(`Input: ${options.input}`);
+        }
+        // TODO: Implement agent runner
+    });
+
+// Test command
+program
+    .command('test')
+    .description('Run agent tests')
+    .argument('[pattern]', 'Test file pattern')
+    .option('-w, --watch', 'Watch mode', false)
+    .option('-c, --coverage', 'Generate coverage report', false)
+    .action(async (pattern, _options) => {
+        console.log('Running tests...');
+        if (pattern) {
+            console.log(`Pattern: ${pattern}`);
+        }
+        // TODO: Implement test runner
+    });
+
+// Validate command
+program
+    .command('validate')
+    .description('Validate agent configuration')
+    .argument('<file>', 'Configuration file path')
+    .action(async (file) => {
+        console.log(`Validating: ${file}`);
+        // TODO: Implement validation
+    });
+
+// Plan command
+program
+    .command('plan')
+    .description('Generate execution plan for a goal')
+    .argument('<goal>', 'Goal to plan')
+    .option('-p, --planner <planner>', 'Planner type', 'classical')
+    .option('-o, --output <output>', 'Output file')
+    .action(async (goal, options) => {
+        console.log(`Planning: ${goal}`);
+        console.log(`Planner: ${options.planner}`);
+        // TODO: Implement plan generation
+    });
+
+// Execute command
+program
+    .command('execute')
+    .description('Execute a plan')
+    .argument('<file>', 'Plan file path')
+    .option('-p, --parallel', 'Enable parallel execution', false)
+    .option('-c, --concurrency <number>', 'Max concurrency', '4')
+    .action(async (file, options) => {
+        console.log(`Executing plan: ${file}`);
+        console.log(`Parallel: ${options.parallel}`);
+        console.log(`Concurrency: ${options.concurrency}`);
+        // TODO: Implement plan execution
+    });
+
+// List templates command
+program
+    .command('list-templates')
+    .description('List available project templates')
+    .action(() => {
+        console.log('Available templates:');
+        console.log('  - basic: Simple agent with minimal setup');
+        console.log('  - advanced: Agent with memory, tools, and planning');
+        console.log('  - multi-agent: Multi-agent orchestration setup');
+        console.log('  - workflow: Workflow-based agent system');
+    });
+
+// Doctor command
+program
+    .command('doctor')
+    .description('Check environment and dependencies')
+    .action(() => {
+        console.log('Checking environment...');
+        console.log(`Node.js version: ${process.version}`);
+        console.log(`Platform: ${process.platform}`);
+        console.log(`Architecture: ${process.arch}`);
+        // TODO: Implement environment checks
+    });
+
+program.parse();

package/src/core/base-agent.ts

@@ -0,0 +1,151 @@
+/**
+ * Base agent implementation
+ */
+
+import {
+    Agent,
+    AgentConfig,
+    AgentContext,
+    AgentInput,
+    AgentOutput,
+    AgentState,
+    ExecutionMetadata,
+} from './types.js';
+import { DebugLogger, createDebugLogger } from '../debug-logger.js';
+
+/**
+ * Abstract base class providing common agent functionality
+ */
+export abstract class BaseAgent extends Agent {
+    protected startTime?: Date;
+    protected iterationCount = 0;
+    protected logger: DebugLogger;
+
+    constructor(config: AgentConfig) {
+        super(config);
+        this.logger = createDebugLogger(`Agent:${this.name}`, config.debug ?? false);
+    }
+
+    /**
+     * Main execution method with lifecycle hooks
+     */
+    async run(input: AgentInput, ctx: AgentContext): Promise<AgentOutput> {
+        this.startTime = new Date();
+        this.iterationCount = 0;
+
+        this.logger.logStart('Agent execution', {
+            agentId: this.id,
+            prompt: input.prompt.slice(0, 100),
+        });
+
+        try {
+            // Before execution hook
+            if (this.hooks.beforeExecution) {
+                this.logger.debug('Running beforeExecution hook');
+                await this.hooks.beforeExecution(input, ctx);
+            }
+
+            // Set state to planning
+            this.logger.logStateChange('Agent', this.state, AgentState.PLANNING);
+            await this.setState(AgentState.PLANNING, ctx);
+
+            // Execute the agent-specific logic
+            this.logger.debug('Executing agent logic');
+            const result = await this.execute(input, ctx);
+
+            // Set state to completed
+            this.logger.logStateChange('Agent', this.state, AgentState.COMPLETED);
+            await this.setState(AgentState.COMPLETED, ctx);
+
+            const output = this.createOutput(result, AgentState.COMPLETED);
+
+            // After execution hook
+            if (this.hooks.afterExecution) {
+                this.logger.debug('Running afterExecution hook');
+                await this.hooks.afterExecution(output, ctx);
+            }
+
+            this.logger.logComplete('Agent execution', output.metadata?.durationMs);
+            return output;
+        } catch (error) {
+            // Set state to failed
+            this.logger.logStateChange('Agent', this.state, AgentState.FAILED);
+            await this.setState(AgentState.FAILED, ctx);
+
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Agent execution failed', undefined, { error: errorMessage });
+
+            const errorOutput = this.createOutput(errorMessage, AgentState.FAILED);
+
+            // Error hook
+            if (this.hooks.onError) {
+                await this.hooks.onError(error instanceof Error ? error : new Error(errorMessage), ctx);
+            }
+
+            return errorOutput;
+        }
+    }
+
+    /**
+     * Execute the agent's core logic - must be implemented by subclasses
+     */
+    protected abstract execute(input: AgentInput, ctx: AgentContext): Promise<unknown>;
+
+    /**
+     * Increment iteration counter
+     */
+    protected incrementIteration(): void {
+        this.iterationCount++;
+    }
+
+    /**
+     * Check if max iterations reached
+     */
+    protected isMaxIterationsReached(): boolean {
+        if (!this.config.maxIterations) return false;
+        return this.iterationCount >= this.config.maxIterations;
+    }
+
+    /**
+     * Create an agent output with metadata
+     */
+    protected createOutput(result: unknown, state: AgentState): AgentOutput {
+        const endTime = new Date();
+        const startTime = this.startTime ?? endTime;
+        const durationMs = endTime.getTime() - startTime.getTime();
+
+        const metadata: ExecutionMetadata = {
+            startTime,
+            endTime,
+            durationMs,
+            iterations: this.iterationCount,
+        };
+
+        return {
+            result,
+            state,
+            metadata,
+        };
+    }
+
+    /**
+     * Check if agent is currently executing
+     */
+    isExecuting(): boolean {
+        return this.state === AgentState.EXECUTING || this.state === AgentState.PLANNING;
+    }
+
+    /**
+     * Check if agent has completed
+     */
+    isCompleted(): boolean {
+        return this.state === AgentState.COMPLETED;
+    }
+
+    /**
+     * Check if agent has failed
+     */
+    hasFailed(): boolean {
+        return this.state === AgentState.FAILED;
+    }
+}

package/src/core/context-builder.ts

@@ -0,0 +1,106 @@
+/**
+ * Agent context builder for fluent context creation
+ */
+
+import {
+    AgentContext,
+    EntityId,
+} from './types.js';
+import type { MemoryStore } from '../memory/types.js';
+import type { ToolRegistry } from '../tools/types.js';
+import type { Planner } from '../planner/types.js';
+
+/**
+ * Builder for creating AgentContext instances
+ */
+export class AgentContextBuilder {
+    private agentId: EntityId = `agent-${Date.now()}`;
+    private memory?: MemoryStore;
+    private tools?: ToolRegistry;
+    private planner?: Planner;
+    private metadata: Record<string, unknown> = {};
+
+    /**
+     * Set the agent ID
+     */
+    withAgentId(agentId: EntityId): this {
+        this.agentId = agentId;
+        return this;
+    }
+
+    /**
+     * Set the memory store
+     */
+    withMemory(memory: MemoryStore): this {
+        this.memory = memory;
+        return this;
+    }
+
+    /**
+     * Set the tool registry
+     */
+    withTools(tools: ToolRegistry): this {
+        this.tools = tools;
+        return this;
+    }
+
+    /**
+     * Set the planner
+     */
+    withPlanner(planner: Planner): this {
+        this.planner = planner;
+        return this;
+    }
+
+    /**
+     * Add metadata
+     */
+    withMetadata(key: string, value: unknown): this {
+        this.metadata[key] = value;
+        return this;
+    }
+
+    /**
+     * Add multiple metadata entries
+     */
+    withMetadataEntries(entries: Record<string, unknown>): this {
+        this.metadata = { ...this.metadata, ...entries };
+        return this;
+    }
+
+    /**
+     * Build the AgentContext
+     */
+    build(): AgentContext {
+        if (!this.memory) {
+            throw new Error('Memory store is required');
+        }
+        if (!this.tools) {
+            throw new Error('Tool registry is required');
+        }
+        if (!this.planner) {
+            throw new Error('Planner is required');
+        }
+
+        return {
+            agentId: this.agentId,
+            memory: this.memory,
+            tools: this.tools,
+            planner: this.planner,
+            metadata: { ...this.metadata },
+        };
+    }
+
+    /**
+     * Create a builder from an existing context
+     */
+    static fromContext(context: AgentContext): AgentContextBuilder {
+        const builder = new AgentContextBuilder();
+        builder.agentId = context.agentId;
+        builder.memory = context.memory;
+        builder.tools = context.tools;
+        builder.planner = context.planner;
+        builder.metadata = { ...context.metadata };
+        return builder;
+    }
+}

package/src/core/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Core module exports
+ */
+
+export * from './types.js';
+export * from './schemas.js';
+export { BaseAgent } from './base-agent.js';
+export { AgentContextBuilder } from './context-builder.js';

package/src/core/schemas.ts

@@ -0,0 +1,17 @@
+/**
+ * Type-safe I/O: input_schema and output_schema (Zod) for agent runs.
+ */
+
+import type { z } from 'zod';
+
+/** Input schema for agent run (e.g. prompt + optional structured fields) */
+export type InputSchema<T = unknown> = z.ZodType<T>;
+
+/** Output schema for agent run (e.g. structured response) */
+export type OutputSchema<T = unknown> = z.ZodType<T>;
+
+/** Parsed input from user when inputSchema is used */
+export type ParsedInput<T> = T;
+
+/** Parsed output from agent when outputSchema is used */
+export type ParsedOutput<T> = T;