crudecode-valuation 0.2.0__py3-none-any.whl

crude_valuation/README.md

@@ -0,0 +1,146 @@
+# crude_valuation
+
+In-package cookbook the inner valuation_agent reads at runtime. Walks
+through the three-phase workflow and the diagnostic helpers.
+
+The package has two subsystems:
+
+- **`forecast/`** — produce `(forecasts_oil, forecasts_gas)`. Three
+  diagnostic helpers (`cohort_summary`, `fit_quality`,
+  `target_vs_cohort`) let you inspect the cohort and target wells before
+  committing to forecast parameters.
+- **`econ/`** — turn forecasts into money. Revenue → cashflow → NPV.
+
+Forecast and econ are deliberately separate. The forecast step's
+deliverable is `(forecasts_oil, forecasts_gas)` — that tuple is the input
+to the econ step. There is no fused entry point.
+
+## Imports (flat)
+
+```python
+from crude_valuation import (
+    # Forecast types and primitives
+    DeclineCurve, Forecast, ForecastProvenance,
+    fit_curve, percentile_curves, blend_curves, curve_rate,
+    project, aggregate,
+    peek_well, load_production, find_analogs,
+    # Diagnostics
+    cohort_summary, fit_quality, target_vs_cohort,
+    CohortSummary, FitQuality, TargetComparison, ParamStats,
+    # Econ
+    compute_gross_revenue, compute_net_cashflow, npv,
+    # Briefing assembly
+    build_minimal_briefing,
+)
+```
+
+## Workflow — EXPLORE → DECIDE → EXECUTE
+
+Every `/tmp/valuation.py` you write is structured into three phases marked
+by comment headers. You think like a petroleum engineer: inspect, decide,
+execute. Document the calls you made in plain English so a reader of the
+briefing can audit them.
+
+### EXPLORE — load data, fit analogs, print diagnostics
+
+```python
+import numpy as np
+from crude_valuation import (
+    load_production, find_analogs, fit_curve, peek_well,
+    percentile_curves,
+    cohort_summary, fit_quality, target_vs_cohort,
+)
+
+prod = load_production(WELL_APIS, run_sql)
+analog_apis = find_analogs(ANALOG_FILTER, run_sql, exclude=WELL_APIS)
+
+analog_curves = []
+for a in analog_apis:
+    try:
+        analog_prod = load_production([a], run_sql)
+        q = np.array(analog_prod["oil_bbl"])
+        months = np.arange(len(q), dtype=float)
+        meta = peek_well(a, run_sql)
+        analog_curves.append(
+            fit_curve(months, q, stream="oil", lateral_norm_ft=meta.lateral_ft, b_fixed=0.8)
+        )
+    except ValueError:
+        continue   # skip thin / un-fittable analogs
+
+print(cohort_summary(analog_curves))    # AGENT READS THIS
+cohort_median = percentile_curves(analog_curves, pct=0.5, norm_to_lateral_ft=10_000.0)
+
+for api in WELL_APIS:
+    meta = peek_well(api, run_sql)
+    target_prod = load_production([api], run_sql)
+    target_q = np.array(target_prod["oil_bbl"])
+    target_months = np.arange(len(target_q), dtype=float)
+    print(api, target_vs_cohort(cohort_median, target_months, target_q, meta.lateral_ft))
+```
+
+For PDP candidates (wells you'll fit on their own history), also print
+`fit_quality(own_curve, months, q)` so you can gate fits that rode the
+b bound.
+
+### DECIDE — write a comment block per well
+
+```python
+# === DECIDE ===
+# Cohort: 15 analogs after dropping 3 b-upper-bound riders. b median 0.92
+# (IQR 0.31). qi median 14,200 bbl/mo at 9,800 ft lateral.
+#
+# Target 42-329-12345 (Wolfcamp A, 9,400 ft):
+#   36 months observed, qi_ratio 1.04 -> in line with cohort
+#   Choice: pdp; fit own decline with b=0.9 (cohort median, dropped outliers)
+#
+# Target 42-329-12999 (PERMITTED, 10,200 ft):
+#   no history; planned spud 2026-08
+#   Choice: pure_analog with cohort curve at target lateral
+```
+
+### EXECUTE — inline the per-well calls, then run econ
+
+No router constants. No `THIN_HISTORY_THRESHOLD`. No `B_FIXED`. Each
+well's strategy is whatever the DECIDE block said.
+
+```python
+forecasts_oil, forecasts_gas = [], []
+for api, choice in CHOICES.items():
+    if choice["strategy"] == "pdp":
+        forecasts_oil.append(_build_pdp(api, b=choice["b"], stream="oil", ...))
+    elif choice["strategy"] == "thin_blend":
+        forecasts_oil.append(_build_thin(api, cohort_median_oil, ...))
+    else:  # pure_analog
+        forecasts_oil.append(_build_pure_analog(api, cohort_median_oil, ...))
+    # same for gas
+
+revenue = compute_gross_revenue(forecasts_oil, forecasts_gas, price_deck=...)
+cashflow = compute_net_cashflow(revenue, interest_type=INTEREST_TYPE, ...)
+npv_dict = npv(cashflow, discount_rates=[0.08, 0.10, 0.12, 0.15])
+
+spec = build_minimal_briefing(headline=..., commentary=..., npv=npv_dict, ...)
+persist(spec, persist_url="$persist_url")
+```
+
+Commentary must reference at least one concrete diagnostic you looked at
+(e.g. "cohort of 14 analogs, b median 0.92 with IQR 0.31; target's first
+4 months at 71% of cohort qi suggests below-average completion").
+
+## Playbooks
+
+`crude_valuation/forecast/examples/` ships annotated playbooks. Today
+only `forecast_mixed.py` is in the new playbook form; the other two are
+still recipe-style and will be migrated.
+
+## Diagnostic helpers in detail
+
+- `cohort_summary(curves)` — distribution stats per fitted parameter
+  (qi, di, b, terminal, lateral). Plus `notes` flagging fits that rode
+  the b bound.
+- `fit_quality(curve, months, q)` — R^2, RMSE, bound-riding flags, max
+  residual %, early/late signed-% bias windows for a single fit.
+- `target_vs_cohort(cohort, target_months, target_q, target_lateral_ft)` —
+  qi_ratio of target to cohort, peak detection, per-month signed-%
+  residual vs cohort placed at target lateral.
+
+None of these decide anything. You read them and choose.

crude_valuation/__init__.py

@@ -0,0 +1,51 @@
+"""crude-valuation — valuation toolkit for the inner valuation_agent.
+
+Wraps crude_analyst (the base briefing platform) and adds domain math.
+The agent only ever imports from crude_valuation; crude_analyst is invisible.
+"""
+from crude_analyst import *  # noqa: F401, F403
+
+# Econ subsystem
+from crude_valuation.econ import (  # noqa: F401
+    compute_gross_revenue,
+    compute_net_cashflow,
+    npv,
+)
+
+# Shared utilities
+from crude_valuation.compose import build_minimal_briefing  # noqa: F401
+
+# Forecast subsystem — flat re-exports for the agent
+from crude_valuation.forecast import (  # noqa: F401
+    # Types
+    CohortSummary,
+    CurveProvenance,
+    DeclineCurve,
+    FitQuality,
+    Forecast,
+    ForecastProvenance,
+    ParamStats,
+    TargetComparison,
+    WellMeta,
+    # Primitives
+    fit_curve,
+    percentile_curves,
+    blend_curves,
+    curve_rate,
+    # Diagnostics
+    cohort_summary,
+    fit_quality,
+    target_vs_cohort,
+    # Projection + aggregation
+    project,
+    aggregate,
+    # DB helpers
+    peek_well,
+    load_production,
+    load_well_status,
+    resolve_asset_list,
+    find_analogs,
+    # Errors
+    AnalogError,
+    WellsError,
+)

crude_valuation/casefile.py

@@ -0,0 +1,104 @@
+"""Case file parsing for the valuation agent.
+
+Validates the JSON contract the MCP tool sends, returns a typed CaseFile
+the rest of the package can read without re-checking shapes.
+"""
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class CaseFileError(ValueError):
+    """Raised when the case file fails schema validation."""
+
+
+@dataclass
+class CaseFile:
+    interest_type: str                              # "wi" | "minerals"
+    interest: dict                                  # {wi_pct, nri_pct} or {decimal}
+    asset_list: dict                                # {well_apis: [...]} XOR {filter_sql: "..."}
+    economics_overrides: dict = field(default_factory=dict)
+    transcript: list = field(default_factory=list)
+    queries_run: list = field(default_factory=list)
+    handoff: str = ""
+    source_documents: list = field(default_factory=list)
+
+
+def parse_case_file(body: dict) -> CaseFile:
+    """Validate + parse the case file body. Raises CaseFileError on any failure."""
+    if not isinstance(body, dict):
+        raise CaseFileError(f"case file must be an object, got {type(body).__name__}")
+
+    interest_type = body.get("interest_type")
+    if interest_type not in ("wi", "minerals"):
+        raise CaseFileError(
+            f"interest_type must be 'wi' or 'minerals', got {interest_type!r}"
+        )
+
+    interest = body.get("interest")
+    if not isinstance(interest, dict):
+        raise CaseFileError("interest must be an object")
+    if interest_type == "wi":
+        for k in ("wi_pct", "nri_pct"):
+            if k not in interest:
+                raise CaseFileError(f"interest.{k} is required for interest_type='wi'")
+            v = interest[k]
+            if not isinstance(v, (int, float)) or not (0.0 <= v <= 1.0):
+                raise CaseFileError(f"interest.{k} must be in [0, 1], got {v!r}")
+    else:  # minerals
+        if "decimal" not in interest:
+            raise CaseFileError("interest.decimal is required for interest_type='minerals'")
+        v = interest["decimal"]
+        if not isinstance(v, (int, float)) or not (0.0 <= v <= 1.0):
+            raise CaseFileError(f"interest.decimal must be in [0, 1], got {v!r}")
+
+    asset_list = body.get("asset_list")
+    if not isinstance(asset_list, dict):
+        raise CaseFileError("asset_list must be an object")
+    has_apis = bool(asset_list.get("well_apis"))
+    has_sql = bool(asset_list.get("filter_sql"))
+    if has_apis and has_sql:
+        raise CaseFileError("asset_list must have exactly one of well_apis or filter_sql, not both")
+    if not has_apis and not has_sql:
+        raise CaseFileError("asset_list must have exactly one of well_apis or filter_sql")
+    if has_apis and not all(isinstance(a, str) for a in asset_list["well_apis"]):
+        raise CaseFileError("asset_list.well_apis must be a list of strings")
+    if has_sql and not isinstance(asset_list["filter_sql"], str):
+        raise CaseFileError("asset_list.filter_sql must be a string")
+
+    handoff = body.get("handoff")
+    if not isinstance(handoff, str) or not handoff.strip():
+        raise CaseFileError("handoff is required and must be a non-empty string")
+
+    transcript = body.get("transcript")
+    if not isinstance(transcript, list) or len(transcript) == 0:
+        raise CaseFileError("transcript is required and must be a non-empty list")
+    for i, turn in enumerate(transcript):
+        if not isinstance(turn, dict):
+            raise CaseFileError(f"transcript[{i}] must be an object")
+        if turn.get("role") not in ("user", "assistant"):
+            raise CaseFileError(f"transcript[{i}].role must be 'user' or 'assistant'")
+        if not isinstance(turn.get("content"), str):
+            raise CaseFileError(f"transcript[{i}].content must be a string")
+
+    queries_run = body.get("queries_run", [])
+    if not isinstance(queries_run, list):
+        raise CaseFileError("queries_run must be a list")
+
+    economics_overrides = body.get("economics_overrides", {}) or {}
+    if not isinstance(economics_overrides, dict):
+        raise CaseFileError("economics_overrides must be an object")
+
+    source_documents = body.get("source_documents", []) or []
+    if not isinstance(source_documents, list):
+        raise CaseFileError("source_documents must be a list")
+
+    return CaseFile(
+        interest_type=interest_type,
+        interest=interest,
+        asset_list=asset_list,
+        economics_overrides=economics_overrides,
+        transcript=transcript,
+        queries_run=queries_run,
+        handoff=handoff.strip(),
+        source_documents=source_documents,
+    )

crude_valuation/compose.py

@@ -0,0 +1,79 @@
+"""Build a minimal Slice-1 briefing spec from valuation results.
+
+Slice 1 is PV-only and commentary-only:
+
+- PV-only — no IRR, no payout, no MOIC, no sensitivity. Those land in a later
+  slice; this slice ships discount-rate NPV values and the methodology footer.
+- Commentary-only — no callout widget. The base `callout` is designed to render
+  a value from a SQL row, not a Python-side literal; using it for a static
+  headline NPV would require a crude_analyst widget change we're deferring.
+  Instead the headline NPV lives in the commentary text body.
+"""
+import math
+from crude_analyst import briefing, section, commentary
+
+
+def _fmt_money(x: float) -> str:
+    """Render dollar values as $X.YM, $XK, etc. Negative shown as -$X.YM."""
+    if not math.isfinite(x):
+        return "n/a"
+    sign = "-" if x < 0 else ""
+    a = abs(x)
+    if a >= 1e9:
+        return f"{sign}${a/1e9:.2f}B"
+    if a >= 1e6:
+        return f"{sign}${a/1e6:.2f}M"
+    if a >= 1e3:
+        return f"{sign}${a/1e3:.1f}K"
+    return f"{sign}${a:.0f}"
+
+
+def _headline_rate(npv_by_rate: dict[float, float]) -> float:
+    """Pick the headline discount rate — PV10 if present, else the lowest rate."""
+    if 0.10 in npv_by_rate:
+        return 0.10
+    return min(npv_by_rate.keys())
+
+
+def build_minimal_briefing(
+    *,
+    npv_by_rate: dict[float, float],
+    n_wells: int,
+    interest_type: str,
+    methodology_notes: str,
+) -> dict:
+    """Assemble the Slice 1 briefing: one commentary widget with PV results."""
+    headline_rate = _headline_rate(npv_by_rate)
+    headline_npv = npv_by_rate[headline_rate]
+    headline_label = f"PV{int(headline_rate*100)}"
+    interest_label = "minerals" if interest_type == "minerals" else "working-interest"
+
+    lines = [
+        f"{interest_label.capitalize()} valuation across {n_wells} producing well(s).",
+        f"{headline_label}: {_fmt_money(headline_npv)}.",
+    ]
+    if len(npv_by_rate) > 1:
+        other = ", ".join(
+            f"PV{int(r*100)}: {_fmt_money(v)}"
+            for r, v in sorted(npv_by_rate.items())
+            if r != headline_rate
+        )
+        lines.append(f"Other rates — {other}.")
+    lines.append("")
+    lines.append(f"Methodology: {methodology_notes}")
+
+    spec = briefing(
+        headline=f"{headline_label} {_fmt_money(headline_npv)} on {n_wells} {interest_label} well(s).",
+        tldr=f"{n_wells}-well {interest_type} valuation; headline {headline_label} = {_fmt_money(headline_npv)}.",
+        sections=[
+            section(
+                label="01 · Result",
+                layout="full-width",
+                widgets=[commentary(text="\n".join(lines))],
+            ),
+        ],
+    )
+    spec["headline_npv"] = {
+        str(round(rate * 100)): value for rate, value in npv_by_rate.items()
+    }
+    return spec

crude_valuation/econ/__init__.py

@@ -0,0 +1,4 @@
+"""Economics: revenue → cashflow → NPV."""
+from crude_valuation.econ.revenue import compute_gross_revenue  # noqa: F401
+from crude_valuation.econ.cashflow import compute_net_cashflow  # noqa: F401
+from crude_valuation.econ.npv import npv  # noqa: F401

crude_valuation/econ/cashflow.py

@@ -0,0 +1,75 @@
+"""Cashflow layer: branches on interest_type.
+
+For all deals:    net_of_deducts = revenue × (1 - tax_pct) × (1 - gpt_pct)
+For minerals:     cashflow = net_of_deducts × decimal
+For WI:           cashflow = net_of_deducts × NRI − (opex + capex + p_and_a) × WI%
+
+Defaults applied when economics fields are missing:
+    tax_pct = 0.075, gpt_pct = 0.05, opex = $3000/well/month,
+    p_and_a = $75000/well at end of stream.
+"""
+import numpy as np
+
+
+_DEFAULTS = {
+    "tax_pct": 0.075,
+    "gpt_pct": 0.05,
+    "opex_per_well_per_month_usd": 3000.0,
+    "p_and_a_per_well_usd": 75000.0,
+}
+
+
+def _resolve(economics: dict, key: str) -> float:
+    return float(economics.get(key, _DEFAULTS[key]))
+
+
+def compute_net_cashflow(
+    *,
+    revenue_monthly: np.ndarray,
+    interest_type: str,
+    interest: dict,
+    economics: dict,
+    n_wells: int,
+    oil_bbl: np.ndarray | None = None,
+) -> np.ndarray:
+    """Apply interest_type branch and return monthly net cashflow.
+
+    `oil_bbl` is required when `economics["opex_per_bbl_usd"]` is set (the
+    per-bbl opex code path); otherwise ignored.
+    """
+    revenue_monthly = np.asarray(revenue_monthly, dtype=float)
+
+    tax_pct = _resolve(economics, "tax_pct")
+    gpt_pct = _resolve(economics, "gpt_pct")
+    net_of_deducts = revenue_monthly * (1.0 - tax_pct) * (1.0 - gpt_pct)
+
+    if interest_type == "minerals":
+        return net_of_deducts * float(interest["decimal"])
+
+    # WI branch
+    wi_pct = float(interest["wi_pct"])
+    nri_pct = float(interest["nri_pct"])
+    revenue_net = net_of_deducts * nri_pct
+
+    n_months = len(revenue_monthly)
+
+    # Opex: either per-bbl or per-well-per-month (caller picks at most one)
+    if "opex_per_bbl_usd" in economics:
+        if oil_bbl is None:
+            raise ValueError("oil_bbl is required when economics.opex_per_bbl_usd is set")
+        opex_monthly = float(economics["opex_per_bbl_usd"]) * np.asarray(oil_bbl, dtype=float)
+    else:
+        per_well = _resolve(economics, "opex_per_well_per_month_usd")
+        opex_monthly = np.full(n_months, per_well * n_wells, dtype=float)
+
+    # P&A — one-time at end of stream
+    p_and_a_per_well = _resolve(economics, "p_and_a_per_well_usd")
+    p_and_a = np.zeros(n_months, dtype=float)
+    if n_months > 0:
+        p_and_a[-1] = p_and_a_per_well * n_wells
+
+    # CapEx — unused in Slice 1 (non-producing wells rejected at run time)
+    capex = np.zeros(n_months, dtype=float)
+
+    cost_monthly = opex_monthly + capex + p_and_a
+    return revenue_net - cost_monthly * wi_pct

crude_valuation/econ/npv.py

@@ -0,0 +1,14 @@
+"""Monthly NPV — pure numpy. Slice 1 ships PV only; IRR / payout / MOIC deferred."""
+import numpy as np
+
+
+def npv(cashflow_monthly: np.ndarray, rate: float) -> float:
+    """Discount a monthly cashflow stream at annual nominal rate.
+
+    Month 0 is undiscounted. `rate` is annual; converted to monthly internally.
+    """
+    cf = np.asarray(cashflow_monthly, dtype=float)
+    monthly_rate = rate / 12.0
+    n = len(cf)
+    discount = 1.0 / np.power(1.0 + monthly_rate, np.arange(n, dtype=float))
+    return float(np.sum(cf * discount))

crude_valuation/econ/revenue.py

@@ -0,0 +1,39 @@
+"""Revenue layer: oil + gas volumes → gross revenue per month."""
+import numpy as np
+
+
+_DEFAULT_OIL_USD = 80.0
+_DEFAULT_GAS_USD = 3.0
+
+
+def compute_gross_revenue(
+    oil_bbl: np.ndarray,
+    gas_mcf: np.ndarray,
+    price_deck: dict | None,
+    differential: dict | None,
+) -> np.ndarray:
+    """Apply price × volumes to produce monthly gross revenue.
+
+    Slice 1: only `price_deck.type == "flat"` is supported. `nymex_strip` and
+    `escalated` raise NotImplementedError until a later slice.
+
+    1 MCF ≈ 1 MMBtu assumption in Slice 1 (real BTU content varies by basin,
+    deferred).
+    """
+    if price_deck is None:
+        oil_price = _DEFAULT_OIL_USD
+        gas_price = _DEFAULT_GAS_USD
+    else:
+        ptype = price_deck.get("type")
+        if ptype != "flat":
+            raise NotImplementedError(
+                f"price_deck type {ptype!r} not supported in Slice 1 (only 'flat')"
+            )
+        oil_price = float(price_deck.get("oil_usd_bbl", _DEFAULT_OIL_USD))
+        gas_price = float(price_deck.get("gas_usd_mmbtu", _DEFAULT_GAS_USD))
+
+    if differential is not None:
+        oil_price += float(differential.get("oil_usd_bbl", 0.0))
+        gas_price += float(differential.get("gas_usd_mmbtu", 0.0))
+
+    return np.asarray(oil_bbl, dtype=float) * oil_price + np.asarray(gas_mcf, dtype=float) * gas_price

crude_valuation/forecast/README.md

@@ -0,0 +1,142 @@
+# crude_valuation.forecast
+
+Build per-well `Forecast`s from production history, analog cohorts, or both.
+This subpackage's deliverable is exactly:
+
+```python
+forecasts_oil: list[Forecast]
+forecasts_gas: list[Forecast]
+```
+
+Economics lives in `crude_valuation.econ` and consumes the tuple above.
+
+## Conceptual model
+
+Two value types do disjoint jobs:
+
+- `DeclineCurve` — pure decline shape. Carries `qi_peak`, `di`, `b`,
+  terminal decline, switch month, the stream, and the lateral the curve
+  is normalized to. No calendar time. No well identity. A curve fit from
+  Well A can be applied to many other wells.
+- `Forecast` — a `DeclineCurve` placed against a target well. Carries
+  `peak_date` (where `qi_peak` applies in calendar time), `start_date`
+  (where the projection's month-0 sits), `lateral_scale`, and provenance.
+
+Together `peak_date` and `start_date` pin down "how far past peak is this
+projection starting." The peak-vs-current bug from Phase 1.5 — anchoring
+projection at peak rate but labeling it as "today" — is structurally
+impossible because `project` always indexes from `peak_date`, and both
+fields are required.
+
+## Three strategies, one shape
+
+Every forecast goes through three steps:
+
+1. **Build a curve.** Either `fit_curve(months, q, ...)` for own
+   production, or `percentile_curves([curve, ...], ...)` for an analog
+   cohort, or `blend_curves(qi_from=..., decline_from=...)` for the
+   thin-history case.
+2. **Wrap in a Forecast** with `peak_date`, `start_date`, and
+   `lateral_scale`.
+3. **`aggregate(forecasts, horizon_months=...)`** to get the per-stream
+   monthly volume.
+
+| Strategy | Curve source | peak_date | start_date |
+|---|---|---|---|
+| PDP (own history) | `fit_curve` on own prod | prod_date at argmax(q) | last prod_date |
+| Pure analog (PERMITTED/DUC) | `percentile_curves` on N analogs | planned first-prod date | planned first-prod date |
+| Thin blend | `blend_curves`(own qi, cohort decline) | prod_date at argmax(own q) | last prod_date |
+
+## Templates
+
+Three runnable templates in `examples/`, organized by strategy:
+
+- `forecast_historical.py` — all wells have own history (PDP)
+- `forecast_analogs.py` — no wells have own history (PERMITTED/DUC)
+- `forecast_mixed.py` — mix of PDP / thin / not-yet-drilled
+
+Each template exposes `build(run_sql) -> (forecasts_oil, forecasts_gas)`.
+Edit `WELL_APIS` (and `ANALOG_FILTER` where applicable) before running.
+
+## Atomic snippets
+
+### Fit one well's curve
+```python
+from crude_valuation.forecast import fit_curve, peek_well, load_production
+import numpy as np
+
+meta = peek_well(api, run_sql)
+prod = load_production([api], run_sql)
+months = np.arange(len(prod["months"]), dtype=float)
+q = np.array(prod["oil_bbl"])
+curve = fit_curve(months, q, stream="oil", lateral_norm_ft=meta.lateral_ft)
+```
+
+### Build a cohort curve
+```python
+from crude_valuation.forecast import (
+    find_analogs, fit_curve, load_production, peek_well, percentile_curves,
+)
+import numpy as np
+
+analog_apis = find_analogs("basin = 'Permian' AND ...", run_sql, exclude=[target])
+curves = []
+for a in analog_apis:
+    meta = peek_well(a, run_sql)
+    prod = load_production([a], run_sql)
+    q = np.array(prod["oil_bbl"])
+    months = np.arange(len(prod["months"]), dtype=float)
+    try:
+        curves.append(fit_curve(months, q, stream="oil", lateral_norm_ft=meta.lateral_ft))
+    except ValueError:
+        pass  # skip thin-history analogs
+cohort = percentile_curves(curves, pct=0.5, norm_to_lateral_ft=10_000.0)
+```
+
+### Place a PDP well
+```python
+from datetime import date
+from crude_valuation.forecast import Forecast, ForecastProvenance
+
+# (continuing from the fit_curve snippet above — `prod` and `curve` in scope)
+peak_idx = int(np.argmax(q))
+fc = Forecast(
+    curve=curve,
+    peak_date=date.fromisoformat(str(prod["months"][peak_idx])),
+    start_date=date.fromisoformat(str(prod["months"][-1])),  # last reported month
+    lateral_scale=1.0,
+    provenance=ForecastProvenance(target_well_api=api, strategy="pdp"),
+)
+```
+
+### Place a synthetic well
+```python
+from datetime import date
+from crude_valuation.forecast import Forecast, ForecastProvenance
+
+fc = Forecast(
+    curve=cohort,
+    peak_date=meta.planned_first_prod_date,
+    start_date=meta.planned_first_prod_date,
+    lateral_scale=(meta.lateral_ft or 10_000.0) / cohort.lateral_norm_ft,
+    provenance=ForecastProvenance(target_well_api=api, strategy="pure_analog"),
+)
+```
+
+### Blend for a thin-history well
+```python
+from crude_valuation.forecast import blend_curves
+blended = blend_curves(qi_from=own_curve, decline_from=cohort_curve)
+```
+
+## Common mistakes
+
+- Setting `peak_date == start_date` for a PDP well. That throws away the
+  decline history — the projection starts at peak rate. For PDP, peak_date
+  is the historical peak month and start_date is `last_prod`.
+- Mixing analog curves at different laterals without normalizing. Use
+  `percentile_curves(..., norm_to_lateral_ft=X)` to put them on the same
+  basis before percentiling.
+- Calling `fit_curve` on a well with only a few months of data. It will
+  raise. Route thin-history wells through `blend_curves(qi_from=own_fit,
+  decline_from=cohort_curve)` (see `examples/forecast_mixed.py`).