vesper-memory 0.3.0

package/config/sqlite-schema.sql

@@ -0,0 +1,413 @@
+-- AI Memory System v3.0 - SQLite Schema
+-- Core graph structure for semantic memory layer
+-- Includes entities, relationships, facts, conflicts, and procedural skills
+
+-- ============================================================================
+-- ENTITIES TABLE
+-- Represents semantic concepts: people, projects, preferences, general concepts
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS entities (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL,  -- 'person', 'project', 'concept', 'preference'
+  description TEXT,
+  embedding BLOB,  -- Vector for Qdrant synchronization (binary-encoded)
+  confidence REAL DEFAULT 1.0,  -- 0.0-1.0, decreases when conflicts detected
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_accessed TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  access_count INTEGER DEFAULT 1,
+
+  -- Metadata for tracking
+  last_modified TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  is_archived BOOLEAN DEFAULT 0,
+  metadata TEXT  -- JSON for extensibility
+);
+
+-- Entity indexes for fast lookup and retrieval
+CREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name);
+CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
+CREATE INDEX IF NOT EXISTS idx_entities_confidence ON entities(confidence DESC);
+CREATE INDEX IF NOT EXISTS idx_entities_created_at ON entities(created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_entities_last_accessed ON entities(last_accessed DESC);
+CREATE INDEX IF NOT EXISTS idx_entities_access_count ON entities(access_count DESC);
+
+-- Optimized index for preference queries (direct SQLite lookup optimization)
+-- Used by handlePreferenceQueryDirect for fast preference retrieval
+CREATE INDEX IF NOT EXISTS idx_entities_preference_lookup
+  ON entities(type, last_accessed DESC, confidence DESC)
+  WHERE type = 'preference';
+
+-- ============================================================================
+-- RELATIONSHIPS TABLE
+-- Represents connections between entities with temporal decay
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS relationships (
+  id TEXT PRIMARY KEY,
+  source_id TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  relation_type TEXT NOT NULL,  -- 'worked_on', 'prefers', 'mentioned', 'related_to', etc.
+  strength REAL NOT NULL DEFAULT 1.0,  -- 0.0-1.0, decays over time with exponential formula
+  evidence TEXT,  -- JSON array of conversation IDs supporting this relationship
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_reinforced TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_modified TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Access tracking for decay calculation
+  access_count INTEGER DEFAULT 1,
+
+  -- Metadata
+  is_archived BOOLEAN DEFAULT 0,
+  metadata TEXT,  -- JSON for extensibility
+
+  -- Foreign key constraints
+  FOREIGN KEY (source_id) REFERENCES entities(id) ON DELETE CASCADE,
+  FOREIGN KEY (target_id) REFERENCES entities(id) ON DELETE CASCADE,
+  CONSTRAINT unique_relationship UNIQUE(source_id, target_id, relation_type)
+);
+
+-- Relationship indexes for efficient traversal and decay updates
+CREATE INDEX IF NOT EXISTS idx_relationships_source ON relationships(source_id);
+CREATE INDEX IF NOT EXISTS idx_relationships_target ON relationships(target_id);
+CREATE INDEX IF NOT EXISTS idx_relationships_type ON relationships(relation_type);
+CREATE INDEX IF NOT EXISTS idx_relationships_strength ON relationships(strength DESC);
+CREATE INDEX IF NOT EXISTS idx_relationships_last_reinforced ON relationships(last_reinforced DESC);
+CREATE INDEX IF NOT EXISTS idx_relationships_created_at ON relationships(created_at DESC);
+
+-- Index for finding relationships that need decay updates (consolidation process)
+CREATE INDEX IF NOT EXISTS idx_relationships_decay_candidates
+  ON relationships(last_reinforced, access_count)
+  WHERE strength > 0.0 AND is_archived = 0;
+
+-- ============================================================================
+-- FACTS TABLE
+-- Represents temporal properties of entities with validity windows
+-- Tracks confidence and detected contradictions
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS facts (
+  id TEXT PRIMARY KEY,
+  entity_id TEXT NOT NULL,
+  property TEXT NOT NULL,
+  value TEXT NOT NULL,
+  confidence REAL NOT NULL DEFAULT 1.0,  -- 0.0-1.0, lowered when contradictions detected
+  valid_from TIMESTAMP NOT NULL,  -- When this fact became true
+  valid_until TIMESTAMP,  -- When this fact became false (NULL if currently valid)
+  source_conversation TEXT,  -- ID of conversation where fact was learned
+  contradicts TEXT,  -- JSON array of fact IDs that contradict this one
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_modified TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Metadata for tracking
+  is_archived BOOLEAN DEFAULT 0,
+  notes TEXT,  -- Explanation of why this fact was lowered/disputed
+  metadata TEXT,  -- JSON for extensibility
+
+  -- Foreign key constraint
+  FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+
+  -- Ensure no exact duplicates
+  CONSTRAINT unique_fact UNIQUE(entity_id, property, value, valid_from)
+);
+
+-- Fact indexes for retrieval and conflict detection
+CREATE INDEX IF NOT EXISTS idx_facts_entity ON facts(entity_id);
+CREATE INDEX IF NOT EXISTS idx_facts_property ON facts(property);
+CREATE INDEX IF NOT EXISTS idx_facts_confidence ON facts(confidence DESC);
+CREATE INDEX IF NOT EXISTS idx_facts_valid_from ON facts(valid_from DESC);
+CREATE INDEX IF NOT EXISTS idx_facts_valid_until ON facts(valid_until DESC);
+CREATE INDEX IF NOT EXISTS idx_facts_source ON facts(source_conversation);
+CREATE INDEX IF NOT EXISTS idx_facts_created_at ON facts(created_at DESC);
+
+-- Composite index for finding currently valid facts (used in retrieval)
+CREATE INDEX IF NOT EXISTS idx_facts_valid_temporal
+  ON facts(entity_id, property, valid_from DESC)
+  WHERE valid_until IS NULL AND is_archived = 0;
+
+-- Index for conflict detection queries
+CREATE INDEX IF NOT EXISTS idx_facts_conflicts
+  ON facts(entity_id, property)
+  WHERE contradicts IS NOT NULL AND is_archived = 0;
+
+-- ============================================================================
+-- CONFLICTS TABLE
+-- Tracks detected contradictions between facts
+-- Never auto-resolves, only flags for user clarification
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS conflicts (
+  id TEXT PRIMARY KEY,
+  fact_id_1 TEXT NOT NULL,
+  fact_id_2 TEXT NOT NULL,
+  conflict_type TEXT NOT NULL,  -- 'temporal_overlap', 'contradiction', 'preference_shift', 'unknown'
+  entity_id TEXT NOT NULL,  -- The entity involved in both facts
+  property TEXT,  -- If applicable, the property being contradicted
+  description TEXT,  -- Human-readable description of the conflict
+  severity TEXT DEFAULT 'medium',  -- 'low', 'medium', 'high'
+  resolution_status TEXT DEFAULT 'flagged',  -- 'flagged', 'acknowledged', 'resolved'
+  user_resolution TEXT,  -- User's clarification of which fact is correct
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_reviewed TIMESTAMP,
+
+  -- Metadata
+  metadata TEXT,  -- JSON for extensibility
+
+  -- Foreign key constraints
+  FOREIGN KEY (fact_id_1) REFERENCES facts(id) ON DELETE CASCADE,
+  FOREIGN KEY (fact_id_2) REFERENCES facts(id) ON DELETE CASCADE,
+  FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+-- Conflict indexes for efficient detection and resolution
+CREATE INDEX IF NOT EXISTS idx_conflicts_entity ON conflicts(entity_id);
+CREATE INDEX IF NOT EXISTS idx_conflicts_fact_1 ON conflicts(fact_id_1);
+CREATE INDEX IF NOT EXISTS idx_conflicts_fact_2 ON conflicts(fact_id_2);
+CREATE INDEX IF NOT EXISTS idx_conflicts_type ON conflicts(conflict_type);
+CREATE INDEX IF NOT EXISTS idx_conflicts_status ON conflicts(resolution_status);
+CREATE INDEX IF NOT EXISTS idx_conflicts_created_at ON conflicts(created_at DESC);
+
+-- Index for finding unresolved conflicts (used during consolidation)
+CREATE INDEX IF NOT EXISTS idx_conflicts_unresolved
+  ON conflicts(entity_id, created_at DESC)
+  WHERE resolution_status IN ('flagged', 'acknowledged');
+
+-- ============================================================================
+-- SKILLS TABLE
+-- Voyager-style procedural memory: reusable patterns that work well
+-- Tracks executable logic, success rates, and dependencies
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS skills (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  description TEXT NOT NULL,
+  category TEXT,  -- Optional categorization: 'data_analysis', 'writing', 'coding', etc.
+
+  -- Executable logic (references or code)
+  code TEXT,  -- The actual implementation (TypeScript or reference)
+  code_type TEXT DEFAULT 'reference',  -- 'inline' or 'reference'
+
+  -- Triggering conditions
+  triggers TEXT NOT NULL,  -- JSON array of semantic descriptions for when to use
+  prerequisites TEXT,  -- JSON array of required context/skills
+
+  -- Success tracking
+  success_count INTEGER DEFAULT 0,
+  failure_count INTEGER DEFAULT 0,
+  avg_user_satisfaction REAL DEFAULT 0.5,  -- 0.0-1.0, from feedback
+
+  -- Dependency tracking (for composition)
+  uses_skills TEXT,  -- JSON array of skill IDs this skill depends on
+  used_by_skills TEXT,  -- JSON array of skill IDs that use this skill
+
+  -- Metadata
+  created_from TEXT,  -- Conversation ID where skill was extracted
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_used TIMESTAMP,
+  last_modified TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  version INTEGER DEFAULT 1,
+  is_archived BOOLEAN DEFAULT 0,
+  notes TEXT,
+  metadata TEXT  -- JSON for extensibility
+);
+
+-- Skill indexes for efficient retrieval
+CREATE INDEX IF NOT EXISTS idx_skills_name ON skills(name);
+CREATE INDEX IF NOT EXISTS idx_skills_category ON skills(category);
+CREATE INDEX IF NOT EXISTS idx_skills_created_at ON skills(created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_skills_last_used ON skills(last_used DESC);
+CREATE INDEX IF NOT EXISTS idx_skills_success_rate ON skills(success_count, failure_count);
+
+-- Index for finding high-confidence skills (used in skill-based retrieval)
+CREATE INDEX IF NOT EXISTS idx_skills_reliability
+  ON skills(avg_user_satisfaction DESC, success_count DESC)
+  WHERE is_archived = 0;
+
+-- ============================================================================
+-- CONSOLIDATION METADATA TABLE
+-- Tracks the consolidation process for recovery and monitoring
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS consolidation_log (
+  id TEXT PRIMARY KEY,
+  consolidation_id TEXT NOT NULL UNIQUE,
+  started_at TIMESTAMP NOT NULL,
+  completed_at TIMESTAMP,
+  status TEXT NOT NULL,  -- 'in_progress', 'completed', 'failed'
+
+  -- Statistics
+  entities_processed INTEGER DEFAULT 0,
+  relationships_processed INTEGER DEFAULT 0,
+  facts_processed INTEGER DEFAULT 0,
+  conflicts_detected INTEGER DEFAULT 0,
+  relationships_pruned INTEGER DEFAULT 0,
+  skills_extracted INTEGER DEFAULT 0,
+
+  -- Recovery information
+  last_checkpoint TIMESTAMP,
+  checkpoint_entity_count INTEGER DEFAULT 0,
+  error_message TEXT,
+
+  -- Performance tracking
+  duration_seconds INTEGER,
+
+  -- Metadata
+  notes TEXT,
+  metadata TEXT  -- JSON for extensibility
+);
+
+-- Consolidation log indexes for monitoring
+CREATE INDEX IF NOT EXISTS idx_consolidation_started ON consolidation_log(started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_consolidation_status ON consolidation_log(status);
+
+-- ============================================================================
+-- BACKUP METADATA TABLE
+-- Tracks backups for rollback capability
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS backup_metadata (
+  id TEXT PRIMARY KEY,
+  backup_timestamp TIMESTAMP NOT NULL,
+  backup_type TEXT NOT NULL,  -- 'daily', 'pre_consolidation', 'manual'
+  status TEXT NOT NULL,  -- 'completed', 'failed'
+
+  -- Backup information
+  backup_path TEXT,
+  file_size_bytes INTEGER,
+
+  -- Backup contents summary
+  entities_count INTEGER,
+  relationships_count INTEGER,
+  facts_count INTEGER,
+
+  -- Retention
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  expires_at TIMESTAMP,  -- Auto-delete after 7 days
+
+  -- Metadata
+  notes TEXT,
+  metadata TEXT
+);
+
+-- Backup metadata indexes
+CREATE INDEX IF NOT EXISTS idx_backup_timestamp ON backup_metadata(backup_timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_backup_status ON backup_metadata(status);
+CREATE INDEX IF NOT EXISTS idx_backup_expiry ON backup_metadata(expires_at);
+
+-- ============================================================================
+-- VIEWS FOR COMMON QUERIES
+-- Provide convenient access patterns for application code
+-- ============================================================================
+
+-- View: Currently valid facts (no longer temporal lookup needed in code)
+CREATE VIEW IF NOT EXISTS valid_facts AS
+SELECT f.*
+FROM facts f
+WHERE f.valid_until IS NULL
+  AND f.is_archived = 0
+  AND f.confidence > 0.0;
+
+-- View: Active relationships (not archived, still have strength)
+CREATE VIEW IF NOT EXISTS active_relationships AS
+SELECT r.*,
+       e1.name as source_name,
+       e2.name as target_name
+FROM relationships r
+JOIN entities e1 ON r.source_id = e1.id
+JOIN entities e2 ON r.target_id = e2.id
+WHERE r.is_archived = 0
+  AND r.strength > 0.0;
+
+-- View: Unresolved conflicts for consolidation
+CREATE VIEW IF NOT EXISTS unresolved_conflicts AS
+SELECT c.*,
+       f1.property as property_1,
+       f1.value as value_1,
+       f2.property as property_2,
+       f2.value as value_2
+FROM conflicts c
+JOIN facts f1 ON c.fact_id_1 = f1.id
+JOIN facts f2 ON c.fact_id_2 = f2.id
+WHERE c.resolution_status IN ('flagged', 'acknowledged');
+
+-- View: High-confidence skills ready for use
+CREATE VIEW IF NOT EXISTS reliable_skills AS
+SELECT s.*,
+       CASE
+         WHEN (s.success_count + s.failure_count) = 0 THEN 0.5
+         ELSE CAST(s.success_count AS REAL) / (s.success_count + s.failure_count)
+       END as success_rate
+FROM skills s
+WHERE s.is_archived = 0
+ORDER BY s.avg_user_satisfaction DESC, s.success_count DESC;
+
+-- View: Entities with connection counts
+CREATE VIEW IF NOT EXISTS entity_stats AS
+SELECT
+  e.id,
+  e.name,
+  e.type,
+  e.confidence,
+  COUNT(DISTINCT r.id) as relationship_count,
+  COUNT(DISTINCT f.id) as fact_count,
+  e.access_count,
+  e.last_accessed
+FROM entities e
+LEFT JOIN relationships r ON (e.id = r.source_id OR e.id = r.target_id) AND r.is_archived = 0
+LEFT JOIN facts f ON e.id = f.entity_id AND f.is_archived = 0
+GROUP BY e.id;
+
+-- ============================================================================
+-- INITIALIZATION NOTES
+-- ============================================================================
+--
+-- This schema supports the AI Memory System v3.0 architecture:
+--
+-- 1. ENTITIES: Semantic concepts (people, projects, preferences)
+--    - Embedding field enables Qdrant vector search integration
+--    - Confidence tracks reliability (lowered when conflicts detected)
+--    - Access patterns tracked for eviction decisions
+--
+-- 2. RELATIONSHIPS: Temporal connections between entities
+--    - strength: Decays over time using exponential formula
+--    - evidence: Links to source conversations for traceability
+--    - Indexed for efficient graph traversal (HippoRAG support)
+--
+-- 3. FACTS: Temporal properties with validity windows
+--    - valid_from/valid_until: Enables temporal reasoning
+--    - contradicts: Links to conflicting facts for detection
+--    - confidence: Lowered when contradictions detected
+--
+-- 4. CONFLICTS: Flagged contradictions (never auto-resolved)
+--    - Types: temporal_overlap, contradiction, preference_shift
+--    - Resolution: Manual user clarification required
+--
+-- 5. SKILLS: Procedural memory (Voyager-style)
+--    - triggers: Semantic descriptions for skill matching
+--    - Dependency tracking for composition
+--    - Success/satisfaction metrics for ranking
+--
+-- CONSOLIDATION PROCESS (Nightly at 3 AM):
+--   1. Extract entities/relationships from working memory
+--   2. Upsert to semantic layer (entities, relationships, facts)
+--   3. Apply exponential decay to all relationships
+--   4. Detect conflicts (temporal, semantic, preference shifts)
+--   5. Prune low-strength, rarely-accessed memories
+--   6. Extract skills from positive interactions
+--   7. Create backup for recovery
+--
+-- DECAY FORMULA (exponential):
+--   strength(t) = strength(0) * e^(-t/30)
+--   - Decays to 50% in ~21 days
+--   - Decays to 10% in ~69 days
+--   - Pruning threshold: strength < 0.05 AND access_count < 3
+--
+-- PERFORMANCE TARGETS:
+--   - Entity lookup: <1ms (indexed by name, type)
+--   - Relationship traversal: <10ms (indexed for HippoRAG)
+--   - Fact retrieval: <5ms (indexed by entity, temporal)
+--   - Conflict detection: <100ms (indexed for query efficiency)
+--   - Consolidation: <15min for 10K memories
+--
+-- ============================================================================

package/dist/benchmark/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Scientific Benchmark System for Vesper Memory
+ *
+ * Main entry point for the benchmark module.
+ * Provides A/B testing with statistical analysis.
+ */
+export { BenchmarkConfigSchema, BenchmarkResultSchema, MetricsSnapshotSchema, ScenarioResultSchema, ComparisonResultSchema, validateBenchmarkConfig, validateBenchmarkResult, validateMetricsSnapshot, createDefaultConfig, SCENARIO_DESCRIPTIONS, getScenarioDescription, } from "./types.js";
+export type { BenchmarkConfig, BenchmarkResult, MetricsSnapshot, ScenarioResult, ComparisonResult, AggregateMetrics, StatisticalComparison, BenchmarkSummary, TTestResult, EffectSize, ScenarioType, BenchmarkPhase, Winner, } from "./types.js";
+export { mean, median, percentile, variance, standardDeviation, confidenceInterval, welchTTest, cohensD, interpretEffectSize, StatisticsError, } from "./statistics.js";
+export type { ConfidenceIntervalResult, WelchTTestResult, } from "./statistics.js";
+export { createMetricsCollector, measureLatency, estimateTokens, evaluateResponseQuality, aggregateMetrics, MetricsCollectorError, } from "./metrics-collector.js";
+export type { MetricsCollector, LatencyMeasurement, ContentType, QualityEvaluationOptions, } from "./metrics-collector.js";
+export { createScenario, createContextRecallScenario, CONTEXT_RECALL_TEST_DATA, } from "./scenarios/index.js";
+export type { BenchmarkScenario, MCPClient, ContextRecallScenario, ContextRecallTestCase, } from "./scenarios/index.js";
+export { createBenchmarkRunner, comparePhasesStatistically, } from "./runner.js";
+export type { BenchmarkRunner } from "./runner.js";
+export { generateMarkdownReport, formatNumber, formatPercentage, formatDuration, generateSummaryTable, generateComparisonSection, } from "./report-generator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/benchmark/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/benchmark/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,MAAM,GACP,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,IAAI,EACJ,MAAM,EACN,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,OAAO,EACP,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC"}

package/dist/benchmark/index.js

@@ -0,0 +1,19 @@
+/**
+ * Scientific Benchmark System for Vesper Memory
+ *
+ * Main entry point for the benchmark module.
+ * Provides A/B testing with statistical analysis.
+ */
+// Types
+export { BenchmarkConfigSchema, BenchmarkResultSchema, MetricsSnapshotSchema, ScenarioResultSchema, ComparisonResultSchema, validateBenchmarkConfig, validateBenchmarkResult, validateMetricsSnapshot, createDefaultConfig, SCENARIO_DESCRIPTIONS, getScenarioDescription, } from "./types.js";
+// Statistics
+export { mean, median, percentile, variance, standardDeviation, confidenceInterval, welchTTest, cohensD, interpretEffectSize, StatisticsError, } from "./statistics.js";
+// Metrics Collector
+export { createMetricsCollector, measureLatency, estimateTokens, evaluateResponseQuality, aggregateMetrics, MetricsCollectorError, } from "./metrics-collector.js";
+// Scenarios
+export { createScenario, createContextRecallScenario, CONTEXT_RECALL_TEST_DATA, } from "./scenarios/index.js";
+// Runner
+export { createBenchmarkRunner, comparePhasesStatistically, } from "./runner.js";
+// Report Generator
+export { generateMarkdownReport, formatNumber, formatPercentage, formatDuration, generateSummaryTable, generateComparisonSection, } from "./report-generator.js";
+//# sourceMappingURL=index.js.map

package/dist/benchmark/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/benchmark/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,QAAQ;AACR,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAkBpB,aAAa;AACb,OAAO,EACL,IAAI,EACJ,MAAM,EACN,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,OAAO,EACP,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAOzB,oBAAoB;AACpB,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAShC,YAAY;AACZ,OAAO,EACL,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAS9B,SAAS;AACT,OAAO,EACL,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAIrB,mBAAmB;AACnB,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC"}

package/dist/benchmark/metrics-collector.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Metrics Collector for Scientific Benchmarks
+ *
+ * Real-time collection and aggregation of benchmark metrics.
+ * Provides accurate latency measurement, token estimation, and quality evaluation.
+ */
+import type { MetricsSnapshot, AggregateMetrics } from "./types.js";
+/**
+ * Error class for metrics collection errors
+ */
+export declare class MetricsCollectorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Metrics collector interface
+ */
+export interface MetricsCollector {
+    /** Record a new metrics snapshot */
+    record(snapshot: MetricsSnapshot): void;
+    /** Get all recorded metrics */
+    getMetrics(): MetricsSnapshot[];
+    /** Get count of recorded metrics */
+    getCount(): number;
+    /** Clear all recorded metrics */
+    clear(): void;
+    /** Aggregate all recorded metrics into summary statistics */
+    aggregate(): AggregateMetrics;
+}
+/**
+ * Create a new metrics collector
+ */
+export declare function createMetricsCollector(): MetricsCollector;
+/**
+ * Result of latency measurement
+ */
+export interface LatencyMeasurement<T> {
+    result: T;
+    latencyMs: number;
+}
+/**
+ * Measure the latency of a function execution
+ *
+ * @param fn - Function to measure (can be sync or async)
+ * @returns Object containing the result and latency in milliseconds
+ */
+export declare function measureLatency<T>(fn: () => T | Promise<T>): Promise<LatencyMeasurement<T>>;
+/**
+ * Content type hint for token estimation
+ */
+export type ContentType = "prose" | "code" | "mixed";
+/**
+ * Estimate the number of tokens in a text string
+ *
+ * Uses a heuristic approximation:
+ * - English prose: ~4 characters per token
+ * - Code: ~3 characters per token (more punctuation)
+ * - Mixed: ~3.5 characters per token
+ *
+ * @param text - The text to estimate tokens for
+ * @param contentType - Optional hint about content type
+ * @returns Estimated token count
+ */
+export declare function estimateTokens(text: string, contentType?: ContentType): number;
+/**
+ * Options for response quality evaluation
+ */
+export interface QualityEvaluationOptions {
+    /** Evaluation mode: 'similarity' (default) or 'keywords' */
+    mode?: "similarity" | "keywords";
+    /** Minimum similarity threshold (0-1) */
+    minThreshold?: number;
+}
+/**
+ * Evaluate the quality of a response against expected content
+ *
+ * @param actual - The actual response
+ * @param expected - Expected response (string) or keywords (array)
+ * @param options - Evaluation options
+ * @returns Quality score from 0.0 to 1.0
+ */
+export declare function evaluateResponseQuality(actual: string, expected: string | string[], options?: QualityEvaluationOptions): number;
+/**
+ * Aggregate an array of metrics snapshots into summary statistics
+ *
+ * @param metrics - Array of metrics snapshots
+ * @returns Aggregated metrics
+ * @throws MetricsCollectorError if metrics array is empty
+ */
+export declare function aggregateMetrics(metrics: MetricsSnapshot[]): AggregateMetrics;
+//# sourceMappingURL=metrics-collector.d.ts.map

package/dist/benchmark/metrics-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-collector.d.ts","sourceRoot":"","sources":["../../src/benchmark/metrics-collector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGpE;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAExC,+BAA+B;IAC/B,UAAU,IAAI,eAAe,EAAE,CAAC;IAEhC,oCAAoC;IACpC,QAAQ,IAAI,MAAM,CAAC;IAEnB,iCAAiC;IACjC,KAAK,IAAI,IAAI,CAAC;IAEd,6DAA6D;IAC7D,SAAS,IAAI,gBAAgB,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CA6BzD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC;IACV,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAYhC;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,WAAqB,GACjC,MAAM,CAoCR;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACjC,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAC3B,OAAO,GAAE,wBAA6B,GACrC,MAAM,CA0DR;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,gBAAgB,CA4C7E"}