scripts/build_self_contained_md.py

from __future__ import annotations

import base64
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "LOCAL_HARDWARE_FRONTIER.md"

COMPARISON_CHARTS = [
    ("Under $3,000", "charts/01_under_3000.svg"),
    ("$3,000-$5,000", "charts/02_3000_5000.svg"),
    ("$5,000-$10,000", "charts/03_5000_10000.svg"),
    ("$10,000-$25,000", "charts/04_10000_25000.svg"),
    ("$25,000-$75,000", "charts/05_25000_75000.svg"),
    ("$75,000+", "charts/06_75000_plus.svg"),
]

PRICE_PER_MEMORY_CHARTS = [
    ("Under $3,000", "charts/price_per_memory/01_under_3000_price_per_memory.svg"),
    ("$3,000-$5,000", "charts/price_per_memory/02_3000_5000_price_per_memory.svg"),
    ("$5,000-$10,000", "charts/price_per_memory/03_5000_10000_price_per_memory.svg"),
    ("$10,000-$25,000", "charts/price_per_memory/04_10000_25000_price_per_memory.svg"),
    ("$25,000-$75,000", "charts/price_per_memory/05_25000_75000_price_per_memory.svg"),
    ("$75,000+", "charts/price_per_memory/06_75000_plus_price_per_memory.svg"),
]

BANDWIDTH_CHARTS = [
    ("Under $3,000", "charts/bandwidth/01_under_3000_bandwidth.svg"),
    ("$3,000-$5,000", "charts/bandwidth/02_3000_5000_bandwidth.svg"),
    ("$5,000-$10,000", "charts/bandwidth/03_5000_10000_bandwidth.svg"),
    ("$10,000-$25,000", "charts/bandwidth/04_10000_25000_bandwidth.svg"),
    ("$25,000-$75,000", "charts/bandwidth/05_25000_75000_bandwidth.svg"),
    ("$75,000+", "charts/bandwidth/06_75000_plus_bandwidth.svg"),
]

MEMORY_BEST_CHARTS = [
    ("Under $3,000", "charts/monotonic/01_under_3000_monotonic.svg"),
    ("$3,000-$5,000", "charts/monotonic/02_3000_5000_monotonic.svg"),
    ("$5,000-$10,000", "charts/monotonic/03_5000_10000_monotonic.svg"),
    ("$10,000-$25,000", "charts/monotonic/04_10000_25000_monotonic.svg"),
    ("$25,000-$75,000", "charts/monotonic/05_25000_75000_monotonic.svg"),
    ("$75,000+", "charts/monotonic/06_75000_plus_monotonic.svg"),
]

CONSUMER_MEMORY_BEST_CHART = (
    "Under $10,000 Consumer Bands",
    "charts/monotonic/00_consumer_bands_monotonic.svg",
)

UNDER_3000_MEMORY_PROJECTION_CHART = (
    "Under $3,000 Linear Projection To 2030",
    "charts/projections/under_3000_memory_linear_projection.svg",
)

CONSUMER_MEMORY_PROJECTION_CHART = (
    "Consumer Bands Linear Projection To 2030",
    "charts/projections/consumer_memory_linear_projection.svg",
)

PRICE_BEST_CHARTS = [
    ("Under $3,000", "charts/best_so_far_price_per_memory/01_under_3000_price_per_memory_best_so_far.svg"),
    ("$3,000-$5,000", "charts/best_so_far_price_per_memory/02_3000_5000_price_per_memory_best_so_far.svg"),
    ("$5,000-$10,000", "charts/best_so_far_price_per_memory/03_5000_10000_price_per_memory_best_so_far.svg"),
    ("$10,000-$25,000", "charts/best_so_far_price_per_memory/04_10000_25000_price_per_memory_best_so_far.svg"),
    ("$25,000-$75,000", "charts/best_so_far_price_per_memory/05_25000_75000_price_per_memory_best_so_far.svg"),
    ("$75,000+", "charts/best_so_far_price_per_memory/06_75000_plus_price_per_memory_best_so_far.svg"),
]

BANDWIDTH_BEST_CHARTS = [
    ("Under $3,000", "charts/best_so_far_bandwidth/01_under_3000_bandwidth_best_so_far.svg"),
    ("$3,000-$5,000", "charts/best_so_far_bandwidth/02_3000_5000_bandwidth_best_so_far.svg"),
    ("$5,000-$10,000", "charts/best_so_far_bandwidth/03_5000_10000_bandwidth_best_so_far.svg"),
    ("$10,000-$25,000", "charts/best_so_far_bandwidth/04_10000_25000_bandwidth_best_so_far.svg"),
    ("$25,000-$75,000", "charts/best_so_far_bandwidth/05_25000_75000_bandwidth_best_so_far.svg"),
    ("$75,000+", "charts/best_so_far_bandwidth/06_75000_plus_bandwidth_best_so_far.svg"),
]


def embed_chart(title: str, relative_path: str) -> str:
    path = ROOT / relative_path
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return (
        "<figure>\n"
        f"<figcaption><strong>{title}</strong></figcaption>\n"
        f'<img alt="{title} chart" src="data:image/svg+xml;base64,{encoded}">\n'
        "</figure>"
    )


def chart_section(charts: list[tuple[str, str]]) -> str:
    return "\n\n".join(embed_chart(title, path) for title, path in charts)


content = f"""# Local Hardware Frontier, 2020-2026

This writeup is the readable version of the local hardware frontier notes. It includes prose and generated SVG charts only. Raw CSVs, item JSON files, schema, and regeneration scripts live next to this file in `docs/local_hardware_frontier/` and in `local_hardware_frontier_artifacts.zip`.

Last rebuilt: 2026-06-26.

## What This Tracks

The data tracks accelerator-accessible memory in one physical machine, grouped by complete-machine price band. It covers Apple, NVIDIA, and AMD from 2020 through 2026.

The core question is practical: what can someone buy or configure locally, and how do affordability, capacity, bandwidth, and vendor tradeoffs move over time?

## How To Read The Symbols

- `U` means unified or coherent memory available to the accelerator.
- `V` means VRAM on one discrete GPU.
- `Σ` means aggregate VRAM across multiple GPUs in one chassis.
- `*` means the price band is inferred from a documented component bill of materials, not from one exact checkout quote.

Aggregate VRAM is useful, but it is not the same thing as one unified memory pool. Treat `Σ` points as capacity in the chassis, not a guarantee that one process can use it as one contiguous model memory space.

## Main Read

Under $3,000, AMD changes the shape of the local market in 2025 and 2026 with 128GB unified memory through Framework Desktop-class hardware. Apple is strong on usable unified memory, but the current sub-$3,000 Apple ceiling in this dataset is 64GB. NVIDIA stays at 24GB in this band because the data is tracking complete machines, not used cards or component-only builds.

In the $3,000-$5,000 band, both AMD and NVIDIA reach 128GB unified or coherent memory by 2025-2026. This is the band that matters most for consumer and prosumer local model work because it is expensive but still within a serious personal hardware budget.

In the $5,000-$10,000 band, Apple has the most dramatic historical point: the 512GB M3 Ultra Mac Studio launch configuration in 2025. The best-so-far memory charts keep that 512GB point through 2026 because the historical frontier should not go down just because the current Apple configuration changed.

Above $75,000, NVIDIA dominates the memory and bandwidth frontier. DGX Station-class systems are local in the physical sense, but not local in the affordability sense.

## Annual Memory By Producer

These charts show the annual maximum accelerator-accessible memory found for each producer in each price band.

{chart_section(COMPARISON_CHARTS)}

## Annual Price Per GB

These charts use the same annual max-memory row as the producer comparison charts, then divide complete-system USD price by accelerator-accessible memory. Lower is better, but this metric should be read next to capacity: a low price per GB can still be a worse strategy if total memory is below the model you need to run.

The adjacent `data/memory_price_per_gb.csv` is a separate extracted-memory metric. It uses GPU/card prices or same-device memory upgrade deltas where those can be source-backed, instead of dividing the whole machine price by memory.

{chart_section(PRICE_PER_MEMORY_CHARTS)}

## Annual Memory Bandwidth

These charts use `memory.bandwidth_gbps` from the item JSON files for the same annual max-memory row. `U` means unified or coherent memory bandwidth, `V` means one discrete GPU, and `Σ` means aggregate installed-GPU bandwidth in one chassis.

{chart_section(BANDWIDTH_CHARTS)}

## Best-So-Far Memory

These charts show the dominant memory frontier for each price band. If a later year has less available memory than an earlier year, the chart keeps the earlier maximum. Labels name releases or price updates that set or match the carried frontier.

{embed_chart(*CONSUMER_MEMORY_BEST_CHART)}

The next projection chart fits one linear trend per under-$10,000 consumer price band and extends those lines to 2030. It is a scenario view, not verified future product data.

{embed_chart(*CONSUMER_MEMORY_PROJECTION_CHART)}

The focused projection chart uses the same method for the under-$3,000 best-so-far memory series.

{embed_chart(*UNDER_3000_MEMORY_PROJECTION_CHART)}

{chart_section(MEMORY_BEST_CHARTS)}

## Best-So-Far Price Per GB

These charts carry forward the lowest complete-system USD per GB achieved so far in each price band. Lower is better.

{chart_section(PRICE_BEST_CHARTS)}

## Best-So-Far Memory Bandwidth

These charts carry forward the highest source-backed memory bandwidth achieved so far in each price band. Higher is better.

{chart_section(BANDWIDTH_BEST_CHARTS)}

## Reproducibility

The editable source of truth is `data/items/*.json`. The generator expands each item price history into CSVs, derives annual and best-so-far frontiers, renders all PNG/SVG charts, rebuilds the gallery, and refreshes the artifact zip.

Extracted component and upgrade prices live in `data/memory_price_sources.csv`; the generated `data/memory_price_per_gb.csv` calculates USD/GB from those rows.

Run from `docs/local_hardware_frontier/`:

```sh
python scripts/validate_items.py
python scripts/generate_graphs.py
python scripts/build_self_contained_md.py
```

Raw data is intentionally not embedded in this writeup. Use the adjacent files when you need the catalog, schema, source item JSON, or regeneration code.

## Limits

This is a working research file reconstructed for talk prep. It is useful for local-model hardware strategy, but the source catalog should be rechecked before being treated as a published dataset.
"""

OUT.write_text(content, encoding="utf-8")
print(OUT)