confused-ai-core 0.1.0

package/src/guardrails/types.ts

@@ -0,0 +1,159 @@
+/**
+ * Guardrails types and interfaces
+ * 
+ * Provides output validation, allowlists, and safety controls for agent outputs.
+ */
+
+import type { z } from 'zod';
+
+/**
+ * Guardrail check result
+ */
+export interface GuardrailResult {
+    readonly passed: boolean;
+    readonly rule: string;
+    readonly message?: string;
+    readonly details?: unknown;
+}
+
+/**
+ * Guardrail violation
+ */
+export interface GuardrailViolation {
+    readonly rule: string;
+    readonly message: string;
+    readonly severity: 'error' | 'warning';
+    readonly details?: unknown;
+}
+
+/**
+ * Guardrail check context
+ */
+export interface GuardrailContext {
+    readonly agentId: string;
+    readonly sessionId?: string;
+    readonly toolName?: string;
+    readonly toolArgs?: Record<string, unknown>;
+    readonly output?: unknown;
+    readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Guardrail rule interface
+ */
+export interface GuardrailRule {
+    readonly name: string;
+    readonly description: string;
+    readonly severity: 'error' | 'warning';
+    check(context: GuardrailContext): GuardrailResult | Promise<GuardrailResult>;
+}
+
+/**
+ * Output validation rule using Zod schema
+ */
+export interface SchemaValidationRule<T = unknown> {
+    readonly name: string;
+    readonly schema: z.ZodType<T>;
+    readonly description?: string;
+}
+
+/**
+ * Allowlist configuration
+ */
+export interface AllowlistConfig {
+    readonly allowedTools?: string[];
+    readonly allowedHosts?: string[];
+    readonly allowedPaths?: string[];
+    readonly allowedOutputs?: string[];
+    readonly blockedPatterns?: RegExp[];
+}
+
+/**
+ * Guardrail configuration
+ */
+export interface GuardrailsConfig {
+    readonly enabled?: boolean;
+    readonly rules?: GuardrailRule[];
+    readonly schemaValidations?: SchemaValidationRule[];
+    readonly allowlist?: AllowlistConfig;
+    readonly onViolation?: (violation: GuardrailViolation, context: GuardrailContext) => void | Promise<void>;
+}
+
+/**
+ * Guardrail engine interface
+ */
+export interface GuardrailEngine {
+    /**
+     * Check if a tool call is allowed
+     */
+    checkToolCall(toolName: string, args: Record<string, unknown>, context: GuardrailContext): Promise<GuardrailResult[]>;
+
+    /**
+     * Validate output against schemas
+     */
+    validateOutput(output: unknown, context: GuardrailContext): Promise<GuardrailResult[]>;
+
+    /**
+     * Run all guardrail checks
+     */
+    checkAll(context: GuardrailContext): Promise<GuardrailResult[]>;
+
+    /**
+     * Get all violations from results
+     */
+    getViolations(results: GuardrailResult[]): GuardrailViolation[];
+}
+
+/**
+ * Human-in-the-loop hook types
+ */
+export interface HumanInTheLoopHooks {
+    /**
+     * Called before executing a tool - can pause for approval
+     * Return true to allow, false to block, or throw to abort
+     */
+    beforeToolCall?: (
+        toolName: string,
+        args: Record<string, unknown>,
+        context: GuardrailContext
+    ) => Promise<boolean> | boolean;
+
+    /**
+     * Called before finishing the run - can pause for review
+     * Return true to allow finish, false to continue, or throw to abort
+     */
+    beforeFinish?: (
+        output: unknown,
+        context: GuardrailContext
+    ) => Promise<boolean> | boolean;
+
+    /**
+     * Called on guardrail violation
+     */
+    onViolation?: (violation: GuardrailViolation, context: GuardrailContext) => void | Promise<void>;
+}
+
+/**
+ * Approval request for human-in-the-loop
+ */
+export interface ApprovalRequest {
+    readonly id: string;
+    readonly type: 'tool_call' | 'finish';
+    readonly context: GuardrailContext;
+    readonly data: {
+        toolName?: string;
+        args?: Record<string, unknown>;
+        output?: unknown;
+    };
+    readonly requestedAt: Date;
+    readonly timeoutMs?: number;
+}
+
+/**
+ * Approval response
+ */
+export interface ApprovalResponse {
+    readonly approved: boolean;
+    readonly reason?: string;
+    readonly modifiedArgs?: Record<string, unknown>;
+}

package/src/guardrails/validator.ts

@@ -0,0 +1,265 @@
+/**
+ * Guardrail validator implementation
+ */
+
+import {
+    GuardrailEngine,
+    GuardrailRule,
+    GuardrailResult,
+    GuardrailViolation,
+    GuardrailContext,
+    GuardrailsConfig,
+    SchemaValidationRule,
+} from './types.js';
+
+/**
+ * Default guardrail engine implementation
+ */
+export class GuardrailValidator implements GuardrailEngine {
+    private rules: GuardrailRule[];
+    private schemaValidations: SchemaValidationRule[];
+    private onViolation?: (violation: GuardrailViolation, context: GuardrailContext) => void | Promise<void>;
+
+    constructor(config: GuardrailsConfig = {}) {
+        this.rules = config.rules ?? [];
+        this.schemaValidations = config.schemaValidations ?? [];
+        this.onViolation = config.onViolation;
+    }
+
+    /**
+     * Add a rule to the validator
+     */
+    addRule(rule: GuardrailRule): void {
+        this.rules.push(rule);
+    }
+
+    /**
+     * Add a schema validation
+     */
+    addSchemaValidation<T>(validation: SchemaValidationRule<T>): void {
+        this.schemaValidations.push(validation);
+    }
+
+    /**
+     * Check if a tool call is allowed
+     */
+    async checkToolCall(
+        toolName: string,
+        args: Record<string, unknown>,
+        context: GuardrailContext
+    ): Promise<GuardrailResult[]> {
+        const ctx: GuardrailContext = {
+            ...context,
+            toolName,
+            toolArgs: args,
+        };
+
+        const results: GuardrailResult[] = [];
+        for (const rule of this.rules) {
+            try {
+                const result = await rule.check(ctx);
+                results.push(result);
+                if (!result.passed && this.onViolation) {
+                    await this.onViolation(
+                        {
+                            rule: rule.name,
+                            message: result.message ?? 'Guardrail check failed',
+                            severity: rule.severity,
+                            details: result.details,
+                        },
+                        ctx
+                    );
+                }
+            } catch (error) {
+                results.push({
+                    passed: false,
+                    rule: rule.name,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+
+        return results;
+    }
+
+    /**
+     * Validate output against schemas
+     */
+    async validateOutput(output: unknown, context: GuardrailContext): Promise<GuardrailResult[]> {
+        const results: GuardrailResult[] = [];
+
+        for (const validation of this.schemaValidations) {
+            try {
+                validation.schema.parse(output);
+                results.push({
+                    passed: true,
+                    rule: validation.name,
+                });
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                results.push({
+                    passed: false,
+                    rule: validation.name,
+                    message: `Schema validation failed: ${message}`,
+                    details: error,
+                });
+
+                if (this.onViolation) {
+                    await this.onViolation(
+                        {
+                            rule: validation.name,
+                            message,
+                            severity: 'error',
+                            details: error,
+                        },
+                        { ...context, output }
+                    );
+                }
+            }
+        }
+
+        return results;
+    }
+
+    /**
+     * Run all guardrail checks
+     */
+    async checkAll(context: GuardrailContext): Promise<GuardrailResult[]> {
+        const results: GuardrailResult[] = [];
+
+        // Check tool call if present
+        if (context.toolName) {
+            const toolResults = await this.checkToolCall(
+                context.toolName,
+                context.toolArgs ?? {},
+                context
+            );
+            results.push(...toolResults);
+        }
+
+        // Validate output if present
+        if (context.output !== undefined) {
+            const outputResults = await this.validateOutput(context.output, context);
+            results.push(...outputResults);
+        }
+
+        // Run general rules
+        for (const rule of this.rules) {
+            try {
+                const result = await rule.check(context);
+                results.push(result);
+                if (!result.passed && this.onViolation) {
+                    await this.onViolation(
+                        {
+                            rule: rule.name,
+                            message: result.message ?? 'Guardrail check failed',
+                            severity: rule.severity,
+                            details: result.details,
+                        },
+                        context
+                    );
+                }
+            } catch (error) {
+                results.push({
+                    passed: false,
+                    rule: rule.name,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+
+        return results;
+    }
+
+    /**
+     * Get all violations from results
+     */
+    getViolations(results: GuardrailResult[]): GuardrailViolation[] {
+        return results
+            .filter(r => !r.passed)
+            .map(r => ({
+                rule: r.rule,
+                message: r.message ?? 'Guardrail check failed',
+                severity: 'error',
+                details: r.details,
+            }));
+    }
+}
+
+/**
+ * Create a regex-based content guardrail rule
+ */
+export function createContentRule(
+    name: string,
+    description: string,
+    pattern: RegExp,
+    severity: 'error' | 'warning' = 'error'
+): GuardrailRule {
+    return {
+        name,
+        description,
+        severity,
+        check(context: GuardrailContext): GuardrailResult {
+            const raw = context.output;
+            const content =
+                typeof raw === 'string' ? raw : raw === undefined || raw === null ? '' : JSON.stringify(raw);
+
+            const matches = pattern.test(content);
+            return {
+                passed: !matches,
+                rule: name,
+                message: matches ? `Content matched forbidden pattern: ${pattern}` : undefined,
+            };
+        },
+    };
+}
+
+/**
+ * Create a tool allowlist rule
+ */
+export function createToolAllowlistRule(allowedTools: string[]): GuardrailRule {
+    return {
+        name: 'tool_allowlist',
+        description: `Only allow tools: ${allowedTools.join(', ')}`,
+        severity: 'error',
+        check(context: GuardrailContext): GuardrailResult {
+            if (!context.toolName) {
+                return { passed: true, rule: 'tool_allowlist' };
+            }
+
+            const allowed = allowedTools.includes(context.toolName);
+            return {
+                passed: allowed,
+                rule: 'tool_allowlist',
+                message: allowed ? undefined : `Tool '${context.toolName}' is not in the allowlist`,
+            };
+        },
+    };
+}
+
+/**
+ * Create a maximum length rule
+ */
+export function createMaxLengthRule(
+    name: string,
+    maxLength: number,
+    severity: 'error' | 'warning' = 'error'
+): GuardrailRule {
+    return {
+        name,
+        description: `Maximum length: ${maxLength}`,
+        severity,
+        check(context: GuardrailContext): GuardrailResult {
+            const raw = context.output;
+            const content =
+                typeof raw === 'string' ? raw : raw === undefined || raw === null ? '' : JSON.stringify(raw);
+
+            const withinLimit = content.length <= maxLength;
+            return {
+                passed: withinLimit,
+                rule: name,
+                message: withinLimit ? undefined : `Output exceeds maximum length of ${maxLength}`,
+            };
+        },
+    };
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Agent Framework - A production-grade TypeScript agent framework
+ *
+ * @packageDocumentation
+ */
+
+// Core exports
+export * from './core/index.js';
+
+// Memory exports
+export * from './memory/index.js';
+
+// Tools exports
+export * from './tools/index.js';
+
+// Planner exports
+export * from './planner/index.js';
+
+// Execution exports
+export * from './execution/index.js';
+
+// Orchestration exports
+export * from './orchestration/index.js';
+
+// Observability exports
+export * from './observability/index.js';
+
+// LLM provider abstraction (optional peer: openai for OpenAIProvider)
+export * from './llm/index.js';
+
+// Agentic loop (ReAct-style)
+export * from './agentic/index.js';
+
+// SDK exports
+export * from './sdk/index.js';
+
+// Session exports
+export * from './session/index.js';
+
+// Guardrails exports
+export * from './guardrails/index.js';
+
+// Learning: user profiles, memories across sessions, learning modes (always / agentic)
+export * from './learning/index.js';
+
+// Knowledge: RAG, hybrid search, reranking, persistent session/state
+export * from './knowledge/index.js';
+
+// Production: runtime, control plane, evals (accuracy, performance, latency)
+export * from './production/index.js';
+
+// Structured errors for production (ErrorCode, AgentError, LLMError, ToolExecutionError, etc.)
+export * from './errors.js';
+
+// Extensions: plug any DB, tools, cross-tool middleware; wrap agents for Orchestrator/Pipeline
+export * from './extensions/index.js';
+
+// One-line production agent (auto LLM, memory, tools, session, guardrails)
+export {
+    createAgent,
+    type CreateAgentOptions,
+    type CreateAgentResult,
+    type AgentRunOptions,
+} from './create-agent.js';
+
+// Agno-style Agent class: clean process, run anytime (model, db, learning, tools)
+export { Agent, type AgentOptions } from './agent.js';
+
+// Best DX: minimal agent(), fluent defineAgent(), dev logging
+export { agent, defineAgent, createDevLogger, createDevToolMiddleware } from './dx/index.js';
+export type { AgentMinimalOptions, DefineAgentOptions } from './dx/index.js';
+
+// Version
+export const VERSION = '1.0.0';

package/src/knowledge/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Knowledge module: RAG, hybrid search, reranking, persistent storage.
+ */
+
+export * from './types.js';

package/src/knowledge/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Knowledge: agentic RAG, hybrid search, reranking, persistent session/state.
+ */
+
+import type { EntityId } from '../core/types.js';
+
+/** Single retrieved chunk for RAG */
+export interface RAGChunk {
+    readonly id: EntityId;
+    readonly content: string;
+    readonly score: number;
+    readonly metadata?: Record<string, unknown>;
+    readonly source?: string;
+}
+
+/** RAG query options */
+export interface RAGQueryOptions {
+    readonly limit?: number;
+    readonly threshold?: number;
+    readonly filter?: Record<string, unknown>;
+    readonly rerank?: boolean;
+    readonly hybrid?: boolean;
+}
+
+/** RAG query result */
+export interface RAGQueryResult {
+    readonly chunks: RAGChunk[];
+    readonly query: string;
+    readonly totalRetrieved?: number;
+}
+
+/** RAG engine: retrieve (and optionally generate). Plug 20+ vector stores, hybrid search, reranking. */
+export interface RAGEngine {
+    /** Retrieve relevant chunks for a query (vector + optional keyword + rerank) */
+    retrieve(query: string, options?: RAGQueryOptions): Promise<RAGQueryResult>;
+
+    /** Optional: generate answer from query + retrieved context (agentic RAG) */
+    generate?(query: string, options?: RAGQueryOptions & { maxTokens?: number }): Promise<{ answer: string; chunks: RAGChunk[] }>;
+
+    /** Ingest documents/chunks for later retrieval */
+    ingest?(chunks: Array<{ content: string; metadata?: Record<string, unknown> }>): Promise<void>;
+}
+
+/** Hybrid search: combine vector similarity + keyword (e.g. BM25). */
+export interface HybridSearchProvider {
+    search(query: string, limit: number, filter?: Record<string, unknown>): Promise<RAGChunk[]>;
+}
+
+/** Reranker: score and reorder retrieved chunks. */
+export interface RerankerProvider {
+    rerank(query: string, chunks: RAGChunk[], topK?: number): Promise<RAGChunk[]>;
+}

package/src/learning/in-memory-store.ts

@@ -0,0 +1,72 @@
+/**
+ * In-memory user profile store (default; plug SQLite/Postgres for production).
+ */
+
+import type { EntityId } from '../core/types.js';
+import type { UserProfile, UserProfileQuery } from './types.js';
+
+export class InMemoryUserProfileStore {
+    private profiles = new Map<string, UserProfile>();
+
+    private key(userId: string, agentId?: EntityId): string {
+        return agentId ? `${userId}:${agentId}` : userId;
+    }
+
+    async get(userId: string, agentId?: EntityId): Promise<UserProfile | null> {
+        return this.profiles.get(this.key(userId, agentId)) ?? null;
+    }
+
+    async set(profile: Omit<UserProfile, 'id' | 'createdAt' | 'updatedAt'>): Promise<UserProfile> {
+        const now = new Date();
+        const id = `profile-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        const entry: UserProfile = {
+            ...profile,
+            id,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.profiles.set(this.key(profile.userId, profile.agentId), entry);
+        return entry;
+    }
+
+    async update(
+        userId: string,
+        updates: Partial<Omit<UserProfile, 'id' | 'userId' | 'createdAt'>>,
+        agentId?: EntityId
+    ): Promise<UserProfile> {
+        const existing = await this.get(userId, agentId);
+        if (!existing) {
+            const now = new Date();
+            const entry: UserProfile = {
+                id: `profile-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+                userId,
+                agentId,
+                metadata: (updates.metadata as Record<string, unknown>) ?? {},
+                createdAt: now,
+                updatedAt: now,
+                ...updates,
+            };
+            this.profiles.set(this.key(userId, agentId), entry);
+            return entry;
+        }
+        const updated: UserProfile = {
+            ...existing,
+            ...updates,
+            updatedAt: new Date(),
+        };
+        this.profiles.set(this.key(userId, agentId), updated);
+        return updated;
+    }
+
+    async list(query?: UserProfileQuery): Promise<UserProfile[]> {
+        let list = Array.from(this.profiles.values());
+        if (query?.userId) list = list.filter(p => p.userId === query.userId);
+        if (query?.agentId) list = list.filter(p => p.agentId === query.agentId);
+        if (query?.limit) list = list.slice(0, query.limit);
+        return list;
+    }
+
+    async delete(userId: string, agentId?: EntityId): Promise<boolean> {
+        return this.profiles.delete(this.key(userId, agentId));
+    }
+}

package/src/learning/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Learning module: user profiles, memories across sessions, learning modes.
+ */
+
+export * from './types.js';
+export { InMemoryUserProfileStore } from './in-memory-store.js';

package/src/learning/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Learning: user profiles, memories that accumulate, knowledge that transfers.
+ * Supports always-on or agentic learning modes.
+ */
+
+import type { EntityId } from '../core/types.js';
+
+/** Learning mode: always persist/learn vs. only when agent explicitly stores */
+export enum LearningMode {
+    /** Always: persist session, accumulate memories, update profiles automatically */
+    ALWAYS = 'always',
+    /** Agentic: agent decides when to store/update (e.g. via tools) */
+    AGENTIC = 'agentic',
+}
+
+/** User profile that persists across sessions */
+export interface UserProfile {
+    readonly id: EntityId;
+    readonly userId: string;
+    readonly agentId?: EntityId;
+    readonly displayName?: string;
+    readonly preferences?: Record<string, unknown>;
+    readonly metadata: Record<string, unknown>;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+}
+
+/** Query for user profiles */
+export interface UserProfileQuery {
+    readonly userId?: string;
+    readonly agentId?: EntityId;
+    readonly limit?: number;
+}
+
+/** Store for user profiles (plug any DB) */
+export interface UserProfileStore {
+    get(userId: string, agentId?: EntityId): Promise<UserProfile | null>;
+    set(profile: Omit<UserProfile, 'id' | 'createdAt' | 'updatedAt'>): Promise<UserProfile>;
+    update(userId: string, updates: Partial<Omit<UserProfile, 'id' | 'userId' | 'createdAt'>>, agentId?: EntityId): Promise<UserProfile>;
+    list(query?: UserProfileQuery): Promise<UserProfile[]>;
+    delete(userId: string, agentId?: EntityId): Promise<boolean>;
+}