disaster-fund-calculation-engine 0.1.0__py3-none-any.whl

disaster_fund_calculation_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: disaster-fund-calculation-engine
+Version: 0.1.0
+Summary: Disaster Reconstruction & Relief Fund Calculation Engine: Multi-Tranche Liabilities, Donation Offsets, and District Pooling
+Author-email: Pujan Pandey <arghakhanchipujan@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/arghakhanchipujan/Fund-Management
+Keywords: disaster-relief,fund-management,reconstruction,nepal,grants,calculation-engine,tranches
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: disaster-fund-plan>=0.1.0
+Requires-Dist: pydantic>=2
+
+# disaster-fund-calculation-engine
+
+**Turn a validated disaster plan plus beneficiary counts into exact rupee figures: what a household receives, what each government owes, and what each district collects and forwards.**
+
+It is the calculation half of the system. The plan itself (structure, grant rates, liability split) comes from [`disaster-fund-plan`](https://pypi.org/project/disaster-fund-plan/), which is installed automatically.
+
+- Python 3.10 or newer
+- Dependencies: `disaster-fund-plan`, `pydantic>=2`
+- Import name: `fm_calculation_engine` (the PyPI name is `disaster-fund-calculation-engine`)
+
+```bash
+pip install disaster-fund-calculation-engine
+```
+
+---
+
+## The three outputs at a glance
+
+| Question you are asking | Function | Who asks it |
+| --- | --- | --- |
+| *"What does one household receive, tranche by tranche?"* | `receivable_amounts(plan, profile)` | Caseworker, beneficiary-facing app |
+| *"How much does the Federal / a Province / a Local government owe, after donations?"* | `calculate_government_liability(plan, profile, counts)` | Finance office of that government |
+| *"How much must a district collect from each level, and how much does it forward to each local government?"* | `calculate_district_fund(plan, profile, counts)` | District coordination office |
+
+All three read the **same** internal schedule, so they can never disagree with each other (see [Guarantees](#guarantees)).
+
+## Inputs
+
+**1. The plan**: loaded with `disaster-fund-plan`:
+
+```python
+from fm_plan import load_plan
+plan = load_plan("example_plan.json")
+```
+
+**2. Beneficiary counts** (outputs 2 and 3): how many households fall in each category. A list of dictionaries:
+
+```python
+counts = [
+    {"district": "Gorkha",        "local_level": "Gorkha Municipality",
+     "disaster_type": "Earthquake", "solution_type": "Reconstruction", "count": 10},
+    {"district": "Sindhupalchok", "local_level": "Melamchi Municipality",
+     "disaster_type": "Earthquake", "solution_type": "Reconstruction", "count": 20},
+    {"district": "Sindhupalchok", "local_level": "Helambu Rural Municipality",
+     "disaster_type": "Earthquake", "solution_type": "Retrofitting",   "count": 5},
+]
+```
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `district` | yes | Name **or code** (`"Sindhupalchok"` or `"23"`) |
+| `disaster_type`, `solution_type` | yes | Must exist in the plan; capital letters do not matter |
+| `count` | yes | Number of households, `0` or more |
+| `local_level` | no | Name or code. If omitted, see [use case 6](#6-counts-without-a-local-level) |
+| `region` | no | Taken from the plan's district. If you supply it, it must match the plan |
+| `district_code`, `local_level_code` | no | Optional cross-check (non-empty strings). If given, they must match the plan's code for that district / local level, otherwise the row is rejected (a local-level code needs a `local_level`) |
+
+**3. A profile** for the question you are asking (shown in each use case below). Every profile carries the `plan_id`, which must match the loaded plan: this stops results being calculated against the wrong plan version.
+
+---
+
+## Use cases
+
+### 1. What does one household receive?
+
+Given a household's region, disaster type and solution type, get its tranche schedule.
+
+```python
+from fm_calculation_engine import receivable_amounts
+
+out = receivable_amounts(plan, {
+    "plan_id": plan.plan_id,
+    "region": "Pahad",
+    "disaster_type": "Earthquake",
+    "solution_type": "Reconstruction",
+})
+
+print(out.total)                       # 300000
+for t in out.tranches:
+    print(t.tranche, t.stage, t.amount)
+# 1 shelter 15000
+# 2 shelter 15000
+# 3 main 100000
+# 4 main 100000
+# 5 main 70000
+```
+
+### 2. What does a government owe? (Federal, Province or Local)
+
+The same function works for every level. The engine works out which level you mean from the name or code.
+
+```python
+from fm_calculation_engine import calculate_government_liability
+
+fed = calculate_government_liability(
+    plan,
+    {"plan_id": plan.plan_id, "gov_entity_name": "Government of Nepal"},   # or "FED"
+    counts,
+)
+print(fed.gov_type, fed.liability_percentage)   # federal 50.0
+print(fed.total_gross_liability)                # 4750000
+print(fed.total_net_payable)                    # 4750000 (no donations given)
+```
+
+Other levels, using the plan from the example file:
+
+| `gov_entity_name` | Resolves to | Pays |
+| --- | --- | --- |
+| `"Government of Nepal"` or `"FED"` | federal | 50% of every district's cost |
+| `"Gandaki Province"` or `"P4"` | province | 30%, **only** for districts inside that province (Gorkha) |
+| `"Melamchi Municipality"` or `"23001"` | local | 20% of its district's cost, split between the district's local levels in proportion to what each needs |
+
+Each result has a per-tranche, per-district breakdown (`fed.tranches[i].districts`) and a summary of who the beneficiaries are (`fed.beneficiary_summary`).
+
+### 3. Apply donations, with automatic rollover
+
+INGO, NGO and other donors give money to a government. It reduces that government's **cash outflow**, starting at tranche 1; whatever is not used rolls over to the next tranche.
+
+```python
+fed = calculate_government_liability(
+    plan,
+    {
+        "plan_id": plan.plan_id,
+        "gov_entity_name": "Government of Nepal",
+        "donations": [
+            {"donor_name": "Red Cross", "amount": 250000, "received_date": "2015-10-01"},
+            {"donor_name": "UNICEF",    "amount": 150000, "received_date": "2015-10-05"},
+        ],
+    },
+    counts,
+)
+for t in fed.tranches[:3]:
+    print(t.tranche, t.gross_liability, t.donation_applied, t.net_payable, t.remaining_donation)
+```
+
+```text
+tranche  gross      donation applied  net payable  donation left
+1        350,000    350,000           0            50,000      ← 400,000 donated, tranche 1 consumes 350,000
+2        350,000     50,000           300,000      0           ← the 50,000 left over rolls into tranche 2
+3        1,500,000         0          1,500,000    0           ← donations are used up
+```
+
+Totals: Rs. 400,000 received, Rs. 4,750,000 gross, **Rs. 4,350,000 net cash payable**. The relief inside each tranche is shared across districts in proportion to what each district needs (`tranches[i].districts[j].donation_offset`).
+
+Notes: `received_date` is optional and only affects the order donations are listed (oldest first). It does not decide *which tranche* a donation can pay for, because the plan has no tranche due dates.
+
+### 4. What must a district collect, and whom does it forward to?
+
+A district office needs two answers per tranche: how much to **collect** from Federal, Province and Local, and how much to **forward** to each local government.
+
+```python
+from fm_calculation_engine import calculate_district_fund
+
+d = calculate_district_fund(
+    plan,
+    {"plan_id": plan.plan_id, "district_name": "Sindhupalchok"},   # or "23"
+    counts,
+)
+print(d.province_name, d.total_beneficiaries, d.grand_total)   # Bagmati Province 25 6500000
+
+t1 = d.tranches[0]
+print(t1.collectible)    # federal=275000 province=165000 local=110000 total=550000
+for x in t1.disbursements:
+    print(x.local_gov, x.amount)
+# Melamchi Municipality 300000
+# Helambu Rural Municipality 250000
+```
+
+Tranche 1 here is 550,000 in total: Rs. 275,000 (50%) from Federal, Rs. 165,000 (30%) from the Province and Rs. 110,000 (20%) from Local, which is then forwarded as 300,000 and 250,000 to the two local governments according to their own beneficiaries.
+
+### 5. Reconcile everything (audit and sanity check)
+
+Because all outputs come from one schedule, they must add up. This is a useful check for auditors and for your own integration tests:
+
+```python
+levels = ["FED", "P3", "P4", "Gorkha Municipality", "Melamchi Municipality", "Helambu Rural Municipality"]
+total_by_government = sum(
+    calculate_government_liability(plan, {"plan_id": plan.plan_id, "gov_entity_name": g}, counts).total_gross_liability
+    for g in levels
+)
+total_by_district = sum(
+    calculate_district_fund(plan, {"plan_id": plan.plan_id, "district_name": d}, counts).grand_total
+    for d in ("Gorkha", "Sindhupalchok")
+)
+assert total_by_government == total_by_district == 9_500_000
+```
+
+### 6. Counts without a local level
+
+Sometimes only district-level totals are known. Leave `local_level` out:
+
+```python
+calculate_district_fund(plan, {"plan_id": plan.plan_id, "district_name": "23"},
+    [{"district": "23", "disaster_type": "Earthquake", "solution_type": "Reconstruction", "count": 10}])
+# tranche 1 -> Melamchi Municipality 75000, Helambu Rural Municipality 75000
+```
+
+The money for such households is shared **equally** between the district's local levels (odd rupees go to the first ones in the plan). For a local government's own report, these households are shown separately as `unassigned_beneficiaries` and are not included in `total_beneficiaries`.
+
+### 7. Catch bad input with readable errors
+
+Every problem in the input is reported at once, in plain words, as an `EngineInputError`:
+
+```python
+from fm_calculation_engine import EngineInputError
+
+try:
+    calculate_district_fund(plan, {"plan_id": plan.plan_id, "district_name": "Gorkha"}, bad_counts)
+except EngineInputError as error:
+    print(error)
+```
+
+```text
+3 problem(s) in beneficiary counts:
+  - item 0: district 'Kathmandu' is not in plan's districts ['Gorkha', 'Sindhupalchok']
+  - item 0: disaster_type 'Flood' is not in plan's disaster types ['Earthquake']
+  - item 1: region 'Terai' does not match district 'Gorkha', which is in region 'Pahad' in this plan
+```
+
+You can also validate a count list on its own, before calculating, and get it back normalised to the plan's spelling and codes:
+
+```python
+from fm_calculation_engine import validate_beneficiary_counts
+clean = validate_beneficiary_counts(plan, counts)
+```
+
+### 8. A local government whose name exists in two districts
+
+Nepal has repeated municipality names. If a local government's name appears in more than one district, the engine refuses to guess; say which district you mean:
+
+```python
+calculate_government_liability(plan, {
+    "plan_id": plan.plan_id,
+    "gov_entity_name": "Some Municipality",
+    "district": "Sindhupalchok",
+}, counts)
+```
+
+(`district` is only accepted for local governments. Using the official code, such as `"23001"`, avoids the ambiguity altogether.)
+
+---
+
+## Guarantees
+
+- **Exact rupees, no drift.** Every split (liability shares, local-level shares, donation offsets) uses the *largest remainder method* on whole rupees: each part gets what it is owed, and leftover rupees go to the parts with the largest fractions. The parts always add up to the total; `round()` and floating point are never used for money.
+- **One schedule per district.** District total = Federal + Province + Local share, and the local share = the sum of the shares given to its local levels, exactly. Outputs 2 and 3 therefore always reconcile.
+- **Deterministic.** The same input always gives the same output (ties are broken by plan order).
+- **Wrong plan is rejected.** A `plan_id` that does not match the loaded plan is an error.
+- **Names or codes everywhere.** Districts, provinces, local levels and the Federal government can all be given by name or official code, in any capitalisation.
+
+## API summary
+
+| Name | Purpose |
+| --- | --- |
+| `receivable_amounts(plan, profile)` → `ReceivableAmounts` | Output 1: tranche schedule for one household |
+| `calculate_government_liability(plan, profile, counts)` → `GovernmentLiabilityOutput` | Output 2: what a government owes, with donation offsets and rollover |
+| `calculate_district_fund(plan, profile, counts)` → `DistrictOutput` | Output 3: what a district collects and forwards |
+| `validate_beneficiary_counts(plan, counts)` | Check counts against the plan; returns normalised `BeneficiaryCount` objects |
+| `EngineInputError` | Raised for any invalid input; the message lists every problem |
+| `BeneficiaryProfile`, `GovEntityProfile`, `DistrictProfile`, `BeneficiaryCount`, `Donation` | Input models (a plain `dict` with the same keys works too) |
+
+Profiles and counts can be passed as dictionaries or as these model objects. Unknown keys are rejected, so a typo is an error rather than being silently ignored.
+
+## Limits
+
+- Amounts are whole rupees.
+- The Federal/Province/Local split is the same for every tranche and every stage (shelter and main).
+- Donations are pooled per government and used from tranche 1 onward; they are not tied to a particular tranche or district.
+- A tranche round exists up to the longest grant in the plan. A grant with fewer tranches simply has Rs. 0 in the later rounds.
+
+## License
+
+MIT

disaster_fund_calculation_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fm_calculation_engine/__init__.py,sha256=ObTeAsx8O9bAublsgOiC2k2MlEf3HMCJ2wVG4KEVYSg,1238
+fm_calculation_engine/beneficiary.py,sha256=Tv1_FQLObfNskuyz1pIeIi5pBqP_pPvBZ4gTgwDS8gg,2585
+fm_calculation_engine/common.py,sha256=ggC6WxXciO7tNteDgRkjPcGAqfgs1_mojJLeKDOdcJ4,7685
+fm_calculation_engine/core.py,sha256=6_VF_R8A82M3gX-tRCsGuB3btMUbBwf0pA9HPn46IBI,6765
+fm_calculation_engine/district.py,sha256=L2_QYtaVYmtdkPwnjW197ab5wFWg1fhFx4Jx5UxUh64,3661
+fm_calculation_engine/government.py,sha256=cJtplOnqSxHVrdkdZNDzDH73ObOJUzirUD2RGN5Jrbo,11323
+fm_calculation_engine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+disaster_fund_calculation_engine-0.1.0.dist-info/METADATA,sha256=RAhgoRC5KWHpbpPshGL3MUaQLwSg0hfdHUG4Upud6Uw,14052
+disaster_fund_calculation_engine-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+disaster_fund_calculation_engine-0.1.0.dist-info/top_level.txt,sha256=y6f0oj8S941rl9Q3zToNEPiu0DaOeE8ZtH4k9PjHt4U,22
+disaster_fund_calculation_engine-0.1.0.dist-info/RECORD,,

disaster_fund_calculation_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

disaster_fund_calculation_engine-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fm_calculation_engine

fm_calculation_engine/__init__.py

@@ -0,0 +1,51 @@
+from fm_calculation_engine.beneficiary import (
+    BeneficiaryProfile,
+    ReceivableAmounts,
+    TrancheAmount,
+    receivable_amounts,
+)
+from fm_calculation_engine.common import (
+    BeneficiaryCount,
+    Donation,
+    EngineInputError,
+    validate_beneficiary_counts,
+)
+from fm_calculation_engine.district import (
+    DistrictCollectible,
+    DistrictOutput,
+    DistrictProfile,
+    DistrictTrancheOutput,
+    LocalGovDisbursement,
+    calculate_district_fund,
+)
+from fm_calculation_engine.government import (
+    BeneficiaryGroupSummary,
+    GovDistrictPayment,
+    GovEntityProfile,
+    GovernmentLiabilityOutput,
+    GovTrancheLiability,
+    calculate_government_liability,
+)
+
+__all__ = [
+    "BeneficiaryProfile",
+    "ReceivableAmounts",
+    "TrancheAmount",
+    "receivable_amounts",
+    "BeneficiaryCount",
+    "Donation",
+    "EngineInputError",
+    "validate_beneficiary_counts",
+    "DistrictProfile",
+    "DistrictCollectible",
+    "LocalGovDisbursement",
+    "DistrictTrancheOutput",
+    "DistrictOutput",
+    "calculate_district_fund",
+    "GovEntityProfile",
+    "GovDistrictPayment",
+    "GovTrancheLiability",
+    "BeneficiaryGroupSummary",
+    "GovernmentLiabilityOutput",
+    "calculate_government_liability",
+]

fm_calculation_engine/beneficiary.py

@@ -0,0 +1,76 @@
+from fm_plan import ImplementationPlan, NonEmptyStr, StrictModel, norm
+
+from fm_calculation_engine.common import EngineInputError, match_name, parse
+
+
+class BeneficiaryProfile(StrictModel):
+    """Input: which plan, and which cell of the grant matrix this beneficiary falls in."""
+
+    plan_id: NonEmptyStr
+    region: NonEmptyStr
+    disaster_type: NonEmptyStr
+    solution_type: NonEmptyStr
+
+
+class TrancheAmount(StrictModel):
+    tranche: int  # 1, 2, 3, ...
+    stage: str
+    amount: int
+
+
+class ReceivableAmounts(StrictModel):
+    """Output: what the beneficiary receives in each tranche."""
+
+    plan_id: str
+    region: str
+    disaster_type: str
+    solution_type: str
+    tranches: list[TrancheAmount]
+    total: int
+
+
+def receivable_amounts(plan: ImplementationPlan, profile) -> ReceivableAmounts:
+    """Receivable amount for each tranche for one beneficiary."""
+    p = parse(BeneficiaryProfile, profile)
+
+    problems = []
+    if norm(p.plan_id) != norm(plan.plan_id):
+        problems.append(
+            f"plan_id '{p.plan_id}' does not match this plan ('{plan.plan_id}')")
+    region = match_name(p.region, plan.regions)
+    if region is None:
+        problems.append(
+            f"region '{p.region}' is not in this plan's regions {plan.regions}")
+    disaster = match_name(p.disaster_type, plan.disaster_types)
+    if disaster is None:
+        problems.append(
+            f"disaster_type '{p.disaster_type}' is not in this plan's disaster types {plan.disaster_types}"
+        )
+    solution = match_name(p.solution_type, plan.solution_types)
+    if solution is None:
+        problems.append(
+            f"solution_type '{p.solution_type}' is not in this plan's solution types {plan.solution_types}"
+        )
+    if problems:
+        raise EngineInputError(
+            f"{len(problems)} problem(s) in the input:\n" +
+            "\n".join(f"  - {x}" for x in problems)
+        )
+
+    row = next(
+        r for r in plan.grant_matrix
+        if (norm(r.region), norm(r.disaster_type), norm(r.solution_type))
+        == (norm(region), norm(disaster), norm(solution))
+    )  # a row always exists: the plan guarantees every combination has one
+
+    return ReceivableAmounts(
+        plan_id=plan.plan_id,
+        region=region,
+        disaster_type=disaster,
+        solution_type=solution,
+        tranches=[
+            TrancheAmount(tranche=number, stage=t.stage, amount=t.amount)
+            for number, t in enumerate(row.tranches, start=1)
+        ],
+        total=row.total,
+    )

fm_calculation_engine/common.py

@@ -0,0 +1,184 @@
+from datetime import date
+from typing import Annotated
+
+from pydantic import Field, ValidationError
+
+from fm_plan import ImplementationPlan, NonEmptyStr, StrictModel, norm
+
+
+class EngineInputError(Exception):
+    """The input given to the engine is not valid."""
+
+
+def parse(model_class, data):
+    """Build model_class from a dictionary (or an existing object).
+
+    A problem becomes an EngineInputError with one readable line per problem.
+    """
+    try:
+        return model_class.model_validate(data)
+    except ValidationError as error:
+        lines = []
+        for err in error.errors():
+            where = ".".join(str(part) for part in err["loc"]) or "input"
+            message = err["msg"].removeprefix("Value error, ")
+            for problem in message.split("; "):
+                lines.append(f"  - {where}: {problem}")
+        raise EngineInputError(
+            f"{len(lines)} problem(s) in the input:\n" + "\n".join(lines)
+        ) from None
+
+
+class Donation(StrictModel):
+    """A donation received by a government entity from INGO, NGO, or private/public source.
+
+    Donations are pooled: the whole amount is available from tranche 1 and any surplus
+    rolls over to the next tranche. `received_date` is recorded for transparency (the
+    output lists donations oldest first) but does not decide which tranche a donation
+    can pay for, because the plan does not give tranches due dates.
+    """
+
+    donor_name: NonEmptyStr
+    amount: Annotated[int, Field(
+        gt=0, description="Exact donation amount in whole rupees")]
+    received_date: date | None = None
+
+
+class BeneficiaryCount(StrictModel):
+    """Beneficiary count for a specific category within a district (and optional local level).
+
+    `district` and `local_level` accept either official names or codes.
+    `region` is optional. A district belongs to exactly one region in the plan, so it
+    is taken from the plan. If you do give it, it must match the plan's region for
+    that district.
+    """
+
+    district: NonEmptyStr
+    disaster_type: NonEmptyStr
+    solution_type: NonEmptyStr
+    count: Annotated[int, Field(
+        ge=0, description="Number of beneficiary households")]
+    region: NonEmptyStr | None = None
+    local_level: NonEmptyStr | None = None
+    district_code: NonEmptyStr | None = None
+    local_level_code: NonEmptyStr | None = None
+
+
+def match_name(value: str, allowed: list[str]) -> str | None:
+    """The name in `allowed` that equals `value`, ignoring capital letters, or None."""
+    for name in allowed:
+        if norm(name) == norm(value):
+            return name
+    return None
+
+
+def validate_beneficiary_counts(
+    plan: ImplementationPlan,
+    counts: list[BeneficiaryCount | dict],
+) -> list[BeneficiaryCount]:
+    """Check every count against the plan and return them with the plan's own spelling and codes.
+
+    Accepts district and local level by name or code.
+    A count is rejected when:
+      - its district, disaster type or solution type is not in the plan;
+      - its region does not match the region the plan gives that district;
+      - its local level does not belong to its district;
+      - its district (or local level) is not inside the plan's affected areas.
+
+    In the returned counts `region` is always filled in, taken from the plan.
+    """
+    parsed_counts = [parse(BeneficiaryCount, c) for c in counts]
+    problems: list[str] = []
+    checked: list[BeneficiaryCount] = []
+
+    for idx, b in enumerate(parsed_counts):
+        district = plan.government.find_district(b.district)
+        if district is None:
+            problems.append(
+                f"item {idx}: district '{b.district}' is not in plan's districts "
+                f"{[d.name for d in plan.government.districts]}"
+            )
+
+        if b.region is not None:
+            matched_region = match_name(b.region, plan.regions)
+            if matched_region is None:
+                problems.append(
+                    f"item {idx}: region '{b.region}' is not in plan's regions {plan.regions}"
+                )
+            elif district is not None and norm(matched_region) != norm(district.region):
+                problems.append(
+                    f"item {idx}: region '{b.region}' does not match district '{district.name}', "
+                    f"which is in region '{district.region}' in this plan"
+                )
+
+        disaster = match_name(b.disaster_type, plan.disaster_types)
+        if disaster is None:
+            problems.append(
+                f"item {idx}: disaster_type '{b.disaster_type}' is not in plan's disaster types "
+                f"{plan.disaster_types}"
+            )
+
+        solution = match_name(b.solution_type, plan.solution_types)
+        if solution is None:
+            problems.append(
+                f"item {idx}: solution_type '{b.solution_type}' is not in plan's solution types "
+                f"{plan.solution_types}"
+            )
+
+        local_level_obj = None
+        if b.local_level and district is not None:
+            matching_lls = plan.government.find_local_level(b.local_level, district.name)
+            if not matching_lls:
+                problems.append(
+                    f"item {idx}: local level '{b.local_level}' does not belong to district "
+                    f"'{district.name}' in this plan"
+                )
+            else:
+                local_level_obj = matching_lls[0]
+
+        if district is not None and b.district_code is not None:
+            if not district.code or norm(b.district_code) != norm(district.code):
+                problems.append(
+                    f"item {idx}: district_code '{b.district_code}' does not match district "
+                    f"'{district.name}' (code '{district.code}' in this plan)"
+                )
+        if b.local_level_code is not None:
+            if not b.local_level:
+                problems.append(
+                    f"item {idx}: local_level_code '{b.local_level_code}' was given without a local_level"
+                )
+            elif local_level_obj is not None and (
+                not local_level_obj.code or norm(b.local_level_code) != norm(local_level_obj.code)
+            ):
+                problems.append(
+                    f"item {idx}: local_level_code '{b.local_level_code}' does not match local level "
+                    f"'{local_level_obj.name}' (code '{local_level_obj.code}' in this plan)"
+                )
+
+        local_level_name = local_level_obj.name if local_level_obj else None
+        if district is not None and (local_level_name or not b.local_level):
+            if not plan.is_affected(district.name, local_level_name):
+                where = f"local level '{b.local_level}' in district '{district.name}'" if b.local_level else f"district '{district.name}'"
+                problems.append(
+                    f"item {idx}: {where} is not in this plan's affected areas")
+
+        if district is not None and disaster and solution and (local_level_name or not b.local_level):
+            checked.append(
+                BeneficiaryCount(
+                    district=district.name,
+                    district_code=district.code,
+                    region=district.region,
+                    disaster_type=disaster,
+                    solution_type=solution,
+                    count=b.count,
+                    local_level=local_level_name,
+                    local_level_code=local_level_obj.code if local_level_obj else None,
+                )
+            )
+
+    if problems:
+        raise EngineInputError(
+            f"{len(problems)} problem(s) in beneficiary counts:\n"
+            + "\n".join(f"  - {p}" for p in problems)
+        )
+    return checked

fm_calculation_engine/core.py

@@ -0,0 +1,183 @@
+"""Shared calculation core.
+
+Every number the engine reports about a district comes from ONE schedule built here,
+so the three outputs cannot disagree:
+
+    district total  =  federal share + province share + local share      (exact)
+    local share     =  sum of the shares given to the district's local levels (exact)
+
+Splitting uses the largest remainder method on whole rupees: each part gets the
+whole rupees it is owed, and the few rupees left over go to the parts with the
+largest fractions. The parts therefore always add up to the total, with no
+rounding drift and no dependence on Python's round().
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+from fm_plan import ImplementationPlan, norm
+
+from fm_calculation_engine.common import BeneficiaryCount, EngineInputError
+
+
+def split_by_weights(total: int, weights) -> list[int]:
+    """Split a whole-rupee `total` in proportion to `weights`. The parts add up to `total`.
+
+    Ties between equal fractions go to the earlier item, so the result is always the
+    same for the same input.
+    """
+    weight_list = [Decimal(str(w)) for w in weights]
+    if any(w < 0 for w in weight_list):
+        raise ValueError("weights cannot be negative")
+    weight_sum = sum(weight_list)
+    if total == 0:
+        return [0] * len(weight_list)
+    if weight_sum == 0:
+        raise ValueError(
+            "cannot split a non-zero amount across weights that add up to zero")
+
+    quotas = [Decimal(total) * w / weight_sum for w in weight_list]
+    # quotas are never negative, so int() is the floor
+    parts = [int(q) for q in quotas]
+    leftover = total - sum(parts)
+    by_largest_fraction = sorted(
+        range(len(parts)), key=lambda i: (-(quotas[i] - parts[i]), i)
+    )
+    for i in by_largest_fraction[:leftover]:
+        parts[i] += 1
+    return parts
+
+
+def split_liability(plan: ImplementationPlan, amount: int) -> tuple[int, int, int]:
+    """(federal, province, local) shares of `amount`, adding up to `amount`."""
+    g = plan.government_liability
+    federal, province, local = split_by_weights(
+        amount, [g.federal, g.province, g.local])
+    return federal, province, local
+
+
+def max_tranche_count(plan: ImplementationPlan) -> int:
+    """Number of tranche rounds: the longest tranche list in the grant matrix."""
+    return max((len(r.tranches) for r in plan.grant_matrix), default=0)
+
+
+@dataclass
+class TrancheRound:
+    """Everything one district needs for one tranche round."""
+
+    tranche: int  # 1, 2, 3, ...
+    stages: list[str]
+    # local level -> money it must receive and pay out
+    required: dict[str, int]
+    total: int  # money the district needs this round
+    federal: int  # federal share of `total`
+    province: int  # province share of `total`
+    local: int  # local share of `total`
+    local_shares: dict[str, int]  # `local` split over the local levels
+
+
+@dataclass
+class DistrictSchedule:
+    name: str
+    code: str | None
+    province: str
+    province_code: str | None
+    region: str
+    local_levels: list[str]
+    local_level_codes: dict[str, str | None]
+    rounds: list[TrancheRound]
+
+
+def build_district_schedule(
+    plan: ImplementationPlan,
+    district_name: str,
+    district_counts: list[BeneficiaryCount],
+) -> DistrictSchedule:
+    """Work out every tranche round for one district.
+
+    `district_counts` must already be validated (see validate_beneficiary_counts)
+    and belong to this district. `district_name` can be a name or code.
+    """
+    district = plan.government.find_district(district_name)
+    if district is None:
+        raise EngineInputError(
+            f"District '{district_name}' was not found in this plan's districts."
+        )
+
+    prov_obj = plan.government.find_province(district.province)
+    province_name = prov_obj.name if prov_obj else district.province
+    province_code = prov_obj.code if prov_obj else None
+
+    matching_levels = [
+        ll for ll in plan.government.local_levels
+        if norm(ll.district) == norm(district.code)
+    ]
+    local_levels = [ll.name for ll in matching_levels]
+    local_level_codes = {ll.name: ll.code for ll in matching_levels}
+
+    if district_counts and not local_levels:
+        raise EngineInputError(
+            f"District '{district.name}' has beneficiaries but no local levels in this plan's "
+            "government section, so its money cannot be forwarded. Add its local levels."
+        )
+
+    matrix = {
+        (norm(r.region), norm(r.disaster_type), norm(r.solution_type)): r
+        for r in plan.grant_matrix
+    }
+
+    rounds: list[TrancheRound] = []
+    for tranche in range(1, max_tranche_count(plan) + 1):
+        required = {ll: 0 for ll in local_levels}
+        unassigned = 0  # beneficiaries who did not name a local level
+        stages: set[str] = set()
+
+        for b in district_counts:
+            row = matrix[(norm(b.region), norm(
+                b.disaster_type), norm(b.solution_type))]
+            if tranche > len(row.tranches):
+                # this grant has no payment in this round (its amount is Rs. 0)
+                continue
+            payment = row.tranches[tranche - 1]
+            stages.add(payment.stage)
+            amount = b.count * payment.amount
+            if b.local_level:
+                required[b.local_level] += amount
+            else:
+                unassigned += amount
+
+        # Money for beneficiaries with no local level is shared equally between the
+        # district's local levels. Any odd rupees go to the first ones in the plan.
+        if unassigned:
+            for ll, share in zip(local_levels, split_by_weights(unassigned, [1] * len(local_levels))):
+                required[ll] += share
+
+        total = sum(required.values())
+        federal, province, local = split_liability(plan, total)
+        local_shares = dict(
+            zip(local_levels, split_by_weights(
+                local, [required[ll] for ll in local_levels]))
+        )
+        rounds.append(
+            TrancheRound(
+                tranche=tranche,
+                stages=sorted(stages),
+                required=required,
+                total=total,
+                federal=federal,
+                province=province,
+                local=local,
+                local_shares=local_shares,
+            )
+        )
+
+    return DistrictSchedule(
+        name=district.name,
+        code=district.code,
+        province=province_name,
+        province_code=province_code,
+        region=district.region,
+        local_levels=local_levels,
+        local_level_codes=local_level_codes,
+        rounds=rounds,
+    )

fm_calculation_engine/district.py

@@ -0,0 +1,119 @@
+from fm_plan import ImplementationPlan, NonEmptyStr, StrictModel, norm
+
+from fm_calculation_engine.common import (
+    BeneficiaryCount,
+    EngineInputError,
+    parse,
+    validate_beneficiary_counts,
+)
+from fm_calculation_engine.core import build_district_schedule
+
+
+class DistrictProfile(StrictModel):
+    """Input profile for District fund calculation (accepts district name or code)."""
+
+    plan_id: NonEmptyStr
+    district_name: NonEmptyStr
+
+
+class DistrictCollectible(StrictModel):
+    """Breakdown of funds collected from Federal, Province, and Local government levels."""
+
+    federal: int
+    province: int
+    local: int
+    total: int
+
+
+class LocalGovDisbursement(StrictModel):
+    """Total fund to be forwarded to a specific local government for a tranche."""
+
+    local_gov: str
+    amount: int
+    local_gov_code: str | None = None
+
+
+class DistrictTrancheOutput(StrictModel):
+    """Collectible and disbursement amounts for a district in a single tranche round."""
+
+    tranche: int
+    stages: list[str]
+    collectible: DistrictCollectible
+    disbursements: list[LocalGovDisbursement]
+    total_amount: int
+
+
+class DistrictOutput(StrictModel):
+    """Fund collection and disbursement responsibility for a district."""
+
+    plan_id: str
+    district_name: str
+    province_name: str
+    region: str
+    total_beneficiaries: int
+    tranches: list[DistrictTrancheOutput]
+    grand_total: int
+    district_code: str | None = None
+    province_code: str | None = None
+
+
+def calculate_district_fund(
+    plan: ImplementationPlan,
+    profile: DistrictProfile | dict,
+    beneficiary_counts: list[BeneficiaryCount | dict],
+) -> DistrictOutput:
+    """Calculate collectible amounts from Fed/Prov/Local and forwarding amounts to local governments."""
+    prof = parse(DistrictProfile, profile)
+
+    if norm(prof.plan_id) != norm(plan.plan_id):
+        raise EngineInputError(
+            f"plan_id '{prof.plan_id}' does not match this plan ('{plan.plan_id}')"
+        )
+
+    district_obj = plan.government.find_district(prof.district_name)
+    if district_obj is None:
+        district_names = [d.name for d in plan.government.districts]
+        raise EngineInputError(
+            f"District '{prof.district_name}' was not found in the plan's districts {district_names}."
+        )
+
+    valid_counts = validate_beneficiary_counts(plan, beneficiary_counts)
+    district_counts = [b for b in valid_counts if norm(
+        b.district) == norm(district_obj.name)]
+
+    schedule = build_district_schedule(plan, district_obj.name, district_counts)
+
+    tranche_outputs = [
+        DistrictTrancheOutput(
+            tranche=r.tranche,
+            stages=r.stages,
+            collectible=DistrictCollectible(
+                federal=r.federal,
+                province=r.province,
+                local=r.local,
+                total=r.total,
+            ),
+            disbursements=[
+                LocalGovDisbursement(
+                    local_gov=ll,
+                    local_gov_code=schedule.local_level_codes.get(ll),
+                    amount=r.required[ll],
+                )
+                for ll in schedule.local_levels
+            ],
+            total_amount=r.total,
+        )
+        for r in schedule.rounds
+    ]
+
+    return DistrictOutput(
+        plan_id=plan.plan_id,
+        district_name=schedule.name,
+        district_code=schedule.code,
+        province_name=schedule.province,
+        province_code=schedule.province_code,
+        region=schedule.region,
+        total_beneficiaries=sum(b.count for b in district_counts),
+        tranches=tranche_outputs,
+        grand_total=sum(r.total for r in schedule.rounds),
+    )

fm_calculation_engine/government.py

@@ -0,0 +1,303 @@
+from datetime import date
+
+from fm_plan import ImplementationPlan, NonEmptyStr, StrictModel, norm
+
+from fm_calculation_engine.common import (
+    BeneficiaryCount,
+    Donation,
+    EngineInputError,
+    parse,
+    validate_beneficiary_counts,
+)
+from fm_calculation_engine.core import (
+    build_district_schedule,
+    max_tranche_count,
+    split_by_weights,
+)
+
+
+class GovEntityProfile(StrictModel):
+    """Input profile for Federal, Provincial, or Local government entity."""
+
+    plan_id: NonEmptyStr
+    gov_entity_name: NonEmptyStr
+    # "federal", "province", or "local" (optional: auto-detected if omitted)
+    gov_type: NonEmptyStr | None = None
+    # Only for a local government whose name is used in more than one district.
+    district: NonEmptyStr | None = None
+    donations: list[Donation] = []
+
+
+class GovDistrictPayment(StrictModel):
+    """Payment responsibility towards a specific district for a single tranche."""
+
+    district: str
+    gross_liability: int
+    donation_offset: int
+    net_payable: int
+    district_code: str | None = None
+
+
+class GovTrancheLiability(StrictModel):
+    """Fund liability breakdown for a government entity for a specific tranche round."""
+
+    tranche: int
+    stages: list[str]
+    gross_liability: int
+    donation_applied: int
+    net_payable: int
+    remaining_donation: int
+    districts: list[GovDistrictPayment]
+
+
+class BeneficiaryGroupSummary(StrictModel):
+    """Summary count of beneficiaries by disaster, region, and solution type under this entity."""
+
+    disaster_type: str
+    region: str
+    solution_type: str
+    count: int
+
+
+class GovernmentLiabilityOutput(StrictModel):
+    """Complete liability and disbursement responsibility for a government entity."""
+
+    plan_id: str
+    gov_entity_name: str
+    gov_type: str  # "federal", "province", or "local"
+    liability_percentage: float
+    total_donations_received: int
+    donations: list[Donation]  # oldest first; donations with no date come last
+    total_beneficiaries: int
+    # Local governments only: households in the same district that did not name a local
+    # level. They are not counted in total_beneficiaries, but their money is shared
+    # equally between the district's local levels, so it is part of the liability.
+    unassigned_beneficiaries: int = 0
+    beneficiary_summary: list[BeneficiaryGroupSummary]
+    tranches: list[GovTrancheLiability]
+    total_gross_liability: int
+    total_donation_applied: int
+    total_net_payable: int
+    final_remaining_donation: int
+    gov_entity_code: str | None = None
+
+
+def _resolve_entity(
+    plan: ImplementationPlan,
+    entity_name: str,
+    requested_type: str | None = None,
+    district: str | None = None,
+):
+    """Find which government this is (by name or code). Returns (type, canonical name, code, its district names)."""
+    federal = plan.government.federal
+    canonical_code = None
+
+    if norm(entity_name) == norm(federal.name) or norm(entity_name) == norm(federal.code):
+        entity_type = "federal"
+        canonical_name = federal.name
+        canonical_code = federal.code
+        managed_districts = [d.name for d in plan.government.districts]
+    elif (prov_obj := plan.government.find_province(entity_name)) is not None:
+        entity_type = "province"
+        canonical_name = prov_obj.name
+        canonical_code = prov_obj.code
+        managed_districts = [
+            d.name
+            for d in plan.government.districts
+            if norm(d.province) == norm(prov_obj.code)
+        ]
+    else:
+        # Check local levels
+        dist_filter_name = None
+        if district is not None:
+            dist_filter = plan.government.find_district(district)
+            if dist_filter is None:
+                raise EngineInputError(f"District '{district}' is not in this plan's districts.")
+            dist_filter_name = dist_filter.name
+
+        locals_found = plan.government.find_local_level(entity_name, district_identifier=dist_filter_name)
+        if not locals_found:
+            # Check if entity exists in another district when district was given
+            if district is not None:
+                all_matching = plan.government.find_local_level(entity_name)
+                if all_matching:
+                    raise EngineInputError(
+                        f"Local government '{all_matching[0].name}' is not in district '{district}' in this plan."
+                    )
+            raise EngineInputError(
+                f"Government entity '{entity_name}' was not found in the plan's government structure."
+            )
+
+        entity_type = "local"
+        canonical_name = locals_found[0].name
+        canonical_code = locals_found[0].code
+        managed_districts = [
+            (plan.government.find_district(ll.district).name if plan.government.find_district(ll.district) else ll.district)
+            for ll in locals_found
+        ]
+        if len(set(managed_districts)) > 1:
+            raise EngineInputError(
+                f"'{canonical_name}' is a local government in more than one district "
+                f"{managed_districts}. Say which one with the 'district' field."
+            )
+
+    if district is not None and entity_type != "local":
+        raise EngineInputError(
+            "'district' can only be given for a local government "
+            f"('{canonical_name}' is a {entity_type} government)."
+        )
+
+    if requested_type is not None and norm(requested_type) != norm(entity_type):
+        raise EngineInputError(
+            f"Specified gov_type '{requested_type}' does not match entity '{entity_name}' (expected '{entity_type}')."
+        )
+
+    return entity_type, canonical_name, canonical_code, managed_districts
+
+
+def calculate_government_liability(
+    plan: ImplementationPlan,
+    profile: GovEntityProfile | dict,
+    beneficiary_counts: list[BeneficiaryCount | dict],
+) -> GovernmentLiabilityOutput:
+    """Calculate government liability, donation offsets across tranches, and district breakdowns."""
+    prof = parse(GovEntityProfile, profile)
+
+    if norm(prof.plan_id) != norm(plan.plan_id):
+        raise EngineInputError(
+            f"plan_id '{prof.plan_id}' does not match this plan ('{plan.plan_id}')"
+        )
+
+    entity_type, canonical_name, canonical_code, managed_districts = _resolve_entity(
+        plan, prof.gov_entity_name, prof.gov_type, prof.district
+    )
+
+    valid_counts = validate_beneficiary_counts(plan, beneficiary_counts)
+
+    # Counts inside this government's districts
+    managed_norms = {norm(d) for d in managed_districts}
+    in_scope = [b for b in valid_counts if norm(b.district) in managed_norms]
+
+    if entity_type == "local":
+        relevant_counts = [
+            b for b in in_scope if b.local_level and norm(b.local_level) == norm(canonical_name)
+        ]
+        unassigned_beneficiaries = sum(
+            b.count for b in in_scope if not b.local_level)
+    else:
+        relevant_counts = in_scope
+        unassigned_beneficiaries = 0
+
+    liability = plan.government_liability
+    liability_pct = {
+        "federal": liability.federal,
+        "province": liability.province,
+        "local": liability.local,
+    }[entity_type]
+
+    # Beneficiary summary (names are already in the plan's spelling and region comes from the plan)
+    grouped: dict[tuple[str, str, str], int] = {}
+    for b in relevant_counts:
+        key = (b.disaster_type, b.region, b.solution_type)
+        grouped[key] = grouped.get(key, 0) + b.count
+    summary_list = [
+        BeneficiaryGroupSummary(
+            disaster_type=dis, region=reg, solution_type=sol, count=n)
+        for (dis, reg, sol), n in grouped.items()
+    ]
+    total_beneficiaries = sum(b.count for b in relevant_counts)
+
+    # Districts with beneficiaries, in the plan's order
+    active_districts = [
+        d.name
+        for d in plan.government.districts
+        if norm(d.name) in managed_norms and any(norm(b.district) == norm(d.name) for b in in_scope)
+    ]
+
+    # One schedule per district: the same numbers the district output uses
+    schedules = {
+        d: build_district_schedule(
+            plan, d, [b for b in in_scope if norm(b.district) == norm(d)]
+        )
+        for d in active_districts
+    }
+
+    def share_of_round(district: str, tranche_round) -> int:
+        if entity_type == "federal":
+            return tranche_round.federal
+        if entity_type == "province":
+            return tranche_round.province
+        local_level = next(
+            ll for ll in schedules[district].local_levels if norm(ll) == norm(canonical_name)
+        )
+        return tranche_round.local_shares[local_level]
+
+    # Donations are pooled and spent from tranche 1 onward; the surplus rolls over.
+    donations = sorted(
+        prof.donations, key=lambda d: (
+            d.received_date is None, d.received_date or date.min)
+    )
+    total_donations_received = sum(d.amount for d in donations)
+    available_donation = total_donations_received
+
+    tranche_outputs: list[GovTrancheLiability] = []
+    total_gross = 0
+    total_donations_used = 0
+
+    for index in range(max_tranche_count(plan)):
+        district_gross = {d: share_of_round(
+            d, schedules[d].rounds[index]) for d in active_districts}
+        stages = sorted(
+            {s for d in active_districts for s in schedules[d].rounds[index].stages})
+
+        tranche_gross = sum(district_gross.values())
+        donation_applied = min(available_donation, tranche_gross)
+        net_payable = tranche_gross - donation_applied
+        available_donation -= donation_applied
+
+        total_gross += tranche_gross
+        total_donations_used += donation_applied
+
+        # The donation relief is shared between districts in proportion to what each one needs
+        offsets = split_by_weights(
+            donation_applied, [district_gross[d] for d in active_districts])
+        district_payments = [
+            GovDistrictPayment(
+                district=d,
+                district_code=schedules[d].code,
+                gross_liability=district_gross[d],
+                donation_offset=offset,
+                net_payable=district_gross[d] - offset,
+            )
+            for d, offset in zip(active_districts, offsets)
+        ]
+
+        tranche_outputs.append(
+            GovTrancheLiability(
+                tranche=index + 1,
+                stages=stages,
+                gross_liability=tranche_gross,
+                donation_applied=donation_applied,
+                net_payable=net_payable,
+                remaining_donation=available_donation,
+                districts=district_payments,
+            )
+        )
+
+    return GovernmentLiabilityOutput(
+        plan_id=plan.plan_id,
+        gov_entity_name=canonical_name,
+        gov_entity_code=canonical_code,
+        gov_type=entity_type,
+        liability_percentage=liability_pct,
+        total_donations_received=total_donations_received,
+        donations=donations,
+        total_beneficiaries=total_beneficiaries,
+        unassigned_beneficiaries=unassigned_beneficiaries,
+        beneficiary_summary=summary_list,
+        tranches=tranche_outputs,
+        total_gross_liability=total_gross,
+        total_donation_applied=total_donations_used,
+        total_net_payable=total_gross - total_donations_used,
+        final_remaining_donation=available_donation,
+    )