@dbx-tools/appkit-mastra 0.9.190 → 0.9.193

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/plugin.ts CHANGED
@@ -86,6 +86,7 @@ import {
86
86
  type StatementData,
87
87
  type FeedbackDestination,
88
88
  MastraFeedbackRequestSchema,
89
+ MastraSuggestionGenerationRequestSchema,
89
90
  type MlflowFeedbackRequest,
90
91
  type GenieFeedbackRequest,
91
92
  MASTRA_ROUTES,
@@ -93,7 +94,11 @@ import {
93
94
  GenieChatRequestSchema,
94
95
  GenieVisualizationModeSchema,
95
96
  } from "@dbx-tools/shared-mastra";
96
- import { type ServingEndpointSummary, toModelDisplayName } from "@dbx-tools/shared-model";
97
+ import {
98
+ type ModelSource,
99
+ type ServingEndpointSummary,
100
+ toModelDisplayName,
101
+ } from "@dbx-tools/shared-model";
97
102
  import { workflowRoute } from "@mastra/ai-sdk";
98
103
  import type { Agent } from "@mastra/core/agent";
99
104
  import { Mastra } from "@mastra/core/mastra";
@@ -126,7 +131,7 @@ import {
126
131
  statementDataDefaults,
127
132
  } from "./defaults.ts";
128
133
  import { resolveFeedbackModes } from "./feedback-mode.ts";
129
- import { resolveFollowUpSuggestionsConfig } from "./follow-up-suggestions.ts";
134
+ import { resolveFollowUpSuggestionsConfig, suggestQuestions } from "./follow-up-suggestions.ts";
130
135
  import {
131
136
  deleteGenieThread,
132
137
  deleteGenieThreadMessage,
@@ -147,7 +152,7 @@ import {
147
152
  mlflowExperimentViewerUrl,
148
153
  mlflowUcTracePrefix,
149
154
  } from "./mlflow.ts";
150
- import { resolveDefaultModelId, withSmartRouterEndpoint } from "./model.ts";
155
+ import { resolveDefaultModelId, withModelRouterEndpoints } from "./model.ts";
151
156
  import { buildObservability, configureOtelPropagation } from "./observability.ts";
152
157
  import { provisionRemoteSkills } from "./remote-skills.ts";
153
158
  import {
@@ -569,12 +574,34 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
569
574
  method: "get",
570
575
  path: MASTRA_ROUTES.models,
571
576
  handler: async (req, res) => {
577
+ const requestedSource = firstNonEmpty(req.query.modelSource);
578
+ if (
579
+ requestedSource !== null &&
580
+ requestedSource !== "all" &&
581
+ requestedSource !== "foundation" &&
582
+ requestedSource !== "custom"
583
+ ) {
584
+ res.status(400).json({ error: "modelSource must be foundation, custom, or all" });
585
+ return;
586
+ }
572
587
  const result = await this.scopedSelf(req).listModelsResult();
573
588
  if (!result.ok) {
574
589
  this.sendFailure(res, result, "models", MODEL_CATALOGUE_FAILED_MESSAGE);
575
590
  return;
576
591
  }
577
- res.json({ endpoints: result.data });
592
+ const source: ModelSource | undefined =
593
+ requestedSource === "all" ? undefined : (requestedSource ?? "foundation");
594
+ const endpoints = source
595
+ ? result.data.filter((endpoint) => endpoint.modelSource === source)
596
+ : result.data;
597
+ const search = firstNonEmpty(req.query.search);
598
+ const ranked = search
599
+ ? modelCatalog
600
+ .searchServingEndpoints(search, endpoints, source ? { modelSource: source } : {})
601
+ .map((match) => match.endpoint)
602
+ : endpoints;
603
+ const limit = parseModelLimit(req.query.limit);
604
+ res.json({ endpoints: limit === undefined ? ranked : ranked.slice(0, limit) });
578
605
  },
579
606
  });
580
607
 
@@ -791,6 +818,29 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
791
818
  path: `${MASTRA_ROUTES.suggestions}/:agentId`,
792
819
  handler: handleSuggestions,
793
820
  });
821
+ this.route(router, {
822
+ name: "suggestionGeneration",
823
+ method: "post",
824
+ path: MASTRA_ROUTES.suggestionGeneration,
825
+ handler: async (req, res) => {
826
+ const parsed = MastraSuggestionGenerationRequestSchema.safeParse(req.body);
827
+ if (!parsed.success) {
828
+ this.logger.warn("suggestions:generate-invalid", { error: parsed.error });
829
+ res.status(400).json({
830
+ error: "Suggestion context or options are invalid",
831
+ fields: invalidFields(parsed.error),
832
+ });
833
+ return;
834
+ }
835
+ const controller = new AbortController();
836
+ res.on("close", () => controller.abort());
837
+ const questions = await this.scopedSelf(req).generateSuggestions(
838
+ parsed.data,
839
+ controller.signal,
840
+ );
841
+ if (!controller.signal.aborted) res.json({ questions });
842
+ },
843
+ });
794
844
  }
795
845
 
796
846
  /**
@@ -1272,6 +1322,22 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1272
1322
  }, genieSuggestionDefaults);
1273
1323
  }
1274
1324
 
1325
+ /** Generate bounded next questions through the shared ChatFast suggestion service. */
1326
+ private async generateSuggestions(
1327
+ request: ReturnType<typeof MastraSuggestionGenerationRequestSchema.parse>,
1328
+ signal?: AbortSignal,
1329
+ ): Promise<string[]> {
1330
+ const requestContext = await createRequestContext();
1331
+ return suggestQuestions(this.config, request.context, {
1332
+ maxSuggestions: request.maxSuggestions,
1333
+ maxTokens: request.maxTokens,
1334
+ existingSuggestions: request.existingSuggestions,
1335
+ ...(request.instructions ? { instructions: request.instructions } : {}),
1336
+ requestContext,
1337
+ ...(signal ? { abortSignal: signal } : {}),
1338
+ });
1339
+ }
1340
+
1275
1341
  /**
1276
1342
  * Implementation backing the `/route/feedback` route. Runs inside the
1277
1343
  * AppKit request context. The workspace client writes the assessment and
@@ -1449,7 +1515,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1449
1515
  ttlMs: serving.ttlMs,
1450
1516
  cacheIdentity,
1451
1517
  });
1452
- return withSmartRouterEndpoint(endpoints, client);
1518
+ return withModelRouterEndpoints(endpoints, client);
1453
1519
  }, modelCatalogueDefaults);
1454
1520
  }
1455
1521
 
@@ -1643,6 +1709,15 @@ function parseStatementLimit(raw: unknown): number | undefined {
1643
1709
  return Math.floor(n);
1644
1710
  }
1645
1711
 
1712
+ /** Parse the optional positive `?limit=<n>` used by the model catalogue route. */
1713
+ function parseModelLimit(raw: unknown): number | undefined {
1714
+ const value = Array.isArray(raw) ? raw[0] : raw;
1715
+ if (typeof value !== "string") return undefined;
1716
+ const parsed = toNumber(value);
1717
+ if (parsed === undefined || parsed <= 0) return undefined;
1718
+ return Math.floor(parsed);
1719
+ }
1720
+
1646
1721
  /**
1647
1722
  * Register the Mastra plugin on an AppKit app. Mounts the agents, the
1648
1723
  * `/route/*` chat surface, and (unless disabled) the MCP transport under
package/src/server.ts CHANGED
@@ -52,7 +52,9 @@ import {
52
52
  import { initializeRequestMlflowTraceInfo } from "./mlflow.ts";
53
53
  import { MASTRA_ORIGIN_KEY } from "./request-context.ts";
54
54
  import {
55
+ extractAiDecideStrategy,
55
56
  extractModelOverride,
57
+ MASTRA_AI_DECIDE_STRATEGY_KEY,
56
58
  MASTRA_MODEL_OVERRIDE_KEY,
57
59
  MASTRA_RESOLVED_MODEL_KEY,
58
60
  MASTRA_SMART_ROUTER_INPUT_KEY,
@@ -432,6 +434,12 @@ export class MastraServer extends ExpressMastraServer {
432
434
  });
433
435
  if (override) requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
434
436
  }
437
+ const aiDecideStrategy = extractAiDecideStrategy({
438
+ headers: req.headers as Record<string, string | string[] | undefined>,
439
+ });
440
+ if (aiDecideStrategy) {
441
+ requestContext.set(MASTRA_AI_DECIDE_STRATEGY_KEY, aiDecideStrategy);
442
+ }
435
443
  }
436
444
 
437
445
  /** Preserve the parsed request body for task-aware Smart Router selection. */
package/src/serving.ts CHANGED
@@ -18,6 +18,12 @@ import {
18
18
  MODEL_OVERRIDE_QUERY,
19
19
  MODEL_OVERRIDE_BODY_FIELDS,
20
20
  } from "@dbx-tools/shared-mastra";
21
+ import type {
22
+ AiDecideObservation,
23
+ AiDecideStrategy,
24
+ SmartRouterObservation,
25
+ } from "@dbx-tools/shared-model-gateway";
26
+ import { AI_DECIDE_STRATEGY_HEADER, AiDecideStrategySchema } from "@dbx-tools/shared-model-gateway";
21
27
 
22
28
  import type { MastraPluginConfig } from "./config.ts";
23
29
 
@@ -28,12 +34,30 @@ import type { MastraPluginConfig } from "./config.ts";
28
34
  */
29
35
  export const MASTRA_MODEL_OVERRIDE_KEY = "mastra__model_override";
30
36
 
37
+ /** RequestContext key carrying the caller-selected ai_decide optimization objective. */
38
+ export const MASTRA_AI_DECIDE_STRATEGY_KEY = "mastra__ai_decide_strategy";
39
+
31
40
  /** RequestContext key carrying the endpoint selected for the active agent step. */
32
41
  export const MASTRA_RESOLVED_MODEL_KEY = "mastra__resolved_model";
33
42
 
34
43
  /** RequestContext key carrying the raw request body used to build Smart Router context. */
35
44
  export const MASTRA_SMART_ROUTER_INPUT_KEY = "mastra__smart_router_input";
36
45
 
46
+ /** RequestContext key carrying model selection metadata for caller-facing usage events. */
47
+ export const MASTRA_MODEL_ROUTE_KEY = "mastra__model_route";
48
+
49
+ /** In-process model selection metadata retained until the Mastra turn finishes. */
50
+ export interface MastraModelRoute {
51
+ /** Concrete serving endpoint selected for the turn. */
52
+ model: string;
53
+ /** Policy branch that selected the concrete endpoint. */
54
+ selection: "smart-router" | "ai-decide" | "explicit" | "fuzzy-match" | "class" | "fallback";
55
+ /** Full Smart Router decision when the virtual model selected the endpoint. */
56
+ smartRouter?: SmartRouterObservation;
57
+ /** Full ai_decide decision when that virtual model selected the endpoint. */
58
+ aiDecide?: AiDecideObservation;
59
+ }
60
+
37
61
  /**
38
62
  * Minimal Express-ish request shape used by {@link extractModelOverride}.
39
63
  * Keeps this module independent of `express` so the helper can be
@@ -81,6 +105,17 @@ export function extractModelOverride(req: ModelOverrideRequest): string | null {
81
105
  return null;
82
106
  }
83
107
 
108
+ /** Read and validate the optional ai_decide optimization objective from a request. */
109
+ export function extractAiDecideStrategy(req: ModelOverrideRequest): AiDecideStrategy | undefined {
110
+ const value = firstNonEmpty(
111
+ req.headers?.[AI_DECIDE_STRATEGY_HEADER] ??
112
+ req.headers?.[AI_DECIDE_STRATEGY_HEADER.toLowerCase()],
113
+ );
114
+ if (!value) return undefined;
115
+ const parsed = AiDecideStrategySchema.safeParse(value.toLowerCase());
116
+ return parsed.success ? parsed.data : undefined;
117
+ }
118
+
84
119
  /**
85
120
  * Read the fuzzy-resolution config knobs off the plugin config with
86
121
  * `@dbx-tools/model` defaults applied. Kept here so `buildModel` and