Building Resumable AI Systems

1
import { v4 as uuid } from 'uuid';
2
import type { CognitiveSession, CognitiveCheckpoint } from './types';
3
 
4
export function createCheckpoint(
5
  session: CognitiveSession,
6
  options: { label: string; description?: string }
7
): CognitiveCheckpoint {
8
  const { nodes, epistemicState, intentGraph } = session.workingState;
9
  const now = Date.now();
10
 
11
  // Calculate metrics
12
  const completedNodes = nodes.filter(n => n.status === 'completed').length;
13
  const tokenEstimate = estimateTokens(session);
14
 
15
  return {
16
    id: uuid(),
17
    timestamp: now,
18
    label: options.label,
19
    description: options.description,
20
    nodes: structuredClone(nodes),           // Deep clone
21
    epistemicState: structuredClone(epistemicState),
22
    intentGraph: structuredClone(intentGraph),
23
    branchId: session.currentBranchId,
24
    parentCheckpointId: session.branches[session.currentBranchId]?.headCheckpointId,
25
    metrics: {
26
      totalNodes: nodes.length,
27
      completedNodes,
28
      tokenEstimate,
29
      elapsedMs: now - session.createdAt,
30
    },
31
  };
32
}

1
export function restoreFromCheckpoint(
2
  checkpoint: CognitiveCheckpoint,
3
  currentSession?: CognitiveSession
4
): { success: boolean; session: CognitiveSession; warnings: string[] } {
5
  const warnings: string[] = [];
6
 
7
  // Check for staleness
8
  const ageHours = (Date.now() - checkpoint.timestamp) / (1000 * 60 * 60);
9
  if (ageHours > 24) {
10
    warnings.push(`Checkpoint is ${Math.round(ageHours)} hours old`);
11
  }
12
 
13
  // Validate checkpoint integrity
14
  const validation = validateCheckpoint(checkpoint);
15
  if (!validation.valid) {
16
    throw new Error(`Invalid checkpoint: ${validation.errors.join(', ')}`);
17
  }
18
  warnings.push(...validation.warnings);
19
 
20
  // Create restored session
21
  const restoredSession: CognitiveSession = {
22
    id: currentSession?.id || uuid(),
23
    name: `Restored: ${checkpoint.label}`,
24
    description: `Restored from checkpoint at ${new Date(checkpoint.timestamp).toISOString()}`,
25
    createdAt: currentSession?.createdAt || Date.now(),
26
    lastModifiedAt: Date.now(),
27
    currentBranchId: checkpoint.branchId,
28
    activeNodeId: undefined,
29
    branches: currentSession?.branches || {},
30
    checkpoints: {
31
      ...(currentSession?.checkpoints || {}),
32
      [checkpoint.id]: checkpoint,
33
    },
34
    workingState: {
35
      nodes: structuredClone(checkpoint.nodes),
36
      epistemicState: structuredClone(checkpoint.epistemicState),
37
      intentGraph: structuredClone(checkpoint.intentGraph),
38
    },
39
    totalMetrics: {
40
      ...currentSession?.totalMetrics,
41
      resumeCount: (currentSession?.totalMetrics.resumeCount || 0) + 1,
42
    },
43
  };
44
 
45
  return { success: true, session: restoredSession, warnings };
46
}

1
export function validateCheckpoint(checkpoint: CognitiveCheckpoint): {
2
  valid: boolean;
3
  errors: string[];
4
  warnings: string[];
5
} {
6
  const errors: string[] = [];
7
  const warnings: string[] = [];
8
  const nodeIds = new Set(checkpoint.nodes.map(n => n.id));
9
 
10
  // Check required fields
11
  if (!checkpoint.id) errors.push('Missing checkpoint ID');
12
  if (!checkpoint.label) errors.push('Missing label');
13
  if (!checkpoint.branchId) errors.push('Missing branch ID');
14
 
15
  // Validate node graph integrity
16
  for (const node of checkpoint.nodes) {
17
    // Check parent references
18
    if (node.parentId && !nodeIds.has(node.parentId)) {
19
      errors.push(`Node ${node.id} references missing parent`);
20
    }
21
 
22
    // Check child references
23
    for (const childId of node.childIds) {
24
      if (!nodeIds.has(childId)) {
25
        errors.push(`Node ${node.id} references missing child`);
26
      }
27
    }
28
 
29
    // Validate confidence bounds
30
    if (node.confidence < 0 || node.confidence > 1) {
31
      warnings.push(`Node ${node.id} has invalid confidence`);
32
    }
33
  }
34
 
35
  // Check for circular references
36
  if (hasCircularReferences(checkpoint.nodes)) {
37
    errors.push('Circular reference detected in node graph');
38
  }
39
 
40
  return { valid: errors.length === 0, errors, warnings };
41
}

1
type LLMMiddleware = (
2
  request: LLMRequest,
3
  next: (req: LLMRequest) => Promise<LLMResponse>
4
) => Promise<LLMResponse>;
5
 
6
export function createCheckpointMiddleware(
7
  store: CognitiveStore,
8
  options: { autoCheckpointInterval?: number } = {}
9
): LLMMiddleware {
10
  let requestCount = 0;
11
  const interval = options.autoCheckpointInterval || 10;
12
 
13
  return async (request, next) => {
14
    requestCount++;
15
 
16
    // Check for resume instruction in system prompt
17
    if (request.systemPrompt?.includes('RESUME_FROM:')) {
18
      const checkpointId = extractCheckpointId(request.systemPrompt);
19
      const checkpoint = store.getCheckpoint(checkpointId);
20
      if (checkpoint) {
21
        store.restoreFromCheckpoint(checkpoint);
22
        request.systemPrompt = request.systemPrompt
23
          .replace(/RESUME_FROM:[\w-]+/, '')
24
          + formatStateForPrompt(checkpoint);
25
      }
26
    }
27
 
28
    // Execute the request
29
    const response = await next(request);
30
 
31
    // Update cognitive state from response
32
    store.updateFromResponse(response);
33
 
34
    // Auto-checkpoint every N requests
35
    if (requestCount % interval === 0) {
36
      store.createCheckpoint({
37
        label: `Auto-checkpoint #${requestCount}`,
38
        description: 'Automatic periodic checkpoint',
39
      });
40
    }
41
 
42
    return response;
43
  };
44
}

1
import Anthropic from '@anthropic-ai/sdk';
2
import { CognitiveStore } from './cognitive-store';
3
import { serializeCheckpoint } from './serialization';
4
 
5
export class ResumableAIClient {
6
  private anthropic: Anthropic;
7
  private store: CognitiveStore;
8
 
9
  constructor(apiKey: string) {
10
    this.anthropic = new Anthropic({ apiKey });
11
    this.store = new CognitiveStore();
12
  }
13
 
14
  async chat(userMessage: string): Promise<string> {
15
    // Build context from current cognitive state
16
    const context = this.buildContextFromState();
17
 
18
    const response = await this.anthropic.messages.create({
19
      model: 'claude-3-sonnet-20240229',
20
      max_tokens: 4096,
21
      system: `You are a resumable AI assistant. Current cognitive state:
22
${context}
23
 
24
When you make decisions or learn new facts, structure your response to include:
25
- FACT: statements you've confirmed
26
- ASSUMPTION: things you're treating as true
27
- QUESTION: unresolved queries
28
- INTENT: goals you're working toward`,
29
      messages: [{ role: 'user', content: userMessage }],
30
    });
31
 
32
    // Parse and update cognitive state
33
    this.parseAndUpdateState(response);
34
 
35
    return response.content[0].text;
36
  }
37
 
38
  private buildContextFromState(): string {
39
    const checkpoint = this.store.getCurrentState();
40
    return serializeCheckpoint(checkpoint);
41
  }
42
 
43
  saveCheckpoint(label: string): string {
44
    const checkpoint = this.store.createCheckpoint({ label });
45
    return checkpoint.id;
46
  }
47
 
48
  restoreCheckpoint(id: string): void {
49
    const checkpoint = this.store.getCheckpoint(id);
50
    if (checkpoint) {
51
      this.store.restoreFromCheckpoint(checkpoint);
52
    }
53
  }
54
}