lendctl-ai 0.2.0 → 0.2.1

package/README.md

@@ -1,22 +1,23 @@
 # LendCtl AI
 
-🏦 **Autonomous Lending Decision Agent** — powered by the [LendCtl CLI Suite](https://github.com/rsatyan/lendctl-skill)
+🏦 **Autonomous Lending Decision Agent** — Ask lending questions in plain English. Get instant, compliant decisions.
 
 [![npm version](https://img.shields.io/npm/v/lendctl-ai.svg)](https://www.npmjs.com/package/lendctl-ai)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-Ask lending questions in plain English. Get instant, compliant decisions with full audit trails.
-
 ```bash
-lendctl-ai ask "Can I qualify for a $400k mortgage with $90k income and 720 credit?"
+npm install -g lendctl-ai
+lendctl-ai ask 'Can I qualify for a $400k mortgage with $90k income and 720 credit?'
 ```
 
+> ⚠️ **Note:** Use single quotes around questions with `$` signs to prevent shell variable expansion.
+
 ## Features
 
 - 🤖 **Natural Language Interface** — Ask lending questions like you'd ask a loan officer
-- 📋 **Autonomous Planning** — Decomposes complex questions into tool calls
+- 📋 **Autonomous Planning** — Decomposes complex questions into calculations
 - ✅ **Self-Validation** — Verifies calculations and compliance automatically
-- 📊 **8 Integrated Tools** — Income, credit, mortgage, auto, personal, card, compliance, audit
+- 📊 **8 Built-in Calculators** — Income, credit, mortgage, auto, personal, card, compliance, audit
 - 📝 **Audit Trail** — Every decision logged for regulatory compliance
 - 🔌 **Multi-Channel** — CLI, REST API, WhatsApp, Telegram
 
@@ -27,10 +28,10 @@ lendctl-ai ask "Can I qualify for a $400k mortgage with $90k income and 720 cred
 npm install -g lendctl-ai
 
 # Set your OpenAI API key
-export OPENAI_API_KEY=your-key
+export OPENAI_API_KEY=sk-...
 
-# Ask a question
-lendctl-ai ask "I make $85,000/year with a 720 credit score. Can I afford a $350,000 house?"
+# Ask a question (use single quotes for $ signs!)
+lendctl-ai ask 'I make $85,000/year with a 720 credit score. Can I afford a $350,000 house?'
 
 # Interactive chat
 lendctl-ai chat
@@ -41,10 +42,12 @@ lendctl-ai serve
 
 ## Example
 
+```bash
+$ lendctl-ai ask 'I make $85,000/year and want to buy a $350,000 home with 10% down. I have a 720 credit score and $400/month in car payments.'
 ```
-$ lendctl-ai ask "I make $85,000/year and want to buy a $350,000 home with 10% down. 
-                  I have a 720 credit score and $400/month in car payments."
 
+Output:
+```
 ╔═══════════════════════════════════════════════════════════╗
 ║  LendCtl AI - Autonomous Lending Decision Agent           ║
 ╚═══════════════════════════════════════════════════════════╝
@@ -81,20 +84,22 @@ Session: lendctl-abc123
 Iterations: 1 | Time: 4823ms
 ```
 
-## Integrated Tools
+## Built-in Calculators
+
+All calculations run locally — no external CLI tools required.
 
-| Tool | Description |
-|------|-------------|
+| Calculator | Description |
+|------------|-------------|
 | `finctl` | Income analysis, DTI calculation |
-| `creditctl` | Credit score analysis, rapid rescore simulation |
+| `creditctl` | Credit score analysis, risk tier, rescore simulation |
 | `mortctl` | Mortgage qualification, LTV, PMI, amortization |
-| `autoloanctl` | Auto loan calculations, GAP insurance |
-| `persctl` | Personal loan eligibility, debt consolidation |
+| `autoloanctl` | Auto loan calculations, GAP insurance recommendations |
+| `persctl` | Personal loan eligibility, debt consolidation analysis |
 | `cardctl` | Credit limit estimation, balance transfer analysis |
-| `compctl` | QM/ATR validation, TRID timing, adverse action |
-| `auditctl` | Immutable audit trail, compliance exports |
+| `compctl` | QM/ATR validation, TRID timing, adverse action notices |
+| `auditctl` | In-memory audit trail, compliance exports |
 
-## API
+## API Server
 
 Start the server:
 
@@ -108,7 +113,7 @@ Query endpoint:
 curl -X POST http://localhost:5055/api/v1/query \
   -H "Content-Type: application/json" \
   -d '{
-    "question": "Can I qualify for a $400k mortgage with $90k income?",
+    "question": "Can I qualify for a 400k mortgage with 90k income?",
     "model": "gpt-4o",
     "stream": false
   }'
@@ -138,10 +143,10 @@ Response:
 ## Architecture
 
 ```
-User Query → Planner (LLM) → Executor (Tools) → Validator → Reporter
+User Query → Planner (LLM) → Executor (Calculators) → Validator → Reporter
                                     ↓
                         ┌──────────────────────┐
-                        │   LendCtl CLI Suite  │
+                        │   Built-in Tools     │
                         │ finctl · creditctl   │
                         │ mortctl · autoloanctl│
                         │ persctl · cardctl    │
@@ -151,8 +156,6 @@ User Query → Planner (LLM) → Executor (Tools) → Validator → Reporter
 
 ## Configuration
 
-Environment variables:
-
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `OPENAI_API_KEY` | OpenAI API key (required) | - |
@@ -172,11 +175,10 @@ lendctl-ai eval --sample 5
 
 ## Related
 
-- [LendCtl Suite](https://github.com/rsatyan/lendctl-skill) — The 8 CLI tools powering this agent
-- [finctl](https://github.com/rsatyan/finctl) — Income & DTI calculator
-- [creditctl](https://github.com/rsatyan/creditctl) — Credit report analyzer
-- [mortctl](https://github.com/rsatyan/mortctl) — Mortgage underwriting
-- [compctl](https://github.com/rsatyan/compctl) — Compliance checker
+- [LendCtl Skill](https://github.com/rsatyan/lendctl-skill) — AI agent skill with 6 workflows
+- [finctl](https://github.com/rsatyan/finctl) — Standalone income & DTI CLI
+- [creditctl](https://github.com/rsatyan/creditctl) — Standalone credit analysis CLI
+- [mortctl](https://github.com/rsatyan/mortctl) — Standalone mortgage underwriting CLI
 
 ## License
 

package/dist/index.js

@@ -25220,33 +25220,90 @@ ${source_default.cyan("║")}  ${source_default.bold.white("LendCtl AI")} - Auto
 ${source_default.cyan("║")}  ${source_default.gray("Powered by LendCtl CLI Suite")}                            ${source_default.cyan("║")}
 ${source_default.cyan("╚═══════════════════════════════════════════════════════════╝")}
 `;
-program2.name("lendctl-ai").description("Autonomous lending decision agent powered by LendCtl CLI suite").version("0.2.0");
-program2.command("ask").description("Ask a lending question").argument("<question>", "Your lending question").option("-m, --model <model>", "LLM model to use", "gpt-4o").option("-i, --iterations <n>", "Max planning iterations", "3").option("-v, --verbose", "Show detailed output").option("--quick", "Quick mode (skip LLM report generation)").action(async (question, options) => {
-  console.log(banner);
+function renderMarkdownToTerminal(md) {
+  let result = md;
+  result = result.replace(/^### (.+)$/gm, (_, h) => source_default.bold.underline(h));
+  result = result.replace(/^## (.+)$/gm, (_, h) => source_default.bold.cyan(h));
+  result = result.replace(/^# (.+)$/gm, (_, h) => source_default.bold.cyan.underline(h));
+  result = result.replace(/\*\*([^*]+)\*\*/g, (_, t) => source_default.bold(t));
+  result = result.replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, (_, t) => source_default.italic(t));
+  result = result.replace(/_([^_]+)_/g, (_, t) => source_default.italic(t));
+  result = result.replace(/`([^`]+)`/g, (_, c) => source_default.yellow(c));
+  result = result.replace(/^- (.+)$/gm, (_, item) => `  ${source_default.cyan("•")} ${item}`);
+  result = result.replace(/^\* (.+)$/gm, (_, item) => `  ${source_default.cyan("•")} ${item}`);
+  result = result.replace(/^(\d+)\. (.+)$/gm, (_, num, item) => `  ${source_default.cyan(num + ".")} ${item}`);
+  result = result.replace(/✓/g, source_default.green("✓"));
+  result = result.replace(/✗/g, source_default.red("✗"));
+  result = result.replace(/⚠️/g, source_default.yellow("⚠"));
+  result = result.replace(/^---+$/gm, source_default.gray("─".repeat(50)));
+  result = result.replace(/^===+$/gm, source_default.gray("═".repeat(50)));
+  return result;
+}
+function formatAsJson(result) {
+  return JSON.stringify({
+    sessionId: result.sessionId,
+    success: result.success,
+    iterations: result.iterations,
+    totalDurationMs: result.totalDurationMs,
+    plan: result.plan,
+    results: result.results,
+    validation: result.validation,
+    report: typeof result.report === "string" ? result.report : "[streaming]"
+  }, null, 2);
+}
+program2.name("lendctl-ai").description("Autonomous lending decision agent powered by LendCtl CLI suite").version("0.2.1");
+program2.command("ask").description("Ask a lending question").argument("<question>", "Your lending question").option("-m, --model <model>", "LLM model to use", "gpt-4o").option("-i, --iterations <n>", "Max planning iterations", "3").option("-v, --verbose", "Show detailed output").option("-j, --json", "Output as JSON").option("-f, --format <format>", "Output format: plain, json, markdown", "plain").option("--quick", "Quick mode (skip LLM report generation)").action(async (question, options) => {
+  const outputJson = options.json || options.format === "json";
+  const outputMarkdown = options.format === "markdown";
+  if (!outputJson) {
+    console.log(banner);
+  }
   const agent = new LendCtlAgent({
     model: options.model,
     maxIterations: parseInt(options.iterations),
     verbose: options.verbose
   });
-  console.log(source_default.blue(`\uD83D\uDCCB Question: ${question}
+  if (!outputJson) {
+    console.log(source_default.blue(`\uD83D\uDCCB Question: ${question}
 `));
+  }
   try {
     if (options.quick) {
-      console.log(source_default.gray(`Running in quick mode...
+      if (!outputJson) {
+        console.log(source_default.gray(`Running in quick mode...
 `));
+      }
       const result = await agent.quickQuery(question);
-      console.log(result.summary);
-      console.log(source_default.gray(`
+      if (outputJson) {
+        console.log(JSON.stringify({
+          sessionId: result.sessionId,
+          summary: result.summary,
+          results: result.results,
+          validation: result.validation
+        }, null, 2));
+      } else {
+        console.log(outputMarkdown ? result.summary : renderMarkdownToTerminal(result.summary));
+        console.log(source_default.gray(`
 Session: ${result.sessionId}`));
+      }
     } else {
-      const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-      let i = 0;
-      const spinnerInterval = setInterval(() => {
-        process.stdout.write(`\r${source_default.cyan(spinner[i++ % spinner.length])} Analyzing...`);
-      }, 100);
+      let spinnerInterval;
+      if (!outputJson) {
+        const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+        let i = 0;
+        spinnerInterval = setInterval(() => {
+          process.stdout.write(`\r${source_default.cyan(spinner[i++ % spinner.length])} Analyzing...`);
+        }, 100);
+      }
       const result = await agent.query(question);
-      clearInterval(spinnerInterval);
-      process.stdout.write("\r" + " ".repeat(20) + "\r");
+      if (spinnerInterval) {
+        clearInterval(spinnerInterval);
+        process.stdout.write("\r" + " ".repeat(20) + "\r");
+      }
+      if (outputJson) {
+        console.log(formatAsJson(result));
+        return;
+      }
       if (options.verbose) {
         console.log(source_default.yellow(`
 \uD83D\uDCCB Plan:`));
@@ -25272,12 +25329,13 @@ Session: ${result.sessionId}`));
 \uD83D\uDCDD Report:
 `));
       if (typeof result.report === "string") {
-        console.log(result.report);
+        console.log(outputMarkdown ? result.report : renderMarkdownToTerminal(result.report));
       } else {
+        let fullReport = "";
         for await (const chunk of result.report) {
-          process.stdout.write(chunk);
+          fullReport += chunk;
         }
-        console.log();
+        console.log(outputMarkdown ? fullReport : renderMarkdownToTerminal(fullReport));
       }
       console.log(source_default.gray(`
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`));
@@ -25285,50 +25343,91 @@ Session: ${result.sessionId}`));
       console.log(source_default.gray(`Iterations: ${result.iterations} | Time: ${result.totalDurationMs}ms`));
     }
   } catch (error) {
-    console.error(source_default.red(`
+    if (outputJson) {
+      console.log(JSON.stringify({ error: error.message }, null, 2));
+    } else {
+      console.error(source_default.red(`
 ❌ Error: ${error.message}`));
-    if (options.verbose) {
-      console.error(error.stack);
+      if (options.verbose) {
+        console.error(error.stack);
+      }
     }
     process.exit(1);
   }
 });
-program2.command("chat").description("Interactive chat mode").option("-m, --model <model>", "LLM model to use", "gpt-4o").action(async (options) => {
-  console.log(banner);
-  console.log(source_default.gray(`Type your lending questions. Enter "quit" to exit.
+program2.command("chat").description("Interactive chat mode").option("-m, --model <model>", "LLM model to use", "gpt-4o").option("-j, --json", "Output responses as JSON").action(async (options) => {
+  const outputJson = options.json;
+  if (!outputJson) {
+    console.log(banner);
+    console.log(source_default.gray(`Type your lending questions. Press Ctrl+C or type "quit" to exit.
 `));
+  }
   const agent = new LendCtlAgent({
     model: options.model,
     stream: true
   });
+  process.on("SIGINT", () => {
+    if (!outputJson) {
+      console.log(source_default.gray(`
+
+Goodbye! \uD83D\uDC4B`));
+    }
+    process.exit(0);
+  });
   while (true) {
-    const question = await esm_default2({ message: source_default.blue("You:") });
+    let question;
+    try {
+      question = await esm_default2({ message: outputJson ? "> " : source_default.blue("You:") });
+    } catch (error) {
+      if (error.name === "ExitPromptError" || error.message?.includes("SIGINT") || error.message?.includes("force closed")) {
+        if (!outputJson) {
+          console.log(source_default.gray(`
+
+Goodbye! \uD83D\uDC4B`));
+        }
+        process.exit(0);
+      }
+      throw error;
+    }
     if (question.toLowerCase() === "quit" || question.toLowerCase() === "exit") {
-      console.log(source_default.gray(`
+      if (!outputJson) {
+        console.log(source_default.gray(`
 Goodbye! \uD83D\uDC4B`));
+      }
       break;
     }
     if (!question.trim()) {
       continue;
     }
-    console.log(source_default.green(`
+    if (!outputJson) {
+      console.log(source_default.green(`
 Agent:`));
+    }
     try {
       const result = await agent.query(question);
-      if (typeof result.report === "string") {
-        console.log(result.report);
+      if (outputJson) {
+        console.log(formatAsJson(result));
       } else {
-        for await (const chunk of result.report) {
-          process.stdout.write(chunk);
+        let reportText = "";
+        if (typeof result.report === "string") {
+          reportText = result.report;
+        } else {
+          for await (const chunk of result.report) {
+            reportText += chunk;
+          }
         }
-        console.log();
-      }
-      console.log(source_default.gray(`
+        console.log(renderMarkdownToTerminal(reportText));
+        console.log(source_default.gray(`
 [${result.iterations} iterations, ${result.totalDurationMs}ms]
 `));
+      }
     } catch (error) {
-      console.error(source_default.red(`Error: ${error.message}
+      if (outputJson) {
+        console.log(JSON.stringify({ error: error.message }, null, 2));
+      } else {
+        console.error(source_default.red(`Error: ${error.message}
 `));
+      }
     }
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lendctl-ai",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Autonomous lending decision agent powered by LendCtl CLI suite",
   "author": "Satyan Avatara <rsatyan@gmail.com>",
   "license": "Apache-2.0",