crudecode 0.1.0a1__py3-none-any.whl

crudecode/GUIDE.md

@@ -0,0 +1,103 @@
+# crudecode: start here
+
+`crudecode` is the method half of Crude Code. It is a small Python package you
+run in your own sandbox. It gives you guides (how to forecast a well, how to
+value a package), default assumptions, and the code that checks your forecasts
+and does the economics. It never touches the network and it never chooses a
+number for you.
+
+The other half is the **Crude Code MCP server**, which serves the data: US well
+headers and monthly production from state regulatory filings. The split is
+deliberate:
+
+| | Crude Code MCP (data) | `crudecode` (method) |
+|---|---|---|
+| Holds | well headers, monthly production, coverage, SQL over the warehouse | guides, decline-curve and cashflow code, default assumptions |
+| You use it for | evidence: what did this well report? | judgment checks and arithmetic: what does this curve imply? what is this package worth? |
+| Where it runs | the server | your sandbox |
+
+Rule of thumb: **bulk data stays on the MCP; only small inputs reach the
+sandbox, and you write them.** You do not copy production tables into the
+sandbox. You read the history through the data tools, make your judgments, and
+write a small file (about a few hundred bytes per well: curves, interests, a
+few facts) that the kit reads.
+
+## The data tools (Crude Code MCP)
+
+| Tool | Use it for |
+|---|---|
+| `get_coverage` | what data exists, per state; how complete each header field is. Call first when unsure a question can be answered. |
+| `search` | resolve a well name, API number, operator or county to ids |
+| `get_well` | full header for up to 50 wells: status, formation, lateral, key dates, cumulatives |
+| `get_production` | monthly oil (bbl), gas (mcf), water, days produced for up to 50 wells, or summed across wells (`combine=true`) |
+| `run_sql` | anything custom: one read-only SELECT against the warehouse (its description carries the schema). Use it for aggregates so the rows you read stay small. |
+
+Facts you must carry with you: `api10` is the **undashed 10-digit** API number.
+A **NULL volume means no number was reported, never zero**. `prod_month = 1`
+is a well's first producing month (often partial). Some header columns are thin
+in some states (check `get_coverage`); say so rather than presenting a partial
+set as the whole.
+
+## Which guide for which job
+
+| Job | Read | Commands |
+|---|---|---|
+| Forecast one well or many: assert decline curves and sanity-check them | `crudecode guide forecasting` | `crudecode forecast check deal.json` |
+| Value a package: NPV by PDP / DUC / PUD, monthly volumes and cashflows | `crudecode guide valuation` (forecast first, then value) | `crudecode assumptions init`, `crudecode forecast check`, `crudecode value` |
+| See the exact deal.json contract | `crudecode guide schema` | |
+| See a worked deal.json | `crudecode guide example` (and `crudecode guide example-assumptions`) | |
+
+A valuation always needs forecasts, so for a valuation read **forecasting
+first**, then **valuation**.
+
+## The commands
+
+```
+crudecode guide [forecasting|valuation|schema|example|example-assumptions]
+                                                         print a guide
+crudecode forecast check deal.json [--assumptions FILE] [--json]
+                                                         validate asserted curves and echo what they imply
+crudecode assumptions init assumptions.toml              write the default economic assumptions to edit
+crudecode value deal.json --assumptions assumptions.toml --out out/
+                                                         run the economics; writes wells_monthly.csv,
+                                                         parameters.csv, README.md into out/
+```
+
+Exit codes: 0 fine, 1 `deal.json` failed validation (every violation is
+listed at once; nothing is accepted piecemeal), 2 a file could not be read, the
+assumptions file is invalid, or the command was used wrongly.
+
+The guides are long. `crudecode guide forecasting --toc` lists a guide's
+sections and `crudecode guide forecasting --section N` prints one, in case your
+sandbox truncates long output.
+
+## Ground rules
+
+1. **You assert every parameter.** The kit validates sanity bounds and echoes
+   consequences; anything inside the bounds is your call. Write your reasoning
+   in each well's `rationale`.
+2. **Nothing is defaulted silently.** Every well needs an explicit bucket
+   (PDP, DUC or PUD). Economic assumptions come from an assumptions file you
+   have shown to the user. If the kit refuses an input, fix the input; do not
+   work around it.
+3. **Show the assumptions, get a yes, then run.** Before `crudecode value`,
+   present the assumptions (the valuation guide has the grid) and let the user
+   confirm or change them.
+4. **Units.** Oil in barrels, gas in mcf, rates per month, money in USD,
+   interests as fractions (0.75 = 75%), decline `di` as a nominal monthly rate.
+5. **Say what the number is.** This version prices on a **flat deck** only
+   (strip/futures pricing is not supported yet), models no NGLs and no
+   ownership or title diligence, and values what the wells' assertions say.
+   State those limits next to any NPV you report.
+6. **Hand over the files.** The outputs are plain CSV, JSON and Markdown. Give
+   the user the files as they are, and summarize the NPV in your reply.
+
+## Installing
+
+```
+pip install --break-system-packages crudecode==0.1.0a1
+```
+
+Two dependencies (numpy, python-dateutil). After install the kit needs no
+network access. Problems with the kit or the data: tell the user, and use the
+MCP's `message_team` tool to report them.

crudecode/__init__.py

@@ -0,0 +1,4 @@
+"""crudecode: guides, forecast checks and valuation economics for oil & gas
+analysis with an LLM. Pairs with the Crude Code MCP data server."""
+
+__version__ = "0.1.0a1"

crudecode/__main__.py

@@ -0,0 +1,3 @@
+from crudecode.cli import main
+
+raise SystemExit(main())

crudecode/cli.py

@@ -0,0 +1,151 @@
+"""The `crudecode` command line.
+
+    crudecode guide [name]
+    crudecode forecast check deal.json [--assumptions FILE] [--json]
+    crudecode assumptions init FILE [--force]
+    crudecode value deal.json --assumptions FILE --out DIR [--json]
+
+The kit makes no network calls and writes only the files it is told to.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from importlib.resources import files
+
+from crudecode import __version__
+
+# `crudecode guide <name>` -> path inside the package.
+_GUIDES = {
+    "index": ("GUIDE.md",),
+    "forecasting": ("forecasting", "GUIDE.md"),
+    "valuation": ("valuation", "GUIDE.md"),
+    "schema": ("valuation", "schema.json"),
+    "example": ("valuation", "examples", "deal.json"),
+    "example-assumptions": ("valuation", "examples", "assumptions.toml"),
+}
+_GUIDE_BLURB = {
+    "index": "what the kit is and which guide to read (default)",
+    "forecasting": "how to assert decline curves and check them",
+    "valuation": "how to build deal.json from the data tools, run the economics, read the results",
+    "schema": "the JSON Schema for deal.json",
+    "example": "one worked deal.json (synthetic wells)",
+    "example-assumptions": "the assumptions file that example was valued with",
+}
+
+
+def _sections(text: str) -> list[tuple[str, str]]:
+    """Split a Markdown guide into (heading, body) parts at its '## ' headings.
+    Anything before the first '## ' (title, intro) is part 0, headed by the title."""
+    parts: list[tuple[str, list[str]]] = [("(start)", [])]
+    in_fence = False
+    for line in text.splitlines(keepends=True):
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+        if line.startswith("## ") and not in_fence:
+            parts.append((line[3:].strip(), [line]))
+        else:
+            parts[-1][1].append(line)
+    return [(h, "".join(b)) for h, b in parts]
+
+
+def _guide(name: str | None, section: str | None, toc: bool) -> int:
+    key = (name or "index").lower()
+    if key not in _GUIDES:
+        sys.stderr.write(f"no guide named {name!r}. Available:\n")
+        for k, blurb in _GUIDE_BLURB.items():
+            sys.stderr.write(f"  crudecode guide {k:<12} {blurb}\n")
+        return 2
+    text = files("crudecode").joinpath(*_GUIDES[key]).read_text(encoding="utf-8")
+    if not (toc or section):
+        sys.stdout.write(text)
+        return 0
+    if not _GUIDES[key][-1].endswith(".md"):
+        sys.stderr.write(f"{key} is not a sectioned guide; print it whole\n")
+        return 2
+    parts = _sections(text)
+    if toc:
+        sys.stdout.write(f"crudecode guide {key}: {len(text):,} characters in {len(parts) - 1} sections\n")
+        for i, (heading, body) in enumerate(parts):
+            sys.stdout.write(f"  {i}  {heading}  ({len(body):,} chars)\n")
+        sys.stdout.write(f"read one with: crudecode guide {key} --section N  (or a word from the heading)\n")
+        return 0
+    if section.isdigit() and int(section) < len(parts):
+        sys.stdout.write(parts[int(section)][1])
+        return 0
+    hits = [p for p in parts[1:] if section.lower() in p[0].lower()]
+    if len(hits) != 1:
+        sys.stderr.write(f"--section {section!r} matches {len(hits)} sections; use a number from --toc\n")
+        return 2
+    sys.stdout.write(hits[0][1])
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="crudecode",
+        description="Guides, forecast checks and valuation economics for oil & gas analysis with an LLM. "
+                    "Start with: crudecode guide")
+    p.add_argument("--version", action="version", version=f"crudecode {__version__}")
+    sub = p.add_subparsers(dest="cmd", metavar="command")
+
+    g = sub.add_parser("guide", help="print a guide (index, forecasting, valuation, schema, example, example-assumptions)")
+    g.add_argument("name", nargs="?", help="guide name; omit for the index")
+    g.add_argument("--toc", action="store_true", help="list the guide's sections and their sizes")
+    g.add_argument("--section", help="print one section only: a number from --toc, or a word from its heading")
+
+    f = sub.add_parser("forecast", help="forecast workflow")
+    fsub = f.add_subparsers(dest="forecast_cmd", metavar="action", required=True)
+    fc = fsub.add_parser("check", help="validate asserted decline curves in deal.json and echo what they imply")
+    fc.add_argument("deal", help="path to deal.json")
+    fc.add_argument("--assumptions", help="assumptions TOML (horizon, terminal decline); defaults if omitted")
+    fc.add_argument("--json", action="store_true", help="machine-readable output")
+
+    a = sub.add_parser("assumptions", help="economic assumptions file")
+    asub = a.add_subparsers(dest="assumptions_cmd", metavar="action", required=True)
+    ai = asub.add_parser("init", help="write the default assumptions to FILE")
+    ai.add_argument("file", help="where to write the TOML")
+    ai.add_argument("--force", action="store_true", help="overwrite an existing file")
+
+    v = sub.add_parser("value", help="run the economics for deal.json and write the result files")
+    v.add_argument("deal", help="path to deal.json")
+    v.add_argument("--assumptions", required=True,
+                   help="assumptions TOML (create one with: crudecode assumptions init FILE)")
+    v.add_argument("--out", required=True, help="directory for wells_monthly.csv, parameters.csv, README.md")
+    v.add_argument("--json", action="store_true", help="print the summary as JSON instead of text")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        return _run(argv)
+    except BrokenPipeError:               # `crudecode guide forecasting | head`
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 0
+
+
+def _run(argv: list[str] | None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.cmd is None:
+        parser.print_help()
+        sys.stdout.write("\nStart here: crudecode guide\n")
+        return 0
+    if args.cmd == "guide":
+        return _guide(args.name, args.section, args.toc)
+    if args.cmd == "forecast":
+        from crudecode.forecasting import check
+        return check.run(args.deal, args.assumptions, args.json)
+    if args.cmd == "assumptions":
+        from crudecode.valuation import run
+        return run.init_assumptions(args.file, args.force)
+    if args.cmd == "value":
+        from crudecode.valuation import run
+        return run.run(args.deal, args.assumptions, args.out, args.json)
+    parser.error(f"unknown command {args.cmd!r}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

crudecode/engine/__init__.py

@@ -0,0 +1,3 @@
+"""Shared utilities: decline curves, forecast consequences, economics, the
+assumptions loader and the deal.json parser. Workflows (forecasting/,
+valuation/) import from here and never from each other."""

crudecode/engine/assumptions.py

@@ -0,0 +1,223 @@
+"""Economic assumptions: the defaults, the TOML loader, the validation.
+
+Every economic number a valuation uses lives here and nowhere else. The
+defaults are the house defaults of the Crude Code valuation engine;
+``valuation/assumptions.default.toml`` is the same numbers as an editable file
+(a test pins the two together). A file may set only some keys: the rest take
+the defaults, and ``Assumptions.explicit`` records which keys the file set, so
+every output can say which numbers are defaults.
+"""
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+BUCKETS = ("PDP", "DUC", "PUD")
+
+
+class AssumptionsError(ValueError):
+    """The assumptions file is unreadable or has invalid values. ``problems``
+    lists every one (never fail-fast)."""
+
+    def __init__(self, problems: list[str]):
+        self.problems = problems
+        super().__init__("; ".join(problems))
+
+
+def _default_rates() -> dict[str, float]:
+    return {"PDP": 0.15, "DUC": 0.20, "PUD": 0.25}
+
+
+@dataclass(frozen=True)
+class Assumptions:
+    # Flat price deck. ("strip" needs futures data and is not supported in v0.)
+    price_deck_type: str = "flat"
+    oil_price: float = 70.0              # $/bbl
+    gas_price: float = 3.50              # $/MMBtu
+
+    # Differentials off the deck: realized = deck - diff. Positive = below the deck.
+    oil_diff: float = 0.0                # $/bbl
+    gas_diff: float = 0.0                # $/MMBtu
+
+    # Gas heat content, MMBtu per mcf. Volumes are mcf; the deck is $/MMBtu, so
+    # gas revenue is mcf x btu x ($/MMBtu). NGL uplift and shrink are not modeled.
+    gas_btu_factor: float = 1.05
+
+    # Taxes / deductions.
+    tax_pct: float = 0.075               # severance / production tax
+    gpt_pct: float = 0.05                # gathering, processing, transport
+
+    # Costs (working-interest deals only; minerals bear none).
+    opex_per_bbl_usd: float = 0.0        # per GROSS oil bbl, borne at WI share
+    opex_per_well_per_month_usd: float = 0.0   # per well-month while online, borne at WI share
+    capex_per_well_usd: float = 0.0      # gross 100% drill+complete cost of ONE well; x WI by the engine
+
+    # Cashflow horizon, months.
+    horizon_months: int = 360
+
+    # Terminal decline: once a curve's hyperbolic decline shallows to this
+    # annual rate it switches to an exponential tail at this rate. The
+    # calculator's tail policy, not a per-well assertion.
+    terminal_di_annual: float = 0.05
+
+    # Annual discount rate per bucket. Each bucket is discounted at its own rate.
+    discount_rates: dict = field(default_factory=_default_rates)
+
+    # Dotted TOML keys the loaded file set explicitly (empty for pure defaults).
+    explicit: frozenset = frozenset()
+
+
+DEFAULTS = Assumptions()
+
+# TOML key -> (table, key, Assumptions attribute)
+_KEYS = {
+    ("price_deck", "type"): "price_deck_type",
+    ("price_deck", "oil_usd_bbl"): "oil_price",
+    ("price_deck", "gas_usd_mmbtu"): "gas_price",
+    ("economics", "oil_diff"): "oil_diff",
+    ("economics", "gas_diff"): "gas_diff",
+    ("economics", "gas_btu_factor"): "gas_btu_factor",
+    ("economics", "tax_pct"): "tax_pct",
+    ("economics", "gpt_pct"): "gpt_pct",
+    ("economics", "opex_per_bbl_usd"): "opex_per_bbl_usd",
+    ("economics", "opex_per_well_per_month_usd"): "opex_per_well_per_month_usd",
+    ("economics", "capex_per_well_usd"): "capex_per_well_usd",
+    ("economics", "horizon_months"): "horizon_months",
+    ("economics", "terminal_di_annual"): "terminal_di_annual",
+}
+_TABLES = {"price_deck", "economics", "discount_rates"}
+
+
+def _is_number(v) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def _check(problems: list[str], label: str, v, kind: str) -> None:
+    """Append a problem unless ``v`` satisfies ``kind``."""
+    ok, want = True, ""
+    if kind == "money":
+        ok, want = _is_number(v) and v >= 0, "a non-negative number"
+    elif kind == "signed":
+        ok, want = _is_number(v), "a number"
+    elif kind == "fraction_lt1":
+        ok, want = _is_number(v) and 0.0 <= v < 1.0, "a number in [0, 1)"
+    elif kind == "open_unit":
+        ok, want = _is_number(v) and 0.0 < v < 1.0, "a number in (0, 1)"
+    elif kind == "btu":
+        ok, want = _is_number(v) and 0.5 <= v <= 2.0, "a number in [0.5, 2.0] (MMBtu per mcf)"
+    elif kind == "horizon":
+        ok, want = isinstance(v, int) and not isinstance(v, bool) and 1 <= v <= 600, "an integer 1-600 (months)"
+    if not ok:
+        problems.append(f"{label} must be {want}, got {v!r}")
+
+
+_KIND = {
+    "oil_price": "money", "gas_price": "money", "oil_diff": "signed", "gas_diff": "signed",
+    "gas_btu_factor": "btu", "tax_pct": "fraction_lt1", "gpt_pct": "fraction_lt1",
+    "opex_per_bbl_usd": "money", "opex_per_well_per_month_usd": "money",
+    "capex_per_well_usd": "money", "horizon_months": "horizon",
+    "terminal_di_annual": "open_unit",
+}
+
+
+def parse_assumptions(data: dict) -> Assumptions:
+    """A parsed TOML document -> validated Assumptions. Raises AssumptionsError
+    listing every problem."""
+    problems: list[str] = []
+    if not isinstance(data, dict):
+        raise AssumptionsError(["the assumptions file must be a TOML document"])
+
+    for table in data:
+        if table not in _TABLES:
+            problems.append(f"unknown table [{table}]; allowed: {sorted(_TABLES)}")
+
+    values: dict = {}
+    explicit: set[str] = set()
+
+    for table in ("price_deck", "economics"):
+        body = data.get(table)
+        if body is None:
+            continue
+        if not isinstance(body, dict):
+            problems.append(f"[{table}] must be a table")
+            continue
+        allowed = sorted(k for (t, k) in _KEYS if t == table)
+        for key, v in body.items():
+            attr = _KEYS.get((table, key))
+            if attr is None:
+                problems.append(f"[{table}] has unknown key {key!r}; allowed: {allowed}")
+                continue
+            explicit.add(f"{table}.{key}")
+            if attr == "price_deck_type":
+                if v == "strip":
+                    problems.append(
+                        "price_deck.type 'strip' is not supported in this version (a strip needs "
+                        "futures data the kit does not have); use 'flat' with oil_usd_bbl / gas_usd_mmbtu")
+                elif v != "flat":
+                    problems.append(f"price_deck.type must be 'flat', got {v!r}")
+                else:
+                    values[attr] = v
+                continue
+            before = len(problems)
+            _check(problems, f"{table}.{key}", v, _KIND[attr])
+            if len(problems) == before:
+                values[attr] = int(v) if attr == "horizon_months" else float(v)
+
+    rates = data.get("discount_rates")
+    if rates is not None:
+        if not isinstance(rates, dict):
+            problems.append("[discount_rates] must be a table keyed by bucket (PDP, DUC, PUD)")
+        else:
+            merged = _default_rates()
+            for code, rate in rates.items():
+                if code not in BUCKETS:
+                    problems.append(f"[discount_rates] has unknown bucket {code!r}; allowed: {list(BUCKETS)}")
+                    continue
+                explicit.add(f"discount_rates.{code}")
+                before = len(problems)
+                _check(problems, f"discount_rates.{code}", rate, "open_unit")
+                if len(problems) == before:
+                    merged[code] = float(rate)
+            values["discount_rates"] = merged
+
+    if problems:
+        raise AssumptionsError(problems)
+    return Assumptions(**values, explicit=frozenset(explicit))
+
+
+def load_assumptions(path: str | Path) -> Assumptions:
+    """Read and validate an assumptions TOML file."""
+    p = Path(path)
+    try:
+        text = p.read_text(encoding="utf-8")
+    except OSError as e:
+        raise AssumptionsError([f"cannot read assumptions file {str(p)!r}: {e.strerror or e}"]) from e
+    return assumptions_from_text(text, source=str(p))
+
+
+def assumptions_from_text(text: str, *, source: str = "assumptions") -> Assumptions:
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        raise AssumptionsError([f"{source} is not valid TOML: {e}"]) from e
+    return parse_assumptions(data)
+
+
+def describe(a: Assumptions) -> list[tuple[str, str, object, str]]:
+    """The assumptions as ``(section, name, value, source)`` rows for printing
+    and for the README, ``source`` being 'file' or 'default'."""
+    def src(dotted: str) -> str:
+        return "file" if dotted in a.explicit else "default"
+
+    rows: list[tuple[str, str, object, str]] = [
+        ("price_deck", "type", a.price_deck_type, src("price_deck.type")),
+        ("price_deck", "oil_usd_bbl", a.oil_price, src("price_deck.oil_usd_bbl")),
+        ("price_deck", "gas_usd_mmbtu", a.gas_price, src("price_deck.gas_usd_mmbtu")),
+    ]
+    for (table, key), attr in _KEYS.items():
+        if table == "economics":
+            rows.append((table, key, getattr(a, attr), src(f"{table}.{key}")))
+    for code in BUCKETS:
+        rows.append(("discount_rates", code, a.discount_rates[code], src(f"discount_rates.{code}")))
+    return rows

crudecode/engine/consequences.py

@@ -0,0 +1,106 @@
+"""Consequence math for the forecast check. Pure: no files, no network.
+
+The check speaks in future volumes, never in fit quality (there is no fit).
+The functions here turn an asserted curve into the numbers the sanity loop
+interrogates: implied next-12 / next-24 cum against trailing actuals,
+effective annual decline at years 1 and 5, EUR (cum-to-date plus forecast
+remainder), EUR/ft, and where the terminal switch lands.
+
+Conventions (shared with the economics schedule):
+
+- t is months since the anchor; q(0) == qi, the anchor-month rate.
+- For a producing well the anchor month itself is history: forecast volumes
+  are t = 1..N, so next-12 means sum q(1..12).
+- For a not-yet-producing well the anchor IS the asserted online month: the
+  online month produces q(0), volumes are t = 0..N-1, matching where the
+  economics schedule places it.
+- EUR = recorded cum through the anchor + the forecast remainder over the
+  horizon. When the anchor sits before the last reported month (contaminated
+  recent data), actuals after the anchor are REPLACED by the forecast, never
+  double-counted.
+- The check runs on calendar months from the anchor; the economics schedule
+  starts at the valuation origin. When an anchor trails the origin the two views
+  differ by construction: the check answers "what does this curve say from
+  where it starts", not "what lands in this deal's month 1". A DUC anchored
+  +36 months also sees its economics contribution truncated at the deal
+  horizon while the check EUR is curve-life; that asymmetry is intentional.
+"""
+from __future__ import annotations
+
+from datetime import date
+
+import numpy as np
+from dateutil.relativedelta import relativedelta
+
+from crudecode.engine.curves import DeclineCurve, curve_rate
+
+
+def effective_annual_decline(curve: DeclineCurve, *, year: int) -> float | None:
+    """Effective (not nominal) annual decline over forecast year ``year``:
+    ``(q_start - q_end) / q_start`` across that year's 12 months. ``None``
+    when the starting rate is zero (a zero curve has no decline)."""
+    if year < 1:
+        raise ValueError(f"year must be >= 1; got {year}")
+    q_start = curve_rate(curve, float(12 * (year - 1)))
+    q_end = curve_rate(curve, float(12 * year))
+    if q_start <= 0.0:
+        return None
+    return (q_start - q_end) / q_start
+
+
+def stream_consequences(
+    curve: DeclineCurve,
+    *,
+    anchor: date,
+    horizon_months: int,
+    trailing_12_actual: float | None,
+    cum_to_date: float,
+    lateral_ft: float | None,
+    anchor_is_future: bool = False,
+) -> dict:
+    """The check's numbers for one stream, per the module conventions.
+
+    ``anchor_is_future`` marks a not-yet-producing well: its forecast window
+    starts at t=0 (the online month) instead of t=1, and there are no trailing
+    actuals to compare against.
+    """
+    if horizon_months <= 0:
+        raise ValueError(f"horizon_months must be positive; got {horizon_months}")
+    anchor = anchor.replace(day=1)
+    t0 = 0 if anchor_is_future else 1
+    t = np.arange(t0, t0 + horizon_months, dtype=float)
+    rates = np.asarray(curve_rate(curve, t), dtype=float)
+
+    next_12 = float(rates[:12].sum()) if horizon_months >= 12 else None
+    next_24 = float(rates[:24].sum()) if horizon_months >= 24 else None
+    remaining = float(rates.sum())
+    eur = cum_to_date + remaining
+
+    ratio = None
+    if next_12 is not None and trailing_12_actual is not None and trailing_12_actual > 0.0:
+        ratio = next_12 / trailing_12_actual
+
+    yr1 = effective_annual_decline(curve, year=1)
+    yr5 = effective_annual_decline(curve, year=5)
+
+    switch = curve.switch_month_from_peak
+    if np.isfinite(switch):
+        switch_date = anchor + relativedelta(months=int(round(switch)))
+        terminal = {"months_from_anchor": round(float(switch), 1),
+                    "date": switch_date.strftime("%Y-%m")}
+    else:
+        terminal = {"months_from_anchor": None, "date": None}
+
+    return {
+        "next_12_cum": None if next_12 is None else round(next_12, 1),
+        "next_24_cum": None if next_24 is None else round(next_24, 1),
+        "trailing_12_actual": None if trailing_12_actual is None else round(trailing_12_actual, 1),
+        "next12_over_trailing12": None if ratio is None else round(ratio, 3),
+        "eff_annual_decline_yr1": None if yr1 is None else round(yr1, 4),
+        "eff_annual_decline_yr5": None if yr5 is None else round(yr5, 4),
+        "eur": round(eur, 1),
+        "cum_to_date": round(cum_to_date, 1),
+        "eur_remaining": round(remaining, 1),
+        "eur_per_ft": None if not lateral_ft else round(eur / float(lateral_ft), 2),
+        "terminal_switch": terminal,
+    }