fresh-vdyp 0.1.0__tar.gz

fresh_vdyp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UBC FRESH Lab
+
+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 OR OTHER DEALINGS IN THE
+SOFTWARE.

fresh_vdyp-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: fresh-vdyp
+Version: 0.1.0
+Summary: A public interoperability layer for the BC VDYP7 coefficient bundle, console runner, and yield curves.
+Author: UBC FRESH Lab
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.29
+Dynamic: license-file
+
+# fresh-vdyp
+
+A public, tested Python package for reading the BC VDYP7 coefficient and control
+bundle, wrapping the VDYP7Console runner, exposing typed yield curves, and
+validating incremental Python growth equations against the official console
+outputs.
+
+`fresh-vdyp` is an interoperability and reimplementation layer. It does not
+claim authorship of VDYP7 or BC government data. It exists so the model's
+plain-text coefficients, control files, and yield tables can be catalogued,
+queried, tested, and used by tools such as FEMIC without a GUI boundary.
+
+Repository: <https://github.com/UBC-FRESH/fresh-vdyp>
+
+## Status
+
+All phases P0-P7 are complete. `ROADMAP.md` lists the phases,
+and GitHub issues carry the live status. The first working milestone is the
+source inventory and coefficient catalog, not a full VDYP growth-model rewrite.
+
+## What this is
+
+- A parser and catalog for the VDYP7 `VDYP_CFG/coe` bundle.
+- A control-file map for `VDYP.CTR`, `VDYPBACK.CTR`, `.COE`, `.PRM`, and `.DAT`.
+- A runner and parser for `VDYP7Console` CSV yield tables.
+- A typed Python curve API and public data assets.
+- An incremental Python equation layer validated one family at a time.
+- A Typer CLI, FastAPI service, FRESH-style web UI, and bounded LLM assistant.
+- A package that FEMIC and other UBC-FRESH tools can depend on.
+
+## What this is not
+
+- A claim that UBC-FRESH invented VDYP7.
+- A byte-for-byte clone of the native VDYP7 binaries.
+- A substitute for measured field data or a complete growth-model validation.
+- A place to commit raw government model bundles or credentials.
+
+## Source and attribution
+
+Every extracted coefficient, control file, curve, and derived value records:
+
+```text
+source
+source version
+source file
+source SHA256
+extraction date
+citation
+```
+
+The original source remains the BC government's work. Reimplemented logic is
+labelled `reimplemented` and validated against console outputs where possible.
+
+## Plan
+
+Read these in order:
+
+1. [`notes/plan/0001-program-plan.md`](notes/plan/0001-program-plan.md)
+2. [`notes/plan/0002-data-provenance.md`](notes/plan/0002-data-provenance.md)
+3. [`notes/plan/0003-architecture.md`](notes/plan/0003-architecture.md)
+4. [`notes/plan/0004-validation-release.md`](notes/plan/0004-validation-release.md)
+5. [`notes/reference/vdyp-inventory.md`](notes/reference/vdyp-inventory.md)
+6. [`notes/reference/vdyp-model-map.md`](notes/reference/vdyp-model-map.md)
+
+## Quick start
+
+This seed is a planning repository. The Python package and data workflows land
+in Phase 2. Until then, the workflow gates are:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -r requirements-dev.txt
+python scripts/dashboard.py
+```
+
+## Bundle inspection
+
+Until the installable package lands, the first commands run from the repository:
+
+```bash
+export VDYP_CFG_DIR=/path/to/VDYP_CFG
+python scripts/fvdyp_cli.py bundle validate
+python scripts/fvdyp_cli.py bundle catalog
+python scripts/fvdyp_cli.py bundle extract --output-dir data/normalized
+```
+
+`validate` checks required files, control targets, and key lookups. `catalog`
+prints the family and row counts. `extract` writes normalized CSV files plus a
+provenance manifest; the CSV files stay under ignored `data/normalized/`.
+
+## Repository map
+
+| Path | Purpose |
+| --- | --- |
+| `AGENTS.md` | Operating contract for coding agents |
+| `HANDOFF.md` | First-read handoff note for a new session agent |
+| `ROADMAP.md` | Plan of record and issue tracker map |
+| `CHANGE_LOG.md` | Dated narrative of changes |
+| `notes/plan/` | Detailed program, data, architecture, and validation plans |
+| `notes/reference/` | VDYP inventory and coefficient-map facts |
+| `notes/adr/` | Accepted design decisions |
+| `docs/` | Sphinx RTFM surface |
+| `scripts/check_workflow.py` | Workflow validator |
+| `tests/` | pytest suite, including planning-surface checks |
+
+## License and citation
+
+Code is MIT licensed. Coefficient files and model outputs retain their original
+BC government attribution. Cite the source model and file, not only this package.

fresh_vdyp-0.1.0/README.md

@@ -0,0 +1,110 @@
+# fresh-vdyp
+
+A public, tested Python package for reading the BC VDYP7 coefficient and control
+bundle, wrapping the VDYP7Console runner, exposing typed yield curves, and
+validating incremental Python growth equations against the official console
+outputs.
+
+`fresh-vdyp` is an interoperability and reimplementation layer. It does not
+claim authorship of VDYP7 or BC government data. It exists so the model's
+plain-text coefficients, control files, and yield tables can be catalogued,
+queried, tested, and used by tools such as FEMIC without a GUI boundary.
+
+Repository: <https://github.com/UBC-FRESH/fresh-vdyp>
+
+## Status
+
+All phases P0-P7 are complete. `ROADMAP.md` lists the phases,
+and GitHub issues carry the live status. The first working milestone is the
+source inventory and coefficient catalog, not a full VDYP growth-model rewrite.
+
+## What this is
+
+- A parser and catalog for the VDYP7 `VDYP_CFG/coe` bundle.
+- A control-file map for `VDYP.CTR`, `VDYPBACK.CTR`, `.COE`, `.PRM`, and `.DAT`.
+- A runner and parser for `VDYP7Console` CSV yield tables.
+- A typed Python curve API and public data assets.
+- An incremental Python equation layer validated one family at a time.
+- A Typer CLI, FastAPI service, FRESH-style web UI, and bounded LLM assistant.
+- A package that FEMIC and other UBC-FRESH tools can depend on.
+
+## What this is not
+
+- A claim that UBC-FRESH invented VDYP7.
+- A byte-for-byte clone of the native VDYP7 binaries.
+- A substitute for measured field data or a complete growth-model validation.
+- A place to commit raw government model bundles or credentials.
+
+## Source and attribution
+
+Every extracted coefficient, control file, curve, and derived value records:
+
+```text
+source
+source version
+source file
+source SHA256
+extraction date
+citation
+```
+
+The original source remains the BC government's work. Reimplemented logic is
+labelled `reimplemented` and validated against console outputs where possible.
+
+## Plan
+
+Read these in order:
+
+1. [`notes/plan/0001-program-plan.md`](notes/plan/0001-program-plan.md)
+2. [`notes/plan/0002-data-provenance.md`](notes/plan/0002-data-provenance.md)
+3. [`notes/plan/0003-architecture.md`](notes/plan/0003-architecture.md)
+4. [`notes/plan/0004-validation-release.md`](notes/plan/0004-validation-release.md)
+5. [`notes/reference/vdyp-inventory.md`](notes/reference/vdyp-inventory.md)
+6. [`notes/reference/vdyp-model-map.md`](notes/reference/vdyp-model-map.md)
+
+## Quick start
+
+This seed is a planning repository. The Python package and data workflows land
+in Phase 2. Until then, the workflow gates are:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -r requirements-dev.txt
+python scripts/dashboard.py
+```
+
+## Bundle inspection
+
+Until the installable package lands, the first commands run from the repository:
+
+```bash
+export VDYP_CFG_DIR=/path/to/VDYP_CFG
+python scripts/fvdyp_cli.py bundle validate
+python scripts/fvdyp_cli.py bundle catalog
+python scripts/fvdyp_cli.py bundle extract --output-dir data/normalized
+```
+
+`validate` checks required files, control targets, and key lookups. `catalog`
+prints the family and row counts. `extract` writes normalized CSV files plus a
+provenance manifest; the CSV files stay under ignored `data/normalized/`.
+
+## Repository map
+
+| Path | Purpose |
+| --- | --- |
+| `AGENTS.md` | Operating contract for coding agents |
+| `HANDOFF.md` | First-read handoff note for a new session agent |
+| `ROADMAP.md` | Plan of record and issue tracker map |
+| `CHANGE_LOG.md` | Dated narrative of changes |
+| `notes/plan/` | Detailed program, data, architecture, and validation plans |
+| `notes/reference/` | VDYP inventory and coefficient-map facts |
+| `notes/adr/` | Accepted design decisions |
+| `docs/` | Sphinx RTFM surface |
+| `scripts/check_workflow.py` | Workflow validator |
+| `tests/` | pytest suite, including planning-surface checks |
+
+## License and citation
+
+Code is MIT licensed. Coefficient files and model outputs retain their original
+BC government attribution. Cite the source model and file, not only this package.

fresh_vdyp-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+# Build and tool configuration for fresh-vdyp. The installable modules live in
+# scripts/ and the public facade lives in scripts/fresh_vdyp/. Each gate
+# configured here is also a check in the green dashboard (scripts/dashboard.py).
+
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fresh-vdyp"
+version = "0.1.0"
+description = "A public interoperability layer for the BC VDYP7 coefficient bundle, console runner, and yield curves."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "UBC FRESH Lab" }]
+dependencies = [
+    "fastapi>=0.110",
+    "httpx>=0.27",
+    "pydantic>=2",
+    "typer>=0.12",
+    "uvicorn>=0.29",
+]
+
+[project.scripts]
+fvdyp = "fvdyp_cli:main"
+fresh-vdyp = "fvdyp_cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "scripts" }
+packages = ["fresh_vdyp"]
+py-modules = [
+    "assistant_tools",
+    "bundle_service",
+    "check_workflow",
+    "coe_parser",
+    "config_parser",
+    "curve_api",
+    "dashboard",
+    "equations",
+    "fvdyp_api",
+    "fvdyp_cli",
+    "inventory_vdyp",
+    "key_inference",
+    "normalize",
+    "provenance",
+    "run_console",
+    "vdyp_control",
+    "vdyp_map",
+    "vdyp_runtime",
+    "yield_parser",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["scripts", "tests"]
+extend-exclude = ["tmp", "_build"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP", "D", "ANN", "N", "PT", "SIM", "RUF", "C4"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+"templates/project/tests/**" = ["D"]
+"docs/conf.py" = ["D", "ANN", "N"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+mypy_path = "scripts"
+files = ["scripts", "tests", "docs/conf.py"]
+
+[[tool.mypy.overrides]]
+module = ["numpydoc", "numpydoc.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=scripts --cov-branch --cov-report=term-missing --cov-fail-under=95"
+
+[tool.coverage.run]
+branch = true
+source = ["scripts"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = ['if __name__ == "__main__":']

fresh_vdyp-0.1.0/scripts/assistant_tools.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Bounded assistant tools over the catalog, curves, provenance, and matrix.
+
+Every handler is deterministic and returns an :class:`AssistantAnswer` with at
+least one source. The validator rejects an answer without a source, so an
+assistant cannot present a coefficient, equation, or curve without attribution.
+No network or model provider is used.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Final
+
+from bundle_service import catalog_payload
+from curve_api import CurveQuery, CurveService
+from yield_parser import DEFAULT_ALIASES, DEFAULT_SCHEMA
+
+DEFAULT_MATRIX: Final[Path] = Path("notes/reference/vdyp-equation-matrix.json")
+
+
+class AssistantAnswerError(ValueError):
+    """Raised when an answer has no usable source."""
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """The schema of one assistant tool.
+
+    Attributes
+    ----------
+    name : str
+        Tool name.
+    description : str
+        What the tool answers.
+    parameters : dict of str to str
+        Parameter names and their descriptions.
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AssistantAnswer:
+    """One source-backed assistant answer.
+
+    Attributes
+    ----------
+    text : str
+        Short answer text.
+    sources : tuple of str
+        Source labels. Must be non-empty.
+    data : dict of str to object
+        Structured result for a caller.
+    """
+
+    text: str
+    sources: tuple[str, ...]
+    data: dict[str, object] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, object]:
+        """Render the answer as a JSON-ready mapping.
+
+        Returns
+        -------
+        dict of str to object
+            Text, sources, and data.
+        """
+        return {"text": self.text, "sources": list(self.sources), "data": self.data}
+
+
+TOOL_SPECS: Final[tuple[ToolSpec, ...]] = (
+    ToolSpec(
+        "catalog_search",
+        "Search the coefficient catalog by family, equation family, or status.",
+        {"query": "case-insensitive text"},
+    ),
+    ToolSpec(
+        "curve_query",
+        "Query the typed curve service with optional species/year/age filters.",
+        {
+            "species": "species code",
+            "year_start": "int",
+            "year_end": "int",
+            "age_start": "int",
+            "age_end": "int",
+        },
+    ),
+    ToolSpec(
+        "provenance_lookup",
+        "Return the source and runtime provenance of the loaded curve table.",
+        {},
+    ),
+    ToolSpec(
+        "validation_status",
+        "Return the validation status of one equation family.",
+        {"family": "family name"},
+    ),
+)
+
+
+def validate_answer(answer: AssistantAnswer) -> None:
+    """Validate that an answer names at least one source.
+
+    Parameters
+    ----------
+    answer : AssistantAnswer
+        Answer to validate.
+
+    Returns
+    -------
+    None
+        The answer is source-backed.
+
+    Raises
+    ------
+    AssistantAnswerError
+        When the source tuple is empty or contains a blank label.
+    """
+    if not answer.sources:
+        raise AssistantAnswerError("answer has no source")
+    if any(not source.strip() for source in answer.sources):
+        raise AssistantAnswerError("answer has a blank source")
+
+
+def catalog_search(config_dir: Path, query: str) -> AssistantAnswer:
+    """Search the catalog and return matching families with their source files.
+
+    Parameters
+    ----------
+    config_dir : Path
+        VDYP_CFG directory.
+    query : str
+        Case-insensitive family, equation-family, or status text.
+
+    Returns
+    -------
+    AssistantAnswer
+        Matching families and source labels.
+    """
+    payload = catalog_payload(config_dir)
+    rows = payload.get("families")
+    families = rows if isinstance(rows, list) else []
+    needle = query.strip().lower()
+    matches = [
+        row
+        for row in families
+        if isinstance(row, dict)
+        and any(
+            needle in str(row.get(key, "")).lower()
+            for key in ("family", "equation_family", "status")
+        )
+    ]
+    sources = tuple(
+        str(row["source_file"])
+        for row in matches
+        if isinstance(row, dict) and row.get("source_file")
+    ) or ("VDYP_CFG",)
+    answer = AssistantAnswer(
+        f"{len(matches)} families match {query!r}.",
+        sources,
+        {"families": matches},
+    )
+    validate_answer(answer)
+    return answer
+
+
+def curve_query(service: CurveService, query: CurveQuery) -> AssistantAnswer:
+    """Run a curve query and return a source-backed summary.
+
+    Parameters
+    ----------
+    service : CurveService
+        Loaded curve service.
+    query : CurveQuery
+        Query inputs.
+
+    Returns
+    -------
+    AssistantAnswer
+        Status, point count, and provenance.
+    """
+    result = service.query(query)
+    answer = AssistantAnswer(
+        f"{result.status}: {len(result.points)} points. {result.reason}".strip(),
+        (result.provenance.source_file, result.provenance.runtime),
+        result.to_dict(),
+    )
+    validate_answer(answer)
+    return answer
+
+
+def provenance_lookup(service: CurveService) -> AssistantAnswer:
+    """Return the provenance of the loaded curve table.
+
+    Parameters
+    ----------
+    service : CurveService
+        Loaded curve service.
+
+    Returns
+    -------
+    AssistantAnswer
+        Source file, runtime, console version, and schema labels.
+    """
+    answer = AssistantAnswer(
+        f"Source {service.table.source_file}; runtime {service.runtime}.",
+        (service.table.source_file, service.runtime),
+        {
+            "source_file": service.table.source_file,
+            "runtime": service.runtime,
+            "console_version": service.console_version,
+            "control_sequence": service.control_sequence,
+            "schema": str(DEFAULT_SCHEMA),
+            "aliases": str(DEFAULT_ALIASES),
+        },
+    )
+    validate_answer(answer)
+    return answer
+
+
+def validation_status(matrix: Path, family: str) -> AssistantAnswer:
+    """Return the validation status of one family from the matrix.
+
+    Parameters
+    ----------
+    matrix : Path
+        Equation matrix JSON.
+    family : str
+        Family name.
+
+    Returns
+    -------
+    AssistantAnswer
+        Status and evidence, or ``not_implemented`` when the family is absent.
+    """
+    payload = json.loads(matrix.read_text(encoding="utf-8"))
+    rows = payload.get("families") if isinstance(payload, dict) else None
+    if not isinstance(rows, list):
+        raise AssistantAnswerError("matrix has no families")
+    match = next(
+        (row for row in rows if isinstance(row, dict) and row.get("family") == family),
+        None,
+    )
+    if match is None:
+        answer = AssistantAnswer(
+            f"{family}: not_implemented (not in the matrix).",
+            (str(matrix),),
+            {"family": family, "status": "not_implemented"},
+        )
+    else:
+        answer = AssistantAnswer(
+            f"{family}: {match.get('status')}.",
+            (str(match.get("evidence", matrix)),),
+            match,
+        )
+    validate_answer(answer)
+    return answer