@soleri/core 2.1.0 → 2.5.0

package/src/governance/types.ts

@@ -0,0 +1,111 @@
+// ─── Policy Types ───────────────────────────────────────────────────
+
+export type PolicyType = 'quota' | 'retention' | 'auto-capture';
+export type PolicyPreset = 'strict' | 'moderate' | 'permissive';
+export type PolicyAction = 'capture' | 'quarantine' | 'reject' | 'propose';
+
+export interface QuotaPolicy {
+  maxEntriesTotal: number;
+  maxEntriesPerCategory: number;
+  maxEntriesPerType: number;
+  warnAtPercent: number;
+}
+
+export interface RetentionPolicy {
+  archiveAfterDays: number;
+  minHitsToKeep: number;
+  deleteArchivedAfterDays: number;
+}
+
+export interface AutoCapturePolicy {
+  enabled: boolean;
+  requireReview: boolean;
+  maxPendingProposals: number;
+  autoExpireDays: number;
+}
+
+export interface VaultPolicy {
+  projectPath: string;
+  quotas: QuotaPolicy;
+  retention: RetentionPolicy;
+  autoCapture: AutoCapturePolicy;
+}
+
+export interface QuotaStatus {
+  total: number;
+  maxTotal: number;
+  byCategory: Record<string, number>;
+  byType: Record<string, number>;
+  warnAtPercent: number;
+  isWarning: boolean;
+}
+
+export interface PolicyDecision {
+  allowed: boolean;
+  action: PolicyAction;
+  reason?: string;
+  quotaStatus?: QuotaStatus;
+}
+
+export interface BatchDecision {
+  entry: { type: string; category: string; title?: string };
+  decision: PolicyDecision;
+}
+
+export interface PolicyAuditEntry {
+  id: number;
+  projectPath: string;
+  policyType: string;
+  oldConfig: Record<string, unknown> | null;
+  newConfig: Record<string, unknown>;
+  changedBy: string | null;
+  changedAt: number;
+}
+
+// ─── Proposal Types ─────────────────────────────────────────────────
+
+export type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'modified' | 'expired';
+
+export interface Proposal {
+  id: number;
+  projectPath: string;
+  entryId: string | null;
+  title: string;
+  type: string;
+  category: string;
+  proposedData: Record<string, unknown>;
+  status: ProposalStatus;
+  proposedAt: number;
+  decidedAt: number | null;
+  decidedBy: string | null;
+  modificationNote: string | null;
+  source: string;
+}
+
+export interface ProposalStats {
+  total: number;
+  pending: number;
+  approved: number;
+  rejected: number;
+  modified: number;
+  expired: number;
+  acceptanceRate: number;
+  byCategory: Record<string, { total: number; accepted: number; rate: number }>;
+}
+
+// ─── Dashboard ──────────────────────────────────────────────────────
+
+export interface GovernanceDashboard {
+  vaultSize: number;
+  quotaPercent: number;
+  quotaStatus: QuotaStatus;
+  pendingProposals: number;
+  acceptanceRate: number;
+  evaluationTrend: Record<string, number>;
+  policySummary: {
+    maxEntries: number;
+    requireReview: boolean;
+    archiveAfterDays: number;
+    autoExpireDays: number;
+  };
+}

package/src/index.ts

@@ -5,6 +5,31 @@ export { loadIntelligenceData } from './intelligence/loader.js';
 // ─── Vault ───────────────────────────────────────────────────────────
 export { Vault } from './vault/vault.js';
 export type { SearchResult, VaultStats, ProjectInfo, Memory, MemoryStats } from './vault/vault.js';
+export { validatePlaybook, parsePlaybookFromEntry } from './vault/playbook.js';
+export type { Playbook, PlaybookStep, PlaybookValidationResult } from './vault/playbook.js';
+
+// ─── Playbook System (registry, matching, seeding) ─────────────────
+export {
+  getBuiltinPlaybook,
+  getAllBuiltinPlaybooks,
+  scorePlaybook,
+  mergePlaybooks,
+  matchPlaybooks,
+  seedDefaultPlaybooks,
+  playbookDefinitionToEntry,
+  entryToPlaybookDefinition,
+} from './playbooks/index.js';
+export type {
+  PlaybookTier,
+  PlaybookIntent,
+  BrainstormSection,
+  PlaybookGate,
+  PlaybookTaskTemplate,
+  PlaybookDefinition,
+  MergedPlaybook,
+  PlaybookMatchResult,
+} from './playbooks/index.js';
+export { createPlaybookOps } from './runtime/playbook-ops.js';
 
 // ─── Text Utilities ─────────────────────────────────────────────────
 export {
@@ -37,6 +62,26 @@ export type {
   CuratorStatus,
 } from './curator/types.js';
 
+// ─── Governance ─────────────────────────────────────────────────────
+export { Governance } from './governance/governance.js';
+export type {
+  PolicyType,
+  PolicyPreset,
+  PolicyAction,
+  QuotaPolicy,
+  RetentionPolicy,
+  AutoCapturePolicy,
+  VaultPolicy,
+  QuotaStatus,
+  PolicyDecision,
+  BatchDecision,
+  PolicyAuditEntry,
+  ProposalStatus,
+  Proposal,
+  ProposalStats,
+  GovernanceDashboard,
+} from './governance/types.js';
+
 // ─── Brain ───────────────────────────────────────────────────────────
 export { Brain } from './brain/brain.js';
 export { BrainIntelligence } from './brain/intelligence.js';
@@ -48,6 +93,11 @@ export type {
   CaptureResult,
   BrainStats,
   QueryContext,
+  FeedbackType,
+  FeedbackSource,
+  FeedbackInput,
+  FeedbackEntry,
+  FeedbackStats,
   PatternStrength,
   StrengthsQuery,
   BrainSession,
@@ -74,9 +124,91 @@ export type {
   CogneeCognifyResult,
 } from './cognee/types.js';
 
+// ─── Cognee Sync ──────────────────────────────────────────────────────
+export { CogneeSyncManager } from './cognee/sync-manager.js';
+export type { SyncOp, SyncStatus, SyncQueueItem, SyncManagerStats } from './cognee/sync-manager.js';
+
+// ─── Intake Pipeline ──────────────────────────────────────────────────
+export { IntakePipeline } from './intake/intake-pipeline.js';
+export { classifyChunk, VALID_TYPES, CLASSIFICATION_PROMPT } from './intake/content-classifier.js';
+export { dedupItems, DEDUP_THRESHOLD } from './intake/dedup-gate.js';
+export type {
+  IntakeConfig,
+  IntakeChunk,
+  IntakeJobRecord,
+  IntakeJobStatus,
+  IntakeChunkStatus,
+  KnowledgeType,
+  ClassifiedItem,
+  IntakePreviewResult,
+} from './intake/types.js';
+export type { DedupResult } from './intake/dedup-gate.js';
+
 // ─── Planning ────────────────────────────────────────────────────────
-export { Planner } from './planning/planner.js';
-export type { PlanStatus, TaskStatus, PlanTask, Plan, PlanStore } from './planning/planner.js';
+export {
+  Planner,
+  calculateScore,
+  calculateDriftScore,
+  isValidTransition,
+  getValidNextStatuses,
+  shouldExpire,
+  LIFECYCLE_TRANSITIONS,
+  NON_EXPIRING_STATUSES,
+  DRIFT_WEIGHTS,
+} from './planning/planner.js';
+export type {
+  PlanStatus,
+  TaskStatus,
+  TaskEvidence,
+  TaskMetrics,
+  TaskDeliverable,
+  ExecutionSummary,
+  PlanTask,
+  PlanDecision,
+  Plan,
+  PlanStore,
+  DriftItem,
+  ReconciliationReport,
+  ReviewEvidence,
+  PlanGrade,
+  PlanCheck,
+} from './planning/planner.js';
+
+// ─── Plan Gap Analysis ──────────────────────────────────────────────
+export {
+  runGapAnalysis,
+  createToolFeasibilityPass,
+  createFlowAlignmentPass,
+  createAntiPatternPass,
+} from './planning/gap-analysis.js';
+export type { GapAnalysisOptions, GapAnalysisPass } from './planning/gap-analysis.js';
+export {
+  SEVERITY_WEIGHTS,
+  CATEGORY_PENALTY_CAPS,
+  MIN_OBJECTIVE_LENGTH,
+  MIN_SCOPE_LENGTH,
+  MIN_DECISION_LENGTH,
+  generateGapId,
+} from './planning/gap-types.js';
+export type { GapSeverity, GapCategory, PlanGap } from './planning/gap-types.js';
+
+// ─── Loop ────────────────────────────────────────────────────────────
+export {
+  LoopManager,
+  extractPromise,
+  detectImplicitCompletion,
+  detectAnomaly,
+} from './loop/loop-manager.js';
+export type {
+  LoopMode,
+  LoopConfig,
+  LoopIteration,
+  LoopStatus,
+  LoopState,
+  LoopKnowledge,
+  LoopHistoryEntry,
+  LoopIterateDecision,
+} from './loop/types.js';
 
 // ─── LLM Types ───────────────────────────────────────────────────────
 export { SecretString, LLMError } from './llm/types.js';
@@ -122,8 +254,87 @@ export type {
 // ─── LLM Client ─────────────────────────────────────────────────────
 export { LLMClient } from './llm/llm-client.js';
 
+// ─── Control ────────────────────────────────────────────────────────
+export { IdentityManager } from './control/identity-manager.js';
+export { IntentRouter } from './control/intent-router.js';
+export type {
+  GuidelineCategory,
+  Guideline,
+  AgentIdentity,
+  IdentityVersion,
+  IdentityUpdateInput,
+  GuidelineInput,
+  IntentType,
+  OperationalMode,
+  IntentClassification,
+  ModeConfig,
+  MorphResult,
+} from './control/types.js';
+
+// ─── Project Registry ──────────────────────────────────────────────
+export { ProjectRegistry } from './project/project-registry.js';
+export type { RegisteredProject, ProjectRule, LinkType, ProjectLink } from './project/types.js';
+
+// ─── Telemetry ─────────────────────────────────────────────────────
+export { Telemetry } from './telemetry/telemetry.js';
+export type { FacadeCall, TelemetryStats } from './telemetry/telemetry.js';
+
+// ─── Logging ────────────────────────────────────────────────────────
+export { Logger, createLogger } from './logging/logger.js';
+export type { LogLevel, LogEntry, LogContext, LoggerConfig } from './logging/types.js';
+
 // ─── Runtime Factory ────────────────────────────────────────────────
 export { createAgentRuntime } from './runtime/runtime.js';
 export { createCoreOps } from './runtime/core-ops.js';
 export { createDomainFacade, createDomainFacades } from './runtime/domain-ops.js';
+export { createPlanningExtraOps } from './runtime/planning-extra-ops.js';
+export { createMemoryExtraOps } from './runtime/memory-extra-ops.js';
+export { createVaultExtraOps } from './runtime/vault-extra-ops.js';
+export { createAdminOps } from './runtime/admin-ops.js';
+export { createAdminExtraOps } from './runtime/admin-extra-ops.js';
+export { createLoopOps } from './runtime/loop-ops.js';
+export { createOrchestrateOps } from './runtime/orchestrate-ops.js';
+export { createGradingOps } from './runtime/grading-ops.js';
+export { createCaptureOps } from './runtime/capture-ops.js';
+export { createCuratorExtraOps } from './runtime/curator-extra-ops.js';
+export { createProjectOps } from './runtime/project-ops.js';
+export { createMemoryCrossProjectOps } from './runtime/memory-cross-project-ops.js';
+export { createCogneeSyncOps } from './runtime/cognee-sync-ops.js';
+export { createIntakeOps } from './runtime/intake-ops.js';
 export type { AgentRuntimeConfig, AgentRuntime } from './runtime/types.js';
+
+// ─── Errors ────────────────────────────────────────────────────────────
+export {
+  SoleriErrorCode,
+  SoleriError,
+  ok,
+  err,
+  isOk,
+  isErr,
+  classifyError,
+  retryWithPreset,
+  shouldRetry,
+  getRetryDelay,
+  RETRY_PRESETS,
+} from './errors/index.js';
+export type {
+  ErrorClassification,
+  Result,
+  SoleriErrorOptions,
+  RetryPreset,
+  RetryConfig as SoleriRetryConfig,
+  RetryOptions,
+} from './errors/index.js';
+
+// ─── Persistence ───────────────────────────────────────────────────────
+export { SQLitePersistenceProvider } from './persistence/index.js';
+export type {
+  PersistenceProvider,
+  PersistenceParams,
+  RunResult,
+  PersistenceConfig,
+} from './persistence/index.js';
+
+// ─── Prompts ───────────────────────────────────────────────────────────
+export { TemplateManager, parseVariables, resolveIncludes } from './prompts/index.js';
+export type { PromptTemplate, TemplateVariable, RenderOptions } from './prompts/index.js';

package/src/intake/content-classifier.ts

@@ -0,0 +1,146 @@
+// ─── Content Classifier — LLM-based knowledge extraction ────────────────────
+//
+// Takes a text chunk and uses an LLM to classify it into structured
+// knowledge items. Graceful degradation: returns [] on any error.
+
+import type { LLMClient } from '../llm/llm-client.js';
+import type { ClassifiedItem, KnowledgeType } from './types.js';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+export const VALID_TYPES: KnowledgeType[] = [
+  'pattern',
+  'anti-pattern',
+  'principle',
+  'concept',
+  'reference',
+  'workflow',
+  'idea',
+  'roadmap',
+];
+
+const VALID_SEVERITIES = ['critical', 'warning', 'suggestion'] as const;
+type Severity = (typeof VALID_SEVERITIES)[number];
+
+export const CLASSIFICATION_PROMPT = `You are a knowledge extraction engine. Your job is to analyze a text chunk and extract structured knowledge items from it.
+
+For each distinct piece of knowledge you identify, produce an object with these fields:
+- type: one of ${JSON.stringify(VALID_TYPES)}
+- title: concise title, max 80 characters
+- description: 2-3 sentence summary of the knowledge
+- tags: 3-5 lowercase single-word or hyphenated tags
+- severity: one of "critical", "warning", "suggestion"
+
+Rules:
+- Extract ALL meaningful knowledge items from the text.
+- Each item must be self-contained and independently useful.
+- Use "critical" for must-know items, "warning" for important gotchas, "suggestion" for nice-to-know.
+- Tags should be specific and useful for search.
+- Respond with a pure JSON array of objects. No markdown fences, no explanation, no wrapping.
+- If the text contains no extractable knowledge, respond with an empty array: []`;
+
+// =============================================================================
+// CLASSIFIER
+// =============================================================================
+
+/**
+ * Classify a text chunk into structured knowledge items using an LLM.
+ *
+ * @param llm      - LLMClient instance
+ * @param chunkText - The text to classify
+ * @param citation  - Source citation (e.g. "book.pdf, pages 12-15")
+ * @returns Classified items, or [] on any error
+ */
+export async function classifyChunk(
+  llm: LLMClient,
+  chunkText: string,
+  citation: string,
+): Promise<ClassifiedItem[]> {
+  try {
+    const result = await llm.complete({
+      provider: 'openai',
+      model: 'gpt-4o-mini',
+      systemPrompt: CLASSIFICATION_PROMPT,
+      userPrompt: chunkText,
+      maxTokens: 4096,
+      temperature: 0.3,
+      caller: 'intake',
+      task: 'classify',
+    });
+
+    const raw = parseJsonResponse(result.text);
+    if (!Array.isArray(raw)) return [];
+
+    return raw
+      .map((item: unknown) => sanitizeItem(item, citation))
+      .filter((item): item is ClassifiedItem => item !== null);
+  } catch {
+    // Graceful degradation — never throw
+    return [];
+  }
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/**
+ * Parse a JSON response, handling potential markdown fences the LLM
+ * might include despite instructions.
+ */
+function parseJsonResponse(text: string): unknown {
+  const trimmed = text.trim();
+
+  // Strip markdown fences if present (defensive)
+  const fenceMatch = trimmed.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?\s*```$/);
+  const jsonStr = fenceMatch ? fenceMatch[1] : trimmed;
+
+  return JSON.parse(jsonStr);
+}
+
+/**
+ * Validate and sanitize a single classified item.
+ * Returns null if the item is not salvageable.
+ */
+function sanitizeItem(raw: unknown, citation: string): ClassifiedItem | null {
+  if (!raw || typeof raw !== 'object') return null;
+
+  const obj = raw as Record<string, unknown>;
+
+  // Type — must be a valid KnowledgeType
+  const type = typeof obj.type === 'string' ? obj.type : '';
+  if (!VALID_TYPES.includes(type as KnowledgeType)) return null;
+
+  // Title — required, truncate to 80 chars
+  const title = typeof obj.title === 'string' ? obj.title.slice(0, 80).trim() : '';
+  if (!title) return null;
+
+  // Description — required
+  const description = typeof obj.description === 'string' ? obj.description.trim() : '';
+  if (!description) return null;
+
+  // Tags — must be array of strings, cap at 5
+  const tags = Array.isArray(obj.tags)
+    ? obj.tags
+        .filter((t): t is string => typeof t === 'string')
+        .map((t) => t.toLowerCase().trim())
+        .filter((t) => t.length > 0)
+        .slice(0, 5)
+    : [];
+
+  // Severity — default to 'suggestion' if invalid
+  const severity: Severity = VALID_SEVERITIES.includes(obj.severity as Severity)
+    ? (obj.severity as Severity)
+    : 'suggestion';
+
+  return {
+    type: type as KnowledgeType,
+    title,
+    description,
+    tags,
+    severity,
+    citation,
+  };
+}

package/src/intake/dedup-gate.ts

@@ -0,0 +1,92 @@
+// ─── Dedup Gate ───────────────────────────────────────────────────
+// TF-IDF cosine similarity check against existing vault entries.
+// Pure function: no side effects, no I/O beyond reading vault.
+
+import {
+  tokenize,
+  calculateTfIdf,
+  cosineSimilarity,
+  type SparseVector,
+} from '../text/similarity.js';
+import type { Vault } from '../vault/vault.js';
+import type { ClassifiedItem } from './types.js';
+
+export const DEDUP_THRESHOLD = 0.85;
+
+export interface DedupResult {
+  item: ClassifiedItem;
+  isDuplicate: boolean;
+  bestMatchId?: string;
+  similarity: number;
+}
+
+/**
+ * Check new items against existing vault entries for duplicates using TF-IDF cosine similarity.
+ *
+ * Builds a shared IDF vocabulary from all texts (existing + new), computes TF-IDF vectors,
+ * and marks items as duplicates when cosine similarity >= DEDUP_THRESHOLD.
+ */
+export function dedupItems(items: ClassifiedItem[], vault: Vault): DedupResult[] {
+  const existing = vault.exportAll().entries;
+
+  // Fast path: nothing in vault — everything is new
+  if (existing.length === 0) {
+    return items.map((item) => ({
+      item,
+      isDuplicate: false,
+      similarity: 0,
+    }));
+  }
+
+  // ── Build texts for vocabulary ──────────────────────────────────
+  const existingTexts = existing.map((e) => `${e.title} ${e.description}`);
+  const newTexts = items.map((i) => `${i.title} ${i.description}`);
+  const allTexts = [...existingTexts, ...newTexts];
+  const totalDocs = allTexts.length;
+
+  // ── Count document frequency per term ───────────────────────────
+  const docFreq = new Map<string, number>();
+  for (const text of allTexts) {
+    const terms = new Set(tokenize(text));
+    for (const term of terms) {
+      docFreq.set(term, (docFreq.get(term) ?? 0) + 1);
+    }
+  }
+
+  // ── Build IDF vocabulary ────────────────────────────────────────
+  const vocabulary = new Map<string, number>();
+  for (const [term, df] of docFreq) {
+    vocabulary.set(term, Math.log((totalDocs + 1) / (df + 1)) + 1);
+  }
+
+  // ── Compute TF-IDF vectors for existing entries ─────────────────
+  const existingVectors: Array<{ id: string; vec: SparseVector }> = existing.map((entry, idx) => ({
+    id: entry.id,
+    vec: calculateTfIdf(tokenize(existingTexts[idx]), vocabulary),
+  }));
+
+  // ── Score each new item against all existing entries ────────────
+  return items.map((item, idx) => {
+    const itemVec = calculateTfIdf(tokenize(newTexts[idx]), vocabulary);
+
+    let bestSimilarity = 0;
+    let bestMatchId: string | undefined;
+
+    for (const { id, vec } of existingVectors) {
+      const sim = cosineSimilarity(itemVec, vec);
+      if (sim > bestSimilarity) {
+        bestSimilarity = sim;
+        bestMatchId = id;
+      }
+    }
+
+    const isDuplicate = bestSimilarity >= DEDUP_THRESHOLD;
+
+    return {
+      item,
+      isDuplicate,
+      bestMatchId: isDuplicate ? bestMatchId : undefined,
+      similarity: bestSimilarity,
+    };
+  });
+}