@diyor28/context 1.0.0

package/dist/adapters/summarizer.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Summarizer: Generate summaries with sensitivity filtering.
+ *
+ * Provides schema-enforced summarization with forbidden field validation.
+ */
+import type { ZodSchema } from 'zod';
+import type { ContextBlock, SensitivityLevel } from '../types/block.js';
+import type { ModelRef } from '../types/policy.js';
+/**
+ * Summarization provenance.
+ */
+export interface SummaryProvenance {
+    /** Source block hashes */
+    derivedFrom: string[];
+    /** Summarization method */
+    method: 'summarize';
+    /** Summarizer version */
+    version: string;
+    /** Source content snapshot hash */
+    snapshotHash: string;
+    /** Creation timestamp */
+    createdAt: number;
+}
+/**
+ * Summary block result.
+ */
+export interface SummaryBlock<TOutput = unknown> {
+    /** Validated summary output */
+    summary: TOutput;
+    /** Provenance information */
+    provenance: SummaryProvenance;
+    /** Token usage */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Summarizer interface.
+ */
+export interface Summarizer {
+    /**
+     * Generate a summary of blocks with schema validation.
+     *
+     * @param blocks - Blocks to summarize
+     * @param schema - Expected output schema
+     * @param options - Summarization options
+     * @returns Summary block
+     */
+    summarize<TOutput>(blocks: ContextBlock<unknown>[], schema: ZodSchema<TOutput>, options?: SummarizationOptions): Promise<SummaryBlock<TOutput>>;
+}
+/**
+ * Summarization options.
+ */
+export interface SummarizationOptions {
+    /** Instruction/prompt for summarization */
+    instruction?: string;
+    /** Maximum output tokens */
+    maxOutputTokens?: number;
+    /** Forbidden fields that must not appear in summary */
+    forbiddenFields?: string[];
+    /** Allowed sensitivity levels for summarization */
+    allowedForSummarization?: SensitivityLevel[];
+}
+/**
+ * Default summarization options.
+ */
+export declare const DEFAULT_SUMMARIZATION_OPTIONS: Required<Omit<SummarizationOptions, 'instruction' | 'maxOutputTokens'>>;
+/**
+ * Default summarizer using gpt-5-nano.
+ */
+export declare class DefaultSummarizer implements Summarizer {
+    private readonly modelRef;
+    private readonly executor?;
+    private readonly version;
+    constructor(modelRef?: ModelRef, executor?: ((instruction: string, content: string, schema: ZodSchema) => Promise<{
+        output: unknown;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            totalTokens: number;
+        };
+    }>) | undefined);
+    /**
+     * Filter blocks by sensitivity level.
+     *
+     * @param blocks - Blocks to filter
+     * @param allowedLevels - Allowed sensitivity levels
+     * @returns Filtered blocks
+     */
+    private filterBySensitivity;
+    /**
+     * Compute snapshot hash from block hashes.
+     *
+     * @param blocks - Blocks to hash
+     * @returns Hex-encoded SHA-256 hash
+     */
+    private computeSnapshotHash;
+    /**
+     * Default executor (throws error - must be provided).
+     */
+    private defaultExecutor;
+    summarize<TOutput>(blocks: ContextBlock<unknown>[], schema: ZodSchema<TOutput>, options?: SummarizationOptions): Promise<SummaryBlock<TOutput>>;
+}
+/**
+ * Create a summarizer with custom model.
+ *
+ * @param modelRef - Model reference
+ * @param executor - Executor function
+ * @returns Summarizer instance
+ */
+export declare function createSummarizer(modelRef: ModelRef, executor: (instruction: string, content: string, schema: ZodSchema) => Promise<{
+    output: unknown;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+}>): Summarizer;
+//# sourceMappingURL=summarizer.d.ts.map

package/dist/adapters/summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.d.ts","sourceRoot":"","sources":["../../src/adapters/summarizer.ts"],"names":[],"mappings":"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"}

package/dist/adapters/summarizer.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Summarizer: Generate summaries with sensitivity filtering.
+ *
+ * Provides schema-enforced summarization with forbidden field validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultSummarizer = exports.DEFAULT_SUMMARIZATION_OPTIONS = void 0;
+exports.createSummarizer = createSummarizer;
+const crypto_1 = require("crypto");
+/**
+ * Default summarization options.
+ */
+exports.DEFAULT_SUMMARIZATION_OPTIONS = {
+    forbiddenFields: ['raw_messages', 'full_transcript', 'raw_history'],
+    allowedForSummarization: ['public'],
+};
+/**
+ * Default summarizer using gpt-5-nano.
+ */
+class DefaultSummarizer {
+    modelRef;
+    executor;
+    version = '1.0.0';
+    constructor(modelRef = {
+        provider: 'openai',
+        model: 'gpt-5-nano',
+    }, executor) {
+        this.modelRef = modelRef;
+        this.executor = executor;
+    }
+    /**
+     * Filter blocks by sensitivity level.
+     *
+     * @param blocks - Blocks to filter
+     * @param allowedLevels - Allowed sensitivity levels
+     * @returns Filtered blocks
+     */
+    filterBySensitivity(blocks, allowedLevels) {
+        return blocks.filter((block) => allowedLevels.includes(block.meta.sensitivity));
+    }
+    /**
+     * Compute snapshot hash from block hashes.
+     *
+     * @param blocks - Blocks to hash
+     * @returns Hex-encoded SHA-256 hash
+     */
+    computeSnapshotHash(blocks) {
+        const concatenated = blocks.map((b) => b.blockHash).join('|');
+        return (0, crypto_1.createHash)('sha256').update(concatenated).digest('hex');
+    }
+    /**
+     * Default executor (throws error - must be provided).
+     */
+    async defaultExecutor(instruction, content, schema) {
+        throw new Error('Summarizer executor not provided. Please provide an executor function in constructor.');
+    }
+    async summarize(blocks, schema, options) {
+        const opts = {
+            ...exports.DEFAULT_SUMMARIZATION_OPTIONS,
+            ...options,
+        };
+        // Filter blocks by sensitivity
+        const filteredBlocks = this.filterBySensitivity(blocks, opts.allowedForSummarization ?? exports.DEFAULT_SUMMARIZATION_OPTIONS.allowedForSummarization);
+        if (filteredBlocks.length === 0) {
+            throw new Error('No blocks available for summarization after sensitivity filtering');
+        }
+        // Build content string from blocks
+        const content = filteredBlocks
+            .map((block, idx) => {
+            return `[Block ${idx + 1}/${filteredBlocks.length}]\nKind: ${block.meta.kind}\nPayload: ${JSON.stringify(block.payload, null, 2)}`;
+        })
+            .join('\n\n---\n\n');
+        // Build instruction
+        const instruction = opts.instruction ??
+            'Summarize the following context blocks concisely. Focus on key information and maintain accuracy.';
+        // Add forbidden fields note if specified
+        const enhancedInstruction = opts.forbiddenFields
+            ? `${instruction}\n\nIMPORTANT: Your summary MUST NOT include these fields: ${opts.forbiddenFields.join(', ')}`
+            : instruction;
+        // Execute summarization
+        const executor = this.executor ?? this.defaultExecutor.bind(this);
+        const result = await executor(enhancedInstruction, content, schema);
+        // Validate output against schema
+        const validatedOutput = schema.parse(result.output);
+        // Check for forbidden fields
+        if (opts.forbiddenFields && opts.forbiddenFields.length > 0) {
+            const outputStr = JSON.stringify(validatedOutput);
+            for (const field of opts.forbiddenFields) {
+                if (outputStr.includes(field)) {
+                    throw new Error(`Summarization failed: Output contains forbidden field '${field}'`);
+                }
+            }
+        }
+        // Compute snapshot hash
+        const snapshotHash = this.computeSnapshotHash(filteredBlocks);
+        return {
+            summary: validatedOutput,
+            provenance: {
+                derivedFrom: filteredBlocks.map((b) => b.blockHash),
+                method: 'summarize',
+                version: this.version,
+                snapshotHash,
+                createdAt: Math.floor(Date.now() / 1000),
+            },
+            usage: result.usage,
+        };
+    }
+}
+exports.DefaultSummarizer = DefaultSummarizer;
+/**
+ * Create a summarizer with custom model.
+ *
+ * @param modelRef - Model reference
+ * @param executor - Executor function
+ * @returns Summarizer instance
+ */
+function createSummarizer(modelRef, executor) {
+    return new DefaultSummarizer(modelRef, executor);
+}
+//# sourceMappingURL=summarizer.js.map

package/dist/adapters/summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.js","sourceRoot":"","sources":["../../src/adapters/summarizer.ts"],"names":[],"mappings":"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"}

package/dist/adapters/token-estimator.d.ts

@@ -0,0 +1,63 @@
+/**
+ * TokenEstimator: Single source of truth for token counting.
+ *
+ * Provides provider-specific token estimation for context blocks.
+ * NOT implemented by codecs - this is the only place token counting happens.
+ */
+import type { ContextBlock } from '../types/block.js';
+/**
+ * Token estimation result.
+ */
+export interface TokenEstimate {
+    /** Estimated token count */
+    tokens: number;
+    /**
+     * Confidence level:
+     * - 'exact': API-provided count (Anthropic)
+     * - 'high': tiktoken-based (OpenAI/Gemini)
+     * - 'low': Heuristic fallback (chars / 4)
+     */
+    confidence: 'exact' | 'high' | 'low';
+}
+/**
+ * TokenEstimator interface.
+ * All implementations must be async (Anthropic uses API calls).
+ */
+export interface TokenEstimator {
+    /**
+     * Estimate tokens for a list of blocks.
+     *
+     * @param blocks - Blocks to estimate
+     * @returns Token estimate
+     */
+    estimate(blocks: ContextBlock<unknown>[]): Promise<TokenEstimate>;
+    /**
+     * Estimate tokens for a single block.
+     *
+     * @param block - Block to estimate
+     * @returns Token estimate
+     */
+    estimateBlock(block: ContextBlock<unknown>): Promise<TokenEstimate>;
+}
+/**
+ * Safety multiplier for low-confidence estimates.
+ * Applies 1.2x multiplier to heuristic estimates to avoid budget overruns.
+ */
+export declare const LOW_CONFIDENCE_MULTIPLIER = 1.2;
+/**
+ * Heuristic token estimation (chars / 4).
+ * Used as fallback when tiktoken/API is unavailable.
+ *
+ * @param text - Text to estimate
+ * @returns Token count
+ */
+export declare function heuristicTokenCount(text: string): number;
+/**
+ * Serialize a block to text for token estimation.
+ * Uses JSON.stringify as a reasonable approximation of rendered content.
+ *
+ * @param block - Block to serialize
+ * @returns Serialized text
+ */
+export declare function serializeBlockForEstimation(block: ContextBlock<unknown>): string;
+//# sourceMappingURL=token-estimator.d.ts.map

package/dist/adapters/token-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.d.ts","sourceRoot":"","sources":["../../src/adapters/token-estimator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAElE;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACrE;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,MAAM,CAEhF"}

package/dist/adapters/token-estimator.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * TokenEstimator: Single source of truth for token counting.
+ *
+ * Provides provider-specific token estimation for context blocks.
+ * NOT implemented by codecs - this is the only place token counting happens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOW_CONFIDENCE_MULTIPLIER = void 0;
+exports.heuristicTokenCount = heuristicTokenCount;
+exports.serializeBlockForEstimation = serializeBlockForEstimation;
+/**
+ * Safety multiplier for low-confidence estimates.
+ * Applies 1.2x multiplier to heuristic estimates to avoid budget overruns.
+ */
+exports.LOW_CONFIDENCE_MULTIPLIER = 1.2;
+/**
+ * Heuristic token estimation (chars / 4).
+ * Used as fallback when tiktoken/API is unavailable.
+ *
+ * @param text - Text to estimate
+ * @returns Token count
+ */
+function heuristicTokenCount(text) {
+    return Math.ceil((text.length / 4) * exports.LOW_CONFIDENCE_MULTIPLIER);
+}
+/**
+ * Serialize a block to text for token estimation.
+ * Uses JSON.stringify as a reasonable approximation of rendered content.
+ *
+ * @param block - Block to serialize
+ * @returns Serialized text
+ */
+function serializeBlockForEstimation(block) {
+    return JSON.stringify(block.payload);
+}
+//# sourceMappingURL=token-estimator.js.map

package/dist/adapters/token-estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.js","sourceRoot":"","sources":["../../src/adapters/token-estimator.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAuDH,kDAEC;AASD,kEAEC;AA1BD;;;GAGG;AACU,QAAA,yBAAyB,GAAG,GAAG,CAAC;AAE7C;;;;;;GAMG;AACH,SAAgB,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,iCAAyB,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,2BAA2B,CAAC,KAA4B;IACtE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC"}

package/dist/builder/context-builder.d.ts

@@ -0,0 +1,186 @@
+/**
+ * ContextBuilder: Fluent API for composing context graphs.
+ *
+ * Provides a declarative interface for building context from various sources:
+ * - System rules (pinned)
+ * - References (tool schemas, docs)
+ * - State (current workflow/session)
+ * - Memory (long-term, RAG results)
+ * - History (conversation turns)
+ * - Attachments (images, PDFs)
+ * - Current turn (user message)
+ */
+import type { BlockKind, SensitivityLevel } from '../types/block.js';
+import type { BlockCodec } from '../types/codec.js';
+import type { ContextPolicy, Provider } from '../types/policy.js';
+import type { AttachmentRef } from '../types/attachment.js';
+import type { CompiledContext } from '../types/compiled.js';
+import { ContextGraph } from '../graph/context-graph.js';
+import { type SystemRulesPayload } from '../codecs/system-rules.codec.js';
+import { type ConversationMessage } from '../codecs/conversation-history.codec.js';
+/**
+ * Fork options for creating specialized contexts.
+ */
+export interface ForkOptions {
+    /** Maximum sensitivity level to include */
+    maxSensitivity?: SensitivityLevel;
+    /** Block kinds to include (omit = include all) */
+    includeKinds?: BlockKind[];
+    /** Block kinds to exclude */
+    excludeKinds?: BlockKind[];
+    /** Optional tag filter */
+    tags?: string[];
+}
+/**
+ * ContextBuilder: Fluent API for composing context.
+ *
+ * Usage:
+ * ```ts
+ * const builder = new ContextBuilder();
+ * builder
+ *   .system({ text: 'You are a helpful assistant.' })
+ *   .history(previousMessages)
+ *   .turn('What is the capital of France?');
+ *
+ * const compiled = await builder.compile(policy, 'anthropic');
+ * ```
+ */
+export declare class ContextBuilder {
+    private readonly graph;
+    private blockCounter;
+    constructor();
+    /**
+     * Add a pinned system rules block.
+     *
+     * @param rules - System rules payload
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    system(rules: SystemRulesPayload, options?: {
+        sensitivity?: SensitivityLevel;
+        source?: string;
+        tags?: string[];
+    }): this;
+    /**
+     * Add a reference block (tool schema, external doc, etc.).
+     *
+     * @param codec - Block codec for the reference type
+     * @param data - Reference payload
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    reference<TPayload>(codec: BlockCodec<TPayload>, data: TPayload, options?: {
+        sensitivity?: SensitivityLevel;
+        source?: string;
+        tags?: string[];
+    }): this;
+    /**
+     * Add a state block (current workflow/session state).
+     *
+     * @param codec - Block codec for the state type
+     * @param data - State payload
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    state<TPayload>(codec: BlockCodec<TPayload>, data: TPayload, options?: {
+        sensitivity?: SensitivityLevel;
+        source?: string;
+        tags?: string[];
+    }): this;
+    /**
+     * Add a memory block (long-term memory, RAG results).
+     *
+     * @param codec - Block codec for the memory type
+     * @param data - Memory payload
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    memory<TPayload>(codec: BlockCodec<TPayload>, data: TPayload, options?: {
+        sensitivity?: SensitivityLevel;
+        source?: string;
+        tags?: string[];
+    }): this;
+    /**
+     * Add a conversation history block.
+     *
+     * @param messages - Array of conversation messages
+     * @param summary - Optional summary of earlier messages
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    history(messages: ConversationMessage[], summary?: string, options?: {
+        sensitivity?: SensitivityLevel;
+        source?: string;
+        tags?: string[];
+    }): this;
+    /**
+     * Add attachment blocks (images, PDFs, etc.).
+     * Note: Attachments need to be resolved via AttachmentResolver before compilation.
+     *
+     * @param attachments - Array of attachments
+     * @param codec - Block codec for attachment type
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    attachments<TPayload>(attachments: AttachmentRef[], codec: BlockCodec<TPayload>, options?: {
+        sensitivity?: SensitivityLevel;
+        source?: string;
+        tags?: string[];
+    }): this;
+    /**
+     * Add a user turn block (current user message).
+     *
+     * @param text - User message text
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    turn(text: string, options?: {
+        sensitivity?: SensitivityLevel;
+        source?: string;
+        tags?: string[];
+    }): this;
+    /**
+     * Create a forked context with filtering.
+     * Useful for creating specialized contexts (e.g., public-only for external models).
+     *
+     * @param options - Fork filtering options
+     * @returns New ContextBuilder with filtered blocks
+     */
+    fork(options: ForkOptions): ContextBuilder;
+    /**
+     * Compile the context for a specific provider.
+     * This is a placeholder - actual compilation happens in provider compilers.
+     *
+     * @param policy - Context policy configuration
+     * @param provider - Target provider
+     * @returns Compiled context
+     */
+    compile(policy: ContextPolicy, provider: Provider): Promise<CompiledContext>;
+    /**
+     * Get the underlying context graph.
+     *
+     * @returns Context graph
+     */
+    getGraph(): ContextGraph;
+    /**
+     * Get the number of blocks in the builder.
+     *
+     * @returns Block count
+     */
+    getBlockCount(): number;
+    /**
+     * Clear all blocks from the builder.
+     */
+    clear(): void;
+    /**
+     * Create a block with generated hash and metadata.
+     *
+     * @param kind - Block kind
+     * @param codec - Block codec
+     * @param payload - Block payload
+     * @param options - Optional metadata overrides
+     * @returns Context block
+     */
+    private createBlock;
+}
+//# sourceMappingURL=context-builder.d.ts.map

package/dist/builder/context-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../../src/builder/context-builder.ts"],"names":[],"mappings":"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"}