Metadata-Version: 2.4
Name: fresh-fuchs
Version: 0.2.0a1
Summary: Stochastic, risk-aware forest landscape planning on the TSA29 mini instance (WS3 inner LP + full-MC outer policy)
Author: UBC FRESH Lab
License-Expression: MIT
Project-URL: Homepage, https://github.com/UBC-FRESH/fresh-fuchs
Project-URL: Documentation, https://ubc-fresh.github.io/fresh-fuchs/
Project-URL: Repository, https://github.com/UBC-FRESH/fresh-fuchs
Project-URL: Issues, https://github.com/UBC-FRESH/fresh-fuchs/issues
Project-URL: Changelog, https://github.com/UBC-FRESH/fresh-fuchs/blob/main/CHANGE_LOG.md
Keywords: forestry,optimization,stochastic,monte-carlo,forest-planning
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml
Requires-Dist: rich
Requires-Dist: typer
Requires-Dist: ws3
Requires-Dist: highspy
Requires-Dist: pulp
Provides-Extra: bundle
Requires-Dist: femic==0.2.0a1; extra == "bundle"
Requires-Dist: geopandas; extra == "bundle"
Provides-Extra: orchestration
Requires-Dist: freshforge==0.1.0a6; extra == "orchestration"
Provides-Extra: rv
Requires-Dist: pacal>=1.6.1; extra == "rv"
Provides-Extra: fhops
Requires-Dist: fhops>=1.0.0; extra == "fhops"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
Provides-Extra: reports
Requires-Dist: matplotlib; extra == "reports"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: freshforge==0.1.0a6; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: sphinx>=7; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: quality
Requires-Dist: ruff>=0.5; extra == "quality"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5; extra == "release"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# fresh-fuchs

Stochastic, risk-aware forest landscape planning on the TSA29 mini instance
(~100,000 ha subset of Williams Lake TSA29).

The research design is a nested decision problem:

- **Outer (policy / administration).** Landscape-scale policy on target
  species / development-type composition by area share and on harvest policy
  (AAC as f(development type, rotation age)), evaluated risk-sensitively on
  Monte-Carlo distributions of NPV using downside-risk measures (CVaR).
- **Inner (enterprise / implementation).** Harvest scheduling and replanting
  decisions (which species to plant) maximizing NPV subject to the outer
  policy constraints, formulated as a Model I linear program.

Full-Monte-Carlo outer problem: sample disturbance (fire) and — later —
price realizations; solve the inner LP once per scenario (full foresight
within a scenario); evaluate each policy on the resulting NPV distribution.

Reuses the UBC-FRESH ecosystem rather than re-implementing it: `ws3`
(wood-supply engine and LP machinery), `femic` (tsa29mini instance bundle and
model bridge), `fhops` (harvest-cost estimation), `nemora` (DBH distribution
fit and sampling), and `freshforge` (workflow + matrix orchestration and
evidence). `fresh-salvage` provides economic calibration anchors (reference
only).

## Status

`v0.1.0a1` (Phase 5 release). The end-to-end pipeline is implemented,
validated, and tested: extended ws3 model build -> full-MC fire scenarios ->
per-scenario inner LP (NPV max) -> NPV distribution -> policy grid search ->
CVaR-based ranking, wrapped in freshforge workflows/matrices with evidence.
See `ROADMAP.md` for the phase/issue tracker map and
`planning/v0.1.0a1-plan.md` for the detailed master plan.

## Quick Start

CI-safe synthetic end-to-end (no private data; the public-safe synthetic
instance in `fresh_fuchs.instance.synthetic`):

```bash
pip install -e ".[dev,orchestration]"
```

```python
from fresh_fuchs.orchestration import fuchs_workflow_spec, run_fuchs_workflow

spec = fuchs_workflow_spec(horizon=2, n_scenarios=3, master_seed=42)
result = run_fuchs_workflow(spec, workdir="outputs/synthetic")
assert result.ok
```

Real-bundle pipeline (requires the `bundle` extra and the annex bundle):

```bash
pip install -e ".[dev,bundle]"
fresh-fuchs --help
# build-model -> scenario-run -> policy-grid -> policy-rank
```

## Documentation

Sphinx docs under `docs/`: installation, quickstart, model semantics, CLI
reference, architecture, and development guides.

## License

MIT, Copyright (c) 2026 UBC FRESH Lab.
