Personal Liquidity

English · 简体中文 · 日本語 · Español · Português (Brasil)

Quick start · AI interface · FAQ · Privacy · AGPL-3.0-only

Personal Liquidity answers a practical question: given the cash, debts, obligations, and uncertain events you know about, what does your available liquidity look like over time?

It is a local-first forecasting engine for people with uneven income, upcoming payments, debt pressure, financing choices, or decisions that do not fit a simple monthly budget. A capable AI agent can turn ordinary language, screenshots, spreadsheets, PDFs, or pasted notes into candidate facts; deterministic Python code validates those facts and performs the calculations.

You provide the financial facts. Personal Liquidity does not connect to a bank automatically, and its results are planning information rather than financial advice.

Install

uv tool install personal-liquidity
# or: pipx install personal-liquidity

personal-liquidity capabilities

The package supports Python 3.11–3.13 and has no third-party runtime dependencies. Commands work from any directory; relative --state-dir paths belong to your current working directory.

Start by giving the URL to an AI agent

Paste this prompt into Codex or another agent that can read files and run Python:

Open https://github.com/squarepots/personal-liquidity and help me understand my liquidity. Clone it if needed, read AGENTS.md and docs/AI-INTERFACE.md, install the published CLI with `uv tool install personal-liquidity`, and begin with `capabilities` and the bundled `@demo` synthetic state. Do not create private state or ingest real financial data until I confirm.

The agent's first two commands are:

personal-liquidity capabilities
personal-liquidity forecast --state-dir @demo --through 2035-02-20

The bundled @demo state is entirely synthetic and read-only. It gives the agent a safe way to learn the product and explain the result before either of you handles personal data.

What it helps you answer

• When does the known cash path reach its lowest point?
• Will available liquidity stay above zero or a chosen cash floor through a date?
• Which upcoming debts, obligations, card payments, and recurring events drive the result?
• Which facts are confirmed, estimated, missing, or contradictory?
• How does a delayed income, one-time payment, card draw, or financing choice change the path?
• Which of several explicitly supplied scenarios best satisfies your constraints?
• How did the current result change from a saved checkpoint, and how did forecast compare with actual state?

How the model stays financially conservative

• Ordinary unused card headroom is not treated as withdrawable cash unless cash-out capacity is known.
• Available-but-undrawn financing is capacity, not current debt or cash.
• Drawn financing creates debt and repayment effects; its cash proceeds enter liquidity exactly once.
• Borrowed liquidity is kept separate from owned wealth.
• Estimated and expected inputs remain visible.
• Possible events stay outside the base forecast until used in a scenario.

The deterministic engine, rather than conversational prose, owns these calculations.

From demo to your own local state

After you decide to use the product, the agent can initialize an ignored local state directory:

personal-liquidity init --state-dir private
personal-liquidity doctor --state-dir private

The agent then:

1. extracts candidate facts from the easiest form you have;
2. inspects existing canonical state;
3. identifies newer, stale, duplicate, missing, or conflicting facts;
4. runs preview-update;
5. applies only a valid real update;
6. recomputes doctor, status, forecast, or a hypothetical scenario;
7. explains the result and its uncertainty in plain language.

Screenshots, XLSX files, PDFs, and natural language are interpreted by the host AI runtime. The Python entrypoint receives normalized JSON operation payloads and maintains canonical CSV/JSON state. Capability discovery exposes each operation's required arguments, schema paths, mutation flag, and effects.

Reading a result

• data_completeness describes the source facts: complete, estimated, or incomplete.
• forecast_readiness describes the projected path.
• readiness is the compatibility alias for the relevant canonical field.
• survives_horizon: null means a material blocker prevents a supported conclusion.
• Recurring forecast events retain source: recurring.csv.
• Scenario results state canonical_state_mutated: false.

The engine reports uncertainty instead of replacing missing facts with optimistic assumptions.

Machine operations

personal-liquidity is the canonical public CLI and capability owner. python personal_liquidity.py remains a source-checkout compatibility entry point.

• inspect: capabilities, doctor, status, timeline, forecast;
• update real state: preview-update, then apply-update;
• explore hypotheticals: scenario, compare, optimize;
• track change over time: checkpoint, diff, reconcile;
• create local state: init.

Success returns JSON with exit code 0. Invalid input, an invalid preview, or a failed doctor result returns JSON with a nonzero exit code so agents and automation can rely on both the payload and process status.

Privacy

Canonical state is plaintext local CSV, JSON, and JSONL under the directory you select. The usual private/ location is ignored by Git, but ignore rules are not encryption, access control, backup isolation, or secure deletion. Protect the directory with operating-system permissions, disk protection, and a deliberate backup policy.

The deterministic engine does not upload state. A cloud AI runtime may receive prompts, screenshots, spreadsheets, PDFs, pasted text, tool arguments, and results while normalizing the input. Use an offline runtime when those materials must remain on your machine.

Normal modeling does not require full account/card numbers, CVV, PIN, bank passwords, authentication tokens, or identity documents. Use synthetic values in every public issue and pull request. See Privacy and Local private state.

Development

Requirements: Python 3.11, 3.12, or 3.13; there are no third-party runtime dependencies.

python -m unittest discover -s tests -v
python scripts/audit_public_tree.py .
uv build --no-sources

See Contributing, Security, and Releasing.

Personal Liquidity is licensed under AGPL-3.0-only.