JoeBot/HOALedgerIQ_Website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add OpenAI-compatible AI investment advisor to benefit calculator

Browse Source 
- server.js: add /api/calculate endpoint using openai SDK with configurable
  AI_API_URL, AI_API_KEY, AI_MODEL, AI_DEBUG env vars (works with any
  OpenAI-compatible provider: NVIDIA NIM, Together AI, Groq, Ollama, etc.)
- app.js: make calculator submit handler async; call /api/calculate with
  graceful fallback to client-side generated text if AI is unavailable
- package.json: add openai and dotenv dependencies
- AI_SETUP.md: rewrite to document new unified env var config with provider examples

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
olsch01
2026-03-11 10:05:36 -04:00
parent c95fd7d424
commit bf70efc0d7
5 changed files with 1423 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
AI_SETUP.md
View File

@@ -1,10 +1,8 @@
# HOA LedgerIQ — AI API Configuration Guide
# HOA LedgerIQ — AI Investment Advisor Configuration
## Overview
The **Benefit Calculator widget** currently runs entirely client-side using conservative
fixed-rate math. This guide explains how to upgrade it to call a real AI API
(Claude or OpenAI) so the recommendation text is generated dynamically by a language model.
The **Benefit Calculator** uses an AI model to generate a personalized investment recommendation. It supports any **OpenAI-compatible API** — including OpenAI, NVIDIA NIM, Together AI, Groq, Ollama, and others — configured via environment variables.
---
@@ -13,162 +11,72 @@ fixed-rate math. This guide explains how to upgrade it to call a real AI API
```
Browser (app.js)
└─► POST /api/calculate (server.js)
└─► Anthropic / OpenAI API
└─► Returns AI-generated investment recommendation text
└─► OpenAI-compatible API (AI_API_URL)
└─► Returns AI-generated recommendation text
└─► JSON response back to browser
(falls back to client-side math text if unavailable)
```
---
## Step 1 — Add your API key to `.env`
## Configuration (.env)
Open `.env` in the project root and add one of the following:
Add these variables to your `.env` file (or systemd `EnvironmentFile`):
```env
# For Claude (Anthropic) — recommended
ANTHROPIC_API_KEY=sk-ant-...
# AI Investment Advisor (OpenAI-compatible API)
AI_API_URL=https://integrate.api.nvidia.com/v1
AI_API_KEY=your_api_key_here
AI_MODEL=qwen/qwen3.5-397b-a17b
# OR for OpenAI
OPENAI_API_KEY=sk-...
# Set to 'true' to enable detailed AI prompt/response logging
AI_DEBUG=false
```
### Provider Examples
| Provider | AI_API_URL | Example Model |
|---|---|---|
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
| NVIDIA NIM | `https://integrate.api.nvidia.com/v1` | `qwen/qwen3.5-397b-a17b` |
| Together AI | `https://api.together.xyz/v1` | `meta-llama/Llama-3-70b-chat-hf` |
| Groq | `https://api.groq.com/openai/v1` | `llama3-70b-8192` |
| Ollama (local) | `http://localhost:11434/v1` | `llama3` |
> If `AI_API_KEY` is not set, the `/api/calculate` endpoint returns 503 and the calculator falls back to client-side generated text automatically.
---
## Step 2 — Install the SDK
## How It Works
```bash
# Claude (Anthropic)
npm install @anthropic-ai/sdk
# OR OpenAI
npm install openai
```
---
## Step 3 — Add the `/api/calculate` endpoint to `server.js`
Add this block after the existing `/api/health` route:
### Using Claude (Anthropic)
`server.js` initializes the OpenAI client with your configured base URL and key:
```js
const Anthropic = require('@anthropic-ai/sdk');
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const aiClient = AI_API_KEY
? new OpenAI({ apiKey: AI_API_KEY, baseURL: AI_API_URL })
: null;
```
app.post('/api/calculate', async (req, res) => {
const { homesites, propertyType, annualIncome, paymentFreq, reserveFunds, interest2025 } = req.body ?? {};
The `POST /api/calculate` endpoint builds a prompt from the form inputs and calls:
if (!homesites || !annualIncome) {
return res.status(400).json({ error: 'homesites and annualIncome are required.' });
}
const fmt = n => '$' + Math.round(n).toLocaleString();
const freqLabel = { monthly: 'monthly', quarterly: 'quarterly', annually: 'annual' }[paymentFreq] || 'monthly';
const typeLabel = { sfh: 'single-family home', townhomes: 'townhome', condos: 'condo', mixed: 'mixed-use' }[propertyType] || '';
const prompt = `You are a conservative HOA financial advisor. Given the following community data, provide a brief (3-4 sentence) plain-English investment income recommendation. Use only conservative, realistic estimates. Do not speculate beyond what the data supports.
Community: ${homesites}-unit ${typeLabel} association
Annual dues income: ${fmt(annualIncome)} (collected ${freqLabel})
Reserve fund balance: ${fmt(reserveFunds || 0)}
Interest income earned in 2025: ${fmt(interest2025 || 0)}
Provide a recommendation focused on:
1. How much of the reserve funds could conservatively be invested and in what vehicle (e.g. CD ladder, money market, T-bills)
2. How much operating cash could earn interest between collection and expense periods
3. A realistic estimated annual interest income potential
4. A single sentence comparing that to their 2025 actual if provided
Keep the tone professional and factual. No bullet points — flowing paragraph only.`;
try {
const message = await anthropic.messages.create({
model: 'claude-opus-4-6',
max_tokens: 300,
messages: [{ role: 'user', content: prompt }],
});
const text = message.content[0]?.text ?? '';
res.json({ recommendation: text });
} catch (err) {
console.error('AI API error:', err.message);
res.status(502).json({ error: 'AI service unavailable. Showing estimated result.' });
}
```js
const completion = await aiClient.chat.completions.create({
model: AI_MODEL,
max_tokens: 300,
messages: [{ role: 'user', content: prompt }],
});
```
### Using OpenAI (GPT-4o)
```js
const OpenAI = require('openai');
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
app.post('/api/calculate', async (req, res) => {
const { homesites, propertyType, annualIncome, paymentFreq, reserveFunds, interest2025 } = req.body ?? {};
// ... (same prompt construction as above) ...
try {
const completion = await openai.chat.completions.create({
model: 'gpt-4o',
max_tokens: 300,
messages: [{ role: 'user', content: prompt }],
});
const text = completion.choices[0]?.message?.content ?? '';
res.json({ recommendation: text });
} catch (err) {
console.error('AI API error:', err.message);
res.status(502).json({ error: 'AI service unavailable.' });
}
});
```
`app.js` calls this endpoint on form submit and falls back to the client-side text if the server returns an error or is unreachable.
---
## Step 4 — Update `app.js` to call the API endpoint
In the `initCalculator` function, replace this line in the submitBtn handler:
```js
document.getElementById('calcAiText').textContent = ai; // current: client-side text
```
With this:
```js
// Call the AI endpoint; fall back to client-side text if unavailable
try {
const aiRes = await fetch('/api/calculate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ homesites, propertyType, annualIncome, paymentFreq, reserveFunds, interest2025 }),
});
if (aiRes.ok) {
const { recommendation } = await aiRes.json();
document.getElementById('calcAiText').textContent = recommendation;
} else {
document.getElementById('calcAiText').textContent = ai; // fallback
}
} catch (_) {
document.getElementById('calcAiText').textContent = ai; // fallback
}
```
> Note: The `submitBtn` handler must be declared `async` for the `await` above to work:
> ```js
> submitBtn?.addEventListener('click', async () => { ... });
> ```
---
## Step 5 — Restart the server
## Restart & Verify
```bash
sudo systemctl restart hoaledgeriqweb
# Verify the endpoint is live
# Test the endpoint
curl -X POST http://localhost:3000/api/calculate \
-H "Content-Type: application/json" \
-d '{"homesites":150,"propertyType":"sfh","annualIncome":300000,"paymentFreq":"monthly","reserveFunds":500000,"interest2025":4200}'
@@ -176,44 +84,35 @@ curl -X POST http://localhost:3000/api/calculate \
---
## Prompt Tuning Tips
## Prompt Tuning
The prompt in Step 3 is the core of the AI's behavior. You can adjust it to:
Edit the prompt in `server.js` (inside the `/api/calculate` route) to adjust tone or output:
| Goal | Change |
|---|---|
| More optimistic estimates | Change "conservative" to "moderate" in the prompt |
| More optimistic estimates | Change "conservative" to "moderate" |
| Shorter output | Reduce `max_tokens` to `150` |
| Include specific investment products | Add "mention specific products like Vanguard Federal Money Market or 6-month T-bills" |
| Add a disclaimer | Append "End with one sentence reminding them this is not financial advice." |
| Specific products | Add "mention Vanguard Federal Money Market or 6-month T-bills" |
| Add disclaimer | Append "End with one sentence reminding them this is not financial advice." |
---
## Cost Estimate
## Debug Logging
| Model | Approx. cost per calculator use |
|---|---|
| Claude Opus 4.6 | ~$0.002 |
| Claude Sonnet 4.6 | ~$0.0004 |
| GPT-4o | ~$0.002 |
| GPT-4o-mini | ~$0.00005 |
For a landing page with low traffic, even Claude Opus is negligible cost. For scale,
`claude-sonnet-4-6` is the best balance of quality and price.
Set `AI_DEBUG=true` in `.env` to log the full prompt and response to the server console. Useful for testing new models or prompt changes.
---
## Security Notes
## Security
- **Never expose your API key in `app.js` or any client-side code.** All AI calls must go through `server.js`.
- Rate-limit the `/api/calculate` endpoint to prevent abuse (e.g. with `express-rate-limit`):
- **Never put `AI_API_KEY` in `app.js`** — all AI calls go through `server.js`.
- Rate-limit the endpoint to prevent abuse:
```bash
npm install express-rate-limit
npm install express-rate-limit --ignore-scripts
```
```js
const rateLimit = require('express-rate-limit');
const calcLimiter = rateLimit({ windowMs: 60 * 1000, max: 10 }); // 10 req/min per IP
app.use('/api/calculate', calcLimiter);
app.use('/api/calculate', rateLimit({ windowMs: 60_000, max: 10 }));
```