calcfinc 0.1.0__tar.gz

calcfinc-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+.cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.db
+*.sqlite
+.coverage
+htmlcov/
+
+# kept locally, not published
+docs/regulatory-definitions.md

calcfinc-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes are listed here. The project follows [semantic versioning](https://semver.org/);
+while the version is 0.x, a minor release may change the public API, and any such change is listed
+under "Changed". A change to a built-in ratio definition raises its `definition_version`.
+
+## 0.1.0 - first release
+
+### What it is
+
+An exact-decimal engine that turns periodic statements into ratios, growth, CAGR, valuation,
+DuPont, trailing twelve months and segment attribution, with the formula, the input facts and the
+limitations on every result. No runtime dependencies; Python 3.11 to 3.13.
+
+### Added
+
+- `FinancialEngine` with `get_metric`, `get_ratio`, `get_valuation`, `get_growth`, `get_cagr`,
+  `compare_periods`, `compare_companies`, `decompose_metric`, `calculate`, `check`, `check_periods`,
+  segment queries, and loaders for CSV (long and wide), records and pandas DataFrames.
+- More than a hundred ratios and derived quantities as formula strings in an open registry
+  (`register_metric`, `register_ratio`); trailing-twelve-month forms through `ttm(x)`; average
+  balances through `prior(x)`; a restricted Decimal formula language.
+- Definitions reconciled across ACCA, the FTC Quarterly Financial Report, MCA/ICAI, RBI and SEBI,
+  with the Indian forms as `india.*` and RBI-form bank ratios (`bank.*`).
+- Sector handling: ratios that do not describe a bank or an insurer return `None` with the reason;
+  sector is declared or inferred from the facts.
+- Source adapters: SEC `companyfacts` (exact periods, restatement versions, derived fourth
+  quarters, US bank lines, a polite download helper) and Indian exchange XBRL (Ind-AS), tested on
+  19 US and 20 Indian companies' real filings.
+- Restatements kept as versions by `reported_at`; each input of a result carries it; a result warns
+  when one period's inputs come from filings far apart.
+- A SQLite store that keeps every value as exact decimal text.
+- A manual whose examples are run by the test suite, and a ratio reference generated from the code.
+
+### Changed
+
+Nothing: this is the first release.
+
+### Known limitations
+
+- Point-in-time views (`as_of`) for restated data are not implemented.
+- IFRS filers, SEC insurers and 20-F/40-F filers are not mapped.
+- EBIT is `profit before exceptional items + finance costs`, so it includes non-operating gains.
+- LLM function-calling schemas and an MCP server are planned for a later release.

calcfinc-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+Thanks for helping. This project cares about exactness and honesty more than breadth, so a few
+rules matter more than usual.
+
+## Set up
+
+```bash
+git clone https://github.com/Am1n1602/calcfinc && cd calcfinc
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"      # Windows: .venv\Scripts\python
+.venv/bin/python -m pytest && .venv/bin/ruff check . && .venv/bin/mypy
+```
+
+All three must pass. CI runs them on Python 3.11, 3.12 and 3.13 on Linux, Windows and macOS.
+
+## The rules
+
+1. **No floats.** Numbers are `Decimal`, `int` or `str`. Anything that lets a float through to a
+   result is a bug. Arithmetic goes through `calcfinc.num`.
+2. **Missing is `None` with a reason.** Never zero, never an estimate. If a definition needs a
+   substitute, make it a labelled fallback so the result announces it.
+3. **The core stays generic.** No country, exchange, regulator or vendor names in `src/calcfinc`
+   outside `adapters/` (a test enforces this). Country-specific inputs and ratios belong in an
+   adapter (see `adapters/ind_as_xbrl/vocab.py`).
+4. **Standard library only** at runtime. The network may be used only in
+   `adapters/sec_companyfacts/fetch.py` (a test enforces this).
+5. **No real data in the repository.** Test and example data is synthetic and written for the test.
+   Do not commit exchange, SEC or vendor data or anything derived from it.
+6. **Definitions need evidence.** A new or changed ratio comes with the source of its definition.
+   If regulators or standards disagree, say so in the pull request and in the ratio's `label`, and
+   pick one with a reason. Changing an existing definition bumps its `version`.
+
+## Tests
+
+Write a test when there is behaviour to pin down, with expected values **worked out by hand**
+(show the arithmetic in a comment), never copied from the code's output. Fix the code, not the
+test, when they disagree. A bug fix comes with a test that fails without it.
+
+The documentation is tested too: every ```` ```python ```` block in `README.md` and
+`docs/manual.md` is run, and `expr  # -> value` lines are checked. `docs/ratios.md` is generated;
+after changing a ratio or metric run
+
+```bash
+python scripts/gen_ratio_docs.py
+```
+
+and commit the result (a test fails if it is stale).
+
+## Adding a source adapter
+
+An adapter reads one source's tags and conventions and produces `FinancialFact`s through the
+loaders; it never changes how a ratio is computed. Test it on synthetic data in the repository and,
+if you can, on real filings *outside* it, and record what was and was not verified in
+`docs/adapters.md`.
+
+## Style
+
+`ruff` (line length 120) and `mypy --strict` are the style guide. Comments explain why, not what.
+
+## Releasing (maintainers)
+
+1. Set `__version__` in `src/calcfinc/__init__.py`, move the changelog entry from "Unreleased" to the
+   new version, regenerate `docs/ratios.md`, and make sure CI is green on `main`.
+2. One-time setup: on PyPI (and on TestPyPI) add a **trusted publisher** for owner `Am1n1602`,
+   repository `calcfinc`, workflow `release.yml`, environment `pypi` (`testpypi` on TestPyPI), and create
+   those two environments in the repository settings. No API token is ever stored.
+3. Dry run: Actions, "release", **Run workflow** publishes the build to TestPyPI. Install it with
+   `pip install --index-url https://test.pypi.org/simple/ --no-deps calcfinc` and try it.
+4. Release: `git tag v0.1.0 && git push origin v0.1.0`. The workflow refuses to publish if the tag
+   and `__version__` disagree.
+
+## Pull requests
+
+Keep one concern per PR, update `CHANGELOG.md` for anything a user would notice, and describe
+how you checked it. By contributing you agree your work is released under the MIT licence.

calcfinc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Am1n1602 (Aman Gautam)
+
+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.

calcfinc-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: calcfinc
+Version: 0.1.0
+Summary: Auditable financial metrics from periodic statements of any entity: every result carries its formula, input facts and limitations.
+Project-URL: Homepage, https://github.com/Am1n1602/calcfinc
+Project-URL: Documentation, https://github.com/Am1n1602/calcfinc/blob/main/docs/manual.md
+Project-URL: Source, https://github.com/Am1n1602/calcfinc
+Project-URL: Issues, https://github.com/Am1n1602/calcfinc/issues
+Project-URL: Changelog, https://github.com/Am1n1602/calcfinc/blob/main/CHANGELOG.md
+Author: Am1n1602 (Aman Gautam)
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,decimal,finance,financial-ratios,financial-statements,provenance,sec,xbrl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: coverage>=7; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pandas>=2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# calcfinc
+
+[![ci](https://github.com/Am1n1602/calcfinc/actions/workflows/ci.yml/badge.svg)](https://github.com/Am1n1602/calcfinc/actions/workflows/ci.yml)
+
+**Auditable financial metrics from the statements of any entity.** Give it periodic figures (a
+CSV, a pandas frame, an SEC filing, an Indian exchange filing) and ask for ratios, growth,
+CAGR, valuation, DuPont, trailing twelve months. Every answer carries the formula that produced
+it, the exact figures it used, and a plain-language note whenever something was substituted or
+could not be computed.
+
+```python skip
+roe = eng.get_ratio("Acme Inc", "roe")
+roe.value        # Decimal('25')
+roe.formula      # '100 * net_profit / total_equity'
+roe.inputs       # the facts used: metric, value, period, currency, source, date reported
+roe.limitations  # () - or why the value is None, or what was substituted
+```
+
+- **Exact.** Every number is a `Decimal`; floats are refused at every entrance. A result is the
+  same on any machine and any Python version.
+- **Honest.** A missing input gives `None` and the reason, never zero and never an estimate.
+- **Open.** More than a hundred ratios, each one a readable formula string
+  ([list](docs/ratios.md)). Add your own with `register_ratio`.
+- **Any entity.** Any currency, any fiscal calendar (March, 52/53-week...), months, quarters
+  and years, consolidated and standalone, banks and insurers.
+- **Zero runtime dependencies.** Python 3.11 or later; pandas is optional.
+
+> **Status: 0.1, beta.** Tested on 19 US and 20 Indian companies' real filings (see
+> [what has and has not been verified](docs/manual.md#15-what-has-and-has-not-been-verified)).
+> The API may still change in 0.x; changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```bash
+pip install calcfinc
+```
+
+## Quick start
+
+A CSV with one row per metric and one column per fiscal year:
+
+```csv acme.csv
+metric,FY2025,FY2026
+revenue,1000,1200
+net_profit,100,150
+total_equity,500,600
+total_assets,2000,2400
+```
+
+```python
+from calcfinc import FinancialEngine
+
+eng = FinancialEngine.from_csv("acme.csv", entity="Acme Inc", currency="USD")
+
+roe = eng.get_ratio("Acme Inc", "roe")
+roe.value                                        # -> 25
+roe.formula                                      # -> 100 * net_profit / total_equity
+
+# growth in percent, FY2025 to FY2026, and compound annual growth
+eng.get_growth("Acme Inc", "revenue").value      # -> 20
+eng.get_cagr("Acme Inc", "revenue").value        # -> 20
+```
+
+A figure that cannot be computed says why instead of guessing. This file has no cash flow
+statement:
+
+```python
+fcf = eng.get_ratio("Acme Inc", "free_cash_flow")
+fcf.value                                        # -> None
+print(fcf.limitations[0])
+```
+
+## What you can ask
+
+| | |
+|---|---|
+| `get_ratio`, `get_metric` | margins, returns, leverage, liquidity, efficiency, per-share, trailing twelve months |
+| `get_valuation` | P/E, P/B, EV/EBITDA, yields, market cap (you supply prices) |
+| `get_growth`, `get_cagr` | year on year, quarter on quarter, month on month, compound |
+| `compare_periods`, `compare_companies` | two periods side by side; rank entities (never across currencies) |
+| `decompose_metric` | DuPont (three and five factor), net-margin bridge |
+| `check`, `check_periods` | accounting identities; do the quarters add up to the year |
+| `get_segment_data`, `segment_growth` | segment revenue, contribution, growth |
+| `calculate` | any formula over numbers you give it |
+
+## Where data comes from
+
+CSV (long or wide), dicts, pandas, or your own storage; a SQLite file if you want it to persist.
+Two adapters read real filings:
+
+- **SEC `companyfacts`** (US-GAAP): exact periods, restatements kept as versions, the fourth
+  quarter derived, bank lines for banks.
+- **Indian exchange XBRL** (Ind-AS): April-March year, `india.*` ratios in the Schedule III and ICAI
+  forms, placeholder zeros not loaded.
+
+Both tie every fact to its filing. See [docs/adapters.md](docs/adapters.md). No market or vendor
+data is bundled, and there is no network access except one explicit SEC download helper.
+
+## Things it deliberately will not do
+
+- Convert currencies. Amounts in different currencies are listed, never ranked.
+- Annualise a quarterly ratio. It says "not annualised" and offers the trailing-twelve-month form.
+- Hide a substitution. A fallback definition, a derived quarter or a mixed restatement vintage is
+  always in `limitations`.
+- Apply operating-company ratios to a bank or an insurer. Interest cover, debt and the
+  working-capital ratios return `None` with the reason for financial companies.
+
+## Documentation
+
+- **[Manual](docs/manual.md)**: concepts, loading data, periods, every question you can ask,
+  reading results, custom ratios, running it in production, troubleshooting. Its examples are run
+  by the test suite.
+- [Ratio and metric reference](docs/ratios.md) (generated from the code)
+- [Fact format and CSV layouts](docs/fact-schema.md)
+- [Adapters and real-data results](docs/adapters.md)
+- [Examples](examples): seven runnable scripts with synthetic data
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"     # Windows: .venv\Scripts\python
+.venv/bin/python -m pytest && .venv/bin/ruff check . && .venv/bin/mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Licence
+
+MIT. Results are calculations, not investment advice.

calcfinc-0.1.0/README.md

@@ -0,0 +1,130 @@
+# calcfinc
+
+[![ci](https://github.com/Am1n1602/calcfinc/actions/workflows/ci.yml/badge.svg)](https://github.com/Am1n1602/calcfinc/actions/workflows/ci.yml)
+
+**Auditable financial metrics from the statements of any entity.** Give it periodic figures (a
+CSV, a pandas frame, an SEC filing, an Indian exchange filing) and ask for ratios, growth,
+CAGR, valuation, DuPont, trailing twelve months. Every answer carries the formula that produced
+it, the exact figures it used, and a plain-language note whenever something was substituted or
+could not be computed.
+
+```python skip
+roe = eng.get_ratio("Acme Inc", "roe")
+roe.value        # Decimal('25')
+roe.formula      # '100 * net_profit / total_equity'
+roe.inputs       # the facts used: metric, value, period, currency, source, date reported
+roe.limitations  # () - or why the value is None, or what was substituted
+```
+
+- **Exact.** Every number is a `Decimal`; floats are refused at every entrance. A result is the
+  same on any machine and any Python version.
+- **Honest.** A missing input gives `None` and the reason, never zero and never an estimate.
+- **Open.** More than a hundred ratios, each one a readable formula string
+  ([list](docs/ratios.md)). Add your own with `register_ratio`.
+- **Any entity.** Any currency, any fiscal calendar (March, 52/53-week...), months, quarters
+  and years, consolidated and standalone, banks and insurers.
+- **Zero runtime dependencies.** Python 3.11 or later; pandas is optional.
+
+> **Status: 0.1, beta.** Tested on 19 US and 20 Indian companies' real filings (see
+> [what has and has not been verified](docs/manual.md#15-what-has-and-has-not-been-verified)).
+> The API may still change in 0.x; changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```bash
+pip install calcfinc
+```
+
+## Quick start
+
+A CSV with one row per metric and one column per fiscal year:
+
+```csv acme.csv
+metric,FY2025,FY2026
+revenue,1000,1200
+net_profit,100,150
+total_equity,500,600
+total_assets,2000,2400
+```
+
+```python
+from calcfinc import FinancialEngine
+
+eng = FinancialEngine.from_csv("acme.csv", entity="Acme Inc", currency="USD")
+
+roe = eng.get_ratio("Acme Inc", "roe")
+roe.value                                        # -> 25
+roe.formula                                      # -> 100 * net_profit / total_equity
+
+# growth in percent, FY2025 to FY2026, and compound annual growth
+eng.get_growth("Acme Inc", "revenue").value      # -> 20
+eng.get_cagr("Acme Inc", "revenue").value        # -> 20
+```
+
+A figure that cannot be computed says why instead of guessing. This file has no cash flow
+statement:
+
+```python
+fcf = eng.get_ratio("Acme Inc", "free_cash_flow")
+fcf.value                                        # -> None
+print(fcf.limitations[0])
+```
+
+## What you can ask
+
+| | |
+|---|---|
+| `get_ratio`, `get_metric` | margins, returns, leverage, liquidity, efficiency, per-share, trailing twelve months |
+| `get_valuation` | P/E, P/B, EV/EBITDA, yields, market cap (you supply prices) |
+| `get_growth`, `get_cagr` | year on year, quarter on quarter, month on month, compound |
+| `compare_periods`, `compare_companies` | two periods side by side; rank entities (never across currencies) |
+| `decompose_metric` | DuPont (three and five factor), net-margin bridge |
+| `check`, `check_periods` | accounting identities; do the quarters add up to the year |
+| `get_segment_data`, `segment_growth` | segment revenue, contribution, growth |
+| `calculate` | any formula over numbers you give it |
+
+## Where data comes from
+
+CSV (long or wide), dicts, pandas, or your own storage; a SQLite file if you want it to persist.
+Two adapters read real filings:
+
+- **SEC `companyfacts`** (US-GAAP): exact periods, restatements kept as versions, the fourth
+  quarter derived, bank lines for banks.
+- **Indian exchange XBRL** (Ind-AS): April-March year, `india.*` ratios in the Schedule III and ICAI
+  forms, placeholder zeros not loaded.
+
+Both tie every fact to its filing. See [docs/adapters.md](docs/adapters.md). No market or vendor
+data is bundled, and there is no network access except one explicit SEC download helper.
+
+## Things it deliberately will not do
+
+- Convert currencies. Amounts in different currencies are listed, never ranked.
+- Annualise a quarterly ratio. It says "not annualised" and offers the trailing-twelve-month form.
+- Hide a substitution. A fallback definition, a derived quarter or a mixed restatement vintage is
+  always in `limitations`.
+- Apply operating-company ratios to a bank or an insurer. Interest cover, debt and the
+  working-capital ratios return `None` with the reason for financial companies.
+
+## Documentation
+
+- **[Manual](docs/manual.md)**: concepts, loading data, periods, every question you can ask,
+  reading results, custom ratios, running it in production, troubleshooting. Its examples are run
+  by the test suite.
+- [Ratio and metric reference](docs/ratios.md) (generated from the code)
+- [Fact format and CSV layouts](docs/fact-schema.md)
+- [Adapters and real-data results](docs/adapters.md)
+- [Examples](examples): seven runnable scripts with synthetic data
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"     # Windows: .venv\Scripts\python
+.venv/bin/python -m pytest && .venv/bin/ruff check . && .venv/bin/mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Licence
+
+MIT. Results are calculations, not investment advice.

calcfinc-0.1.0/SECURITY.md

@@ -0,0 +1,37 @@
+# Security policy
+
+## Supported versions
+
+Only the latest release receives fixes. While the version is 0.x, upgrade to the newest 0.x.
+
+## Reporting a vulnerability
+
+Please **do not open a public issue** for a security problem. Use GitHub's private reporting:
+the repository's **Security** tab, then **Report a vulnerability**
+(<https://github.com/Am1n1602/calcfinc/security/advisories/new>).
+
+Include what you found, the smallest input that shows it, and the version. You can expect an
+acknowledgement within a week. A confirmed problem is fixed in a new release and credited in the
+changelog unless you prefer otherwise.
+
+## What is in scope
+
+calcfinc parses text it is given, so these are the surfaces that matter:
+
+- **The formula evaluator.** Formulas are parsed with Python's `ast` and run by a small
+  interpreter that allows numbers, arithmetic, names and six functions. `eval` is never used. Input
+  that escapes this (attribute access, calls to other functions, a crash on deeply nested or
+  enormous input, unbounded memory or time) is a vulnerability.
+- **File readers.** The CSV loader, the SEC `companyfacts` JSON reader and the XBRL reader, which
+  uses the standard library's XML parser (it does not fetch external entities). Anything that makes
+  them execute code, read other files or exhaust resources on a reasonably sized input is in scope.
+- **Storage.** All SQL uses bound parameters; an injection is in scope.
+- **The one network call.** `sec_companyfacts.fetch_companyfacts` is the only code that can touch
+  the network. Anything that makes other code do so is in scope.
+
+## Out of scope
+
+- Wrong financial results are bugs, not vulnerabilities: please open a normal issue with the data.
+- Running calcfinc on untrusted XBRL with the stock parser is documented as a limit; see the manual's
+  security section for the hardened-parser route.
+- Denial of service by loading an enormous file you chose to load.

calcfinc-0.1.0/docs/adapters.md

@@ -0,0 +1,171 @@
+# Source adapters
+
+An adapter reads one source's tags and conventions and produces calcfinc facts. The core never
+imports an adapter, and an adapter never changes how a ratio is computed.
+
+| Adapter | Source | Notes |
+|---|---|---|
+| `calcfinc.adapters.ind_as_xbrl` | Indian exchange XBRL filings (.xbrl file, raw fact rows, or canonical records) | April-March year, INR, `india.*` ratios |
+| `calcfinc.adapters.sec_companyfacts` | The SEC's public `companyfacts` JSON | US-GAAP filers; IFRS is not mapped yet |
+
+## Ind-AS XBRL
+
+```python
+from calcfinc.adapters import ind_as_xbrl
+ind_as_xbrl.load_xbrl_file(repos, "results_consolidated.xbrl", entity="ACME")
+```
+
+- Three entry points, one per stage: `load_xbrl_file` (a filing), `load_raw_facts` (rows from
+  `parse_xbrl_file`), `load_canonical` / `load_canonical_file` (records already mapped to names).
+- The file's basis comes from its name (`consolidated` or `standalone`), or pass `basis=`.
+- Only whole-company contexts are read (`OneD`, `OneI`, `PY_D`...). Segment and note breakdowns
+  are ignored. Filings that tag the older `in-bse-fin:` prefix are matched by local concept name.
+- Some filers declare their reporting period as plain facts and leave the context without one;
+  those are recovered. Banks that omit a start date get it worked out from the financial year and
+  the quarter label, and only when that agrees with the declared end.
+- Numbers are parsed from the filing's text straight to `Decimal`. Indian formatting, accounting
+  negatives and a `sign="-"` attribute are handled.
+- Bank totals (equity, cash, liabilities) are built from their parts only when every part is
+  present; a reported total always wins.
+- **A record whose own arithmetic fails still loads**, but each of its facts carries a review
+  reason (`source record failed arithmetic checks: ...`) and the report lists the period.
+- **Zeros that mean "not applicable" are not loaded.** Real filings report an exact 0 where a
+  figure does not apply: a consolidated bank filing gives 0 for its whole NPA block (gross and net
+  NPA, both ratios, ROA, CET1, AT1); paid-up capital, face value and CET1 are never genuinely 0;
+  a coverage ratio of exactly 0 is a placeholder. Stored as numbers they would give a 0% NPA ratio
+  instead of "not reported". The block rule needs all four NPA figures to be zero together, so a
+  real zero (no exceptional items, no borrowings, no minority interest) is kept. Dropped names are
+  listed in `report.skipped`; pass `placeholder_zeros=False` to keep every zero.
+- **Two contexts that contradict each other.** A cumulative context can carry the quarter's own
+  dates with different values, and a context can carry a stale prior-year balance. The current
+  period's context (`OneD`/`OneI`, then `TwoD`..., then `PY_`) wins, the winner's fact is flagged
+  with what the other context said, and `report.conflicts` lists each one. The store never
+  decides by load order.
+- `paid_up_equity_capital / face_value_per_share` becomes a `shares_outstanding` fact marked as
+  derived, so valuation works.
+- The XML is read with the standard library, which does not fetch external entities. For a file
+  you do not trust, parse it with a hardened parser and use `map_facts`.
+- Pass `reported_at=` (the filing date) so a later revised filing is kept beside the original
+  instead of overwriting it.
+- **Original and Revision filings** carry the same board-meeting date and no filing date, so the
+  file cannot say which is later. Without `reported_at` a later load overwrites an earlier one for
+  the same period. `load_xbrl_files(repos, paths, entity=...)` loads every "Revision" after its
+  "Original" whatever order you give, so the correction wins. (19 revisions exist in the
+  author's 2,960 files; most have no original beside them.)
+
+## SEC companyfacts
+
+```python
+from calcfinc.adapters import sec_companyfacts as sec
+data = sec.read_companyfacts("CIK0000320193.json")      # a file you downloaded once
+sec.load_companyfacts(repos, data, ticker="AAPL")
+```
+
+- **Periods are matched on exact start and end dates.** The `fy` and `fp` fields in the JSON
+  describe the filing, not the period a figure covers, so they are never used to place a number.
+- **Tag choice is per period.** For each metric, the first concept in `tags.CANDIDATES` that the
+  filer reported for that exact period wins, and a lower-priority concept is flagged
+  `alternate_tag` in the fact's mapping reason. Filers change concepts over time, so the choice is
+  never made once for a whole history.
+- **Restatements are kept.** A figure that changes in a later filing becomes a second version with
+  `reported_at` set to that filing's date; the engine uses the latest. A later filing that merely
+  repeats a comparative figure adds nothing.
+- **The fourth quarter is derived.** The SEC reports no stand-alone Q4, so it is the year less the
+  nine-month figure (or less the three reported quarters). Cash-flow statements, which are
+  reported year-to-date only, become single quarters the same way. Derived facts are marked
+  `derived` with the arithmetic in the reason. This is what makes trailing-twelve-month ratios
+  work for SEC filers.
+- **Only currency amounts are derived.** Per-share figures are not additive, so a Q4 EPS is never
+  invented.
+- **Every fact points to its filing.** Each accession number becomes a source with the form and
+  the filing URL, so `result.inputs[...].source_id` leads back to the document.
+- The fiscal year end is inferred from the full-year figures (a 52/53-week year ending on 1 Feb is
+  a January year end). Pass `fiscal_year_end_month=` to override.
+- Facts carrying a dimension are ignored; amounts are already in base units; only 10-K, 10-Q, 20-F
+  and 40-F family filings are read (`forms=` to change). 8-Ks are ignored.
+- **US GAAP has no exceptional-items line**, so `pbt_before_exceptional` is set equal to pre-tax
+  income, marked `derived`, so EBIT-based ratios work.
+
+### Downloading, politely
+
+`fetch_companyfacts` is the only function in calcfinc that can use the network, and nothing else
+calls it. The SEC's [fair access rules](https://www.sec.gov/os/accessing-edgar-data) require:
+
+- a User-Agent that identifies you with a real contact (there is deliberately no default);
+- fewer than 10 requests per second (the helper keeps to 5 and never retries by itself);
+- downloading once and keeping the file; the data changes only when a company files.
+
+```python
+raw = sec.fetch_companyfacts(320193, "Jane Doe jane@example.com")
+open("CIK0000320193.json", "wb").write(raw)
+```
+
+## What is and is not verified
+
+- Every test in the repository uses synthetic data written for the test. No SEC or exchange data
+  is stored in this repository, and no test uses the network.
+- **Ind-AS, checked on real filings outside the repository** (the installed wheel, in a separate
+  environment, reading the author's earlier extraction output read-only): 2,938 raw `.xbrl`
+  filings were parsed and mapped, and compared with the earlier pipeline's output for the same
+  filing: 138,313 fields, all identical. Facts from the canonical files were compared with the
+  earlier database for eight companies: all 22,293 overlapping facts matched exactly. The
+  comparison is what found the placeholder zeros and the contradicting contexts above. It also
+  showed that the earlier database stored a 6-month cash-flow figure under the 3-month quarter
+  for one filing; this adapter does not.
+- **SEC, checked live** (the installed wheel, in a separate environment, downloading with
+  `fetch_companyfacts`): Apple, Microsoft and JPMorgan companyfacts, 3.8-8.0 MB each, loaded in
+  about 0.2 s each.
+  - The fiscal year end was inferred correctly for all three (Apple's 52/53-week September year,
+    Microsoft's June, JPMorgan's December).
+  - Revenue and net income matched published figures to the dollar for all seven company-years
+    checked (reference values written from memory, so a mismatch would have been investigated, not
+    trusted).
+  - The four quarters, with Q4 derived, added up to the reported year in 65 of 68 tests; the three
+    that did not are restatement-vintage cases (below).
+  - That run found and fixed: a quarter whose start date differed by a day between a filing and its
+    recast (a duplicate period); a bank's quarterly revenue concept missing from the list; a safety
+    rule that wrongly blocked deriving Q4 for a bank that reports one quantity under two concepts;
+    and an "alternate concept" flag that fired on filers that only ever use the second-choice
+    concept.
+- **A second, broader run** (19 US filers: Apple, Microsoft, JPMorgan, Wells Fargo, Citigroup,
+  Goldman Sachs, MetLife, Walmart, Costco, Amazon, NVIDIA, Alphabet, Exxon, Johnson & Johnson,
+  Caterpillar, Duke, Prologis, Coca-Cola, AT&T; and 20 Indian companies, 5 of them banks, with
+  about 600 consolidated filings) found and fixed: `latest` landing on an SEC cover-page date;
+  Amazon's trailing-twelve-month 10-Q figures counted as fiscal years; Costco's 52/53-week years
+  labelled a year late; MetLife and other non-banks receiving `bank.*` lines; Indian banks not
+  recognised as banks; `paid_up_equity_capital` stored as a flow; and one filing whose declared
+  reporting period had day and month swapped. After the fixes, revenue and net income matched
+  published figures for all nine companies checked (written from memory; one differs by a
+  minority-interest amount), every company loaded in about 1 s, and the quarters add up to the year
+  for FY2019 onwards except where a company restated (ITC and Hindustan Unilever after demergers;
+  HDFC Bank after its merger).
+- Identity checks still fail on some real statements for real reasons: regulatory deferral balances
+  (NTPC), redeemable minority interests and other temporary equity, minorities inside continuing
+  profit (Citigroup, AT&T), and utilities' deferred-tax presentation (Duke). They report; they
+  never correct.
+- The candidate-concept list uses standard `us-gaap` names and has now met nineteen real filers, but
+  not hundreds. Expect other filers to use concepts that are not in the list; those metrics are
+  simply absent (never guessed), and the list is meant to be extended.
+- **US banks.** Seven `bank.*` lines are mapped (interest income and expense, provisions, employee
+  cost, deposits, gross loans, and net loans where tagged), and only for a filer that reports both
+  `NoninterestExpense` and `Deposits`: insurers and industrials file `Deposits` and `InterestExpense`
+  too, where they do not mean what `bank.*` means. Interest income less interest expense
+  matched reported net interest income for every year checked on one large US bank (2010-2023). Not
+  mapped, so their ratios return None with a reason: non-performing assets (the US "nonaccrual" is a
+  different definition from the RBI's), CASA and interest-earning assets (not tagged), and "loans net
+  of allowance" (that bank's value exceeded its own gross loans, so it cannot be trusted). Loan to
+  deposit and credit cost therefore use gross loans, with a note; net interest margin uses total assets,
+  with a note. Only one bank has been checked.
+- **Restatement vintages.** The engine uses the latest-reported figure for each metric and period.
+  When a company recasts only some figures (Microsoft's ASC 606 recast changed 2016 annual revenue
+  and equity but not the 2016 quarters or total assets), a period can combine figures from
+  different filings, and the four quarters need not add up to the year. The accounting-identity
+  check (`engine.check()`) flags the balance-sheet cases; 6-8 periods per company were flagged in
+  the live run and every one examined was this effect. Three aids exist: every input in a result
+  carries `reported_at`; a result says so in `limitations` when inputs for one period were first
+  reported more than 120 days apart; and `engine.check_periods()` tests, per year, whether the
+  four quarters add up to the year. Point-in-time views (`as_of`) are the planned fix.
+- Debt lines use only the first available concept, never a sum, so a filer that reports several
+  overlapping debt concepts may show a partial figure.
+- Not covered yet: IFRS filers (`ifrs-full`), insurer concepts from the SEC, and the
+  period-end details of 4-4-5 retail calendars beyond what the 52/53-week handling covers.