@falai/agent 0.8.1 → 0.9.0-alpha-1

package/src/core/PromptComposer.ts

@@ -1,143 +1,216 @@
-import type { Event } from "../types/history";
-import type { Term, Guideline, Capability } from "../types/agent";
+import type { Event, Term, Guideline, AgentOptions } from "../types";
 import type { Route } from "./Route";
+import { render, renderMany, formatKnowledgeBase } from "../utils/template";
+import { TemplateContext } from "../types/template";
 
-export class PromptComposer<TContext = unknown> {
+export class PromptComposer<TContext = unknown, TData = unknown> {
   private parts: string[] = [];
+  private renderContext: TemplateContext<TContext, TData>;
+
+  constructor(context: TemplateContext<TContext, TData> = {}) {
+    this.renderContext = context;
+  }
 
   // Specific, typed sections tailored to the framework
 
-  addAgentMeta(agent: {
-    name: string;
-    goal?: string;
-    description?: string;
-  }): this {
+  async addAgentMeta(agent: AgentOptions<TContext>): Promise<this> {
     const lines: string[] = [];
-    lines.push(`Agent: ${agent.name}`);
-    if (agent.goal) lines.push(`Goal: ${agent.goal}`);
-    if (agent.description) lines.push(`Description: ${agent.description}`);
-    this.parts.push(lines.join("\n"));
-    return this;
-  }
-
-  addPersonality(personality?: string): this {
-    if (personality && personality.trim().length) {
-      this.parts.push(`Personality: ${personality.trim()}`);
+    lines.push("## Agent");
+    lines.push(`**Name:** ${agent.name}`);
+    if (agent.goal) {
+      lines.push(`**Goal:** ${agent.goal}`);
     }
+    if (agent.description) {
+      lines.push(`**Description:** ${agent.description}`);
+    }
+    if (agent.identity) {
+      lines.push(
+        `**Identity:** ${await render(agent.identity, this.renderContext)}`
+      );
+    }
+    if (agent.personality) {
+      lines.push(
+        `**Personality:** ${await render(
+          agent.personality,
+          this.renderContext
+        )}`
+      );
+    }
+    this.parts.push(lines.join("\n"));
     return this;
   }
 
-  addRoutingOverview(routes: Route<TContext>[]): this {
+  async addRoutingOverview(routes: Route<TContext, TData>[]): Promise<this> {
     return this.addActiveRoutes(routes);
   }
 
-  addScoringRules(): this {
+  async addScoringRules(): Promise<this> {
     this.parts.push(
-      [
-        "Scoring rules:",
+      `## Scoring Rules\n\n${[
         "- 90-100: explicit keywords + clear intent",
         "- 70-89: strong contextual evidence + relevant keywords",
         "- 50-69: moderate relevance",
         "- 30-49: weak connection or ambiguous",
         "- 0-29: minimal/none",
         "Return ONLY JSON matching the provided schema. Include scores for ALL routes.",
-      ].join("\n")
+      ].join("\n")}`
     );
-    return this;
+    return Promise.resolve(this);
   }
 
-  addInstruction(text: string): this {
-    if (text) this.parts.push(text);
-    return this;
+  async addInstruction(text: string): Promise<this> {
+    if (text) this.parts.push(`## Instruction\n\n${text}`);
+    return Promise.resolve(this);
   }
 
-  addInteractionHistory(history: Event[], note?: string): this {
+  async addInteractionHistory(history: Event[], note?: string): Promise<this> {
     const recent = history
       .slice(-10)
-      .map((e) => JSON.stringify(e))
+      .map((e) => `- ${JSON.stringify(e)}`)
       .join("\n");
-    const header = note ? `${note}\n` : "";
-    this.parts.push(`${header}Recent conversation events:\n${recent}`);
-    return this;
+    const header = note ? `${note}\n\n` : "";
+    this.parts.push(
+      `## Interaction History\n\n${header}Recent conversation events:\n\n${recent}`
+    );
+    return Promise.resolve(this);
   }
 
-  addLastMessage(message: string): this {
-    this.parts.push(`Last user message:\n${message}`);
-    return this;
+  async addLastMessage(message: string): Promise<this> {
+    this.parts.push(`## Last Message\n\n${message}`);
+    return Promise.resolve(this);
   }
 
-  addGlossary(terms: Term[]): this {
+  async addGlossary(terms: Term<TContext>[]): Promise<this> {
     if (!terms.length) return this;
-    const text = terms
-      .map(
-        (t, i) =>
-          `${i + 1}) ${t.name}${
-            t.synonyms?.length ? ` (synonyms: ${t.synonyms.join(", ")})` : ""
-          }: ${t.description}`
-      )
-      .join("\n");
-    this.parts.push(`Glossary:\n${text}`);
+
+    const renderedTerms = await Promise.all(
+      terms.map(async (t) => {
+        const name = await render(t.name, this.renderContext);
+        const description = await render(t.description, this.renderContext);
+        const synonyms = t.synonyms
+          ? await renderMany(t.synonyms, this.renderContext)
+          : [];
+        const synonymText =
+          synonyms.length > 0 ? ` (synonyms: ${synonyms.join(", ")})` : "";
+        return `- **${name}**${synonymText}: ${description}`;
+      })
+    );
+
+    this.parts.push(`## Glossary\n\n${renderedTerms.join("\n")}`);
     return this;
   }
 
-  addGuidelines(guidelines: Guideline[]): this {
+  async addGuidelines(guidelines: Guideline<TContext>[]): Promise<this> {
     const enabled = guidelines.filter((g) => g.enabled !== false);
     if (!enabled.length) return this;
-    const text = enabled
-      .map((g, i) => {
-        const cond = g.condition
-          ? `When ${g.condition}, then ${g.action}`
-          : g.action;
-        return `Guideline #${i + 1}) ${cond}`;
+
+    const renderedGuidelines = await Promise.all(
+      enabled.map(async (g, i) => {
+        const action = await render(g.action, this.renderContext);
+        if (g.condition) {
+          const condition = await render(g.condition, this.renderContext);
+          return `- Guideline #${i + 1}: When ${condition}, then ${action}`;
+        }
+        return `- Guideline #${i + 1}: ${action}`;
       })
-      .join("\n");
-    this.parts.push(`Guidelines:\n${text}`);
+    );
+
+    this.parts.push(`## Guidelines\n\n${renderedGuidelines.join("\n")}`);
     return this;
   }
 
-  addCapabilities(capabilities: Capability[]): this {
-    if (!capabilities.length) return this;
-    const text = capabilities
-      .map((c, i) => `Capability ${i + 1}: ${c.title}\n${c.description}`)
-      .join("\n\n");
-    this.parts.push(`Capabilities:\n${text}`);
-    return this;
+  async addKnowledgeBase(
+    agentKnowledgeBase?: Record<string, unknown>,
+    routeKnowledgeBase?: Record<string, unknown>
+  ): Promise<this> {
+    // Merge agent and route knowledge bases (route takes precedence for conflicts)
+    const mergedKnowledge = {
+      ...(agentKnowledgeBase || {}),
+      ...(routeKnowledgeBase || {}),
+    };
+
+    // Only add section if there's knowledge data
+    if (Object.keys(mergedKnowledge).length > 0) {
+      const formatted = formatKnowledgeBase(mergedKnowledge, "Knowledge Base");
+      this.parts.push(formatted);
+    }
+
+    return Promise.resolve(this);
   }
 
-  addActiveRoutes(routes: Route<TContext>[]): this {
+  async addActiveRoutes(routes: Route<TContext, TData>[]): Promise<this> {
     if (!routes.length) return this;
-    const text = routes
-      .map((r, i) => {
-        const conditions = r.conditions.length
-          ? `\n  Triggered when: ${r.conditions.join(" OR ")}`
-          : "";
-        const desc = r.description ? `\n  ${r.description}` : "";
-        const rules = r.getRules();
-        const prohibitions = r.getProhibitions();
-        const rulesInfo = rules.length
-          ? `\n  RULES: ${rules.map((x, idx) => `${idx + 1}. ${x}`).join("; ")}`
-          : "";
-        const prohibitionsInfo = prohibitions.length
-          ? `\n  PROHIBITIONS: ${prohibitions
-              .map((x, idx) => `${idx + 1}. ${x}`)
-              .join("; ")}`
+
+    const renderedRoutes = await Promise.all(
+      routes.map(async (r, i) => {
+        const conditions =
+          r.conditions.length > 0
+            ? `\n\n  **Triggered when:** ${(
+                await renderMany(r.conditions, this.renderContext)
+              ).join(" OR ")}`
+            : "";
+        const desc = r.description
+          ? `\n\n  **Description:** ${r.description}`
           : "";
-        return `${i + 1}) ${
+        const rules = await renderMany(r.getRules(), this.renderContext);
+        const prohibitions = await renderMany(
+          r.getProhibitions(),
+          this.renderContext
+        );
+        const rulesInfo =
+          rules.length > 0
+            ? `\n\n  **Rules:**\n  ${rules.map((x) => `  - ${x}`).join("\n  ")}`
+            : "";
+        const prohibitionsInfo =
+          prohibitions.length > 0
+            ? `\n\n  **Prohibitions:**\n  ${prohibitions
+                .map((x) => `  - ${x}`)
+                .join("\n  ")}`
+            : "";
+        return `### Route ${i + 1}: ${
           r.title
         }${desc}${conditions}${rulesInfo}${prohibitionsInfo}`;
       })
-      .join("\n\n");
-    this.parts.push(`Available routes:\n${text}`);
+    );
+
+    this.parts.push(`## Available Routes\n\n${renderedRoutes.join("\n\n")}`);
     return this;
   }
 
-  addDirectives(directives?: string[]): this {
+  async addDirectives(directives?: string[]): Promise<this> {
     if (!directives?.length) return this;
-    this.parts.push(`Address concisely:\n- ${directives.join("\n- ")}`);
-    return this;
+    this.parts.push(
+      `## Directives\n\nAddress concisely:\n\n${directives
+        .map((d) => `- ${d}`)
+        .join("\n")}`
+    );
+    return Promise.resolve(this);
+  }
+
+  async addAvailableTools(
+    tools?: Array<{
+      id: string;
+      name?: string;
+      description?: string;
+      parameters?: unknown;
+    }>
+  ): Promise<this> {
+    if (!tools?.length) return this;
+
+    const renderedTools = tools.map((tool, i) => {
+      const toolName = tool.name || tool.id;
+      const desc = tool.description
+        ? `\n    Description: ${tool.description}`
+        : "";
+      return `### Tool ${i + 1}: ${toolName}${desc}`;
+    });
+
+    this.parts.push(`## Available Tools\n\n${renderedTools.join("\n\n")}`);
+    return Promise.resolve(this);
   }
 
-  build(): string {
-    return this.parts.filter(Boolean).join("\n\n").trim();
+  async build(): Promise<string> {
+    const prompt = this.parts.filter(Boolean).join("\n\n").trim();
+    return Promise.resolve(prompt);
   }
 }

package/src/core/ResponseEngine.ts

@@ -1,8 +1,44 @@
-import type { Event } from "../types/history";
+import type {
+  Event,
+  StructuredSchema,
+  SessionState,
+  AgentOptions,
+  Guideline,
+  Term,
+  Template,
+} from "../types";
 import type { Route } from "./Route";
 import type { Step } from "./Step";
-import type { StructuredSchema } from "../types/schema";
 import { PromptComposer } from "./PromptComposer";
+import { render } from "../utils/template";
+
+export interface BuildResponsePromptParams<
+  TContext = unknown,
+  TData = unknown
+> {
+  route: Route<TContext, TData>;
+  currentStep: Step<TContext, TData>;
+  rules: Template<TContext, TData>[];
+  prohibitions: Template<TContext, TData>[];
+  directives: string[] | undefined;
+  history: Event[];
+  lastMessage: string;
+  agentOptions?: AgentOptions<TContext>;
+  // Combined properties from agent and route
+  combinedGuidelines?: Guideline<TContext>[];
+  combinedTerms?: Term<TContext>[];
+  context?: TContext;
+  session?: SessionState<TData>;
+}
+
+export interface BuildFallbackPromptParams<TContext = unknown> {
+  history: Event[];
+  agentOptions: AgentOptions<TContext>;
+  terms: Term<TContext>[];
+  guidelines: Guideline<TContext>[];
+  context?: TContext;
+  session?: SessionState;
+}
 
 export class ResponseEngine<TContext = unknown> {
   responseSchemaForRoute<TData = unknown>(
@@ -24,8 +60,8 @@ export class ResponseEngine<TContext = unknown> {
     }
 
     // Add collect fields from current step
-    if (currentStep?.collectFields && route.schema?.properties) {
-      for (const field of currentStep.collectFields) {
+    if (currentStep?.collect && route.schema?.properties) {
+      for (const field of currentStep.collect) {
         const fieldSchema = route.schema.properties[field];
         if (fieldSchema) {
           base.properties![field] = fieldSchema;
@@ -36,50 +72,94 @@ export class ResponseEngine<TContext = unknown> {
     return base;
   }
 
-  buildResponsePrompt(
-    route: Route<TContext>,
-    currentStep: Step<TContext>,
-    rules: string[],
-    prohibitions: string[],
-    directives: string[] | undefined,
-    history: Event[],
-    lastMessage: string,
-    agentMeta?: {
-      name?: string;
-      goal?: string;
-      description?: string;
-      personality?: string;
+  async buildResponsePrompt(
+    params: BuildResponsePromptParams<TContext>
+  ): Promise<string> {
+    const {
+      route,
+      currentStep,
+      rules,
+      prohibitions,
+      directives,
+      history,
+      lastMessage,
+      agentOptions,
+      combinedGuidelines,
+      combinedTerms,
+      context,
+      session,
+    } = params;
+    const templateContext = { context, session, history };
+    const pc = new PromptComposer(templateContext);
+
+    // Create combined agent options with route overrides
+    let effectiveAgentOptions = agentOptions;
+    if (agentOptions && (route.identity || route.personality)) {
+      // Route identity and personality override agent versions
+      effectiveAgentOptions = {
+        ...agentOptions,
+        ...(route.identity && { identity: route.identity }),
+        ...(route.personality && { personality: route.personality }),
+      };
     }
-  ): string {
-    const pc = new PromptComposer();
-    if (agentMeta?.name || agentMeta?.goal || agentMeta?.description)
-      pc.addAgentMeta({
-        name: agentMeta?.name || "Agent",
-        goal: agentMeta?.goal,
-        description: agentMeta?.description,
-      });
-    const personality =
-      agentMeta?.personality || "Tone: brief, natural, 1-2 short sentences.";
-    pc.addPersonality(personality);
-    pc.addInstruction(
+
+    if (effectiveAgentOptions) {
+      await pc.addAgentMeta(effectiveAgentOptions);
+    }
+    await pc.addInstruction(
       `Route: ${route.title}${
         route.description ? ` — ${route.description}` : ""
       }`
     );
-    if (currentStep.instructions) {
-      pc.addInstruction(
-        `Guideline for your response (adapt to the conversation):\n${currentStep.instructions}`
+    if (currentStep.prompt) {
+      await pc.addInstruction(
+        `Guideline for your response (adapt to the conversation):\n${await render(
+          currentStep.prompt,
+          templateContext
+        )}`
       );
     }
-    if (rules.length) pc.addInstruction(`Rules:\n- ${rules.join("\n- ")}`);
+    if (rules.length)
+      await pc.addInstruction(`Rules:\n- ${rules.join("\n- ")}`);
     if (prohibitions.length)
-      pc.addInstruction(`Prohibitions:\n- ${prohibitions.join("\n- ")}`);
-    pc.addDirectives(directives);
-    pc.addInteractionHistory(history);
-    pc.addLastMessage(lastMessage);
-    pc.addInstruction(
+      await pc.addInstruction(`Prohibitions:\n- ${prohibitions.join("\n- ")}`);
+    await pc.addDirectives(directives);
+    await pc.addKnowledgeBase(
+      agentOptions?.knowledgeBase,
+      route.getKnowledgeBase()
+    );
+
+    // Add combined guidelines (agent + route)
+    if (combinedGuidelines && combinedGuidelines.length > 0) {
+      await pc.addGuidelines(combinedGuidelines);
+    }
+
+    // Add combined terms (agent + route)
+    if (combinedTerms && combinedTerms.length > 0) {
+      await pc.addGlossary(combinedTerms);
+    }
+
+    await pc.addInteractionHistory(history);
+    await pc.addLastMessage(lastMessage);
+    await pc.addInstruction(
       "Return ONLY JSON matching the schema. The 'message' field is required."
     );
     return pc.build();
   }
+
+  async buildFallbackPrompt(
+    params: BuildFallbackPromptParams<TContext>
+  ): Promise<string> {
+    const { history, agentOptions, terms, guidelines, context, session } =
+      params;
+    const templateContext = { context, session, history };
+    const pc = new PromptComposer(templateContext);
+
+    await pc.addAgentMeta(agentOptions);
+    await pc.addInteractionHistory(history);
+    await pc.addGlossary(terms);
+    await pc.addGuidelines(guidelines);
+    await pc.addKnowledgeBase(agentOptions.knowledgeBase);
+    return pc.build();
+  }
 }