@x12i/optimixer 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Athenix License
+
+Copyright (c) Athenices. All rights reserved.
+
+This software is proprietary. Redistribution, modification, and use are permitted only under a separate written agreement with Athenices.
+
+For licensing inquiries, contact the rights holder.

package/README.md

@@ -0,0 +1,96 @@
+# @x12i/optimixer
+
+Prediction and learning layer for AI workloads. First pipeline: **`ai.max_tokens.v1`** (recommended max completion tokens from historical usage).
+
+Uses `@x12i/activix-contracts` for record agreement. Persists prediction/evidence through an Activix-compatible client.
+
+## Install
+
+```bash
+npm install @x12i/optimixer @x12i/activix-contracts
+# Optional for standalone mode:
+npm install @x12i/activix
+```
+
+## Usage
+
+### Embedded mode (caller owns Activix)
+
+```typescript
+import { Activix } from '@x12i/activix';
+import { Optimixer } from '@x12i/optimixer';
+
+const activix = await Activix.create({
+  collection: 'ai-gateway-activities',
+  mongoUri: process.env.MONGO_URI,
+});
+
+const optimixer = await Optimixer.create({
+  activixClient: activix,
+  activixCollection: 'ai-gateway-activities',
+  pipelines: { aiMaxTokens: { enabled: true } },
+});
+
+const prediction = await optimixer.predictAiMaxTokens({
+  actionTypeId: 'summarize',
+  inputSize: 1200,
+  contextSize: 800,
+  acceptableRisk: 'medium',
+  runContext: { sessionId: 'sess-1', jobId: 'job-1' },
+});
+
+// Use prediction.recommendedMaxTokens for the AI call
+
+await optimixer.completeAiMaxTokensPrediction({
+  requestId: prediction.requestId,
+  actual: {
+    promptTokens: 900,
+    completionTokens: 420,
+    totalTokens: 1320,
+    finishReason: 'stop',
+    latencyMs: 800,
+  },
+});
+```
+
+### Standalone mode
+
+```typescript
+const optimixer = await Optimixer.create({
+  activix: {
+    collection: 'optimixer-activities',
+    mongoUri: process.env.MONGO_URI,
+    storageMode: 'automatic',
+  },
+});
+```
+
+Requires peer `@x12i/activix`.
+
+## Flow
+
+```
+AI wrapper
+  → Optimixer.predictAiMaxTokens   (creates Activix record)
+  → AI call with recommendedMaxTokens
+  → Optimixer.completeAiMaxTokensPrediction (updates record + in-memory stats)
+```
+
+`requestId` equals the Activix `activityId` from `startRecord`.
+
+## Record conventions
+
+Optimixer writes Activix rows with:
+
+- `outer.input` — prediction request
+- `outer.output` — prediction result, then actual usage + learning on complete
+- `outer.metadata.kind` — `optimixer:prediction`
+- `outer.metadata.pipelineId` — `ai.max_tokens.v1`
+
+## Warmup
+
+On `create()`, Optimixer loads recent completed prediction rows via `findRecords` (when the client supports it) to repopulate in-memory quantile stats.
+
+## Version
+
+Pre-1.0 (`0.1.0`) while pipelines evolve.

package/dist/Optimixer.d.ts

@@ -0,0 +1,22 @@
+import type { AiMaxTokensCompleteInput, AiMaxTokensPredictionInput, AiMaxTokensPredictionResult, OptimixerCreateOptions } from './contracts/optimixer-types.js';
+export declare class Optimixer {
+    private readonly client;
+    private readonly collection?;
+    private readonly bucketStore;
+    private readonly aiMaxTokensEnabled;
+    private readonly aiMaxTokensConfig;
+    private readonly writer;
+    private readonly closeHook?;
+    private constructor();
+    static create(options: OptimixerCreateOptions): Promise<Optimixer>;
+    close(): Promise<void>;
+    warmup(limit?: number): Promise<number>;
+    predictAiMaxTokens(input: AiMaxTokensPredictionInput): Promise<AiMaxTokensPredictionResult>;
+    completeAiMaxTokensPrediction(input: AiMaxTokensCompleteInput): Promise<{
+        learning: {
+            bucketKey: string;
+            observedCompletionTokens: number;
+        };
+    }>;
+}
+//# sourceMappingURL=Optimixer.d.ts.map

package/dist/Optimixer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Optimixer.d.ts","sourceRoot":"","sources":["../src/Optimixer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,sBAAsB,EACvB,MAAM,gCAAgC,CAAC;AAgBxC,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAC7C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAsB;IAEjD,OAAO;WAgBM,MAAM,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,CAAC;IAoBlE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,MAAM,CAAC,KAAK,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBpC,kBAAkB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAQ3F,6BAA6B,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC;QAC5E,QAAQ,EAAE;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,wBAAwB,EAAE,MAAM,CAAA;SAAE,CAAC;KACnE,CAAC;CASH"}

package/dist/Optimixer.js

@@ -0,0 +1,78 @@
+import { createStandaloneActivixClient } from './adapters/standalone-activix.js';
+import { AI_MAX_TOKENS_V1_ALGORITHM_VERSION, AI_MAX_TOKENS_V1_PIPELINE_ID, } from './contracts/optimixer-types.js';
+import { completeAiMaxTokensPredictionV1, predictAiMaxTokensV1, recordAiMaxTokensPrediction, } from './pipelines/ai-max-tokens-v1.js';
+import { ActivixOptimixerWriter, warmupBucketStoreFromActivix, } from './persistence/activix-writer.js';
+import { BucketStore } from './state/bucket-store.js';
+export class Optimixer {
+    client;
+    collection;
+    bucketStore = new BucketStore();
+    aiMaxTokensEnabled;
+    aiMaxTokensConfig;
+    writer;
+    closeHook;
+    constructor(client, options) {
+        this.client = client;
+        this.collection = options.collection ?? options.activixCollection;
+        this.aiMaxTokensEnabled = options.pipelines?.aiMaxTokens?.enabled !== false;
+        this.aiMaxTokensConfig = options.pipelines?.aiMaxTokens;
+        this.closeHook = options.closeHook;
+        this.writer = new ActivixOptimixerWriter(client, {
+            collection: this.collection,
+            pipelineId: AI_MAX_TOKENS_V1_PIPELINE_ID,
+            algorithmVersion: AI_MAX_TOKENS_V1_ALGORITHM_VERSION,
+        });
+    }
+    static async create(options) {
+        let client = options.activixClient;
+        let collection = options.activixCollection ?? options.activix?.collection;
+        let closeHook;
+        if (!client) {
+            if (!options.activix) {
+                throw new Error('Optimixer.create requires activixClient or activix standalone config');
+            }
+            const standalone = await createStandaloneActivixClient(options.activix);
+            client = standalone.client;
+            collection = standalone.collection;
+            closeHook = standalone.close;
+        }
+        const optimixer = new Optimixer(client, { ...options, collection, closeHook });
+        await optimixer.warmup(options.warmupLimit ?? options.pipelines?.aiMaxTokens?.warmupLimit ?? 500);
+        return optimixer;
+    }
+    async close() {
+        if (this.closeHook) {
+            await this.closeHook();
+        }
+    }
+    async warmup(limit = 500) {
+        if (!this.aiMaxTokensEnabled) {
+            return 0;
+        }
+        return warmupBucketStoreFromActivix(this.client, {
+            collection: this.collection,
+            pipelineId: AI_MAX_TOKENS_V1_PIPELINE_ID,
+            limit,
+            onObservation: (actionTypeId, provider, model, completionTokens) => {
+                this.bucketStore.observe(`${actionTypeId}|${provider ?? '*'}|${model ?? '*'}`, completionTokens);
+            },
+        });
+    }
+    async predictAiMaxTokens(input) {
+        if (!this.aiMaxTokensEnabled) {
+            throw new Error('Optimixer ai.max_tokens.v1 pipeline is disabled');
+        }
+        const prediction = predictAiMaxTokensV1(input, this.bucketStore, this.aiMaxTokensConfig);
+        return recordAiMaxTokensPrediction(this.writer, input, prediction);
+    }
+    async completeAiMaxTokensPrediction(input) {
+        if (!this.aiMaxTokensEnabled) {
+            throw new Error('Optimixer ai.max_tokens.v1 pipeline is disabled');
+        }
+        return completeAiMaxTokensPredictionV1(this.client, this.writer, this.bucketStore, {
+            ...input,
+            collection: this.collection,
+        });
+    }
+}
+//# sourceMappingURL=Optimixer.js.map

package/dist/Optimixer.js.map

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

package/dist/adapters/standalone-activix.d.ts

@@ -0,0 +1,8 @@
+import type { ActivixActivityClient } from '@x12i/activix-contracts';
+import type { OptimixerStandaloneActivixConfig } from '../contracts/optimixer-types.js';
+export declare function createStandaloneActivixClient(config: OptimixerStandaloneActivixConfig): Promise<{
+    client: ActivixActivityClient;
+    collection: string;
+    close?: () => Promise<void>;
+}>;
+//# sourceMappingURL=standalone-activix.d.ts.map

package/dist/adapters/standalone-activix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone-activix.d.ts","sourceRoot":"","sources":["../../src/adapters/standalone-activix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,iCAAiC,CAAC;AAExF,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,gCAAgC,GACvC,OAAO,CAAC;IAAE,MAAM,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAwB7F"}

package/dist/adapters/standalone-activix.js

@@ -0,0 +1,23 @@
+export async function createStandaloneActivixClient(config) {
+    let ActivixCtor;
+    try {
+        ({ Activix: ActivixCtor } = await import('@x12i/activix'));
+    }
+    catch {
+        throw new Error('Optimixer standalone mode requires optional peer dependency @x12i/activix. Install it or pass activixClient instead.');
+    }
+    const ax = await ActivixCtor.create({
+        collection: config.collection,
+        mongoUri: config.mongoUri,
+        storageMode: config.storageMode ?? 'automatic',
+        playground: config.playground,
+        collectionRegistry: false,
+        autoCost: false,
+    });
+    return {
+        client: ax,
+        collection: config.collection,
+        close: () => ax.close(),
+    };
+}
+//# sourceMappingURL=standalone-activix.js.map

package/dist/adapters/standalone-activix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone-activix.js","sourceRoot":"","sources":["../../src/adapters/standalone-activix.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,MAAwC;IAExC,IAAI,WAAmD,CAAC;IACxD,IAAI,CAAC;QACH,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,sHAAsH,CACvH,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC;QAClC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,WAAW;QAC9C,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,kBAAkB,EAAE,KAAK;QACzB,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;IAEH,OAAO;QACL,MAAM,EAAE,EAAsC;QAC9C,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/contracts/optimixer-types.d.ts

@@ -0,0 +1,68 @@
+import type { ActivixRunContext } from '@x12i/activix-contracts';
+export type OptimixerPipelineId = 'ai.max_tokens.v1' | (string & {});
+export declare const AI_MAX_TOKENS_V1_PIPELINE_ID: OptimixerPipelineId;
+export declare const AI_MAX_TOKENS_V1_ALGORITHM_VERSION = "1.0.0";
+export type OptimixerAcceptableRisk = 'very-low' | 'low' | 'medium' | 'high' | number;
+export type OptimixerPredictionRecord = {
+    requestId: string;
+    pipelineId: OptimixerPipelineId;
+    algorithmVersion: string;
+    prediction: unknown;
+    actual?: unknown;
+    learning?: unknown;
+};
+export type AiMaxTokensPredictionInput = {
+    runContext?: ActivixRunContext;
+    actionTypeId: string;
+    inputSize: number;
+    contextSize: number;
+    plannedTools?: string[];
+    acceptableRisk: OptimixerAcceptableRisk;
+    provider?: string;
+    model?: string;
+};
+export type AiMaxTokensActualUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    finishReason?: string;
+    latencyMs?: number;
+};
+export type AiMaxTokensPredictionResult = {
+    requestId: string;
+    pipelineId: typeof AI_MAX_TOKENS_V1_PIPELINE_ID;
+    algorithmVersion: string;
+    recommendedMaxTokens: number;
+    confidence: 'cold-start' | 'warm';
+    bucketKey: string;
+    riskLevel: OptimixerAcceptableRisk;
+};
+export type AiMaxTokensCompleteInput = {
+    requestId: string;
+    actual: AiMaxTokensActualUsage;
+};
+export type OptimixerPipelineConfig = {
+    enabled?: boolean;
+    warmupLimit?: number;
+    defaultMaxTokens?: number;
+};
+export type OptimixerPipelinesConfig = {
+    aiMaxTokens?: OptimixerPipelineConfig;
+};
+export type OptimixerStandaloneActivixConfig = {
+    collection: string;
+    mongoUri?: string;
+    storageMode?: 'automatic' | 'database' | 'local';
+    playground?: {
+        outputDir?: string;
+        runId?: string;
+    };
+};
+export type OptimixerCreateOptions = {
+    activixClient?: import('@x12i/activix-contracts').ActivixActivityClient;
+    activix?: OptimixerStandaloneActivixConfig;
+    activixCollection?: string;
+    pipelines?: OptimixerPipelinesConfig;
+    warmupLimit?: number;
+};
+//# sourceMappingURL=optimixer-types.d.ts.map

package/dist/contracts/optimixer-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimixer-types.d.ts","sourceRoot":"","sources":["../../src/contracts/optimixer-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAErE,eAAO,MAAM,4BAA4B,EAAE,mBAAwC,CAAC;AAEpF,eAAO,MAAM,kCAAkC,UAAU,CAAC;AAE1D,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,mBAAmB,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,uBAAuB,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,4BAA4B,CAAC;IAChD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,YAAY,GAAG,MAAM,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,uBAAuB,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,sBAAsB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,WAAW,CAAC,EAAE,uBAAuB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;IACjD,UAAU,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,aAAa,CAAC,EAAE,OAAO,yBAAyB,EAAE,qBAAqB,CAAC;IACxE,OAAO,CAAC,EAAE,gCAAgC,CAAC;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/dist/contracts/optimixer-types.js

@@ -0,0 +1,3 @@
+export const AI_MAX_TOKENS_V1_PIPELINE_ID = 'ai.max_tokens.v1';
+export const AI_MAX_TOKENS_V1_ALGORITHM_VERSION = '1.0.0';
+//# sourceMappingURL=optimixer-types.js.map

package/dist/contracts/optimixer-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimixer-types.js","sourceRoot":"","sources":["../../src/contracts/optimixer-types.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,4BAA4B,GAAwB,kBAAkB,CAAC;AAEpF,MAAM,CAAC,MAAM,kCAAkC,GAAG,OAAO,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Optimixer } from './Optimixer.js';
+export type { AiMaxTokensActualUsage, AiMaxTokensCompleteInput, AiMaxTokensPredictionInput, AiMaxTokensPredictionResult, OptimixerAcceptableRisk, OptimixerCreateOptions, OptimixerPipelineConfig, OptimixerPipelineId, OptimixerPipelinesConfig, OptimixerPredictionRecord, OptimixerStandaloneActivixConfig, } from './contracts/optimixer-types.js';
+export { AI_MAX_TOKENS_V1_ALGORITHM_VERSION, AI_MAX_TOKENS_V1_PIPELINE_ID, } from './contracts/optimixer-types.js';
+export { BucketStore, buildBucketKey } from './state/bucket-store.js';
+export { QuantileStats, riskToPercentile } from './state/quantile-stats.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,YAAY,EACV,sBAAsB,EACtB,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,gCAAgC,GACjC,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,kCAAkC,EAClC,4BAA4B,GAC7B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Optimixer } from './Optimixer.js';
+export { AI_MAX_TOKENS_V1_ALGORITHM_VERSION, AI_MAX_TOKENS_V1_PIPELINE_ID, } from './contracts/optimixer-types.js';
+export { BucketStore, buildBucketKey } from './state/bucket-store.js';
+export { QuantileStats, riskToPercentile } from './state/quantile-stats.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAgB3C,OAAO,EACL,kCAAkC,EAClC,4BAA4B,GAC7B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/persistence/activix-writer.d.ts

@@ -0,0 +1,26 @@
+import type { ActivixActivityClient, ActivixActivityRecord, ActivixRunContext } from '@x12i/activix-contracts';
+export type ActivixWriterOptions = {
+    collection?: string;
+    pipelineId: string;
+    algorithmVersion: string;
+};
+export declare class ActivixOptimixerWriter {
+    private readonly client;
+    private readonly options;
+    constructor(client: ActivixActivityClient, options: ActivixWriterOptions);
+    startPredictionRecord(input: {
+        runContext?: ActivixRunContext;
+        outerInput: unknown;
+        outerOutput: unknown;
+        outerMetadata?: Record<string, unknown>;
+    }): Promise<string>;
+    completePredictionRecord(activityId: string, updates: Partial<ActivixActivityRecord>): Promise<void>;
+    patchPredictionRecord(activityId: string, fields: Partial<ActivixActivityRecord>): Promise<void>;
+}
+export declare function warmupBucketStoreFromActivix(client: ActivixActivityClient, opts: {
+    collection?: string;
+    pipelineId: string;
+    limit: number;
+    onObservation: (actionTypeId: string, provider: string | undefined, model: string | undefined, completionTokens: number) => void;
+}): Promise<number>;
+//# sourceMappingURL=activix-writer.d.ts.map

package/dist/persistence/activix-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activix-writer.d.ts","sourceRoot":"","sources":["../../src/persistence/activix-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AAMjC,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,qBAAa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,oBAAoB;IAG1C,qBAAqB,CAAC,KAAK,EAAE;QACjC,UAAU,CAAC,EAAE,iBAAiB,CAAC;QAC/B,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,OAAO,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACzC,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBb,wBAAwB,CAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,CAAC,qBAAqB,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC;IAMV,qBAAqB,CACzB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO,CAAC,qBAAqB,CAAC,GACrC,OAAO,CAAC,IAAI,CAAC;CAWjB;AAED,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE;IACJ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,gBAAgB,EAAE,MAAM,KAAK,IAAI,CAAC;CAClI,GACA,OAAO,CAAC,MAAM,CAAC,CAqCjB"}

package/dist/persistence/activix-writer.js

@@ -0,0 +1,72 @@
+import { ACTIVIX_METADATA_KIND_OPTIMIXER_PREDICTION, ACTIVIX_METADATA_OPTIMIZER_OPTIMIXER, } from '@x12i/activix-contracts';
+export class ActivixOptimixerWriter {
+    client;
+    options;
+    constructor(client, options) {
+        this.client = client;
+        this.options = options;
+    }
+    async startPredictionRecord(input) {
+        const result = await this.client.startRecord({
+            runContext: input.runContext,
+            outer: {
+                input: input.outerInput,
+                output: input.outerOutput,
+                metadata: {
+                    kind: ACTIVIX_METADATA_KIND_OPTIMIXER_PREDICTION,
+                    optimizer: ACTIVIX_METADATA_OPTIMIZER_OPTIMIXER,
+                    pipelineId: this.options.pipelineId,
+                    algorithmVersion: this.options.algorithmVersion,
+                    ...(input.outerMetadata ?? {}),
+                },
+            },
+        }, { collection: this.options.collection });
+        return result.activityId;
+    }
+    async completePredictionRecord(activityId, updates) {
+        await this.client.completeRecord(activityId, updates, {
+            collection: this.options.collection,
+        });
+    }
+    async patchPredictionRecord(activityId, fields) {
+        if (this.client.patchRecord) {
+            await this.client.patchRecord(activityId, fields, {
+                collection: this.options.collection,
+            });
+            return;
+        }
+        await this.client.completeRecord(activityId, fields, {
+            collection: this.options.collection,
+        });
+    }
+}
+export async function warmupBucketStoreFromActivix(client, opts) {
+    if (!client.findRecords) {
+        return 0;
+    }
+    const rows = await client.findRecords({
+        'outer.metadata.pipelineId': opts.pipelineId,
+        'outer.metadata.optimizer': ACTIVIX_METADATA_OPTIMIZER_OPTIMIXER,
+        status: 'completed',
+    }, {
+        collection: opts.collection,
+        limit: opts.limit,
+        sort: { startTime: -1 },
+    });
+    let loaded = 0;
+    for (const row of rows) {
+        const outer = row.outer;
+        const input = outer?.input;
+        const output = outer?.output;
+        const actual = (output?.actual ?? output);
+        const completionTokens = actual?.completionTokens ?? actual?.completion_tokens;
+        const actionTypeId = input?.actionTypeId;
+        if (typeof actionTypeId !== 'string' || typeof completionTokens !== 'number' || !input) {
+            continue;
+        }
+        opts.onObservation(actionTypeId, typeof input.provider === 'string' ? input.provider : undefined, typeof input.model === 'string' ? input.model : undefined, completionTokens);
+        loaded += 1;
+    }
+    return loaded;
+}
+//# sourceMappingURL=activix-writer.js.map

package/dist/persistence/activix-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activix-writer.js","sourceRoot":"","sources":["../../src/persistence/activix-writer.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,0CAA0C,EAC1C,oCAAoC,GACrC,MAAM,yBAAyB,CAAC;AAQjC,MAAM,OAAO,sBAAsB;IAEd;IACA;IAFnB,YACmB,MAA6B,EAC7B,OAA6B;QAD7B,WAAM,GAAN,MAAM,CAAuB;QAC7B,YAAO,GAAP,OAAO,CAAsB;IAC7C,CAAC;IAEJ,KAAK,CAAC,qBAAqB,CAAC,KAK3B;QACC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAC1C;YACE,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,KAAK,EAAE;gBACL,KAAK,EAAE,KAAK,CAAC,UAAU;gBACvB,MAAM,EAAE,KAAK,CAAC,WAAW;gBACzB,QAAQ,EAAE;oBACR,IAAI,EAAE,0CAA0C;oBAChD,SAAS,EAAE,oCAAoC;oBAC/C,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU;oBACnC,gBAAgB,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB;oBAC/C,GAAG,CAAC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC;iBAC/B;aACF;SACF,EACD,EAAE,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CACxC,CAAC;QACF,OAAO,MAAM,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,wBAAwB,CAC5B,UAAkB,EAClB,OAAuC;QAEvC,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,OAAO,EAAE;YACpD,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU;SACpC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,qBAAqB,CACzB,UAAkB,EAClB,MAAsC;QAEtC,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE;gBAChD,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU;aACpC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE;YACnD,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU;SACpC,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,MAA6B,EAC7B,IAKC;IAED,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,WAAW,CACnC;QACE,2BAA2B,EAAE,IAAI,CAAC,UAAU;QAC5C,0BAA0B,EAAE,oCAAoC;QAChE,MAAM,EAAE,WAAW;KACpB,EACD;QACE,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE;KACxB,CACF,CAAC;IAEF,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACxB,MAAM,KAAK,GAAG,KAAK,EAAE,KAA4C,CAAC;QAClE,MAAM,MAAM,GAAG,KAAK,EAAE,MAA6C,CAAC;QACpE,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,MAAM,CAAwC,CAAC;QACjF,MAAM,gBAAgB,GAAG,MAAM,EAAE,gBAAgB,IAAI,MAAM,EAAE,iBAAiB,CAAC;QAC/E,MAAM,YAAY,GAAG,KAAK,EAAE,YAAY,CAAC;QACzC,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,OAAO,gBAAgB,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;YACvF,SAAS;QACX,CAAC;QACD,IAAI,CAAC,aAAa,CAChB,YAAY,EACZ,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,EAC/D,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EACzD,gBAAgB,CACjB,CAAC;QACF,MAAM,IAAI,CAAC,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/pipelines/ai-max-tokens-v1.d.ts

@@ -0,0 +1,18 @@
+import type { ActivixActivityClient } from '@x12i/activix-contracts';
+import type { AiMaxTokensActualUsage, AiMaxTokensPredictionInput, AiMaxTokensPredictionResult, OptimixerAcceptableRisk, OptimixerPipelineConfig } from '../contracts/optimixer-types.js';
+import { ActivixOptimixerWriter } from '../persistence/activix-writer.js';
+import { type BucketStore } from '../state/bucket-store.js';
+export declare function predictAiMaxTokensV1(input: AiMaxTokensPredictionInput, bucketStore: BucketStore, config?: OptimixerPipelineConfig): Omit<AiMaxTokensPredictionResult, 'requestId'>;
+export declare function recordAiMaxTokensPrediction(writer: ActivixOptimixerWriter, input: AiMaxTokensPredictionInput, prediction: Omit<AiMaxTokensPredictionResult, 'requestId'>): Promise<AiMaxTokensPredictionResult>;
+export declare function completeAiMaxTokensPredictionV1(client: ActivixActivityClient, writer: ActivixOptimixerWriter, bucketStore: BucketStore, input: {
+    requestId: string;
+    actual: AiMaxTokensActualUsage;
+    collection?: string;
+    acceptableRisk?: OptimixerAcceptableRisk;
+}): Promise<{
+    learning: {
+        bucketKey: string;
+        observedCompletionTokens: number;
+    };
+}>;
+//# sourceMappingURL=ai-max-tokens-v1.d.ts.map

package/dist/pipelines/ai-max-tokens-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-max-tokens-v1.d.ts","sourceRoot":"","sources":["../../src/pipelines/ai-max-tokens-v1.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,KAAK,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,iCAAiC,CAAC;AAKzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAO5E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,0BAA0B,EACjC,WAAW,EAAE,WAAW,EACxB,MAAM,CAAC,EAAE,uBAAuB,GAC/B,IAAI,CAAC,2BAA2B,EAAE,WAAW,CAAC,CAuChD;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,0BAA0B,EACjC,UAAU,EAAE,IAAI,CAAC,2BAA2B,EAAE,WAAW,CAAC,GACzD,OAAO,CAAC,2BAA2B,CAAC,CAgBtC;AAED,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,sBAAsB,EAC9B,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE;IACL,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,wBAAwB,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CA4ChF"}

package/dist/pipelines/ai-max-tokens-v1.js

@@ -0,0 +1,96 @@
+import { normalizeToActivixCostShape } from '@x12i/activix-contracts';
+import { AI_MAX_TOKENS_V1_ALGORITHM_VERSION, AI_MAX_TOKENS_V1_PIPELINE_ID, } from '../contracts/optimixer-types.js';
+import { buildBucketKey } from '../state/bucket-store.js';
+import { riskToPercentile } from '../state/quantile-stats.js';
+const DEFAULT_MAX_TOKENS = 4096;
+const MIN_MAX_TOKENS = 64;
+const HEADROOM_RATIO = 1.15;
+export function predictAiMaxTokensV1(input, bucketStore, config) {
+    const bucketKey = buildBucketKey({
+        actionTypeId: input.actionTypeId,
+        provider: input.provider,
+        model: input.model,
+    });
+    const stats = bucketStore.statsFor(bucketKey);
+    const defaultMax = config?.defaultMaxTokens ?? DEFAULT_MAX_TOKENS;
+    if (!stats || stats.count === 0) {
+        const baseline = Math.max(MIN_MAX_TOKENS, Math.ceil((input.inputSize + input.contextSize) * 0.25) + 256);
+        return {
+            pipelineId: AI_MAX_TOKENS_V1_PIPELINE_ID,
+            algorithmVersion: AI_MAX_TOKENS_V1_ALGORITHM_VERSION,
+            recommendedMaxTokens: Math.min(defaultMax, baseline),
+            confidence: 'cold-start',
+            bucketKey,
+            riskLevel: input.acceptableRisk,
+        };
+    }
+    const percentile = riskToPercentile(input.acceptableRisk);
+    const observed = stats.percentile(percentile) ?? stats.max() ?? defaultMax;
+    const recommended = Math.max(MIN_MAX_TOKENS, Math.ceil(observed * HEADROOM_RATIO));
+    return {
+        pipelineId: AI_MAX_TOKENS_V1_PIPELINE_ID,
+        algorithmVersion: AI_MAX_TOKENS_V1_ALGORITHM_VERSION,
+        recommendedMaxTokens: Math.min(defaultMax, recommended),
+        confidence: 'warm',
+        bucketKey,
+        riskLevel: input.acceptableRisk,
+    };
+}
+export async function recordAiMaxTokensPrediction(writer, input, prediction) {
+    const requestId = await writer.startPredictionRecord({
+        runContext: input.runContext,
+        outerInput: input,
+        outerOutput: {
+            recommendedMaxTokens: prediction.recommendedMaxTokens,
+            confidence: prediction.confidence,
+            bucketKey: prediction.bucketKey,
+            riskLevel: prediction.riskLevel,
+        },
+        outerMetadata: {
+            actionTypeId: input.actionTypeId,
+        },
+    });
+    return { ...prediction, requestId };
+}
+export async function completeAiMaxTokensPredictionV1(client, writer, bucketStore, input) {
+    const existing = await client.getRecord(input.requestId, {
+        collection: input.collection,
+    });
+    const outerInput = (existing?.outer?.input ?? {});
+    const actionTypeId = typeof outerInput.actionTypeId === 'string' ? outerInput.actionTypeId : 'unknown';
+    const bucketKey = buildBucketKey({
+        actionTypeId,
+        provider: typeof outerInput.provider === 'string' ? outerInput.provider : undefined,
+        model: typeof outerInput.model === 'string' ? outerInput.model : undefined,
+    });
+    bucketStore.observe(bucketKey, input.actual.completionTokens);
+    const cost = normalizeToActivixCostShape({
+        prompt_tokens: input.actual.promptTokens,
+        completion_tokens: input.actual.completionTokens,
+        total_tokens: input.actual.totalTokens,
+        provider: outerInput.provider,
+        model: outerInput.model,
+    });
+    await writer.completePredictionRecord(input.requestId, {
+        outer: {
+            input: existing?.outer?.input ?? outerInput,
+            output: {
+                ...existing?.outer?.output,
+                actual: input.actual,
+                learning: {
+                    bucketKey,
+                    observedCompletionTokens: input.actual.completionTokens,
+                },
+            },
+            metadata: existing?.outer?.metadata ?? {},
+            ...(cost ? { cost } : {}),
+        },
+    });
+    return {
+        learning: {
+            bucketKey,
+            observedCompletionTokens: input.actual.completionTokens,
+        },
+    };
+}
+//# sourceMappingURL=ai-max-tokens-v1.js.map

package/dist/pipelines/ai-max-tokens-v1.js.map

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

package/dist/state/bucket-store.d.ts

@@ -0,0 +1,14 @@
+import { QuantileStats } from './quantile-stats.js';
+export type BucketKeyParts = {
+    actionTypeId: string;
+    provider?: string;
+    model?: string;
+};
+export declare function buildBucketKey(parts: BucketKeyParts): string;
+export declare class BucketStore {
+    private readonly buckets;
+    getOrCreate(key: string): QuantileStats;
+    observe(key: string, completionTokens: number): void;
+    statsFor(key: string): QuantileStats | undefined;
+}
+//# sourceMappingURL=bucket-store.d.ts.map

package/dist/state/bucket-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-store.d.ts","sourceRoot":"","sources":["../../src/state/bucket-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAI5D;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IASvC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAIpD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;CAGjD"}