litellm/litellm-rust/AGENTS.md

Rust workspace rules

For diagnostic tracing changes, follow .agents/skills/rust-tracing/SKILL.md

For string-valued enums and their Serde conversions, follow .agents/skills/rust-string-enums/SKILL.md

For fieldless enums, derive strum::VariantArray and use VARIANTS instead of a hand-listed ALL array. Derive Strum string conversions instead of hand-written variant-to-string matches

Use the derived conversions directly (<&'static str>::from(x) / .into(), str::parse) with no as_str/parse wrapper that only delegates, and spell each variant with explicit #[strum(serialize = "...")] instead of serialize_all

Test placement

• Never create a tests.rs (or test.rs) file under src/, and never #[path = "tests.rs"] mod tests;
• Tests live inline by default, in a #[cfg(test)] mod tests { ... } at the bottom of the file that owns the code under test, whether or not they touch private items
• crates/<crate>/tests/ is only for tests that drive several modules together end to end, such as a full request through a route. A test of one type or function never goes there
• A helper shared by several inline test modules goes in a #[cfg(test)] mod test_support; at the crate root, and only once a second module needs it
• A test for another crate's item belongs in that crate, not in a downstream one
• Tests that call a real provider go in crates/<crate>/tests/live/<provider>.rs behind a tests/live/main.rs. Each reads the provider's key from the environment through an Option fixture and returns early when it is unset, never #[ignore], so cargo test stays offline until the key is exported
• Never set autotests = false or hand-list [[test]] targets. Every file directly under tests/ is discovered by cargo, and a shared helper goes in tests/<name>/mod.rs or tests/<subject>/support.rs so it is not picked up as a test crate of its own

Test fixtures and cases

Use #[rstest] for new and updated tests and #[fixture] for reusable setup, injected through typed test arguments. Express input variations as named #[case::name(...)] cases instead of loops or duplicated tests so each failure identifies its case. Keep behavior assertions in the test body and fixtures focused on setup. Use the workspace rstest dependency

• Never loop over inputs (for, .iter().for_each, .all) inside a test body. Give each input its own #[case::name(...)], or use #[values(...)] for a cross product
• Exception: a test pinning a Rust table against a repo-owned data file (for example include_str! of a JSON config) may iterate that file's entries

Error definitions

• A crate's errors live in src/error.rs, defined with thiserror, and re-exported from lib.rs
• Put message templates in the variant's #[error(...)] declaration. Callers pass only the small typed arguments needed to fill them, never Error::Variant(format!(...)) or a preformatted message. Keep the smallest set of neutral variants that callers need to distinguish. Different wording or providers do not justify new variants
• Default to one top-level Error enum per crate, with one variant per failure mode and a #[error(...)] message on each. A failure mode is something a caller handles differently (phase, status code, retry, a message Python parity pins exactly). Failures no caller tells apart share one variant and differ only in its message
• Keep shared error enums minimal and provider-neutral. Provider names, credential types, configuration fields, and setup guidance belong in caller-supplied data, not dedicated variants or hardcoded shared messages. Reuse a variant for the same failure mode across providers, such as MissingApiBase { provider: "Azure", guidance: "..." }. An exact parity message does not justify a provider-specific variant when caller-supplied context can preserve it
• Wrap a lower-level error as a variant with #[from] or #[source] instead of flattening it to a string
• Exception: split into separate types when different functions fail in disjoint ways, especially when different callers see them. A shared enum would force every caller to match variants its function can never return
• Name a split type after what went wrong (a unit struct is fine for a single failure mode), not after the function that returns it