Loan Inquiry Agent

#!/usr/bin/env python3
"""
BimpeAI SDK — Loan Inquiry Agent (end-to-end)

Install:
    pip install bimpeai

Run:
    BIMPEAI_API_KEY=sk_... python notebooks/examples/bimpeai_sdk_usecase.py

Environment variables:
    BIMPEAI_API_KEY          (required) Your team API key (sk_...)
    BIMPE_DESTINATION_NUMBER (optional) E.164 number for outbound call demo
    BANKING_API_BASE_URL     (optional) Base URL for the custom API integration
"""

from __future__ import annotations

import json
import os
import uuid

from bimpeai import BimpeAI, ValidationError

# ---------------------------------------------------------------------------
# Step 1: Installation & Setup
# Initialize the synchronous client. The SDK does not read the API key from
# the environment automatically — pass it explicitly when constructing BimpeAI.
# ---------------------------------------------------------------------------

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

BANKING_API_BASE_URL = os.environ.get("BANKING_API_BASE_URL", "https://api.example.com/v1")
DESTINATION_NUMBER = os.environ.get("BIMPE_DESTINATION_NUMBER", "+15551234567")


def main() -> None:
    # -----------------------------------------------------------------------
    # Step 2: Create the Loan Agent Workflow
    # A workflow encodes conversation logic and the system prompt. The agent
    # binds to this workflow in the next step.
    # -----------------------------------------------------------------------

    loan_workflow = client.workflows.create(
        name="Loan Inquiry Rules",
        system_prompt=(
            "You are a professional banking virtual assistant specialized in loans. "
            "Your job is to gather initial information from customers regarding loan types "
            "(e.g., mortgage, personal, auto), explain basic interest rates, check "
            "eligibility rules, and assist them with their application status."
        ),
    )
    print(f"Workflow created with ID: {loan_workflow.id}")

    # -----------------------------------------------------------------------
    # Step 3: Provision and Configure the Agent
    # workflow_id, name, and description are required on create.
    # -----------------------------------------------------------------------

    loan_agent = client.agents.create(
        workflow_id=loan_workflow.id,
        name="Apex Loan Agent",
        description="Handles client inquiries regarding rates, eligibility, and loan status.",
        persona="professional",
        idempotency_key="create-apex-loan-agent-v1",
    )
    print(f"Agent provisioned with ID: {loan_agent.id}")

    # -----------------------------------------------------------------------
    # Step 4: Add a Knowledge Base (optional but recommended)
    # Grounds the agent in static loan terms it must quote accurately.
    # -----------------------------------------------------------------------

    client.agents.knowledge_bases.create(
        loan_agent.id,
        {
            "type": "text",
            "name": "2026 Loan Terms FAQ",
            "content": (
                "Personal Loan rates start at 5.5% APR. Minimum credit score required is 640. "
                "Mortgage down payments must be at least 3.5%. Maximum auto loan duration is 72 months."
            ),
        },
    )
    print("Knowledge base attached.")

    # -----------------------------------------------------------------------
    # Step 5: Connect a Custom API Tool & Integration (optional)
    # Register your core banking backend so the agent can look up application status.
    # See: /docs/use-cases/configuring-integrations#custom-http-apis-customapi
    # -----------------------------------------------------------------------

    banking_api = client.agents.integrations.custom_api.configure(
        agent_id=loan_agent.id,
        name="Core Banking Dashboard",
        base_url=BANKING_API_BASE_URL,
    )

    client.agents.integrations.custom_api.tools.add(
        loan_agent.id,
        banking_api.id,
        {
            "name": "Lookup Application Status",
            "http_method": "POST",
            "url_template": "/loans/status-lookup",
        },
    )
    print("Custom API integration configured.")

    # -----------------------------------------------------------------------
    # Step 6: Transition to production — go live
    # Move the agent from development to live once configuration is complete.
    # -----------------------------------------------------------------------

    client.agents.update_live_status(
        agent_id=loan_agent.id,
        status="live",
        status_reason="Deploying finalized loan desks helper agent to consumers.",
    )
    print("Agent is officially live!")

    # -----------------------------------------------------------------------
    # Step 7: Start testing / interaction (webchat)
    # conversations.send seeds or finds a conversation by channel identity.
    # channel_user_id should be stable per end-user session.
    # -----------------------------------------------------------------------

    channel_user_id = str(uuid.uuid4())

    print("\nStarting webchat conversation with BimpeAI Agent...")
    print("Type your message and hit Enter. Type 'exit' or 'quit' to end the chat.\n")

    initial_greet = client.conversations.send(
        agent_id=loan_agent.id,
        message="tell me about you?",
        channel_type="webchat",
        channel_user_id=channel_user_id,
    )
    print(f"Agent response: {initial_greet.message}")

    # Optional: extend to a full interactive REPL in the terminal.
    # while True:
    #     user_input = input("You: ").strip()
    #     if user_input.lower() in ("exit", "quit"):
    #         break
    #     reply = client.conversations.send(
    #         agent_id=loan_agent.id,
    #         message=user_input,
    #         channel_type="webchat",
    #         channel_user_id=channel_user_id,
    #     )
    #     print(f"Agent: {reply.message}")

    # -----------------------------------------------------------------------
    # Step 8: Link a phone number line and trigger a call
    # Request a number if none is pending review, link it to the agent, then
    # place an outbound call. Falls back to is_test_call=True when no approved
    # number is available yet.
    # -----------------------------------------------------------------------

    agent_id = loan_agent.id

    print("\nChecking for pending phone number requests...")
    has_pending_request = False
    requests_list: list = []

    try:
        requests_page = client.phone_numbers.requests.list()
        requests_list = requests_page.data

        for req in requests_list:
            status = getattr(req, "status", None)
            if status == "pending_review":
                has_pending_request = True
                break

    except ValidationError as err:
        # Fallback when Pydantic cannot parse pending requests missing e164.
        if err.raw_body:
            raw_json = err.raw_body.decode("utf-8") if isinstance(err.raw_body, bytes) else err.raw_body
            data = json.loads(raw_json)
            requests_list = data.get("data", [])

            for req in requests_list:
                if isinstance(req, dict) and req.get("status") == "pending_review":
                    has_pending_request = True
                    break

    if not has_pending_request:
        print("No pending review requests found. Requesting a new phone number...")
        client.phone_numbers.requests.create(
            business_name="Apex Bank Loan Desk",
            intended_use="Handling customer loan inquiries via inbound and outbound lines",
            region="uk",  # "us" | "uk" | "eu" | "ng"
            agent_count=1,
            outbound_minutes=1000,
        )
        print("Provisioning request submitted successfully.")
    else:
        print("An active request is currently 'pending_review'. Skipping new submission.")

    print("\nChecking if there is an approved phone number ready...")
    phone_number_id = None
    approved_number_e164 = None

    try:
        numbers_page = client.phone_numbers.list()
        if numbers_page.data:
            phone_number_id = numbers_page.data[0].id
            approved_number_e164 = numbers_page.data[0].e164
    except ValidationError:
        for req in requests_list:
            if isinstance(req, dict) and req.get("e164"):
                phone_number_id = req.get("id")
                approved_number_e164 = req.get("e164")
                break

    is_test = False

    if phone_number_id:
        print(f"Approved number found: {approved_number_e164}")
        print(f"Linking phone line (ID: {phone_number_id}) to Agent (ID: {agent_id})...")

        client.phone_numbers.update(
            phone_number_id,
            agent_id=agent_id,
            label="Loan Telephony Desk Line",
        )
        print("Line successfully connected!")
    else:
        print("No fully approved phone numbers are active yet.")
        print("Switching to test telephony mode.")
        is_test = True

    print(f"\nInitiating outbound call to {DESTINATION_NUMBER} (is_test_call={is_test})...")
    call_result = client.calls.make(
        agent_id=agent_id,
        body={
            "destination": DESTINATION_NUMBER,
            "is_test_call": is_test,
        },
    )

    print(f"Call dispatch status: {call_result.status}")
    if getattr(call_result, "call_id", None):
        print(f"Call tracking ID: {call_result.call_id}")


if __name__ == "__main__":
    main()

/**
 * BimpeAI SDK — Loan Inquiry Agent (end-to-end)
 *
 * Install:
 *   npm install @bimpeai/sdk
 *   npm install -D tsx   # to run this file directly
 *
 * Run:
 *   BIMPEAI_API_KEY=sk_... npx tsx notebooks/examples/bimpeai_sdk_usecase.ts
 *
 * Environment variables:
 *   BIMPEAI_API_KEY          (required) Your team API key (sk_...)
 *   BIMPE_DESTINATION_NUMBER (optional) E.164 number for outbound call demo
 *   BANKING_API_BASE_URL     (optional) Base URL for the custom API integration
 */

import { randomUUID } from "node:crypto";

import { BimpeAI, ValidationError } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

const BANKING_API_BASE_URL = process.env.BANKING_API_BASE_URL ?? "https://api.example.com/v1";
const DESTINATION_NUMBER = process.env.BIMPE_DESTINATION_NUMBER ?? "+15551234567";

function parseValidationBody(body: unknown): { data?: Array<Record<string, unknown>> } | null {
  if (body == null) return null;
  if (typeof body === "string") {
    try {
      return JSON.parse(body) as { data?: Array<Record<string, unknown>> };
    } catch {
      return null;
    }
  }
  if (typeof body === "object") {
    return body as { data?: Array<Record<string, unknown>> };
  }
  return null;
}

async function main(): Promise<void> {
  // -------------------------------------------------------------------------
  // Step 2: Create the Loan Agent Workflow
  // A workflow encodes conversation logic and the system prompt.
  // -------------------------------------------------------------------------

  const loanWorkflow = await bimpe.workflows.create({
    name: "Loan Inquiry Rules",
    system_prompt:
      "You are a professional banking virtual assistant specialized in loans. " +
      "Your job is to gather initial information from customers regarding loan types " +
      "(e.g., mortgage, personal, auto), explain basic interest rates, check " +
      "eligibility rules, and assist them with their application status.",
  });
  console.log(`Workflow created with ID: ${loanWorkflow.id}`);

  // -------------------------------------------------------------------------
  // Step 3: Provision and Configure the Agent
  // -------------------------------------------------------------------------

  const loanAgent = await bimpe.agents.create(
    {
      name: "Apex Loan Agent",
      description: "Handles client inquiries regarding rates, eligibility, and loan status.",
      workflow_id: loanWorkflow.id,
      persona: "professional",
    },
    { idempotencyKey: "create-apex-loan-agent-v1" },
  );
  console.log(`Agent provisioned with ID: ${loanAgent.id}`);

  // -------------------------------------------------------------------------
  // Step 4: Add a Knowledge Base (optional but recommended)
  // -------------------------------------------------------------------------

  await bimpe.agents.knowledgeBases.create(loanAgent.id, {
    type: "text",
    name: "2026 Loan Terms FAQ",
    content:
      "Personal Loan rates start at 5.5% APR. Minimum credit score required is 640. " +
      "Mortgage down payments must be at least 3.5%. Maximum auto loan duration is 72 months.",
  });
  console.log("Knowledge base attached.");

  // -------------------------------------------------------------------------
  // Step 5: Connect a Custom API Tool & Integration (optional)
  // -------------------------------------------------------------------------

  const bankingApi = await bimpe.agents.integrations.customApi.configure(loanAgent.id, {
    name: "Core Banking Dashboard",
    base_url: BANKING_API_BASE_URL,
  });

  await bimpe.agents.integrations.customApi.tools.add(loanAgent.id, bankingApi.id, {
    name: "Lookup Application Status",
    http_method: "POST",
    url_template: "/loans/status-lookup",
  });
  console.log("Custom API integration configured.");

  // -------------------------------------------------------------------------
  // Step 6: Transition to production — go live
  // -------------------------------------------------------------------------

  await bimpe.agents.updateLiveStatus(loanAgent.id, {
    status: "live",
    status_reason: "Deploying finalized loan desks helper agent to consumers.",
  });
  console.log("Agent is officially live!");

  // -------------------------------------------------------------------------
  // Step 7: Start testing / interaction (webchat)
  // -------------------------------------------------------------------------

  const channelUserId = randomUUID();

  console.log("\nStarting webchat conversation with BimpeAI Agent...");
  console.log("Type your message and hit Enter. Type 'exit' or 'quit' to end the chat.\n");

  const initialGreet = await bimpe.conversations.send(loanAgent.id, {
    message: "tell me about you?",
    channel_type: "webchat",
    channel_user_id: channelUserId,
  });
  console.log(`Agent response: ${initialGreet.message}`);

  // Optional: extend to a full interactive REPL in the terminal.
  // import * as readline from "node:readline/promises";
  // const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  // while (true) {
  //   const userInput = (await rl.question("You: ")).trim();
  //   if (userInput.toLowerCase() === "exit" || userInput.toLowerCase() === "quit") break;
  //   const reply = await bimpe.conversations.send(loanAgent.id, {
  //     message: userInput,
  //     channel_type: "webchat",
  //     channel_user_id: channelUserId,
  //   });
  //   console.log(`Agent: ${reply.message}`);
  // }
  // rl.close();

  // -------------------------------------------------------------------------
  // Step 8: Link a phone number line and trigger a call
  // -------------------------------------------------------------------------

  const agentId = loanAgent.id;

  console.log("\nChecking for pending phone number requests...");
  let hasPendingRequest = false;
  let requestsList: Array<Record<string, unknown>> = [];

  try {
    const requestsPage = await bimpe.phoneNumbers.requests.list();
    requestsList = requestsPage.data as Array<Record<string, unknown>>;

    for (const req of requestsPage.data) {
      const status = (req as { status?: string }).status;
      if (status === "pending_review") {
        hasPendingRequest = true;
        break;
      }
    }
  } catch (error) {
    if (error instanceof ValidationError) {
      const parsed = parseValidationBody(error.body);
      requestsList = parsed?.data ?? [];

      for (const req of requestsList) {
        if (req.status === "pending_review") {
          hasPendingRequest = true;
          break;
        }
      }
    } else {
      throw error;
    }
  }

  if (!hasPendingRequest) {
    console.log("No pending review requests found. Requesting a new phone number...");
    await bimpe.phoneNumbers.requests.create({
      business_name: "Apex Bank Loan Desk",
      intended_use: "Handling customer loan inquiries via inbound and outbound lines",
      region: "uk",
      agent_count: 1,
      outbound_minutes: 1000,
    });
    console.log("Provisioning request submitted successfully.");
  } else {
    console.log("An active request is currently 'pending_review'. Skipping new submission.");
  }

  console.log("\nChecking if there is an approved phone number ready...");
  let phoneNumberId: string | undefined;
  let approvedNumberE164: string | undefined;

  try {
    const numbersPage = await bimpe.phoneNumbers.list();
    if (numbersPage.data[0]) {
      phoneNumberId = numbersPage.data[0].id;
      approvedNumberE164 = numbersPage.data[0].e164;
    }
  } catch (error) {
    if (error instanceof ValidationError) {
      for (const req of requestsList) {
        if (req.e164) {
          phoneNumberId = req.id as string;
          approvedNumberE164 = req.e164 as string;
          break;
        }
      }
    } else {
      throw error;
    }
  }

  let isTest = false;

  if (phoneNumberId) {
    console.log(`Approved number found: ${approvedNumberE164}`);
    console.log(`Linking phone line (ID: ${phoneNumberId}) to Agent (ID: ${agentId})...`);

    await bimpe.phoneNumbers.update(phoneNumberId, {
      agent_id: agentId,
      label: "Loan Telephony Desk Line",
    });
    console.log("Line successfully connected!");
  } else {
    console.log("No fully approved phone numbers are active yet.");
    console.log("Switching to test telephony mode.");
    isTest = true;
  }

  console.log(`\nInitiating outbound call to ${DESTINATION_NUMBER} (is_test_call=${isTest})...`);
  const callResult = await bimpe.calls.make(agentId, {
    destination: DESTINATION_NUMBER,
    is_test_call: isTest,
  });

  console.log(`Call dispatch status: ${callResult.status}`);
  if (callResult.call_id) {
    console.log(`Call tracking ID: ${callResult.call_id}`);
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

/**
 * BimpeAI SDK — Loan Inquiry Agent (end-to-end)
 *
 * Install:
 *   npm install @bimpeai/sdk
 *
 * Run:
 *   BIMPEAI_API_KEY=sk_... node notebooks/examples/bimpeai_sdk_usecase.mjs
 *   # or: node --env-file=.env notebooks/examples/bimpeai_sdk_usecase.mjs
 *
 * Environment variables:
 *   BIMPEAI_API_KEY          (required) Your team API key (sk_...)
 *   BIMPE_DESTINATION_NUMBER (optional) E.164 number for outbound call demo
 *   BANKING_API_BASE_URL     (optional) Base URL for the custom API integration
 */

import { randomUUID } from "node:crypto";

import { BimpeAI, ValidationError } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY });

const BANKING_API_BASE_URL = process.env.BANKING_API_BASE_URL ?? "https://api.example.com/v1";
const DESTINATION_NUMBER = process.env.BIMPE_DESTINATION_NUMBER ?? "+15551234567";

function parseValidationBody(body) {
  if (body == null) return null;
  if (typeof body === "string") {
    try {
      return JSON.parse(body);
    } catch {
      return null;
    }
  }
  if (typeof body === "object") {
    return body;
  }
  return null;
}

async function main() {
  // -------------------------------------------------------------------------
  // Step 2: Create the Loan Agent Workflow
  // A workflow encodes conversation logic and the system prompt.
  // -------------------------------------------------------------------------

  const loanWorkflow = await bimpe.workflows.create({
    name: "Loan Inquiry Rules",
    system_prompt:
      "You are a professional banking virtual assistant specialized in loans. " +
      "Your job is to gather initial information from customers regarding loan types " +
      "(e.g., mortgage, personal, auto), explain basic interest rates, check " +
      "eligibility rules, and assist them with their application status.",
  });
  console.log(`Workflow created with ID: ${loanWorkflow.id}`);

  // -------------------------------------------------------------------------
  // Step 3: Provision and Configure the Agent
  // -------------------------------------------------------------------------

  const loanAgent = await bimpe.agents.create(
    {
      name: "Apex Loan Agent",
      description: "Handles client inquiries regarding rates, eligibility, and loan status.",
      workflow_id: loanWorkflow.id,
      persona: "professional",
    },
    { idempotencyKey: "create-apex-loan-agent-v1" },
  );
  console.log(`Agent provisioned with ID: ${loanAgent.id}`);

  // -------------------------------------------------------------------------
  // Step 4: Add a Knowledge Base (optional but recommended)
  // -------------------------------------------------------------------------

  await bimpe.agents.knowledgeBases.create(loanAgent.id, {
    type: "text",
    name: "2026 Loan Terms FAQ",
    content:
      "Personal Loan rates start at 5.5% APR. Minimum credit score required is 640. " +
      "Mortgage down payments must be at least 3.5%. Maximum auto loan duration is 72 months.",
  });
  console.log("Knowledge base attached.");

  // -------------------------------------------------------------------------
  // Step 5: Connect a Custom API Tool & Integration (optional)
  // -------------------------------------------------------------------------

  const bankingApi = await bimpe.agents.integrations.customApi.configure(loanAgent.id, {
    name: "Core Banking Dashboard",
    base_url: BANKING_API_BASE_URL,
  });

  await bimpe.agents.integrations.customApi.tools.add(loanAgent.id, bankingApi.id, {
    name: "Lookup Application Status",
    http_method: "POST",
    url_template: "/loans/status-lookup",
  });
  console.log("Custom API integration configured.");

  // -------------------------------------------------------------------------
  // Step 6: Transition to production — go live
  // -------------------------------------------------------------------------

  await bimpe.agents.updateLiveStatus(loanAgent.id, {
    status: "live",
    status_reason: "Deploying finalized loan desks helper agent to consumers.",
  });
  console.log("Agent is officially live!");

  // -------------------------------------------------------------------------
  // Step 7: Start testing / interaction (webchat)
  // -------------------------------------------------------------------------

  const channelUserId = randomUUID();

  console.log("\nStarting webchat conversation with BimpeAI Agent...");
  console.log("Type your message and hit Enter. Type 'exit' or 'quit' to end the chat.\n");

  const initialGreet = await bimpe.conversations.send(loanAgent.id, {
    message: "tell me about you?",
    channel_type: "webchat",
    channel_user_id: channelUserId,
  });
  console.log(`Agent response: ${initialGreet.message}`);

  // Optional: extend to a full interactive REPL in the terminal.
  // import * as readline from "node:readline/promises";
  // const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  // while (true) {
  //   const userInput = (await rl.question("You: ")).trim();
  //   if (userInput.toLowerCase() === "exit" || userInput.toLowerCase() === "quit") break;
  //   const reply = await bimpe.conversations.send(loanAgent.id, {
  //     message: userInput,
  //     channel_type: "webchat",
  //     channel_user_id: channelUserId,
  //   });
  //   console.log(`Agent: ${reply.message}`);
  // }
  // rl.close();

  // -------------------------------------------------------------------------
  // Step 8: Link a phone number line and trigger a call
  // -------------------------------------------------------------------------

  const agentId = loanAgent.id;

  console.log("\nChecking for pending phone number requests...");
  let hasPendingRequest = false;
  let requestsList = [];

  try {
    const requestsPage = await bimpe.phoneNumbers.requests.list();
    requestsList = requestsPage.data;

    for (const req of requestsPage.data) {
      if (req.status === "pending_review") {
        hasPendingRequest = true;
        break;
      }
    }
  } catch (error) {
    if (error instanceof ValidationError) {
      const parsed = parseValidationBody(error.body);
      requestsList = parsed?.data ?? [];

      for (const req of requestsList) {
        if (req.status === "pending_review") {
          hasPendingRequest = true;
          break;
        }
      }
    } else {
      throw error;
    }
  }

  if (!hasPendingRequest) {
    console.log("No pending review requests found. Requesting a new phone number...");
    await bimpe.phoneNumbers.requests.create({
      business_name: "Apex Bank Loan Desk",
      intended_use: "Handling customer loan inquiries via inbound and outbound lines",
      region: "uk",
      agent_count: 1,
      outbound_minutes: 1000,
    });
    console.log("Provisioning request submitted successfully.");
  } else {
    console.log("An active request is currently 'pending_review'. Skipping new submission.");
  }

  console.log("\nChecking if there is an approved phone number ready...");
  let phoneNumberId;
  let approvedNumberE164;

  try {
    const numbersPage = await bimpe.phoneNumbers.list();
    if (numbersPage.data[0]) {
      phoneNumberId = numbersPage.data[0].id;
      approvedNumberE164 = numbersPage.data[0].e164;
    }
  } catch (error) {
    if (error instanceof ValidationError) {
      for (const req of requestsList) {
        if (req.e164) {
          phoneNumberId = req.id;
          approvedNumberE164 = req.e164;
          break;
        }
      }
    } else {
      throw error;
    }
  }

  let isTest = false;

  if (phoneNumberId) {
    console.log(`Approved number found: ${approvedNumberE164}`);
    console.log(`Linking phone line (ID: ${phoneNumberId}) to Agent (ID: ${agentId})...`);

    await bimpe.phoneNumbers.update(phoneNumberId, {
      agent_id: agentId,
      label: "Loan Telephony Desk Line",
    });
    console.log("Line successfully connected!");
  } else {
    console.log("No fully approved phone numbers are active yet.");
    console.log("Switching to test telephony mode.");
    isTest = true;
  }

  console.log(`\nInitiating outbound call to ${DESTINATION_NUMBER} (is_test_call=${isTest})...`);
  const callResult = await bimpe.calls.make(agentId, {
    destination: DESTINATION_NUMBER,
    is_test_call: isTest,
  });

  console.log(`Call dispatch status: ${callResult.status}`);
  if (callResult.call_id) {
    console.log(`Call tracking ID: ${callResult.call_id}`);
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});