@falai/agent 0.3.0 → 0.3.10

package/docs/API_REFERENCE.md

@@ -40,9 +40,17 @@ Adds an agent capability. Returns `this` for chaining.
 
 Creates an observation for disambiguation.
 
-##### `addDomain<TName, TDomain>(name: TName, domainObject: TDomain): this`
+##### `addDomain<TName, TDomain>(name: TName, domainObject: TDomain): void`
 
-Registers a domain with tools/methods. Returns `this` for chaining.
+Registers a domain with tools/methods.
+
+##### `getDomainsForRoute(routeId: string): Record<string, Record<string, unknown>>`
+
+Gets allowed domains for a specific route by ID. Returns filtered domains based on route's `domains` property, or all domains if route has no restrictions.
+
+##### `getDomainsForRouteByTitle(routeTitle: string): Record<string, Record<string, unknown>>`
+
+Gets allowed domains for a specific route by title. Returns filtered domains based on route's `domains` property, or all domains if route has no restrictions.
 
 ##### `respond(input: RespondInput<TContext>): Promise<RespondOutput>`
 
@@ -136,6 +144,9 @@ interface RouteOptions {
   description?: string;     // Route description
   conditions?: string[];    // Conditions that activate this route
   guidelines?: Guideline[]; // Initial guidelines for this route
+  domains?: string[];       // Domain names allowed in this route (undefined = all domains)
+  rules?: string[];         // Absolute rules the agent MUST follow in this route
+  prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do in this route
 }
 ```
 
@@ -151,6 +162,18 @@ Adds a guideline specific to this route. Returns `this` for chaining.
 
 Returns all guidelines for this route.
 
+##### `getDomains(): string[] | undefined`
+
+Returns allowed domain names for this route. Returns `undefined` if all domains are allowed, or an array of domain names if restricted.
+
+##### `getRules(): string[]`
+
+Returns the rules that must be followed in this route.
+
+##### `getProhibitions(): string[]`
+
+Returns the prohibitions that must never be done in this route.
+
 ##### `getRef(): RouteRef`
 
 Returns a reference to this route.
@@ -216,6 +239,7 @@ interface TransitionResult {
 **Example:**
 
 ```typescript
+// Approach 1: Step-by-step (ideal for complex flows with branching)
 const t0 = route.initialState.transitionTo({
   chatState: "Ask for user name",
 });
@@ -224,9 +248,30 @@ const t1 = t0.transitionTo({
   chatState: "Ask for email",
 });
 
+const t2 = t1.transitionTo({
+  chatState: "Confirm details",
+});
+
 // Access state properties
 console.log(t1.id); // State ID
 console.log(t1.routeId); // Route ID
+
+// Use saved references for branching
+t1.transitionTo(
+  { chatState: "Handle invalid email" },
+  "Email validation failed"
+);
+
+// Approach 2: Fluent chaining (elegant for linear flows)
+route.initialState
+  .transitionTo({ chatState: "Ask for user name" })
+  .transitionTo({ chatState: "Ask for email" })
+  .transitionTo({ chatState: "Confirm details" })
+  .transitionTo({ state: END_ROUTE });
+
+// Both approaches are equivalent - choose based on your needs:
+// - Use step-by-step for complex flows with conditional branches
+// - Use chaining for simple linear flows for conciseness
 ```
 
 ##### `addGuideline(guideline: Guideline): void`
@@ -289,6 +334,58 @@ Observation description (readonly).
 
 ---
 
+### `DomainRegistry`
+
+Registry for organizing agent tools and methods by domain.
+
+#### Methods
+
+##### `register<TDomain>(name: string, domain: TDomain): void`
+
+Registers a new domain with its tools/methods. Throws error if domain name already exists.
+
+##### `get<TDomain>(name: string): TDomain | undefined`
+
+Gets a registered domain by name. Returns `undefined` if not found.
+
+##### `has(name: string): boolean`
+
+Checks if a domain is registered.
+
+##### `all(): Record<string, Record<string, unknown>>`
+
+Returns all registered domains as a single object.
+
+##### `getFiltered(allowedNames?: string[]): Record<string, Record<string, unknown>>`
+
+Returns filtered domains by names. If `allowedNames` is `undefined`, returns all domains.
+
+**Example:**
+
+```typescript
+const registry = new DomainRegistry();
+
+registry.register("payment", {
+  processPayment: async (amount: number) => { /* ... */ },
+});
+
+registry.register("shipping", {
+  calculateShipping: (zipCode: string) => { /* ... */ },
+});
+
+// Get specific domains
+const filtered = registry.getFiltered(["payment"]); // Only payment domain
+
+// Get all domains
+const all = registry.getFiltered(); // payment + shipping
+```
+
+##### `getDomainNames(): string[]`
+
+Returns list of all registered domain names.
+
+---
+
 ### `GeminiProvider`
 
 AI provider implementation for Google Gemini.

package/docs/CONSTRUCTOR_OPTIONS.md

@@ -41,48 +41,48 @@ interface AgentOptions<TContext = unknown> {
 
 ```typescript
 const agent = new Agent({
-  name: "SupportBot",
-  description: "Helpful customer support",
-  goal: "Resolve issues efficiently",
-  ai: new GeminiProvider({ apiKey: "...", model: "..." }),
-  context: { userId: "123" },
+  name: 'SupportBot',
+  description: 'Helpful customer support',
+  goal: 'Resolve issues efficiently',
+  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"],
+      condition: 'User is frustrated',
+      action: 'Show empathy and offer escalation',
+      tags: ['support'],
       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"],
+      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!
+      description: 'User mentions problem but unclear what kind',
+      routeRefs: ['Create Ticket', 'Check Ticket Status'], // By title!
     },
   ],
 });
@@ -98,33 +98,49 @@ interface RouteOptions {
   title: string;
 
   // Optional
+  id?: string;              // Custom ID (auto-generated from title if not provided)
   description?: string;
   conditions?: string[];
-  guidelines?: Guideline[]; // NEW!
+  guidelines?: Guideline[];
+  domains?: string[];       // Restrict which domains are available in this route
+  rules?: string[];         // Absolute rules the agent MUST follow
+  prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do
 }
 ```
 
+**Domain Scoping:**
+- Use `domains` to limit which registered domains (tools/methods) can be accessed during this route
+- If `undefined` or omitted, all registered domains are available
+- Useful for security (preventing unauthorized tool calls) and performance (reducing AI decision space)
+
+**Rules & Prohibitions:**
+- **Rules**: Absolute requirements the agent must follow in this route (style, format, behavior)
+- **Prohibitions**: Things the agent must never do in this route
+- These override general guidelines if there's any conflict
+- Applied automatically when the route is active
+- Perfect for controlling message style, tone, length, emoji usage, etc.
+
 ### Example: Route with Nested Guidelines
 
 ```typescript
 const agent = new Agent({
-  name: "Bot",
+  name: 'Bot',
   ai: provider,
   routes: [
     {
-      title: "Onboarding",
-      description: "Guide new users",
-      conditions: ["User is new"],
+      title: 'Onboarding',
+      description: 'Guide new users',
+      conditions: ['User is new'],
       guidelines: [
         {
-          condition: "User skips a step",
+          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"],
+          condition: 'User seems confused',
+          action: 'Offer a quick tutorial video',
+          tags: ['help'],
         },
       ],
     },
@@ -132,6 +148,131 @@ const agent = new Agent({
 });
 ```
 
+### Example: Route with Domain Scoping
+
+```typescript
+// Register domains
+agent.addDomain('scraping', {
+  scrapeSite: async (url: string) => {
+    /* ... */
+  },
+  extractData: async (html: string) => {
+    /* ... */
+  },
+});
+
+agent.addDomain('calendar', {
+  scheduleEvent: async (date: Date, title: string) => {
+    /* ... */
+  },
+  listEvents: async () => {
+    /* ... */
+  },
+});
+
+agent.addDomain('payment', {
+  processPayment: async (amount: number) => {
+    /* ... */
+  },
+});
+
+// Create routes with domain restrictions
+agent.createRoute({
+  title: 'Data Collection',
+  description: 'Collect and process web data',
+  domains: ['scraping'], // ✅ Only scraping tools available
+});
+
+agent.createRoute({
+  title: 'Schedule Meeting',
+  description: 'Book appointments',
+  domains: ['calendar'], // ✅ Only calendar tools available
+});
+
+agent.createRoute({
+  title: 'Checkout',
+  description: 'Process purchase',
+  domains: ['payment', 'calendar'], // ✅ Multiple domains allowed
+});
+
+agent.createRoute({
+  title: 'FAQ Support',
+  description: 'Answer general questions',
+  domains: [], // ✅ No tools available (conversation only)
+});
+
+agent.createRoute({
+  title: 'Admin Support',
+  description: 'Administrative tasks',
+  // domains not specified = all domains available (for demo purposes)
+});
+```
+
+### Example: Route with Rules & Prohibitions
+
+```typescript
+// WhatsApp support bot with different styles per route
+agent.createRoute({
+  title: 'Customer Support',
+  description: 'Help customers with issues',
+  domains: [],
+  rules: [
+    'Keep messages short (maximum 2 lines per message)',
+    'Use maximum 1 emoji per message',
+    'Always ask if the issue is resolved before ending',
+    'Professional but friendly tone'
+  ],
+  prohibitions: [
+    'Never send messages longer than 3 paragraphs',
+    'Do not use slang or informal language',
+    'Never promise what you cannot deliver',
+    'Do not ask for sensitive information via chat'
+  ]
+});
+
+agent.createRoute({
+  title: 'Sales Consultation',
+  description: 'Help customer discover needs and present solutions',
+  domains: ['calendar', 'analytics'],
+  rules: [
+    'Ask open-ended questions to discover needs',
+    'Use storytelling when presenting solutions',
+    'Emoji only to reinforce positive emotions 😊',
+    'Always present value before mentioning price'
+  ],
+  prohibitions: [
+    'Never talk about price before showing value',
+    'Do not pressure the customer',
+    'Avoid complex technical terms',
+    'Never send more than 2 messages in a row without customer response'
+  ]
+});
+
+agent.createRoute({
+  title: 'Emergency Support',
+  description: 'Handle urgent customer issues',
+  domains: ['notifications', 'ticketing'],
+  rules: [
+    'Respond immediately and acknowledge urgency',
+    'Use clear, direct language',
+    'Provide concrete next steps',
+    'Set clear expectations on resolution time'
+  ],
+  prohibitions: [
+    'Never downplay the customer\'s concern',
+    'Do not use emojis',
+    'Never say "calm down" or similar phrases',
+    'Do not transfer without explaining why'
+  ]
+});
+```
+
+**How it works:**
+- Rules and prohibitions are automatically applied when the route is active
+- They override general guidelines if there's any conflict
+- Perfect for controlling communication style per context
+- Applied in the AI prompt to ensure compliance
+
 ---
 
 ## 🔍 Observation Options
@@ -175,14 +316,14 @@ All constructor options also have fluent methods that **return `this`** for chai
 
 ```typescript
 agent
-  .createTerm({ name: "API", description: "..." })
-  .createGuideline({ condition: "...", action: "..." })
-  .createCapability({ title: "...", description: "..." });
+  .createTerm({ name: 'API', description: '...' })
+  .createGuideline({ condition: '...', action: '...' })
+  .createCapability({ title: '...', description: '...' });
 
-const route = agent.createRoute({ title: "..." });
-route.createGuideline({ condition: "...", action: "..." });
+const route = agent.createRoute({ title: '...' });
+route.createGuideline({ condition: '...', action: '...' });
 
-const obs = agent.createObservation("User intent unclear");
+const obs = agent.createObservation('User intent unclear');
 obs.disambiguate([route1, route2]);
 ```
 
@@ -209,7 +350,7 @@ obs.disambiguate([route1, route2]);
 ```typescript
 // Start with static config
 const agent = new Agent({
-  name: "Bot",
+  name: 'Bot',
   ai: provider,
   terms: loadTermsFromFile(),
   guidelines: loadGuidelinesFromDB(),
@@ -218,8 +359,8 @@ const agent = new Agent({
 // Add dynamic features
 if (user.isPremium) {
   agent.createGuideline({
-    condition: "User asks for priority support",
-    action: "Escalate immediately to premium team",
+    condition: 'User asks for priority support',
+    action: 'Escalate immediately to premium team',
   });
 }
 ```

package/docs/GETTING_STARTED.md

@@ -154,7 +154,9 @@ const onboardingRoute = agent.createRoute({
   conditions: ["User is new and needs onboarding"],
 });
 
-// Build the flow
+// Build the flow - two approaches:
+
+// Approach 1: Step-by-step (great for complex flows with branching)
 const step1 = onboardingRoute.initialState.transitionTo({
   chatState: "Ask for user's name",
 });
@@ -167,8 +169,14 @@ const step3 = step2.transitionTo({
   chatState: "Confirm details and welcome user",
 });
 
-// End the route
 step3.transitionTo({ state: END_ROUTE });
+
+// Approach 2: Fluent chaining (concise for linear flows)
+onboardingRoute.initialState
+  .transitionTo({ chatState: "Ask for user's name" })
+  .transitionTo({ chatState: "Ask for user's email" })
+  .transitionTo({ chatState: "Confirm details and welcome user" })
+  .transitionTo({ state: END_ROUTE });
 ```
 
 ### Handle Context Dynamically