fresh-tipsy 0.1.0__tar.gz

fresh_tipsy-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_tipsy-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: fresh-tipsy
+Version: 0.1.0
+Summary: A provenance-first Python interoperability layer for BC TIPSY and FAN$IER tables.
+Author: UBC FRESH Lab
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: jsonschema>=4.20
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=15; extra == "parquet"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115; extra == "api"
+Requires-Dist: uvicorn>=0.30; extra == "api"
+Requires-Dist: jinja2>=3.1; extra == "api"
+Dynamic: license-file
+
+# fresh-tipsy
+
+A public, tested Python package for reading TIPSY and FAN$IER data tables,
+exposing growth, product-recovery, and economics workflows, and preserving the
+provenance of every value.
+
+`fresh-tipsy` is a reimplementation and interoperability layer. It does not
+claim authorship of TIPSY, FAN$IER, TASS, FEMIC, or BC government data. It exists
+so those models and tables can be queried from Python, tested in the open, and
+used by tools such as FEMIC without a GUI boundary.
+
+Repository: <https://github.com/UBC-FRESH/fresh-tipsy>
+
+## Status
+
+Version 0.1.0 was released on 2026-11-09.
+`ROADMAP.md` and GitHub issues carry the live status. The package is an
+interoperability layer over precomputed TASS/TIPSY tables, not a TASS rewrite.
+
+## Features
+
+- `.tab`/`.taf` parsers, provenance manifests, catalog, and normalization.
+- Typed growth queries over precomputed TASS/TIPSY tables, with interpolation,
+  metrics, source SHA-256, and explicit unavailable metrics.
+- Product recovery for lumber, residues, log grades, graded/degraded lumber, and
+  industrial logs, with strict mass-balance checks.
+- Explicit-input product economics: prices, costs, NPV, Faustmann site value,
+  and FAN$IER-style sensitivity cases.
+- Typer CLI: `db`, `curve`, `product`, and `econ` commands with JSON output.
+- FastAPI service and Pydantic response envelopes.
+- Server-rendered FRESH-style catalog, curve, product, and economics UI.
+- Deterministic assistant tools with provenance-first prompt guidance.
+- Optional FEMIC adapter with package-version and data-manifest provenance.
+
+## What this is not
+
+- A claim that UBC-FRESH invented TIPSY, FAN$IER, or FEMIC.
+- A byte-for-byte reimplementation of TASS.
+- A substitute for measured BC log grades or mill-specific recovery.
+- A place to commit raw government data tables, credentials, or personal paths.
+- A validated FAN$IER replacement.
+
+## Install
+
+From a source checkout:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[api,parquet]"
+python scripts/dashboard.py
+fresh-tipsy --help
+```
+
+Extras:
+
+- `api`: FastAPI, Jinja2, and uvicorn for the HTTP API and web UI.
+- `parquet`: PyArrow for Parquet normalization and `db extract`.
+- The minimal install supports parsing, catalog, curve, product, and economics
+  commands that do not need Parquet or the API.
+
+Download the wheel, sdist, or HTML docs archive from the 0.1.0 GitHub release.
+Build evidence is in [`notes/reference/package-build.md`](notes/reference/package-build.md).
+
+## Quick start
+
+Set the local source roots:
+
+```bash
+export TIPSY_INSTALL="/path/to/tipsy"
+export TIPSY_DATABASE="$TIPSY_INSTALL/Database"
+export FRESH_TIPSY_CACHE="/path/to/fresh-tipsy-cache"
+```
+
+Extract a catalog from a local licensed install:
+
+```bash
+fresh-tipsy db extract --source "$TIPSY_INSTALL" --out "$FRESH_TIPSY_CACHE"
+fresh-tipsy db validate --catalog "$FRESH_TIPSY_CACHE/manifest.json" --source "$TIPSY_INSTALL"
+```
+
+Query growth, products, and economics:
+
+```bash
+fresh-tipsy curve query --catalog "$FRESH_TIPSY_CACHE/manifest.json" \
+  --source "$TIPSY_INSTALL" --species PLI --site-index 20 --age 80 --pnc N --json
+
+fresh-tipsy product recover --catalog "$FRESH_TIPSY_CACHE/manifest.json" \
+  --source "$TIPSY_INSTALL" --species PLI --site-index 20 --age 80 --pnc N --json
+
+fresh-tipsy econ run --catalog "$FRESH_TIPSY_CACHE/manifest.json" \
+  --source "$TIPSY_INSTALL" --scenario scenario.json --json
+```
+
+The scenario schema and exit codes are in
+[`notes/reference/cli.md`](notes/reference/cli.md). The API and web UI are in
+[`notes/reference/api.md`](notes/reference/api.md) and
+[`notes/reference/web.md`](notes/reference/web.md).
+
+## Validation and evidence
+
+- Four-species TIPSY golden regression: PLI, FDC, AT, and FDI exact ages plus
+  product mass balance. See
+  [`notes/reference/release-validation.md`](notes/reference/release-validation.md).
+- Hand-checked economics case: NPV 335.543289 CAD/ha and site value 546.081251
+  CAD/ha for the documented inputs. See
+  [`notes/reference/economics.md`](notes/reference/economics.md).
+- Cross-interface parity for CLI, API, web, and assistant tools.
+- 376 tests passed and 13 skipped at the last preparation run; combined branch
+  coverage 95.5%.
+- Real-source tests skip when `TIPSY_DATABASE` is unset; a skip is not a pass.
+
+## Known gaps
+
+The release is deliberately explicit about missing evidence:
+
+- TIPSY custom runtime output is unavailable under Wine.
+- FAN$IER price, cost, product-suite, and NPV tables are unparsed.
+- FEMIC TSR output is not captured.
+- Product aggregate totals are not stored in `.taf`; aggregate checks are
+  derived, with an independent #2 & Better-to-graded cross-check.
+- Residue totals are absent.
+- Carbon conversion is unavailable.
+- No measured BC field grade or mill-specific recovery is claimed.
+- FEMIC adapter call and dependency are prepared but not applied to the FEMIC
+  repository.
+- Wheel/sdist are prepared but not published.
+
+See [`notes/reference/known-gaps.md`](notes/reference/known-gaps.md) for the full
+list and limits.
+
+## Citation
+
+Cite the package, the source model, and the specific table path and SHA-256.
+Raw data is not relicensed by this package.
+
+- [`CITATION.cff`](CITATION.cff)
+- [`notes/reference/citation.md`](notes/reference/citation.md)
+- [`notes/reference/source-inventory.md`](notes/reference/source-inventory.md)
+
+## Release notes
+
+- [`RELEASE_NOTES.md`](RELEASE_NOTES.md)
+- [`notes/reference/release-assets.md`](notes/reference/release-assets.md)
+- [`notes/reference/release-assets.csv`](notes/reference/release-assets.csv)
+
+## 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 |
+| `RELEASE_NOTES.md` | 0.1.0 release notes and known gaps |
+| `notes/plan/` | Program, data, architecture, and validation plans |
+| `notes/reference/` | Source inventory, schemas, validation, and release facts |
+| `notes/adr/` | Accepted design decisions |
+| `docs/` | Sphinx RTFM surface |
+| `scripts/check_workflow.py` | Workflow validator |
+| `scripts/check_release_assets.py` | Release asset and checksum validator |
+| `tests/` | pytest suite, including interface and release checks |
+
+## License and attribution
+
+Code is MIT licensed. Data tables and model outputs retain their original BC
+government attribution. Cite the source model and table, not only this package.
+No source table, normalized asset, or model output is relicensed here.

fresh_tipsy-0.1.0/README.md

@@ -0,0 +1,168 @@
+# fresh-tipsy
+
+A public, tested Python package for reading TIPSY and FAN$IER data tables,
+exposing growth, product-recovery, and economics workflows, and preserving the
+provenance of every value.
+
+`fresh-tipsy` is a reimplementation and interoperability layer. It does not
+claim authorship of TIPSY, FAN$IER, TASS, FEMIC, or BC government data. It exists
+so those models and tables can be queried from Python, tested in the open, and
+used by tools such as FEMIC without a GUI boundary.
+
+Repository: <https://github.com/UBC-FRESH/fresh-tipsy>
+
+## Status
+
+Version 0.1.0 was released on 2026-11-09.
+`ROADMAP.md` and GitHub issues carry the live status. The package is an
+interoperability layer over precomputed TASS/TIPSY tables, not a TASS rewrite.
+
+## Features
+
+- `.tab`/`.taf` parsers, provenance manifests, catalog, and normalization.
+- Typed growth queries over precomputed TASS/TIPSY tables, with interpolation,
+  metrics, source SHA-256, and explicit unavailable metrics.
+- Product recovery for lumber, residues, log grades, graded/degraded lumber, and
+  industrial logs, with strict mass-balance checks.
+- Explicit-input product economics: prices, costs, NPV, Faustmann site value,
+  and FAN$IER-style sensitivity cases.
+- Typer CLI: `db`, `curve`, `product`, and `econ` commands with JSON output.
+- FastAPI service and Pydantic response envelopes.
+- Server-rendered FRESH-style catalog, curve, product, and economics UI.
+- Deterministic assistant tools with provenance-first prompt guidance.
+- Optional FEMIC adapter with package-version and data-manifest provenance.
+
+## What this is not
+
+- A claim that UBC-FRESH invented TIPSY, FAN$IER, or FEMIC.
+- A byte-for-byte reimplementation of TASS.
+- A substitute for measured BC log grades or mill-specific recovery.
+- A place to commit raw government data tables, credentials, or personal paths.
+- A validated FAN$IER replacement.
+
+## Install
+
+From a source checkout:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[api,parquet]"
+python scripts/dashboard.py
+fresh-tipsy --help
+```
+
+Extras:
+
+- `api`: FastAPI, Jinja2, and uvicorn for the HTTP API and web UI.
+- `parquet`: PyArrow for Parquet normalization and `db extract`.
+- The minimal install supports parsing, catalog, curve, product, and economics
+  commands that do not need Parquet or the API.
+
+Download the wheel, sdist, or HTML docs archive from the 0.1.0 GitHub release.
+Build evidence is in [`notes/reference/package-build.md`](notes/reference/package-build.md).
+
+## Quick start
+
+Set the local source roots:
+
+```bash
+export TIPSY_INSTALL="/path/to/tipsy"
+export TIPSY_DATABASE="$TIPSY_INSTALL/Database"
+export FRESH_TIPSY_CACHE="/path/to/fresh-tipsy-cache"
+```
+
+Extract a catalog from a local licensed install:
+
+```bash
+fresh-tipsy db extract --source "$TIPSY_INSTALL" --out "$FRESH_TIPSY_CACHE"
+fresh-tipsy db validate --catalog "$FRESH_TIPSY_CACHE/manifest.json" --source "$TIPSY_INSTALL"
+```
+
+Query growth, products, and economics:
+
+```bash
+fresh-tipsy curve query --catalog "$FRESH_TIPSY_CACHE/manifest.json" \
+  --source "$TIPSY_INSTALL" --species PLI --site-index 20 --age 80 --pnc N --json
+
+fresh-tipsy product recover --catalog "$FRESH_TIPSY_CACHE/manifest.json" \
+  --source "$TIPSY_INSTALL" --species PLI --site-index 20 --age 80 --pnc N --json
+
+fresh-tipsy econ run --catalog "$FRESH_TIPSY_CACHE/manifest.json" \
+  --source "$TIPSY_INSTALL" --scenario scenario.json --json
+```
+
+The scenario schema and exit codes are in
+[`notes/reference/cli.md`](notes/reference/cli.md). The API and web UI are in
+[`notes/reference/api.md`](notes/reference/api.md) and
+[`notes/reference/web.md`](notes/reference/web.md).
+
+## Validation and evidence
+
+- Four-species TIPSY golden regression: PLI, FDC, AT, and FDI exact ages plus
+  product mass balance. See
+  [`notes/reference/release-validation.md`](notes/reference/release-validation.md).
+- Hand-checked economics case: NPV 335.543289 CAD/ha and site value 546.081251
+  CAD/ha for the documented inputs. See
+  [`notes/reference/economics.md`](notes/reference/economics.md).
+- Cross-interface parity for CLI, API, web, and assistant tools.
+- 376 tests passed and 13 skipped at the last preparation run; combined branch
+  coverage 95.5%.
+- Real-source tests skip when `TIPSY_DATABASE` is unset; a skip is not a pass.
+
+## Known gaps
+
+The release is deliberately explicit about missing evidence:
+
+- TIPSY custom runtime output is unavailable under Wine.
+- FAN$IER price, cost, product-suite, and NPV tables are unparsed.
+- FEMIC TSR output is not captured.
+- Product aggregate totals are not stored in `.taf`; aggregate checks are
+  derived, with an independent #2 & Better-to-graded cross-check.
+- Residue totals are absent.
+- Carbon conversion is unavailable.
+- No measured BC field grade or mill-specific recovery is claimed.
+- FEMIC adapter call and dependency are prepared but not applied to the FEMIC
+  repository.
+- Wheel/sdist are prepared but not published.
+
+See [`notes/reference/known-gaps.md`](notes/reference/known-gaps.md) for the full
+list and limits.
+
+## Citation
+
+Cite the package, the source model, and the specific table path and SHA-256.
+Raw data is not relicensed by this package.
+
+- [`CITATION.cff`](CITATION.cff)
+- [`notes/reference/citation.md`](notes/reference/citation.md)
+- [`notes/reference/source-inventory.md`](notes/reference/source-inventory.md)
+
+## Release notes
+
+- [`RELEASE_NOTES.md`](RELEASE_NOTES.md)
+- [`notes/reference/release-assets.md`](notes/reference/release-assets.md)
+- [`notes/reference/release-assets.csv`](notes/reference/release-assets.csv)
+
+## 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 |
+| `RELEASE_NOTES.md` | 0.1.0 release notes and known gaps |
+| `notes/plan/` | Program, data, architecture, and validation plans |
+| `notes/reference/` | Source inventory, schemas, validation, and release facts |
+| `notes/adr/` | Accepted design decisions |
+| `docs/` | Sphinx RTFM surface |
+| `scripts/check_workflow.py` | Workflow validator |
+| `scripts/check_release_assets.py` | Release asset and checksum validator |
+| `tests/` | pytest suite, including interface and release checks |
+
+## License and attribution
+
+Code is MIT licensed. Data tables and model outputs retain their original BC
+government attribution. Cite the source model and table, not only this package.
+No source table, normalized asset, or model output is relicensed here.

fresh_tipsy-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+# Tool configuration for the UBC-FRESH dev workflow and the fresh-tipsy package.
+# Each gate configured here is also a check in the green dashboard
+# (scripts/dashboard.py).
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fresh-tipsy"
+version = "0.1.0"
+description = "A provenance-first Python interoperability layer for BC TIPSY and FAN$IER tables."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "UBC FRESH Lab" }]
+dependencies = ["typer>=0.12", "jsonschema>=4.20"]
+
+[project.optional-dependencies]
+parquet = ["pyarrow>=15"]
+api = ["fastapi>=0.115", "uvicorn>=0.30", "jinja2>=3.1"]
+
+[project.scripts]
+fresh-tipsy = "fresh_tipsy.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"fresh_tipsy.tables" = ["data/*.csv", "data/*.json"]
+"fresh_tipsy.web" = ["templates/*.html", "static/*.css"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["scripts", "tests", "src"]
+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", "src", "tests", "docs/conf.py"]
+
+[[tool.mypy.overrides]]
+module = ["numpydoc", "numpydoc.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["pyarrow", "pyarrow.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "--cov=scripts --cov=src/fresh_tipsy --cov-branch --cov-report=term-missing --cov-fail-under=95"
+
+[tool.coverage.run]
+branch = true
+source = ["scripts", "src/fresh_tipsy"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = ['if __name__ == "__main__":']

fresh_tipsy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fresh_tipsy-0.1.0/src/fresh_tipsy/__init__.py

@@ -0,0 +1,7 @@
+"""Public package surface for fresh-tipsy."""
+
+from __future__ import annotations
+
+from fresh_tipsy.version import __version__
+
+__all__ = ["__version__"]

fresh_tipsy-0.1.0/src/fresh_tipsy/agent/__init__.py

@@ -0,0 +1,8 @@
+"""Bounded assistant tools and prompt guidance."""
+
+from __future__ import annotations
+
+from fresh_tipsy.agent.prompts import SYSTEM_PROMPT, prompt
+from fresh_tipsy.agent.tools import ToolBox, ToolResult, tool_specs
+
+__all__ = ["SYSTEM_PROMPT", "ToolBox", "ToolResult", "prompt", "tool_specs"]

fresh_tipsy-0.1.0/src/fresh_tipsy/agent/prompts.py

@@ -0,0 +1,31 @@
+"""Provenance-first prompt guidance for an optional assistant adapter."""
+
+from __future__ import annotations
+
+SYSTEM_PROMPT = """You are a bounded assistant for fresh-tipsy, a provenance-first
+interoperability layer for BC TIPSY and FAN$IER data.
+
+Rules:
+- Use the provided tools. Never invent a table, column, coefficient, price, cost,
+  grade, or result.
+- Every answer must identify the source table or asset and the original query
+  inputs. If provenance is missing, say so and stop.
+- Product values are TASS/SYLVER model output, not measured BC field grades.
+- Economics is reimplemented from documented formulas with explicit inputs and
+  is not validated against FAN$IER. Missing prices and incompatible units are
+  gaps, not zero.
+- If a tool returns an error or warning, report it instead of guessing.
+- Do not claim mill-specific recovery or a measured grade.
+- Keep raw data out of the answer; cite the source path and checksum."
+"""
+
+
+def prompt() -> str:
+    """Return the provenance-first system prompt.
+
+    Returns
+    -------
+    str
+        System prompt.
+    """
+    return SYSTEM_PROMPT