cognitive-core 0.0.2 → 0.1.0

package/src/types/config.ts

@@ -0,0 +1,333 @@
+import { z } from 'zod';
+
+/**
+ * Credit assignment strategy for trajectory analysis
+ */
+export const CreditStrategySchema = z.enum(['simple', 'llm', 'counterfactual']);
+export type CreditStrategy = z.infer<typeof CreditStrategySchema>;
+
+/**
+ * Pattern extraction approach
+ */
+export const PatternExtractorSchema = z.enum(['llm', 'text', 'both']);
+export type PatternExtractor = z.infer<typeof PatternExtractorSchema>;
+
+/**
+ * Learning pipeline configuration
+ */
+export const LearningConfigSchema = z.object({
+  /** How to assign credit to steps */
+  creditStrategy: CreditStrategySchema.default('simple'),
+  /** How to extract patterns */
+  patternExtractor: PatternExtractorSchema.default('llm'),
+  /** Minimum trajectories before batch learning */
+  minTrajectories: z.number().default(10),
+  /** Minimum hours since last batch learning */
+  minHoursSinceLast: z.number().optional(),
+  /** Minimum success rate for extraction */
+  minSuccessRate: z.number().min(0).max(1).optional(),
+  /** Similarity threshold for deduplication */
+  deduplicationThreshold: z.number().min(0).max(1).default(0.9),
+  /** Maximum experiences to keep during pruning (default: 1000) */
+  maxExperiences: z.number().default(1000),
+});
+
+export type LearningConfig = z.infer<typeof LearningConfigSchema>;
+
+/**
+ * Task routing configuration
+ */
+export const RouterConfigSchema = z.object({
+  /** Threshold for considering tasks similar */
+  similarityThreshold: z.number().min(0).max(1).default(0.85),
+  /** Enable domain-based routing */
+  useDomainRouting: z.boolean().default(true),
+  /** Default search strategy */
+  defaultStrategy: z.string().default('direct'),
+});
+
+export type RouterConfig = z.infer<typeof RouterConfigSchema>;
+
+/**
+ * Memory capacity limits for automatic pruning
+ */
+export const MemoryCapacityConfigSchema = z.object({
+  /** Maximum number of experiences to store (0 = unlimited) */
+  maxExperiences: z.number().default(0),
+  /** Maximum number of playbooks to store (0 = unlimited) */
+  maxPlaybooks: z.number().default(0),
+  /** Maximum age of experiences in days (0 = unlimited) */
+  maxExperienceAgeDays: z.number().default(0),
+  /** Maximum age of failed experiences in days (shorter than successful) */
+  maxFailedExperienceAgeDays: z.number().default(30),
+  /** Enable automatic pruning when limits are exceeded */
+  autoPrune: z.boolean().default(true),
+  /** Preserve domain coverage when pruning */
+  preserveDomainCoverage: z.boolean().default(true),
+  /** Similarity threshold for deduplication (0 = disabled) */
+  deduplicationThreshold: z.number().min(0).max(1).default(0),
+});
+
+export type MemoryCapacityConfig = z.infer<typeof MemoryCapacityConfigSchema>;
+
+/**
+ * Memory retrieval configuration
+ */
+export const MemoryConfigSchema = z.object({
+  /** Maximum experiences to retrieve */
+  maxExperiences: z.number().default(4), // ReMem paper default
+  /** Maximum strategies to retrieve */
+  maxStrategies: z.number().default(3),
+  /** Maximum concepts to retrieve */
+  maxConcepts: z.number().default(5),
+  /** Maximum skills to retrieve */
+  maxSkills: z.number().default(3),
+  /** Maximum tokens for memory context */
+  maxContextTokens: z.number().default(4000),
+  /** Capacity limits for storage */
+  capacity: MemoryCapacityConfigSchema.default({}),
+});
+
+export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
+
+/**
+ * Storage configuration
+ */
+export const StorageConfigSchema = z.object({
+  /** Base directory for file storage */
+  baseDir: z.string().default('.atlas'),
+  /** Enable file-based persistence */
+  persistenceEnabled: z.boolean().default(true),
+  /** Auto-save interval in milliseconds */
+  autoSaveInterval: z.number().default(60000), // 1 minute
+});
+
+export type StorageConfig = z.infer<typeof StorageConfigSchema>;
+
+/**
+ * Embedding provider type
+ */
+export const EmbeddingProviderTypeSchema = z.enum([
+  'openai',
+  'voyage',
+  'local',
+  'none',
+]);
+export type EmbeddingProviderType = z.infer<typeof EmbeddingProviderTypeSchema>;
+
+/**
+ * Embedding configuration
+ */
+export const EmbeddingConfigSchema = z.object({
+  /** Embedding provider type */
+  provider: EmbeddingProviderTypeSchema.default('none'),
+  /** API key for hosted providers (OpenAI, Voyage) */
+  apiKey: z.string().optional(),
+  /** Model name/identifier */
+  model: z.string().optional(),
+  /** Path to local model (for 'local' provider) */
+  modelPath: z.string().optional(),
+  /** Embedding dimension (defaults vary by provider) */
+  dimension: z.number().optional(),
+  /** Path for sqlite-vec database file */
+  vectorDbPath: z.string().default('.atlas/vectors.db'),
+  /** Base URL for API (for custom endpoints) */
+  baseUrl: z.string().optional(),
+});
+
+export type EmbeddingConfig = z.infer<typeof EmbeddingConfigSchema>;
+
+/**
+ * Execution backend type
+ */
+export const ExecutionBackendSchema = z.enum(['acp', 'subprocess', 'mock']);
+export type ExecutionBackend = z.infer<typeof ExecutionBackendSchema>;
+
+/**
+ * Execution configuration
+ */
+export const ExecutionConfigSchema = z.object({
+  /** Backend to use for agent execution */
+  backend: ExecutionBackendSchema.default('acp'),
+  /** Maximum execution time in seconds */
+  maxExecutionTime: z.number().default(300),
+  /** Capture tool calls for trajectory extraction */
+  captureToolCalls: z.boolean().default(true),
+  /** Default agent type */
+  defaultAgentType: z.string().default('claude-code'),
+});
+
+export type ExecutionConfig = z.infer<typeof ExecutionConfigSchema>;
+
+/**
+ * Refinement configuration
+ */
+export const RefinementConfigSchema = z.object({
+  /** Maximum refinement iterations */
+  maxIterations: z.number().min(1).max(10).default(3),
+  /** Minimum quality score to accept without refinement */
+  acceptableScore: z.number().min(0).max(1).default(0.7),
+  /** Whether to use ACP agent for evaluation */
+  useAgentEvaluation: z.boolean().default(true),
+  /** Agent type to use for evaluation */
+  evaluatorAgentType: z.string().default('evaluator'),
+  /** Confidence threshold below which to trigger refinement */
+  confidenceThreshold: z.number().min(0).max(1).default(0.6),
+  /** Routing strategies that should trigger refinement */
+  triggerOnStrategies: z
+    .array(z.enum(['explore', 'fallback', 'direct', 'adapt']))
+    .default(['explore', 'fallback']),
+});
+
+export type RefinementConfig = z.infer<typeof RefinementConfigSchema>;
+
+/**
+ * Skill Library promotion criteria
+ */
+export const SkillPromotionConfigSchema = z.object({
+  /** Minimum confidence to promote to core skill */
+  minConfidence: z.number().min(0).max(1).default(0.85),
+  /** Minimum success count to promote */
+  minSuccessCount: z.number().default(5),
+  /** Minimum success rate to promote */
+  minSuccessRate: z.number().min(0).max(1).default(0.8),
+});
+
+export type SkillPromotionConfig = z.infer<typeof SkillPromotionConfigSchema>;
+
+/**
+ * Skill Library capacity limits
+ */
+export const SkillLimitsConfigSchema = z.object({
+  /** Maximum core skills (always in system prompt) */
+  maxCoreSkills: z.number().default(10),
+  /** Maximum domain skills per domain */
+  maxDomainSkills: z.number().default(5),
+  /** Maximum contextual playbooks per task */
+  maxContextualPlaybooks: z.number().default(3),
+});
+
+export type SkillLimitsConfig = z.infer<typeof SkillLimitsConfigSchema>;
+
+/**
+ * Skill Library context budget
+ */
+export const SkillContextConfigSchema = z.object({
+  /** Maximum tokens for skills in system prompt */
+  maxTokensForSkills: z.number().default(2000),
+  /** Include refinements in skill context */
+  includeRefinements: z.boolean().default(true),
+  /** Include code examples in skill context */
+  includeExamples: z.boolean().default(false),
+  /** Cache refresh interval in milliseconds (default: 5 minutes) */
+  cacheRefreshInterval: z.number().default(5 * 60 * 1000),
+});
+
+export type SkillContextConfig = z.infer<typeof SkillContextConfigSchema>;
+
+/**
+ * Skill Library demotion criteria
+ */
+export const SkillDemotionConfigSchema = z.object({
+  /** Number of consecutive failures before demotion */
+  failureThreshold: z.number().default(3),
+  /** Minimum confidence to retain core skill status */
+  minConfidenceToRetain: z.number().min(0).max(1).default(0.6),
+});
+
+export type SkillDemotionConfig = z.infer<typeof SkillDemotionConfigSchema>;
+
+/**
+ * Skill Library configuration - all thresholds configurable
+ */
+export const SkillLibraryConfigSchema = z.object({
+  /** Promotion criteria */
+  promotion: SkillPromotionConfigSchema.default({}),
+  /** Capacity limits */
+  limits: SkillLimitsConfigSchema.default({}),
+  /** Context budget */
+  context: SkillContextConfigSchema.default({}),
+  /** Demotion criteria */
+  demotion: SkillDemotionConfigSchema.default({}),
+});
+
+export type SkillLibraryConfig = z.infer<typeof SkillLibraryConfigSchema>;
+
+/**
+ * MCP Server configuration
+ */
+export const MCPServerConfigSchema = z.object({
+  /** Enable MCP server */
+  enabled: z.boolean().default(false),
+  /** Port for standalone server */
+  port: z.number().optional(),
+  /** Expose playbooks as MCP resources */
+  exposeResources: z.boolean().default(true),
+  /** Expose playbook tools */
+  exposeTools: z.boolean().default(true),
+  /** Maximum results to return from searches */
+  maxResults: z.number().default(5),
+  /** Minimum confidence threshold for search results */
+  minConfidence: z.number().min(0).max(1).default(0.3),
+  /** Include refinements in playbook details */
+  includeRefinements: z.boolean().default(true),
+  /** Enable filtering by domain */
+  enableDomainFiltering: z.boolean().default(true),
+});
+
+export type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
+
+/**
+ * Main Atlas configuration
+ */
+export const AtlasConfigSchema = z.object({
+  /** Learning configuration */
+  learning: LearningConfigSchema.default({}),
+  /** Router configuration */
+  router: RouterConfigSchema.default({}),
+  /** Memory configuration */
+  memory: MemoryConfigSchema.default({}),
+  /** Storage configuration */
+  storage: StorageConfigSchema.default({}),
+  /** Embedding configuration */
+  embedding: EmbeddingConfigSchema.default({}),
+  /** Execution configuration */
+  execution: ExecutionConfigSchema.default({}),
+  /** Refinement configuration */
+  refinement: RefinementConfigSchema.default({}),
+  /** Skill Library configuration */
+  skillLibrary: SkillLibraryConfigSchema.default({}),
+  /** MCP Server configuration */
+  mcp: MCPServerConfigSchema.default({}),
+});
+
+export type AtlasConfig = z.infer<typeof AtlasConfigSchema>;
+
+/**
+ * Create default configuration
+ */
+export function createDefaultConfig(
+  overrides?: Partial<AtlasConfig>
+): AtlasConfig {
+  return AtlasConfigSchema.parse(overrides ?? {});
+}
+
+/**
+ * Merge configurations
+ */
+export function mergeConfig(
+  base: AtlasConfig,
+  overrides: Partial<AtlasConfig>
+): AtlasConfig {
+  return AtlasConfigSchema.parse({
+    learning: { ...base.learning, ...overrides.learning },
+    router: { ...base.router, ...overrides.router },
+    memory: { ...base.memory, ...overrides.memory },
+    storage: { ...base.storage, ...overrides.storage },
+    embedding: { ...base.embedding, ...overrides.embedding },
+    execution: { ...base.execution, ...overrides.execution },
+    refinement: { ...base.refinement, ...overrides.refinement },
+    skillLibrary: { ...base.skillLibrary, ...overrides.skillLibrary },
+    mcp: { ...base.mcp, ...overrides.mcp },
+  });
+}

package/src/types/index.ts

@@ -0,0 +1,130 @@
+// Core types
+export {
+  type Task,
+  type VerificationSpec,
+  TaskSchema,
+  VerificationSpecSchema,
+  createTask,
+} from './task.js';
+
+export {
+  type Step,
+  StepSchema,
+  createStep,
+} from './step.js';
+
+export {
+  type Outcome,
+  OutcomeSchema,
+  successOutcome,
+  failureOutcome,
+  partialOutcome,
+} from './outcome.js';
+
+export {
+  type Trajectory,
+  TrajectorySchema,
+  createTrajectory,
+  isSuccessful,
+  getKeySteps,
+} from './trajectory.js';
+
+// Memory types
+export {
+  type Experience,
+  type CodeConcept,
+  type Strategy,
+  type Skill,
+  ExperienceSchema,
+  CodeConceptSchema,
+  StrategySchema,
+  SkillSchema,
+  createExperience,
+  createConcept,
+  createStrategy,
+  createSkill,
+} from './memory.js';
+
+// Playbook types (replaces Strategy + Skill)
+export {
+  type Playbook,
+  type PlaybookApplicability,
+  type PlaybookGuidance,
+  type PlaybookVerification,
+  type PlaybookEvolution,
+  type PlaybookProvenance,
+  type PlaybookOrigin,
+  type FailureRecord,
+  type Refinement,
+  type PlaybookComplexity,
+  createPlaybook,
+  bumpPlaybookVersion,
+  getPlaybookSuccessRate,
+  hasReliableStats,
+} from './playbook.js';
+
+// Meta-learning types
+export {
+  type MetaObservation,
+  type RoutingObservation,
+  type RoutingDecisionType,
+  type MemoryUsageObservation,
+  type RetrievalQuality,
+  type ExecutionObservation,
+  type OutcomeObservation,
+  type OutcomeQuality,
+  type LessonsLearned,
+  type MetaStrategy,
+  type MetaStrategyCondition,
+  type MetaStrategyAdjustment,
+  type RoutingAnalysis,
+  type RetrievalAnalysis,
+  type MetaStats,
+  type MetaContext,
+  createMetaObservation,
+  createMetaStrategy,
+} from './meta.js';
+
+// Configuration types
+export {
+  type CreditStrategy,
+  type PatternExtractor,
+  type LearningConfig,
+  type RouterConfig,
+  type MemoryConfig,
+  type MemoryCapacityConfig,
+  type StorageConfig,
+  type EmbeddingProviderType,
+  type EmbeddingConfig,
+  type ExecutionBackend,
+  type ExecutionConfig,
+  type RefinementConfig,
+  type SkillPromotionConfig,
+  type SkillLimitsConfig,
+  type SkillContextConfig,
+  type SkillDemotionConfig,
+  type SkillLibraryConfig,
+  type MCPServerConfig,
+  type AtlasConfig,
+  CreditStrategySchema,
+  PatternExtractorSchema,
+  LearningConfigSchema,
+  RouterConfigSchema,
+  MemoryConfigSchema,
+  MemoryCapacityConfigSchema,
+  StorageConfigSchema,
+  EmbeddingProviderTypeSchema,
+  EmbeddingConfigSchema,
+  ExecutionBackendSchema,
+  ExecutionConfigSchema,
+  RefinementConfigSchema,
+  SkillPromotionConfigSchema,
+  SkillLimitsConfigSchema,
+  SkillContextConfigSchema,
+  SkillDemotionConfigSchema,
+  SkillLibraryConfigSchema,
+  MCPServerConfigSchema,
+  AtlasConfigSchema,
+  createDefaultConfig,
+  mergeConfig,
+} from './config.js';