@dbx-tools/appkit-generator 0.0.0-stage → 0.9.138

package/src/schema.ts

@@ -0,0 +1,114 @@
+/**
+ * Model-facing profile contract and AppKit tool description for researched
+ * brand generation. Browser-safe request, event, and package contracts are
+ * owned by `@dbx-tools/shared-generator`.
+ *
+ * @module
+ */
+
+import { stringUtils } from "@dbx-tools/shared-core";
+import type { BrandGenerationRequest as SharedBrandGenerationRequest } from "@dbx-tools/shared-generator/brand";
+import { z } from "zod";
+
+export {
+  BrandGenerationErrorEventSchema,
+  BrandGenerationEventSchema,
+  BrandGenerationProgressEventSchema,
+  BrandGenerationRequestSchema,
+  BrandGenerationResultEventSchema,
+  BrandGenerationStageSchema,
+  BrandPackageSchema,
+  BrandPackageSourceSchema,
+  BrandVisualImageSchema,
+  BrandVisualReferenceSchema,
+} from "@dbx-tools/shared-generator/brand";
+export type {
+  BrandGenerationErrorEvent,
+  BrandGenerationEvent,
+  BrandGenerationProgressEvent,
+  BrandGenerationRequest,
+  BrandGenerationResultEvent,
+  BrandGenerationStage,
+  BrandPackage,
+  BrandPackageSource,
+  BrandVisualImage,
+  BrandVisualReference,
+} from "@dbx-tools/shared-generator/brand";
+
+const nonBlankString = z.string().trim().min(1);
+const color = z.string().regex(/^#(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i, "Expected a hex color.");
+
+/** Resolve the human-readable subject from a validated brand request. */
+export function brandRequestSubject(request: SharedBrandGenerationRequest): string {
+  return request.name ?? request.prompt!;
+}
+
+/** Description shared by the native AppKit brand-generation tool. */
+export const GENERATE_BRAND_TOOL_DESCRIPTION = stringUtils.toDescription(`
+  Research a named organization or product on the web and generate a portable
+  branding package. The result includes a validated BrandContext for
+  application and email presentation plus the sources used. Supply the
+  official website when known to disambiguate brands with similar names.
+`);
+
+/**
+ * Structured model output before deterministic asset references and schema
+ * metadata are attached.
+ */
+export const GeneratedBrandProfileSchema = z
+  .object({
+    name: nonBlankString.describe("Canonical display name supported by the sources."),
+    shortName: nonBlankString.describe("Compact brand name suitable for constrained UI."),
+    tagline: nonBlankString.describe("Short brand line suitable for a header or metadata."),
+    description: nonBlankString.describe("Plain-language description of the brand."),
+    colors: z
+      .object({
+        primary: color.describe("Primary identity color."),
+        primaryHover: color.describe("Accessible hover or pressed color for the primary color."),
+        accent: color.describe("Secondary accent color."),
+        foreground: color.describe("Default high-contrast text and mark color."),
+        background: color.describe("Default page background."),
+        surface: color.describe("Secondary surface background."),
+        muted: color.describe("Muted text color with readable contrast."),
+        border: color.describe("Default border color."),
+      })
+      .strict()
+      .describe("Usable interface palette based on the researched identity."),
+    typography: z
+      .object({
+        sans: nonBlankString.describe("CSS font-family stack for normal interface text."),
+        mono: nonBlankString.describe("CSS font-family stack for code and tabular text."),
+      })
+      .strict()
+      .describe("Brand-compatible CSS font stacks."),
+    voice: z
+      .object({
+        audience: z
+          .array(nonBlankString)
+          .describe("Primary audiences explicitly supported by the sources."),
+        tone: z.array(nonBlankString).describe("Concise descriptors for the brand's writing tone."),
+        principles: z
+          .array(nonBlankString)
+          .describe("Concrete rules for writing in the brand voice."),
+        avoid: z.array(nonBlankString).describe("Writing patterns the brand should avoid."),
+      })
+      .strict()
+      .describe("Evidence-based writing voice guidance."),
+    links: z
+      .object({
+        website: z.string().url().describe("Official brand website."),
+        repository: z.string().url().optional().describe("Official source repository, if any."),
+        documentation: z
+          .string()
+          .url()
+          .optional()
+          .describe("Official documentation site, if distinct from the website."),
+      })
+      .strict()
+      .describe("Verified first-party brand links."),
+  })
+  .strict()
+  .describe("Evidence-based brand profile produced by the synthesis model.");
+
+/** Structured model output before deterministic package assembly. */
+export type GeneratedBrandProfile = z.infer<typeof GeneratedBrandProfileSchema>;

package/src/structured.ts

@@ -0,0 +1,54 @@
+/**
+ * Mastra-backed prompt-injected structured generation.
+ *
+ * @module
+ */
+
+import type { WorkspaceClient } from "@databricks/appkit";
+import { buildModel, RESPONSES_PROVIDER_OPTIONS } from "@dbx-tools/appkit-mastra/model";
+import { Agent } from "@mastra/core/agent";
+import type { MessageListInput } from "@mastra/core/agent/message-list";
+import type { z } from "zod";
+
+/** Options for one isolated structured synthesis pass. */
+export interface StructuredGenerationOptions<TSchema extends z.ZodType> {
+  /** Stable operation identifier. */
+  id: string;
+  /** Trusted system instructions. */
+  instructions: string;
+  /** Data-only prompt. */
+  prompt: MessageListInput;
+  /** Zod-owned output contract. */
+  schema: TSchema;
+  /** Optional model preference. */
+  model?: string;
+  /** Explicit workspace client for standalone callers. */
+  workspaceClient?: WorkspaceClient;
+  /** External cancellation. */
+  signal?: AbortSignal;
+}
+
+/** Generate and validate one structured object without provider response-format APIs. */
+export async function generateStructured<TSchema extends z.ZodType>(
+  options: StructuredGenerationOptions<TSchema>,
+): Promise<z.output<TSchema>> {
+  const model = await buildModel({ modelOverride: false }, undefined, {
+    ...(options.model ? { modelId: options.model } : {}),
+    ...(options.workspaceClient ? { workspaceClient: options.workspaceClient } : {}),
+  });
+  const agent = new Agent({
+    id: options.id,
+    name: options.id,
+    instructions: options.instructions,
+    model,
+  });
+  const result = await agent.generate(options.prompt, {
+    structuredOutput: {
+      schema: options.schema,
+      jsonPromptInjection: "system",
+    },
+    providerOptions: RESPONSES_PROVIDER_OPTIONS,
+    ...(options.signal ? { abortSignal: options.signal } : {}),
+  });
+  return options.schema.parse(result.object);
+}

package/src/workflow.ts

@@ -0,0 +1,221 @@
+/**
+ * Mastra workflow composing reusable generator operations.
+ *
+ * @module
+ */
+
+import { BrandPackageSchema, type BrandGenerationRequest } from "@dbx-tools/shared-generator/brand";
+import { KpiResearchResultSchema } from "@dbx-tools/shared-generator/kpi";
+import {
+  GeneratedAssetsSchema,
+  GeneratedSchemaSchema,
+  GeneratorPlanSchema,
+  GeneratorRequestSchema,
+  MaterializedGeneratorDataSchema,
+} from "@dbx-tools/shared-generator/workflow";
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+import type { GeneratorOperations } from "./operations.ts";
+
+/** Operation surface consumed by the workflow and implemented by GeneratorOperations. */
+export type GeneratorWorkflowOperations = Pick<
+  GeneratorOperations,
+  | "generateBrand"
+  | "researchKpis"
+  | "planData"
+  | "provisionSchema"
+  | "materializeData"
+  | "createDashboard"
+  | "createGenie"
+>;
+
+/** Construction options for workflow hosts and isolated tests. */
+export interface GeneratorWorkflowOptions {
+  /** Suspend before mutations. Defaults to true. */
+  approval?: boolean;
+}
+
+const ResearchOutputSchema = z
+  .object({
+    request: GeneratorRequestSchema,
+    brand: BrandPackageSchema,
+    kpiResearch: KpiResearchResultSchema,
+  })
+  .strict();
+
+const PlanOutputSchema = ResearchOutputSchema.extend({
+  plan: GeneratorPlanSchema,
+}).strict();
+
+const ProvisionOutputSchema = PlanOutputSchema.extend({
+  location: GeneratedSchemaSchema,
+}).strict();
+
+const MaterializeOutputSchema = ProvisionOutputSchema.extend({
+  materialized: MaterializedGeneratorDataSchema,
+}).strict();
+
+/** Build one typed workflow over an isolated generator operation owner. */
+export function createGeneratorWorkflow(
+  operations: GeneratorWorkflowOperations,
+  options: GeneratorWorkflowOptions = {},
+) {
+  const research = createStep({
+    id: "research-brand-and-kpis",
+    inputSchema: GeneratorRequestSchema,
+    outputSchema: ResearchOutputSchema,
+    execute: async ({ inputData, abortSignal, writer }) => {
+      await writer?.write({ type: "generator-progress", stage: "research", status: "started" });
+      const brandRequest: BrandGenerationRequest = {
+        name: inputData.company,
+        ...(inputData.website ? { website: inputData.website } : {}),
+      };
+      const [brand, kpiResearch] = await Promise.all([
+        operations.generateBrand(brandRequest, abortSignal),
+        operations.researchKpis(
+          {
+            company: inputData.company,
+            purpose: inputData.purpose,
+            queries: inputData.queries,
+          },
+          abortSignal,
+        ),
+      ]);
+      return { request: inputData, brand, kpiResearch };
+    },
+  });
+
+  const plan = createStep({
+    id: "plan-demo-data",
+    inputSchema: ResearchOutputSchema,
+    outputSchema: PlanOutputSchema,
+    execute: async ({ inputData, abortSignal, writer }) => {
+      await writer?.write({ type: "generator-progress", stage: "plan", status: "started" });
+      const generatedPlan = await operations.planData(inputData, abortSignal);
+      return { ...inputData, plan: generatedPlan };
+    },
+  });
+
+  const approval = createStep({
+    id: "approve-mutation-plan",
+    inputSchema: PlanOutputSchema,
+    outputSchema: PlanOutputSchema,
+    resumeSchema: z.object({
+      approved: z.boolean().describe("Whether the generated mutation plan is approved."),
+    }),
+    suspendSchema: z.object({
+      reason: z.string().describe("Why approval is required."),
+      plan: GeneratorPlanSchema,
+    }),
+    execute: async ({ inputData, resumeData, suspend }) => {
+      if (options.approval === false) return inputData;
+      if (resumeData === undefined) {
+        return suspend({
+          reason: "Approve schema, data, and presentation creation.",
+          plan: inputData.plan,
+        });
+      }
+      if (!resumeData.approved) {
+        throw new Error("Generator mutation plan was rejected");
+      }
+      return inputData;
+    },
+  });
+
+  const provision = createStep({
+    id: "provision-schema",
+    inputSchema: PlanOutputSchema,
+    outputSchema: ProvisionOutputSchema,
+    execute: async ({ inputData, abortSignal, writer }) => {
+      await writer?.write({ type: "generator-progress", stage: "schema", status: "started" });
+      const location = await operations.provisionSchema(
+        {
+          request: {
+            company: inputData.request.company,
+            purpose: inputData.request.purpose,
+          },
+        },
+        abortSignal,
+      );
+      return { ...inputData, location };
+    },
+  });
+
+  const materialize = createStep({
+    id: "materialize-and-validate-data",
+    inputSchema: ProvisionOutputSchema,
+    outputSchema: MaterializeOutputSchema,
+    execute: async ({ inputData, abortSignal, writer }) => {
+      await writer?.write({ type: "generator-progress", stage: "data", status: "started" });
+      const materialized = await operations.materializeData(
+        {
+          location: inputData.location,
+          plan: inputData.plan,
+        },
+        abortSignal,
+      );
+      return { ...inputData, materialized };
+    },
+  });
+
+  const presentation = createStep({
+    id: "create-presentation",
+    inputSchema: MaterializeOutputSchema,
+    outputSchema: GeneratedAssetsSchema,
+    execute: async ({ inputData, abortSignal, writer }) => {
+      await writer?.write({
+        type: "generator-progress",
+        stage: "presentation",
+        status: "started",
+      });
+      const presentationInput = {
+        request: {
+          company: inputData.request.company,
+          purpose: inputData.request.purpose,
+        },
+        location: inputData.location,
+        plan: inputData.plan,
+        brand: inputData.brand,
+      };
+      if (inputData.request.presentation === "dashboard") {
+        const dashboard = await operations.createDashboard(presentationInput, abortSignal);
+        return GeneratedAssetsSchema.parse({
+          request: inputData.request,
+          schema: inputData.location,
+          tables: inputData.materialized.tables,
+          brand: inputData.brand,
+          kpiResearch: inputData.kpiResearch,
+          plan: inputData.plan,
+          dashboard,
+        });
+      }
+      const genie = await operations.createGenie(presentationInput, abortSignal);
+      return GeneratedAssetsSchema.parse({
+        request: inputData.request,
+        schema: inputData.location,
+        tables: inputData.materialized.tables,
+        brand: inputData.brand,
+        kpiResearch: inputData.kpiResearch,
+        plan: inputData.plan,
+        genie,
+      });
+    },
+  });
+
+  return createWorkflow({
+    id: "generator-demo-assets",
+    inputSchema: GeneratorRequestSchema,
+    outputSchema: GeneratedAssetsSchema,
+    options: { autoRestartActiveRuns: false },
+  })
+    .then(research)
+    .then(plan)
+    .then(approval)
+    .then(provision)
+    .then(materialize)
+    .then(presentation)
+    .commit();
+}
+
+/** Generator workflow type. */
+export type GeneratorWorkflow = ReturnType<typeof createGeneratorWorkflow>;