/** * RecommendationEngine -- item-based collaborative filtering, workflow * transition analysis, proportional allocation and marginal config comparison, * all computed from the caller's own records. * * WHAT WAS HERE: all eight published operations returned * `{ success: true, data: { result: " completed successfully" } }` * with a hard-coded `confidence: 0.85`, having read none of their input. * * WHAT "TRAINING" MEANS HERE, since the word invites the wrong expectation: * nothing is learned and nothing is stored. The model is the item-item cosine * similarity matrix of the interactions passed in, which is a function of that * data and nothing else -- so every operation recomputes it from * `interactions` rather than reading a hidden copy. `train` exists to return * that matrix and its diagnostics (how sparse, how many items are reachable at * all) because those are what decide whether a recommendation from this data * means anything, and a caller cannot see them from a ranked list. * * WHAT THE SCORES ARE NOT: a score here is a weighted sum of similarities to * things the user already used. It is not a probability, not a rating, and not * comparable between two different interaction sets. `explain-recommendation` * returns the individual terms, and they sum to the score -- so any figure this * tool reports can be taken apart into the caller's own records. * * An operation whose inputs are absent REFUSES, naming the missing key. */ import type { CacheEngine } from '../../core/cache-engine.js'; import type { TokenCounter } from '../../core/token-counter.js'; import type { MetricsCollector } from '../../core/metrics.js'; /** * The operations, in one place: the TS union and the published enum are both * derived from this array, so they cannot drift apart. */ export declare const RECOMMENDATION_ENGINE_OPERATIONS: readonly ["recommend", "train", "find-similar", "personalize", "optimize-workflow", "allocate-resources", "tune-config", "explain-recommendation"]; export type RecommendationEngineOperation = (typeof RECOMMENDATION_ENGINE_OPERATIONS)[number]; /** The one similarity this engine computes, named in what it returns. */ export declare const MODEL_KIND = "item-cosine"; /** * Defaults. Each is a presentation choice reported back in the result, never a * stand-in for a missing input: `minOccurrences` is 2 because a run seen once * is not a pattern, and `topK` only truncates a list that is already ranked. */ export declare const RECOMMENDATION_ENGINE_DEFAULTS: Readonly<{ topK: 10; sequenceLength: 2; minOccurrences: 2; }>; /** One observed use: who used what, and how much it counted. */ export interface Interaction { user: string; item: string; /** Defaults to 1, so a plain usage log needs no weights. */ weight?: number; } /** One claim on a fixed capacity. */ export interface Demand { label: string; demand: number; } /** One measured run of a configuration. */ export interface ConfigTrial { config: Record; score: number; } export interface RecommendationEngineOptions { operation: RecommendationEngineOperation; /** recommend, train, find-similar, personalize, explain-recommendation. */ interactions?: Interaction[]; user?: string; item?: string; candidates?: string[]; topK?: number; /** optimize-workflow. */ events?: string[]; sequenceLength?: number; minOccurrences?: number; /** allocate-resources. */ demands?: Demand[]; capacity?: number; /** tune-config. */ trials?: ConfigTrial[]; useCache?: boolean; } export interface RecommendationEngineResult { success: boolean; operation: string; data: Record; metadata: { tokensUsed: number; tokensSaved: number; cacheHit: boolean; processingTime: number; }; } /** One item-item similarity, as returned and as used to score. */ export interface ItemSimilarity { a: string; b: string; similarity: number; } export declare class RecommendationEngine { private cache; private tokenCounter; private metricsCollector; constructor(cache: CacheEngine, tokenCounter: TokenCounter, metricsCollector: MetricsCollector); run(options: RecommendationEngineOptions): Promise; /** * One branch per published operation. No fall-through: a value added to the * published enum without an implementation here reaches the default and is * refused rather than quietly served by a neighbour. */ private compute; /** * The item-item model and the diagnostics that say whether anything built on * it can mean much: how many of the possible pairs are connected at all, and * how many items no pair reaches. */ private train; /** * Items the user has not used, scored by similarity to the ones they have. * Items already in the profile are excluded -- recommending something back * to the person already using it is the classic way a recommender looks * accurate while saying nothing. */ private recommend; private findSimilar; /** * Rank a list the caller already chose, rather than choosing one. Each * candidate is marked `known` when the user already uses it, because a * ranking that silently mixed the two would be read as all-new. */ private personalize; /** * Transition counts over one ordered event stream, plus the steps whose next * step never varies. * * The deterministic transitions are the actionable part: a step always * followed by the same step can be merged, and that is a statement about the * caller's log rather than a suggestion invented for them. */ private optimizeWorkflow; /** * Proportional allocation of an integer capacity by the largest-remainder * method: floor each share, then hand the leftover units to the largest * fractional parts. * * WHY LARGEST REMAINDER: rounding each share independently does not sum to * the capacity, so the allocation either overspends or leaves units * unassigned without saying so. Here the allocated units equal `capacity` * exactly, and `remainderOrder` shows which claims received a leftover unit * and why, so the arithmetic can be checked by hand. */ private allocateResources; /** * Per-parameter marginal comparison of the caller's own measured trials. * * WHAT THIS IS NOT: a causal estimate or a search. It groups the trials by * each parameter's value and reports the mean score of each group, so a * parameter whose groups differ is worth varying and one whose groups agree * is not. Because the trials were not necessarily varied one factor at a * time, `independent` says whether each parameter's values were observed * against more than one setting of the others -- without that, a difference * here may belong to a different parameter entirely. */ private tuneConfig; /** * The score for one user-item pair, taken apart into the terms that produced * it. `score` equals the sum of `contributions`, so nothing here is a * summary of a number computed somewhere else. */ private explainRecommendation; } export declare const RECOMMENDATIONENGINETOOL: { readonly name: "recommendation-engine"; readonly description: "Item-based collaborative filtering, workflow transition analysis, proportional allocation and config trial comparison over records you supply"; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly operation: { readonly type: "string"; readonly enum: readonly ["recommend", "train", "find-similar", "personalize", "optimize-workflow", "allocate-resources", "tune-config", "explain-recommendation"]; readonly description: "Operation to perform"; }; readonly interactions: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly user: { readonly type: "string"; readonly minLength: 1; }; readonly item: { readonly type: "string"; readonly minLength: 1; }; readonly weight: { readonly type: "number"; readonly exclusiveMinimum: 0; }; }; readonly required: readonly ["user", "item"]; readonly additionalProperties: false; }; readonly minItems: 1; readonly description: "Observed uses: who used what, optionally how much"; }; readonly user: { readonly type: "string"; readonly minLength: 1; readonly description: "Which user to score for"; }; readonly item: { readonly type: "string"; readonly minLength: 1; readonly description: "Which item to compare or explain"; }; readonly candidates: { readonly type: "array"; readonly items: { readonly type: "string"; readonly minLength: 1; }; readonly minItems: 1; readonly description: "The list personalize ranks"; }; readonly topK: { readonly type: "integer"; readonly minimum: 1; readonly default: 10; readonly description: "How many ranked entries to return"; }; readonly events: { readonly type: "array"; readonly items: { readonly type: "string"; readonly minLength: 1; }; readonly minItems: 2; readonly description: "One ordered event stream, for optimize-workflow"; }; readonly sequenceLength: { readonly type: "integer"; readonly minimum: 1; readonly default: 2; readonly description: "Run length to mine for repeats"; }; readonly minOccurrences: { readonly type: "integer"; readonly minimum: 2; readonly default: 2; readonly description: "How often a run must repeat to count as a pattern"; }; readonly demands: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly label: { readonly type: "string"; readonly minLength: 1; }; readonly demand: { readonly type: "number"; readonly minimum: 0; }; }; readonly required: readonly ["label", "demand"]; readonly additionalProperties: false; }; readonly minItems: 1; readonly description: "Claims on the capacity, for allocate-resources"; }; readonly capacity: { readonly type: "integer"; readonly minimum: 0; readonly description: "Whole units available to allocate"; }; readonly trials: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly config: { readonly type: "object"; }; readonly score: { readonly type: "number"; }; }; readonly required: readonly ["config", "score"]; readonly additionalProperties: false; }; readonly minItems: 2; readonly description: "Measured configuration runs, for tune-config"; }; readonly useCache: { readonly type: "boolean"; readonly default: true; readonly description: "Enable caching"; }; }; readonly required: readonly ["operation"]; readonly anyOf: readonly [{ readonly properties: { readonly operation: { readonly const: "train"; }; }; readonly required: readonly ["operation", "interactions"]; }, { readonly properties: { readonly operation: { readonly const: "recommend"; }; }; readonly required: readonly ["operation", "interactions", "user"]; }, { readonly properties: { readonly operation: { readonly const: "find-similar"; }; }; readonly required: readonly ["operation", "interactions", "item"]; }, { readonly properties: { readonly operation: { readonly const: "personalize"; }; }; readonly required: readonly ["operation", "interactions", "user", "candidates"]; }, { readonly properties: { readonly operation: { readonly const: "explain-recommendation"; }; }; readonly required: readonly ["operation", "interactions", "user", "item"]; }, { readonly properties: { readonly operation: { readonly const: "optimize-workflow"; }; }; readonly required: readonly ["operation", "events"]; }, { readonly properties: { readonly operation: { readonly const: "allocate-resources"; }; }; readonly required: readonly ["operation", "demands", "capacity"]; }, { readonly properties: { readonly operation: { readonly const: "tune-config"; }; }; readonly required: readonly ["operation", "trials"]; }]; }; }; export declare function runRecommendationEngine(options: RecommendationEngineOptions): Promise; //# sourceMappingURL=recommendation-engine.d.ts.map