opencashflow 0.11.0__tar.gz

opencashflow-0.11.0/.claude/skills/run-opencashflow/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: run-opencashflow
+description: Build, test, and exercise the opencashflow library (a framework-agnostic SQLAlchemy/Pydantic cashflow-projection engine) and its standalone `opencashflow` CLI. Use when asked to install it, run its tests, verify it works after a change, try its CLI directly, or see a worked example of its write paths (override, record, period close, wallet movement).
+---
+
+`opencashflow` is primarily a Python **library** (no server, no GUI), but since v0.8.1 it
+also has its own standalone CLI (`opencashflow` console script / `python -m
+opencashflow.cli`) -- a minimal, app-independent surface (no ledger, no credit cards, no
+multi-user auth) good for trying the library out or running its example specs, but not a
+substitute for a real consuming app's own richer CLI (e.g. `opencashflow-cli`'s `ocf`).
+For exercising the library's write paths as CODE (the thing a consuming app actually
+does), use `.claude/skills/run-opencashflow/smoke.py` -- a runnable worked example (not a
+pytest file, no assertions-as-the-point) that seeds a sheet and walks every write path
+the library exposes, printing the result of each step.
+
+All paths below are relative to the repo root (`~/Escritorio/opencashflow`).
+
+## Prerequisites
+
+Python >=3.10 (verified against 3.14.7 in this container). No system packages needed --
+pure Python, SQLAlchemy + Pydantic only, SQLite backing store.
+
+## Setup
+
+```bash
+python3 -m venv .venv   # skip if .venv already exists
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Run (agent path)
+
+```bash
+source .venv/bin/activate
+python .claude/skills/run-opencashflow/smoke.py
+```
+
+Expected output (values may shift slightly if the seed data changes):
+
+```
+== 1. seed_sheet + compute_sheet ==
+  Sheet #1 seeded, 7 sections. SALDO FINAL (Jan 2026) proyectado = 1537000.00
+== 2. _do_set_override (write path: manual override) ==
+  Wrote override on row 'Sueldo líquido' -> 2000000.00. SALDO FINAL recomputed = 1177000.00
+== 3. record set (write path: actual/accrued/paid + CellActualEntry) ==
+  Recorded actual=2000000.00 on cell #6
+== 4. close_period (dry_run, then committed) ==
+  Preview: SALDO FINAL=3200000.00, real_net_flow=2000000.00, 0 rollover(s), warnings=[...]
+  Committed: period.is_closed=True, next_period_label=Feb 2026
+== 5. wallet + wallet_movements (write path: Wallet/WalletMovement) ==
+  wallet_movement_add -> movement #1, wallet balance = 50000.0
+  wallet_movement_undo -> reversal #2, wallet balance = 0.0
+
+All write paths exercised successfully.
+```
+
+It runs entirely against an in-memory SQLite database created fresh each run --
+it never touches a real `opencashflow.db`, so it's always safe to re-run. A
+non-zero exit / traceback means the library's public surface (`compute_sheet`,
+`_do_set_override`, `close_period`, `do_wallet_movement_add/undo`) has a real
+regression, not a flaky test.
+
+## Run the standalone CLI directly
+
+```bash
+.venv/bin/opencashflow seed --user-id 1 --months 6
+.venv/bin/opencashflow sheets
+.venv/bin/opencashflow rows --sheet-id 1
+```
+
+Defaults to a throwaway `sqlite:///./opencashflow-demo.db` in the current directory
+(override with `--db-url` or `$OPENCASHFLOW_DB_URL`) -- never a real consuming app's own
+database. This is the generic surface `register_generic_commands` builds, plus a minimal
+`seed`; it has no ledger/credit-card/auth commands (those live in a real consuming app).
+
+## Test
+
+```bash
+source .venv/bin/activate
+pytest tests/ -v
+```
+
+96 tests, all pass (confirmed this session). No known-flaky tests.
+
+## Gotchas
+
+- **`opencashflow.wallet` must be imported before `Base.metadata.create_all()`** on
+  a fresh database -- `Wallet`/`WalletMovement` live in their own module and only
+  register their tables on `opencashflow.models.Base`'s registry as a side effect of
+  being imported. Skipping the import silently creates every table except
+  `wallets`/`wallet_movements`. `smoke.py` does `import opencashflow.wallet  # noqa: F401`
+  for exactly this reason.
+- **Write-path result objects don't use the field names you'd guess**:
+  `_do_set_override(...)` returns `OverrideWriteResult` objects whose written value
+  is at `.override.value` (not `.new_value`, not `.override.manual_value`) --
+  confirmed by inspecting `opencashflow.models.CellOverride`'s actual columns, not
+  by guessing from the CLI's print statements.
+- **`.venv` is not relocatable.** `pip install -e .` bakes this repo's absolute path
+  into the venv's editable-finder files and script shebangs. If this folder is ever
+  moved or renamed, re-run `pip install -e .` against the new path (or delete and
+  recreate `.venv` entirely if even `pip` itself stops working).
+- **`find_balance_row` (used by `close_period`) auto-detects the starting-balance
+  row by scanning for the one row using the `previous_period` projection rule** --
+  there's no config flag for it. A sheet with zero or more than one such row raises
+  `ValueError` (never `sys.exit`), listing every candidate.

opencashflow-0.11.0/.claude/skills/run-opencashflow/smoke.py

@@ -0,0 +1,115 @@
+"""Smoke test / worked example for the `opencashflow` library.
+
+This is not a test in the pytest sense (no assertions) -- it is a runnable
+demonstration that imports the package as an external consumer would and
+exercises every write path the library exposes, printing the result of each
+step. Run it after `pip install -e ".[dev]"` to confirm the library actually
+works end to end, not just that its own unit tests pass in isolation.
+
+    python .claude/skills/run-opencashflow/smoke.py
+
+Everything runs against an in-memory SQLite database created fresh each run
+-- it never touches a real `opencashflow.db`.
+"""
+from datetime import date, datetime
+from decimal import Decimal
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+import opencashflow.wallet  # noqa: F401 -- registers Wallet/WalletMovement on Base.metadata
+from opencashflow.cli import _do_set_override
+from opencashflow.engine import compute_sheet
+from opencashflow.models import Base, CellActualEntry, SheetCell, SheetPeriod, SheetRow
+from opencashflow.period_close import close_period
+from opencashflow.wallet import Wallet
+from opencashflow.wallet_movements import do_wallet_movement_add, do_wallet_movement_undo
+from opencashflow.seed import seed_sheet
+
+
+def cell_for(result, row_id, period_id):
+    for section in result["sections"]:
+        for row_data in section["rows"]:
+            if row_data["row"].id == row_id:
+                for cr in row_data["cells"]:
+                    if cr.period_id == period_id:
+                        return cr
+    return None
+
+
+def main():
+    engine = create_engine("sqlite:///:memory:")
+    Base.metadata.create_all(bind=engine)
+    db = sessionmaker(bind=engine)()
+
+    print("== 1. seed_sheet + compute_sheet ==")
+    sheet = seed_sheet(db, user_id=1, months=3, base_period=date(2026, 1, 1))
+    result = compute_sheet(sheet.id, db)
+    first_period = db.query(SheetPeriod).filter_by(sheet_id=sheet.id).order_by(SheetPeriod.sort_order).first()
+    saldo_final_row = next(
+        r for s in result["sections"] for r in s["rows"] if r["row"].name == "SALDO FINAL"
+    )["row"]
+    saldo_before = cell_for(result, saldo_final_row.id, first_period.id).projected_value
+    print(f"  Sheet #{sheet.id} seeded, {len(result['sections'])} sections. "
+          f"SALDO FINAL ({first_period.label}) proyectado = {saldo_before}")
+    assert saldo_before is not None
+
+    print("== 2. _do_set_override (write path: manual override) ==")
+    ingresos_row = next(
+        r for s in result["sections"] for r in s["rows"]
+        if r["row"].name not in ("SALDO INICIAL", "SALDO FINAL") and r["row"].section.section_type == "income"
+    )["row"]
+    write_results = _do_set_override(
+        db, sheet.id, ingresos_row, [first_period],
+        value=Decimal("2000000"), created_by=1, note="smoke test override",
+    )
+    result = compute_sheet(sheet.id, db)
+    saldo_after_override = cell_for(result, saldo_final_row.id, first_period.id).projected_value
+    print(f"  Wrote override on row '{ingresos_row.name}' -> {write_results[0].override.value}. "
+          f"SALDO FINAL recomputed = {saldo_after_override}")
+    assert saldo_after_override != saldo_before
+
+    print("== 3. record set (write path: actual/accrued/paid + CellActualEntry) ==")
+    cell = db.query(SheetCell).filter_by(row_id=ingresos_row.id, period_id=first_period.id).first()
+    if not cell:
+        cell = SheetCell(row_id=ingresos_row.id, period_id=first_period.id)
+        db.add(cell)
+        db.flush()
+    cell.actual_value = cell.accrued_value = cell.paid_value = Decimal("2000000")
+    db.add(CellActualEntry(cell_id=cell.id, actual_value=cell.actual_value,
+                            accrued_value=cell.accrued_value, paid_value=cell.paid_value,
+                            note="smoke test record", created_by=1))
+    db.commit()
+    print(f"  Recorded actual={cell.actual_value} on cell #{cell.id}")
+
+    print("== 4. close_period (dry_run, then committed) ==")
+    preview = close_period(db, sheet, first_period, acting_user_id=1, dry_run=True)
+    print(f"  Preview: SALDO FINAL={preview.saldo_final_value}, real_net_flow={preview.real_net_flow}, "
+          f"{len(preview.rollovers)} rollover(s), warnings={preview.warnings}")
+    report = close_period(db, sheet, first_period, acting_user_id=1, dry_run=False)
+    db.refresh(first_period)
+    print(f"  Committed: period.is_closed={first_period.is_closed}, "
+          f"next_period_label={report.next_period_label}")
+    assert first_period.is_closed
+
+    print("== 5. wallet + wallet_movements (write path: Wallet/WalletMovement) ==")
+    wallet_obj = Wallet(user_id=1, name="Efectivo", wallet_type="cash", currency="CLP", balance=Decimal("0"))
+    db.add(wallet_obj)
+    db.commit()
+    second_period = db.query(SheetPeriod).filter_by(sheet_id=sheet.id).order_by(SheetPeriod.sort_order).offset(1).first()
+    add_result = do_wallet_movement_add(
+        db, wallet_obj, sheet.id, ingresos_row, second_period,
+        amount=Decimal("50000"), note="smoke test deposit", created_by=1,
+    )
+    db.refresh(wallet_obj)
+    print(f"  wallet_movement_add -> movement #{add_result.movement.id}, wallet balance = {wallet_obj.balance}")
+    undo_result = do_wallet_movement_undo(db, add_result.movement, note="smoke test undo", created_by=1)
+    db.refresh(wallet_obj)
+    print(f"  wallet_movement_undo -> reversal #{undo_result.reversal.id}, wallet balance = {wallet_obj.balance}")
+    assert wallet_obj.balance == Decimal("0")
+
+    print("\nAll write paths exercised successfully.")
+
+
+if __name__ == "__main__":
+    main()

opencashflow-0.11.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Runs on every version tag push (vX.Y.Z), matching this repo's own
+# release convention (version bump + tag as the last step of a feature).
+# Uses PyPI's trusted publishing (OIDC) -- no API token stored as a
+# secret. The PyPI project must have this repo/workflow registered as a
+# trusted publisher first (a one-time step on pypi.org).
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch: {}  # manual "Run workflow" button, for a first-time test run
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

opencashflow-0.11.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+*.db
+.claude/worktrees/

opencashflow-0.11.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

opencashflow-0.11.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: opencashflow
+Version: 0.11.0
+Summary: Motor de proyección de flujo de caja: modelos SQLAlchemy, engine de cálculo y schemas Pydantic, agnóstico de framework web y de ledger.
+Project-URL: Homepage, https://github.com/LuisLopezMunoz/opencashflow
+Project-URL: Repository, https://github.com/LuisLopezMunoz/opencashflow
+Project-URL: Issues, https://github.com/LuisLopezMunoz/opencashflow/issues
+Author-email: Luis Alfredo López <luis@bmya.cl>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: budgeting,cashflow,finance,projection,sqlalchemy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: sqlalchemy<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opencashflow
+
+Motor de proyección de flujo de caja: modelos SQLAlchemy, engine de cálculo y schemas
+Pydantic. Agnóstico de framework web, de autenticación y de ledger — es una librería,
+no una aplicación.
+
+Modela una planilla financiera como sección → fila → celda, donde cada fila declara una
+regla de proyección (`constant`, `previous_period`, `sum_rows`, `percent_of_row`, entre
+otras) y cada celda puede exponer un valor proyectado y, por separado, un valor real
+(`actual_value`/`accrued_value`/`paid_value`) que la aplicación consumidora es responsable
+de poblar. Overrides manuales son inmutables y auditables (nunca se actualizan, se
+reemplazan). Ver [docs/model.md](docs/model.md) para el glosario completo del dominio.
+
+## Instalación
+
+```bash
+pip install "opencashflow @ git+https://github.com/LuisLopezMunoz/opencashflow.git@v0.1.0"
+```
+
+(Todavía no está publicado en PyPI — instalar directamente desde el repositorio.)
+
+Esto también instala el comando `opencashflow` (equivalente a `python -m
+opencashflow.cli`) -- una CLI standalone, independiente de cualquier app consumidora
+(sin ledger, sin auth multiusuario), útil para probar la librería o correr el demo de
+abajo.
+
+## Demo en un minuto
+
+```bash
+opencashflow seed --user-id 1 --months 12 --base-period 2026-01
+opencashflow rows --sheet-id 1
+opencashflow doctor --sheet-id 1
+opencashflow show --sheet-id 1
+```
+
+Esto crea (en una base SQLite descartable, `./opencashflow-demo.db` por defecto) una
+planilla de ejemplo realista -- un hogar chileno con ingresos, gastos fijos/variables,
+impuestos, financiamiento y un saldo acumulado -- lista sus filas y reglas, y por
+último muestra la matriz calculada como tabla. (`--cards`/`--bridge` -- tarjetas de
+crédito con parseo de PDF de banco y financiamiento puente -- son de las pocas cosas
+que se quedan del lado de una app consumidora real; el modelo básico de tarjeta y
+`creditcard list/edit/cupo/map` sí son parte de esta CLI standalone. Ver
+[docs/model.md](docs/model.md), secciones "CLI genérico" y "Tarjetas de crédito".)
+
+El mismo ejemplo vive como archivo declarativo en
+[docs/examples/hogar-chileno.yaml](docs/examples/hogar-chileno.yaml) -- una planilla
+completa (secciones → filas → reglas) en un solo documento YAML, generado con `sheet
+export` y reimportable con `sheet import`:
+
+```bash
+opencashflow sheet import --file docs/examples/hogar-chileno.yaml --user-id 1
+opencashflow sheet export --sheet-id 1   # -- lo mismo, de vuelta a YAML, a stdout
+```
+
+Ver [docs/model.md](docs/model.md), sección "Sheet spec", para el formato completo
+(los 6 tipos de regla soportados, cómo se referencian filas por nombre, `sheet
+import`/`export`). Nota: el spec captura la ESTRUCTURA de una planilla (secciones,
+filas, reglas) -- no overrides manuales por celda, que es justamente lo que distingue
+al ejemplo de arriba (generado con `seed`, que sí aplica un par de overrides realistas
+de calendario) del mismo ejemplo reimportado desde el YAML (que empieza sin ellos).
+
+## Uso mínimo (desde Python)
+
+Este paquete no crea usuarios ni conexiones a base de datos por ti — trae tu propia
+`Session` de SQLAlchemy y tu propio `user_id` (un entero simple, sin relación con ningún
+modelo de usuario: ver "Ownership" en [docs/model.md](docs/model.md)).
+
+```python
+from datetime import datetime
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+from opencashflow.engine import compute_sheet
+from opencashflow.models import Base, CashflowSheet, SheetRow, SheetSection
+from opencashflow.periods import generate_periods
+
+engine = create_engine("sqlite:///example.db")
+Base.metadata.create_all(bind=engine)
+db = sessionmaker(bind=engine)()
+
+sheet = CashflowSheet(user_id=1, name="Mi flujo de caja", currency="CLP",
+                       horizon_months=6, base_period=datetime(2026, 1, 1))
+db.add(sheet)
+db.flush()
+generate_periods(sheet, db)
+
+section = SheetSection(sheet_id=sheet.id, name="Ingresos", section_type="income")
+db.add(section)
+db.flush()
+
+row = SheetRow(section_id=section.id, name="Sueldo",
+               default_projection_rule={"type": "constant", "value": 1_500_000})
+db.add(row)
+db.commit()
+
+result = compute_sheet(sheet.id, db)
+```
+
+Para un ejemplo completo y realista (una planilla de hogar chileno con las cuatro reglas
+de proyección, saldo acumulado y overrides de calendario), ver
+`opencashflow.seed.seed_sheet()`.
+
+## Desarrollo
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Licencia
+
+Apache 2.0 — ver [LICENSE](LICENSE).