@falai/agent 1.0.1 → 1.0.2

package/docs/api/README.md

@@ -9,7 +9,7 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
 - **[AI Routing System](../core/routing/intelligent-routing.md)** - Intelligent route and step selection
 - **[Route DSL](../core/conversation-flows/route-dsl.md)** - Declarative conversation flow design
 - **[Data Collection](../core/conversation-flows/data-collection.md)** - Schema-driven data extraction
-- **[Tool Execution](../core/tools/tool-execution.md)** - Dynamic tool calling and context updates
+- **[Tool Definition](../core/tools/tool-definition.md)** - Tool creation and configuration
 - **[Session Storage](../core/persistence/session-storage.md)** - Persistence and session management
 - **[AI Providers](../core/ai-integration/providers.md)** - Provider integrations and configuration
 
@@ -127,7 +127,7 @@ Main agent class for managing conversational AI with agent-level data collection
 new Agent<TContext, TData>(options: AgentOptions<TContext, TData>)
 ```
 
-See [Agent](./AGENT.md) for full details.
+See `AgentOptions` type definition for full details.
 
 #### Methods
 
@@ -632,7 +632,7 @@ return response.message;
 - If all steps are skipped (due to `skipIf` conditions), the route can complete immediately on entry
 - Use `agent.getData(session)` to retrieve all collected data
 
-See also: [Custom Database Integration Example](../examples/custom-database-persistence.ts)
+See also: [Database Integration Example](../../examples/integrations/database-integration.ts)
 
 ##### `respondStream(input: RespondInput<TContext>): AsyncGenerator<StreamChunk>`
 
@@ -808,7 +808,7 @@ await db.agentMessages.create({
 });
 ```
 
-**See Also:** [streaming-agent.ts](../examples/streaming-agent.ts) for comprehensive examples.
+**See Also:** [streaming-responses.ts](../../examples/advanced-patterns/streaming-responses.ts) for comprehensive examples.
 
 #### Properties
 
@@ -1461,7 +1461,7 @@ Route this step belongs to (readonly).
 
 Tools provide a powerful way to execute custom logic, access external APIs, and enrich conversation context before AI response generation.
 
-**See Also:** [TOOLS.md](./TOOLS.md) - Complete guide to tool execution, lifecycle, and best practices
+**See Also:** [Tool Definition](../core/tools/tool-definition.md) - Complete guide to tool creation and configuration
 
 ---
 
@@ -1642,7 +1642,7 @@ const provider = new OpenRouterProvider({
 });
 ```
 
-**See Also:** [Providers Guide](./PROVIDERS.md) for detailed provider comparison and configuration examples.
+**See Also:** [AI Providers](../core/ai-integration/providers.md) for detailed provider comparison and configuration examples.
 
 ---
 
@@ -1789,9 +1789,7 @@ Handles route and step selection logic for conversation orchestration.
 new RoutingEngine<TContext, TData>(options?: RoutingEngineOptions)
 
 interface RoutingEngineOptions {
-  allowRouteSwitch?: boolean;  // Default: true
-  switchThreshold?: number;    // Default: 70 (0-100)
-  maxCandidates?: number;      // Default: 5
+  routeSwitchMargin?: number;  // Default: 15 (0-100)
 }
 ```
 
@@ -1927,9 +1925,9 @@ const agent = new Agent({
 });
 ```
 
-**Schema Example:** See [examples/prisma-schema.example.prisma](../examples/prisma-schema.example.prisma)
+**Schema Example:** See [examples/prisma-schema.example.prisma](../../examples/persistence/prisma-schema.example.prisma)
 
-**Full Example:** See [examples/prisma-persistence.ts](../examples/prisma-persistence.ts)
+**Full Example:** See [examples/database-persistence.ts](../../examples/persistence/database-persistence.ts)
 
 ---
 
@@ -1972,7 +1970,7 @@ const agent = new Agent({
 
 **Install:** `npm install ioredis` or `npm install redis`
 
-**Full Example:** See [examples/redis-persistence.ts](../examples/redis-persistence.ts)
+**Full Example:** See [examples/redis-persistence.ts](../../examples/persistence/redis-persistence.ts)
 
 ---
 
@@ -2185,8 +2183,6 @@ const agent = new Agent({
 
 **Perfect for:** Full-text search, analytics, time-series analysis, AWS OpenSearch Service, Elasticsearch 7.x users
 
-**Full Example:** See [examples/opensearch-persistence.ts](../examples/opensearch-persistence.ts)
-
 ---
 
 ### `MemoryAdapter`
@@ -2310,8 +2306,8 @@ interface PersistenceAdapter {
 
 **See Also:**
 
-- [docs/PERSISTENCE.md](./PERSISTENCE.md) - Complete persistence guide
-- [docs/ADAPTERS.md](./ADAPTERS.md) - Adapter comparison and details
+- [Session Storage](../core/persistence/session-storage.md) - Session persistence patterns
+- [Database Adapters](../core/persistence/adapters.md) - Adapter comparison and details
 
 ---
 

package/docs/architecture/data-extraction-flow.md

@@ -360,4 +360,3 @@ This results in natural, efficient conversations that respect user time.
 **Next Steps:**
 - [Route Configuration](../core/conversation-flows/routes.md)
 - [Step Configuration](../core/conversation-flows/steps.md)
-- [Schema Design](../guides/building-agents/schema-design.md)

package/docs/core/agent/context-management.md

@@ -773,10 +773,10 @@ hooks: {
 
 ## 📚 Related Resources
 
-- [Complete Example: Persistent Onboarding](../examples/persistent-onboarding.ts)
-- [API Reference: AgentOptions](../api/overview.md#agentoptions)
-- [API Reference: ContextLifecycleHooks](../api/overview.md#contextlifecyclehooks)
-- [Getting Started](../guides/getting-started/README.md)
+- [Complete Example: Persistent Onboarding](../../../examples/advanced-patterns/persistent-onboarding.ts)
+- [API Reference: AgentOptions](../../api/overview.md#agentoptions)
+- [API Reference: ContextLifecycleHooks](../../api/overview.md#contextlifecyclehooks)
+- [Getting Started](../../guides/getting-started/README.md)
 
 ---
 
@@ -784,8 +784,8 @@ hooks: {
 
 If you're still having issues:
 
-1. Check the [examples](../examples/) for working implementations
-2. Review the [API Reference](../api/README.md) for detailed type information
+1. Check the [examples](../../../examples/) for working implementations
+2. Review the [API Reference](../../api/README.md) for detailed type information
 3. Open an issue on GitHub with your use case
 
 **Remember:** The key to persistent conversations is:

package/docs/core/agent/session-management.md

@@ -631,10 +631,9 @@ This framework draws inspiration from:
 
 ## Further Reading
 
-- [Getting Started Guide](../guides/getting-started/README.md) - Build your first agent
-- [Session Step Guide](./CONTEXT_MANAGEMENT.md) - Session management patterns
-- [API Reference](../api/README.md) - Complete API documentation
-- [Examples](../examples/) - Real-world implementations
+- [Getting Started Guide](../../guides/getting-started/README.md) - Build your first agent
+- [Context Management](./context-management.md) - Context providers and updates
+- [API Reference](../../api/README.md) - Complete API documentation
 
 ---
 

package/docs/core/routing/intelligent-routing.md

@@ -376,14 +376,19 @@ if (routes.length === 1) {
 }
 ```
 
-### Candidate Limiting
+### Sticky Route Switching
 
-Applies configurable limits to prevent excessive AI calls:
+When the agent is already on a route, it won't switch unless an alternative route scores higher by a configurable margin. This prevents flip-flopping on marginal score differences:
 
 ```typescript
-const limited = maxCandidates ? entries.slice(0, maxCandidates) : entries;
+const agent = new Agent({
+  // ...
+  routeSwitchMargin: 15, // default: 15, range 0-100
+});
 ```
 
+A margin of 15 means the best alternative must outscore the current route by at least 15 points before a switch occurs.
+
 ## Error Handling & Resilience
 
 ### Backup Model Support
@@ -408,13 +413,12 @@ Robust validation ensures system stability:
 
 ## Configuration Options
 
-### Routing Engine Options
+### Routing Configuration
 
 ```typescript
-const routingEngine = new RoutingEngine({
-  allowRouteSwitch: true, // Allow switching between routes
-  switchThreshold: 70, // Minimum score to switch routes
-  maxCandidates: 5, // Limit AI evaluation candidates
+const agent = new Agent({
+  // ...
+  routeSwitchMargin: 15, // Score margin before switching routes (0-100, default: 15)
 });
 ```
 

package/docs/guides/getting-started/README.md

@@ -717,27 +717,24 @@ console.log(response2.message); // Agent remembers: "Your name is Alice"
 
 ### Level 2: Core Concepts
 
-- **[Schema-Driven Extraction](../core-concepts/schema-driven-extraction.ts)** - Advanced data collection patterns
-- **[Session Management](../core-concepts/session-management.ts)** - Multi-turn conversations
-- **[Context Providers](../core-concepts/context-providers.ts)** - Dynamic context fetching
+- **[Schema-Driven Extraction](../../../examples/core-concepts/schema-driven-extraction.ts)** - Advanced data collection patterns
+- **[Session Management](../../../examples/core-concepts/session-management.ts)** - Multi-turn conversations
+- **[Modern Streaming API](../../../examples/core-concepts/modern-streaming-api.ts)** - Streaming with the modern API
 
 ### Level 3: Conversation Flows
 
-- **[Simple Routes](../conversation-flows/simple-route.ts)** - Basic route patterns
-- **[Data-Driven Flows](../conversation-flows/data-driven-flows.ts)** - Conditional logic and requirements
-- **[Branching](../conversation-flows/branching/README.md)** - Non-linear conversations
+- **[Completion Transitions](../../../examples/conversation-flows/completion-transitions.ts)** - Route completion and transitions
 
 ### Level 4: Advanced Features
 
-- **[Custom Providers](../ai-providers/custom-provider.ts)** - Integrate any AI service
-- **[Context Tools](../tools/context-updating-tools.ts)** - Modify agent state
-- **[Multi-Turn Conversations](../advanced-patterns/multi-turn-conversations.ts)** - Complex dialogues
+- **[Knowledge-Based Agent](../../../examples/advanced-patterns/knowledge-based-agent.ts)** - Domain-specific knowledge bases
+- **[Route Lifecycle Hooks](../../../examples/advanced-patterns/route-lifecycle-hooks.ts)** - Custom route behavior
 
 ### Level 5: Production
 
-- **[Server Deployment](../integrations/server-deployment.ts)** - HTTP API with WebSockets
-- **[Database Persistence](../persistence/custom-adapter.ts)** - Custom storage adapters
-- **[Streaming Responses](../advanced-patterns/streaming-responses.ts)** - Real-time UX
+- **[Server Session Management](../../../examples/integrations/server-session-management.ts)** - Server-side sessions
+- **[Database Persistence](../../../examples/persistence/custom-adapter.ts)** - Custom storage adapters
+- **[Streaming Responses](../../../examples/advanced-patterns/streaming-responses.ts)** - Real-time UX
 
 ---
 
@@ -783,7 +780,7 @@ console.log("Provider:", agent.options.provider.name);
 ### Getting Help
 
 - 📖 **[Full Documentation](../../README.md)** - Complete API reference
-- 💬 **[Examples Directory](../../examples/)** - Working code samples
+- 💬 **[Examples Directory](../../../examples/)** - Working code samples
 - 🐛 **[GitHub Issues](https://github.com/falai-dev/agent/issues)** - Report bugs
 - 💡 **[Discussions](https://github.com/falai-dev/agent/discussions)** - Ask questions
 

package/docs/guides/migration/response-modal-refactor.md

@@ -513,6 +513,6 @@ The modern `stream()` API is the recommended approach for new streaming implemen
 ---
 
 **Need Help?** 
-- Check the [examples](../../examples/) directory for complete working examples
+- Check the [examples](../../../examples/) directory for complete working examples
 - Review the [API documentation](../../api/) for detailed method signatures
-- Look at the [streaming examples](../../examples/advanced-patterns/streaming-responses.ts) for side-by-side comparisons
+- Look at the [streaming examples](../../../examples/advanced-patterns/streaming-responses.ts) for side-by-side comparisons

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/Agent.ts

@@ -126,9 +126,7 @@ export class Agent<TContext = any, TData = any> {
 
     // Initialize routing engine
     this.routingEngine = new RoutingEngine<TContext, TData>({
-      maxCandidates: 5,
-      allowRouteSwitch: true,
-      switchThreshold: 70,
+      routeSwitchMargin: options.routeSwitchMargin,
     });
 
     // Initialize ResponseModal for handling all response generation

package/src/core/RoutingEngine.ts

@@ -2,7 +2,6 @@ import type {
   Event,
   AgentOptions,
   StructuredSchema,
-  RoutingDecision,
   SessionState,
   AiProvider,
   TemplateContext,
@@ -36,9 +35,12 @@ export interface RoutingDecisionOutput {
 }
 
 export interface RoutingEngineOptions {
-  allowRouteSwitch?: boolean;
-  switchThreshold?: number; // 0-100
-  maxCandidates?: number;
+  /**
+   * Score margin the best alternative route must exceed the current route's score
+   * by before the agent switches routes. Prevents flip-flopping on marginal differences.
+   * @default 15
+   */
+  routeSwitchMargin?: number;
 }
 
 export interface BuildStepSelectionPromptParams<
@@ -746,7 +748,8 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       const optimalRoute = this.selectOptimalRoute(
         eligibleRoutes,
         updatedSession.data || {},
-        routingResult.structured.routes
+        routingResult.structured.routes,
+        updatedSession.currentRoute?.id
       );
 
       // If no optimal route found, check why
@@ -908,42 +911,68 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
    * @returns Route that should be prioritized for continuation
    */
   selectOptimalRoute(
-    routes: Route<TContext, TData>[],
-    data: Partial<TData>,
-    routeScores: Record<string, number>
-  ): Route<TContext, TData> | undefined {
-    const completionStatus = this.getRouteCompletionStatus(routes, data);
-
-    // Create weighted scores combining AI intent scores with completion progress
-    const weightedScores: Array<{ route: Route<TContext, TData>; score: number }> = [];
+      routes: Route<TContext, TData>[],
+      data: Partial<TData>,
+      routeScores: Record<string, number>,
+      currentRouteId?: string
+    ): Route<TContext, TData> | undefined {
+      const completionStatus = this.getRouteCompletionStatus(routes, data);
+      const switchMargin = this.options?.routeSwitchMargin ?? 15;
+
+      // Create weighted scores combining AI intent scores with completion progress
+      const weightedScores: Array<{ route: Route<TContext, TData>; score: number }> = [];
+
+      for (const route of routes) {
+        const aiScore = routeScores[route.id] || 0;
+        const completionProgress = completionStatus.get(route.id) || 0;
+
+        // ALWAYS skip fully completed routes to prevent re-entering finished tasks
+        if (completionProgress >= 1.0) {
+          logger.debug(
+            `[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`
+          );
+          continue;
+        }
 
-    for (const route of routes) {
-      const aiScore = routeScores[route.id] || 0;
-      const completionProgress = completionStatus.get(route.id) || 0;
+        // Boost partially complete routes that match user intent
+        let weightedScore = aiScore;
+        if (completionProgress > 0 && completionProgress < 1.0) {
+          weightedScore += (completionProgress * 20); // Up to 20 point boost
+        }
 
-      // ALWAYS skip fully completed routes to prevent re-entering finished tasks
-      // Users should not be forced back into completed routes
-      if (completionProgress >= 1.0) {
-        logger.debug(
-          `[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`
-        );
-        continue;
+        weightedScores.push({ route, score: weightedScore });
       }
 
-      // Boost partially complete routes that match user intent
-      let weightedScore = aiScore;
-      if (completionProgress > 0 && completionProgress < 1.0) {
-        // Boost score for partially complete routes
-        weightedScore += (completionProgress * 20); // Up to 20 point boost
-      }
+      // Sort by weighted score descending
+      weightedScores.sort((a, b) => b.score - a.score);
 
-      weightedScores.push({ route, score: weightedScore });
-    }
+      if (weightedScores.length === 0) {
+        return undefined;
+      }
 
-    // Sort by weighted score and return the best option
-    weightedScores.sort((a, b) => b.score - a.score);
+      // Apply sticky routing: if there's a current route, only switch if the
+      // best alternative exceeds the current route's score by the configured margin
+      if (currentRouteId) {
+        const currentEntry = weightedScores.find(e => e.route.id === currentRouteId);
+        const bestEntry = weightedScores[0];
+
+        if (currentEntry && bestEntry.route.id !== currentRouteId) {
+          if (bestEntry.score < currentEntry.score + switchMargin) {
+            logger.debug(
+              `[RoutingEngine] Staying on current route: ${currentEntry.route.title} ` +
+              `(current: ${currentEntry.score}, best alternative: ${bestEntry.score}, ` +
+              `margin required: ${switchMargin})`
+            );
+            return currentEntry.route;
+          }
+          logger.debug(
+            `[RoutingEngine] Switching route: ${currentEntry.route.title} → ${bestEntry.route.title} ` +
+            `(current: ${currentEntry.score}, alternative: ${bestEntry.score}, ` +
+            `margin: ${switchMargin})`
+          );
+        }
+      }
 
-    if (weightedScores.length > 0) {
       logger.debug(
         `[RoutingEngine] Selected optimal route: ${weightedScores[0].route.title} ` +
         `(AI: ${routeScores[weightedScores[0].route.id]}, ` +
@@ -953,9 +982,6 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       return weightedScores[0].route;
     }
 
-    return undefined;
-  }
-
   /**
    * Build prompt for step selection within a single route
    * @private
@@ -1380,17 +1406,4 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     return pc.build();
   }
 
-  decideRouteFromScores(output: RoutingDecision): {
-    routeId: string;
-    maxScore: number;
-  } {
-    // Optionally limit candidates and apply switching threshold
-    const entries = Object.entries(output.routes).sort((a, b) => b[1] - a[1]);
-    const limited = this.options?.maxCandidates
-      ? entries.slice(0, this.options.maxCandidates)
-      : entries;
-    const [topId, topScore] = limited[0] || ["", 0];
-    // switchThreshold is enforced by caller when a current route exists
-    return { routeId: topId, maxScore: topScore };
-  }
 }

package/src/types/agent.ts

@@ -114,6 +114,13 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
   schema?: StructuredSchema;
   /** Initial data to pre-populate when creating the agent */
   initialData?: Partial<TData>;
+  /**
+   * Margin (0-100) the best alternative route must exceed the current route's score
+   * by before the agent switches. Higher values make the agent "stickier" to the
+   * current route. Set to 0 to switch whenever any route scores higher.
+   * @default 15
+   */
+  routeSwitchMargin?: number;
 }
 
 /**

package/src/types/routing.ts

@@ -8,11 +8,6 @@ export interface RoutingDecision {
   contextUpdate?: Record<string, unknown>;
 }
 
-export interface RoutingDecisionWithRoute extends RoutingDecision {
-  selectedRouteId: string;
-  maxScore: number;
-}
-
 export interface RoutingSchemaOptions {
   extrasSchema?: StructuredSchema;
 }