@amitdeshmukh/ax-crew 7.0.0 → 8.0.0

package/examples/ace-flight-finder.ts

@@ -0,0 +1,329 @@
+/**
+ * ACE Feedback Loop Demo - Google Flights Assistant
+ * 
+ * This example demonstrates:
+ * - An agent using Google Flights MCP server for real flight searches
+ * - ACE learning from user feedback to improve recommendations
+ * - Interactive CLI for flight queries
+ * - Playbook persistence and display
+ * 
+ * ═══════════════════════════════════════════════════════════════════
+ * SETUP: Google Flights MCP Server
+ * ═══════════════════════════════════════════════════════════════════
+ * 
+ * This example uses the Google Flights MCP Server:
+ * https://github.com/opspawn/Google-Flights-MCP-Server
+ * 
+ * Installation:
+ * 
+ * 1. Clone the MCP server:
+ *    git clone https://github.com/opspawn/Google-Flights-MCP-Server.git
+ *    cd Google-Flights-MCP-Server
+ * 
+ * 2. Create virtual environment and install dependencies:
+ *    python -m venv .venv
+ *    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+ *    pip install -r requirements.txt
+ * 
+ * 3. Install Playwright browsers (needed by fast_flights):
+ *    playwright install
+ * 
+ * 4. Set environment variable and run from activated venv:
+ *    export GOOGLE_FLIGHTS_SERVER_PATH="/path/to/Google-Flights-MCP-Server/server.py"
+ *    # Python is auto-detected from your PATH (uses activated venv)
+ * 
+ * Available MCP Tools:
+ * - get_flights_on_date: One-way flights for a specific date
+ * - get_round_trip_flights: Round-trip flights with departure/return dates
+ * - find_all_flights_in_range: Find flights within a date range
+ * 
+ * ═══════════════════════════════════════════════════════════════════
+ * 
+ * Usage: npx tsx examples/ace-feedback-routing.ts
+ */
+
+import { AxCrew } from "../dist/index.js";
+import { AxCrewFunctions } from "../dist/functions/index.js";
+import type { AxCrewConfig } from "../dist/types.js";
+import type { Provider } from "../dist/types.js";
+import "dotenv/config";
+import * as readline from "readline";
+
+// --- 1. Configuration ---
+
+// Google Flights MCP Server paths - set via env vars
+// See: https://github.com/opspawn/Google-Flights-MCP-Server
+const GOOGLE_FLIGHTS_SERVER = process.env.GOOGLE_FLIGHTS_SERVER_PATH 
+  || "/path/to/Google-Flights-MCP-Server/server.py";
+// Uses system python by default - activate your venv before running!
+const GOOGLE_FLIGHTS_PYTHON = process.env.PYTHON_PATH || "python";
+
+const crewConfig: AxCrewConfig = {
+  crew: [
+    {
+      name: "FlightAssistant",
+      description: `A helpful flight booking assistant that searches Google Flights and provides recommendations.`,
+      signature: "query:string -> recommendation:string",
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: {
+        model: "gemini-flash-latest",
+        temperature: 0.7,
+      },
+      options: {
+        debug: false,
+        stream: false
+      },
+      // Google Flights MCP Server - see https://github.com/opspawn/Google-Flights-MCP-Server
+      mcpServers: {
+        "google-flights": {
+          command: GOOGLE_FLIGHTS_PYTHON,
+          args: [GOOGLE_FLIGHTS_SERVER],
+          env: {}
+        }
+      },
+      // Enable ACE for learning from feedback
+      ace: {
+        teacher: {
+          provider: "google-gemini" as Provider,
+          providerKeyName: "GEMINI_API_KEY",
+          ai: { model: "gemini-flash-latest" }
+        },
+        options: { 
+          maxEpochs: 1, 
+          allowDynamicSections: true 
+        },
+        persistence: { 
+          playbookPath: "playbooks/flight-assistant.json", 
+          autoPersist: true 
+        },
+        metric: { primaryOutputField: "recommendation" },
+        compileOnStart: false,
+      }
+    }
+  ]
+};
+
+// --- 2. CLI Helper Functions ---
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+const prompt = (question: string): Promise<string> => {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+};
+
+const displayPlaybook = (playbook: any, agentName: string) => {
+  console.log(`\n📘 ACE Playbook for ${agentName}:`);
+  console.log("─".repeat(60));
+  
+  if (!playbook) {
+    console.log("  (No playbook yet - will be created after first feedback)");
+    console.log("─".repeat(60));
+    return;
+  }
+  
+  if (playbook.sections) {
+    for (const [sectionName, bullets] of Object.entries(playbook.sections)) {
+      console.log(`\n  📂 ${sectionName}:`);
+      if (Array.isArray(bullets)) {
+        bullets.forEach((bullet: any, i: number) => {
+          const content = typeof bullet === 'string' ? bullet : bullet.content || JSON.stringify(bullet);
+          console.log(`     ${i + 1}. ${content}`);
+        });
+      }
+    }
+  } else {
+    console.log("  " + JSON.stringify(playbook, null, 2).replace(/\n/g, "\n  "));
+  }
+  
+  if (playbook.updatedAt) {
+    console.log(`  🕐 Last updated: ${new Date(playbook.updatedAt).toLocaleString()}`);
+  }
+  
+  console.log("─".repeat(60));
+};
+
+const displayHelp = () => {
+  console.log("\n📋 Example flight queries:");
+  console.log("   • Find flights from JFK to LAX on 2025-02-15");
+  console.log("   • Round trip from SFO to LHR, leaving 2025-03-01 returning 2025-03-10");
+  console.log("   • Cheapest flights from NYC to Tokyo in March 2025");
+  console.log("\n📝 Feedback examples to train the assistant:");
+  console.log("   • Always show price in USD");
+  console.log("   • Prioritize direct flights");
+  console.log("   • Include flight duration");
+};
+
+// --- 3. Main Interactive Loop ---
+
+async function main() {
+  console.log("\n✈️  ACE Flight Assistant - Google Flights Edition");
+  console.log("═".repeat(60));
+  console.log("Search real flights and train the assistant with feedback.");
+  console.log("MCP Server: https://github.com/opspawn/Google-Flights-MCP-Server\n");
+
+  // Check configuration
+  const isConfigured = !GOOGLE_FLIGHTS_SERVER.includes("/path/to/");
+  if (!isConfigured) {
+    console.log("⚠️  MCP Server not configured!");
+    console.log("   1. Clone: git clone https://github.com/opspawn/Google-Flights-MCP-Server.git");
+    console.log("   2. Setup: cd Google-Flights-MCP-Server && python -m venv .venv");
+    console.log("   3. Activate: source .venv/bin/activate");
+    console.log("   4. Install: pip install -r requirements.txt && playwright install");
+    console.log("   5. Export: export GOOGLE_FLIGHTS_SERVER_PATH=/path/to/server.py");
+    console.log("\n   Demo will continue but flight lookups won't work.\n");
+  }
+
+  // Initialize AxCrew
+  const crew = new AxCrew(crewConfig, AxCrewFunctions);
+
+  try {
+    console.log("⏳ Initializing Flight Assistant...");
+    await crew.addAgentsToCrew(["FlightAssistant"]);
+    const assistant = crew.agents!.get("FlightAssistant")!;
+
+    console.log("✅ Flight Assistant ready with ACE enabled");
+    if (isConfigured) {
+      console.log("✅ Google Flights MCP server connected\n");
+    }
+
+    // Show initial playbook (if loaded from persistence)
+    const initialPlaybook = (assistant as any).getPlaybook?.();
+    displayPlaybook(initialPlaybook, "FlightAssistant");
+
+    displayHelp();
+
+    let continueLoop = true;
+    let queryCount = 0;
+    let feedbackCount = 0;
+
+    while (continueLoop) {
+      console.log(`\n${"═".repeat(60)}`);
+      console.log(`✈️  Search #${queryCount + 1}`);
+      console.log("═".repeat(60));
+
+      // Get flight query from user
+      const query = await prompt("\n🔍 Flight query (or 'help'/'quit'): ");
+      
+      if (query.toLowerCase() === 'quit' || query.toLowerCase() === 'exit' || query === '') {
+        continueLoop = false;
+        continue;
+      }
+
+      if (query.toLowerCase() === 'help') {
+        displayHelp();
+        continue;
+      }
+
+      if (query.toLowerCase() === 'playbook') {
+        const currentPlaybook = (assistant as any).getPlaybook?.();
+        displayPlaybook(currentPlaybook, "FlightAssistant");
+        continue;
+      }
+
+      queryCount++;
+      console.log("\n⏳ Searching Google Flights...\n");
+
+      try {
+        // Execute the query
+        const result = await assistant.forward({ query });
+        const taskId = (result as any)._taskId;
+
+        console.log("─".repeat(60));
+        console.log("🛫 Flight Results:");
+        console.log("─".repeat(60));
+        console.log(result.recommendation);
+        console.log("─".repeat(60));
+
+        // Get feedback from user
+        console.log("\n💬 Train the assistant (Enter feedback or press Enter to skip):");
+        
+        const feedback = await prompt("📝 Feedback: ");
+
+        if (feedback.toLowerCase() === 'quit' || feedback.toLowerCase() === 'exit') {
+          continueLoop = false;
+          continue;
+        }
+
+        if (feedback && feedback.length > 0) {
+          console.log("\n⏳ Updating ACE playbook...");
+
+          // Apply feedback via ACE
+          if (taskId) {
+            await crew.applyTaskFeedback({
+              taskId,
+              feedback,
+              strategy: "all"
+            });
+          } else {
+            await (assistant as any).applyOnlineUpdate?.({
+              example: { query },
+              prediction: result,
+              feedback
+            });
+          }
+
+          feedbackCount++;
+          console.log("✅ Playbook updated!\n");
+
+          // Display updated playbook
+          const updatedPlaybook = (assistant as any).getPlaybook?.();
+          displayPlaybook(updatedPlaybook, "FlightAssistant");
+
+          console.log("\n💡 The assistant has learned from your feedback!");
+        } else {
+          console.log("\n⏭️  Skipped feedback.");
+        }
+
+      } catch (error: any) {
+        console.error(`\n❌ Error: ${error.message}`);
+        if (error.message.includes("MCP") || error.message.includes("transport")) {
+          console.log("   Check MCP server configuration.");
+          console.log("   See: https://github.com/opspawn/Google-Flights-MCP-Server");
+        }
+      }
+    }
+
+    // Final summary
+    console.log("\n" + "═".repeat(60));
+    console.log("📊 Session Summary");
+    console.log("═".repeat(60));
+    console.log(`   Searches: ${queryCount}`);
+    console.log(`   Feedback given: ${feedbackCount}`);
+    
+    const finalPlaybook = (assistant as any).getPlaybook?.();
+    if (finalPlaybook?.sections) {
+      const bulletCount = Object.values(finalPlaybook.sections)
+        .reduce((acc: number, bullets: any) => acc + (Array.isArray(bullets) ? bullets.length : 0), 0);
+      console.log(`   Playbook insights: ${bulletCount}`);
+    }
+    console.log(`   Saved to: playbooks/flight-assistant.json`);
+
+    console.log("\n✈️  Thanks for using ACE Flight Assistant!");
+    console.log("   Your preferences are saved for next time.\n");
+
+  } catch (error: any) {
+    console.error("\n❌ Error:", error.message);
+    console.log("\nTroubleshooting:");
+    console.log("• Ensure OPENAI_API_KEY is set");
+    console.log("• For MCP: https://github.com/opspawn/Google-Flights-MCP-Server");
+  } finally {
+    crew.cleanupOldExecutions(60000);
+    crew.destroy();
+    rl.close();
+  }
+}
+
+// --- 4. Run ---
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/examples/telemetry-demo.ts

@@ -111,7 +111,6 @@ async function main() {
   const crew = new AxCrew(
     crewConfig,
     AxCrewFunctions,
-    undefined, // Use default crewId
     {
       telemetry: {
         tracer,

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "Build and launch a crew of AI agents with shared state. Built with axllm.dev",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plan.md

@@ -0,0 +1,255 @@
+# Integrate AxACE into Ax-Crew (per-agent)
+
+### Scope
+
+- Add optional AxACE support to `StatefulAxAgent` so each agent can: (a) run offline compile with examples + metric, (b) apply online updates with feedback, and (c) persist playbooks in memory or to file/DB. Reference: [ACE docs](https://axllm.dev/ace/).
+- Add simple execution tracking at crew level for intelligent feedback routing across agent dependency chains.
+
+### Key Design
+
+- **Per-agent playbooks**: stored in-memory, optionally persisted via path or callback.
+- **Student/Teacher AIs**: default student = agent's existing `AxAI`; teacher configured per agent (provider + model) or default to student.
+- **Non-breaking**: all ACE fields are optional; no behavior changes unless enabled.
+- **Execution tracking for feedback routing**: Simple in-memory tracking of agent involvement in task execution, enabling feedback distribution across agent dependency chains.
+
+### Architecture Clarification
+
+**OpenTelemetry Telemetry** (observability) and **ACE Feedback Routing** (execution tracking) are **separate concerns**:
+
+| Feature | Purpose | Where Configured |
+|---------|---------|------------------|
+| **Telemetry** | Observability, tracing, metrics | `AxAI` options via `AxCrewOptions.telemetry` |
+| **Execution Tracking** | Track which agents handled a task for ACE feedback | `AxCrew.executionHistory` in-memory Map |
+
+Telemetry is an `AxAI` feature (not `AxAgent`). The Ax framework automatically creates OpenTelemetry spans for all LLM operations when `tracer`/`meter` are passed to `AxAI`.
+
+### Files to Update/Add
+
+- Update `src/types.ts`: add `ACEConfig` and optional `ace?: ACEConfig` to `AgentConfig`. ✅ Done
+- **Add `src/agents/ace.ts`**: helper to build optimizer using real `AxACE` from `@ax-llm/ax`, load/save playbooks, run offline/online flows.
+- Update `src/agents/index.ts` (`StatefulAxAgent`): hold `aceConfig`, optional `aceOptimizer`, and methods: `initACE()`, `optimizeOffline(...)`, `applyOnlineUpdate(...)`, `getPlaybook()`, `applyPlaybook(...)`.
+- Update `src/agents/index.ts` (`AxCrew`): add `executionHistory` Map for tracking agent involvement, `applyTaskFeedback()` for routing.
+- Update `src/agents/agentConfig.ts`: parse `ace` block; optionally load initial playbook and pass into agent. ✅ Telemetry already correctly passed to `AxAI`.
+- Add `examples/ace-feedback-routing.ts`: demonstrates execution-based feedback routing across agent dependency chains.
+
+### New Types (in src/types.ts) ✅ Already Implemented
+
+```ts
+export interface ACETeacherConfig {
+  provider?: Provider;
+  providerKeyName?: string;
+  apiURL?: string;
+  ai?: AxModelConfig & { model: string };
+  providerArgs?: Record<string, unknown>;
+}
+
+export interface ACEPersistenceConfig {
+  playbookPath?: string;
+  initialPlaybook?: Record<string, any>;
+  autoPersist?: boolean;
+  onPersist?: (pb: any) => Promise<void> | void;
+  onLoad?: () => Promise<any> | any;
+}
+
+export interface ACEOptionsConfig {
+  maxEpochs?: number;
+  allowDynamicSections?: boolean;
+  tokenBudget?: number;
+  reflectorPrompt?: string;
+  curatorPrompt?: string;
+}
+
+export interface ACEMetricConfig {
+  metricFnName?: string;
+  primaryOutputField?: string;
+}
+
+export interface ACEConfig {
+  teacher?: ACETeacherConfig;
+  persistence?: ACEPersistenceConfig;
+  options?: ACEOptionsConfig;
+  metric?: ACEMetricConfig;
+  compileOnStart?: boolean;
+}
+```
+
+### Helper Module (src/agents/ace.ts)
+
+```ts
+import { AxACE, type AxMetricFn } from "@ax-llm/ax";
+import { ai as buildAI } from "@ax-llm/ax";
+import type { ACEConfig, ACEPersistenceConfig, ACEMetricConfig, FunctionRegistryType } from "../types.js";
+import type { StatefulAxAgent } from "./index.js";
+
+// Build AxACE optimizer with student (agent's AI) and optional teacher
+export function buildACEOptimizer(
+  studentAI: any,
+  cfg: ACEConfig
+): AxACE {
+  const teacherAI = buildTeacherAI(cfg.teacher, studentAI);
+  return new AxACE(
+    { studentAI, teacherAI, verbose: cfg.options?.maxEpochs ? true : false },
+    {
+      maxEpochs: cfg.options?.maxEpochs,
+      allowDynamicSections: cfg.options?.allowDynamicSections,
+      initialPlaybook: cfg.persistence?.initialPlaybook
+    }
+  );
+}
+
+// Load playbook from file or callback
+export async function loadInitialPlaybook(cfg?: ACEPersistenceConfig): Promise<any | undefined> { /*...*/ }
+
+// Persist playbook to file or callback
+export async function persistPlaybook(pb: any, cfg?: ACEPersistenceConfig): Promise<void> { /*...*/ }
+
+// Resolve metric function from registry or create equality metric
+export function resolveMetric(cfg: ACEMetricConfig | undefined, registry: FunctionRegistryType): AxMetricFn | undefined { /*...*/ }
+
+// Run offline compile
+export async function runOfflineCompile(args: {
+  program: any;
+  optimizer: AxACE;
+  metric: AxMetricFn;
+  examples: any[];
+  persistence?: ACEPersistenceConfig;
+}): Promise<any> { /*...*/ }
+
+// Run online update
+export async function runOnlineUpdate(args: {
+  optimizer: AxACE;
+  example: any;
+  prediction: any;
+  feedback?: string;
+  persistence?: ACEPersistenceConfig;
+}): Promise<any> { /*...*/ }
+```
+
+### Agent Class Changes (minimal API)
+
+```ts
+class StatefulAxAgent extends AxAgent<any, any> {
+  private aceConfig?: ACEConfig;
+  private aceOptimizer?: AxACE;
+  private acePlaybook?: any;
+
+  async initACE(ace?: ACEConfig): Promise<void> { /* build optimizer, load playbook */ }
+  async optimizeOffline(params?: { metric?: AxMetricFn; examples?: any[] }): Promise<void> { /* compile, persist */ }
+  async applyOnlineUpdate(params: { example: any; prediction: any; feedback?: string }): Promise<void> { /* update + persist */ }
+  getPlaybook(): any | undefined { return this.acePlaybook; }
+  applyPlaybook(pb: any): void { /* apply to optimizer */ }
+}
+```
+
+**Note**: No telemetry fields in agent - telemetry is handled by `AxAI`.
+
+### Crew-Level Execution Tracking for Feedback Routing
+
+**Problem Solved**: "How does the crew know which agent to pass online feedback to?"
+
+**Solution**: Simple in-memory execution history (not OpenTelemetry - that's for observability):
+
+```ts
+class AxCrew {
+  // Track agent execution for ACE feedback routing
+  private executionHistory: Map<string, {
+    taskId: string;
+    rootAgent: string;
+    involvedAgents: Set<string>;
+    taskInput: any;
+    results: Map<string, any>;
+    startTime: number;
+    endTime?: number;
+  }> = new Map();
+
+  // Track agent involvement during execution
+  trackAgentExecution(taskId: string, agentName: string, input: any): void { /*...*/ }
+  recordAgentResult(taskId: string, agentName: string, result: any): void { /*...*/ }
+
+  // Get involvement info for feedback routing
+  getTaskAgentInvolvement(taskId: string): AgentInvolvement | null { /*...*/ }
+
+  // Route feedback to involved agents
+  async applyTaskFeedback(params: {
+    taskId: string;
+    feedback: string;
+    strategy?: 'all' | 'primary' | 'weighted';
+  }): Promise<void> { /*...*/ }
+
+  // Cleanup old entries
+  cleanupOldExecutions(maxAgeMs?: number): void { /*...*/ }
+}
+```
+
+### Agent Config Parsing
+
+In `parseAgentConfig(...)`:
+- Telemetry (`tracer`, `meter`) is passed to `AxAI` options ✅ Already implemented
+- If `agentConfigData.ace` is present, the agent's `initACE()` is called during creation
+- If `compileOnStart` and a usable metric is available, run offline compile with `examples`
+
+### Minimal Usage
+
+```ts
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "writer",
+      description: "Writes articles",
+      signature: "topic:string -> article:string",
+      provider: "openai",
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o-mini" },
+      ace: {
+        enabled: true,
+        teacher: { provider: "openai", providerKeyName: "OPENAI_API_KEY", ai: { model: "gpt-4o" } },
+        options: { maxEpochs: 1, allowDynamicSections: true },
+        persistence: { playbookPath: "playbooks/writer.json", autoPersist: true },
+        metric: { primaryOutputField: "article" },
+        compileOnStart: false,
+      },
+    },
+  ],
+};
+
+// Initialize crew (telemetry is for observability, separate from ACE)
+const crew = new AxCrew(config, AxCrewFunctions, {
+  telemetry: { tracer, meter }  // Optional: for OpenTelemetry observability
+});
+
+await crew.addAgentsToCrew(["writer"]);
+const writer = crew.agents?.get("writer");
+
+// Manual per-agent ACE operations
+await writer?.optimizeOffline();
+const prediction = await writer?.forward({ topic: "Quantum" });
+await writer?.applyOnlineUpdate({ 
+  example: { topic: "Quantum" }, 
+  prediction, 
+  feedback: "Too verbose." 
+});
+
+// Crew-level feedback routing (for multi-agent tasks)
+// The forward() call returns a taskId that can be used for feedback
+const result = await writer.forward({ topic: "AI Ethics" });
+await crew.applyTaskFeedback({
+  taskId: result._taskId,  // Returned by forward()
+  feedback: "More balanced perspective needed",
+  strategy: "all"  // Route to all involved agents
+});
+```
+
+### Benefits
+
+- **Separation of Concerns**: Telemetry (observability) vs Execution Tracking (ACE feedback)
+- **Zero Breaking Changes**: All ACE features are opt-in
+- **Uses Real AxACE**: Imports actual `AxACE` class from `@ax-llm/ax`
+- **Simple Feedback Routing**: In-memory tracking without OpenTelemetry dependency
+- **Flexible**: Supports per-agent and crew-level feedback
+
+### Notes
+
+- Persistence is optional; in-memory playbooks work fine. Save to file/DB only if you want reuse after restarts.
+- Metric configuration is required for offline compile; online updates don't need a metric.
+- Defaults are conservative: ACE is only active when `ace` config is present.
+- Telemetry and ACE are independent features - you can use one without the other.

package/playbooks/customer-support.json

@@ -0,0 +1,32 @@
+{
+  "sections": {
+    "Guidelines": [
+      {
+        "id": "guidel-9507499a",
+        "section": "Guidelines",
+        "content": "For returning customers who have spent $15000 over 8 years, exercise compassion and allow a refund.",
+        "helpfulCount": 1,
+        "harmfulCount": 0,
+        "createdAt": "2026-01-13T13:07:18.958Z",
+        "updatedAt": "2026-01-13T13:07:18.958Z"
+      },
+      {
+        "id": "guidel-8b3abea4",
+        "section": "Guidelines",
+        "content": "Always refund orders that have incurred shipping damage.",
+        "helpfulCount": 1,
+        "harmfulCount": 0,
+        "createdAt": "2026-01-17T10:00:30.736Z",
+        "updatedAt": "2026-01-17T10:00:30.736Z"
+      }
+    ]
+  },
+  "createdAt": null,
+  "updatedAt": "2026-01-17T10:00:30.736Z",
+  "stats": {
+    "bulletCount": 2,
+    "helpfulCount": 2,
+    "harmfulCount": 0,
+    "tokenEstimate": 39
+  }
+}

package/playbooks/flight-assistant.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "sections": {
+    "Guidelines": [
+      {
+        "id": "guidel-541925c9",
+        "section": "Guidelines",
+        "content": "Only show non-stop flights in the search results.",
+        "helpfulCount": 1,
+        "harmfulCount": 0,
+        "createdAt": "2025-12-30T03:44:39.741Z",
+        "updatedAt": "2025-12-30T03:44:39.741Z"
+      }
+    ]
+  },
+  "stats": {
+    "bulletCount": 1,
+    "helpfulCount": 1,
+    "harmfulCount": 0,
+    "tokenEstimate": 13
+  },
+  "updatedAt": "2025-12-30T03:44:39.743Z"
+}