calcfinc 0.1.0__py3-none-any.whl

calcfinc/__init__.py

@@ -0,0 +1,30 @@
+"""calcfinc: auditable financial metrics for any entity."""
+import logging
+
+from calcfinc.engine import CheckResult, EngineError, EngineResult, FactRef, FinancialEngine
+from calcfinc.entity import Entity
+from calcfinc.fact import (
+    Basis,
+    FinancialFact,
+    MappingConfidence,
+    Segment,
+    SegmentFact,
+    SharePrice,
+    Source,
+    StatementType,
+)
+from calcfinc.period import PeriodWindows
+from calcfinc.registry import RatioSpec, register_metric, register_ratio
+from calcfinc.store import SqliteRepositories
+
+__version__ = "0.1.0"
+
+# A library logs through the standard `logging` module and leaves the handlers to the application.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "Basis", "CheckResult", "Entity", "EngineError", "EngineResult", "FactRef", "FinancialEngine",
+    "FinancialFact", "MappingConfidence", "PeriodWindows", "RatioSpec", "Segment", "SegmentFact",
+    "SharePrice", "Source", "SqliteRepositories", "StatementType", "__version__", "register_metric",
+    "register_ratio",
+]

calcfinc/adapters/__init__.py

@@ -0,0 +1 @@
+"""Source adapters: each maps a source's tags and conventions to canonical facts."""

calcfinc/adapters/ind_as_xbrl/__init__.py

@@ -0,0 +1,29 @@
+"""Ind-AS (India) adapter.
+
+Reads exchange XBRL filings (a .xbrl file, raw fact rows, or canonical records) into
+calcfinc facts: April-March fiscal year, INR, exact Decimal values, review flags for records
+whose own arithmetic fails. Also holds the India-only vocabulary and the `india.*` ratios
+(`register()`), so the core stays free of country names.
+
+    from calcfinc.adapters import ind_as_xbrl
+    ind_as_xbrl.load_xbrl_file(repos, "results_consolidated.xbrl", entity="ACME")
+"""
+from calcfinc.adapters.ind_as_xbrl.canonical import consistency_issues, map_facts, parse_number
+from calcfinc.adapters.ind_as_xbrl.load import (
+    IndAsReport,
+    load_canonical,
+    load_canonical_file,
+    load_raw_facts,
+    load_xbrl_file,
+    load_xbrl_files,
+    read_canonical_json,
+    record_to_facts,
+)
+from calcfinc.adapters.ind_as_xbrl.vocab import RENAMES, register, shares_outstanding
+from calcfinc.adapters.ind_as_xbrl.xbrl import parse_xbrl_file
+
+__all__ = [
+    "IndAsReport", "RENAMES", "consistency_issues", "load_canonical", "load_canonical_file",
+    "load_raw_facts", "load_xbrl_file", "load_xbrl_files", "map_facts", "parse_number", "parse_xbrl_file",
+    "read_canonical_json", "record_to_facts", "register", "shares_outstanding",
+]

calcfinc/adapters/ind_as_xbrl/canonical.py

@@ -0,0 +1,171 @@
+"""Raw XBRL facts -> canonical records, with exact Decimal values.
+
+A *raw fact* is a dict as produced by `xbrl.parse_xbrl_file`: line_item_tag, value (text),
+context_id, period_start / period_end / instant, sign. A *canonical record* is one context's
+facts under the source-side canonical names (`tags.TAG_MAP`), plus its period.
+
+Only whole-company contexts are used (OneD, OneI, PY_D...), never segment or note breakdowns.
+Duration and instant contexts are kept as separate records; the engine merges a balance sheet
+into the duration record that ends on the same day.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable, Mapping
+from decimal import Decimal, InvalidOperation
+from typing import Any
+
+from calcfinc.adapters.ind_as_xbrl.tags import (
+    BANK_BALANCE_SHEET_AUX_TAGS,
+    BANK_EQUITY_AUX_TAGS,
+    DEBT_ALT_TAGS,
+    HIGH_SEVERITY,
+    SECTOR_ALT_TAGS,
+    SNAPSHOT_FIELDS,
+    TAG_MAP,
+    is_primary_context,
+)
+from calcfinc.num import HUNDRED, add, div, mul, sub
+
+_MISSING = {"", "-", "—", "NA", "N/A"}
+
+
+def parse_number(raw: object) -> Decimal | None:
+    """Parse a reported number exactly. Handles Indian formatting ('59,553.00'), accounting
+    negatives ('(1,234.5)'), a rupee sign and trailing footnote markers. Returns None for
+    anything that is not a number. A float (from JSON) is taken through its shortest text,
+    which is the original text for any figure of 17 significant digits or fewer."""
+    if raw is None or isinstance(raw, bool):
+        return None
+    if isinstance(raw, Decimal):
+        return raw if raw.is_finite() else None
+    if isinstance(raw, int):
+        return Decimal(raw)
+    s = repr(raw) if isinstance(raw, float) else str(raw).strip()
+    if s in _MISSING:
+        return None
+    negative = s.startswith("(") and s.endswith(")")
+    s = s.strip("()").replace(",", "").replace("₹", "").strip()
+    for candidate in (s, "".join(c for c in s if c.isdigit() or c in ".-")):
+        try:
+            value = Decimal(candidate)
+        except InvalidOperation:
+            continue
+        if value.is_finite():
+            return -value if negative else value
+    return None
+
+
+def _tag_index() -> tuple[dict[str, str], dict[str, str]]:
+    by_tag = {v: k for k, v in TAG_MAP.items()}
+    by_tag.update({v: k for k, v in BANK_EQUITY_AUX_TAGS.items()})
+    by_tag.update({v: k for k, v in BANK_BALANCE_SHEET_AUX_TAGS.items()})
+    by_tag.update(SECTOR_ALT_TAGS)
+    by_tag.update(DEBT_ALT_TAGS)
+    # Older Regulation 33 filings use the in-bse-fin: prefix with the same local concept name.
+    # An exact full-tag match always wins; the local name is only a fallback.
+    by_local: dict[str, str] = {}
+    for tag, name in by_tag.items():
+        by_local.setdefault(tag.split(":", 1)[1] if ":" in tag else tag, name)
+    return by_tag, by_local
+
+
+def map_facts(facts: Iterable[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    """Group raw facts into canonical records, newest first."""
+    by_tag, by_local = _tag_index()
+    fields: dict[str, dict[str, Decimal | None]] = defaultdict(dict)
+    periods: dict[str, dict[str, Any]] = {}
+
+    for fact in facts:
+        ctx = fact.get("context_id")
+        if not isinstance(ctx, str) or not is_primary_context(ctx):
+            continue
+        tag = fact.get("line_item_tag")
+        name = by_tag.get(tag or "")
+        if name is None and tag and ":" in tag:
+            name = by_local.get(tag.split(":", 1)[1])
+        if name is None:
+            continue                                   # not a field we track
+        value = parse_number(fact.get("value"))
+        if value is not None and fact.get("sign") == "-":
+            value = -value
+        fields[ctx][name] = value
+        periods[ctx] = {"context_id": ctx, "period_start": fact.get("period_start"),
+                        "period_end": fact.get("period_end"), "instant": fact.get("instant")}
+
+    records = []
+    for ctx, values in fields.items():
+        record: dict[str, Any] = {**periods[ctx], **values}
+        _derive_bank_lines(record)
+        records.append(record)
+    records.sort(key=lambda r: r.get("period_end") or r.get("instant") or "", reverse=True)
+    return records
+
+
+def _derive_bank_lines(record: dict[str, Any]) -> None:
+    """Banks report their equity, cash and liabilities as sub-lines. Build the totals only when
+    the total itself is absent and every needed part is present."""
+    capital = record.pop("_bank_capital", None)
+    reserves = record.pop("_bank_reserves_and_surplus", None)
+    if record.get("total_equity") is None and capital is not None and reserves is not None:
+        record["total_equity"] = add(capital, reserves)
+    cash_with_central_bank = record.pop("_bank_cash_with_rbi", None)
+    balances_with_banks = record.pop("_bank_balances_with_banks", None)
+    if (record.get("cash_and_equivalents") is None and cash_with_central_bank is not None
+            and balances_with_banks is not None):
+        record["cash_and_equivalents"] = add(cash_with_central_bank, balances_with_banks)
+    other = record.pop("_bank_other_liabilities_and_provisions", None)
+    if (record.get("total_liabilities") is None and other is not None
+            and record.get("deposits_debt") is not None and record.get("borrowings_noncurrent") is not None):
+        record["total_liabilities"] = add(add(record["deposits_debt"], record["borrowings_noncurrent"]), other)
+
+
+# Fields a filing reports as an exact 0 when it means "not applicable". Found in real filings:
+# a consolidated bank filing carries 0 for its whole NPA block; paid-up capital, face value and
+# CET1 are never genuinely 0; a coverage ratio of exactly 0 is a placeholder, not a result.
+NPA_BLOCK = ("gross_npa", "net_npa", "gross_npa_ratio", "net_npa_ratio")
+BANK_REGULATORY = (*NPA_BLOCK, "return_on_assets", "cet1_ratio", "additional_tier1_ratio")
+ZERO_IS_MISSING = ("paid_up_equity_capital", "face_value_per_share", "cet1_ratio",
+                   "debt_service_coverage_ratio_reported", "interest_service_coverage_ratio_reported")
+
+
+def drop_placeholder_zeros(record: Mapping[str, Any]) -> tuple[dict[str, Any], list[str]]:
+    """The record without the zeros that mean 'not reported', and the names removed. A genuine
+    zero (no exceptional items, no borrowings, no minority interest) is left alone."""
+    out = dict(record)
+    dropped: list[str] = []
+    npa = [record.get(k) for k in NPA_BLOCK]
+    if all(isinstance(v, Decimal) and v == 0 for v in npa):          # the whole block is zero together
+        dropped += [k for k in BANK_REGULATORY if isinstance(record.get(k), Decimal)]
+    dropped += [k for k in ZERO_IS_MISSING if isinstance(record.get(k), Decimal) and record[k] == 0
+                and k not in dropped]
+    for k in dropped:
+        out.pop(k, None)
+    return out, dropped
+
+
+def consistency_issues(records: Iterable[Mapping[str, Any]],
+                       tolerance: Decimal = Decimal(1)) -> list[dict[str, Any]]:
+    """Records that end on the same date but disagree on a balance-sheet / capital field, as a
+    filing sometimes does between its quarterly and cumulative contexts. Differences within
+    `tolerance` (rounding) are ignored."""
+    by_date: dict[str, list[Mapping[str, Any]]] = defaultdict(list)
+    for r in records:
+        key = r.get("period_end") or r.get("instant")
+        if key:
+            by_date[key].append(r)
+    issues: list[dict[str, Any]] = []
+    for date_key, group in by_date.items():
+        if len(group) < 2:
+            continue
+        for name in SNAPSHOT_FIELDS:
+            values: dict[Any, Decimal] = {r.get("context_id"): r[name] for r in group if r.get(name) is not None}
+            distinct = set(values.values())
+            if len(distinct) <= 1 or sub(max(distinct), min(distinct)) <= tolerance:
+                continue
+            nonzero = [v for v in distinct if v != 0]
+            smallest = min(nonzero, key=abs) if nonzero else Decimal(1)
+            pct = div(mul(sub(max(distinct), min(distinct)), HUNDRED), abs(smallest)).quantize(Decimal("0.01"))
+            issues.append({"period_end": date_key, "field": name, "values": values,
+                           "severity": "high" if name in HIGH_SEVERITY else "low", "magnitude_pct": pct})
+    return issues

calcfinc/adapters/ind_as_xbrl/load.py

@@ -0,0 +1,231 @@
+"""Canonical records -> facts in a store.
+
+Ind-AS reporting: an April-March fiscal year and INR by default. Values are exact Decimals; a
+record whose own arithmetic does not add up (assets vs liabilities + equity, income vs
+expenses...) still loads, but every fact from it carries a review reason so it can be routed
+to a person.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field, replace
+from datetime import UTC, date, datetime
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+from calcfinc.adapters.ind_as_xbrl.canonical import consistency_issues, drop_placeholder_zeros, map_facts
+from calcfinc.adapters.ind_as_xbrl.tags import META_KEYS, NAME_MAP
+from calcfinc.adapters.ind_as_xbrl.vocab import register
+from calcfinc.adapters.ind_as_xbrl.xbrl import parse_xbrl_file
+from calcfinc.engine.check import check_values
+from calcfinc.entity import Entity
+from calcfinc.fact import Basis, FinancialFact, MappingConfidence, Source
+from calcfinc.num import div
+from calcfinc.period import DEFAULT_WINDOWS, PeriodWindows, ResolvedPeriod, classify_range, fiscal_year
+from calcfinc.registry import metrics
+
+_FILENAME = re.compile(r"^(?P<symbol>.+)_(?P<basis>consolidated|standalone)_(?P<period>.+)_canonical\.json$")
+_XBRL_BASIS = re.compile(r"consolidated|standalone", re.I)
+
+
+@dataclass(frozen=True, slots=True)
+class IndAsReport:
+    entity: str
+    records: int
+    facts: int
+    needs_review: tuple[str, ...] = ()            # period labels of records whose arithmetic failed
+    skipped: tuple[str, ...] = ()                 # facts that could not be placed in a period
+    consistency: tuple[dict[str, Any], ...] = field(default=())   # contexts that disagree on a balance
+    conflicts: tuple[str, ...] = ()               # figures two contexts reported differently; one was used
+
+
+_ORDER = {"One": 0, "Two": 1, "Three": 2, "Four": 3, "Five": 4, "Six": 5}
+_CONTEXT_START = re.compile(r"(One|Two|Three|Four|Five|Six)")
+
+
+def _rank(context_id: Any, fact: FinancialFact) -> tuple[int, str]:
+    """How much to trust the context a fact came from: OneD / OneI describe the current period,
+    TwoD... earlier ones, PY_ the prior year. A balance comes from the instant half of a merged
+    id ('FourD+OneI'), a flow or a derived figure from the duration half."""
+    parts = str(context_id or "").split("+")
+    from_instant = fact.is_point_in_time and fact.mapping_confidence is MappingConfidence.EXACT
+    part = parts[-1] if from_instant else parts[0]
+    m = _CONTEXT_START.match(part)
+    return (_ORDER[m.group(1)] if m else 9 if part.startswith("PY_") else 8), part
+
+
+def _resolve_conflicts(items: list[tuple[int, str, FinancialFact]]) -> tuple[list[FinancialFact], list[str]]:
+    """Two contexts of one filing can claim the same figure for the same period with different
+    values (a cumulative context given the quarter's dates, a stale prior-year capital). The most
+    current context wins, the winner is flagged, and the disagreement is reported; the store
+    never gets to pick silently by load order."""
+    groups: dict[tuple[Any, ...], list[tuple[int, str, FinancialFact]]] = {}
+    for item in items:
+        f = item[2]
+        groups.setdefault((f.metric, f.basis, f.period_start, f.period_end), []).append(item)
+    kept: list[FinancialFact] = []
+    notes: list[str] = []
+    for candidates in groups.values():
+        if len({c[2].value for c in candidates}) == 1:
+            kept.append(candidates[0][2])
+            continue
+        candidates.sort(key=lambda c: c[0])
+        _, winner_ctx, winner = candidates[0]
+        others = "; ".join(f"{ctx} reports {f.value}" for _, ctx, f in candidates[1:] if f.value != winner.value)
+        why = f"contexts disagree on this figure ({others}); {winner_ctx} used"
+        kept.append(replace(winner, mapping_reason=f"{winner.mapping_reason}; {why}" if winner.mapping_reason else why))
+        notes.append(f"{winner.metric} {winner.period_end}: {winner_ctx} = {winner.value} used; {others}")
+    return kept, notes
+
+
+def _date(v: Any) -> date | None:
+    if isinstance(v, date):
+        return v
+    return date.fromisoformat(str(v)[:10]) if v else None
+
+
+def record_to_facts(record: Mapping[str, Any], *, entity_id: int, basis: Basis | str = "consolidated",
+                    currency: str = "INR", fiscal_year_end_month: int = 3,
+                    windows: PeriodWindows = DEFAULT_WINDOWS, source_id: int | None = None,
+                    reported_at: date | None = None,
+                    placeholder_zeros: bool = True) -> tuple[list[FinancialFact], list[str]]:
+    """Facts for one canonical record, and notes for any value that could not be placed or that
+    was dropped. With `placeholder_zeros` (the default), figures the filing reports as an exact 0
+    to mean 'not applicable' are treated as not reported (see `canonical.drop_placeholder_zeros`)."""
+    register()
+    notes: list[str] = []
+    if placeholder_zeros:
+        record, dropped = drop_placeholder_zeros(record)
+        if dropped:
+            notes.append(f"context {record.get('context_id')}: exactly 0, treated as not reported: "
+                         + ", ".join(dropped))
+    start, end = _date(record.get("period_start")), _date(record.get("period_end") or record.get("instant"))
+    values = {NAME_MAP.get(k, k): v for k, v in record.items()
+              if k not in META_KEYS and not k.startswith("_") and isinstance(v, Decimal)}
+    if end is None or not values:
+        return [], notes + [f"context {record.get('context_id')}: no period or no values"]
+    failed = check_values(values)
+    review = ("source record failed arithmetic checks: " + ", ".join(k for k, ok in failed.items() if not ok)
+              if not all(failed.values()) else None)
+    fye = fiscal_year_end_month
+    duration = classify_range(start, end, fye, windows) if start is not None else None
+    instant = ResolvedPeriod(None, end, fiscal_year(end, fye), None, False)
+
+    facts: list[FinancialFact] = []
+    for name, value in values.items():
+        spec = metrics.get(name)
+        if spec is None:
+            continue
+        pit = spec.is_point_in_time
+        period = instant if pit else duration
+        if period is None:
+            notes.append(f"{name} ({record.get('context_id')}): a flow figure with no start date, not loaded")
+            continue
+        facts.append(FinancialFact(
+            entity_id=entity_id, metric=name, value=value, statement_type=spec.statement_type,
+            basis=Basis(basis), currency=currency if spec.kind in metrics.CURRENCY_KINDS else None,
+            period_start=None if pit else period.start, period_end=period.end,
+            financial_year=period.financial_year, quarter=None if pit else period.quarter,
+            is_annual=period.is_annual and not pit, is_point_in_time=pit, reported_at=reported_at,
+            source_id=source_id, mapping_confidence=MappingConfidence.EXACT, mapping_reason=review))
+    paid_up, face = values.get("paid_up_equity_capital"), values.get("face_value_per_share")
+    if paid_up is not None and face:
+        facts.append(FinancialFact(
+            entity_id=entity_id, metric="shares_outstanding", value=div(paid_up, face),
+            statement_type=metrics.BS, basis=Basis(basis), period_end=end,
+            financial_year=instant.financial_year, is_point_in_time=True, reported_at=reported_at,
+            source_id=source_id, mapping_confidence=MappingConfidence.DERIVED,
+            mapping_reason=review or "derived: paid-up equity capital / face value per share"))
+    return facts, notes
+
+
+def load_canonical(repos: Any, records: Iterable[Mapping[str, Any]], *, entity: str,
+                   basis: Basis | str = "consolidated", currency: str = "INR",
+                   fiscal_year_end_month: int = 3, windows: PeriodWindows = DEFAULT_WINDOWS,
+                   reported_at: date | None = None, source: Source | None = None,
+                   placeholder_zeros: bool = True) -> IndAsReport:
+    """Load canonical records for one entity and basis. An existing entity keeps its own
+    currency and fiscal year end; a new one is created with the arguments given."""
+    register()
+    records = list(records)
+    ent = repos.entities.resolve(entity)
+    fye = ent.fiscal_year_end_month if ent else fiscal_year_end_month
+    try:
+        if ent is None:
+            ent = repos.entities.upsert(Entity(name=entity, currency=currency, fiscal_year_end_month=fye))
+        source_id = repos.sources.add(source).source_id if source is not None else None
+        items: list[tuple[int, str, FinancialFact]] = []
+        skipped: list[str] = []
+        review: list[str] = []
+        for record in records:
+            facts, notes = record_to_facts(record, entity_id=int(ent.id or 0), basis=basis, currency=currency,
+                                           fiscal_year_end_month=fye, windows=windows, source_id=source_id,
+                                           reported_at=reported_at, placeholder_zeros=placeholder_zeros)
+            skipped += notes
+            if any(f.mapping_reason and f.mapping_reason.startswith("source record failed") for f in facts):
+                review.append(str(record.get("period_end") or record.get("instant")))
+            items += [(*_rank(record.get("context_id"), f), f) for f in facts]
+        all_facts, conflicts = _resolve_conflicts(items)
+        repos.facts.add_many(all_facts)
+        repos.commit()
+    except Exception:
+        repos.rollback()
+        raise
+    return IndAsReport(entity=ent.name, records=len(records), facts=len(all_facts), needs_review=tuple(review),
+                       skipped=tuple(skipped), consistency=tuple(consistency_issues(records)),
+                       conflicts=tuple(conflicts))
+
+
+def load_raw_facts(repos: Any, facts: Iterable[Mapping[str, Any]], **kwargs: Any) -> IndAsReport:
+    """Raw XBRL fact rows (see `xbrl.parse_xbrl_file`) -> canonical records -> store."""
+    return load_canonical(repos, map_facts(facts), **kwargs)
+
+
+def load_xbrl_file(repos: Any, path: str | Path, *, entity: str, basis: Basis | str | None = None,
+                   **kwargs: Any) -> IndAsReport:
+    """Load one .xbrl filing. The basis is read from the file name (it must say consolidated or
+    standalone) unless you pass it."""
+    p = Path(path)
+    if basis is None:
+        m = _XBRL_BASIS.search(p.stem)
+        if m is None:
+            raise ValueError(f"{p.name}: cannot tell consolidated from standalone; pass basis=")
+        basis = m.group(0).lower()
+    source = Source(kind="xbrl", document_title=p.name, uri=str(p.resolve()),
+                    content_hash=hashlib.sha256(p.read_bytes()).hexdigest(),
+                    retrieved_at=datetime.now(UTC))
+    return load_raw_facts(repos, parse_xbrl_file(p, entity), entity=entity, basis=basis, source=source, **kwargs)
+
+
+def load_xbrl_files(repos: Any, paths: Iterable[str | Path], *, entity: str, **kwargs: Any) -> list[IndAsReport]:
+    """Load several filings, each "Revision" after the "Original" it corrects, whatever order they
+    are given in. The filing carries no date, so with no `reported_at` a later load overwrites an
+    earlier one for the same period, and a revision must therefore come last."""
+    ordered = sorted((Path(p) for p in paths), key=lambda p: ("revision" in p.stem.lower(), p.name))
+    return [load_xbrl_file(repos, p, entity=entity, **kwargs) for p in ordered]
+
+
+def read_canonical_json(path: str | Path) -> list[dict[str, Any]]:
+    """Canonical JSON with numbers read as exact Decimals (never through float)."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"), parse_float=Decimal, parse_int=Decimal)
+    return [data] if isinstance(data, dict) else list(data)
+
+
+def load_canonical_file(repos: Any, path: str | Path, *, entity: str | None = None,
+                        basis: Basis | str | None = None, **kwargs: Any) -> IndAsReport:
+    """Load a `<SYMBOL>_<consolidated|standalone>_<period>_canonical.json` file. The entity and
+    basis default to what the file name says."""
+    p = Path(path)
+    m = _FILENAME.match(p.name)
+    if m is None and (entity is None or basis is None):
+        raise ValueError(f"{p.name}: not a <SYMBOL>_<basis>_<period>_canonical.json name; "
+                         "pass entity= and basis=")
+    source = Source(kind="xbrl", document_title=p.name, uri=str(p.resolve()),
+                    content_hash=hashlib.sha256(p.read_bytes()).hexdigest(),
+                    retrieved_at=datetime.now(UTC), period_label=m["period"] if m else None)
+    return load_canonical(repos, read_canonical_json(p), entity=entity or m["symbol"],  # type: ignore[index]
+                          basis=basis or m["basis"], source=source, **kwargs)  # type: ignore[index]

calcfinc/adapters/ind_as_xbrl/tags.py

@@ -0,0 +1,144 @@
+"""Ind-AS XBRL tag map: exchange taxonomy concepts -> canonical names.
+
+Ported from the author's earlier extraction code. The names on the left are the *source-side*
+canonical names that code used; `NAME_MAP` renames the few that differ from calcfinc's
+vocabulary. Concepts live under the `in-capmkt:` taxonomy; older Regulation 33 filings use
+`in-bse-fin:` with the same local names, so `map_facts` falls back to the local name.
+"""
+from __future__ import annotations
+
+import re
+
+TAG_MAP: dict[str, str] = {
+    # P&L
+    "revenue": "in-capmkt:RevenueFromOperations",
+    "other_income": "in-capmkt:OtherIncome",
+    "total_income": "in-capmkt:Income",
+    "employee_expense": "in-capmkt:EmployeeBenefitExpense",
+    "depreciation": "in-capmkt:DepreciationDepletionAndAmortisationExpense",
+    "other_expenses": "in-capmkt:OtherExpenses",
+    "finance_costs": "in-capmkt:FinanceCosts",
+    "total_expenses": "in-capmkt:Expenses",
+    "pbt_before_exceptional": "in-capmkt:ProfitBeforeExceptionalItemsAndTax",
+    "exceptional_items": "in-capmkt:ExceptionalItemsBeforeTax",
+    "pbt": "in-capmkt:ProfitBeforeTax",
+    "current_tax": "in-capmkt:CurrentTax",
+    "deferred_tax": "in-capmkt:DeferredTax",
+    "tax_expense": "in-capmkt:TaxExpense",
+    "pat_continuing_ops": "in-capmkt:ProfitLossForPeriodFromContinuingOperations",
+    "net_profit": "in-capmkt:ProfitLossForPeriod",
+    "oci": "in-capmkt:OtherComprehensiveIncomeNetOfTaxes",
+    "total_comprehensive_income": "in-capmkt:ComprehensiveIncomeForThePeriod",
+    "net_profit_owners": "in-capmkt:ProfitOrLossAttributableToOwnersOfParent",
+    "net_profit_nci": "in-capmkt:ProfitOrLossAttributableToNonControllingInterests",
+    "eps_basic": "in-capmkt:BasicEarningsLossPerShareFromContinuingAndDiscontinuedOperations",
+    "eps_diluted": "in-capmkt:DilutedEarningsLossPerShareFromContinuingAndDiscontinuedOperations",
+    # equity / capital and the ratios SEBI makes issuers report
+    "paid_up_equity_capital": "in-capmkt:PaidUpValueOfEquityShareCapital",
+    "face_value_per_share": "in-capmkt:FaceValueOfEquityShareCapital",
+    "debt_equity_ratio_reported": "in-capmkt:DebtEquityRatio",
+    "debt_service_coverage_ratio_reported": "in-capmkt:DebtServiceCoverageRatio",
+    "interest_service_coverage_ratio_reported": "in-capmkt:InterestServiceCoverageRatio",
+    # balance sheet
+    "total_assets": "in-capmkt:Assets",
+    "total_liabilities": "in-capmkt:Liabilities",
+    "total_equity": "in-capmkt:Equity",
+    "current_assets": "in-capmkt:CurrentAssets",
+    "noncurrent_assets": "in-capmkt:NoncurrentAssets",
+    "current_liabilities": "in-capmkt:CurrentLiabilities",
+    "noncurrent_liabilities": "in-capmkt:NoncurrentLiabilities",
+    "borrowings_current": "in-capmkt:BorrowingsCurrent",
+    "borrowings_noncurrent": "in-capmkt:BorrowingsNoncurrent",
+    "cash_and_equivalents": "in-capmkt:CashAndCashEquivalents",
+    # cash flow
+    "operating_cash_flow": "in-capmkt:CashFlowsFromUsedInOperatingActivities",
+    "investing_cash_flow": "in-capmkt:CashFlowsFromUsedInInvestingActivities",
+    "financing_cash_flow": "in-capmkt:CashFlowsFromUsedInFinancingActivities",
+    "dividends": "in-capmkt:DividendsPaidClassifiedAsFinancingActivities",
+    "capex_ppe": "in-capmkt:PurchaseOfPropertyPlantAndEquipmentClassifiedAsInvestingActivities",
+    "capex_intangibles": "in-capmkt:PurchaseOfIntangibleAssetsClassifiedAsInvestingActivities",
+    # insurers (life insurers file net premium income; it marks the filer as an insurer)
+    "insurance_net_premium": "in-capmkt:NetPremiumIncome",
+    # banks
+    "bank_interest_earned": "in-capmkt:InterestEarned",
+    "bank_interest_expended": "in-capmkt:InterestExpended",
+    "bank_operating_profit": "in-capmkt:OperatingProfitBeforeProvisionAndContingencies",
+    "bank_provisions": "in-capmkt:ProvisionsOtherThanTaxAndContingencies",
+    "bank_employee_cost": "in-capmkt:EmployeesCost",
+    "bank_other_operating_expenses": "in-capmkt:OtherOperatingExpenses",
+    "advances": "in-capmkt:Advances",
+    # Bank capital adequacy and asset quality are reported at the bank entity (standalone)
+    # level only; consolidated filings carry zeros.
+    "cet1_ratio": "in-capmkt:CET1Ratio",
+    "additional_tier1_ratio": "in-capmkt:AdditionalTier1Ratio",
+    "gross_npa": "in-capmkt:GrossNonPerformingAssets",
+    # `NonPerformingAssets` is the NET figure (confirmed against a bank's own NPA ratios).
+    "net_npa": "in-capmkt:NonPerformingAssets",
+    "gross_npa_ratio": "in-capmkt:PercentageOfGrossNpa",
+    "net_npa_ratio": "in-capmkt:PercentageOfNpa",
+    # Filers tag this with a currency unit although it is a plain ratio; the unit is taken
+    # from the metric registry, not from the raw tag, so the mistake is harmless.
+    "return_on_assets": "in-capmkt:ReturnOnAssets",
+}
+
+BANK_EQUITY_AUX_TAGS = {
+    "_bank_capital": "in-capmkt:Capital",
+    "_bank_reserves_and_surplus": "in-capmkt:ReservesAndSurplus",
+}
+BANK_BALANCE_SHEET_AUX_TAGS = {
+    "_bank_cash_with_rbi": "in-capmkt:CashAndBalancesWithReserveBankOfIndia",
+    "_bank_balances_with_banks": "in-capmkt:BalancesWithBanksAndMoneyAtCallAndShortNotice",
+    "_bank_other_liabilities_and_provisions": "in-capmkt:OtherLiabilitiesAndProvisions",
+}
+SECTOR_ALT_TAGS = {
+    "in-capmkt:ShareholdersFunds": "total_equity",
+    "in-capmkt:ProfitLossForThePeriod": "net_profit",
+    "in-capmkt:ProfitLossAfterTaxAndExtraordinaryItems": "net_profit",
+    "in-capmkt:ProfitLossFromOrdinaryActivitiesBeforeTax": "pbt",
+}
+DEBT_ALT_TAGS = {
+    "in-capmkt:Borrowings": "borrowings_noncurrent",
+    "in-capmkt:LongTermBorrowings": "borrowings_noncurrent",
+    "in-capmkt:ShortTermBorrowings": "borrowings_current",
+    "in-capmkt:DebtSecurities": "debt_securities",
+    "in-capmkt:Deposits": "deposits_debt",
+}
+
+# Source-side canonical name -> calcfinc metric name (names not listed are unchanged).
+NAME_MAP = {
+    "pat_continuing_ops": "profit_continuing_ops",
+    "insurance_net_premium": "insurance.net_earned_premium",
+    "bank_interest_earned": "bank.interest_earned",
+    "bank_interest_expended": "bank.interest_expended",
+    "bank_operating_profit": "bank.operating_profit",
+    "bank_provisions": "bank.provisions",
+    "bank_employee_cost": "bank.employee_cost",
+    "bank_other_operating_expenses": "bank.other_operating_expenses",
+    "advances": "bank.advances",
+    "cet1_ratio": "bank.cet1_ratio",
+    "additional_tier1_ratio": "bank.additional_tier1_ratio",
+    "gross_npa": "bank.gross_npa",
+    "net_npa": "bank.net_npa",
+    "gross_npa_ratio": "bank.gross_npa_ratio",
+    "net_npa_ratio": "bank.net_npa_ratio",
+    "return_on_assets": "india.return_on_assets_reported",
+}
+
+# The primary whole-company contexts: OneD / OneI, TwoD ..., and PY_D / PY_I for the prior
+# year. Segment and note-breakdown contexts (OneReportable1D, OneExpenses2D...) are rejected.
+PRIMARY_CONTEXT = re.compile(r"^(One|Two|Three|Four|Five|Six)[DI]$|^PY_[DI]$")
+
+# Fields compared across contexts that share a date, to catch a filing that disagrees with itself.
+SNAPSHOT_FIELDS = (
+    "total_assets", "total_liabilities", "total_equity", "current_assets", "noncurrent_assets",
+    "current_liabilities", "noncurrent_liabilities", "borrowings_current", "borrowings_noncurrent",
+    "debt_securities", "deposits_debt", "cash_and_equivalents", "paid_up_equity_capital",
+    "face_value_per_share",
+)
+HIGH_SEVERITY = frozenset({"paid_up_equity_capital", "face_value_per_share", "total_assets", "total_equity"})
+
+META_KEYS = frozenset({"context_id", "period_start", "period_end", "instant"})
+
+
+def is_primary_context(context_id: str | None) -> bool:
+    return bool(PRIMARY_CONTEXT.match(context_id or ""))