Improve math tutorial README documentation

[lbliii]

Description

Addresses documentation gaps in the math data curation pipeline tutorial README, based on feedback from internal review. Changes include:

• Added platform requirements (vLLM x86_64 Linux only), GPU VRAM needs (≥20 GB), and compatible GPU list (A100, A40, L40, L40S, H100)
• Added AWS credential setup section and improved HuggingFace token guidance with common error notes
• Documented all 12 available prompts (was only 2) with selection guidance, organized into cleaning, classification, and MIND dialogue categories
• Added quality score interpretation table (0–5) with threshold recommendations for Step 4
• Added LSH parameter table with tuning guidance and similarity threshold formula for Step 5
• Added compact horizontal pipeline overview and wrapped the large mermaid diagram in a collapsible section
• Added troubleshooting section covering common errors (no GPUs, 0 CC matches, auth errors, empty LLM output, all-zero scores, S3 failures, dedup issues)

Checklist

• I am familiar with the Contributing Guide.
• New or Existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

This PR significantly improves the math tutorial README with AWS credential guidance, a full listing of all 12 LLM prompts with selection guidance, quality score and LSH parameter tables, a collapsible pipeline diagram, and a troubleshooting section. Most previously flagged issues are addressed: the wrong --input deduplicated path in the Content Cleaning example is fixed, --bands_per_iteration appears in the LSH table, and AWS access is correctly described as free-but-auth-required.

Confidence Score: 5/5

Safe to merge; all remaining findings are P2 style suggestions that do not block merge.

All P0/P1 issues from prior rounds are resolved or addressed (wrong input dir fixed, bands_per_iteration added, AWS framing corrected). The two remaining findings are P2 documentation polish (missing platform details and missing MIND example command) that can be addressed in a follow-up.

No files require special attention.

Important Files Changed

Filename	Overview
tutorials/math/README.md	Comprehensive documentation improvements including AWS credentials guidance, all 12 prompts documented, LSH parameter table, quality score interpretation table, collapsible pipeline diagram, and troubleshooting section; minor gap between PR description and implemented content

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    HF([HuggingFace]) --> D[0_download]
    D --> RAW[(Raw Data)]
    RAW --> CC[1_cc_index_lookup*]
    CC --> PRE[2_text_preprocess]
    S3_CC([Common Crawl S3]) --> PRE
    PRE --> LLM[3_llm_cleanup]
    LLM --> QC[4_quality_classifier]
    QC --> DEDUP[5_deduplication]
    DEDUP --> FINAL[(Final Data)]

    note1["* Only for datasets without WARC metadata"] -.-> CC

    style HF fill:#ff9,stroke:#888
    style FINAL fill:#9f9,stroke:#888
    style S3_CC fill:#ff9,stroke:#888
    style note1 fill:#eee,stroke:#aaa,color:#555

Loading

_{Reviews (8): Last reviewed commit: "Merge branch 'main' into lbliii/math-tut..." | Re-trigger Greptile}

[greptile-apps]

Wrong input directory in Content Cleaning example

This example uses --input $MATH_DATA_DIR/deduplicated, but deduplicated is the final output of Step 5. LLM cleanup (Step 3) consumes preprocessed text from Step 2 and must run before Steps 4 and 5 — the pipeline table on line 315 and the main usage example on line 483 both confirm this ordering. Feeding deduplicated output back through LLM cleanup is logically backwards and will confuse users following this example.

Suggested change

	python tutorials/math/3_llm_cleanup.py \
	--input $MATH_DATA_DIR/preprocessed \
	--output $MATH_DATA_DIR/cleaned_code \
	--model microsoft/phi-4 \
	--prompt HTML_TO_TEXT_PROMPT_CODE \
	--chunk_data \
	--chunk_length 5000 \
	--max_model_len 16384 \
	--input_filetype jsonl

[greptile-apps]

--bands_per_iteration missing from LSH parameters table

The troubleshooting section (line 682) references --bands_per_iteration (default: 5) as a tuning knob for OOM errors, and the flag exists in 5_deduplication.py (line 75–78). Adding it to the parameters table here would make the documentation consistent and help users find it before they hit an OOM error.

Suggested change

	**LSH parameters** (tunable via command-line flags):
	The LLM cleanup step supports various specialized prompts for different mathematical content processing needs:
	| Flag | Default | Description |
	|------|---------|-------------|
	| `--char_ngrams` | 24 | Character n-gram size for MinHash. Values below 20 may produce ~5% false positives. |
	| `--num_bands` | 20 | Number of LSH bands. More bands = higher recall but slower. |
	| `--minhashes_per_band` | 13 | Hashes per band. More hashes = higher precision but lower recall. |
	| `--use_64_bit_hash` | False | Use 64-bit hash for fewer collisions on very large datasets. |
	| `--seed` | 42 | Seed for MinHash permutations (for reproducibility). |
	The similarity threshold is implicitly controlled by `num_bands` and `minhashes_per_band`. The approximate threshold is `(1/num_bands)^(1/minhashes_per_band)`. With the defaults (20 bands, 13 hashes/band), this is approximately 0.72. To detect more similar pairs (stricter dedup), increase `num_bands`; to be more lenient, decrease it.
	| Flag | Default | Description |
	|------|---------|-------------|
	| `--char_ngrams` | 24 | Character n-gram size for MinHash. Values below 20 may produce ~5% false positives. |
	| `--num_bands` | 20 | Number of LSH bands. More bands = higher recall but slower. |
	| `--minhashes_per_band` | 13 | Hashes per band. More hashes = higher precision but lower recall. |
	| `--bands_per_iteration` | 5 | Number of bands to shuffle concurrently. Reduce if you hit OOM errors. |
	| `--use_64_bit_hash` | False | Use 64-bit hash for fewer collisions on very large datasets. |
	| `--seed` | 42 | Seed for MinHash permutations (for reproducibility). |

[sarahyurick]

Thanks! Mostly looks good to me, left some minor comments. Let's see if we can get @ronjer30 and/or @raosukrit67 to review as well.

[sarahyurick]

I think this subsection can be removed. Otherwise LGTM, thanks!

[ronjer30]

Thanks @lbliii, looks good to me.

[lbliii]

Thanks @lbliii, looks good to me.

thanks for taking a look! do you have the ability to hit approve to unblock merge? if not i can find another team member

[sarahyurick]

/ok to test 6cd8a0d