crudecode-valuation 0.2.0__tar.gz

crudecode_valuation-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+.env
+.venv/
+sessions/
+logs/
+test_output/
+node_modules/
+__pycache__/
+.DS_Store
+*.pyc
+renderer/src/App.css
+renderer/src/assets/
+renderer/public/icons.svg
+repomix-*.txt
+managed_agents/.cache.json
+managed_agents/output/
+
+# Sibling/scratch dirs (not part of MCP server)
+.superpowers/
+planning_notes.md
+.worktrees/
+
+# Marker written by deploy.sh on the EC2 host — the SHA the running MCP
+# was last deployed against. Never committed.
+.last-mcp-deployed-sha

crudecode_valuation-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crude Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN THE
+SOFTWARE.

crudecode_valuation-0.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: crudecode-valuation
+Version: 0.2.0
+Summary: Oil & gas deal valuation toolkit for Crude Code inner agents — forecast, cashflow, NPV.
+Project-URL: Homepage, https://github.com/petroleumPythoneer/crudecode
+Author: Crude Code
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: crudecode-analyst>=0.5.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Description-Content-Type: text/markdown
+
+# crudecode-valuation
+
+Domain package for oil & gas deal valuation. Used by the `valuation_agent`
+inner agent in the EI Plugins MCP server.
+
+## What you get
+
+Two subsystems:
+
+- **`forecast`** — primitives + diagnostic helpers for building production
+  forecasts from analogs, own history, or blends.
+- **`econ`** — revenue → cashflow → NPV given a forecast tuple, interest
+  type, and economic assumptions.
+
+You compose them yourself. No fused `valuate()` entry point.
+
+## Agent workflow — EXPLORE → DECIDE → EXECUTE
+
+Every `/tmp/valuation.py` follows three phases marked by comment headers.
+
+### EXPLORE
+
+Load production, find analogs, fit them, and inspect with the three
+diagnostic helpers:
+
+```python
+from crude_valuation import (
+    load_production, find_analogs, fit_curve,
+    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))
+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))
+```
+
+### DECIDE
+
+A free-form comment block. Document the call per well in plain English:
+
+```python
+# === DECIDE ===
+# Cohort: 15 analogs after dropping 3 bound-riders. b median 0.92, IQR 0.31.
+# 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
+
+Build Forecasts inline per-well — no router, no module constants:
+
+```python
+# === EXECUTE ===
+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
+
+# Econ + persist
+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.
+
+## Playbooks
+
+`crude_valuation/forecast/examples/` ships annotated playbooks showing the
+EXPLORE → DECIDE → EXECUTE pattern end-to-end. Today only `forecast_mixed.py`
+is in the new playbook form; the other two are still recipe-style.
+
+## 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. The agent reads them and chooses.

crudecode_valuation-0.2.0/README.md

@@ -0,0 +1,117 @@
+# crudecode-valuation
+
+Domain package for oil & gas deal valuation. Used by the `valuation_agent`
+inner agent in the EI Plugins MCP server.
+
+## What you get
+
+Two subsystems:
+
+- **`forecast`** — primitives + diagnostic helpers for building production
+  forecasts from analogs, own history, or blends.
+- **`econ`** — revenue → cashflow → NPV given a forecast tuple, interest
+  type, and economic assumptions.
+
+You compose them yourself. No fused `valuate()` entry point.
+
+## Agent workflow — EXPLORE → DECIDE → EXECUTE
+
+Every `/tmp/valuation.py` follows three phases marked by comment headers.
+
+### EXPLORE
+
+Load production, find analogs, fit them, and inspect with the three
+diagnostic helpers:
+
+```python
+from crude_valuation import (
+    load_production, find_analogs, fit_curve,
+    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))
+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))
+```
+
+### DECIDE
+
+A free-form comment block. Document the call per well in plain English:
+
+```python
+# === DECIDE ===
+# Cohort: 15 analogs after dropping 3 bound-riders. b median 0.92, IQR 0.31.
+# 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
+
+Build Forecasts inline per-well — no router, no module constants:
+
+```python
+# === EXECUTE ===
+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
+
+# Econ + persist
+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.
+
+## Playbooks
+
+`crude_valuation/forecast/examples/` ships annotated playbooks showing the
+EXPLORE → DECIDE → EXECUTE pattern end-to-end. Today only `forecast_mixed.py`
+is in the new playbook form; the other two are still recipe-style.
+
+## 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. The agent reads them and chooses.

crudecode_valuation-0.2.0/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.

crudecode_valuation-0.2.0/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,
+)

crudecode_valuation-0.2.0/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,
+    )

crudecode_valuation-0.2.0/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

crudecode_valuation-0.2.0/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