@rlynjb/aptkit-core 0.1.0

package/node_modules/@aptkit/agent-query/fixtures/promoted/revenue-by-state-query-fixture-promoted-2026-06-18-19-29-11.json

@@ -0,0 +1,138 @@
+{
+  "id": "revenue-by-state-query-fixture-promoted",
+  "description": "Promoted deterministic query fixture from fixture replay artifact. Source fixture: revenue-by-state-query. Replay created at: 2026-06-18T19:29:11.225Z.",
+  "question": "What was revenue by state in the last 30 days?",
+  "intent": "monitoring",
+  "workspace": {
+    "projectId": "olist",
+    "projectName": "Olist Brazilian ecommerce fixture",
+    "events": [
+      {
+        "name": "purchase",
+        "properties": [
+          "state",
+          "category",
+          "total_price"
+        ],
+        "eventCount": 50000
+      },
+      {
+        "name": "session_start",
+        "properties": [
+          "utm_source"
+        ],
+        "eventCount": 80000
+      },
+      {
+        "name": "checkout",
+        "properties": [
+          "state"
+        ],
+        "eventCount": 35000
+      },
+      {
+        "name": "view_item",
+        "properties": [
+          "category"
+        ],
+        "eventCount": 120000
+      }
+    ],
+    "customerProperties": [
+      "state",
+      "city"
+    ],
+    "catalogs": [],
+    "totalCustomers": 125000,
+    "totalEvents": 285000,
+    "oldestTimestamp": 1764547200000,
+    "dataHorizon": {
+      "from": "2025-12-01",
+      "to": "2026-06-01",
+      "durationDays": 182
+    }
+  },
+  "tools": [
+    {
+      "name": "get_metric_timeseries",
+      "description": "Return metric timeseries for an optional dimension.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "metric": {
+            "type": "string"
+          },
+          "dimension": {
+            "type": "string"
+          },
+          "time_range": {
+            "type": "object"
+          },
+          "granularity": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "metric",
+          "time_range"
+        ]
+      },
+      "result": {
+        "points": [
+          {
+            "ts": "2026-05-04",
+            "segment": "SP",
+            "value": 28550000
+          },
+          {
+            "ts": "2026-05-04",
+            "segment": "RJ",
+            "value": 12100000
+          },
+          {
+            "ts": "2026-05-04",
+            "segment": "MG",
+            "value": 9800000
+          }
+        ],
+        "totalCount": 4200,
+        "unit": "brl_cents"
+      }
+    }
+  ],
+  "modelResponses": [
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "For the last 30 days in the populated fixture window, SP had the most revenue at BRL 285,500, followed by RJ at BRL 121,000 and MG at BRL 98,000. The ranking is SP, RJ, then MG, based on the get_metric_timeseries result for revenue by state from 2026-05-04 to 2026-06-01."
+        }
+      ],
+      "usage": {
+        "inputTokens": 1680,
+        "outputTokens": 165,
+        "estimated": true
+      },
+      "model": "promoted-fixture-replay"
+    }
+  ],
+  "expectations": {
+    "requiredAnswerText": [
+      "BRL 121,000",
+      "BRL 285,500",
+      "BRL 98,000",
+      "MG",
+      "RJ",
+      "SP"
+    ]
+  },
+  "promotion": {
+    "sourceArtifact": "artifacts/replays/2026-06-18T19-29-11-225Z-revenue-by-state-query-fixture-studio.json",
+    "sourceProvider": {
+      "id": "fixture",
+      "model": "fixture-model"
+    },
+    "promotedAt": "2026-06-18T19:37:13.692Z",
+    "note": "This fixture captures the final query replay answer deterministically; it does not reconstruct the live provider tool loop."
+  }
+}

package/node_modules/@aptkit/agent-query/fixtures/revenue-by-state-query.json

@@ -0,0 +1,79 @@
+{
+  "id": "revenue-by-state-query",
+  "description": "Answer a free-form revenue-by-state question from deterministic Olist-style timeseries data.",
+  "question": "What was revenue by state in the last 30 days?",
+  "intent": "monitoring",
+  "workspace": {
+    "projectId": "olist",
+    "projectName": "Olist Brazilian ecommerce fixture",
+    "events": [
+      { "name": "purchase", "properties": ["state", "category", "total_price"], "eventCount": 50000 },
+      { "name": "session_start", "properties": ["utm_source"], "eventCount": 80000 },
+      { "name": "checkout", "properties": ["state"], "eventCount": 35000 },
+      { "name": "view_item", "properties": ["category"], "eventCount": 120000 }
+    ],
+    "customerProperties": ["state", "city"],
+    "catalogs": [],
+    "totalCustomers": 125000,
+    "totalEvents": 285000,
+    "oldestTimestamp": 1764547200000,
+    "dataHorizon": { "from": "2025-12-01", "to": "2026-06-01", "durationDays": 182 }
+  },
+  "tools": [
+    {
+      "name": "get_metric_timeseries",
+      "description": "Return metric timeseries for an optional dimension.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "metric": { "type": "string" },
+          "dimension": { "type": "string" },
+          "time_range": { "type": "object" },
+          "granularity": { "type": "string" }
+        },
+        "required": ["metric", "time_range"]
+      },
+      "result": {
+        "points": [
+          { "ts": "2026-05-04", "segment": "SP", "value": 28550000 },
+          { "ts": "2026-05-04", "segment": "RJ", "value": 12100000 },
+          { "ts": "2026-05-04", "segment": "MG", "value": 9800000 }
+        ],
+        "totalCount": 4200,
+        "unit": "brl_cents"
+      }
+    }
+  ],
+  "modelResponses": [
+    {
+      "content": [
+        {
+          "type": "tool_use",
+          "id": "query-tool-1",
+          "name": "get_metric_timeseries",
+          "input": {
+            "metric": "revenue",
+            "dimension": "state",
+            "time_range": { "from": "2026-05-04", "to": "2026-06-01" },
+            "granularity": "week"
+          }
+        }
+      ],
+      "usage": { "inputTokens": 900, "outputTokens": 70 },
+      "model": "fixture-model"
+    },
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "For the last 30 days in the populated fixture window, SP had the most revenue at BRL 285,500, followed by RJ at BRL 121,000 and MG at BRL 98,000. The ranking is SP, RJ, then MG, based on the get_metric_timeseries result for revenue by state from 2026-05-04 to 2026-06-01."
+        }
+      ],
+      "usage": { "inputTokens": 780, "outputTokens": 95 },
+      "model": "fixture-model"
+    }
+  ],
+  "expectations": {
+    "requiredAnswerText": ["SP", "BRL 285,500", "RJ", "BRL 121,000", "MG", "BRL 98,000"]
+  }
+}

package/node_modules/@aptkit/agent-query/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@aptkit/agent-query",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "README.md",
+    "dist/src",
+    "fixtures"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "replay:fixture": "npm run build && node dist/scripts/replay-fixture.js",
+    "replay:promoted": "npm run build && node ../../../scripts/replay-promoted-fixtures.mjs --count answerPresent --empty \"no promoted query fixtures found\""
+  },
+  "dependencies": {
+    "@aptkit/context": "0.0.0",
+    "@aptkit/prompts": "0.0.0",
+    "@aptkit/runtime": "0.0.0",
+    "@aptkit/tools": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  }
+}

package/node_modules/@aptkit/agent-recommendation/README.md

@@ -0,0 +1,109 @@
+# @aptkit/agent-recommendation
+
+Extracted recommendation capability from the Blooming Insights workflow.
+
+The package proposes 1-3 marketer-facing actions from an anomaly and diagnosis. It is provider-neutral: callers inject a `ModelProvider`, `ToolRegistry`, workspace descriptor, optional action taxonomy, and optional trace sink.
+
+## Install In Workspace
+
+```sh
+npm install
+npm run build
+```
+
+## Fixture Replay
+
+Run the default recorded fixture without network or secrets:
+
+```sh
+npm run replay:fixture -w @aptkit/agent-recommendation
+```
+
+The default fixture is `fixtures/sp-revenue-drop.json`, derived from the Blooming Insights `06-recommendation-sp` regression case.
+
+Additional fixtures:
+
+- `fixtures/electronics-spike.json`
+- `fixtures/voucher-dropoff.json`
+
+Run a specific fixture:
+
+```sh
+npm run replay:fixture -w @aptkit/agent-recommendation -- fixtures/electronics-spike.json
+npm run replay:fixture -w @aptkit/agent-recommendation -- fixtures/voucher-dropoff.json
+```
+
+## Basic Usage
+
+```ts
+import { RecommendationAgent } from '@aptkit/agent-recommendation';
+import { InMemoryToolRegistry } from '@aptkit/tools';
+
+const agent = new RecommendationAgent({
+  model,
+  tools,
+  workspace,
+  trace: { emit: console.log },
+});
+
+const recommendations = await agent.propose(anomaly, diagnosis);
+```
+
+## Live Anthropic Usage
+
+The agent does not import Anthropic directly. Use `@aptkit/provider-anthropic` at the app boundary:
+
+```ts
+import { AnthropicModelProvider } from '@aptkit/provider-anthropic';
+import { RecommendationAgent } from '@aptkit/agent-recommendation';
+
+const model = new AnthropicModelProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  model: 'claude-sonnet-4-6',
+});
+
+const agent = new RecommendationAgent({ model, tools, workspace });
+```
+
+Live provider tests should stay opt-in and must not run in CI without explicit credentials.
+
+## Live OpenAI Usage
+
+Use `@aptkit/provider-openai` at the app boundary:
+
+```ts
+import { OpenAIModelProvider } from '@aptkit/provider-openai';
+import { RecommendationAgent } from '@aptkit/agent-recommendation';
+
+const model = new OpenAIModelProvider({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: process.env.OPENAI_MODEL ?? 'gpt-4.1',
+});
+
+const agent = new RecommendationAgent({ model, tools, workspace });
+```
+
+The OpenAI adapter uses Chat Completions function tools because AptKit's current runtime contract is chat/tool-loop shaped. A Responses API adapter can be added later if AptKit needs OpenAI-native response state, richer built-in tools, or streaming event parity.
+
+## Contract
+
+Input:
+
+- `Anomaly`
+- `Diagnosis`
+- `WorkspaceDescriptor`
+- Optional `ActionTaxonomy`
+
+Output:
+
+- `Recommendation[]`
+
+The model is asked to emit recommendations without `id`; this package validates the id-less shape, caps the output at three recommendations, then assigns ids through `idGenerator`.
+
+## What Stayed Out
+
+- Bloomreach OAuth and cookies.
+- Next.js route handlers.
+- UI streaming state.
+- Concrete Bloomreach and Olist adapters.
+- Source-app state files and live provider logs.

package/node_modules/@aptkit/agent-recommendation/dist/src/fixture-provider.d.ts

@@ -0,0 +1,10 @@
+import type { ModelProvider, ModelRequest, ModelResponse } from '@aptkit/runtime';
+export declare class FixtureModelProvider implements ModelProvider {
+    private readonly responses;
+    readonly id = "fixture";
+    readonly defaultModel = "fixture-model";
+    readonly requests: ModelRequest[];
+    private index;
+    constructor(responses: ModelResponse[]);
+    complete(request: ModelRequest): Promise<ModelResponse>;
+}

package/node_modules/@aptkit/agent-recommendation/dist/src/fixture-provider.js

@@ -0,0 +1,18 @@
+export class FixtureModelProvider {
+    responses;
+    id = 'fixture';
+    defaultModel = 'fixture-model';
+    requests = [];
+    index = 0;
+    constructor(responses) {
+        this.responses = responses;
+    }
+    async complete(request) {
+        this.requests.push(request);
+        const response = this.responses[this.index];
+        this.index += 1;
+        if (!response)
+            throw new Error(`fixture model exhausted after ${this.index - 1} responses`);
+        return response;
+    }
+}

package/node_modules/@aptkit/agent-recommendation/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './recommendation-agent.js';
+export * from './types.js';
+export * from './fixture-provider.js';
+export * from './schema-summary.js';

package/node_modules/@aptkit/agent-recommendation/dist/src/index.js

@@ -0,0 +1,4 @@
+export * from './recommendation-agent.js';
+export * from './types.js';
+export * from './fixture-provider.js';
+export * from './schema-summary.js';

package/node_modules/@aptkit/agent-recommendation/dist/src/recommendation-agent.d.ts

@@ -0,0 +1,30 @@
+import { type CapabilityTraceSink, type ModelProvider } from '@aptkit/runtime';
+import { type ToolRegistry } from '@aptkit/tools';
+import { type ActionTaxonomy, type Anomaly, type Diagnosis, type Recommendation, type WorkspaceDescriptor } from './types.js';
+export declare const RECOMMENDATION_CAPABILITY_ID = "recommendation-agent";
+/** Least-privilege tool grant for read-only recommendation generation. */
+export declare const recommendationToolPolicy: {
+    capabilityId: string;
+    allowedTools: readonly ["list_scenarios", "get_scenario", "list_initiatives", "get_initiative_items", "list_recommendations", "get_recommendation", "list_segmentations", "list_email_campaigns", "list_voucher_pools", "get_frequency_policies", "get_metric_timeseries", "get_segments", "get_anomaly_context"];
+};
+export type RecommendationAgentOptions = {
+    model: ModelProvider;
+    tools: ToolRegistry;
+    workspace: WorkspaceDescriptor;
+    actionTaxonomy?: ActionTaxonomy;
+    trace?: CapabilityTraceSink;
+    idGenerator?: () => string;
+    prompt?: string;
+};
+export type RecommendationRunOptions = {
+    signal?: AbortSignal;
+};
+export declare class RecommendationAgent {
+    private readonly options;
+    private readonly taxonomy;
+    private readonly idGenerator;
+    private readonly prompt;
+    constructor(options: RecommendationAgentOptions);
+    /** Produces validated, id-assigned recommendations grounded in an anomaly diagnosis. */
+    propose(anomaly: Anomaly, diagnosis: Diagnosis, runOptions?: RecommendationRunOptions): Promise<Recommendation[]>;
+}

package/node_modules/@aptkit/agent-recommendation/dist/src/recommendation-agent.js

@@ -0,0 +1,85 @@
+import { recommendationPromptPackage, renderPromptTemplate } from '@aptkit/prompts';
+import { buildSynthesisInstruction, runAgentLoop } from '@aptkit/runtime';
+import { filterToolsForPolicy } from '@aptkit/tools';
+import { schemaSummary } from './schema-summary.js';
+import { DEFAULT_ACTION_TAXONOMY, } from './types.js';
+import { tryParseRecommendations } from './validate.js';
+export const RECOMMENDATION_CAPABILITY_ID = 'recommendation-agent';
+/** Least-privilege tool grant for read-only recommendation generation. */
+export const recommendationToolPolicy = {
+    capabilityId: RECOMMENDATION_CAPABILITY_ID,
+    allowedTools: [
+        'list_scenarios',
+        'get_scenario',
+        'list_initiatives',
+        'get_initiative_items',
+        'list_recommendations',
+        'get_recommendation',
+        'list_segmentations',
+        'list_email_campaigns',
+        'list_voucher_pools',
+        'get_frequency_policies',
+        'get_metric_timeseries',
+        'get_segments',
+        'get_anomaly_context',
+    ],
+};
+export class RecommendationAgent {
+    options;
+    taxonomy;
+    idGenerator;
+    prompt;
+    constructor(options) {
+        this.options = options;
+        this.taxonomy = options.actionTaxonomy ?? DEFAULT_ACTION_TAXONOMY;
+        this.idGenerator = options.idGenerator ?? (() => crypto.randomUUID());
+        this.prompt = options.prompt ?? recommendationPromptPackage.system;
+    }
+    /** Produces validated, id-assigned recommendations grounded in an anomaly diagnosis. */
+    async propose(anomaly, diagnosis, runOptions = {}) {
+        const allTools = await this.options.tools.listTools();
+        const toolSchemas = filterToolsForPolicy(allTools, recommendationToolPolicy);
+        const system = renderPromptTemplate(this.prompt, {
+            schema: schemaSummary(this.options.workspace),
+            project_id: this.options.workspace.projectId,
+            diagnosis: JSON.stringify(diagnosis),
+        });
+        const { parsed } = await runAgentLoop({
+            capabilityId: RECOMMENDATION_CAPABILITY_ID,
+            model: this.options.model,
+            tools: this.options.tools,
+            system,
+            userPrompt: 'Propose recommendations for this diagnosis and return the JSON array.',
+            toolSchemas,
+            trace: this.options.trace,
+            signal: runOptions.signal,
+            maxTurns: 6,
+            maxToolCalls: 4,
+            synthesisInstruction: buildSynthesisInstruction('Stop querying now and output your final answer. Respond with ONLY a JSON array of at most 3 recommendation objects in a json fence, or [] if you cannot propose grounded actions, based on the diagnosis and the data you have already gathered. Do NOT include an id field.'),
+            parseResult: (text) => tryParseRecommendations(text, this.taxonomy),
+            recoveryPrompt: (toolCalls) => buildRecoveryPrompt(anomaly, diagnosis, toolCalls),
+        });
+        if (!parsed)
+            return [];
+        return parsed.slice(0, 3).map((recommendation) => ({
+            id: this.idGenerator(),
+            ...recommendation,
+        }));
+    }
+}
+function buildRecoveryPrompt(anomaly, diagnosis, toolCalls) {
+    const evidence = toolCalls
+        .map((call, index) => {
+        const payload = call.error ? { error: call.error } : call.result;
+        return `Query ${index + 1}: ${call.toolName} ${JSON.stringify(call.args).slice(0, 200)}\nResult: ${JSON.stringify(payload).slice(0, 900)}`;
+    })
+        .join('\n\n') || '(no existing-feature queries were completed)';
+    return [
+        `Anomaly that was diagnosed:\n${JSON.stringify(anomaly)}`,
+        `Diagnosis to act on:\n${JSON.stringify(diagnosis)}`,
+        `Existing-feature queries run and their results:\n${evidence}`,
+        'Based on the diagnosis above, output your best 2-3 recommendations as a single JSON array in a json fence.',
+        'Each object must include title, rationale, bloomreachFeature, steps, estimatedImpact, confidence, and any useful setup fields.',
+        'Do NOT include an id field. If you cannot propose grounded actions, return []. Do NOT request more queries.',
+    ].join('\n\n');
+}

package/node_modules/@aptkit/agent-recommendation/dist/src/schema-summary.d.ts

@@ -0,0 +1 @@
+export { schemaSummary } from '@aptkit/context';

package/node_modules/@aptkit/agent-recommendation/dist/src/schema-summary.js

@@ -0,0 +1 @@
+export { schemaSummary } from '@aptkit/context';

package/node_modules/@aptkit/agent-recommendation/dist/src/types.d.ts

@@ -0,0 +1,68 @@
+export type { WorkspaceDescriptor } from '@aptkit/context';
+export type Severity = 'critical' | 'warning' | 'info' | 'positive';
+export type Anomaly = {
+    metric: string;
+    scope: string[];
+    change: {
+        value: number;
+        direction: 'up' | 'down';
+        baseline: string;
+    };
+    severity: Severity;
+    evidence: {
+        tool: string;
+        result: unknown;
+    }[];
+    impact?: string;
+    history?: number[];
+    category?: string;
+};
+export type Diagnosis = {
+    conclusion: string;
+    evidence: string[];
+    hypothesesConsidered: {
+        hypothesis: string;
+        supported: boolean;
+        reasoning: string;
+    }[];
+    affectedCustomers?: {
+        count: number;
+        segmentDescription: string;
+    };
+    confidence?: 'high' | 'medium' | 'low';
+    timeSeries?: {
+        day: string;
+        value: number;
+    }[];
+};
+export type ActionFeature = 'scenario' | 'segment' | 'campaign' | 'voucher' | 'experiment';
+export type EstimatedImpact = string | {
+    range: string;
+    rangeUsd?: {
+        low: number;
+        high: number;
+    };
+    assumption: string;
+};
+export type Recommendation = {
+    id: string;
+    title: string;
+    rationale: string;
+    bloomreachFeature: ActionFeature;
+    steps: string[];
+    estimatedImpact: EstimatedImpact;
+    confidence: 'high' | 'medium' | 'low';
+    effort?: 'low' | 'medium' | 'high';
+    timeToSetUpMinutes?: number;
+    readResultInDays?: number;
+    prerequisites?: {
+        label: string;
+        satisfied: boolean;
+    }[];
+    successMetric?: string;
+};
+export type IdlessRecommendation = Omit<Recommendation, 'id'>;
+export type ActionTaxonomy = {
+    features: readonly ActionFeature[];
+};
+export declare const DEFAULT_ACTION_TAXONOMY: ActionTaxonomy;

package/node_modules/@aptkit/agent-recommendation/dist/src/types.js

@@ -0,0 +1,3 @@
+export const DEFAULT_ACTION_TAXONOMY = {
+    features: ['scenario', 'segment', 'campaign', 'voucher', 'experiment'],
+};

package/node_modules/@aptkit/agent-recommendation/dist/src/validate.d.ts

@@ -0,0 +1,3 @@
+import type { ActionTaxonomy, IdlessRecommendation } from './types.js';
+export declare function isRecommendationArray(value: unknown, taxonomy: ActionTaxonomy): value is IdlessRecommendation[];
+export declare function tryParseRecommendations(text: string, taxonomy: ActionTaxonomy): IdlessRecommendation[] | null;

package/node_modules/@aptkit/agent-recommendation/dist/src/validate.js

@@ -0,0 +1,54 @@
+import { parseAgentJson } from '@aptkit/runtime';
+const CONFIDENCE = ['high', 'medium', 'low'];
+const EFFORT = ['low', 'medium', 'high'];
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isEstimatedImpact(value) {
+    if (typeof value === 'string')
+        return true;
+    return isRecord(value) && typeof value.range === 'string';
+}
+function isPrerequisite(value) {
+    return isRecord(value) && typeof value.label === 'string' && typeof value.satisfied === 'boolean';
+}
+export function isRecommendationArray(value, taxonomy) {
+    return Array.isArray(value) && value.every((item) => {
+        if (!isRecord(item))
+            return false;
+        if (typeof item.title !== 'string')
+            return false;
+        if (typeof item.rationale !== 'string')
+            return false;
+        if (!taxonomy.features.includes(item.bloomreachFeature))
+            return false;
+        if (!Array.isArray(item.steps) || !item.steps.every((step) => typeof step === 'string'))
+            return false;
+        if (!isEstimatedImpact(item.estimatedImpact))
+            return false;
+        if (!CONFIDENCE.includes(String(item.confidence)))
+            return false;
+        if (item.effort !== undefined && !EFFORT.includes(String(item.effort)))
+            return false;
+        if (item.timeToSetUpMinutes !== undefined && typeof item.timeToSetUpMinutes !== 'number')
+            return false;
+        if (item.readResultInDays !== undefined && typeof item.readResultInDays !== 'number')
+            return false;
+        if (item.prerequisites !== undefined &&
+            (!Array.isArray(item.prerequisites) || !item.prerequisites.every(isPrerequisite))) {
+            return false;
+        }
+        if (item.successMetric !== undefined && typeof item.successMetric !== 'string')
+            return false;
+        return true;
+    });
+}
+export function tryParseRecommendations(text, taxonomy) {
+    try {
+        const parsed = parseAgentJson(text);
+        return isRecommendationArray(parsed, taxonomy) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}