enigma-memory 0.1.17 → 0.1.22

package/packages/snapcompact/index.d.ts

@@ -0,0 +1,284 @@
+/// <reference types="node" />
+
+export const SNAPCOMPACT_VERSION: '1.0.0';
+
+export interface RenderLimits {
+  maxCharacters?: number;
+  maxFrames?: number;
+  maxPixelsPerFrame?: number;
+  maxTotalPixels?: number;
+  maxPngBytes?: number;
+}
+
+export const DEFAULT_LIMITS: Readonly<Required<RenderLimits>>;
+
+export interface TokenEstimateAssumptions {
+  readonly textCharactersPerToken: number;
+  readonly imagePixelsPerToken: number;
+  readonly basis: string;
+}
+
+export const TOKEN_ESTIMATE_ASSUMPTIONS: Readonly<TokenEstimateAssumptions>;
+
+export type Provider = 'anthropic' | 'google' | 'openai';
+
+export interface ProviderProfile {
+  readonly id: string;
+  readonly provider: Provider;
+  readonly width: number;
+  readonly maxHeight: number;
+  readonly glyphWidth: 8;
+  readonly glyphHeight: 13;
+  readonly cellWidth: number;
+  readonly cellHeight: number;
+  readonly colorType: 0;
+  readonly imageDetail: 'original' | null;
+  readonly modelFamilies: readonly string[];
+  readonly columns: number;
+  readonly rowsPerFrame: number;
+  readonly tokenEstimate: Readonly<TokenEstimateAssumptions>;
+}
+
+export const PROVIDER_PROFILES: Readonly<Record<Provider, Readonly<ProviderProfile>>>;
+
+export interface NormalizeOptions {
+  maxCharacters?: number;
+  tabWidth?: number;
+}
+
+export function normalizeText(input: string, options?: NormalizeOptions): string;
+
+export interface ConversationMessage {
+  role: 'user' | 'assistant' | 'tool' | 'system' | string;
+  content?: unknown;
+  output?: unknown;
+  result?: unknown;
+  name?: string;
+  toolName?: string;
+  toolCallId?: string;
+  tool_call_id?: string;
+  [key: string]: unknown;
+}
+
+export interface SerializationOptions extends NormalizeOptions {
+  maxMessageCharacters?: number;
+  maxCharacters?: number;
+}
+
+export function serializeConversation(messages: readonly ConversationMessage[], options?: SerializationOptions): string;
+
+export interface RepetitionOptions {
+  minimumRun?: number;
+}
+
+export function compactRepeatedLines(text: string, options?: RepetitionOptions): string;
+
+export interface BdfGlyph {
+  readonly name: string;
+  readonly encoding: number;
+  readonly advance: number;
+  readonly width: number;
+  readonly height: number;
+  readonly xOffset: number;
+  readonly yOffset: number;
+  readonly bitmap: readonly bigint[];
+}
+
+export interface BdfFont {
+  readonly width: number;
+  readonly height: number;
+  readonly xOffset: number;
+  readonly yOffset: number;
+  readonly glyphs: ReadonlyMap<number, Readonly<BdfGlyph>>;
+}
+
+export function parseBdf(source: string | Buffer): Readonly<BdfFont>;
+
+export function resolveProviderProfile(provider: string, model: string): Readonly<ProviderProfile> | null;
+
+export interface ProfileRequest {
+  provider: string;
+  model: string;
+}
+
+export interface RenderOptions extends Partial<ProfileRequest> {
+  profile?: Readonly<ProviderProfile>;
+  limits?: RenderLimits;
+  tabWidth?: number;
+  collapseRepeatedLines?: boolean;
+  repetition?: RepetitionOptions;
+}
+
+export interface FramePlanPage {
+  readonly index: number;
+  readonly width: number;
+  readonly height: number;
+  readonly rows: number;
+  readonly startRow: number;
+  readonly endRow: number;
+}
+
+export interface FramePlan {
+  readonly profileId: string;
+  readonly frameCount: number;
+  readonly sourceCharacters: number;
+  readonly renderedCharacters: number;
+  readonly columns: number;
+  readonly rowsPerFrame: number;
+  readonly rowCount: number;
+  readonly pixelCount: number;
+  readonly pages: readonly Readonly<FramePlanPage>[];
+}
+
+export function countFrames(
+  source: string,
+  profileOrRequest: Readonly<ProviderProfile> | ProfileRequest,
+  options?: RenderOptions,
+): Readonly<FramePlan>;
+
+export interface BitmapPage {
+  readonly index: number;
+  readonly width: number;
+  readonly height: number;
+  readonly png: Buffer;
+  readonly bytes: number;
+  readonly sha256: string;
+  readonly sourceSha256: string;
+}
+
+export interface AnthropicImageBlock {
+  readonly type: 'image';
+  readonly source: { readonly type: 'base64'; readonly media_type: 'image/png'; readonly data: string };
+}
+
+export interface GoogleImageBlock {
+  readonly inlineData: { readonly mimeType: 'image/png'; readonly data: string };
+}
+
+export interface OpenAiImageBlock {
+  readonly type: 'input_image';
+  readonly image_url: string;
+  readonly detail: 'original';
+}
+
+export type ProviderImageBlock = AnthropicImageBlock | GoogleImageBlock | OpenAiImageBlock;
+
+export interface BitmapReceipt {
+  readonly version: string;
+  readonly profile: string;
+  readonly contextDigest: string;
+  readonly sourceSha256: string;
+  readonly payloadDigest: string;
+  readonly pageSha256s: readonly string[];
+  readonly pageSourceSha256s: readonly string[];
+  readonly sourceCharacters: number;
+  readonly renderedCharacters: number;
+  readonly lineCount: number;
+  readonly frameCount: number;
+  readonly pixelCount: number;
+  readonly byteCount: number;
+}
+
+export interface BitmapRenderResult {
+  readonly version: string;
+  readonly profile: Readonly<ProviderProfile>;
+  readonly textFallback: string;
+  readonly pages: readonly Readonly<BitmapPage>[];
+  readonly blocks: readonly Readonly<ProviderImageBlock>[];
+  readonly receipt: Readonly<BitmapReceipt>;
+}
+
+export function renderBitmapContext(
+  source: string,
+  request: RenderOptions & (ProfileRequest | { profile: Readonly<ProviderProfile> }),
+): Readonly<BitmapRenderResult>;
+
+export interface CostInputs {
+  textInputUsdPerMillion: number;
+  imageInputUsdPerMillion: number;
+  outputUsdPerMillion?: number;
+  decodeOutputTokens?: number;
+  decodeFixedUsd?: number;
+}
+
+export interface TokenEstimateOverrides {
+  textCharactersPerToken?: number;
+  imagePixelsPerToken?: number;
+}
+
+export interface DecisionRequest extends RenderOptions {
+  provider: string;
+  model: string;
+  source: string;
+  vision: boolean;
+  expectedReuse?: number;
+  costs?: CostInputs;
+  tokenEstimates?: TokenEstimateOverrides;
+}
+
+export interface TransportEstimates {
+  readonly textTokens: number;
+  readonly imageTokens: number;
+  readonly textUsd: number;
+  readonly imageInputUsd: number;
+  readonly oneTimeDecodeUsd: number;
+  readonly imageUsd: number;
+  readonly assumptions: Readonly<TokenEstimateAssumptions>;
+}
+
+export interface TextTransportDecision {
+  readonly selected: 'text';
+  readonly eligible: boolean;
+  readonly reason: string;
+  readonly profile: string | null;
+  readonly textFallback: string;
+  readonly expectedReuse?: number;
+  readonly frameCount?: number;
+  readonly estimates?: Readonly<TransportEstimates>;
+}
+
+export interface BitmapTransportDecision {
+  readonly selected: 'bitmap-png';
+  readonly eligible: true;
+  readonly reason: 'lower-estimated-input-cost';
+  readonly profile: string;
+  readonly textFallback: string;
+  readonly expectedReuse: number;
+  readonly frameCount: number;
+  readonly estimates: Readonly<TransportEstimates>;
+}
+
+export type ContextTransportDecision = TextTransportDecision | BitmapTransportDecision;
+
+export function decideContextTransport(request: DecisionRequest): Readonly<ContextTransportDecision>;
+
+export interface ContextCarrierDescriptor {
+  readonly codec: 'utf8' | 'bitmap-png';
+  readonly version: string;
+  readonly profile: string | null;
+  readonly contextDigest: string;
+  readonly payloadDigest: string;
+  readonly dimensions: readonly Readonly<{ width: number; height: number }>[];
+  readonly bytes: number;
+  readonly counts: Readonly<{ characters: number; frames: number; pixels: number }>;
+}
+
+interface ContextCarrierRequestBase extends Omit<DecisionRequest, 'source'> {
+  serialization?: SerializationOptions;
+}
+
+export type ContextCarrierRequest = ContextCarrierRequestBase & (
+  | { source: string; messages?: never }
+  | { messages: readonly ConversationMessage[]; source?: never }
+);
+
+export interface ContextCarrier {
+  readonly selected: 'text' | 'bitmap-png';
+  readonly textFallback: string;
+  readonly blocks: readonly Readonly<ProviderImageBlock>[];
+  readonly pages: readonly Readonly<BitmapPage>[];
+  readonly descriptor: Readonly<ContextCarrierDescriptor>;
+  readonly decision: Readonly<ContextTransportDecision>;
+}
+
+export function createContextCarrier(request: ContextCarrierRequest): Readonly<ContextCarrier>;

package/packages/snapcompact/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@enigma/snapcompact",
+  "version": "0.1.0",
+  "description": "Deterministic local bitmap context carrier for vision-capable providers",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "assets/",
+    "index.d.ts",
+    "THIRD_PARTY_LICENSES.txt"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "SEE LICENSE IN ../../LICENSE"
+}