@falai/agent 0.1.4 → 0.1.5

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,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

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;
   }
 

package/src/core/Route.ts

@@ -6,8 +6,7 @@ import type { RouteOptions, RouteRef } from "../types/route";
 import type { Guideline } from "../types/agent";
 
 import { State } from "./State";
-
-let routeIdCounter = 0;
+import { generateRouteId } from "../utils/id";
 
 /**
  * Represents a conversational route/journey
@@ -21,9 +20,8 @@ export class Route<TContext = unknown> {
   private guidelines: Guideline[] = [];
 
   constructor(options: RouteOptions) {
-    this.id = `route_${++routeIdCounter}_${options.title
-      .toLowerCase()
-      .replace(/\s+/g, "_")}`;
+    // Use provided ID or generate a deterministic one from the title
+    this.id = options.id || generateRouteId(options.title);
     this.title = options.title;
     this.description = options.description;
     this.conditions = options.conditions || [];

package/src/core/State.ts

@@ -11,8 +11,7 @@ import type { Guideline } from "../types/agent";
 
 import { END_ROUTE } from "../constants";
 import { Transition } from "./Transition";
-
-let stateIdCounter = 0;
+import { generateStateId } from "../utils/id";
 
 /**
  * Represents a state within a route
@@ -24,9 +23,11 @@ export class State<TContext = unknown> {
 
   constructor(
     public readonly routeId: string,
-    public readonly description?: string
+    public readonly description?: string,
+    customId?: string
   ) {
-    this.id = `state_${++stateIdCounter}`;
+    // Use provided ID or generate a deterministic one
+    this.id = customId || generateStateId(routeId, description);
   }
 
   /**

package/src/core/Tool.ts

@@ -8,8 +8,7 @@ import type {
   ToolRef,
   ToolResult,
 } from "../types/tool";
-
-let toolIdCounter = 0;
+import { generateToolId } from "../utils/id";
 
 /**
  * Define a new tool with type-safe context and arguments
@@ -33,11 +32,13 @@ export function defineTool<TContext, TArgs extends unknown[], TResult>(
   name: string,
   handler: ToolHandler<TContext, TArgs, TResult>,
   options?: {
+    id?: string;
     description?: string;
     parameters?: unknown;
   }
 ): ToolRef<TContext, TArgs, TResult> {
-  const id = `tool_${++toolIdCounter}_${name}`;
+  // Use provided ID or generate a deterministic one from the name
+  const id = options?.id || generateToolId(name);
 
   return {
     id,

package/src/index.ts

@@ -28,6 +28,14 @@ export type { OpenRouterProviderOptions } from "./providers/OpenRouterProvider";
 // Constants
 export { END_ROUTE } from "./constants";
 
+// Utils
+export {
+  generateRouteId,
+  generateStateId,
+  generateObservationId,
+  generateToolId,
+} from "./utils/id";
+
 // Types
 export type {
   AgentOptions,

package/src/types/agent.ts

@@ -82,7 +82,8 @@ export interface Guideline {
   /** Tags for organizing and filtering guidelines */
   tags?: string[];
   /** Tools available when following this guideline */
-  tools?: ToolRef<unknown, unknown[], unknown>[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tools?: ToolRef<any, any[], any>[];
   /** Additional metadata */
   metadata?: Record<string, unknown>;
 }
@@ -98,7 +99,8 @@ export interface Capability {
   /** Description of what the capability does */
   description: string;
   /** Tools used by this capability */
-  tools?: ToolRef<unknown, unknown[], unknown>[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tools?: ToolRef<any, any[], any>[];
 }
 
 /**

package/src/types/observation.ts

@@ -20,6 +20,8 @@ export interface Observation {
  * Options for creating an observation
  */
 export interface ObservationOptions {
+  /** Custom ID for the observation (optional - will generate deterministic ID from description if not provided) */
+  id?: string;
   /** The observation description */
   description: string;
   /** Route IDs or titles to disambiguate between (can be set later with disambiguate()) */

package/src/types/route.ts

@@ -31,6 +31,8 @@ import type { Guideline } from "./agent";
  * Options for creating a route
  */
 export interface RouteOptions {
+  /** Custom ID for the route (optional - will generate deterministic ID from title if not provided) */
+  id?: string;
   /** Title of the route */
   title: string;
   /** Description of what this route accomplishes */

package/src/utils/id.ts

@@ -0,0 +1,74 @@
+/**
+ * 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: string): string {
+  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: string): string {
+  return str.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+}
+
+/**
+ * Generate a deterministic route ID
+ * Format: route_{sanitized_title}_{hash}
+ */
+export function generateRouteId(title: string): string {
+  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: string,
+  description?: string,
+  index?: number
+): string {
+  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: string): string {
+  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: string): string {
+  const sanitized = sanitize(name);
+  const hash = simpleHash(name);
+  return `tool_${sanitized}_${hash}`;
+}