@alexkroman1/aai-cli 5.1.1 → 5.2.0

package/dist/templates/dispatch-center/tools/resources_get_available.ts

@@ -0,0 +1,36 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import { getState, RESOURCE_TYPES } from "../shared.ts";
+
+export const resourcesGetAvailable = tool({
+  description: "List available resources, optionally filtered by type.",
+  parameters: z.object({
+    type: z
+      .enum([...RESOURCE_TYPES, "all"])
+      .describe("Filter by resource type, or 'all'")
+      .optional(),
+  }),
+  async execute(args, ctx) {
+    const state = getState(ctx);
+    let resources = state.resources;
+    if (args.type && args.type !== "all") {
+      resources = resources.filter((r) => r.type === args.type);
+    }
+
+    return {
+      resources: resources.map((r) => ({
+        callsign: r.callsign,
+        type: r.type,
+        status: r.status,
+        assignedIncident: r.assignedIncident,
+        eta: r.eta,
+        capabilities: r.capabilities,
+      })),
+      summary: {
+        total: resources.length,
+        available: resources.filter((r) => r.status === "available").length,
+        committed: resources.filter((r) => r.status !== "available").length,
+      },
+    };
+  },
+});

package/dist/templates/dispatch-center/tools/resources_update_status.ts

@@ -0,0 +1,62 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import { logEvent, RESOURCE_STATUSES, updateState } from "../shared.ts";
+
+export const resourcesUpdateStatus = tool({
+  description: "Update a resource unit's status when it radios in.",
+  parameters: z.object({
+    callsign: z.string().max(50).describe("The resource callsign"),
+    status: z.enum(RESOURCE_STATUSES).describe("New status"),
+    notes: z.string().max(1000).describe("Status notes").optional(),
+  }),
+  async execute(args, ctx) {
+    return updateState(ctx, (state) => {
+      const resource = state.resources.find(
+        (r) => r.callsign.toLowerCase() === args.callsign.toLowerCase(),
+      );
+      if (!resource) {
+        return { error: `Resource ${args.callsign} not found` };
+      }
+
+      const previousStatus = resource.status;
+
+      // Log to the incident timeline BEFORE unassigning, so the
+      // return-to-available transition is recorded too.
+      if (resource.assignedIncident) {
+        const inc = state.incidents[resource.assignedIncident];
+        if (inc) {
+          logEvent(
+            inc,
+            `${resource.callsign}: ${previousStatus} → ${args.status}${args.notes ? ` (${args.notes})` : ""}`,
+          );
+        }
+      }
+
+      resource.status = args.status;
+
+      if (args.status === "available") {
+        // Detach from the old incident on BOTH sides — leaving the id in
+        // assignedResources lets that incident later yank a unit that has
+        // been re-dispatched elsewhere.
+        if (resource.assignedIncident) {
+          const inc = state.incidents[resource.assignedIncident];
+          if (inc) {
+            inc.assignedResources = inc.assignedResources.filter((id) => id !== resource.id);
+          }
+        }
+        resource.assignedIncident = null;
+        resource.eta = null;
+      }
+      if (args.status === "on_scene") {
+        resource.eta = null;
+      }
+
+      return {
+        callsign: resource.callsign,
+        previousStatus,
+        newStatus: args.status,
+        assignedIncident: resource.assignedIncident,
+      };
+    });
+  },
+});

package/dist/templates/embedded-assets/agent.ts

@@ -0,0 +1,55 @@
+import { agent, assemblyAIPipeline, tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import knowledge from "./knowledge.json" with { type: "json" };
+
+type FaqEntry = { question: string; answer: string };
+const faqs: FaqEntry[] = knowledge.faqs;
+
+// Search text is static, so it's normalized once at module load — per-call
+// work stays O(query) even when the knowledge base grows.
+const searchable = faqs.map((entry) => ({
+  entry,
+  text: `${entry.question} ${entry.answer}`.toLowerCase(),
+}));
+
+export default agent({
+  name: "FAQ Bot",
+  ...assemblyAIPipeline(),
+  systemPrompt:
+    "You are a friendly FAQ assistant. Answer questions using ONLY the information from your embedded knowledge base. If the user asks something not covered by your knowledge base, say you don't have that information and suggest they check the official documentation.\n\nRules:\n- Keep answers concise and conversational — this is a voice agent\n- Quote the knowledge base accurately, do not embellish\n- If a question is ambiguous, ask the user to clarify\n- Use 'search_knowledge' to find answers to specific questions\n- Use 'list_topics' to see all available FAQ topics\n- Always be helpful and polite",
+  greeting:
+    "Hi! I'm your FAQ assistant. Ask me anything about the AAI agent framework and I'll look it up in my knowledge base.",
+
+  tools: {
+    list_topics: tool({
+      description: "List all available topics in the embedded FAQ knowledge base.",
+      async execute() {
+        return faqs.map((f) => f.question);
+      },
+    }),
+
+    search_knowledge: tool({
+      description:
+        "Search the embedded FAQ knowledge base for an answer matching the user's question.",
+      parameters: z.object({
+        query: z.string().describe("The user's question to search for"),
+      }),
+      async execute(args) {
+        // Score by word overlap — natural questions rarely match an FAQ
+        // entry as an exact substring.
+        const words = args.query
+          .toLowerCase()
+          .split(/\W+/)
+          .filter((w) => w.length > 2);
+        if (words.length === 0) return { result: "No matching FAQ found." };
+
+        let best: { entry: FaqEntry; score: number } | null = null;
+        for (const { entry, text } of searchable) {
+          const score = words.filter((w) => text.includes(w)).length;
+          if (score > 0 && (!best || score > best.score)) best = { entry, score };
+        }
+        return best?.entry ?? { result: "No matching FAQ found." };
+      },
+    }),
+  },
+});

package/dist/templates/embedded-assets/knowledge.json

@@ -0,0 +1,20 @@
+{
+  "faqs": [
+    {
+      "question": "What is AAI?",
+      "answer": "AAI is a framework for building voice-powered AI agents that run on Node.js."
+    },
+    {
+      "question": "How do agents handle tools?",
+      "answer": "Agents define tools with a schema and handler function. The LLM decides when to call them based on the conversation."
+    },
+    {
+      "question": "What speech providers are supported?",
+      "answer": "AAI supports AssemblyAI for speech-to-text and text-to-speech."
+    },
+    {
+      "question": "Can agents access the internet?",
+      "answer": "Yes, agents run with network access and can make HTTP requests via the fetch API or built-in tools like web_search."
+    }
+  ]
+}

package/dist/templates/health-assistant/agent.ts

@@ -0,0 +1,174 @@
+import { agent, assemblyAIPipeline, tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import systemPrompt from "./system-prompt.md?raw";
+
+function first(arr: string[] | undefined): string | undefined {
+  return arr?.[0];
+}
+
+type FdaLabel = Record<string, unknown> & { openfda?: Record<string, string[]> };
+
+/**
+ * Fetch a drug's FDA label (generic OR brand name match) from openFDA.
+ * Returns null when the drug can't be found or the API is unreachable.
+ *
+ * Memoized per drug name: a voice session naturally asks several questions
+ * about the same drugs, and labels are static, so repeats skip the network
+ * round-trip. A null result (not found, or a transient network failure) is
+ * NOT cached, so the next call retries instead of pinning the failure.
+ */
+const labelCache = new Map<string, Promise<FdaLabel | null>>();
+
+function fetchFdaLabel(name: string): Promise<FdaLabel | null> {
+  const key = name.toLowerCase();
+  let p = labelCache.get(key);
+  if (!p) {
+    p = fetchFdaLabelUncached(key).then((label) => {
+      if (label === null) labelCache.delete(key);
+      return label;
+    });
+    labelCache.set(key, p);
+  }
+  return p;
+}
+
+async function fetchFdaLabelUncached(name: string): Promise<FdaLabel | null> {
+  const q = encodeURIComponent(name);
+  try {
+    const resp = await fetch(
+      `https://api.fda.gov/drug/label.json?search=openfda.generic_name:"${q}"+openfda.brand_name:"${q}"&limit=1`,
+    );
+    if (!resp.ok) return null;
+    const raw = (await resp.json()) as { results?: FdaLabel[] };
+    return raw.results?.[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+type DrugInfo = {
+  /** The name the user asked about. */
+  name: string;
+  /** All known names, lowercased — generic + brands — used for cross-matching. */
+  aliases: string[];
+  /** The label's "Drug Interactions" section, lowercased. */
+  interactionsText: string;
+};
+
+function toDrugInfo(name: string, label: FdaLabel): DrugInfo {
+  const openfda = label.openfda ?? {};
+  const generic = openfda.generic_name ?? [];
+  const brands = openfda.brand_name ?? [];
+  const aliases = [...new Set([name, ...generic, ...brands].map((n) => n.toLowerCase()))];
+  const interactionsText = ((label.drug_interactions as string[] | undefined) ?? [])
+    .join(" ")
+    .toLowerCase();
+  return { name, aliases, interactionsText };
+}
+
+/** Pull a short excerpt around the first mention of `alias` in `text`. */
+function excerptAround(text: string, alias: string): string {
+  const idx = text.indexOf(alias);
+  const start = Math.max(0, idx - 100);
+  const end = Math.min(text.length, idx + alias.length + 200);
+  return `${start > 0 ? "…" : ""}${text.slice(start, end)}${end < text.length ? "…" : ""}`;
+}
+
+export default agent({
+  name: "Dr. Sage",
+  ...assemblyAIPipeline(),
+  systemPrompt,
+  greeting:
+    "Hey, I'm Dr. Sage. Try asking me something like, what are the side effects of ibuprofen, can I take aspirin and warfarin together, or calculate my BMI. Just remember, I'm not a real doctor, so always check with your healthcare provider.",
+  builtinTools: ["web_search", "run_code"],
+
+  tools: {
+    check_drug_interaction: tool({
+      description:
+        "Check for interactions between two or more medications using FDA drug label data. Looks up each drug's official label and reports where one drug's Drug Interactions section mentions another. Absence of a mention does not guarantee safety.",
+      parameters: z.object({
+        drugs: z
+          .array(z.string().min(1))
+          .min(2)
+          .describe("Medication names to check, e.g. ['ibuprofen', 'warfarin']"),
+      }),
+      async execute(args) {
+        const names = args.drugs.map((d) => d.trim().toLowerCase()).filter((d) => d.length > 0);
+        if (names.length < 2) {
+          return { error: "Provide at least two medication names to check." };
+        }
+
+        const labels = await Promise.all(names.map((n) => fetchFdaLabel(n)));
+        const unresolved = names.filter((_, i) => labels[i] === null);
+        if (unresolved.length > 0) {
+          // Never silently drop a drug from an interaction check — a partial
+          // answer would read as "no interaction" for the missing one.
+          return {
+            error: `Could not find FDA label data for: ${unresolved.join(", ")}. Check the spelling, or try the generic name.`,
+          };
+        }
+
+        // The unresolved check above guarantees every label resolved.
+        const drugs = names.map((name, i) => toDrugInfo(name, labels[i]!));
+
+        const interactions: Array<{ drug: string; mentions: string; excerpt: string }> = [];
+        for (const a of drugs) {
+          if (!a.interactionsText) continue;
+          for (const b of drugs) {
+            if (a === b) continue;
+            const hit = b.aliases.find((alias) => a.interactionsText.includes(alias));
+            if (hit) {
+              interactions.push({
+                drug: a.name,
+                mentions: b.name,
+                excerpt: excerptAround(a.interactionsText, hit).slice(0, 400),
+              });
+            }
+          }
+        }
+
+        return {
+          drugs: names,
+          interactions_found: interactions.length,
+          interactions: interactions.slice(0, 5),
+          note:
+            interactions.length === 0
+              ? "No cross-mentions found in the FDA label Drug Interactions sections. This does not guarantee the combination is safe — confirm with a pharmacist or doctor."
+              : "Based on FDA label Drug Interactions sections. Confirm with a pharmacist or doctor.",
+        };
+      },
+    }),
+
+    medication_lookup: tool({
+      description:
+        "Look up detailed information about a single medication, including purpose, warnings, dosage, side effects, and manufacturer. Works with both generic and brand names.",
+      parameters: z.object({
+        name: z
+          .string()
+          .describe("Medication name (generic or brand, e.g. 'ibuprofen' or 'Advil')"),
+      }),
+      async execute(args) {
+        const drug = await fetchFdaLabel(args.name);
+        if (!drug) {
+          return { error: `No FDA data found for: ${args.name}` };
+        }
+
+        const openfda = drug.openfda ?? {};
+        return {
+          name: openfda.generic_name?.[0] ?? args.name,
+          brand_names: openfda.brand_name ?? [],
+          purpose:
+            first(drug.purpose as string[] | undefined) ??
+            first(drug.indications_and_usage as string[] | undefined) ??
+            "N/A",
+          warnings: first(drug.warnings as string[] | undefined)?.slice(0, 500) ?? "N/A",
+          dosage:
+            first(drug.dosage_and_administration as string[] | undefined)?.slice(0, 500) ?? "N/A",
+          side_effects:
+            first(drug.adverse_reactions as string[] | undefined)?.slice(0, 500) ?? "N/A",
+          manufacturer: openfda.manufacturer_name?.[0] ?? "N/A",
+        };
+      },
+    }),
+  },
+});

package/dist/templates/health-assistant/system-prompt.md

@@ -0,0 +1,17 @@
+You are Dr. Sage, a friendly health information assistant. You help people understand symptoms, look up medication details, check drug interactions, and calculate basic health metrics.
+
+Rules:
+- You are NOT a doctor and cannot diagnose or prescribe. Always remind users to consult a healthcare provider for medical decisions.
+- Be clear and calm when discussing symptoms — avoid alarming language
+- When discussing medications, always mention common side effects
+- Use plain language first, then mention the medical term
+- Keep responses concise — this is a voice conversation
+- If symptoms sound urgent (chest pain, difficulty breathing, sudden numbness), advise calling emergency services immediately
+- Use web_search to look up current symptom information when needed
+- Use medication_lookup to get details on a single medication
+- Use check_drug_interaction to check interactions between multiple drugs. It reads FDA drug labels — if it finds no mention, say that no interaction was found on the labels but that this does not prove the combination is safe, and recommend asking a pharmacist
+
+Use run_code for health calculations:
+- BMI: weight_kg / (height_m * height_m). Categories: <18.5 underweight, 18.5-25 normal, 25-30 overweight, >30 obese
+  Unit conversions: 1 lb = 0.453592 kg, 1 in = 0.0254 m, 1 ft = 0.3048 m, 1 cm = 0.01 m
+- Weight-based dosage: dose_mg = weight_kg * dose_per_kg. Always note this is an estimate.

package/dist/templates/infocom-adventure/agent.ts

@@ -0,0 +1,119 @@
+import { agent, assemblyAIPipeline, tool } from "@alexkroman1/aai";
+import { assemblyAI as assemblyAITts } from "@alexkroman1/aai/tts";
+import { z } from "zod";
+import { getGameState, resetGameState } from "./shared.ts";
+import systemPrompt from "./system-prompt.md?raw";
+
+export default agent({
+  name: "Cavern Adventure",
+  ...assemblyAIPipeline(),
+  // Overriding one stage of the preset: a narrator wants a narrative voice,
+  // and the other two stages stay as the preset set them.
+  tts: assemblyAITts({ voice: "paul" }),
+  systemPrompt,
+  // The opening scene here must agree with DEFAULT_GAME_STATE.currentRoom
+  // (shared.ts) and the world map in system-prompt.md.
+  greeting:
+    "Welcome, adventurer. You are standing at the mouth of a weathered cave at the edge of a pine forest. A cold wind carries the smell of damp stone up from the darkness below. A rusted lantern hangs from an iron hook beside the entrance. What would you like to do?",
+
+  tools: {
+    game_state_drop: tool({
+      description: "Remove an item from the player's inventory.",
+      parameters: z.object({
+        value: z.string().describe("Item name to drop"),
+      }),
+      async execute(args, ctx) {
+        const g = getGameState(ctx);
+        g.inventory = g.inventory.filter((i) => i !== args.value);
+        return { inventory: g.inventory };
+      },
+    }),
+
+    game_state_flag: tool({
+      description: "Set a game flag to true, used for tracking puzzle and event state.",
+      parameters: z.object({
+        value: z.string().describe("Flag name to set"),
+      }),
+      async execute(args, ctx) {
+        const g = getGameState(ctx);
+        g.flags[args.value] = true;
+        return { flags: g.flags };
+      },
+    }),
+
+    game_state_get: tool({
+      description:
+        "Read the current game state including inventory, current room, score, moves, flags, and recent history.",
+      async execute(_args, ctx) {
+        const g = getGameState(ctx);
+        return {
+          currentRoom: g.currentRoom,
+          inventory: g.inventory,
+          score: g.score,
+          moves: g.moves,
+          flags: g.flags,
+          recentHistory: g.history.slice(-5),
+        };
+      },
+    }),
+
+    game_state_history: tool({
+      description: "Log a player command to the history and increment the move counter.",
+      parameters: z.object({
+        value: z.string().describe("Command text to log"),
+      }),
+      async execute(args, ctx) {
+        const g = getGameState(ctx);
+        g.history.push(args.value);
+        g.moves++;
+        return { moves: g.moves, recentHistory: g.history.slice(-5) };
+      },
+    }),
+
+    game_state_move: tool({
+      description: "Move the player to a new room and increment the move counter.",
+      parameters: z.object({
+        value: z.string().describe("Room name to move to"),
+      }),
+      async execute(args, ctx) {
+        const g = getGameState(ctx);
+        g.currentRoom = args.value;
+        g.moves++;
+        return { currentRoom: g.currentRoom, moves: g.moves };
+      },
+    }),
+
+    game_state_restart: tool({
+      description:
+        "Reset the game to the beginning: empty inventory, zero score and moves, all flags cleared. Use when the player asks to restart, quit, or start a new game.",
+      async execute(_args, ctx) {
+        const g = resetGameState(ctx);
+        return { restarted: true, currentRoom: g.currentRoom };
+      },
+    }),
+
+    game_state_score: tool({
+      description: "Add points to the player's score.",
+      parameters: z.object({
+        value: z.number().describe("Points to add"),
+      }),
+      async execute(args, ctx) {
+        const g = getGameState(ctx);
+        g.score += args.value;
+        return { score: g.score };
+      },
+    }),
+
+    game_state_take: tool({
+      description: "Add an item to the player's inventory.",
+      parameters: z.object({
+        value: z.string().describe("Item name to take"),
+      }),
+      async execute(args, ctx) {
+        const g = getGameState(ctx);
+        if (!g.inventory.includes(args.value)) g.inventory.push(args.value);
+        return { inventory: g.inventory };
+      },
+    }),
+  },
+});