crudecode 0.1.0a1__tar.gz

crudecode-0.1.0a1/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/

crudecode-0.1.0a1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Crude Code
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

crudecode-0.1.0a1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.5
+Name: crudecode
+Version: 0.1.0a1
+Summary: The method for oil & gas analysis with LLMs: guides, decline-curve forecast checks and well-level valuation economics. Pairs with the Crude Code MCP data server.
+Project-URL: Homepage, https://crudecode.dev
+Author: Crude Code
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: decline curve,llm,mcp,npv,oil and gas,valuation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: python-dateutil>=2.8
+Description-Content-Type: text/markdown
+
+# crudecode
+
+The method half of Crude Code. The [Crude Code MCP server](https://crudecode.dev)
+serves US well data from state filings; this package is what an LLM (any LLM
+with a Python sandbox) uses to turn that data into forecasts and valuations:
+guides, code and default assumptions.
+
+```bash
+pip install --break-system-packages crudecode==0.1.0a1
+crudecode guide            # start here
+```
+
+* `crudecode guide [name]` prints a guide (`forecasting`, `valuation`, `schema`, `example`).
+* `crudecode forecast check deal.json` validates asserted decline curves and echoes what they imply.
+* `crudecode assumptions init assumptions.toml` writes the default economic assumptions.
+* `crudecode value deal.json --assumptions assumptions.toml --out out/` runs the economics.
+
+The kit is standalone: two dependencies (numpy, python-dateutil), no network
+calls, plain CSV/JSON/Markdown outputs. Apache-2.0.
+
+Version 0.1.0a1 covers the valuation workflow on a flat price deck. A strip
+(futures) deck is not supported yet.

crudecode-0.1.0a1/README.md

@@ -0,0 +1,22 @@
+# crudecode
+
+The method half of Crude Code. The [Crude Code MCP server](https://crudecode.dev)
+serves US well data from state filings; this package is what an LLM (any LLM
+with a Python sandbox) uses to turn that data into forecasts and valuations:
+guides, code and default assumptions.
+
+```bash
+pip install --break-system-packages crudecode==0.1.0a1
+crudecode guide            # start here
+```
+
+* `crudecode guide [name]` prints a guide (`forecasting`, `valuation`, `schema`, `example`).
+* `crudecode forecast check deal.json` validates asserted decline curves and echoes what they imply.
+* `crudecode assumptions init assumptions.toml` writes the default economic assumptions.
+* `crudecode value deal.json --assumptions assumptions.toml --out out/` runs the economics.
+
+The kit is standalone: two dependencies (numpy, python-dateutil), no network
+calls, plain CSV/JSON/Markdown outputs. Apache-2.0.
+
+Version 0.1.0a1 covers the valuation workflow on a flat price deck. A strip
+(futures) deck is not supported yet.

crudecode-0.1.0a1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crudecode"
+version = "0.1.0a1"
+description = "The method for oil & gas analysis with LLMs: guides, decline-curve forecast checks and well-level valuation economics. Pairs with the Crude Code MCP data server."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Crude Code" }]
+keywords = ["oil and gas", "decline curve", "valuation", "npv", "llm", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# Runtime dependencies are exactly these two. The kit makes no network calls.
+dependencies = [
+    "numpy>=1.26",
+    "python-dateutil>=2.8",
+]
+
+[project.scripts]
+crudecode = "crudecode.cli:main"
+
+[project.urls]
+Homepage = "https://crudecode.dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crudecode"]
+
+# The sdist carries the kit's own tests. The parity tests compare against the
+# crude-code repo's engine and a database, so they stay in the repo.
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "LICENSE", "README.md", "pyproject.toml"]
+exclude = ["tests/parity_*.py", "tests/test_parity_*.py", "tests/test_drift.py"]
+
+# Tests run from the checkout without installing: `src` for the kit, `..` (the
+# crude-code repo root) only for the parity tests, which import the repo's
+# ad/valuation engine and skip themselves when it is not there.
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", ".."]
+markers = ["db: needs a live database (CC_WELLS_DB_URL or TASK_DB_URL); skipped without one"]

crudecode-0.1.0a1/src/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-0.1.0a1/src/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-0.1.0a1/src/crudecode/__main__.py

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

crudecode-0.1.0a1/src/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-0.1.0a1/src/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."""