# WRITER.md — Script Writer

The pipeline uses `midnight_static.writer.ScriptWriter` as the boundary between
script generation and audio rendering.

## Implementations

- `fixture`: deterministic, schema-valid local writer used for tests and Day 1
  pipeline proof.
- `nemotron`: lazy-loaded Transformers writer targeting
  `nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16` by default.

The model ID was verified from Hugging Face Hub search results on June 12, 2026.
Related official repos include:

- `nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16`
- `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8`
- `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF`

## Commands

Fast schema smoke:

```bash
uv run python scripts/check_writer_premises.py --writer fixture
```

Real model smoke, downloads/loads the 4B model:

```bash
uv sync --extra dev --extra tts --extra writer
uv run python scripts/check_writer_premises.py --writer nemotron
```

Local macOS fallback smoke using the Llama-architecture Nemotron Nano 4B repo:

```bash
uv run python scripts/check_writer_premises.py \
  --writer nemotron \
  --model-id nvidia/Llama-3.1-Nemotron-Nano-4B-v1.1 \
  --limit 1 \
  --max-new-tokens 900
```

Runtime knobs:

- `MIDNIGHT_NEMOTRON_MODEL`
- `MIDNIGHT_NEMOTRON_DEVICE_MAP`
- `MIDNIGHT_NEMOTRON_MAX_NEW_TOKENS`

The current implementation validates generated JSON with `script_from_json_dict`.
If model output fails parsing or cross-field validation, the next pipeline step
should add one retry with the validation error appended, then fixture fallback.

## Current Runtime Notes

`nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16` loads custom Nemotron-H code and failed
on local macOS arm64 because `mamba-ssm` was unavailable. That package is
CUDA/Linux-oriented, so the likely target for this exact model is Space/ZeroGPU
or Modal rather than local Mac execution.

`nvidia/Llama-3.1-Nemotron-Nano-4B-v1.1` avoided the `mamba-ssm` import path,
but local smoke was interrupted after 3m47s while fetching two checkpoint
shards. Treat local Mac execution as non-critical; the real model smoke should
run on the deployment GPU path.