cognitive-core 0.0.2 → 0.1.0

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(),
+  });
+}

package/src/types/trajectory.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { TaskSchema, type Task } from './task.js';
+import { StepSchema, type Step } from './step.js';
+import { OutcomeSchema, type Outcome } from './outcome.js';
+
+/**
+ * Trajectory - A complete record of an agent's task-solving attempt
+ * The atomic unit of learning in Atlas
+ */
+export const TrajectorySchema = z.object({
+  /** Unique trajectory identifier */
+  id: z.string(),
+  /** The task being solved */
+  task: TaskSchema,
+  /** Sequence of steps taken */
+  steps: z.array(StepSchema),
+  /** Final outcome */
+  outcome: OutcomeSchema,
+  /** Identifier of the agent that produced this trajectory */
+  agentId: z.string(),
+  /** When the trajectory was created */
+  timestamp: z.date().default(() => new Date()),
+  /** Number of LLM API calls made */
+  llmCalls: z.number().default(0),
+  /** Total tokens used */
+  totalTokens: z.number().default(0),
+  /** Wall clock time in seconds */
+  wallTimeSeconds: z.number().default(0),
+  /** Additional metadata */
+  metadata: z.record(z.unknown()).default({}),
+});
+
+export type Trajectory = z.infer<typeof TrajectorySchema>;
+
+/**
+ * Create a new trajectory
+ */
+export function createTrajectory(params: {
+  id?: string;
+  task: Task;
+  steps: Step[];
+  outcome: Outcome;
+  agentId: string;
+  llmCalls?: number;
+  totalTokens?: number;
+  wallTimeSeconds?: number;
+  metadata?: Record<string, unknown>;
+}): Trajectory {
+  return TrajectorySchema.parse({
+    id: params.id ?? crypto.randomUUID(),
+    task: params.task,
+    steps: params.steps,
+    outcome: params.outcome,
+    agentId: params.agentId,
+    timestamp: new Date(),
+    llmCalls: params.llmCalls ?? 0,
+    totalTokens: params.totalTokens ?? 0,
+    wallTimeSeconds: params.wallTimeSeconds ?? 0,
+    metadata: params.metadata ?? {},
+  });
+}
+
+/**
+ * Check if trajectory was successful
+ */
+export function isSuccessful(trajectory: Trajectory): boolean {
+  return trajectory.outcome.success;
+}
+
+/**
+ * Get key steps (those with high attribution scores)
+ */
+export function getKeySteps(
+  trajectory: Trajectory,
+  threshold = 0.15
+): Step[] {
+  return trajectory.steps.filter(
+    (step) => (step.attributionScore ?? 0) >= threshold
+  );
+}

package/src/utils/index.ts

@@ -0,0 +1,38 @@
+export {
+  cosineSimilarity,
+  jaccardSimilarity,
+  textSimilarity,
+  ngramSimilarity,
+  tokenize,
+  findTopK,
+} from './similarity.js';
+
+export {
+  ensureDir,
+  saveJson,
+  loadJson,
+  listFiles,
+  exists,
+  JsonStore,
+  saveIndex,
+  loadIndex,
+  type StorageOptions,
+} from './storage.js';
+
+export {
+  ValidationError,
+  validateString,
+  validateOptionalString,
+  validateNumber,
+  validateOptionalNumber,
+  validateArray,
+  validateVector,
+  validateTaskInput,
+  validateTrajectoryStepCount,
+  validateMCPArgs,
+  TaskInputSchema,
+  MCPSearchPlaybooksSchema,
+  MCPGetPlaybookDetailsSchema,
+  MCPGetPlaybooksByDomainSchema,
+  type TaskInput,
+} from './validation.js';

package/src/utils/similarity.ts

@@ -0,0 +1,139 @@
+/**
+ * Similarity utilities for comparing embeddings and text
+ */
+
+/**
+ * Compute cosine similarity between two vectors
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) {
+    throw new Error('Vectors must have the same length');
+  }
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  normA = Math.sqrt(normA);
+  normB = Math.sqrt(normB);
+
+  if (normA === 0 || normB === 0) {
+    return 0;
+  }
+
+  return dotProduct / (normA * normB);
+}
+
+/**
+ * Compute Jaccard similarity between two sets of words
+ */
+export function jaccardSimilarity(a: string, b: string): number {
+  const setA = new Set(tokenize(a));
+  const setB = new Set(tokenize(b));
+
+  const intersection = new Set([...setA].filter((x) => setB.has(x)));
+  const union = new Set([...setA, ...setB]);
+
+  if (union.size === 0) {
+    return 0;
+  }
+
+  return intersection.size / union.size;
+}
+
+/**
+ * Simple tokenization for text similarity
+ */
+export function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter((token) => token.length > 0);
+}
+
+/**
+ * Compute n-gram overlap similarity
+ */
+export function ngramSimilarity(
+  a: string,
+  b: string,
+  n = 3
+): number {
+  const ngramsA = getNgrams(a, n);
+  const ngramsB = getNgrams(b, n);
+
+  const intersection = new Set(
+    [...ngramsA].filter((x) => ngramsB.has(x))
+  );
+  const union = new Set([...ngramsA, ...ngramsB]);
+
+  if (union.size === 0) {
+    return 0;
+  }
+
+  return intersection.size / union.size;
+}
+
+/**
+ * Get character n-grams from text
+ */
+function getNgrams(text: string, n: number): Set<string> {
+  const ngrams = new Set<string>();
+  const normalized = text.toLowerCase();
+
+  for (let i = 0; i <= normalized.length - n; i++) {
+    ngrams.add(normalized.slice(i, i + n));
+  }
+
+  return ngrams;
+}
+
+/**
+ * Combined text similarity using multiple methods
+ */
+export function textSimilarity(a: string, b: string): number {
+  const jaccard = jaccardSimilarity(a, b);
+  const ngram = ngramSimilarity(a, b);
+
+  // Weighted average
+  return jaccard * 0.6 + ngram * 0.4;
+}
+
+/**
+ * Find top-k most similar items
+ */
+export function findTopK<T>(
+  query: number[] | string,
+  items: T[],
+  getVector: (item: T) => number[] | string | undefined,
+  k: number
+): Array<{ item: T; score: number }> {
+  const scored = items
+    .map((item) => {
+      const vector = getVector(item);
+      if (!vector) {
+        return { item, score: 0 };
+      }
+
+      let score: number;
+      if (typeof query === 'string' && typeof vector === 'string') {
+        score = textSimilarity(query, vector);
+      } else if (Array.isArray(query) && Array.isArray(vector)) {
+        score = cosineSimilarity(query, vector);
+      } else {
+        score = 0;
+      }
+
+      return { item, score };
+    })
+    .sort((a, b) => b.score - a.score);
+
+  return scored.slice(0, k);
+}