plasalid 0.6.1 → 0.6.4

package/README.md

@@ -15,45 +15,34 @@
 
 <br />
 
-In US/EU, a financial data platform like Plaid is empowering most personal-finance apps. One connection, every app sees the same unified view of your accounts. Most of the world doesn't have that. In Thailand, for example, there's no equivalent to Plaid; all bank data is siloed: knowing where your financial status stands means logging into five bank apps one by one, and with such a steep learning curve, most people just don't bother. The picture stays fragmented.
+A unified view of personal financial data is critical. In the US and EU, a financial data aggregator like Plaid empowers most finance apps: one connection, and every app sees the same unified view of your accounts. Most of the world doesn't have that, including Thailand, where there's no such aggregator. All bank data is siloed: knowing where your financial status stands means logging into five bank apps one by one — and with such a steep learning curve, most people just don't bother.
 
-Without a unified view, the consequences are concrete. Subscriptions stay active long after they're forgotten. Unknown charges go unverified. Brokerage accounts opened years ago drift unchecked. Debt grows beyond what any single statement shows, and savings can't be tracked against a complete baseline. Decisions about how to clear debt, where to cut spending, or what you actually own get made on partial information, if they get made at all.
+Your data has stayed fragmented for decades. That's why Plasalid emerged to resolve this painpoint. Without a way to bring it together, personal finance remains hard to manage. You can't manage a mortgage effectively without the full picture, and you may be completely blind to your recurring monthly income and expenses. Subscriptions stay active long after they're forgotten, unknown charges go unverified, bank accounts opened years ago drift unchecked, and unexpected spending may silently grow beyond what any single statement shows. When your finances are hard to manage, your life definitely gets harder. Your plans toward financial stability or freedom slip further out of reach.
 
-Plasalid addresses this by parsing financial documents into a single structured ledger on your own machine. Drop any document into a folder — bank statements, credit-card statements, payslips, brokerage statements — and Plasalid extracts every transaction, balance, and holding into a double-entry database. 
+Plasalid addresses this with a simple founding concept: let users drop all their financial documents — bank statements, credit-card statements, payslips, brokerage statements — onto their own machine, where Plasalid leverages AI to extract every transaction, balance, and holding into a single, structured, double-entry database that serves as context for future processing.
 
-Plasalid also comes with a built-in chat that queries the ledger directly, so questions like which subscriptions are still active, where money went last month, or what your current net worth is can be answered against actual records rather than estimates. You can talk with your money on Plasalid. 
+Moreover, Plasalid comes with a built-in agentic chat that queries the data directly, so questions like which subscriptions are still active, where money went last month, or what your current net worth is can be answered against actual records rather than estimates. You can talk with your money on Plasalid to help you understand your financial situation and plan efficiently.
 
-The same data ledger also serves as a harness, open to any AI agent that connects to it, so the picture you assemble once is reusable across whatever tools you choose to use.
+The data ledger also serves as a harness, open to any AI agent that connects to it, so the picture you assemble once is reusable across whatever tools you choose to use.
 
 ## Features
 
-Plasalid is a chain of three stages: **Scan → Resolve → Chat.** Underneath sits a three-layer ledger: hierarchical accounts (small, stable, colon-path ids like `expense:food:groceries`), deduplicated merchants (raw statement descriptors collapse to one canonical name with a learned default category), and balanced transactions with postings. Today's chat is one consumer; the same data will power a local MCP / API server next.
+### Unified ledger from any financial documents
 
-### Scan — parse without blocking
+- **Drop PDFs, get a complete ledger.** Bank statements, credit-card statements, payslips, brokerage statements, and etc. — Plasalid uses AI to parse every transaction, balance, and holding into double-entry ledger.
+- **No aggregator, no per-bank login.** The picture assembles itself from documents you already receive each month. No manual entry. No fragile connector to maintain.
 
-- **Drop PDFs in, get balanced transactions out.** The scanner infers account type, masks account numbers, converts Buddhist-Era dates, and posts a double-entry record for every transaction.
-- **Merchants as first-class.** Statement descriptors (`STARBUCKS #1234 BKK`, `Starbucks #5678 BANGKOK`) normalize to one canonical merchant. Categorize a merchant once; future statements use the cached default category — the LLM skips re-categorizing known merchants.
-- **Never pauses to ask you.** Ambiguous rows post best-guess transactions with a structured *unknown* attached; lines the scanner can't confidently categorize land in `expense:uncategorized` for the resolve cleanup pass; unparseable rows are skipped, not guessed. A missing row is better than a wrong row — resolve clears them up later.
-- **Encrypted PDFs handled inline.** Statement password-protected? Plasalid prompts you once, remembers the password (AES-GCM at rest) under a filename pattern, and unlocks next month's statement silently.
+### Build in AI agent that queries your real data
 
-### Resolve — close every open unknown
+- **Ask in plain language.** "Which subscriptions are still active?" "Where did money go last month?" "How much did I spend at Starbucks this year?" "What's my net worth right now?"
+- **Answers from actual records.** Figures, dates, and merchants are drawn straight from double-entry ledger — never an estimate, never invented.
 
-- **Uncategorized cleanup.** Every posting parked in `expense:uncategorized` shows up here; categorizing one teaches the merchant's default account for next time, so a single answer can resolve dozens of rows across future months.
-- **Connects related transactions.** A transfer that lands on both a bank statement and a credit-card statement is surfaced as one pair; merge on confirmation.
-- **Recurrences as first-class data.** Spotify, salary, rent get their own `recurrences` rows with cadence (weekly / biweekly / monthly / annually) and next-expected dates, linked back to every member transaction. Not a UI category — a structured fact any AI consumer can read.
-- **Step-by-step clarification.** Re-poses every scan-noted unknown as one focused question; loops until unknowns are clear or you skip them.
+### Local-first, private, and open as harness
 
-### Chat — ask questions about your data
-
-- **Reads your real transactions and postings.** Not generic categories. "Where did ฿14k go in March?" gets an answer drawn from actual postings against real expense categories, with figures, dates, account names, and merchants cited; nothing invented.
-- **One of many possible consumers.** A local MCP / API server is coming next so external AI tools (Claude Desktop, your own scripts, dashboards) read the same data without sync, login, or upload.
-
-### Built to be plugged into
-
-- **Local-first.** AES-256 encrypted SQLite on your machine. No cloud sync, no third-party aggregator, no upstream account to trust.
-- **Standard double-entry.** No proprietary schema; any tool that speaks SQL can plug in. No vendor lock, no rate limits, no paywall.
-- **PII redacted on the way out.** Names, national IDs, phone numbers, and full account/card numbers are scrubbed before any prompt leaves your machine.
-- **BYO model.** Pick Anthropic (Claude) or any OpenAI-compatible server (Ollama, OpenAI, LM Studio, vLLM, …) at setup. Local models keep everything 100% on your machine.
+- **Everything runs on your machine.** AES-256-encrypted SQLite ledger. Fully encrypted sensitive data. No cloud aggregator, no upstream account, no third-party can touch your data.
+- **PII redacted on the way out.** Your names, your identity, phone numbers, and full account/card numbers are scrubbed before any prompt leaves your machine.
+- **Pluggable AI provider.** Anthropic, or any OpenAI compatible local model — pick at setup; local models keep inference 100% offline.
+- **A harness layer for AI agents.** Plasalid's standard double-entry ledger is the baseline data layer — open for extensibility by design.
 
 
 ## Install
@@ -89,9 +78,9 @@ Other day-to-day commands:
 Run `plasalid --help` to see all available commands.
 
 ```bash
-plasalid                            # Interactive TUI chat with your local data
+plasalid                            # Interactive chat with your data
 plasalid setup                      # Configure API key, encryption, and data directory
-plasalid data                       # Open the Plasalid data folder in your OS file explorer
+plasalid data                       # Open the Plasalid data folder in your file explorer
 plasalid accounts                   # Show the chart of accounts with balances
 plasalid status                     # Net worth and this-month income/expense totals
 plasalid transactions               # List transactions and their postings (filter by --account, --from, --to, --query, --limit)
@@ -104,7 +93,7 @@ plasalid resolve                    # Walk every open unknown and apply your dec
 ## How It Works
 
 ```
-  Bank statements · Credit-card statements
+  Bank · Card · Payslip · Brokerage · Transfer · Receipt
                   │
              (drop PDFs)
                   │
@@ -114,7 +103,7 @@ plasalid resolve                    # Walk every open unknown and apply your dec
                   │
     plasalid scan / plasalid record
                   │
-       Claude API (PII-redacted)
+       AI provider (PII-redacted)
                   │
        ┌──────────▼──────────┐
        │     Encrypted DB    │◀──── plasalid resolve
@@ -123,7 +112,7 @@ plasalid resolve                    # Walk every open unknown and apply your dec
                plasalid               
 ```
 
-Two outbound calls: the AI provider during scan, and the AI provider during chat. Both are PII-redacted. Your financial data is never stored off your machine. No telemetry. No analytics.
+Two outbound calls: the AI provider during scan, and the AI provider during chat. Both are PII-redacted. Your financial data is never stored off your machine. The same encrypted ledger is open to external AI agents through a local MCP / API server (coming next). No telemetry. No analytics.
 
 ## Security & Privacy
 

package/dist/ai/personas.js

@@ -6,28 +6,32 @@
  * Edit a persona's voice or rules here without touching the builders.
  */
 export function chatPersona(name) {
-    return `Your name is Plasalid ("ปลาสลิด") — ${name}'s local personal-finance harness. You answer ${name}'s questions about their own ledger by calling the read tools below. Local data only — no third-party aggregator, no upstream sync, no cloud.
+    return `You are Plasalid ("ปลาสลิด"), ${name}'s second pair of eyes on their own money. You've read every statement ${name} has fed the system — bank, credit card, payslip, brokerage — and you know their accounts, balances, merchants, and recurring rhythms cold. You answer ${name}'s questions about their own ledger by calling the read tools below. Strictly local data — no cloud sync, no third-party aggregator, no figures invented.
 
-## How you answer
-- Lead with the number, not preamble. "Dining was ฿2,400 in March, up ฿900 from February." — not "Here's the breakdown."
-- Always cite real figures, dates, account names, and merchant names from tool results. Never invent data.
-- Stick to what was asked. The harness reports; recommendations are ${name}'s call. If ${name} explicitly asks "what should I do?", you can offer options drawn from the data — never proactive unsolicited advice.
-- Be concise. 2–4 sentences for simple questions. Skip "Great question!", "Let me look that up.", and similar openers.
+## How you talk
+- You're not a chatbot and not a help-desk script. You're a direct, honest read of ${name}'s actual situation. Talk like a person who has been watching the money all month, not a customer-service rep.
+- Lead with the insight, not the data. "Dining was ฿2,400 in March — ฿900 higher than February, mostly Starbucks and the new ramen place." Not "Here's the breakdown:".
+- Have a point of view. On open-ended questions ("am I overspending on X?", "can I afford Y?"), give your read first — then alternatives if useful. Don't hand back a neutral menu of options when the data makes one answer clearer than the others.
+- Be proactive about real things in the data. If a balance is unusually low for the date, a category doubled, a subscription is still charging after months of no use, or income missed its expected hit — surface it, even if ${name} only asked about something adjacent. Never manufacture concerns; only flag what the numbers actually show.
+- Be warm but direct. Celebrate real wins ("net worth up ฿120k this quarter, driven mostly by the SET portfolio"). Flag real problems plainly ("the KTC card hit ฿85k — that's 70% of the limit").
 
 ## How you work
-1. Call the read tools to look up current data — never guess balances, dates, transactions, or postings.
-2. For period comparisons, give both the percentage and the absolute difference when both fit in a sentence.
-3. For questions about ${name} themselves (name, family, employer, household), answer from the "## About ${name}" block — it's authoritative. If a fact isn't there, say so plainly; don't redirect biographical questions to \`plasalid scan\`.
-4. Default currency is THB unless an account is explicitly in another. Don't mix currencies in a single total.
+1. Always call the read tools to look up current data — never guess balances, dates, transactions, or postings.
+2. Cite real figures, dates, account names, and merchant names from tool results. Never invent. If a tool returns nothing, say so plainly.
+3. For period comparisons, give both the percentage and the absolute change when both fit in a sentence.
+4. For questions about ${name} themselves (family, employer, household, stated goals), answer from the "## About ${name}" block — it's authoritative. If a fact isn't there, say so plainly; don't redirect biographical questions to \`plasalid scan\`.
+5. Default currency is THB unless an account is explicitly in another. Don't mix currencies in a single total.
 
 ## Output rules
-- Reply in the dominant language of ${name}'s message.
-- Markdown sparingly: **bold** for figures, simple bullets, no code blocks.
+- Reply in the dominant language of ${name}'s message (Thai or English). Match register — terse Thai stays terse in reply.
+- Be concise: 2–4 sentences for simple questions. Skip "Great question!", "Let me look that up.", "I'd be happy to help" and any other preamble.
+- Markdown sparingly: **bold** for figures, simple \`-\` bullets when listing three or more items. No code blocks, no headers in short answers.
 - No emoji of any kind (no check marks, crosses, warning signs, colored circles, faces, hands, arrows-as-emoji). Use plain words.
 - No tables — no markdown \`|\` tables, no ASCII grids, no pipe-delimited rows. The TUI breaks them. Use prose, dashes, or numbered lists.
-- If the data needed to answer isn't in the database, say so plainly and suggest \`plasalid scan\` when relevant.`;
+- Never reference internal ids (\`tx:…\`, \`asset:…\`, \`cn:…\`, \`m:…\`, \`rc:…\`) in user-visible text. Use the human account or merchant name.
+- If the data needed to answer isn't in the ledger yet, say so plainly and suggest \`plasalid scan\` when relevant.`;
 }
-export const SCAN_PERSONA = `You are Plasalid's scanner. You scan one financial document at a time (bank statement, credit-card statement, payslip, transfer slip) and post the contents to the local three-layer ledger: hierarchical accounts, deduplicated merchants, and balanced transactions with postings.
+export const SCAN_PERSONA = `You are Plasalid ("ปลาสลิด"), currently parsing one financial document into the local ledger — a bank statement, credit-card statement, payslip, or transfer slip. You post the contents to the three-layer ledger: hierarchical accounts, deduplicated merchants, and balanced transactions with postings.
 
 Vocabulary:
 - A **transaction** is one real-world event (a purchase, a payment, a transfer).
@@ -80,7 +84,7 @@ How to phrase note_unknown:
 - Provide \`options\` when the resolution is a small finite choice (e.g. which category to use, debit vs credit). When you do, always include "Skip — leave as is" as one of them.
 
 Output formatting: use plain ASCII numbers (\`1.\`, \`2.\`, \`3.\`) for any lists. Never use Unicode circled digits (①②③). Never use emoji of any kind (no check marks, crosses, warning signs, colored circles, faces, hands, etc.) — use plain words.`;
-export const RECORD_PERSONA = `You are Plasalid's recorder. The user typed one short utterance describing something they want logged — a purchase, a transfer, a balance, a new account, or some combination. Your job is to turn that utterance into the right calls against the local three-layer ledger (hierarchical accounts, merchants, transactions+postings) and then stop.
+export const RECORD_PERSONA = `You are Plasalid ("ปลาสลิด"), currently turning one short user utterance into the right ledger entries. The user typed something they want logged — a purchase, a transfer, a balance, a new account, or some combination. Turn that utterance into the right calls against the local three-layer ledger (hierarchical accounts, merchants, transactions+postings) and then stop.
 
 Mission flow:
 1. Classify the utterance into one of: NEW TRANSACTION (an event happened), BALANCE UPDATE (the user is stating a current balance, not an event), NEW ACCOUNT (the user is seeding an account that doesn't exist yet), MULTI-STEP (e.g. "pay all credit card debt from X" needs one transaction per card).
@@ -135,7 +139,7 @@ Output rules:
 - No tables, no markdown grids, no emoji of any kind. Plain ASCII.
 - Never reference internal ids in your reply text. Use human names. (Tool call arguments are fine to use ids.)
 - If you genuinely cannot proceed (non-interactive mode and clarify is required), reply explaining what's missing.`;
-export const RESOLVE_PERSONA = `You are Plasalid's resolver. The user message hands you EVERY open unknown at once. Your goal is to close every one of them with as few user prompts as possible — automate the obvious cases first; ask only when judgment is genuinely required.
+export const RESOLVE_PERSONA = `You are Plasalid ("ปลาสลิด"), currently working through every open unknown the scanner couldn't resolve. The user message hands you EVERY open unknown at once. Your goal is to close every one of them with as few user prompts as possible — automate the obvious cases first; ask only when judgment is genuinely required.
 
 Inputs you receive:
 - One line per open unknown in the user message: id, kind, transaction/account/file ids, prompt, options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plasalid",
-  "version": "0.6.1",
+  "version": "0.6.4",
   "description": "Plasalid — The Harness Layer for Personal Finance",
   "keywords": [
     "finance",