Heavy File Ingestion Claude Code

1. If dependencies are missing, prefer:

uv run \
  --with pdfplumber \
  --with python-docx \
  --with python-pptx \
  --with openpyxl \
  python scripts/convert_heavy_file.py /absolute/path/to/file.ext

1. Read the generated index.md before reading any converted artifact.
2. Use the index to decide the cheapest next step:
   • read_extracted_artifact: read the markdown or CSV and continue
   • install_dependency_and_retry: install the missing deterministic dependency and rerun
   • cheap_model_or_stronger_converter: retry with a better converter or use a cheaper model only on the extracted artifact
3. Only escalate to a stronger model after the file has already been compressed into markdown, CSV, or a short sampled subset.

Client Rules

• Prefer deterministic scripts over model-based conversion.
• Save the converted artifacts next to the source file and work from those files.
• For spreadsheets, use the generated per-sheet CSV files instead of trying to reason over workbook internals directly.
• For PDFs, treat scan detection and low-density warnings as a routing signal, not as a reason to read the original PDF raw.

Bundled References

• references/open-source-stack.md explains the tool choices and fallback strategy.