cognitive-core 0.0.2 → 0.1.2

package/src/types/meta.ts

@@ -0,0 +1,218 @@
+/**
+ * Meta Memory Types
+ *
+ * Types for meta-learning - learning about learning itself
+ * Tracks routing decisions, memory effectiveness, and execution patterns
+ */
+
+/**
+ * MetaObservation - Records for learning about learning
+ * Captures what happened during task execution for later analysis
+ */
+export interface MetaObservation {
+  id: string;
+  trajectoryId: string;
+
+  // === ROUTING DECISION ===
+  routing: RoutingObservation;
+
+  // === MEMORY EFFECTIVENESS ===
+  memoryUsage: MemoryUsageObservation;
+
+  // === EXECUTION PATH ===
+  execution: ExecutionObservation;
+
+  // === OUTCOME ===
+  outcome: OutcomeObservation;
+
+  // === LESSONS (LLM-generated reflection) ===
+  lessons: LessonsLearned;
+
+  timestamp: Date;
+}
+
+/**
+ * Observation about the routing decision
+ */
+export interface RoutingObservation {
+  decision: RoutingDecisionType;
+  confidence: number;
+  reasoning: string;
+}
+
+export type RoutingDecisionType = 'adapt' | 'direct' | 'explore' | 'fallback';
+
+/**
+ * Observation about memory retrieval effectiveness
+ */
+export interface MemoryUsageObservation {
+  experiencesRetrieved: number;
+  playbooksApplied: string[]; // IDs of playbooks used
+  retrievalQuality: RetrievalQuality;
+}
+
+export type RetrievalQuality = 'helpful' | 'neutral' | 'misleading';
+
+/**
+ * Observation about the execution path
+ */
+export interface ExecutionObservation {
+  decompositionUsed: boolean;
+  refinementIterations: number;
+  backtrackingOccurred: boolean;
+  toolsUsed: string[];
+}
+
+/**
+ * Observation about the outcome
+ */
+export interface OutcomeObservation {
+  success: boolean;
+  quality: OutcomeQuality;
+  effortActual: number; // Actual LLM calls
+  effortEstimate: number; // What router predicted
+}
+
+export type OutcomeQuality = 'excellent' | 'good' | 'acceptable' | 'poor';
+
+/**
+ * Lessons learned from the execution
+ */
+export interface LessonsLearned {
+  whatWorked: string[];
+  whatFailed: string[];
+  suggestions: string[]; // How to do better next time
+}
+
+/**
+ * MetaStrategy - Learned patterns about learning itself
+ * Used to adjust routing and retrieval based on context
+ */
+export interface MetaStrategy {
+  id: string;
+  name: string;
+
+  // When to apply this meta-strategy
+  condition: MetaStrategyCondition;
+
+  // What to do differently
+  adjustment: MetaStrategyAdjustment;
+
+  // Track effectiveness
+  applicationCount: number;
+  successRate: number;
+
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Conditions for applying a meta-strategy
+ */
+export interface MetaStrategyCondition {
+  taskCharacteristics: string[]; // "multi-file change", "unfamiliar domain"
+  memoryState: string[]; // "no similar experiences", "low confidence"
+}
+
+/**
+ * Adjustments to make when meta-strategy applies
+ */
+export interface MetaStrategyAdjustment {
+  routingBias: Partial<Record<RoutingDecisionType, number>>;
+  retrievalModification: string; // "expand query", "include adjacent domains"
+  executionHint: string; // "prefer decomposition", "verify incrementally"
+}
+
+/**
+ * Analysis of routing effectiveness
+ */
+export interface RoutingAnalysis {
+  byDecision: Record<string, { total: number; successful: number }>;
+  recommendations: string[];
+}
+
+/**
+ * Analysis of retrieval quality
+ */
+export interface RetrievalAnalysis {
+  helpfulPatterns: string[];
+  misleadingPatterns: string[];
+  recommendations: string[];
+}
+
+/**
+ * Statistics about meta-learning
+ */
+export interface MetaStats {
+  totalObservations: number;
+  totalStrategies: number;
+  observationsByRouting: Record<RoutingDecisionType, number>;
+  averageSuccessRate: number;
+  recentTrend: 'improving' | 'stable' | 'declining';
+}
+
+/**
+ * Context for meta-learning queries
+ */
+export interface MetaContext {
+  taskCharacteristics: string[];
+  memoryState: string[];
+}
+
+/**
+ * Create a new meta-observation with defaults
+ */
+export function createMetaObservation(
+  input: Partial<MetaObservation> & {
+    trajectoryId: string;
+    routing: RoutingObservation;
+    outcome: OutcomeObservation;
+  }
+): MetaObservation {
+  return {
+    id: input.id ?? `meta-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    trajectoryId: input.trajectoryId,
+    routing: input.routing,
+    memoryUsage: input.memoryUsage ?? {
+      experiencesRetrieved: 0,
+      playbooksApplied: [],
+      retrievalQuality: 'neutral',
+    },
+    execution: input.execution ?? {
+      decompositionUsed: false,
+      refinementIterations: 0,
+      backtrackingOccurred: false,
+      toolsUsed: [],
+    },
+    outcome: input.outcome,
+    lessons: input.lessons ?? {
+      whatWorked: [],
+      whatFailed: [],
+      suggestions: [],
+    },
+    timestamp: input.timestamp ?? new Date(),
+  };
+}
+
+/**
+ * Create a new meta-strategy with defaults
+ */
+export function createMetaStrategy(
+  input: Partial<MetaStrategy> & {
+    name: string;
+    condition: MetaStrategyCondition;
+    adjustment: MetaStrategyAdjustment;
+  }
+): MetaStrategy {
+  const now = new Date();
+  return {
+    id: input.id ?? `meta-strategy-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    name: input.name,
+    condition: input.condition,
+    adjustment: input.adjustment,
+    applicationCount: input.applicationCount ?? 0,
+    successRate: input.successRate ?? 0,
+    createdAt: input.createdAt ?? now,
+    updatedAt: input.updatedAt ?? now,
+  };
+}

package/src/types/outcome.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+
+/**
+ * Outcome - The result of a task attempt
+ */
+export const OutcomeSchema = z.object({
+  /** Whether the task was completed successfully */
+  success: z.boolean(),
+  /** Partial progress score (0.0-1.0) */
+  partialScore: z.number().min(0).max(1).default(0),
+  /** Error information if failed */
+  errorInfo: z.string().optional(),
+  /** Detailed verification results */
+  verificationDetails: z.record(z.unknown()).default({}),
+  /** The final solution/output */
+  solution: z.unknown().optional(),
+});
+
+export type Outcome = z.infer<typeof OutcomeSchema>;
+
+/**
+ * Create a successful outcome
+ */
+export function successOutcome(
+  solution: unknown,
+  details?: Record<string, unknown>
+): Outcome {
+  return OutcomeSchema.parse({
+    success: true,
+    partialScore: 1.0,
+    solution,
+    verificationDetails: details ?? {},
+  });
+}
+
+/**
+ * Create a failed outcome
+ */
+export function failureOutcome(
+  errorInfo: string,
+  partialScore = 0,
+  details?: Record<string, unknown>
+): Outcome {
+  return OutcomeSchema.parse({
+    success: false,
+    partialScore,
+    errorInfo,
+    verificationDetails: details ?? {},
+  });
+}
+
+/**
+ * Create a partial outcome
+ */
+export function partialOutcome(
+  partialScore: number,
+  solution: unknown,
+  details?: Record<string, unknown>
+): Outcome {
+  return OutcomeSchema.parse({
+    success: false,
+    partialScore,
+    solution,
+    verificationDetails: details ?? {},
+  });
+}

package/src/types/playbook.ts

@@ -0,0 +1,196 @@
+/**
+ * Playbook Types
+ *
+ * Playbook - Adaptive guidance that evolves with experience
+ * Merges ArcMemo strategies with Claudeception skills + Voyager evolution
+ */
+
+/**
+ * Playbook - The core learning unit that replaces Strategy + Skill
+ * Provides adaptive guidance that evolves based on usage outcomes
+ */
+export interface Playbook {
+  id: string;
+  name: string; // kebab-case identifier
+
+  // === APPLICABILITY (when to use) ===
+  applicability: PlaybookApplicability;
+
+  // === GUIDANCE (what to do) ===
+  guidance: PlaybookGuidance;
+
+  // === VERIFICATION (how to know it worked) ===
+  verification: PlaybookVerification;
+
+  // === EVOLUTION (Voyager-style learning) ===
+  evolution: PlaybookEvolution;
+
+  // === PROVENANCE ===
+  provenance?: PlaybookProvenance;
+
+  // === METADATA ===
+  confidence: number; // 0-1, grows with successful use
+  complexity: PlaybookComplexity;
+  estimatedEffort: number; // Rough LLM calls needed
+  embedding?: number[]; // For semantic search
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * When to apply this playbook
+ */
+export interface PlaybookApplicability {
+  situations: string[]; // High-level: "debugging async code"
+  triggers: string[]; // Concrete: "Promise rejection", "TS2307"
+  antiPatterns: string[]; // When NOT to use (avoids false positives)
+  domains: string[]; // "typescript", "react", "api", "testing"
+}
+
+/**
+ * What to do when the playbook applies
+ */
+export interface PlaybookGuidance {
+  strategy: string; // High-level approach
+  tactics: string[]; // Mid-level steps
+  steps?: string[]; // Optional concrete commands
+  codeExample?: string; // Optional illustrative code
+}
+
+/**
+ * How to verify the playbook worked
+ */
+export interface PlaybookVerification {
+  successIndicators: string[]; // "Build passes", "Tests green"
+  failureIndicators: string[]; // "Same error", "New errors introduced"
+  rollbackStrategy?: string; // How to undo if it fails
+}
+
+/**
+ * Provenance tracking - where a playbook came from
+ */
+export type PlaybookOrigin = 'extracted' | 'curated' | 'imported' | 'manual';
+
+export interface PlaybookProvenance {
+  /** How the playbook was created */
+  origin: PlaybookOrigin;
+  /** For curated: relative path to source file (e.g. "playbooks/typescript-debugging.json") */
+  sourceFile?: string;
+  /** For imported: identifier of the source (e.g. "dash-agent", "community-pack") */
+  importedFrom?: string;
+  /** For curated: who authored it */
+  curatedBy?: string;
+  /** When this provenance was recorded */
+  recordedAt: Date;
+}
+
+/**
+ * Evolution tracking for Voyager-style learning
+ */
+export interface PlaybookEvolution {
+  version: string; // Semantic versioning
+  createdFrom: string[]; // Source trajectory IDs
+  failures: FailureRecord[]; // What went wrong
+  refinements: Refinement[]; // Context-specific adaptations
+  successCount: number;
+  failureCount: number;
+  lastUsed?: Date;
+}
+
+/**
+ * Record of a failure when applying the playbook
+ */
+export interface FailureRecord {
+  trajectoryId: string;
+  context: string; // What was different
+  failureMode: string; // How it failed
+  timestamp: Date;
+}
+
+/**
+ * Context-specific refinement to the playbook
+ */
+export interface Refinement {
+  context: string; // "monorepo", "esm", "legacy codebase"
+  addition: string; // "Also check workspace symlinks"
+  source: 'failure' | 'success' | 'manual';
+  addedAt: Date;
+}
+
+export type PlaybookComplexity = 'simple' | 'moderate' | 'complex';
+
+/**
+ * Create a new playbook with defaults
+ */
+export function createPlaybook(
+  input: Partial<Playbook> & {
+    name: string;
+    applicability: PlaybookApplicability;
+    guidance: PlaybookGuidance;
+  }
+): Playbook {
+  const now = new Date();
+  return {
+    id: input.id ?? `playbook-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    name: input.name,
+    applicability: input.applicability,
+    guidance: input.guidance,
+    verification: input.verification ?? {
+      successIndicators: [],
+      failureIndicators: [],
+    },
+    evolution: input.evolution ?? {
+      version: '1.0.0',
+      createdFrom: [],
+      failures: [],
+      refinements: [],
+      successCount: 0,
+      failureCount: 0,
+    },
+    provenance: input.provenance ?? {
+      origin: 'extracted',
+      recordedAt: now,
+    },
+    confidence: input.confidence ?? 0.3, // Start with low confidence
+    complexity: input.complexity ?? 'moderate',
+    estimatedEffort: input.estimatedEffort ?? 3,
+    embedding: input.embedding,
+    createdAt: input.createdAt ?? now,
+    updatedAt: input.updatedAt ?? now,
+  };
+}
+
+/**
+ * Bump playbook version
+ */
+export function bumpPlaybookVersion(
+  playbook: Playbook,
+  type: 'major' | 'minor' | 'patch' = 'patch'
+): string {
+  const [major, minor, patch] = playbook.evolution.version.split('.').map(Number);
+  switch (type) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+    default:
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+
+/**
+ * Calculate playbook success rate
+ */
+export function getPlaybookSuccessRate(playbook: Playbook): number {
+  const total = playbook.evolution.successCount + playbook.evolution.failureCount;
+  if (total === 0) return 0;
+  return playbook.evolution.successCount / total;
+}
+
+/**
+ * Check if playbook has been used enough for reliable statistics
+ */
+export function hasReliableStats(playbook: Playbook, minUses: number = 3): boolean {
+  return playbook.evolution.successCount + playbook.evolution.failureCount >= minUses;
+}

package/src/types/step.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+/**
+ * Step - A single action in a trajectory
+ * Follows ReAct-style (Reasoning + Acting) pattern
+ */
+export const StepSchema = z.object({
+  /** Optional reasoning/thought before action */
+  thought: z.string().optional(),
+  /** The action taken */
+  action: z.string(),
+  /** Result/observation from the action */
+  observation: z.string(),
+  /** Timestamp when step was executed */
+  timestamp: z.date().default(() => new Date()),
+  /** Additional metadata */
+  metadata: z.record(z.unknown()).default({}),
+  /** Credit attribution score (0-1), assigned during analysis */
+  attributionScore: z.number().min(0).max(1).optional(),
+});
+
+export type Step = z.infer<typeof StepSchema>;
+
+/**
+ * Create a new step
+ */
+export function createStep(params: {
+  thought?: string;
+  action: string;
+  observation: string;
+  metadata?: Record<string, unknown>;
+}): Step {
+  return StepSchema.parse({
+    thought: params.thought,
+    action: params.action,
+    observation: params.observation,
+    timestamp: new Date(),
+    metadata: params.metadata ?? {},
+  });
+}

package/src/types/task.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+
+/**
+ * Verification specification for validating task outcomes
+ */
+export const VerificationSpecSchema = z.object({
+  type: z.enum(['exact_match', 'fuzzy_match', 'function', 'llm']),
+  expected: z.unknown().optional(),
+  tolerance: z.number().optional(),
+  verifier_id: z.string().optional(),
+});
+
+export type VerificationSpec = z.infer<typeof VerificationSpecSchema>;
+
+/**
+ * Task - The fundamental unit of work
+ * Represents what an agent needs to accomplish
+ */
+export const TaskSchema = z.object({
+  id: z.string(),
+  domain: z.string(), // e.g., 'arc', 'swe', 'code', 'reasoning'
+  description: z.string(),
+  context: z.record(z.unknown()).default({}),
+  verification: VerificationSpecSchema.optional(),
+  embedding: z.array(z.number()).optional(),
+  metadata: z.record(z.unknown()).default({}),
+  createdAt: z.date().default(() => new Date()),
+});
+
+export type Task = z.infer<typeof TaskSchema>;
+
+/**
+ * Create a new task with defaults
+ */
+export function createTask(params: {
+  id?: string;
+  domain: string;
+  description: string;
+  context?: Record<string, unknown>;
+  verification?: VerificationSpec;
+  metadata?: Record<string, unknown>;
+}): Task {
+  return TaskSchema.parse({
+    id: params.id ?? crypto.randomUUID(),
+    domain: params.domain,
+    description: params.description,
+    context: params.context ?? {},
+    verification: params.verification,
+    metadata: params.metadata ?? {},
+    createdAt: new Date(),
+  });
+}