cognitive-core 0.2.4 → 0.3.1

package/src/types/trajectory-source.ts

@@ -1,47 +0,0 @@
-import type { Trajectory } from './trajectory.js';
-import type { AnalysisResult } from '../learning/analyzer.js';
-
-// ============================================================================
-// Trajectory Source — formal interface for loading trajectories
-// ============================================================================
-
-/**
- * A trajectory paired with its optional pre-computed analysis.
- * If analysis is missing, the consumer should compute it.
- */
-export interface TrajectoryWithAnalysis {
-  trajectory: Trajectory;
-  analysis?: AnalysisResult;
-}
-
-/**
- * Options for filtering trajectories when loading.
- */
-export interface TrajectoryLoadOptions {
-  /** Only load trajectories created after this date */
-  since?: Date;
-  /** Filter to a specific domain */
-  domain?: string;
-  /** Maximum number of trajectories to return */
-  limit?: number;
-  /** Only include successful trajectories */
-  successOnly?: boolean;
-}
-
-/**
- * TrajectorySource — abstract interface for loading trajectories from
- * different backends (in-memory arrays, filesystem, pipeline accumulators, etc.).
- *
- * Consumers of this interface (e.g. KnowledgeBank.extractFrom) don't care
- * where trajectories come from — they just load and process them.
- */
-export interface TrajectorySource {
-  /** Human-readable name for this source */
-  readonly name: string;
-
-  /** Load trajectories, optionally filtered */
-  load(options?: TrajectoryLoadOptions): Promise<TrajectoryWithAnalysis[]>;
-
-  /** Count available trajectories without loading them */
-  count(options?: TrajectoryLoadOptions): Promise<number>;
-}

package/src/types/trajectory.ts

@@ -1,80 +0,0 @@
-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/error-classifier.ts

@@ -1,113 +0,0 @@
-/**
- * Unified error classification utility.
- *
- * Provides a single canonical error type mapping used by TrajectoryAnalyzer,
- * ReflexionGenerator, KnowledgeExtractor, and other learning components.
- */
-
-/**
- * Canonical error types recognized by the classifier.
- */
-export type ErrorType =
-  | 'type-error'
-  | 'import-error'
-  | 'syntax-error'
-  | 'timeout'
-  | 'permission-error'
-  | 'not-found'
-  | 'network-error'
-  | 'test-failure'
-  | 'assertion-error'
-  | 'general-error';
-
-/**
- * Result of classifying an error string.
- */
-export interface ErrorClassification {
-  /** Canonical error type */
-  type: ErrorType;
-  /** Human-readable description */
-  description: string;
-}
-
-/**
- * Ordered list of error classification rules.
- * More specific patterns come first; 'general-error' is the fallback.
- */
-const ERROR_RULES: Array<{ test: (s: string) => boolean; type: ErrorType; description: string }> = [
-  {
-    test: (s) => /type\s*error/i.test(s) || (s.includes('type') && s.includes('error')),
-    type: 'type-error',
-    description: 'Type mismatch error',
-  },
-  {
-    test: (s) => /import|module not found|cannot find module/i.test(s),
-    type: 'import-error',
-    description: 'Import or module resolution error',
-  },
-  {
-    test: (s) => /syntax\s*error/i.test(s),
-    type: 'syntax-error',
-    description: 'Syntax error in code',
-  },
-  {
-    test: (s) => /timeout|timed?\s*out/i.test(s),
-    type: 'timeout',
-    description: 'Operation timed out',
-  },
-  {
-    test: (s) => /permission\s*denied|forbidden|unauthorized/i.test(s),
-    type: 'permission-error',
-    description: 'Permission denied',
-  },
-  {
-    test: (s) => /network|connection|ECONNREFUSED|ENOTFOUND/i.test(s),
-    type: 'network-error',
-    description: 'Network or connection error',
-  },
-  {
-    test: (s) => /not\s*found|missing|no\s*such\s*file/i.test(s),
-    type: 'not-found',
-    description: 'Resource not found',
-  },
-  {
-    test: (s) => /assertion|assert/i.test(s),
-    type: 'assertion-error',
-    description: 'Assertion failed',
-  },
-  {
-    test: (s) => /test.*fail|fail.*test/i.test(s),
-    type: 'test-failure',
-    description: 'Test or assertion failure',
-  },
-  {
-    test: (s) => /exception|error/i.test(s),
-    type: 'general-error',
-    description: 'General error',
-  },
-];
-
-/**
- * Classify an error message into a canonical error type.
- * Returns `null` if no pattern matches.
- */
-export function classifyError(errorInfo: string): ErrorClassification | null {
-  if (!errorInfo) return null;
-
-  for (const rule of ERROR_RULES) {
-    if (rule.test(errorInfo)) {
-      return { type: rule.type, description: rule.description };
-    }
-  }
-
-  return null;
-}
-
-/**
- * Get just the error type string (convenience wrapper).
- * Returns `null` if no pattern matches.
- */
-export function classifyErrorType(errorInfo: string): ErrorType | null {
-  const result = classifyError(errorInfo);
-  return result?.type ?? null;
-}

package/src/utils/frontmatter.ts

@@ -1,118 +0,0 @@
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import {
-  KnowledgeNoteFrontmatterSchema,
-  type KnowledgeNoteFrontmatter,
-  type KnowledgeNote,
-} from '../types/knowledge.js';
-
-const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
-
-/**
- * Parse markdown content with YAML frontmatter into a KnowledgeNoteFrontmatter + body.
- *
- * Uses the `yaml` npm package for full-fidelity parsing (nested objects,
- * arrays of objects, etc.). Validates against the Zod schema.
- *
- * Returns null frontmatter if the content has no frontmatter block or
- * if the frontmatter fails validation (logged, not thrown).
- */
-export function parseKnowledgeFrontmatter(content: string): {
-  frontmatter: KnowledgeNoteFrontmatter | null;
-  body: string;
-} {
-  const match = content.match(FRONTMATTER_REGEX);
-  if (!match) {
-    return { frontmatter: null, body: content };
-  }
-
-  const [, yamlBlock, body] = match;
-
-  try {
-    const raw = parseYaml(yamlBlock);
-    if (!raw || typeof raw !== 'object') {
-      return { frontmatter: null, body };
-    }
-
-    const parsed = KnowledgeNoteFrontmatterSchema.safeParse(raw);
-    if (!parsed.success) {
-      console.warn(
-        `[frontmatter] Validation failed for note: ${JSON.stringify(parsed.error.issues)}`
-      );
-      return { frontmatter: null, body };
-    }
-
-    return { frontmatter: parsed.data, body: body.trim() };
-  } catch (error) {
-    console.warn(
-      `[frontmatter] YAML parse error: ${error instanceof Error ? error.message : String(error)}`
-    );
-    return { frontmatter: null, body: content };
-  }
-}
-
-/**
- * Serialize a KnowledgeNoteFrontmatter into a YAML frontmatter block.
- *
- * Keeps simple top-level fields (created, updated, tags) in a format
- * that minimem's simpler parser can partially read.
- */
-export function serializeKnowledgeFrontmatter(
-  frontmatter: KnowledgeNoteFrontmatter
-): string {
-  // Build a clean object for serialization, omitting null/undefined/empty values
-  const obj: Record<string, unknown> = {
-    id: frontmatter.id,
-    type: frontmatter.type,
-  };
-
-  if (frontmatter.domain.length > 0) obj.domain = frontmatter.domain;
-  if (frontmatter.entities.length > 0) obj.entities = frontmatter.entities;
-  if (frontmatter.tags.length > 0) obj.tags = frontmatter.tags;
-
-  obj.confidence = frontmatter.confidence;
-  obj.source = frontmatter.source;
-
-  if (frontmatter.links.length > 0) obj.links = frontmatter.links;
-
-  obj.created = frontmatter.created;
-  obj.updated = frontmatter.updated;
-
-  if (frontmatter.supersedes) obj.supersedes = frontmatter.supersedes;
-
-  const yaml = stringifyYaml(obj, {
-    lineWidth: 120,
-    defaultKeyType: 'PLAIN',
-    defaultStringType: 'PLAIN',
-  });
-
-  return `---\n${yaml}---\n`;
-}
-
-/**
- * Serialize a full KnowledgeNote (frontmatter + body) into markdown content.
- */
-export function serializeKnowledgeNote(note: KnowledgeNote): string {
-  const header = serializeKnowledgeFrontmatter(note.frontmatter);
-  return `${header}\n${note.body}\n`;
-}
-
-/**
- * Parse a full markdown file into a KnowledgeNote.
- * Returns null if frontmatter is missing or invalid.
- *
- * @param content - The raw markdown file content
- * @param filePath - The file path (stored on the note for reference)
- */
-export function parseKnowledgeNote(
-  content: string,
-  filePath: string
-): KnowledgeNote | null {
-  const { frontmatter, body } = parseKnowledgeFrontmatter(content);
-  if (!frontmatter) return null;
-
-  return {
-    frontmatter,
-    body,
-    filePath,
-  };
-}

package/src/utils/index.ts

@@ -1,63 +0,0 @@
-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 {
-  PartitionedStore,
-  type PartitionedStoreOptions,
-} from './partitioned-store.js';
-
-export {
-  ValidationError,
-  validateString,
-  validateOptionalString,
-  validateNumber,
-  validateOptionalNumber,
-  validateArray,
-  validateVector,
-  validateTaskInput,
-  validateTrajectoryStepCount,
-  validateMCPArgs,
-  TaskInputSchema,
-  MCPSearchPlaybooksSchema,
-  MCPGetPlaybookDetailsSchema,
-  MCPGetPlaybooksByDomainSchema,
-  type TaskInput,
-} from './validation.js';
-
-export {
-  parseKnowledgeFrontmatter,
-  serializeKnowledgeFrontmatter,
-  serializeKnowledgeNote,
-  parseKnowledgeNote,
-} from './frontmatter.js';
-
-export {
-  classifyError,
-  classifyErrorType,
-  type ErrorType,
-  type ErrorClassification,
-} from './error-classifier.js';
-
-export {
-  detectRepeatedActions,
-  extractToolNames,
-  type RepeatedAction,
-} from './trajectory-helpers.js';