@falai/agent 0.1.3 → 0.1.5

package/dist/utils/id.js

@@ -0,0 +1,65 @@
+/**
+ * ID generation utilities
+ * Provides deterministic ID generation to ensure consistency across server restarts
+ */
+/**
+ * Generate a deterministic ID from a string by creating a simple hash
+ * This ensures the same input always produces the same ID
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Sanitize a string for use in an ID
+ */
+function sanitize(str) {
+    return str.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+}
+/**
+ * Generate a deterministic route ID
+ * Format: route_{sanitized_title}_{hash}
+ */
+export function generateRouteId(title) {
+    const sanitized = sanitize(title);
+    const hash = simpleHash(title);
+    return `route_${sanitized}_${hash}`;
+}
+/**
+ * Generate a deterministic state ID
+ * Format: state_{sanitized_description}_{hash} or state_{routeId}_{index}
+ */
+export function generateStateId(routeId, description, index) {
+    if (description) {
+        const sanitized = sanitize(description);
+        const hash = simpleHash(`${routeId}_${description}`);
+        return `state_${sanitized}_${hash}`;
+    }
+    // Fallback for states without descriptions
+    const suffix = index !== undefined ? index : simpleHash(routeId);
+    return `state_${routeId}_${suffix}`;
+}
+/**
+ * Generate a deterministic observation ID
+ * Format: observation_{sanitized_description}_{hash}
+ */
+export function generateObservationId(description) {
+    const sanitized = sanitize(description.substring(0, 50)); // Limit length
+    const hash = simpleHash(description);
+    return `observation_${sanitized}_${hash}`;
+}
+/**
+ * Generate a deterministic tool ID
+ * Format: tool_{sanitized_name}_{hash}
+ */
+export function generateToolId(name) {
+    const sanitized = sanitize(name);
+    const hash = simpleHash(name);
+    return `tool_${sanitized}_${hash}`;
+}
+//# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;QACjC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,4BAA4B;IAClD,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,GAAW;IAC3B,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO,SAAS,SAAS,IAAI,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,WAAoB,EACpB,KAAc;IAEd,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,OAAO,IAAI,WAAW,EAAE,CAAC,CAAC;QACrD,OAAO,SAAS,SAAS,IAAI,IAAI,EAAE,CAAC;IACtC,CAAC;IACD,2CAA2C;IAC3C,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACjE,OAAO,SAAS,OAAO,IAAI,MAAM,EAAE,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,eAAe;IACzE,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACrC,OAAO,eAAe,SAAS,IAAI,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,QAAQ,SAAS,IAAI,IAAI,EAAE,CAAC;AACrC,CAAC"}

package/docs/API_REFERENCE.md

@@ -129,8 +129,18 @@ Represents a conversation flow with states and transitions.
 
 ```typescript
 new Route(options: RouteOptions)
+
+interface RouteOptions {
+  id?: string;              // Optional custom ID (deterministic ID generated from title if not provided)
+  title: string;            // Route title
+  description?: string;     // Route description
+  conditions?: string[];    // Conditions that activate this route
+  guidelines?: Guideline[]; // Initial guidelines for this route
+}
 ```
 
+**Note on IDs:** Route IDs are deterministic by default, generated from the title using a hash function. This ensures consistency across server restarts. You can provide a custom ID if you need specific control over the identifier.
+
 #### Methods
 
 ##### `createGuideline(guideline: Guideline): this`
@@ -223,8 +233,16 @@ Handles disambiguation between multiple routes.
 
 ```typescript
 new Observation(options: ObservationOptions)
+
+interface ObservationOptions {
+  id?: string;          // Optional custom ID (deterministic ID generated from description if not provided)
+  description: string;  // The observation description
+  routeRefs?: string[]; // Route IDs or titles to disambiguate between
+}
 ```
 
+**Note on IDs:** Observation IDs are deterministic by default, generated from the description using a hash function. This ensures consistency across server restarts.
+
 #### Methods
 
 ##### `disambiguate(routes: (Route | RouteRef)[]): this`
@@ -326,12 +344,15 @@ defineTool<TContext, TArgs extends unknown[], TReturn>(
   name: string,
   handler: ToolHandler<TContext, TArgs, TReturn>,
   options?: {
+    id?: string;              // Optional custom ID (deterministic ID generated from name if not provided)
     description?: string;
-    metadata?: Record<string, unknown>;
+    parameters?: unknown;
   }
 ): ToolRef<TContext, TArgs, TReturn>
 ```
 
+**Note on IDs:** Tool IDs are deterministic by default, generated from the name using a hash function. This ensures consistency across server restarts.
+
 **Example:**
 
 ```typescript
@@ -340,7 +361,10 @@ const getTool = defineTool<MyContext, [id: string], Data>(
   async ({ context }, id) => {
     return { data: await fetchData(id) };
   },
-  { description: "Fetches data by ID" }
+  {
+    id: "custom_get_data_tool", // Optional: provide your own ID
+    description: "Fetches data by ID",
+  }
 );
 ```
 
@@ -353,11 +377,27 @@ Creates a message event for conversation history.
 ```typescript
 createMessageEvent(
   source: EventSource,
-  name: string,
-  message: string
+  participantName: string,
+  message: string,
+  timestamp?: string  // Optional: provide custom timestamp (ISO 8601 format)
 ): Event
 ```
 
+**Example:**
+
+```typescript
+// With auto-generated timestamp
+createMessageEvent(EventSource.CUSTOMER, "Alice", "Hello!");
+
+// With custom timestamp (useful for historical data)
+createMessageEvent(
+  EventSource.CUSTOMER,
+  "Alice",
+  "Hello!",
+  "2025-10-13T10:30:00Z"
+);
+```
+
 ---
 
 ### `createToolEvent()`
@@ -366,11 +406,28 @@ Creates a tool execution event.
 
 ```typescript
 createToolEvent(
-  toolName: string,
-  data: unknown
+  source: EventSource,
+  toolCalls: ToolCall[],
+  timestamp?: string  // Optional: provide custom timestamp (ISO 8601 format)
 ): Event
 ```
 
+**Example:**
+
+```typescript
+// With auto-generated timestamp
+createToolEvent(EventSource.AI_AGENT, [
+  { tool_id: "get_data", arguments: { id: "123" }, result: { data: {...} } }
+]);
+
+// With custom timestamp
+createToolEvent(
+  EventSource.AI_AGENT,
+  [{ tool_id: "get_data", arguments: { id: "123" }, result: { data: {...} } }],
+  "2025-10-13T10:30:00Z"
+);
+```
+
 ---
 
 ### `adaptEvent()`
@@ -501,6 +558,65 @@ This type represents the structured JSON output that AI providers return when us
 
 ---
 
+### ID Generation Utilities
+
+Generate deterministic IDs for consistency across server restarts.
+
+#### `generateRouteId(title: string): string`
+
+Generates a deterministic route ID from a title.
+
+```typescript
+import { generateRouteId } from "@falai/agent";
+
+const routeId = generateRouteId("User Onboarding");
+// Returns: "route_user_onboarding_{hash}"
+```
+
+#### `generateStateId(routeId: string, description?: string, index?: number): string`
+
+Generates a deterministic state ID.
+
+```typescript
+import { generateStateId } from "@falai/agent";
+
+const stateId = generateStateId("route_123", "Ask for name");
+// Returns: "state_ask_for_name_{hash}"
+```
+
+#### `generateObservationId(description: string): string`
+
+Generates a deterministic observation ID from a description.
+
+```typescript
+import { generateObservationId } from "@falai/agent";
+
+const obsId = generateObservationId("User intent is unclear");
+// Returns: "observation_user_intent_is_unclear_{hash}"
+```
+
+#### `generateToolId(name: string): string`
+
+Generates a deterministic tool ID from a name.
+
+```typescript
+import { generateToolId } from "@falai/agent";
+
+const toolId = generateToolId("get_user_data");
+// Returns: "tool_get_user_data_{hash}"
+```
+
+**Why Deterministic IDs?**
+
+All IDs are generated deterministically using a hash function of their content (title, name, description). This ensures:
+
+- **Consistency** - Same input always produces the same ID
+- **Server Restart Safe** - IDs remain stable across application restarts
+- **Persistence Friendly** - Safe to store in databases and reference later
+- **Custom Control** - You can always provide your own IDs when needed
+
+---
+
 ## Constants
 
 ### `END_ROUTE`

package/docs/CONSTRUCTOR_OPTIONS.md

@@ -18,16 +18,16 @@ interface AgentOptions<TContext = unknown> {
   // Required
   name: string;
   ai: AiProvider;
-  
+
   // Optional metadata
   description?: string;
   goal?: string;
   context?: TContext;
-  
+
   // Configuration
   maxEngineIterations?: number;
   compositionMode?: CompositionMode;
-  
+
   // Declarative initialization (NEW!)
   terms?: Term[];
   guidelines?: Guideline[];
@@ -44,43 +44,47 @@ const agent = new Agent({
   name: "SupportBot",
   description: "Helpful customer support",
   goal: "Resolve issues efficiently",
-  ai: new GeminiProvider({ apiKey: "..." }),
+  ai: new GeminiProvider({ apiKey: "...", model: "..." }),
   context: { userId: "123" },
-  
+
   terms: [
-    { name: "SLA", description: "Service Level Agreement", synonyms: ["response time"] }
+    {
+      name: "SLA",
+      description: "Service Level Agreement",
+      synonyms: ["response time"],
+    },
   ],
-  
+
   guidelines: [
     {
       condition: "User is frustrated",
       action: "Show empathy and offer escalation",
       tags: ["support"],
-      enabled: true
-    }
+      enabled: true,
+    },
   ],
-  
+
   capabilities: [
-    { title: "Ticket Management", description: "Create and track tickets" }
+    { title: "Ticket Management", description: "Create and track tickets" },
   ],
-  
+
   routes: [
     {
       title: "Create Ticket",
       description: "Help user create a support ticket",
       conditions: ["User wants to report an issue"],
       guidelines: [
-        { condition: "Issue is urgent", action: "Prioritize immediately" }
-      ]
-    }
+        { condition: "Issue is urgent", action: "Prioritize immediately" },
+      ],
+    },
   ],
-  
+
   observations: [
     {
       description: "User mentions problem but unclear what kind",
-      routeRefs: ["Create Ticket", "Check Ticket Status"] // By title!
-    }
-  ]
+      routeRefs: ["Create Ticket", "Check Ticket Status"], // By title!
+    },
+  ],
 });
 ```
 
@@ -92,7 +96,7 @@ const agent = new Agent({
 interface RouteOptions {
   // Required
   title: string;
-  
+
   // Optional
   description?: string;
   conditions?: string[];
@@ -115,16 +119,16 @@ const agent = new Agent({
         {
           condition: "User skips a step",
           action: "Gently remind them it's important",
-          tags: ["onboarding"]
+          tags: ["onboarding"],
         },
         {
           condition: "User seems confused",
           action: "Offer a quick tutorial video",
-          tags: ["help"]
-        }
-      ]
-    }
-  ]
+          tags: ["help"],
+        },
+      ],
+    },
+  ],
 });
 ```
 
@@ -187,18 +191,21 @@ obs.disambiguate([route1, route2]);
 ## 🎨 Best Practices
 
 ### Use Declarative When:
+
 - ✅ Configuration is **static** and known upfront
 - ✅ Loading config from **JSON/YAML files**
 - ✅ Building **reusable agent templates**
 - ✅ You want **clean, readable initialization**
 
 ### Use Fluent When:
+
 - ✅ Logic is **dynamic** or **conditional**
 - ✅ Building routes with **complex state machines**
 - ✅ Adding features **based on runtime conditions**
 - ✅ You prefer **step-by-step construction**
 
 ### Mix Both!
+
 ```typescript
 // Start with static config
 const agent = new Agent({
@@ -212,7 +219,7 @@ const agent = new Agent({
 if (user.isPremium) {
   agent.createGuideline({
     condition: "User asks for priority support",
-    action: "Escalate immediately to premium team"
+    action: "Escalate immediately to premium team",
   });
 }
 ```
@@ -221,15 +228,15 @@ if (user.isPremium) {
 
 ## 📊 Complete Comparison
 
-| Feature | Declarative (Constructor) | Fluent (Methods) |
-|---------|--------------------------|------------------|
-| **Terms** | `terms: Term[]` | `agent.createTerm(...)` |
-| **Guidelines** | `guidelines: Guideline[]` | `agent.createGuideline(...)` |
-| **Capabilities** | `capabilities: Capability[]` | `agent.createCapability(...)` |
-| **Routes** | `routes: RouteOptions[]` | `agent.createRoute(...)` |
-| **Route Guidelines** | `route.guidelines: Guideline[]` | `route.createGuideline(...)` |
-| **Observations** | `observations: ObservationOptions[]` | `agent.createObservation(...)` |
-| **Disambiguation** | `routeRefs: string[]` | `obs.disambiguate([...])` |
+| Feature              | Declarative (Constructor)            | Fluent (Methods)               |
+| -------------------- | ------------------------------------ | ------------------------------ |
+| **Terms**            | `terms: Term[]`                      | `agent.createTerm(...)`        |
+| **Guidelines**       | `guidelines: Guideline[]`            | `agent.createGuideline(...)`   |
+| **Capabilities**     | `capabilities: Capability[]`         | `agent.createCapability(...)`  |
+| **Routes**           | `routes: RouteOptions[]`             | `agent.createRoute(...)`       |
+| **Route Guidelines** | `route.guidelines: Guideline[]`      | `route.createGuideline(...)`   |
+| **Observations**     | `observations: ObservationOptions[]` | `agent.createObservation(...)` |
+| **Disambiguation**   | `routeRefs: string[]`                | `obs.disambiguate([...])`      |
 
 ---
 

package/docs/GETTING_STARTED.md

@@ -58,6 +58,7 @@ interface MyContext {
 // Create AI provider
 const ai = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-pro",
 });
 
 // Create your agent
@@ -307,6 +308,7 @@ Increase timeout in provider config:
 ```typescript
 new GeminiProvider({
   apiKey: "...",
+  model: "models/gemini-2.5-flash",
   retryConfig: {
     timeout: 120000, // 2 minutes
     retries: 5,

package/docs/PROVIDERS.md

@@ -281,6 +281,7 @@ const geminiAgent = new Agent({
   name: "Gemini Assistant",
   ai: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
+    model: "models/gemini-2.5-flash",
   }),
 });
 
@@ -315,10 +316,12 @@ config();
 
 const geminiProvider = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-flash",
 });
 
 const openaiProvider = new OpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5",
 });
 ```
 

package/examples/declarative-agent.ts

@@ -6,8 +6,9 @@
  * - Terms (glossary)
  * - Guidelines (behavior rules)
  * - Capabilities
- * - Routes with nested guidelines
- * - Observations with route references
+ * - Routes with nested guidelines and custom IDs
+ * - Observations with route references and custom IDs
+ * - Custom timestamps for events
  */
 
 import {
@@ -29,13 +30,16 @@ interface HealthcareContext {
   patientName: string;
 }
 
-// Define tools
+// Define tools with custom IDs (optional - IDs are deterministic by default)
 const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>(
   "get_insurance_providers",
   async () => {
     return { data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"] };
   },
-  { description: "Retrieves list of accepted insurance providers" }
+  {
+    id: "healthcare_insurance_providers", // Custom ID for persistence
+    description: "Retrieves list of accepted insurance providers",
+  }
 );
 
 const getAvailableSlots = defineTool<
@@ -53,7 +57,10 @@ const getAvailableSlots = defineTool<
       ],
     };
   },
-  { description: "Gets available appointment slots" }
+  {
+    id: "healthcare_available_slots", // Custom ID
+    description: "Gets available appointment slots",
+  }
 );
 
 const getLabResults = defineTool<
@@ -70,7 +77,10 @@ const getLabResults = defineTool<
       },
     };
   },
-  { description: "Retrieves patient lab results" }
+  {
+    id: "healthcare_lab_results", // Custom ID
+    description: "Retrieves patient lab results",
+  }
 );
 
 // Declarative configuration
@@ -126,6 +136,7 @@ const capabilities: Capability[] = [
 
 const routes: RouteOptions[] = [
   {
+    id: "route_schedule_appointment", // Custom ID ensures consistency across restarts
     title: "Schedule Appointment",
     description: "Helps the patient schedule an appointment",
     conditions: ["The patient wants to schedule an appointment"],
@@ -139,6 +150,7 @@ const routes: RouteOptions[] = [
     ],
   },
   {
+    id: "route_check_lab_results", // Custom ID
     title: "Check Lab Results",
     description: "Retrieves and explains patient lab results",
     conditions: ["The patient wants to see their lab results"],
@@ -155,6 +167,7 @@ const routes: RouteOptions[] = [
 
 const observations: ObservationOptions[] = [
   {
+    id: "obs_visit_followup", // Custom ID for tracking
     description:
       "The patient asks to follow up on their visit, but it's not clear in which way",
     routeRefs: ["Schedule Appointment", "Check Lab Results"], // Reference by title
@@ -172,6 +185,7 @@ const agent = new Agent<HealthcareContext>({
   },
   ai: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY || "demo-key",
+    model: "models/gemini-2.5-flash",
   }),
   // Declarative initialization
   terms,
@@ -196,19 +210,29 @@ agent
 
 // Example usage
 async function main() {
+  // Create events with custom timestamps (useful for historical data)
   const history = [
     createMessageEvent(
       EventSource.CUSTOMER,
       "Alice",
-      "Hi, I need to follow up on my recent visit"
+      "Hi, I need to follow up on my recent visit",
+      "2025-10-13T14:30:00Z" // Optional custom timestamp
     ),
   ];
 
   const response = await agent.respond({ history });
   console.log("Agent:", response.message);
+  console.log("Route chosen:", response.route?.title);
+  console.log("Route ID:", response.route?.id); // Custom ID is preserved
 
   // The agent will use the observation to disambiguate
   // and ask which type of follow-up the patient needs
+
+  // Note: Custom IDs ensure consistency across server restarts
+  // This is crucial for:
+  // - Storing conversation state in databases
+  // - Tracking metrics and analytics
+  // - Referencing routes in external systems
 }
 
 // Uncomment to run:

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "@falai/agent",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "files": [
@@ -31,7 +38,10 @@
   },
   "homepage": "https://github.com/gusnips/falai#readme",
   "scripts": {
-    "build": "tsc",
+    "build": "npm run build:esm && npm run build:cjs && npm run fix:cjs",
+    "build:esm": "tsc",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "fix:cjs": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/**/*.ts",

package/src/core/Events.ts

@@ -70,7 +70,8 @@ export function adaptEvent(e: Event | EmittedEvent): string {
 export function createMessageEvent(
   source: EventSource,
   participantName: string,
-  message: string
+  message: string,
+  timestamp?: string
 ): Event<MessageEventData> {
   return {
     kind: EventKind.MESSAGE,
@@ -79,7 +80,7 @@ export function createMessageEvent(
       participant: { display_name: participantName },
       message,
     },
-    timestamp: new Date().toISOString(),
+    timestamp: timestamp || new Date().toISOString(),
   };
 }
 
@@ -88,7 +89,8 @@ export function createMessageEvent(
  */
 export function createToolEvent(
   source: EventSource,
-  toolCalls: ToolCall[]
+  toolCalls: ToolCall[],
+  timestamp?: string
 ): Event<ToolEventData> {
   return {
     kind: EventKind.TOOL,
@@ -96,6 +98,6 @@ export function createToolEvent(
     data: {
       tool_calls: toolCalls,
     },
-    timestamp: new Date().toISOString(),
+    timestamp: timestamp || new Date().toISOString(),
   };
 }

package/src/core/Observation.ts

@@ -8,8 +8,7 @@ import type {
 } from "../types/observation";
 import type { RouteRef } from "../types/route";
 import type { Route } from "./Route";
-
-let observationIdCounter = 0;
+import { generateObservationId } from "../utils/id";
 
 /**
  * An observation that can trigger disambiguation between routes
@@ -20,7 +19,8 @@ export class Observation implements IObservation {
   public routes: RouteRef[] = [];
 
   constructor(options: ObservationOptions) {
-    this.id = `observation_${++observationIdCounter}`;
+    // Use provided ID or generate a deterministic one from the description
+    this.id = options.id || generateObservationId(options.description);
     this.description = options.description;
   }