README.md

# Local Hardware Frontier

Start with `LOCAL_HARDWARE_FRONTIER.md`. It is the readable writeup: prose and generated charts only. Raw CSVs, item JSON, schema, and regeneration code stay as adjacent files instead of being embedded in the writeup.

This folder also keeps the separate item JSON files, CSVs, PNG/SVG charts, gallery, schema, and scripts for editing and regeneration.

Hugging Face deployment:

- Space: <https://huggingface.co/spaces/dutifuldev/local-frontier>
- App: <https://dutifuldev-local-frontier.static.hf.space/index.html>
- Bucket: <https://huggingface.co/buckets/dutifuldev/local-frontier>

## Contents

- `ITEM_FORMAT.md`: spec for the per-item JSON format.
- `schemas/local_hardware_item.schema.json`: JSON Schema for item files.
- `data/items/*.json`: editable source-of-truth item files with historical prices.
- `data/verified_system_catalog.csv`: generated system catalog with price band, memory amount, bandwidth, price-per-memory, evidence grade, source URL, and notes.
- `data/memory_price_sources.csv`: source-backed GPU/card or same-device memory upgrade prices.
- `data/memory_price_per_gb.csv`: generated extracted-memory USD/GB rows derived from `data/memory_price_sources.csv`.
- `data/annual_frontier_2020_2026.csv`: derived annual maximums by producer and price band.
- `data/dominant_frontier_2020_2026.csv`: monotonic best-so-far frontier by price band.
- `data/dominant_frontier_events_2020_2026.csv`: releases labeled on the monotonic charts, including releases that match the carried frontier without raising it.
- `data/best_price_per_memory_2020_2026.csv`: best-so-far complete-system USD/GB frontier by price band.
- `data/best_price_per_memory_events_2020_2026.csv`: releases labeled on the best-so-far USD/GB charts.
- `data/best_bandwidth_2020_2026.csv`: best-so-far memory-bandwidth frontier by price band.
- `data/best_bandwidth_events_2020_2026.csv`: releases labeled on the best-so-far bandwidth charts.
- `data/consumer_memory_linear_projection_2020_2030.csv`: generated linear projections for the under-$10,000 consumer best-so-far memory frontiers.
- `data/under_3000_memory_linear_projection_2020_2030.csv`: generated linear projection for the under-$3,000 best-so-far memory frontier.
- `data/frontier_matrix.csv`: compact chart-value matrix.
- `charts/*.png` and `charts/*.svg`: generated price-band charts.
- `charts/monotonic/*.png` and `charts/monotonic/*.svg`: monotonic best-so-far charts that carry prior maxima forward, including a combined under-$10,000 consumer-band chart.
- `charts/price_per_memory/*.png` and `charts/price_per_memory/*.svg`: complete-system USD per GB charts.
- `charts/bandwidth/*.png` and `charts/bandwidth/*.svg`: peak memory bandwidth charts.
- `charts/best_so_far_price_per_memory/*.png` and `charts/best_so_far_price_per_memory/*.svg`: best-so-far USD per GB charts.
- `charts/best_so_far_bandwidth/*.png` and `charts/best_so_far_bandwidth/*.svg`: best-so-far memory bandwidth charts.
- `charts/projections/*.png` and `charts/projections/*.svg`: generated projection charts.
- `gallery/all_price_band_charts.html`: simple local HTML gallery for the charts.
- `space/`: generated static Hugging Face Space bundle with interactive charts and per-device pages.
- `README_methodology.txt`: generated methodology note.
- `scripts/local_hardware_items.py`: shared item loader and validator.
- `scripts/validate_items.py`: validates `data/items/*.json`.
- `scripts/generate_graphs.py`: chart and CSV generation script.
- `scripts/build_self_contained_md.py`: rebuilds `LOCAL_HARDWARE_FRONTIER.md` with embedded SVG charts only.
- `scripts/build_static_space.py`: rebuilds `space/` from the generated CSVs and item JSON files.
- `requirements.txt`: Python dependency needed for chart generation.

## Regenerate

From this folder:

```sh
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python scripts/validate_items.py
python scripts/generate_graphs.py
python scripts/build_self_contained_md.py
python scripts/build_static_space.py
```

The validator checks item-file shape, price bands, year ranges, source URLs, bandwidth-source pairing, aggregate-bandwidth notes, duplicate generated rows, non-overlapping price histories, and extracted memory-price rows. The graph script refreshes generated CSVs, `charts/`, `gallery/all_price_band_charts.html`, `README_methodology.txt`, and `local_hardware_frontier_artifacts.zip`. The writeup builder refreshes `LOCAL_HARDWARE_FRONTIER.md` without embedding raw data. The Space builder refreshes the static `space/` bundle.

## Scope

The data tracks maximum accelerator-accessible memory in one machine from 2020 to 2026 across Apple, NVIDIA, and AMD, grouped by complete-machine price band. It distinguishes unified/coherent memory, single-GPU VRAM, and aggregate multi-GPU VRAM. Bandwidth is plotted only from explicit item JSON values; missing bandwidth is left blank rather than inferred.

`price_per_memory_gb` in `data/verified_system_catalog.csv` is the complete configured machine price divided by accelerator-accessible memory. `data/memory_price_per_gb.csv` is different: it is the extracted GPU/card price or same-device memory upgrade delta divided by the priced memory amount.