docs/WRITER.md

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:

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

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

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:

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.