Metadata-Version: 2.4
Name: personal-liquidity
Version: 0.2.0
Summary: Use AI to forecast your personal liquidity from facts you control.
Author: squarepots
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/squarepots/personal-liquidity
Project-URL: Documentation, https://github.com/squarepots/personal-liquidity#readme
Project-URL: Issues, https://github.com/squarepots/personal-liquidity/issues
Project-URL: Source, https://github.com/squarepots/personal-liquidity
Keywords: personal-finance,cash-flow,liquidity,forecasting,ai-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Personal Liquidity

[English](https://github.com/squarepots/personal-liquidity/blob/main/README.md) · [简体中文](https://github.com/squarepots/personal-liquidity/blob/main/README.zh-CN.md) · [日本語](https://github.com/squarepots/personal-liquidity/blob/main/README.ja.md) · [Español](https://github.com/squarepots/personal-liquidity/blob/main/README.es.md) · [Português (Brasil)](https://github.com/squarepots/personal-liquidity/blob/main/README.pt-BR.md)

[Quick start](https://github.com/squarepots/personal-liquidity/blob/main/docs/QUICKSTART.md) · [AI interface](https://github.com/squarepots/personal-liquidity/blob/main/docs/AI-INTERFACE.md) · [FAQ](https://github.com/squarepots/personal-liquidity/blob/main/docs/FAQ.md) · [Privacy](https://github.com/squarepots/personal-liquidity/blob/main/docs/PRIVACY.md) · [AGPL-3.0-only](https://github.com/squarepots/personal-liquidity/blob/main/LICENSE)

[![Tests](https://github.com/squarepots/personal-liquidity/actions/workflows/test.yml/badge.svg)](https://github.com/squarepots/personal-liquidity/actions/workflows/test.yml)

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.

![Personal Liquidity workflow: give an AI your facts, validate them with deterministic Python, and receive dated low-point, cause, confidence, and scenario answers.](https://raw.githubusercontent.com/squarepots/personal-liquidity/main/docs/assets/liquidity-demo.svg)

## Install

```bash
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:

```text
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:

```bash
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:

```bash
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](https://github.com/squarepots/personal-liquidity/blob/main/docs/PRIVACY.md) and [Local private state](https://github.com/squarepots/personal-liquidity/blob/main/docs/PRIVATE-INSTANCE.md).

## Development

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

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

See [Contributing](https://github.com/squarepots/personal-liquidity/blob/main/CONTRIBUTING.md), [Security](https://github.com/squarepots/personal-liquidity/blob/main/SECURITY.md), and [Releasing](https://github.com/squarepots/personal-liquidity/blob/main/docs/RELEASING.md).

Personal Liquidity is licensed under [AGPL-3.0-only](https://github.com/squarepots/personal-liquidity/blob/main/LICENSE).
