@dbx-tools/genie 0.1.9

package/README.md

@@ -0,0 +1,162 @@
+# @dbx-tools/node-genie
+
+Server-side Databricks Genie chat drivers.
+
+Import this package when Node or AppKit backend code needs to run one turn
+against a Genie space and consume either raw Genie message snapshots or a typed
+event stream. It preserves AppKit OBO auth when called inside an AppKit request,
+falls back to the Databricks SDK default auth outside AppKit, and supports
+caller-provided cancellation.
+
+Pure Genie schemas and event detector helpers live in
+[`@dbx-tools/shared-genie`](../../shared/genie).
+
+Key features:
+
+- Starts new Genie conversations or continues an existing `conversationId`.
+- Polls Databricks Genie until terminal status while filtering unchanged
+  snapshots.
+- Converts raw Genie messages into semantic events for thinking text, generated
+  SQL, row counts, final results, and errors.
+- Preserves AppKit OBO auth when called during an AppKit request, but also works
+  from standalone scripts with normal Databricks SDK auth.
+- Accepts SDK `Context` or web `AbortSignal` cancellation for route handlers and
+  CLI tools.
+- Fetches Genie space metadata and starter questions for UI suggestions.
+
+## Why Not Just AppKit Genie?
+
+Native AppKit's Genie plugin is the right choice for a standalone Genie chat
+experience: it provides named space aliases, SSE status updates, conversation
+history replay, query result fetching, OBO execution, and the AppKit UI
+`GenieChat` component.
+
+Use this package when Genie is one capability inside a larger agent or custom
+backend:
+
+- You want a low-level async iterator rather than an AppKit HTTP route.
+- You want raw message snapshots or a normalized event stream that can be fed
+  into Mastra writer events, logs, tests, or custom SSE endpoints.
+- You need to diff snapshots and emit only newly observed thinking, SQL, rows,
+  result, and error events.
+- You want to combine Genie answers with agent-side chart planning, statement
+  row fetches, or durable thread storage owned elsewhere.
+- You need the same driver to work inside AppKit with OBO auth and outside
+  AppKit from scripts using normal Databricks SDK auth.
+
+## Stream Semantic Events
+
+```ts
+import { chat } from "@dbx-tools/node-genie";
+
+for await (const event of chat.genieEventChat(spaceId, "Top stores by revenue?")) {
+  switch (event.type) {
+    case "thinking":
+      console.log(event.thought_type, event.text);
+      break;
+    case "query":
+      console.log(event.sql);
+      break;
+    case "rows":
+      console.log(event.row_count);
+      break;
+    case "result":
+      console.log(event.status);
+      break;
+  }
+}
+```
+
+`chat.genieEventChat()` wraps the lower-level snapshot stream and yields a
+`GenieChatEvent` union. Use it for SSE streams, log pipelines, and tool writer
+events where consumers care about progress and SQL, not just the terminal
+message.
+
+## Stream Raw Message Snapshots
+
+```ts
+import { chat } from "@dbx-tools/node-genie";
+
+for await (const message of chat.genieChat(spaceId, "Top stores by revenue?")) {
+  renderSnapshot(message);
+}
+```
+
+`chat.genieChat()` starts a conversation or appends to an existing one, polls
+`client.genie.getMessage`, filters identical consecutive payloads, and stops
+after a terminal status. Use it when you want to run your own diffing or persist
+the raw Genie wire shape.
+
+## Continue A Conversation
+
+```ts
+let conversationId: string | undefined;
+
+for (const prompt of prompts) {
+  for await (const event of chat.genieEventChat(spaceId, prompt, { conversationId })) {
+    if ("conversation_id" in event && event.conversation_id) {
+      conversationId = event.conversation_id;
+    }
+  }
+}
+```
+
+The driver does not own multi-turn state. Callers read the conversation id from
+a yielded message/event and pass it into the next turn. That makes the package
+usable in stateless route handlers, durable thread stores, and one-off scripts.
+
+This split is deliberate: the package is a transport/driver layer, not a thread
+store. AppKit-Mastra persists thread state separately and passes the Genie
+conversation id back into this driver when a turn continues.
+
+## Resolve A Workspace Client
+
+```ts
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import { chat } from "@dbx-tools/node-genie";
+
+await chat.genieEventChat(spaceId, content, {
+  workspaceClient: new WorkspaceClient({ profile: "dev" }),
+});
+```
+
+Client resolution order:
+
+1. `options.workspaceClient`;
+2. AppKit execution-context client, when present;
+3. `new WorkspaceClient({})` using normal Databricks SDK auth.
+
+Pass `options.context` as an `AbortSignal` or SDK context to cancel SDK calls and
+the polling sleep.
+
+## Read Space Metadata And Starter Questions
+
+```ts
+import { space } from "@dbx-tools/node-genie";
+
+const genieSpace = await space.getGenieSpace(spaceId);
+const questions = space.genieSampleQuestions(genieSpace);
+```
+
+`space.getGenieSpace()` fetches the space definition, including serialized space
+metadata by default. `space.genieSampleQuestions()` extracts curated starter
+questions and returns `[]` when none are configured.
+
+## Options
+
+`chat.GenieChatOptions` is shared by both drivers:
+
+- `conversationId` - append to an existing Genie conversation.
+- `workspaceClient` - explicit Databricks SDK client.
+- `pollIntervalMs` - polling cadence, default `500`.
+- `context` - SDK `Context` or `AbortSignal` for cancellation.
+
+## Modules
+
+- `chat` - `genieChat()` raw snapshot stream and `genieEventChat()` typed event
+  stream.
+- `space` - `getGenieSpace()` and `genieSampleQuestions()`.
+
+The AppKit-Mastra package builds its Genie tools on top of this driver; see
+[`@dbx-tools/node-appkit-mastra`](../appkit-mastra) for the agent-level
+workflow.

package/index.ts

@@ -0,0 +1,8 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as chat from "./src/chat";
+export * as space from "./src/space";
+export type { GenieChatOptions } from "./src/chat";
+export type { GetGenieSpaceOptions } from "./src/space";

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@dbx-tools/genie",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/node/genie"
+  },
+  "devDependencies": {
+    "@databricks/appkit": "^0.43.0",
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@databricks/appkit": "^0.43.0"
+  },
+  "dependencies": {
+    "@databricks/sdk-experimental": "^0.17.0",
+    "@dbx-tools/appkit": "0.1.9",
+    "@dbx-tools/shared-core": "0.1.9",
+    "@dbx-tools/shared-genie": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "peerDependenciesMeta": {
+    "@databricks/appkit": {
+      "optional": true
+    }
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/chat.ts

@@ -0,0 +1,324 @@
+/**
+ * Genie chat driver.
+ *
+ * Drives a single turn against a Genie space from one `content` string;
+ * multi-turn conversations are the caller's job (thread the `conversation_id`
+ * returned on each `GenieMessage` back into the next turn's
+ * `options.conversationId`).
+ *
+ * Two layers serve two kinds of consumer. The low-level layer yields every
+ * poll-observed `GenieMessage` (validated against `GenieMessageSchema`,
+ * falling back to the raw snapshot on a schema miss) and owns the messy parts
+ * - cancellation, conversation seeding, distinct-filtering, and SDK quirks
+ * (Waiter stripping); reach for it when you want the raw stream. The
+ * high-level layer wraps it and emits semantic, deduplicated `{ type, payload }`
+ * events (see {@link GenieChatEvent}), always closing a successful turn with a
+ * terminal `result` event carrying the final `GenieMessage`; errors propagate
+ * by throwing, with no `error` variant. Iterating UI / agent code that wants
+ * every message verbatim takes the low-level stream; subscribers reacting to
+ * "Genie is thinking about X" or "Genie produced text Y" take the event layer.
+ */
+
+import { async, log, type PollContext } from "@dbx-tools/shared-core";
+import { databricks } from "@dbx-tools/appkit";
+import { event, genieModel, type GenieChatEvent, type GenieMessage } from "@dbx-tools/shared-genie";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+
+const logger = log.logger("genie/chat");
+
+/**
+ * Validate a polled wire snapshot against {@link GenieMessageSchema}
+ * and return the schema-normalized message. Genie's wire occasionally ships a
+ * shape the (SDK-derived) schema doesn't model exactly - e.g. an early poll
+ * that omits the SDK-required `message_id` - so a miss degrades to the raw
+ * snapshot rather than throwing, keeping a single odd poll from aborting the
+ * whole turn.
+ */
+function validateMessage(raw: GenieMessage): GenieMessage {
+  const result = genieModel.GenieMessageSchema.safeParse(raw);
+  if (result.success) return result.data;
+  logger.debug("wire-message:schema-miss", {
+    message_id: raw.message_id ?? raw.id,
+    issues: result.error.issues.length,
+  });
+  return raw;
+}
+
+/* -------------------------- shared options -------------------------- */
+
+/** Options accepted by both {@link genieChat} and {@link genieEventChat}. */
+export interface GenieChatOptions {
+  /**
+   * Seed conversation id. When set, this turn appends to the existing
+   * conversation (via `createMessage`) instead of opening a new one. Use it to
+   * thread a multi-turn conversation: read `conversation_id` off the prior
+   * turn's terminal `GenieMessage` (or the `result` event's
+   * `payload.conversation_id`) and pass it into the next call.
+   */
+  conversationId?: string;
+  /**
+   * Explicit `WorkspaceClient`. Defaults to AppKit's per-request
+   * execution-context client when AppKit is installed and we're inside a
+   * request; falls back to a fresh `new WorkspaceClient({})` (env-var auth)
+   * otherwise.
+   */
+  workspaceClient?: WorkspaceClient;
+  /** Poll cadence in milliseconds between successive `getMessage` calls (default 500). */
+  pollIntervalMs?: number;
+  /**
+   * External cancellation. Accepts a WHATWG `AbortSignal` or a fully-built SDK
+   * `Context` (see `databricks.ContextLike`). Aborting it cancels every in-flight
+   * SDK call and the next inter-poll sleep.
+   */
+  context?: databricks.ContextLike;
+}
+
+/* ----------------------- low-level: genieChat ----------------------- */
+
+/**
+ * One turn against a Genie space, yielded as a stream of `GenieMessage`
+ * snapshots.
+ *
+ * Turn lifecycle:
+ *
+ *   - No `options.conversationId`: open a new conversation via
+ *     `client.genie.startConversation`. The opened conversation id surfaces on
+ *     every yielded `GenieMessage` (`.conversation_id`) so the caller can
+ *     thread it into a follow-up call.
+ *   - With `options.conversationId`: append to that conversation via
+ *     `client.genie.createMessage`.
+ *   - In both cases, after the create/start the driver polls
+ *     `client.genie.getMessage` every `options.pollIntervalMs` (default 500ms)
+ *     until the message reaches a terminal status, then yields the terminal
+ *     snapshot and returns.
+ *
+ * Cancellation: a single internal `AbortController` covers the whole turn.
+ * `options.context` is tied into that controller so an external abort tears
+ * down every in-flight SDK call AND the inter-poll sleep. Breaking out of the
+ * `for await` does the same via the `try / finally`.
+ *
+ * @example
+ * // Single turn.
+ * for await (const m of genieChat(spaceId, "Top 5 stores?")) {
+ *   render(m);
+ * }
+ *
+ * @example
+ * // Multi-turn: caller threads the conversation id.
+ * let conversationId: string | undefined;
+ * for (const question of questions) {
+ *   for await (const m of genieChat(spaceId, question, { conversationId })) {
+ *     conversationId = m.conversation_id ?? conversationId;
+ *     render(m);
+ *   }
+ * }
+ */
+export async function* genieChat(
+  space_id: string,
+  content: string,
+  options?: GenieChatOptions,
+): AsyncGenerator<GenieMessage, void, void> {
+  const controller = new AbortController();
+  try {
+    const client = await getWorkspaceClient(options);
+    // Build the SDK Context ONCE. Building it inside the poll producer would
+    // re-attach an abort listener to `options.context` on every poll iteration
+    // (via `databricks.toContext` -> `async.tieAbortSignal`), eventually tripping
+    // Node's `MaxListenersExceededWarning`.
+    const ctx = databricks.toContext(controller, options?.context);
+    let conversationId = options?.conversationId;
+    let messageId: string | undefined;
+
+    const pollProducer = async (pollCtx: PollContext<GenieMessage>): Promise<GenieMessage> => {
+      if (!conversationId) {
+        // First poll: open the conversation. Refuse to retry: if
+        // `startConversation` returned a response without a `conversation_id`,
+        // retrying would just open conversation after conversation.
+        if (pollCtx.attempt > 0) {
+          throw new Error("Genie did not return a conversation id; refusing to retry");
+        }
+        const startResponse = await client.genie.startConversation({ space_id, content }, ctx);
+        conversationId = startResponse.conversation_id;
+        messageId = startResponse.message_id;
+        return startResponse.message!;
+      }
+      if (!messageId) {
+        // First poll of a follow-up turn: append to the seeded conversation.
+        // `client.genie.createMessage` returns a `Waiter<GenieMessage>`
+        // (`{ ...message, wait: async () => ... }`). Strip `wait` here so
+        // downstream serializers (e.g. yaml.stringify) don't choke on the
+        // AsyncFunction value.
+        const { wait: _wait, ...createResponse } = await client.genie.createMessage(
+          { space_id, conversation_id: conversationId, content },
+          ctx,
+        );
+        messageId = createResponse.message_id;
+        return createResponse;
+      }
+      // Subsequent polls: re-fetch the current message until its status becomes
+      // terminal.
+      return await client.genie.getMessage(
+        {
+          space_id,
+          conversation_id: conversationId,
+          message_id: messageId,
+        },
+        ctx,
+      );
+    };
+
+    yield* async.poll(
+      async (pollCtx: PollContext<GenieMessage>) => validateMessage(await pollProducer(pollCtx)),
+      {
+        intervalMs: options?.pollIntervalMs ?? 500,
+        // Skip yielding identical consecutive snapshots; Genie often returns
+        // the exact same payload twice during quiet periods. `poll` does a deep
+        // equal on the previous yield.
+        filter: "distinct",
+        // Stop after the terminal message is yielded. `poll` checks the
+        // predicate AFTER yielding, so the terminal message still reaches the
+        // consumer.
+        predicate: (m) => !genieModel.isTerminalStatus(m.status),
+        // Wake the inter-poll sleep on abort so a `for await` break (or
+        // external abort) tears down promptly instead of waiting out the
+        // interval.
+        signal: controller.signal,
+      },
+    );
+  } finally {
+    // Cancels any still-pending SDK call and the inter-poll sleep whether we're
+    // unwinding from a normal return, a consumer break, or a thrown error.
+    // Idempotent.
+    controller.abort();
+  }
+}
+
+/* ---------------------- high-level: genieEventChat ------------------ */
+
+/**
+ * One turn against a Genie space, yielded as a typed {@link GenieChatEvent}
+ * stream. Drives {@link genieChat} underneath and decorates each snapshot with
+ * the derived events the field-level diff produced. Stream order:
+ *
+ *   1. `{ type: "message", message }` - the raw `GenieMessage`, once per poll
+ *      yield.
+ *   2. `{ type: "question", content, message_id, ... }` fires exactly once, on
+ *      the FIRST `message` yield. We read `content` and `message_id` straight
+ *      off the snapshot so every downstream event for this turn shares the same
+ *      `message_id` (the question included) - subscribers can group everything
+ *      for one Genie call under that one key.
+ *   3. Any of `status` / `attachment` / `thinking` / `text` / `query` /
+ *      `statement` / `rows` / `suggested_questions` the diff against the prior
+ *      snapshot produced.
+ *   4. On the terminal snapshot, `{ type: "result", ... }` as the final yield.
+ *
+ * Errors propagate by the generator throwing - there's no `"error"` variant.
+ * Wrap the `for await` in `try/catch` if you need to handle failures.
+ *
+ * @example
+ * for await (const evt of genieEventChat(spaceId, "Top stores?")) {
+ *   switch (evt.type) {
+ *     case "thinking":
+ *       console.log("[thinking]", evt.thought_type, evt.text);
+ *       break;
+ *     case "text":
+ *       console.log("[text]", evt.text);
+ *       break;
+ *     case "result":
+ *       console.log("[done]", evt.status);
+ *       break;
+ *   }
+ * }
+ */
+export async function* genieEventChat(
+  space_id: string,
+  content: string,
+  options?: GenieChatOptions,
+): AsyncGenerator<GenieChatEvent, void, void> {
+  // Diff source for the current turn. Always `undefined` on the first snapshot
+  // so the initial status / attachments emit fresh; updated to the most recent
+  // snapshot after each yield.
+  let previous: GenieMessage | undefined;
+  // The `question` event is deferred to the first `message` yield so it can
+  // carry the assigned `message_id` (subscribers use it as the grouping key for
+  // every event in this turn). The first snapshot is the earliest point that id
+  // exists.
+  let questionEmitted = false;
+  for await (const rawMessage of genieChat(space_id, content, options)) {
+    // Normalize `message_id` from the legacy `id` field when Genie's wire
+    // response only populates one of them. The SDK schema marks both as
+    // required, but in practice the `startConversation` / `createMessage` inner
+    // `message` payload sometimes ships only `id` while the new `message_id`
+    // field lands undefined. Every downstream event detector keys grouping off
+    // `message_id`; the fallback keeps one Genie turn's events from splitting
+    // across an anon group + the real-id group when subscribers bucket by
+    // `message_id`.
+    const message: GenieMessage = rawMessage.message_id
+      ? rawMessage
+      : { ...rawMessage, message_id: rawMessage.id };
+    yield {
+      type: "message",
+      space_id: message.space_id,
+      message_id: message.message_id,
+      message,
+    };
+    if (!questionEmitted) {
+      yield {
+        type: "question",
+        space_id: message.space_id,
+        ...(message.conversation_id ? { conversation_id: message.conversation_id } : {}),
+        ...(message.message_id ? { message_id: message.message_id } : {}),
+        content: message.content,
+      };
+      questionEmitted = true;
+    }
+    yield* event.eventsFromMessage(message, previous, message.space_id);
+    const status = message.status;
+    if (genieModel.isTerminalStatus(status)) {
+      yield {
+        type: "result",
+        space_id: message.space_id,
+        conversation_id: message.conversation_id,
+        message_id: message.message_id,
+        status,
+        message,
+      };
+    }
+    previous = message;
+  }
+}
+
+/* ---------------------- workspace client helper --------------------- */
+
+/**
+ * Resolve a `WorkspaceClient` in this preference order:
+ *
+ *   1. Caller-supplied `options.workspaceClient`.
+ *   2. AppKit's per-request execution-context client, when AppKit is installed
+ *      AND we're inside a request scope.
+ *   3. Fresh `new WorkspaceClient({})` (env-var auth via
+ *      `DATABRICKS_CONFIG_PROFILE` / `DATABRICKS_HOST` / `DATABRICKS_TOKEN`).
+ *
+ * AppKit is loaded lazily so this package stays usable in non-AppKit
+ * environments.
+ */
+async function getWorkspaceClient(options?: GenieChatOptions): Promise<WorkspaceClient> {
+  if (options?.workspaceClient) return options.workspaceClient;
+  const appkit = await getAppKit();
+  if (appkit) {
+    try {
+      return appkit.getExecutionContext().client;
+    } catch {
+      // Not inside an AppKit request context; fall through to env.
+    }
+  }
+  return new WorkspaceClient({});
+}
+
+async function getAppKit() {
+  try {
+    return await import("@databricks/appkit");
+  } catch {
+    return undefined;
+  }
+}

package/src/space.ts

@@ -0,0 +1,113 @@
+/**
+ * Genie space metadata helpers.
+ *
+ * Fetches a Genie space's definition (including the opt-in `serialized_space`
+ * blob) and extracts the curated starter questions an author configured on the
+ * space. The typed SDK `client.genie.getSpace` only returns the
+ * directory-listing surface (`title` / `description` / `warehouse_id`); the
+ * sample questions live inside `serialized_space`, which the REST API returns
+ * only when `include_serialized_space=true`. We hit that endpoint through the
+ * workspace client's raw `apiClient` since the typed request shape has no flag
+ * for it.
+ */
+
+import { error, log, string } from "@dbx-tools/shared-core";
+import { databricks } from "@dbx-tools/appkit";
+import { genieModel, type GenieSpace } from "@dbx-tools/shared-genie";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+
+const logger = log.logger("genie/space");
+
+/** Options for {@link getGenieSpace}. */
+export interface GetGenieSpaceOptions {
+  /**
+   * Explicit `WorkspaceClient`. Defaults to a fresh `new WorkspaceClient({})`
+   * (env-var auth). Server callers should pass their OBO-scoped client so the
+   * lookup runs as the user.
+   */
+  workspaceClient?: WorkspaceClient;
+  /**
+   * Request the `serialized_space` blob (catalogs, tables, sample questions,
+   * prompts). Defaults to `true` - the only reason to skip it is when the
+   * caller just needs title / description and wants the smaller payload.
+   */
+  serialized?: boolean;
+  /**
+   * External cancellation. Accepts a WHATWG `AbortSignal` or a fully-built SDK
+   * `Context` (see `databricks.ContextLike`).
+   */
+  context?: databricks.ContextLike;
+}
+
+/**
+ * Fetch a Genie space by id, optionally including its serialized definition.
+ * Hits `GET /api/2.0/genie/spaces/<id>` with `include_serialized_space=true`
+ * through the raw `apiClient`, then validates the response against
+ * {@link GenieSpaceSchema} (unknown fields like `etag` /
+ * `parent_path` are stripped).
+ */
+export async function getGenieSpace(
+  spaceId: string,
+  options?: GetGenieSpaceOptions,
+): Promise<GenieSpace> {
+  const client = options?.workspaceClient ?? new WorkspaceClient({});
+  const serialized = options?.serialized !== false;
+  const ctx = options?.context ? databricks.toContext(options.context) : undefined;
+  const raw = await client.apiClient.request(
+    {
+      path: `/api/2.0/genie/spaces/${encodeURIComponent(spaceId)}`,
+      method: "GET",
+      query: serialized ? { include_serialized_space: true } : {},
+      headers: new Headers(),
+      raw: false,
+    },
+    ctx,
+  );
+  return genieModel.GenieSpaceSchema.parse(raw);
+}
+
+/**
+ * One entry in a serialized space's `config.sample_questions`. The
+ * author-facing field is `question`, which the wire format models as a string
+ * array (a single multi-line question is split across entries); we treat the
+ * first non-empty entry as the displayable question text.
+ */
+interface SerializedSampleQuestion {
+  question?: unknown;
+}
+
+/**
+ * Extract the curated starter questions an author configured on a Genie space.
+ * Reads `serialized_space -> config.sample_questions[*].question`. Returns `[]`
+ * when the space carries no serialized blob, the blob is unparseable, or no
+ * sample questions are configured - so a missing or misconfigured space
+ * degrades to "no suggestions" rather than throwing. Order is preserved (the
+ * author's ordering) and duplicates are dropped.
+ */
+export function genieSampleQuestions(space: GenieSpace): string[] {
+  const serialized = space.serialized_space;
+  if (!serialized) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(serialized);
+  } catch (err) {
+    logger.warn("serialized-space:parse-error", {
+      spaceId: space.space_id,
+      error: error.errorMessage(err),
+    });
+    return [];
+  }
+  const sampleQuestions = (parsed as { config?: { sample_questions?: unknown } } | null)?.config
+    ?.sample_questions;
+  if (!Array.isArray(sampleQuestions)) return [];
+
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of sampleQuestions as SerializedSampleQuestion[]) {
+    const text = string.firstNonEmpty(entry?.question);
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    out.push(text);
+  }
+  return out;
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}