finvariant 0.1.0__tar.gz

finvariant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atakan Arikan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

finvariant-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: finvariant
+Version: 0.1.0
+Summary: Deterministic integrity checks for financial statements: does the balance sheet balance, does the cash flow tie out, do the three statements articulate. Verifies, does not parse or build.
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/finvariant
+Project-URL: Repository, https://github.com/arikanatakan/finvariant
+Project-URL: Issues, https://github.com/arikanatakan/finvariant/issues
+Keywords: accounting,financial-statements,audit,tie-out,integrity,balance-sheet,income-statement,cash-flow,three-statement-model,financial-modeling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# finvariant
+
+[![CI](https://github.com/arikanatakan/finvariant/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/finvariant/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/finvariant)](https://pypi.org/project/finvariant/)
+[![License: MIT](https://img.shields.io/github/license/arikanatakan/finvariant)](LICENSE)
+
+Deterministic integrity checks for financial statements.
+
+Give finvariant income statement, balance sheet and cash flow data; it verifies
+the accounting invariants - the balance sheet balances, the cash flow ties to
+the balance sheet, subtotals foot, and the three statements articulate - and
+returns a structured, auditable report. It verifies; it does not parse, fetch
+or build statements.
+
+## Motivation
+
+Python has plenty of libraries to *retrieve* statements (financetoolkit, the SEC
+tools) and to *build* models (DCF templates, FP&A scripts). What none of them do
+is *check that a set of statements or a model is internally consistent*: that
+assets equal liabilities plus equity, that the cash flow's ending cash matches
+the balance sheet, that retained earnings roll forward by net income less
+dividends, that every subtotal foots. That check is exactly what a spreadsheet
+silently gets wrong - and surveys put an error in the large majority of business
+spreadsheets.
+
+finvariant encodes those invariants as deterministic, testable rules. The same
+thing a large language model cannot be trusted to get right (consistent
+arithmetic across linked statements), a small library can guarantee. Every
+result is one report: a verdict, the exact failing checks with expected vs
+actual, and provenance, so a verification can be reproduced and audited later.
+
+```
+pip install finvariant
+```
+
+No runtime dependencies.
+
+## Usage
+
+Catch an error:
+
+```python
+import finvariant as fv
+
+s = fv.Statements(
+    periods=["FY2024"],
+    balance_sheet={"FY2024": {
+        "total_assets": 540,          # should be 538
+        "total_liabilities": 158,
+        "total_equity": 380,
+    }},
+)
+
+r = fv.check(s)
+r.ok            # False
+print(r.summary())
+# finvariant audit - 2026-...
+#   1 checks run, 0 passed, 1 failed, 0 skipped
+#   [ERROR] EQ.accounting_equation assets = liabilities + equity (FY2024): expected 538, got 540, off by 2
+# Verdict: FAIL - statements do not tie out
+```
+
+Real statements tie out (Apple FY2024, from the 10-K):
+
+```python
+s = fv.Statements(
+    periods=["FY2024"],
+    income_statement={"FY2024": {
+        "revenue": 391035, "cogs": 210352, "gross_profit": 180683,
+        "operating_expenses": 57467, "operating_income": 123216,
+        "other_income": 269, "pretax_income": 123485, "tax": 29749,
+        "net_income": 93736,
+    }},
+    balance_sheet={"FY2024": {
+        "total_current_assets": 152987, "total_non_current_assets": 211993,
+        "total_assets": 364980,
+        "total_current_liabilities": 176392, "total_non_current_liabilities": 131638,
+        "total_liabilities": 308030,
+        "common_stock": 83276, "retained_earnings": -19154,
+        "accumulated_oci": -7172, "total_equity": 56950,
+    }},
+)
+fv.check(s).ok          # True
+```
+
+The report carries named findings, counts, `ok`, `summary()` and a JSON-safe
+`to_dict()` with provenance (version, input hash, timestamp).
+
+## What it checks
+
+| Group | Invariant |
+|-------|-----------|
+| Footing | every subtotal equals the sum of its line items (all three statements) |
+| Equation | total assets = total liabilities + total equity |
+| Cash | net change = cfo + cfi + cff; ending cash ties to the balance sheet; beginning cash ties to the prior period |
+| Articulation | net income agrees across statements; retained earnings roll forward by net income less dividends |
+
+Provide only the fields you have: a check whose inputs are missing is reported
+as skipped, never failed. Tolerances absorb the rounding in statements reported
+in whole millions.
+
+## Status
+
+Version 0.1.0. Single entity, single currency, one or more periods, in a
+canonical schema. The `Statements` input and `AuditReport` output are the
+contract and are append-only from here.
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| 0.2 | roll-forward checks (PP&E = opening + capex - depreciation - disposals; debt; equity); working-capital changes reconciled to operating cash flow |
+| 0.3 | an MCP server so an agent can verify financial statements it reads or generates |
+| 0.4 | optional readers to map common export formats into the canonical schema |
+
+Out of scope: retrieving statements (see financetoolkit, the SEC tools),
+building or forecasting models, ratio analysis, consolidation and currency
+translation.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

finvariant-0.1.0/README.md

@@ -0,0 +1,123 @@
+# finvariant
+
+[![CI](https://github.com/arikanatakan/finvariant/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/finvariant/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/finvariant)](https://pypi.org/project/finvariant/)
+[![License: MIT](https://img.shields.io/github/license/arikanatakan/finvariant)](LICENSE)
+
+Deterministic integrity checks for financial statements.
+
+Give finvariant income statement, balance sheet and cash flow data; it verifies
+the accounting invariants - the balance sheet balances, the cash flow ties to
+the balance sheet, subtotals foot, and the three statements articulate - and
+returns a structured, auditable report. It verifies; it does not parse, fetch
+or build statements.
+
+## Motivation
+
+Python has plenty of libraries to *retrieve* statements (financetoolkit, the SEC
+tools) and to *build* models (DCF templates, FP&A scripts). What none of them do
+is *check that a set of statements or a model is internally consistent*: that
+assets equal liabilities plus equity, that the cash flow's ending cash matches
+the balance sheet, that retained earnings roll forward by net income less
+dividends, that every subtotal foots. That check is exactly what a spreadsheet
+silently gets wrong - and surveys put an error in the large majority of business
+spreadsheets.
+
+finvariant encodes those invariants as deterministic, testable rules. The same
+thing a large language model cannot be trusted to get right (consistent
+arithmetic across linked statements), a small library can guarantee. Every
+result is one report: a verdict, the exact failing checks with expected vs
+actual, and provenance, so a verification can be reproduced and audited later.
+
+```
+pip install finvariant
+```
+
+No runtime dependencies.
+
+## Usage
+
+Catch an error:
+
+```python
+import finvariant as fv
+
+s = fv.Statements(
+    periods=["FY2024"],
+    balance_sheet={"FY2024": {
+        "total_assets": 540,          # should be 538
+        "total_liabilities": 158,
+        "total_equity": 380,
+    }},
+)
+
+r = fv.check(s)
+r.ok            # False
+print(r.summary())
+# finvariant audit - 2026-...
+#   1 checks run, 0 passed, 1 failed, 0 skipped
+#   [ERROR] EQ.accounting_equation assets = liabilities + equity (FY2024): expected 538, got 540, off by 2
+# Verdict: FAIL - statements do not tie out
+```
+
+Real statements tie out (Apple FY2024, from the 10-K):
+
+```python
+s = fv.Statements(
+    periods=["FY2024"],
+    income_statement={"FY2024": {
+        "revenue": 391035, "cogs": 210352, "gross_profit": 180683,
+        "operating_expenses": 57467, "operating_income": 123216,
+        "other_income": 269, "pretax_income": 123485, "tax": 29749,
+        "net_income": 93736,
+    }},
+    balance_sheet={"FY2024": {
+        "total_current_assets": 152987, "total_non_current_assets": 211993,
+        "total_assets": 364980,
+        "total_current_liabilities": 176392, "total_non_current_liabilities": 131638,
+        "total_liabilities": 308030,
+        "common_stock": 83276, "retained_earnings": -19154,
+        "accumulated_oci": -7172, "total_equity": 56950,
+    }},
+)
+fv.check(s).ok          # True
+```
+
+The report carries named findings, counts, `ok`, `summary()` and a JSON-safe
+`to_dict()` with provenance (version, input hash, timestamp).
+
+## What it checks
+
+| Group | Invariant |
+|-------|-----------|
+| Footing | every subtotal equals the sum of its line items (all three statements) |
+| Equation | total assets = total liabilities + total equity |
+| Cash | net change = cfo + cfi + cff; ending cash ties to the balance sheet; beginning cash ties to the prior period |
+| Articulation | net income agrees across statements; retained earnings roll forward by net income less dividends |
+
+Provide only the fields you have: a check whose inputs are missing is reported
+as skipped, never failed. Tolerances absorb the rounding in statements reported
+in whole millions.
+
+## Status
+
+Version 0.1.0. Single entity, single currency, one or more periods, in a
+canonical schema. The `Statements` input and `AuditReport` output are the
+contract and are append-only from here.
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| 0.2 | roll-forward checks (PP&E = opening + capex - depreciation - disposals; debt; equity); working-capital changes reconciled to operating cash flow |
+| 0.3 | an MCP server so an agent can verify financial statements it reads or generates |
+| 0.4 | optional readers to map common export formats into the canonical schema |
+
+Out of scope: retrieving statements (see financetoolkit, the SEC tools),
+building or forecasting models, ratio analysis, consolidation and currency
+translation.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

finvariant-0.1.0/finvariant/__init__.py

@@ -0,0 +1,28 @@
+"""finvariant - deterministic integrity checks for financial statements.
+
+Give it income statement, balance sheet and cash flow data in a canonical
+schema; it verifies the accounting invariants - the balance sheet balances,
+the cash flow ties to the balance sheet, subtotals foot, and the three
+statements articulate - and returns a structured, auditable report.
+
+    import finvariant as fv
+
+    s = fv.Statements(periods=["FY2024"],
+                      income_statement={"FY2024": {...}},
+                      balance_sheet={"FY2024": {...}},
+                      cash_flow={"FY2024": {...}})
+
+    r = fv.check(s)
+    r.ok            # do the statements tie out?
+    r.summary()     # plain-language verdict with every failed check
+    r.to_dict()     # JSON-safe payload with provenance
+
+It verifies; it does not parse, fetch or build statements.
+"""
+
+from ._result import AuditReport, RuleOutcome
+from ._version import __version__
+from .check import check
+from .model import Statements
+
+__all__ = ["check", "Statements", "AuditReport", "RuleOutcome", "__version__"]

finvariant-0.1.0/finvariant/_result.py

@@ -0,0 +1,126 @@
+"""The result contract: one ``AuditReport`` for every check, with provenance
+and a JSON-safe payload, so a verification can be reproduced and audited later.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+SCHEMA = 1
+
+PASS = "pass"
+FAIL = "fail"
+SKIP = "skip"
+ERROR = "error"
+WARNING = "warning"
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def data_hash(obj: object) -> str:
+    payload = json.dumps(obj, sort_keys=True, default=str).encode("utf-8")
+    return "sha256:" + hashlib.sha256(payload).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class RuleOutcome:
+    """The result of one rule on one period."""
+
+    rule_id: str
+    description: str
+    statement: str
+    period: str
+    status: str            # pass | fail | skip
+    severity: str          # error | warning
+    expected: float | None = None
+    actual: float | None = None
+    difference: float | None = None
+    message: str = ""
+
+    def __str__(self) -> str:
+        tag = self.severity.upper() if self.status == FAIL else self.status.upper()
+        head = f"[{tag}] {self.rule_id} {self.description} ({self.period})"
+        if self.status == FAIL and self.expected is not None:
+            return (f"{head}: expected {self.expected:g}, got {self.actual:g}, "
+                    f"off by {self.difference:g}")
+        return head if not self.message else f"{head}: {self.message}"
+
+
+@dataclass(frozen=True)
+class AuditReport:
+    """Outcome of checking a set of statements against the accounting invariants."""
+
+    outcomes: tuple[RuleOutcome, ...]
+    meta: dict
+
+    @property
+    def findings(self) -> tuple[RuleOutcome, ...]:
+        """The rules that failed."""
+        return tuple(o for o in self.outcomes if o.status == FAIL)
+
+    @property
+    def ok(self) -> bool:
+        """True when no error-severity rule failed."""
+        return not any(o.status == FAIL and o.severity == ERROR for o in self.outcomes)
+
+    @property
+    def n_passed(self) -> int:
+        return sum(1 for o in self.outcomes if o.status == PASS)
+
+    @property
+    def n_failed(self) -> int:
+        return sum(1 for o in self.outcomes if o.status == FAIL)
+
+    @property
+    def n_skipped(self) -> int:
+        return sum(1 for o in self.outcomes if o.status == SKIP)
+
+    def _verdict(self) -> str:
+        if not self.ok:
+            return "FAIL - statements do not tie out"
+        warnings = any(o.status == FAIL and o.severity == WARNING for o in self.outcomes)
+        return "PASS (with warnings)" if warnings else "PASS - statements tie out"
+
+    def summary(self) -> str:
+        run = self.n_passed + self.n_failed
+        lines = [
+            f"finvariant audit - {self.meta.get('computed_at', '')}",
+            f"  {run} checks run, {self.n_passed} passed, {self.n_failed} failed, "
+            f"{self.n_skipped} skipped",
+        ]
+        for finding in self.findings:
+            lines.append("  " + str(finding))
+        lines.append(f"Verdict: {self._verdict()}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "schema": SCHEMA,
+            "ok": self.ok,
+            "verdict": self._verdict(),
+            "counts": {
+                "passed": self.n_passed,
+                "failed": self.n_failed,
+                "skipped": self.n_skipped,
+            },
+            "findings": [
+                {
+                    "rule_id": o.rule_id,
+                    "description": o.description,
+                    "statement": o.statement,
+                    "period": o.period,
+                    "severity": o.severity,
+                    "expected": o.expected,
+                    "actual": o.actual,
+                    "difference": o.difference,
+                    "message": o.message,
+                }
+                for o in self.findings
+            ],
+            "meta": self.meta,
+        }

finvariant-0.1.0/finvariant/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

finvariant-0.1.0/finvariant/check.py

@@ -0,0 +1,55 @@
+"""The public entry point: ``check()`` runs the applicable invariants over a set
+of statements and returns an :class:`AuditReport`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from ._result import AuditReport, data_hash, utcnow
+from ._version import __version__
+from .model import Statements
+from .rules import run_rules
+
+
+def _jsonable(table: Mapping) -> dict:
+    return {period: dict(values) for period, values in table.items()}
+
+
+def check(statements: Statements, *, abs_tol: float = 0.5, rel_tol: float = 1e-4,
+          rules: Iterable[str] | None = None) -> AuditReport:
+    """Check ``statements`` against the accounting invariants.
+
+    Parameters
+    ----------
+    statements:
+        A :class:`Statements` instance in the canonical schema.
+    abs_tol, rel_tol:
+        A check passes when the discrepancy is within
+        ``max(abs_tol, rel_tol * abs(expected))``. The defaults absorb the
+        rounding found in statements reported in whole millions.
+    rules:
+        Optional set of rule ids to restrict the report to.
+    """
+    if not isinstance(statements, Statements):
+        raise TypeError("check() expects a Statements instance")
+
+    outcomes = run_rules(statements, abs_tol, rel_tol)
+    if rules is not None:
+        wanted = set(rules)
+        outcomes = [o for o in outcomes if o.rule_id in wanted]
+
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "periods": list(statements.periods),
+        "abs_tol": abs_tol,
+        "rel_tol": rel_tol,
+        "input_hash": data_hash({
+            "periods": list(statements.periods),
+            "is": _jsonable(statements.income_statement),
+            "bs": _jsonable(statements.balance_sheet),
+            "cf": _jsonable(statements.cash_flow),
+        }),
+    }
+    return AuditReport(tuple(outcomes), meta)

finvariant-0.1.0/finvariant/model.py

@@ -0,0 +1,145 @@
+"""Canonical financial-statement schema and the ``Statements`` container.
+
+Sign convention (the checks assume it; finvariant does not parse or convert):
+
+- Income statement: revenue positive; expenses (``cogs``, ``operating_expenses``,
+  ``interest_expense``, ``tax``) entered as positive magnitudes, so
+  ``net_income = ((revenue - cogs) - operating_expenses + other_income
+  - interest_expense) - tax``.
+- Balance sheet: every line positive as normally presented. ``treasury_stock``
+  and an accumulated deficit may be negative.
+- Cash flow: every line signed by its effect on cash (inflows positive,
+  outflows negative). So ``capex``, ``debt_repaid``, ``share_buybacks`` and
+  ``dividends_paid`` are negative, and
+  ``net_change_in_cash = cfo + cfi + cff + fx_effect``.
+
+Provide only the fields you have. A check whose inputs are missing is reported
+as skipped, never failed. To check that a subtotal foots, provide its line
+items as well as the subtotal; partial line items are reported as not footing.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Mapping
+
+# Income statement: (subtotal, plus_terms, minus_terms). A subtotal must equal
+# the sum of the plus terms minus the sum of the minus terms.
+IS_RELATIONS: list[tuple[str, list[str], list[str]]] = [
+    ("gross_profit", ["revenue"], ["cogs"]),
+    ("operating_income", ["gross_profit"], ["operating_expenses"]),
+    ("pretax_income", ["operating_income", "other_income"], ["interest_expense"]),
+    ("net_income", ["pretax_income"], ["tax"]),
+]
+IS_FIELDS: set[str] = {
+    "revenue", "cogs", "gross_profit", "operating_expenses", "operating_income",
+    "other_income", "interest_expense", "pretax_income", "tax", "net_income",
+    "depreciation_amortization",
+}
+
+# Balance sheet sections: subtotal -> line items that should sum to it.
+BS_SECTIONS: dict[str, list[str]] = {
+    "total_current_assets": [
+        "cash", "short_term_investments", "accounts_receivable", "inventory",
+        "prepaid_expenses", "other_current_assets",
+    ],
+    "total_non_current_assets": [
+        "ppe_net", "goodwill", "intangible_assets", "long_term_investments",
+        "deferred_tax_assets", "other_non_current_assets",
+    ],
+    "total_current_liabilities": [
+        "accounts_payable", "short_term_debt", "accrued_liabilities",
+        "deferred_revenue", "current_portion_long_term_debt",
+        "other_current_liabilities",
+    ],
+    "total_non_current_liabilities": [
+        "long_term_debt", "deferred_tax_liabilities", "pension_liabilities",
+        "other_non_current_liabilities",
+    ],
+    "total_equity": [
+        "common_stock", "additional_paid_in_capital", "retained_earnings",
+        "treasury_stock", "accumulated_oci", "minority_interest", "other_equity",
+    ],
+}
+# Higher-level balance-sheet sums.
+BS_TOTALS: dict[str, list[str]] = {
+    "total_assets": ["total_current_assets", "total_non_current_assets"],
+    "total_liabilities": ["total_current_liabilities", "total_non_current_liabilities"],
+}
+BS_FIELDS: set[str] = (
+    {item for items in BS_SECTIONS.values() for item in items}
+    | set(BS_SECTIONS) | set(BS_TOTALS)
+)
+
+# Cash flow sections: subtotal -> line items that should sum to it.
+CF_SECTIONS: dict[str, list[str]] = {
+    "cfo": [
+        "net_income", "depreciation_amortization", "stock_based_compensation",
+        "deferred_taxes", "change_in_accounts_receivable", "change_in_inventory",
+        "change_in_accounts_payable", "change_in_working_capital", "other_operating",
+    ],
+    "cfi": [
+        "capex", "acquisitions", "divestitures", "purchases_of_investments",
+        "sales_of_investments", "other_investing",
+    ],
+    "cff": [
+        "debt_issued", "debt_repaid", "equity_issued", "share_buybacks",
+        "dividends_paid", "other_financing",
+    ],
+}
+CF_OTHER: list[str] = ["fx_effect", "net_change_in_cash", "beginning_cash", "ending_cash"]
+CF_FIELDS: set[str] = (
+    {item for items in CF_SECTIONS.values() for item in items}
+    | set(CF_SECTIONS) | set(CF_OTHER)
+)
+
+
+def _validate_period(name: str, period: str, values: Mapping[str, float],
+                     valid: set[str]) -> None:
+    unknown = sorted(set(values) - valid)
+    if unknown:
+        raise ValueError(
+            f"{name} for period {period!r} has unknown fields: {unknown}. "
+            f"Map them to a canonical role or an 'other_*' line."
+        )
+    for key, value in values.items():
+        if not isinstance(value, (int, float)) or isinstance(value, bool):
+            raise ValueError(f"{name}[{period!r}][{key!r}] must be a number")
+        if not math.isfinite(float(value)):
+            raise ValueError(f"{name}[{period!r}][{key!r}] must be finite")
+
+
+@dataclass
+class Statements:
+    """A set of financial statements, by period, in the canonical schema."""
+
+    periods: list[str]
+    income_statement: Mapping[str, Mapping[str, float]] = field(default_factory=dict)
+    balance_sheet: Mapping[str, Mapping[str, float]] = field(default_factory=dict)
+    cash_flow: Mapping[str, Mapping[str, float]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.periods or not all(isinstance(p, str) for p in self.periods):
+            raise ValueError("periods must be a non-empty list of period labels")
+        if len(set(self.periods)) != len(self.periods):
+            raise ValueError("periods must be unique")
+        known = set(self.periods)
+        for name, table, valid in (
+            ("income_statement", self.income_statement, IS_FIELDS),
+            ("balance_sheet", self.balance_sheet, BS_FIELDS),
+            ("cash_flow", self.cash_flow, CF_FIELDS),
+        ):
+            extra = set(table) - known
+            if extra:
+                raise ValueError(f"{name} has periods not in 'periods': {sorted(extra)}")
+            for period, values in table.items():
+                _validate_period(name, period, values, valid)
+
+    def at(self, period: str) -> dict[str, dict[str, float]]:
+        """The three statements for one period as plain dicts (missing -> empty)."""
+        return {
+            "is": dict(self.income_statement.get(period, {})),
+            "bs": dict(self.balance_sheet.get(period, {})),
+            "cf": dict(self.cash_flow.get(period, {})),
+        }

finvariant-0.1.0/finvariant/rules.py

@@ -0,0 +1,189 @@
+"""The accounting-invariant catalogue.
+
+Each rule reads only the fields it needs. A rule whose inputs are absent emits
+nothing; a subtotal given without its line items emits a ``skip``; an applicable
+rule emits ``pass`` or ``fail``.
+"""
+
+from __future__ import annotations
+
+from ._result import ERROR, FAIL, PASS, SKIP, WARNING, RuleOutcome
+from .model import BS_SECTIONS, BS_TOTALS, CF_SECTIONS, IS_RELATIONS, Statements
+
+IS_DESC = {
+    "gross_profit": "gross profit = revenue - cogs",
+    "operating_income": "operating income = gross profit - operating expenses",
+    "pretax_income": "pretax income = operating income + other income - interest",
+    "net_income": "net income = pretax income - tax",
+}
+BS_SECTION_DESC = {
+    "total_current_assets": "current assets foot",
+    "total_non_current_assets": "non-current assets foot",
+    "total_current_liabilities": "current liabilities foot",
+    "total_non_current_liabilities": "non-current liabilities foot",
+    "total_equity": "equity foots",
+}
+BS_TOTAL_DESC = {
+    "total_assets": "total assets = current + non-current assets",
+    "total_liabilities": "total liabilities = current + non-current liabilities",
+}
+CF_SECTION_DESC = {
+    "cfo": "operating cash flow foots",
+    "cfi": "investing cash flow foots",
+    "cff": "financing cash flow foots",
+}
+
+
+def _present(d: dict, keys: list[str]) -> list[str]:
+    return [k for k in keys if k in d]
+
+
+def _sum(d: dict, keys: list[str]) -> float:
+    return sum(d[k] for k in keys if k in d)
+
+
+def _close(expected: float, actual: float, abs_tol: float, rel_tol: float) -> bool:
+    return abs(actual - expected) <= max(abs_tol, rel_tol * abs(expected))
+
+
+def _check(rule_id, desc, statement, period, severity,
+           expected, actual, abs_tol, rel_tol) -> RuleOutcome:
+    status = PASS if _close(expected, actual, abs_tol, rel_tol) else FAIL
+    return RuleOutcome(rule_id, desc, statement, period, status, severity,
+                       round(float(expected), 6), round(float(actual), 6),
+                       round(float(actual) - float(expected), 6))
+
+
+def _skip(rule_id, desc, statement, period, severity, message) -> RuleOutcome:
+    return RuleOutcome(rule_id, desc, statement, period, SKIP, severity,
+                       message=message)
+
+
+def _income_relations(out, cur, period, at, rt) -> None:
+    isd = cur["is"]
+    for target, plus, minus in IS_RELATIONS:
+        if target not in isd:
+            continue
+        if plus[0] not in isd:
+            out.append(_skip(f"FOOT.is.{target}", IS_DESC[target], "IS", period,
+                             ERROR, f"{plus[0]} not provided"))
+            continue
+        expected = _sum(isd, plus) - _sum(isd, minus)
+        out.append(_check(f"FOOT.is.{target}", IS_DESC[target], "IS", period,
+                          ERROR, expected, isd[target], at, rt))
+
+
+def _bs_sections(out, cur, period, at, rt) -> None:
+    bs = cur["bs"]
+    for subtotal, items in BS_SECTIONS.items():
+        if subtotal not in bs:
+            continue
+        present = _present(bs, items)
+        if not present:
+            out.append(_skip(f"FOOT.bs.{subtotal}", BS_SECTION_DESC[subtotal], "BS",
+                             period, ERROR, "no line items provided"))
+            continue
+        out.append(_check(f"FOOT.bs.{subtotal}", BS_SECTION_DESC[subtotal], "BS",
+                          period, ERROR, _sum(bs, present), bs[subtotal], at, rt))
+
+
+def _bs_totals(out, cur, period, at, rt) -> None:
+    bs = cur["bs"]
+    for total, parts in BS_TOTALS.items():
+        if total not in bs or not all(p in bs for p in parts):
+            continue
+        out.append(_check(f"FOOT.bs.{total}", BS_TOTAL_DESC[total], "BS", period,
+                          ERROR, _sum(bs, parts), bs[total], at, rt))
+
+
+def _accounting_equation(out, cur, period, at, rt) -> None:
+    bs = cur["bs"]
+    if not all(k in bs for k in ("total_assets", "total_liabilities", "total_equity")):
+        return
+    out.append(_check("EQ.accounting_equation",
+                      "assets = liabilities + equity", "BS", period, ERROR,
+                      bs["total_liabilities"] + bs["total_equity"],
+                      bs["total_assets"], at, rt))
+
+
+def _cf_sections(out, cur, period, at, rt) -> None:
+    cf = cur["cf"]
+    for subtotal, items in CF_SECTIONS.items():
+        if subtotal not in cf:
+            continue
+        present = _present(cf, items)
+        if not present:
+            out.append(_skip(f"FOOT.cf.{subtotal}", CF_SECTION_DESC[subtotal], "CF",
+                             period, ERROR, "no line items provided"))
+            continue
+        out.append(_check(f"FOOT.cf.{subtotal}", CF_SECTION_DESC[subtotal], "CF",
+                          period, ERROR, _sum(cf, present), cf[subtotal], at, rt))
+
+
+def _cf_net_change(out, cur, period, at, rt) -> None:
+    cf = cur["cf"]
+    if not all(k in cf for k in ("cfo", "cfi", "cff", "net_change_in_cash")):
+        return
+    expected = cf["cfo"] + cf["cfi"] + cf["cff"] + cf.get("fx_effect", 0.0)
+    out.append(_check("FOOT.cf.net_change",
+                      "net change in cash = cfo + cfi + cff", "CF", period, ERROR,
+                      expected, cf["net_change_in_cash"], at, rt))
+
+
+def _cash_ties(out, cur, prev, period, at, rt) -> None:
+    cf, bs = cur["cf"], cur["bs"]
+    if all(k in cf for k in ("net_change_in_cash", "beginning_cash", "ending_cash")):
+        out.append(_check("CASH.net_change_ties",
+                          "net change = ending cash - beginning cash", "CF", period,
+                          ERROR, cf["ending_cash"] - cf["beginning_cash"],
+                          cf["net_change_in_cash"], at, rt))
+    if "ending_cash" in cf and "cash" in bs:
+        out.append(_check("CASH.ending_ties",
+                          "cash flow ending cash = balance sheet cash", "BS/CF",
+                          period, ERROR, bs["cash"], cf["ending_cash"], at, rt))
+    if prev is not None and "beginning_cash" in cf and "cash" in prev["bs"]:
+        out.append(_check("CASH.beginning_ties",
+                          "beginning cash = prior period balance sheet cash", "BS/CF",
+                          period, ERROR, prev["bs"]["cash"], cf["beginning_cash"],
+                          at, rt))
+
+
+def _articulation(out, cur, prev, period, at, rt) -> None:
+    isd, bs, cf = cur["is"], cur["bs"], cur["cf"]
+
+    if "net_income" in isd and "net_income" in cf:
+        out.append(_check("ART.net_income",
+                          "net income agrees between income statement and cash flow",
+                          "IS/CF", period, ERROR, isd["net_income"], cf["net_income"],
+                          at, rt))
+
+    ni = isd.get("net_income", cf.get("net_income"))
+    if (prev is not None and "retained_earnings" in bs
+            and "retained_earnings" in prev["bs"] and ni is not None):
+        dividends = cf.get("dividends_paid", 0.0)
+        expected = prev["bs"]["retained_earnings"] + ni + dividends
+        out.append(_check("ART.retained_earnings",
+                          "retained earnings = prior + net income - dividends", "BS",
+                          period, ERROR, expected, bs["retained_earnings"], at, rt))
+
+    if "depreciation_amortization" in cf and "depreciation_amortization" in isd:
+        out.append(_check("ART.depreciation",
+                          "depreciation agrees between income statement and cash flow",
+                          "IS/CF", period, WARNING, isd["depreciation_amortization"],
+                          cf["depreciation_amortization"], at, rt))
+
+
+def run_rules(s: Statements, abs_tol: float, rel_tol: float) -> list[RuleOutcome]:
+    out: list[RuleOutcome] = []
+    for i, period in enumerate(s.periods):
+        cur = s.at(period)
+        prev = s.at(s.periods[i - 1]) if i > 0 else None
+        _income_relations(out, cur, period, abs_tol, rel_tol)
+        _bs_sections(out, cur, period, abs_tol, rel_tol)
+        _bs_totals(out, cur, period, abs_tol, rel_tol)
+        _accounting_equation(out, cur, period, abs_tol, rel_tol)
+        _cf_sections(out, cur, period, abs_tol, rel_tol)
+        _cf_net_change(out, cur, period, abs_tol, rel_tol)
+        _cash_ties(out, cur, prev, period, abs_tol, rel_tol)
+        _articulation(out, cur, prev, period, abs_tol, rel_tol)
+    return out

finvariant-0.1.0/finvariant.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: finvariant
+Version: 0.1.0
+Summary: Deterministic integrity checks for financial statements: does the balance sheet balance, does the cash flow tie out, do the three statements articulate. Verifies, does not parse or build.
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/finvariant
+Project-URL: Repository, https://github.com/arikanatakan/finvariant
+Project-URL: Issues, https://github.com/arikanatakan/finvariant/issues
+Keywords: accounting,financial-statements,audit,tie-out,integrity,balance-sheet,income-statement,cash-flow,three-statement-model,financial-modeling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# finvariant
+
+[![CI](https://github.com/arikanatakan/finvariant/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/finvariant/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/finvariant)](https://pypi.org/project/finvariant/)
+[![License: MIT](https://img.shields.io/github/license/arikanatakan/finvariant)](LICENSE)
+
+Deterministic integrity checks for financial statements.
+
+Give finvariant income statement, balance sheet and cash flow data; it verifies
+the accounting invariants - the balance sheet balances, the cash flow ties to
+the balance sheet, subtotals foot, and the three statements articulate - and
+returns a structured, auditable report. It verifies; it does not parse, fetch
+or build statements.
+
+## Motivation
+
+Python has plenty of libraries to *retrieve* statements (financetoolkit, the SEC
+tools) and to *build* models (DCF templates, FP&A scripts). What none of them do
+is *check that a set of statements or a model is internally consistent*: that
+assets equal liabilities plus equity, that the cash flow's ending cash matches
+the balance sheet, that retained earnings roll forward by net income less
+dividends, that every subtotal foots. That check is exactly what a spreadsheet
+silently gets wrong - and surveys put an error in the large majority of business
+spreadsheets.
+
+finvariant encodes those invariants as deterministic, testable rules. The same
+thing a large language model cannot be trusted to get right (consistent
+arithmetic across linked statements), a small library can guarantee. Every
+result is one report: a verdict, the exact failing checks with expected vs
+actual, and provenance, so a verification can be reproduced and audited later.
+
+```
+pip install finvariant
+```
+
+No runtime dependencies.
+
+## Usage
+
+Catch an error:
+
+```python
+import finvariant as fv
+
+s = fv.Statements(
+    periods=["FY2024"],
+    balance_sheet={"FY2024": {
+        "total_assets": 540,          # should be 538
+        "total_liabilities": 158,
+        "total_equity": 380,
+    }},
+)
+
+r = fv.check(s)
+r.ok            # False
+print(r.summary())
+# finvariant audit - 2026-...
+#   1 checks run, 0 passed, 1 failed, 0 skipped
+#   [ERROR] EQ.accounting_equation assets = liabilities + equity (FY2024): expected 538, got 540, off by 2
+# Verdict: FAIL - statements do not tie out
+```
+
+Real statements tie out (Apple FY2024, from the 10-K):
+
+```python
+s = fv.Statements(
+    periods=["FY2024"],
+    income_statement={"FY2024": {
+        "revenue": 391035, "cogs": 210352, "gross_profit": 180683,
+        "operating_expenses": 57467, "operating_income": 123216,
+        "other_income": 269, "pretax_income": 123485, "tax": 29749,
+        "net_income": 93736,
+    }},
+    balance_sheet={"FY2024": {
+        "total_current_assets": 152987, "total_non_current_assets": 211993,
+        "total_assets": 364980,
+        "total_current_liabilities": 176392, "total_non_current_liabilities": 131638,
+        "total_liabilities": 308030,
+        "common_stock": 83276, "retained_earnings": -19154,
+        "accumulated_oci": -7172, "total_equity": 56950,
+    }},
+)
+fv.check(s).ok          # True
+```
+
+The report carries named findings, counts, `ok`, `summary()` and a JSON-safe
+`to_dict()` with provenance (version, input hash, timestamp).
+
+## What it checks
+
+| Group | Invariant |
+|-------|-----------|
+| Footing | every subtotal equals the sum of its line items (all three statements) |
+| Equation | total assets = total liabilities + total equity |
+| Cash | net change = cfo + cfi + cff; ending cash ties to the balance sheet; beginning cash ties to the prior period |
+| Articulation | net income agrees across statements; retained earnings roll forward by net income less dividends |
+
+Provide only the fields you have: a check whose inputs are missing is reported
+as skipped, never failed. Tolerances absorb the rounding in statements reported
+in whole millions.
+
+## Status
+
+Version 0.1.0. Single entity, single currency, one or more periods, in a
+canonical schema. The `Statements` input and `AuditReport` output are the
+contract and are append-only from here.
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| 0.2 | roll-forward checks (PP&E = opening + capex - depreciation - disposals; debt; equity); working-capital changes reconciled to operating cash flow |
+| 0.3 | an MCP server so an agent can verify financial statements it reads or generates |
+| 0.4 | optional readers to map common export formats into the canonical schema |
+
+Out of scope: retrieving statements (see financetoolkit, the SEC tools),
+building or forecasting models, ratio analysis, consolidation and currency
+translation.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

finvariant-0.1.0/finvariant.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+finvariant/__init__.py
+finvariant/_result.py
+finvariant/_version.py
+finvariant/check.py
+finvariant/model.py
+finvariant/py.typed
+finvariant/rules.py
+finvariant.egg-info/PKG-INFO
+finvariant.egg-info/SOURCES.txt
+finvariant.egg-info/dependency_links.txt
+finvariant.egg-info/requires.txt
+finvariant.egg-info/top_level.txt
+tests/test_check.py
+tests/test_model.py
+tests/test_validation_suite.py

finvariant-0.1.0/finvariant.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

finvariant-0.1.0/finvariant.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=7
+ruff
+build

finvariant-0.1.0/finvariant.egg-info/top_level.txt

@@ -0,0 +1 @@
+finvariant

finvariant-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "finvariant"
+version = "0.1.0"
+description = "Deterministic integrity checks for financial statements: does the balance sheet balance, does the cash flow tie out, do the three statements articulate. Verifies, does not parse or build."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Atakan Arikan" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = [
+    "accounting", "financial-statements", "audit", "tie-out", "integrity",
+    "balance-sheet", "income-statement", "cash-flow", "three-statement-model",
+    "financial-modeling",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff", "build"]
+
+[project.urls]
+Homepage = "https://github.com/arikanatakan/finvariant"
+Repository = "https://github.com/arikanatakan/finvariant"
+Issues = "https://github.com/arikanatakan/finvariant/issues"
+
+[tool.setuptools.packages.find]
+include = ["finvariant*"]
+
+[tool.setuptools.package-data]
+finvariant = ["py.typed"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

finvariant-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

finvariant-0.1.0/tests/test_check.py

@@ -0,0 +1,78 @@
+import json
+
+import pytest
+
+import finvariant as fv
+
+
+def _balanced(assets=100, liabilities=60, equity=40):
+    return fv.Statements(
+        periods=["FY2024"],
+        balance_sheet={"FY2024": {
+            "total_assets": assets, "total_liabilities": liabilities,
+            "total_equity": equity,
+        }},
+    )
+
+
+def test_equation_passes():
+    r = fv.check(_balanced())
+    assert r.ok
+    assert r.n_failed == 0
+    assert any(o.rule_id == "EQ.accounting_equation" and o.status == "pass"
+               for o in r.outcomes)
+
+
+def test_equation_fails_with_numbers():
+    r = fv.check(_balanced(assets=101))
+    assert not r.ok
+    assert len(r.findings) == 1
+    f = r.findings[0]
+    assert f.rule_id == "EQ.accounting_equation"
+    assert f.expected == 100 and f.actual == 101 and f.difference == 1
+
+
+def test_relative_tolerance_absorbs_rounding():
+    s = _balanced(assets=1000050, liabilities=1000000, equity=0)
+    assert fv.check(s).ok                    # 50 is within 0.01% of 1,000,000
+    assert not fv.check(s, rel_tol=0.0).ok   # demanded exact, so it fails
+
+
+def test_rules_filter():
+    r = fv.check(_balanced(), rules=["EQ.accounting_equation"])
+    assert {o.rule_id for o in r.outcomes} == {"EQ.accounting_equation"}
+
+
+def test_subtotal_without_items_skips():
+    s = fv.Statements(periods=["FY2024"],
+                      balance_sheet={"FY2024": {"total_current_assets": 100}})
+    r = fv.check(s)
+    assert any(o.rule_id == "FOOT.bs.total_current_assets" and o.status == "skip"
+               for o in r.outcomes)
+    assert r.ok  # a skip never fails the report
+
+
+def test_to_dict_is_json_serializable():
+    d = fv.check(_balanced()).to_dict()
+    json.dumps(d)
+    assert d["schema"] == 1
+    assert d["ok"] is True
+    assert "input_hash" in d["meta"]
+
+
+def test_summary_is_plain_text():
+    t = fv.check(_balanced()).summary()
+    assert "finvariant" in t
+    assert "Verdict" in t
+    assert "—" not in t  # no em dash
+
+
+def test_provenance_changes_with_input():
+    a = fv.check(_balanced()).meta["input_hash"]
+    b = fv.check(_balanced(assets=200, liabilities=100, equity=100)).meta["input_hash"]
+    assert a != b
+
+
+def test_typeerror_on_non_statements():
+    with pytest.raises(TypeError):
+        fv.check({"periods": ["FY2024"]})

finvariant-0.1.0/tests/test_model.py

@@ -0,0 +1,41 @@
+import pytest
+
+from finvariant import Statements
+
+
+def test_unknown_field_raises():
+    with pytest.raises(ValueError):
+        Statements(periods=["FY2024"], balance_sheet={"FY2024": {"frobnicate": 1}})
+
+
+def test_non_finite_raises():
+    with pytest.raises(ValueError):
+        Statements(periods=["FY2024"], balance_sheet={"FY2024": {"cash": float("nan")}})
+
+
+def test_bool_rejected():
+    with pytest.raises(ValueError):
+        Statements(periods=["FY2024"], balance_sheet={"FY2024": {"cash": True}})
+
+
+def test_empty_periods_raises():
+    with pytest.raises(ValueError):
+        Statements(periods=[])
+
+
+def test_duplicate_periods_raise():
+    with pytest.raises(ValueError):
+        Statements(periods=["FY2024", "FY2024"])
+
+
+def test_period_not_declared_raises():
+    with pytest.raises(ValueError):
+        Statements(periods=["FY2024"], balance_sheet={"FY2025": {"cash": 1}})
+
+
+def test_at_returns_three_statements():
+    s = Statements(periods=["FY2024"], balance_sheet={"FY2024": {"cash": 10}})
+    at = s.at("FY2024")
+    assert set(at) == {"is", "bs", "cf"}
+    assert at["bs"]["cash"] == 10
+    assert at["is"] == {}

finvariant-0.1.0/tests/test_validation_suite.py

@@ -0,0 +1,30 @@
+"""Run finvariant against the cases in validation_cases.json: a hand-built
+consistent model, Apple's real FY2024 statements, and one isolated breakage per
+invariant.
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+
+import finvariant as fv
+
+CASES = json.loads((Path(__file__).parent / "validation_cases.json").read_text())["cases"]
+
+
+def _build(case):
+    return fv.Statements(
+        periods=case["periods"],
+        income_statement=case.get("income_statement", {}),
+        balance_sheet=case.get("balance_sheet", {}),
+        cash_flow=case.get("cash_flow", {}),
+    )
+
+
+@pytest.mark.parametrize("case", CASES, ids=[c["id"] for c in CASES])
+def test_case(case):
+    report = fv.check(_build(case))
+    assert report.ok is case["expect_ok"]
+    failed = {o.rule_id for o in report.findings}
+    assert failed == set(case["expect_failed_rules"])