added cookbook for batch api

[Baldur-Hua-ai20labs]

Adds a complete Batch API cookbook demonstrating how to tag a CSV of customer reviews overnight.

Includes:

• End-to-end flow (CSV -> JSONL -> upload -> batch -> poll -> download -> merge)
• Error handling and recovery using error_file_id
• custom_id mapping for order-safe joins
• Before/after CSV examples
• Runnable Python script
• Sample dataset and input.jsonl

Jira

Summary by CodeRabbit

• Documentation
  • Added a new cookbook tutorial: "Tag customer reviews overnight" — an end-to-end CSV batch workflow for sentiment and topic tagging, including running in Colab, uploading batches, polling/download, error handling, retry patterns, and merging results back into the original dataset while preserving row order.
  • Updated the cookbook homepage and navigation to feature the new tutorial.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added a comprehensive cookbook page documenting overnight review tagging using the ZeroGPU Batch API: setup, data schemas, JSONL formatting, complete Python implementation, error recovery patterns, and example workflows. Updated cookbook index and navigation to surface the new tutorial.

Changes

Batch API Review Tagging Cookbook

Layer / File(s)	Summary
Introduction and Colab Setup cookbook/batch-review-tagging.mdx	Introduces the overnight review-tagging use case, Colab environment setup, REST API authentication with project ID/key, and dependency installation.
Classification Schema and JSONL Request Format cookbook/batch-review-tagging.mdx	Defines JSON output contract with sentiment and topics fields, demonstrates CSV-to-JSONL transformation using custom_id keys for result merging, and documents filtering of malformed rows to prevent batch-wide rejection.
Batch API Operations and Lifecycle cookbook/batch-review-tagging.mdx	Documents complete batch workflow: uploading JSONL as purpose=batch, creating batch targeting /v1/chat/completions with 24h window, polling for terminal states, and downloading output and error files.
Core Python Implementation cookbook/batch-review-tagging.mdx	Provides full tag_reviews.py script with JSONL building, batch upload/polling, defensive JSON parsing (code-fence removal), result merging into tagged.csv (preserving original row order), and per-line error extraction to failed.csv.
Example Payloads and Expected Output cookbook/batch-review-tagging.mdx	Shows sample output lines, before/after CSV examples, demonstrates tagged.csv row-order preservation via custom_id lookups, and illustrates concrete API errors.
Error Recovery and Retry Patterns cookbook/batch-review-tagging.mdx	Covers extracting failed custom_ids from error files, filtering original JSONL for retry, and provides lookup of common per-line error codes with remediation guidance.
Recap and Key Highlights cookbook/batch-review-tagging.mdx	Summarizes end-to-end workflow components: local validation, batch submission, polling, output parsing, merging, and error recovery.
Site Navigation and Cookbook Discovery cookbook/index.mdx, docs.json	Adds tutorial card to cookbook homepage linking to batch-review-tagging and updates navigation structure for discoverability.

Sequence Diagram(s)

sequenceDiagram
participant tag_reviews.py as tag_reviews.py
participant ZeroGPU_API as /v1/chat/completions
participant BatchService as BatchService
participant Storage as Storage
tag_reviews.py->>ZeroGPU_API: upload JSONL (purpose=batch)
tag_reviews.py->>ZeroGPU_API: create batch (completion_window=24h)
tag_reviews.py->>ZeroGPU_API: poll status
BatchService->>BatchService: process rows with LFM2.5-1.2B-Instruct
BatchService->>Storage: write output file (per-line JSON)
BatchService->>Storage: write error file (per-line)
tag_reviews.py->>Storage: download output and error files
tag_reviews.py->>tag_reviews.py: parse and merge results, write tagged.csv/failed.csv

Loading

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers:

• amaan-ai20

🐇 A batch of reviews flies through the night so fast,
Tagged with sentiment by morning at last!
From CSV to model, through error and recovery's dance,
Your insights emerge—give the API a chance! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'added cookbook for batch api' directly reflects the main change: adding a new cookbook page for the Batch API with a complete end-to-end workflow for tagging customer reviews.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@cookbook/batch-review-tagging.mdx`:
- Line 609: Update the example sentence in cookbook/batch-review-tagging.mdx
(the line starting "Cap batch size by your real SLO, not the 100 MB file
limit.") to remove the impossible "a million-line batch" example and replace it
with a realistic batch size within the Batch API limits (e.g., "a 50,000-line
batch" or "a batch near the 50k-line limit") so the guidance matches the
documented 50,000-line per-batch constraint and clarifies the recommendation to
pick chunk sizes that fit the completion_window.
- Line 609: Replace the incorrect "100 MB file limit" text with the correct
Batch API limit: "200 MB (209,715,200 bytes) file limit" in the sentence that
currently reads "**Cap batch size by your real SLO, not the 100 MB file
limit.**" (update the phrase so it reads "**Cap batch size by your real SLO, not
the 200 MB (209,715,200 bytes) file limit.**") to accurately reflect the API
limit in cookbook/batch-review-tagging.mdx.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 284e6a43-2e54-4515-a801-913396281c92

📥 Commits

Reviewing files that changed from the base of the PR and between fec4c27 and 35eaf15.

⛔ Files ignored due to path filters (1)

• cookbook/batch-review-tagging/reviews.csv is excluded by !**/*.csv

📒 Files selected for processing (2)

• cookbook/batch-review-tagging.mdx
• cookbook/batch-review-tagging/input.jsonl

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

cookbook/batch-review-tagging.mdx (2)

282-310: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Validate review_id before emitting custom_id to prevent whole-batch rejection.

build_jsonl currently writes row["review_id"] directly as custom_id (Line 296) without checking non-empty/unique values. A blank or duplicate ID will fail POST /v1/batches validation and reject the entire batch.

🛠️ Suggested fix

 def build_jsonl(csv_path: str, jsonl_path: str) -> int:
"""Skip rows with an empty review; return the number of lines written."""
written = 0
+ seen_ids: set[str] = set()
with open(csv_path, encoding="utf-8") as src, \
open(jsonl_path, "w", encoding="utf-8") as dst:
reader = csv.DictReader(src)
for row in reader:
+ review_id = (row.get("review_id") or "").strip()+ if not review_id:+ print("skip row: empty review_id")+ continue+ if review_id in seen_ids:+ print(f"skip {review_id}: duplicate review_id")+ continue+ seen_ids.add(review_id)
review = (row.get("review") or "").strip()
if not review:
# Row r-007 in the sample CSV has no review text. Don't waste a
# request on it; record it as a local skip instead.
print(f"skip {row.get('review_id')}: empty review text")
continue
line = {
- "custom_id": row["review_id"],+ "custom_id": review_id,
"method": "POST",
"url": "/v1/chat/completions",

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cookbook/batch-review-tagging.mdx` around lines 282 - 310, The build_jsonl
function writes row["review_id"] directly as custom_id which can be empty or
duplicated and will cause /v1/batches to reject the entire batch; before
emitting the line in build_jsonl validate that review_id is non-empty and unique
within this run (use row.get("review_id") or fallback), if empty generate a
stable fallback ID (e.g., a UUID or "row-N" sequence) and if a duplicate is
encountered log/print a skip or append a suffix to make it unique, then use that
validated/unique value as custom_id when writing the JSONL entry.

---

537-544: ⚠️ Potential issue | 🟠 Major

Check HTTP status in errored_ids before parsing response body.

errored_ids reads requests.get(...).text without raise_for_status(), so 401/404/5xx responses can later fail as JSON parse errors instead of surfacing the real HTTP failure.

🛠️ Suggested fix

 def errored_ids(error_file_id: str) -> set[str]:
- text = requests.get(- f"{BASE}/v1/files/{error_file_id}/content", headers=HEADERS- ).text+ resp = requests.get(+ f"{BASE}/v1/files/{error_file_id}/content", headers=HEADERS+ )+ resp.raise_for_status()+ text = resp.text
return {
json.loads(line)["custom_id"]
for line in text.splitlines() if line.strip()
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@cookbook/batch-review-tagging.mdx` around lines 537 - 544, The function
errored_ids should check the HTTP response status before reading and parsing the
body; update errored_ids to capture the Response from requests.get, call
response.raise_for_status() (or check response.ok and raise a descriptive error)
before using response.text, and only then parse each non-empty line as JSON and
extract "custom_id" so 4xx/5xx/401 failures surface as HTTP errors instead of
JSON parsing errors.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@cookbook/batch-review-tagging.mdx`:
- Around line 282-310: The build_jsonl function writes row["review_id"] directly
as custom_id which can be empty or duplicated and will cause /v1/batches to
reject the entire batch; before emitting the line in build_jsonl validate that
review_id is non-empty and unique within this run (use row.get("review_id") or
fallback), if empty generate a stable fallback ID (e.g., a UUID or "row-N"
sequence) and if a duplicate is encountered log/print a skip or append a suffix
to make it unique, then use that validated/unique value as custom_id when
writing the JSONL entry.
- Around line 537-544: The function errored_ids should check the HTTP response
status before reading and parsing the body; update errored_ids to capture the
Response from requests.get, call response.raise_for_status() (or check
response.ok and raise a descriptive error) before using response.text, and only
then parse each non-empty line as JSON and extract "custom_id" so 4xx/5xx/401
failures surface as HTTP errors instead of JSON parsing errors.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 69518606-6e17-4ba0-97c0-1cd409968e2b

📥 Commits

Reviewing files that changed from the base of the PR and between 077227e and 3622ed1.

📒 Files selected for processing (3)

• cookbook/batch-review-tagging.mdx
• cookbook/index.mdx
• docs.json

💤 Files with no reviewable changes (1)

• cookbook/index.mdx

✅ Files skipped from review due to trivial changes (1)

• docs.json

[amaan-ai20]

Looks good! @Baldur-Hua-ai20labs

Waiting for the video.

[amaan-ai20]

Awesome Work! @Baldur-Hua-ai20labs