@diyor28/context 1.0.0

package/src/providers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Provider compiler exports.
+ */
+
+export * from './capabilities.js';
+export * from './anthropic-compiler.js';
+export * from './openai-compiler.js';
+export * from './gemini-compiler.js';

package/src/providers/openai-compiler.ts

@@ -0,0 +1,191 @@
+/**
+ * OpenAI compiler: Pure compilation to OpenAI chat completion format.
+ *
+ * Features:
+ * - Inline system messages
+ * - Tool/function calling support
+ * - Structured outputs
+ */
+
+import type { ContextBlock } from '../types/block.js';
+import type { ContextPolicy } from '../types/policy.js';
+import type { OpenAICompiledContext } from '../types/compiled.js';
+import type { BlockCodec } from '../types/codec.js';
+import { getProviderCapabilities } from './capabilities.js';
+
+/**
+ * OpenAI compilation options.
+ */
+export interface OpenAICompilationOptions {
+  /** Codec registry for rendering */
+  codecRegistry: Map<string, BlockCodec<unknown>>;
+
+  /** Include tool definitions (optional) */
+  tools?: unknown[];
+}
+
+/**
+ * Compile context to OpenAI chat completion format.
+ * Pure function: same inputs → identical outputs.
+ *
+ * @param blocks - Ordered blocks from ContextView
+ * @param policy - Context policy
+ * @param options - Compilation options
+ * @returns OpenAI compiled context
+ */
+export function compileOpenAIContext(
+  blocks: ContextBlock[],
+  policy: ContextPolicy,
+  options: OpenAICompilationOptions
+): OpenAICompiledContext {
+  const capabilities = getProviderCapabilities('openai');
+
+  // Compile all blocks to messages (including system messages inline)
+  const messages = compileMessages(blocks, options.codecRegistry);
+
+  // Calculate tokens (simplified - would use actual estimator in production)
+  const estimatedTokens = blocks.length * 100; // Placeholder
+
+  return {
+    provider: 'openai',
+    modelId: policy.modelId,
+    messages,
+    estimatedTokens,
+    blocks,
+    meta: {
+      compiledAt: Math.floor(Date.now() / 1000),
+      contextWindow: policy.contextWindow,
+      completionReserve: policy.completionReserve,
+      availableTokens: policy.contextWindow - policy.completionReserve,
+      overflowed: false,
+      compacted: false,
+      truncated: false,
+      tokensByKind: {},
+    },
+  };
+}
+
+/**
+ * Compile blocks to OpenAI messages.
+ * System messages are inlined as first messages.
+ *
+ * @param blocks - Context blocks
+ * @param codecRegistry - Codec registry
+ * @returns OpenAI messages
+ */
+function compileMessages(
+  blocks: ContextBlock[],
+  codecRegistry: Map<string, BlockCodec<unknown>>
+): Array<{
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: unknown;
+  name?: string;
+  tool_call_id?: string;
+}> {
+  const messages: Array<{
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: unknown;
+    name?: string;
+    tool_call_id?: string;
+  }> = [];
+
+  // Compile blocks in order
+  for (const block of blocks) {
+    const codec = codecRegistry.get(block.meta.codecId);
+
+    if (!codec) {
+      console.warn(`[OpenAI] Codec not found: ${block.meta.codecId}`);
+      continue;
+    }
+
+    const rendered = codec.render(block);
+    const openaiContent = rendered.openai as any;
+
+    // Handle different block kinds
+    if (block.meta.kind === 'pinned') {
+      // System messages
+      messages.push({
+        role: 'system',
+        content: openaiContent.content || openaiContent,
+      });
+    } else if (block.meta.kind === 'history') {
+      // History blocks are already in message format
+      if (Array.isArray(openaiContent)) {
+        messages.push(...openaiContent);
+      } else {
+        messages.push(openaiContent);
+      }
+    } else if (block.meta.kind === 'turn') {
+      // Turn blocks are user messages
+      messages.push({
+        role: 'user',
+        content: openaiContent.content || openaiContent,
+      });
+    } else if (block.meta.kind === 'tool_output') {
+      // Tool output blocks
+      messages.push({
+        role: 'tool',
+        content: typeof openaiContent === 'string'
+          ? openaiContent
+          : JSON.stringify(openaiContent),
+        tool_call_id: (block.payload as any).toolCallId || 'unknown',
+      });
+    } else {
+      // Other blocks (reference, memory, state) as user messages
+      messages.push({
+        role: 'user',
+        content: typeof openaiContent === 'string'
+          ? openaiContent
+          : JSON.stringify(openaiContent),
+      });
+    }
+  }
+
+  return messages;
+}
+
+/**
+ * Validate OpenAI message sequence.
+ * Ensures messages follow OpenAI's alternation rules.
+ *
+ * @param messages - OpenAI messages
+ * @returns Validation diagnostics
+ */
+export function validateOpenAIMessages(
+  messages: Array<{ role: string; content: unknown }>
+): Array<{ level: 'error' | 'warning'; message: string }> {
+  const diagnostics: Array<{ level: 'error' | 'warning'; message: string }> = [];
+
+  // Check for empty messages
+  if (messages.length === 0) {
+    diagnostics.push({
+      level: 'error',
+      message: 'Message array is empty',
+    });
+    return diagnostics;
+  }
+
+  // Check for user-assistant alternation
+  let lastRole: string | null = null;
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+
+    if (msg.role === 'user' && lastRole === 'user') {
+      diagnostics.push({
+        level: 'warning',
+        message: `Consecutive user messages at index ${i}`,
+      });
+    }
+
+    if (msg.role === 'assistant' && lastRole === 'assistant') {
+      diagnostics.push({
+        level: 'warning',
+        message: `Consecutive assistant messages at index ${i}`,
+      });
+    }
+
+    lastRole = msg.role;
+  }
+
+  return diagnostics;
+}

package/src/types/attachment.ts

@@ -0,0 +1,86 @@
+/**
+ * Attachment types for external content (images, PDFs, etc.).
+ */
+
+/**
+ * Attachment MIME type.
+ */
+export type AttachmentMimeType =
+  | 'image/png'
+  | 'image/jpeg'
+  | 'image/webp'
+  | 'image/gif'
+  | 'application/pdf'
+  | 'text/plain'
+  | 'text/markdown'
+  | 'application/json';
+
+/**
+ * Attachment storage backend.
+ */
+export type AttachmentStorage = 'local' | 's3' | 'gcs';
+
+/**
+ * Attachment metadata.
+ */
+export interface AttachmentMeta {
+  /** Attachment ID (content-addressed hash) */
+  attachmentId: string;
+
+  /** MIME type */
+  mimeType: AttachmentMimeType;
+
+  /** File size (bytes) */
+  sizeBytes: number;
+
+  /** Original filename (if available) */
+  filename?: string;
+
+  /** Storage backend */
+  storage: AttachmentStorage;
+
+  /** Storage path (backend-specific) */
+  storagePath: string;
+
+  /** Created timestamp (Unix seconds) */
+  createdAt: number;
+}
+
+/**
+ * Attachment reference in context block.
+ */
+export interface AttachmentRef {
+  /** Attachment ID */
+  attachmentId: string;
+
+  /** Optional description/caption */
+  description?: string;
+}
+
+/**
+ * Resolved attachment with content.
+ */
+export interface ResolvedAttachment extends AttachmentMeta {
+  /** Base64-encoded content (for images, PDFs) */
+  content?: string;
+
+  /** Text content (for text/plain, text/markdown) */
+  text?: string;
+
+  /** Parsed JSON content (for application/json) */
+  json?: unknown;
+}
+
+/**
+ * Attachment selection result (for token budgeting).
+ */
+export interface AttachmentSelection {
+  /** Selected attachments */
+  selected: ResolvedAttachment[];
+
+  /** Excluded attachments (over budget) */
+  excluded: AttachmentRef[];
+
+  /** Total tokens consumed */
+  totalTokens: number;
+}

package/src/types/block.ts

@@ -0,0 +1,84 @@
+/**
+ * Block types for @foundry/context
+ *
+ * Core data structures for context blocks with stable hashing and ordering.
+ */
+
+/**
+ * Block kind determines ordering in compiled context.
+ * Must follow KIND_ORDER for deterministic compilation.
+ */
+export type BlockKind =
+  | 'pinned'          // System rules, always first
+  | 'reference'       // Tool schemas, external docs
+  | 'memory'          // Long-term memory, RAG results
+  | 'state'           // Current workflow/session state
+  | 'tool_output'     // Tool execution results
+  | 'history'         // Conversation history
+  | 'turn';           // Current turn (user message)
+
+/**
+ * Sensitivity level for content filtering and forking.
+ */
+export type SensitivityLevel =
+  | 'public'          // Safe to fork to any model
+  | 'internal'        // Contains business logic/PII
+  | 'restricted';     // Contains credentials/secrets
+
+/**
+ * Block metadata (stable subset used for hashing).
+ */
+export interface BlockMeta {
+  /** Block kind (determines ordering) */
+  kind: BlockKind;
+
+  /** Content sensitivity level */
+  sensitivity: SensitivityLevel;
+
+  /** Codec identifier for rendering */
+  codecId: string;
+
+  /** Codec version for rendering */
+  codecVersion: string;
+
+  /** Unix timestamp (seconds) */
+  createdAt: number;
+
+  /** Optional source identifier (workflow ID, session ID, etc.) */
+  source?: string;
+
+  /** Optional tags for filtering */
+  tags?: string[];
+}
+
+/**
+ * Subset of BlockMeta used for stable hashing.
+ * Excludes volatile fields like createdAt, source, tags.
+ */
+export interface StableMetaSubset {
+  kind: BlockKind;
+  sensitivity: SensitivityLevel;
+  codecId: string;
+  codecVersion: string;
+}
+
+/**
+ * Context block with content-addressed hash.
+ */
+export interface ContextBlock<TPayload = unknown> {
+  /** Content-addressed hash (computed from meta + payload) */
+  blockHash: string;
+
+  /** Block metadata */
+  meta: BlockMeta;
+
+  /** Block payload (codec-specific) */
+  payload: TPayload;
+}
+
+/**
+ * Block reference (hash only, used in compiled context).
+ */
+export interface BlockRef {
+  blockHash: string;
+}

package/src/types/codec.ts

@@ -0,0 +1,68 @@
+/**
+ * Block codec interface for rendering and validation.
+ */
+
+import { z } from 'zod';
+import type { ContextBlock } from './block.js';
+
+/**
+ * Provider-specific rendered content.
+ */
+export interface RenderedContent {
+  /** Anthropic Claude format */
+  anthropic?: unknown;
+
+  /** OpenAI GPT format */
+  openai?: unknown;
+
+  /** Google Gemini format */
+  gemini?: unknown;
+}
+
+/**
+ * Block codec for content rendering and validation.
+ */
+export interface BlockCodec<TPayload = unknown> {
+  /** Unique codec identifier */
+  codecId: string;
+
+  /** Codec version (semver) */
+  version: string;
+
+  /** Payload schema for validation */
+  payloadSchema: z.ZodSchema<TPayload>;
+
+  /**
+   * Canonicalize payload for deterministic hashing.
+   * Must produce identical output for semantically equivalent inputs.
+   *
+   * @param payload - Raw payload
+   * @returns Canonicalized payload (serializable)
+   */
+  canonicalize(payload: TPayload): unknown;
+
+  /**
+   * Compute stable hash from canonicalized payload.
+   * Default: SHA-256 of JSON.stringify(canonicalized).
+   *
+   * @param canonicalized - Canonicalized payload
+   * @returns Hex-encoded hash
+   */
+  hash(canonicalized: unknown): string;
+
+  /**
+   * Render block content for provider-specific formats.
+   *
+   * @param block - Context block
+   * @returns Rendered content for each provider
+   */
+  render(block: ContextBlock<TPayload>): RenderedContent;
+
+  /**
+   * Validate payload against schema.
+   * Throws on validation failure.
+   *
+   * @param payload - Payload to validate
+   */
+  validate(payload: unknown): TPayload;
+}

package/src/types/compiled.ts

@@ -0,0 +1,109 @@
+/**
+ * Compiled context types for LLM provider consumption.
+ */
+
+import type { ContextBlock } from './block.js';
+import type { Provider } from './policy.js';
+import type { ResolvedAttachment } from './attachment.js';
+
+/**
+ * Compiled context for a specific provider.
+ */
+export interface CompiledContext {
+  /** Target provider */
+  provider: Provider;
+
+  /** Model identifier */
+  modelId: string;
+
+  /** Provider-specific messages array */
+  messages: unknown[];
+
+  /** Provider-specific system message(s) */
+  system?: unknown;
+
+  /** Resolved attachments (if any) */
+  attachments?: ResolvedAttachment[];
+
+  /** Total estimated tokens */
+  estimatedTokens: number;
+
+  /** Blocks included in compilation */
+  blocks: ContextBlock[];
+
+  /** Blocks excluded (overflow, sensitivity, etc.) */
+  excludedBlocks?: ContextBlock[];
+
+  /** Compilation metadata */
+  meta: CompiledContextMeta;
+}
+
+/**
+ * Compilation metadata.
+ */
+export interface CompiledContextMeta {
+  /** Compilation timestamp (Unix seconds) */
+  compiledAt: number;
+
+  /** Context window size */
+  contextWindow: number;
+
+  /** Completion reserve (tokens) */
+  completionReserve: number;
+
+  /** Available tokens (contextWindow - completionReserve) */
+  availableTokens: number;
+
+  /** Overflow occurred */
+  overflowed: boolean;
+
+  /** Compaction applied */
+  compacted: boolean;
+
+  /** Truncation applied */
+  truncated: boolean;
+
+  /** Token breakdown by block kind */
+  tokensByKind: Record<string, number>;
+}
+
+/**
+ * Anthropic-specific compiled context.
+ */
+export interface AnthropicCompiledContext extends CompiledContext {
+  provider: 'anthropic';
+  messages: Array<{
+    role: 'user' | 'assistant';
+    content: unknown;
+  }>;
+  system?: Array<{
+    type: 'text';
+    text: string;
+    cache_control?: { type: 'ephemeral' };
+  }>;
+}
+
+/**
+ * OpenAI-specific compiled context.
+ */
+export interface OpenAICompiledContext extends CompiledContext {
+  provider: 'openai';
+  messages: Array<{
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: unknown;
+    name?: string;
+    tool_call_id?: string;
+  }>;
+}
+
+/**
+ * Gemini-specific compiled context.
+ */
+export interface GeminiCompiledContext extends CompiledContext {
+  provider: 'gemini';
+  messages: Array<{
+    role: 'user' | 'model';
+    parts: unknown[];
+  }>;
+  system?: string;
+}

package/src/types/hash.ts

@@ -0,0 +1,58 @@
+/**
+ * Block hashing utilities.
+ */
+
+import { createHash } from 'crypto';
+import type { BlockMeta, StableMetaSubset } from './block.js';
+import type { BlockCodec } from './codec.js';
+
+/**
+ * Extract stable metadata subset for hashing.
+ * Excludes volatile fields like createdAt, source, tags.
+ *
+ * @param meta - Full block metadata
+ * @returns Stable metadata subset
+ */
+export function extractStableMetaSubset(meta: BlockMeta): StableMetaSubset {
+  return {
+    kind: meta.kind,
+    sensitivity: meta.sensitivity,
+    codecId: meta.codecId,
+    codecVersion: meta.codecVersion,
+  };
+}
+
+/**
+ * Compute content-addressed block hash.
+ * Uses StableMetaSubset + codec.canonicalize(payload) for deterministic hashing.
+ *
+ * @param meta - Block metadata (or StableMetaSubset)
+ * @param payload - Block payload (or canonicalized payload if codec not provided)
+ * @param codec - Block codec for canonicalization (optional)
+ * @returns Hex-encoded SHA-256 hash
+ */
+export function computeBlockHash<TPayload>(
+  meta: BlockMeta | StableMetaSubset,
+  payload: TPayload,
+  codec?: BlockCodec<TPayload>
+): string {
+  // Extract stable metadata subset (if full meta provided)
+  const stableMeta = 'createdAt' in meta ? extractStableMetaSubset(meta) : meta;
+
+  // Canonicalize payload (if codec provided)
+  const canonicalized = codec ? codec.canonicalize(payload) : payload;
+
+  // Combine stable meta + canonicalized payload
+  const combined = {
+    meta: stableMeta,
+    payload: canonicalized,
+  };
+
+  // Compute SHA-256 hash
+  const hash = createHash('sha256')
+    .update(JSON.stringify(combined))
+    .digest('hex');
+
+  return hash;
+}
+

package/src/types/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Core types for @foundry/context
+ */
+
+export * from './block.js';
+export * from './codec.js';
+export * from './hash.js';
+export * from './policy.js';
+export * from './attachment.js';
+export * from './compiled.js';