@falai/agent 0.1.0

package/src/core/Agent.ts

@@ -0,0 +1,307 @@
+/**
+ * Core Agent implementation
+ */
+
+import type {
+  AgentOptions,
+  Term,
+  Guideline,
+  GuidelineMatch,
+  Capability,
+} from "@/types/agent";
+import type { Event, StateRef } from "@/types/index";
+import type { RouteOptions } from "@/types/route";
+
+import { Route } from "@/core/Route";
+import { DomainRegistry } from "@/core/DomainRegistry";
+import { PromptBuilder } from "@/core/PromptBuilder";
+import { Observation } from "@/core/Observation";
+
+/**
+ * Main Agent class with generic context support
+ */
+export class Agent<TContext = unknown> {
+  private terms: Term[] = [];
+  private guidelines: Guideline[] = [];
+  private capabilities: Capability[] = [];
+  private routes: Route[] = [];
+  private observations: Observation[] = [];
+  private domainRegistry = new DomainRegistry();
+
+  /**
+   * Dynamic domain property - populated via addDomain
+   */
+  public readonly domain: Record<string, Record<string, unknown>> = {};
+
+  constructor(private readonly options: AgentOptions<TContext>) {
+    // Initialize with default values
+    if (!this.options.maxEngineIterations) {
+      this.options.maxEngineIterations = 1;
+    }
+
+    // Initialize from options
+    if (options.terms) {
+      this.terms = [...options.terms];
+    }
+
+    if (options.guidelines) {
+      options.guidelines.forEach((guideline) => {
+        this.createGuideline(guideline);
+      });
+    }
+
+    if (options.capabilities) {
+      options.capabilities.forEach((capability) => {
+        this.createCapability(capability);
+      });
+    }
+
+    if (options.routes) {
+      options.routes.forEach((routeOptions) => {
+        this.createRoute(routeOptions);
+      });
+    }
+
+    if (options.observations) {
+      options.observations.forEach((obsOptions) => {
+        const obs = this.createObservation(obsOptions.description);
+
+        // If route refs were provided, resolve and disambiguate
+        if (obsOptions.routeRefs && obsOptions.routeRefs.length > 0) {
+          const resolvedRoutes = obsOptions.routeRefs
+            .map((ref) => {
+              // Try to find route by ID or title
+              return this.routes.find((r) => r.id === ref || r.title === ref);
+            })
+            .filter((r): r is Route => r !== undefined);
+
+          if (resolvedRoutes.length > 0) {
+            obs.disambiguate(resolvedRoutes);
+          }
+        }
+      });
+    }
+  }
+
+  /**
+   * Get agent name
+   */
+  get name(): string {
+    return this.options.name;
+  }
+
+  /**
+   * Get agent description
+   */
+  get description(): string | undefined {
+    return this.options.description;
+  }
+
+  /**
+   * Get agent goal
+   */
+  get goal(): string | undefined {
+    return this.options.goal;
+  }
+
+  /**
+   * Create a new route (journey)
+   */
+  createRoute(options: RouteOptions): Route {
+    const route = new Route(options);
+    this.routes.push(route);
+    return route;
+  }
+
+  /**
+   * Create a domain term for the glossary
+   */
+  createTerm(term: Term): this {
+    this.terms.push(term);
+    return this;
+  }
+
+  /**
+   * Create a behavioral guideline
+   */
+  createGuideline(guideline: Guideline): this {
+    const guidelineWithId = {
+      ...guideline,
+      id: guideline.id || `guideline_${this.guidelines.length}`,
+      enabled: guideline.enabled !== false, // Default to true
+    };
+    this.guidelines.push(guidelineWithId);
+    return this;
+  }
+
+  /**
+   * Add a capability
+   */
+  createCapability(capability: Capability): this {
+    const capabilityWithId = {
+      ...capability,
+      id: capability.id || `capability_${this.capabilities.length}`,
+    };
+    this.capabilities.push(capabilityWithId);
+    return this;
+  }
+
+  /**
+   * Create an observation for disambiguation
+   */
+  createObservation(description: string): Observation {
+    const observation = new Observation({ description });
+    this.observations.push(observation);
+    return observation;
+  }
+
+  /**
+   * Add a domain with its tools/methods
+   */
+  addDomain<TName extends string, TDomain extends Record<string, unknown>>(
+    name: TName,
+    domainObject: TDomain
+  ): void {
+    this.domainRegistry.register(name, domainObject);
+    // Attach to the domain property for easy access
+    this.domain[name] = domainObject;
+  }
+
+  /**
+   * Generate a response based on history and context
+   */
+  async respond(params: {
+    history: Event[];
+    state?: StateRef;
+    contextOverride?: Partial<TContext>;
+    signal?: AbortSignal;
+  }): Promise<{ message: string }> {
+    const { history, contextOverride, signal } = params;
+
+    // Merge context
+    const effectiveContext = {
+      ...(this.options.context as Record<string, unknown>),
+      ...(contextOverride as Record<string, unknown>),
+    } as TContext;
+
+    // Build prompt
+    const promptBuilder = new PromptBuilder();
+
+    // Add agent identity
+    if (this.options.description) {
+      promptBuilder.addAgentIdentity({
+        name: this.options.name,
+        description: this.options.description,
+      });
+    }
+
+    // Add interaction history
+    promptBuilder.addInteractionHistoryForMessageGeneration(history);
+
+    // Add glossary
+    if (this.terms.length > 0) {
+      promptBuilder.addGlossary(this.terms);
+    }
+
+    // Add guidelines (convert to GuidelineMatch format, filter enabled only)
+    const enabledGuidelines = this.guidelines.filter(
+      (g) => g.enabled !== false
+    );
+    if (enabledGuidelines.length > 0) {
+      const guidelineMatches: GuidelineMatch[] = enabledGuidelines.map((g) => ({
+        guideline: g,
+      }));
+      promptBuilder.addGuidelinesForMessageGeneration(guidelineMatches);
+    }
+
+    // Add capabilities
+    if (this.capabilities.length > 0) {
+      promptBuilder.addCapabilitiesForMessageGeneration(this.capabilities);
+    }
+
+    // Add observations
+    if (this.observations.length > 0) {
+      const observationsWithRoutes = this.observations
+        .map((obs) => ({
+          description: obs.description,
+          routes: obs.getRoutes().map((routeRef) => {
+            const route = this.routes.find((r) => r.id === routeRef.id);
+            return { title: route?.title || routeRef.id };
+          }),
+        }))
+        .filter((obs) => obs.routes.length > 0);
+
+      if (observationsWithRoutes.length > 0) {
+        promptBuilder.addObservations(observationsWithRoutes);
+      }
+    }
+
+    // Add active routes
+    if (this.routes.length > 0) {
+      promptBuilder.addActiveRoutes(
+        this.routes.map((r) => ({
+          title: r.title,
+          description: r.description,
+          conditions: r.conditions,
+        }))
+      );
+    }
+
+    // Build final prompt
+    const prompt = promptBuilder.build();
+
+    // Generate message using AI provider
+    const result = await this.options.ai.generateMessage({
+      prompt,
+      history,
+      context: effectiveContext,
+      signal,
+    });
+
+    return {
+      message: result.message,
+    };
+  }
+
+  /**
+   * Get all routes
+   */
+  getRoutes(): Route[] {
+    return [...this.routes];
+  }
+
+  /**
+   * Get all terms
+   */
+  getTerms(): Term[] {
+    return [...this.terms];
+  }
+
+  /**
+   * Get all guidelines
+   */
+  getGuidelines(): Guideline[] {
+    return [...this.guidelines];
+  }
+
+  /**
+   * Get all capabilities
+   */
+  getCapabilities(): Capability[] {
+    return [...this.capabilities];
+  }
+
+  /**
+   * Get all observations
+   */
+  getObservations(): Observation[] {
+    return [...this.observations];
+  }
+
+  /**
+   * Get the domain registry
+   */
+  getDomainRegistry(): DomainRegistry {
+    return this.domainRegistry;
+  }
+}

package/src/core/DomainRegistry.ts

@@ -0,0 +1,50 @@
+/**
+ * Domain registry for organizing agent capabilities by domain
+ */
+
+/**
+ * Registry that holds domain-specific tools and methods
+ */
+export class DomainRegistry {
+  private domains: Map<string, Record<string, unknown>> = new Map();
+
+  /**
+   * Register a new domain with its methods/tools
+   */
+  register<TDomain extends Record<string, unknown>>(
+    name: string,
+    domain: TDomain
+  ): void {
+    if (this.domains.has(name)) {
+      throw new Error(`Domain "${name}" is already registered`);
+    }
+    this.domains.set(name, domain);
+  }
+
+  /**
+   * Get a registered domain
+   */
+  get<TDomain extends Record<string, unknown>>(
+    name: string
+  ): TDomain | undefined {
+    return this.domains.get(name) as TDomain | undefined;
+  }
+
+  /**
+   * Check if a domain is registered
+   */
+  has(name: string): boolean {
+    return this.domains.has(name);
+  }
+
+  /**
+   * Get all registered domains as a single object
+   */
+  all(): Record<string, Record<string, unknown>> {
+    const result: Record<string, Record<string, unknown>> = {};
+    for (const [name, domain] of this.domains) {
+      result[name] = domain;
+    }
+    return result;
+  }
+}

package/src/core/Events.ts

@@ -0,0 +1,101 @@
+/**
+ * Event utilities and helpers
+ */
+
+import type {
+  Event,
+  EmittedEvent,
+  MessageEventData,
+  ToolEventData,
+  ToolCall,
+} from "@/types/history";
+import { EventKind, EventSource } from "@/types/history";
+
+/**
+ * Adapt an event for inclusion in prompts
+ * Transforms event data into a serializable format
+ */
+export function adaptEvent(e: Event | EmittedEvent): string {
+  let data: unknown = e.data;
+
+  if (e.kind === EventKind.MESSAGE) {
+    const messageData = e.data as MessageEventData;
+
+    if (messageData.flagged) {
+      data = {
+        participant: messageData.participant.display_name,
+        message: "<N/A>",
+        censored: true,
+        reasons: messageData.tags,
+      };
+    } else {
+      data = {
+        participant: messageData.participant.display_name,
+        message: messageData.message,
+      };
+    }
+  }
+
+  if (e.kind === EventKind.TOOL) {
+    const toolData = e.data as ToolEventData;
+
+    data = {
+      tool_calls: toolData.tool_calls.map((tc) => ({
+        tool_id: tc.tool_id,
+        arguments: tc.arguments,
+        result: tc.result.data,
+      })),
+    };
+  }
+
+  const sourceMap: Record<EventSource, string> = {
+    [EventSource.CUSTOMER]: "user",
+    [EventSource.CUSTOMER_UI]: "frontend_application",
+    [EventSource.HUMAN_AGENT]: "human_service_agent",
+    [EventSource.HUMAN_AGENT_ON_BEHALF_OF_AI_AGENT]: "ai_agent",
+    [EventSource.AI_AGENT]: "ai_agent",
+    [EventSource.SYSTEM]: "system-provided",
+  };
+
+  return JSON.stringify({
+    event_kind: e.kind,
+    event_source: sourceMap[e.source],
+    data,
+  });
+}
+
+/**
+ * Create a message event
+ */
+export function createMessageEvent(
+  source: EventSource,
+  participantName: string,
+  message: string
+): Event<MessageEventData> {
+  return {
+    kind: EventKind.MESSAGE,
+    source,
+    data: {
+      participant: { display_name: participantName },
+      message,
+    },
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Create a tool event
+ */
+export function createToolEvent(
+  source: EventSource,
+  toolCalls: ToolCall[]
+): Event<ToolEventData> {
+  return {
+    kind: EventKind.TOOL,
+    source,
+    data: {
+      tool_calls: toolCalls,
+    },
+    timestamp: new Date().toISOString(),
+  };
+}

package/src/core/Observation.ts

@@ -0,0 +1,46 @@
+/**
+ * Observation for route disambiguation
+ */
+
+import type {
+  Observation as IObservation,
+  ObservationOptions,
+} from "@/types/observation";
+import type { RouteRef } from "@/types/route";
+import type { Route } from "@/core/Route";
+
+let observationIdCounter = 0;
+
+/**
+ * An observation that can trigger disambiguation between routes
+ */
+export class Observation implements IObservation {
+  public readonly id: string;
+  public readonly description: string;
+  public routes: RouteRef[] = [];
+
+  constructor(options: ObservationOptions) {
+    this.id = `observation_${++observationIdCounter}`;
+    this.description = options.description;
+  }
+
+  /**
+   * Set routes that this observation can disambiguate between
+   */
+  disambiguate(routes: (Route | RouteRef)[]): this {
+    this.routes = routes.map((r) => {
+      if ("getRef" in r) {
+        return r.getRef();
+      }
+      return r;
+    });
+    return this;
+  }
+
+  /**
+   * Get the routes this observation disambiguates
+   */
+  getRoutes(): RouteRef[] {
+    return [...this.routes];
+  }
+}