@falai/agent 0.1.0

package/docs/STRUCTURE.md

@@ -0,0 +1,32 @@
+# Package Structure
+
+\`\`\`
+src/
+├── types/          # Type definitions (interfaces, types, enums)
+├── core/           # Core framework classes
+│   ├── Agent.ts           # Main agent class
+│   ├── Route.ts           # Route/Journey DSL
+│   ├── State.ts           # State management
+│   ├── Transition.ts      # State transitions
+│   ├── Observation.ts     # Disambiguation
+│   ├── Tool.ts            # Tool definitions
+│   ├── PromptBuilder.ts   # Prompt construction
+│   ├── Events.ts          # Event history
+│   └── DomainRegistry.ts  # Domain organization
+├── providers/      # AI provider implementations
+│   └── GeminiProvider.ts  # Google Gemini AI
+├── utils/          # Utility functions
+│   └── retry.ts           # Retry/timeout logic
+├── constants/      # Constants and symbols
+│   └── index.ts           # END_ROUTE, etc.
+└── index.ts        # Public API exports
+\`\`\`
+
+## Design Principles
+
+1. **Flat, organized structure** - Clear separation by purpose
+2. **Types-first** - All types in dedicated folder
+3. **Core logic isolated** - Business logic in \`core/\`
+4. **Provider pattern** - Pluggable AI backends
+5. **Path aliases** - Clean imports with \`@/types\`, \`@/core\`, etc.
+6. **Fluent API** - Methods return \`this\` for chaining

package/examples/declarative-agent.ts

@@ -0,0 +1,217 @@
+/**
+ * Example: Declarative Agent Configuration
+ *
+ * This example demonstrates how to configure an entire agent
+ * using declarative syntax in the constructor, including:
+ * - Terms (glossary)
+ * - Guidelines (behavior rules)
+ * - Capabilities
+ * - Routes with nested guidelines
+ * - Observations with route references
+ */
+
+import {
+  Agent,
+  GeminiProvider,
+  defineTool,
+  createMessageEvent,
+  EventSource,
+  type Term,
+  type Guideline,
+  type Capability,
+  type RouteOptions,
+  type ObservationOptions,
+} from "../src/index";
+
+// Context type
+interface HealthcareContext {
+  patientId: string;
+  patientName: string;
+}
+
+// Define tools
+const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>(
+  "get_insurance_providers",
+  async () => {
+    return { data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"] };
+  },
+  { description: "Retrieves list of accepted insurance providers" }
+);
+
+const getAvailableSlots = defineTool<
+  HealthcareContext,
+  [],
+  { date: string; time: string }[]
+>(
+  "get_available_slots",
+  async () => {
+    return {
+      data: [
+        { date: "2025-10-20", time: "10:00 AM" },
+        { date: "2025-10-20", time: "2:00 PM" },
+        { date: "2025-10-21", time: "1:00 PM" },
+      ],
+    };
+  },
+  { description: "Gets available appointment slots" }
+);
+
+const getLabResults = defineTool<
+  HealthcareContext,
+  [],
+  { report: string; status: string }
+>(
+  "get_lab_results",
+  async ({ context }) => {
+    return {
+      data: {
+        report: `Lab results for ${context.patientName}`,
+        status: "All values within normal range",
+      },
+    };
+  },
+  { description: "Retrieves patient lab results" }
+);
+
+// Declarative configuration
+const terms: Term[] = [
+  {
+    name: "Office Phone Number",
+    description: "The phone number of our office, at +1-234-567-8900",
+  },
+  {
+    name: "Office Hours",
+    description: "Office hours are Monday to Friday, 9 AM to 5 PM",
+  },
+  {
+    name: "Dr. Charles Xavier",
+    description: "Neurologist specializing in brain disorders",
+    synonyms: ["Professor X", "Dr. Xavier"],
+  },
+];
+
+const guidelines: Guideline[] = [
+  {
+    condition: "The patient asks about insurance",
+    action:
+      "List the insurance providers we accept and tell them to call the office for more details",
+    tools: [getInsuranceProviders],
+    tags: ["insurance", "billing"],
+  },
+  {
+    condition: "The patient asks to talk to a human agent",
+    action: "Provide the office phone number and office hours",
+    tags: ["escalation"],
+  },
+  {
+    condition: "The patient inquires about something unrelated to healthcare",
+    action:
+      "Kindly tell them you cannot assist with off-topic inquiries - do not engage",
+    tags: ["off-topic"],
+  },
+];
+
+const capabilities: Capability[] = [
+  {
+    title: "Appointment Scheduling",
+    description: "Schedule, reschedule, or cancel patient appointments",
+    tools: [getAvailableSlots],
+  },
+  {
+    title: "Lab Results Access",
+    description: "Retrieve and explain patient lab results",
+    tools: [getLabResults],
+  },
+];
+
+const routes: RouteOptions[] = [
+  {
+    title: "Schedule Appointment",
+    description: "Helps the patient schedule an appointment",
+    conditions: ["The patient wants to schedule an appointment"],
+    guidelines: [
+      {
+        condition: "The patient says their visit is urgent",
+        action: "Tell them to call the office immediately",
+        tags: ["urgent"],
+        enabled: true,
+      },
+    ],
+  },
+  {
+    title: "Check Lab Results",
+    description: "Retrieves and explains patient lab results",
+    conditions: ["The patient wants to see their lab results"],
+    guidelines: [
+      {
+        condition: "The patient presses for more conclusions about results",
+        action:
+          "Assertively tell them they should call the office to speak with a doctor",
+        tags: ["escalation"],
+      },
+    ],
+  },
+];
+
+const observations: ObservationOptions[] = [
+  {
+    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
+  },
+];
+
+// Create the fully configured agent
+const agent = new Agent<HealthcareContext>({
+  name: "HealthBot",
+  description: "A compassionate healthcare assistant",
+  goal: "Provide helpful information and assist with appointments",
+  context: {
+    patientId: "p_12345",
+    patientName: "Alice Johnson",
+  },
+  ai: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "demo-key",
+  }),
+  // Declarative initialization
+  terms,
+  guidelines,
+  capabilities,
+  routes,
+  observations,
+});
+
+// You can still add more dynamically after construction
+agent
+  .createGuideline({
+    condition: "The patient seems confused or distressed",
+    action: "Speak slowly, clearly, and offer to connect them with a human",
+    tags: ["empathy", "support"],
+  })
+  .createTerm({
+    name: "Telemedicine",
+    description: "Remote medical consultation via video call",
+    synonyms: ["virtual visit", "video appointment"],
+  });
+
+// Example usage
+async function main() {
+  const history = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Alice",
+      "Hi, I need to follow up on my recent visit"
+    ),
+  ];
+
+  const response = await agent.respond({ history });
+  console.log("Agent:", response.message);
+
+  // The agent will use the observation to disambiguate
+  // and ask which type of follow-up the patient needs
+}
+
+// Uncomment to run:
+// main().catch(console.error);
+
+export { agent };

package/examples/healthcare-agent.ts

@@ -0,0 +1,283 @@
+/**
+ * Healthcare agent example demonstrating observations and disambiguation
+ */
+
+import {
+  Agent,
+  defineTool,
+  GeminiProvider,
+  END_ROUTE,
+  EventSource,
+  createMessageEvent,
+} from "../src/index";
+
+// Context type
+interface HealthcareContext {
+  patientId: string;
+  patientName: string;
+}
+
+// Tools
+const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>(
+  "get_insurance_providers",
+  async () => {
+    return { data: ["Mega Insurance", "Acme Insurance"] };
+  },
+  { description: "Get list of accepted insurance providers" }
+);
+
+const getUpcomingSlots = defineTool<HealthcareContext, [], string[]>(
+  "get_upcoming_slots",
+  async () => {
+    return { data: ["Monday 10 AM", "Tuesday 2 PM", "Wednesday 1 PM"] };
+  },
+  { description: "Get upcoming appointment slots" }
+);
+
+const getLaterSlots = defineTool<HealthcareContext, [], string[]>(
+  "get_later_slots",
+  async () => {
+    return { data: ["November 3, 11:30 AM", "November 12, 3 PM"] };
+  },
+  { description: "Get later appointment slots" }
+);
+
+const scheduleAppointment = defineTool<
+  HealthcareContext,
+  [datetime: string],
+  string
+>("schedule_appointment", async (_, datetime) => {
+  return { data: `Appointment scheduled for ${datetime}` };
+});
+
+const getLabResults = defineTool<HealthcareContext, [], object>(
+  "get_lab_results",
+  async ({ context }) => {
+    return {
+      data: {
+        report: "All tests are within the valid range",
+        prognosis: "Patient is healthy as a horse!",
+      },
+    };
+  }
+);
+
+async function createHealthcareAgent() {
+  const provider = new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "test-key",
+    model: "models/gemini-2.5-flash",
+  });
+
+  const agent = new Agent<HealthcareContext>({
+    name: "Healthcare Agent",
+    description: "Is empathetic and calming to the patient.",
+    ai: provider,
+    context: {
+      patientId: "patient-123",
+      patientName: "Test Patient",
+    },
+  });
+
+  // Add domain glossary
+  agent.createTerm({
+    name: "Office Phone Number",
+    description: "The phone number of our office, at +1-234-567-8900",
+  });
+
+  agent.createTerm({
+    name: "Office Hours",
+    description: "Office hours are Monday to Friday, 9 AM to 5 PM",
+  });
+
+  agent.createTerm({
+    name: "Charles Xavier",
+    synonyms: ["Professor X"],
+    description:
+      "The doctor who specializes in neurology and is available on Mondays and Tuesdays.",
+  });
+
+  // Create scheduling route
+  const schedulingRoute = agent.createRoute({
+    title: "Schedule an Appointment",
+    description: "Helps the patient find a time for their appointment.",
+    conditions: ["The patient wants to schedule an appointment"],
+  });
+
+  const t0 = schedulingRoute.initialState.transitionTo({
+    chatState: "Determine the reason for the visit",
+  });
+
+  const t1 = t0.target.transitionTo({
+    toolState: getUpcomingSlots,
+  });
+
+  const t2 = t1.target.transitionTo({
+    chatState: "List available times and ask which ones works for them",
+  });
+
+  const t3 = t2.target.transitionTo(
+    {
+      chatState: "Confirm the details with the patient before scheduling",
+    },
+    "The patient picks a time"
+  );
+
+  const t4 = t3.target.transitionTo(
+    {
+      toolState: scheduleAppointment,
+    },
+    "The patient confirms the details"
+  );
+
+  const t5 = t4.target.transitionTo({
+    chatState: "Confirm the appointment has been scheduled",
+  });
+
+  t5.target.transitionTo({ state: END_ROUTE });
+
+  // Alternative path: no times work
+  const t6 = t2.target.transitionTo(
+    {
+      toolState: getLaterSlots,
+    },
+    "None of those times work for the patient"
+  );
+
+  const t7 = t6.target.transitionTo({
+    chatState: "List later times and ask if any of them works",
+  });
+
+  t7.target.transitionTo(
+    {
+      state: t3.target,
+    },
+    "The patient picks a time"
+  );
+
+  const t8 = t7.target.transitionTo(
+    {
+      chatState:
+        "Ask the patient to call the office to schedule an appointment",
+    },
+    "None of those times work for the patient either"
+  );
+
+  t8.target.transitionTo({ state: END_ROUTE });
+
+  schedulingRoute.createGuideline({
+    condition: "The patient says their visit is urgent",
+    action: "Tell them to call the office immediately",
+  });
+
+  // Create lab results route
+  const labResultsRoute = agent.createRoute({
+    title: "Lab Results",
+    description: "Retrieves the patient's lab results and explains them.",
+    conditions: ["The patient wants to see their lab results"],
+  });
+
+  const l0 = labResultsRoute.initialState.transitionTo({
+    toolState: getLabResults,
+  });
+
+  l0.target.transitionTo(
+    {
+      chatState:
+        "Tell the patient that the results are not available yet, and to try again later",
+    },
+    "The lab results could not be found"
+  );
+
+  l0.target.transitionTo(
+    {
+      chatState:
+        "Explain the lab results to the patient - that they are normal",
+    },
+    "The lab results are good - i.e., nothing to worry about"
+  );
+
+  l0.target.transitionTo(
+    {
+      chatState:
+        "Present the results and ask them to call the office for clarifications on the results as you are not a doctor",
+    },
+    "The lab results are not good - i.e., there's an issue with the patient's health"
+  );
+
+  labResultsRoute.createGuideline({
+    condition:
+      "The patient presses you for more conclusions about the lab results",
+    action:
+      "Assertively tell them that you cannot help and they should call the office",
+  });
+
+  // Create observation for disambiguation
+  const statusInquiry = agent.createObservation(
+    "The patient asks to follow up on their visit, but it's not clear in which way"
+  );
+
+  // Use observation to disambiguate between the two routes
+  statusInquiry.disambiguate([schedulingRoute, labResultsRoute]);
+
+  // Global guidelines
+  agent.createGuideline({
+    condition: "The patient asks about insurance",
+    action:
+      "List the insurance providers we accept, and tell them to call the office for more details",
+    tools: [getInsuranceProviders],
+  });
+
+  agent.createGuideline({
+    condition: "The patient asks to talk to a human agent",
+    action: "Ask them to call the office, providing the phone number",
+  });
+
+  agent.createGuideline({
+    condition:
+      "The patient inquires about something that has nothing to do with our healthcare",
+    action:
+      "Kindly tell them you cannot assist with off-topic inquiries - do not engage with their request.",
+  });
+
+  return agent;
+}
+
+// Example usage
+async function main() {
+  const agent = await createHealthcareAgent();
+
+  const history = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Patient",
+      "Hi, I need to follow up on my visit"
+    ),
+  ];
+
+  console.log("Agent:", agent.name);
+  console.log("Description:", agent.description);
+  console.log("\nRoutes:", agent.getRoutes().length);
+  console.log("Terms:", agent.getTerms().length);
+  console.log("Guidelines:", agent.getGuidelines().length);
+  console.log("Observations:", agent.getObservations().length);
+
+  // Print routes
+  const routes = agent.getRoutes();
+  for (const route of routes) {
+    console.log("\n" + route.describe());
+  }
+
+  // Print observations
+  console.log("\nObservations:");
+  for (const obs of agent.getObservations()) {
+    console.log(
+      `- "${obs.description}" (disambiguates ${obs.getRoutes().length} routes)`
+    );
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { createHealthcareAgent };

package/examples/openai-agent.ts

@@ -0,0 +1,167 @@
+/**
+ * Example: OpenAI Agent with multiple providers
+ *
+ * This example demonstrates how to use the OpenAI provider
+ * and how to switch between different AI providers
+ */
+
+import {
+  Agent,
+  OpenAIProvider,
+  defineTool,
+  createMessageEvent,
+  EventSource,
+} from "../src/index";
+
+// Custom context type
+interface CustomerContext {
+  customerId: string;
+  name: string;
+  preferences: string[];
+}
+
+// Define a simple tool
+const getWeather = defineTool<
+  CustomerContext,
+  [{ location: string }],
+  { location: string; temperature: number; condition: string }
+>(
+  "get_weather",
+  async (_context, args) => {
+    // Simulate API call
+    return {
+      data: {
+        location: args.location,
+        temperature: 72,
+        condition: "Sunny",
+      },
+    };
+  },
+  {
+    description: "Get current weather for a location",
+    parameters: {
+      location: { type: "string", description: "City name" },
+    },
+  }
+);
+
+async function main() {
+  // Initialize OpenAI provider
+  const openaiProvider = new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY || "",
+    model: "gpt-5", // Latest model
+    config: {
+      temperature: 0.7,
+      max_tokens: 1000,
+    },
+    // Optional: customize backup models
+    backupModels: ["gpt-5-mini", "gpt-5-nano"],
+    // Optional: customize retry config
+    retryConfig: {
+      timeout: 30000,
+      retries: 2,
+    },
+  });
+
+  // Create agent with OpenAI
+  const agent = new Agent<CustomerContext>({
+    name: "Assistant",
+    description:
+      "A helpful AI assistant that can check weather and answer questions",
+    goal: "Assist users with information and weather queries",
+    context: {
+      customerId: "user123",
+      name: "Alice",
+      preferences: ["concise answers", "weather updates"],
+    },
+    ai: openaiProvider,
+  });
+
+  // Add domain knowledge
+  agent
+    .createTerm({
+      name: "Weather Service",
+      description: "Our real-time weather information service",
+      synonyms: ["weather API", "forecast service"],
+    })
+    .createGuideline({
+      action:
+        "Always provide temperature in Fahrenheit and include the current condition",
+      tags: ["weather", "formatting"],
+      enabled: true,
+    })
+    .createGuideline({
+      condition: "User asks for weather in multiple cities",
+      action: "Offer to check weather for each city one by one",
+      enabled: true,
+    });
+
+  // Create a simple route
+  const weatherRoute = agent.createRoute({
+    title: "Check Weather",
+    description: "Help user check weather for a location",
+    conditions: ["User wants to know the weather"],
+  });
+
+  // Add states and transitions
+  const askLocation = weatherRoute.initialState.transitionTo({
+    chatState: "Ask which city they want weather for",
+  });
+
+  const fetchWeather = askLocation.target.transitionTo({
+    toolState: getWeather,
+    condition: "User provides a city name",
+  });
+
+  const showWeather = fetchWeather.target.transitionTo({
+    chatState:
+      "Present the weather information in a friendly way with temperature and condition",
+  });
+
+  // Simulate a conversation
+  console.log("🤖 Starting OpenAI Agent Example\n");
+
+  // Build history
+  const history = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Alice",
+      "What's the weather like in San Francisco?"
+    ),
+  ];
+
+  try {
+    // Generate response (this would call OpenAI)
+    console.log("📤 Sending request to OpenAI...");
+
+    // In a real scenario, you would call agent.generateMessage() or similar
+    // For now, let's just show the structure:
+    console.log("\n✅ Agent Configuration:");
+    console.log(`   AI Provider: ${openaiProvider.name}`);
+
+    console.log("\n🗺️  Route Configuration:");
+    console.log(`   Title: ${weatherRoute.title}`);
+    console.log(
+      `   States: Initial → Ask Location → Fetch Weather → Show Weather`
+    );
+
+    console.log("\n💬 Conversation History:");
+    history.forEach((event, i) => {
+      console.log(`   ${i + 1}. ${event.source}: ${event.data.message}`);
+    });
+
+    console.log("\n✨ Ready to process with OpenAI provider!");
+    console.log(
+      "   (Set OPENAI_API_KEY environment variable to make actual API calls)"
+    );
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { main };