Add loss functions page

[guan404ming]

Purpose

--loss-fn accepts seven losses and JSON weighted combinations, but nothing in the docs explains what they optimize or when to pick one. Adds a User Guide page, sourced from src/speculators/models/metrics.py.

• Available Losses -- one table row per loss
  • kl_div (default), rkl, jsd, ce, tv, nla, lk_hybrid
  • notes the fused Triton path for tv / nla
• Choosing a Loss -- three bullets: default, acceptance-rate optimization, hard labels / D-PACE
• Weighted Combinations -- the JSON dict syntax and per-term logging
• References -- JSD (Lin 1991) and LK Losses (arXiv 2602.23881)
• Wired into docs/.nav.yml and the User Guide index

Tests

Docs-only. mdformat --check passes.

Checklist

I have filled in:

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan/results, such as providing test command and pasting the results.
• (Optional) The necessary documentation update.
• I (a human) have written or reviewed the code in this pr to the best of my ability.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 81d46e89-8262-4772-b99a-cbb9b301fb37

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Summary

Adds documentation for training loss configuration and links the new guide from the user guide navigation and quick links.

Changes

Loss Functions Documentation

Layer / File(s)	Summary
Loss function reference and usage docs/user_guide/loss_functions.md	Documents --loss-fn, available loss functions, weighted combinations, separate logging, selection guidance, and references.
User guide navigation docs/.nav.yml, docs/user_guide/index.md	Adds the Loss Functions guide to the User Guide navigation and Quick Links.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a new loss functions documentation page.
Description check	✅ Passed	The description is directly related to the docs update and matches the files changed in the PR.
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.

✨ 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.}

[mergify]

Merge Protections

🔴 1 of 1 protections blocking · waiting on 👀 reviews

	Protection	Waiting on
🔴	Require approval from approved reviewers list	👀 reviews

🔴 Require approval from approved reviewers list

Waiting for any of

• approved-reviews-by = dsikka
• approved-reviews-by = fynnsu
• approved-reviews-by = orestis-z
• approved-reviews-by = rahul-tuli
• approved-reviews-by = shanjiaz

This rule is failing.

All pull requests must have at least one approving review from a member of the approved reviewers list before merging.

• any of:
  • approved-reviews-by = dsikka
  • approved-reviews-by = fynnsu
  • approved-reviews-by = orestis-z
  • approved-reviews-by = rahul-tuli
  • approved-reviews-by = shanjiaz

[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 `@docs/user_guide/loss_functions.md`:
- Line 33: Update the weighted-loss documentation near the compound_loss
description to state that each `{name}_loss` log records the unweighted
component loss, while weights apply only to the aggregate result. Also clarify
that resolve_loss_config uses weights exactly as provided and does not normalize
them.
- Line 23: Update the documentation statement describing fused Triton kernel
support for tv and nla to mention only CUDA tensors when the kernel is
importable, and describe eager PyTorch as the fallback; remove the unverified
ROCm claim.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ccee897a-53c9-4b42-8d5e-e972a1369185

📥 Commits

Reviewing files that changed from the base of the PR and between f5e2450 and cd8c342.

📒 Files selected for processing (3)

• docs/.nav.yml
• docs/user_guide/index.md
• docs/user_guide/loss_functions.md