diff --git a/litellm-rust/.agents/skills/rust-string-enums/SKILL.md b/litellm-rust/.agents/skills/rust-string-enums/SKILL.md new file mode 100644 index 00000000000..fc6988639d0 --- /dev/null +++ b/litellm-rust/.agents/skills/rust-string-enums/SKILL.md @@ -0,0 +1,66 @@ +--- +name: rust-string-enums +description: Define or refactor Rust string-valued enums and their Serde adapters in litellm-rust, using Strum and serde_with while preserving parsing, wire values, and schemas +--- + +# Rust string enums + +Use this skill when adding or changing enums represented by a single string, or surveying handwritten string conversions + +## Choose the representation + +For an enum with fixed spellings and an unknown-string fallback, prefer `strum::EnumString` and `strum::Display` together with `serde_with::DeserializeFromStr` and `serde_with::SerializeDisplay`. Keep each wire spelling in the Strum attributes instead of repeating it in a handwritten Serde match + +Strum implements string conversion traits, not Serde traits. `EnumString` implements `FromStr`; `Display` formats the wire string. The two `serde_with` derives connect those traits to Serde. `AsRefStr` provides a borrowed string accessor and is optional + +```rust +#[derive( + Clone, + Debug, + PartialEq, + Eq, + strum::AsRefStr, + strum::EnumString, + strum::Display, + serde_with::DeserializeFromStr, + serde_with::SerializeDisplay, +)] +#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))] +#[cfg_attr(feature = "schema", schemars(from = "String", into = "String"))] +pub enum EventType { + #[strum(serialize = "event.created")] + Created, + #[strum(default, transparent)] + Other(String), +} +``` + +Use `#[strum(serialize_all = "snake_case")]` or another supported case style when it exactly matches the contract. Use explicit variant spellings otherwise. With multiple accepted aliases, set `to_string` to the existing canonical output: Strum Display otherwise selects the longest `serialize` spelling + +Use only the derives the contract needs. A deserialize-only type should remain deserialize-only. Do not add an unknown variant to a closed enum, or derive Serde for a type that currently has no serialization contract + +Plain Serde derives with `rename` or `rename_all` remain appropriate for closed unit enums. Adding Strum and serde_with solely to replace working Serde derives adds little value. When a type has both Serde and Strum parsing, compare their accepted inputs before sharing the parser: case-insensitive Strum parsing must not silently make strict JSON parsing case-insensitive + +## Preserve behavior during migration + +Read the type, its callers, and existing tests before changing it. Preserve canonical output, accepted aliases, case sensitivity, whitespace handling, unknown values, malformed-input rejection, and existing public conversion APIs. Keep conversions needed by callers or compatibility even when Serde no longer uses them + +Use the workspace dependencies and enable `serde_with.workspace = true` in a crate only when needed. Check the versions and enabled features in `Cargo.toml` and `Cargo.lock` rather than upgrading dependencies for this refactor + +Remove replaced manual Serde implementations and obsolete Serde conversion attributes. Do not combine the new derives with `wire_type`, `request_type`, or `response_type` aliases that already derive the same Serde traits. Expand the necessary non-Serde derives and schema attributes locally rather than changing shared aliases for unrelated types + +Preserve the generated schema, including titles and definition names. Open string enums need a string schema, including unknown values. When replacing Serde `from`/`into` attributes that previously supplied that schema, retain their schema behavior with `#[cfg_attr(feature = "schema", schemars(from = "String", into = "String"))]` and compare the full generated result. `schemars(with = "String")` also makes a string schema, but changes the schema name and title, so keep it only where it already matches the contract + +Keep custom `FromStr` and `Display` implementations for structured strings or validation that Strum does not express faithfully. Their Serde adapters can still use `DeserializeFromStr` and `SerializeDisplay`. Do not replace JSON visitors, tagged payload enums, permissive value wrappers, or domain transformations with string parsing + +For a requested survey, document candidates and exceptions without migrating source. If the user asks to approve a bulk migration, present the concrete scope and wait for that approval + +## Verify the contract + +Extend existing mapped tests with named `rstest` cases. Assert both parsing into the expected variant and serialization to the expected wire string. Include unknown and empty strings for open enums, accepted aliases when present, and rejection of non-string JSON. A decode-only assertion does not prove a round trip + +Test structured parsers with valid and invalid payloads, including their existing error behavior. For types with schema support, check the string schema and run the affected crate tests with the schema feature enabled. Run affected downstream checks when conversion APIs or derive aliases change + +## Upstream references + +The workspace used Strum 0.28.0 and serde_with 3.16.1 when this guidance was written. Consult the matching version of the [EnumString docs](https://docs.rs/strum/0.28.0/strum/derive.EnumString.html), [Display docs](https://docs.rs/strum_macros/0.28.0/strum_macros/derive.Display.html), [DeserializeFromStr docs](https://docs.rs/serde_with/3.16.1/serde_with/derive.DeserializeFromStr.html), and [SerializeDisplay docs](https://docs.rs/serde_with/3.16.1/serde_with/derive.SerializeDisplay.html). Schemars documents [schema overrides and Serde conversion attributes](https://docs.rs/schemars/1.2.2/schemars/derive.JsonSchema.html) diff --git a/litellm-rust/AGENTS.md b/litellm-rust/AGENTS.md index fe0aac56f0c..442dfd8e957 100644 --- a/litellm-rust/AGENTS.md +++ b/litellm-rust/AGENTS.md @@ -2,6 +2,8 @@ For diagnostic tracing changes, follow [.agents/skills/rust-tracing/SKILL.md](.agents/skills/rust-tracing/SKILL.md) +For string-valued enums and their Serde conversions, follow [.agents/skills/rust-string-enums/SKILL.md](.agents/skills/rust-string-enums/SKILL.md) + ## Test placement - Never create a `tests.rs` (or `test.rs`) file under `src/`, and never `#[path = "tests.rs"] mod tests;` diff --git a/litellm-rust/Cargo.lock b/litellm-rust/Cargo.lock index a1f25cde57b..0c78b43cb2f 100644 --- a/litellm-rust/Cargo.lock +++ b/litellm-rust/Cargo.lock @@ -4450,6 +4450,7 @@ dependencies = [ "schemars 1.2.2", "serde", "serde_json", + "serde_with", "strum", "thiserror 2.0.19", "time", diff --git a/litellm-rust/crates/llms-types/src/formats/messages/request.rs b/litellm-rust/crates/llms-types/src/formats/messages/request.rs index d14e9afd0c3..16cc55e4f5a 100644 --- a/litellm-rust/crates/llms-types/src/formats/messages/request.rs +++ b/litellm-rust/crates/llms-types/src/formats/messages/request.rs @@ -18,9 +18,18 @@ pub enum MessageContent { Blocks(Vec), } -#[macro_rules_attribute::apply(wire_type)] -#[derive(Eq, strum::Display, strum::EnumString)] -#[serde(from = "String", into = "String")] +#[derive( + Clone, + Debug, + PartialEq, + Eq, + strum::Display, + strum::EnumString, + serde_with::DeserializeFromStr, + serde_with::SerializeDisplay, +)] +#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))] +#[cfg_attr(feature = "schema", schemars(from = "String", into = "String"))] #[strum(serialize_all = "snake_case")] pub enum ContentBlockType { Text, diff --git a/litellm-rust/crates/llms-types/src/formats/responses/streaming_websocket.rs b/litellm-rust/crates/llms-types/src/formats/responses/streaming_websocket.rs index 75858b45223..6b648a21bd1 100644 --- a/litellm-rust/crates/llms-types/src/formats/responses/streaming_websocket.rs +++ b/litellm-rust/crates/llms-types/src/formats/responses/streaming_websocket.rs @@ -1,7 +1,16 @@ -use serde::{Deserialize, Deserializer, Serialize, Serializer}; use serde_json::{Map, Value}; -#[derive(Clone, Debug, PartialEq, Eq, strum::AsRefStr)] +#[derive( + Clone, + Debug, + PartialEq, + Eq, + strum::AsRefStr, + strum::EnumString, + strum::Display, + serde_with::DeserializeFromStr, + serde_with::SerializeDisplay, +)] #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))] #[cfg_attr(feature = "schema", schemars(with = "String"))] pub enum ResponsesWsEventType { @@ -27,33 +36,6 @@ impl ResponsesWsEventType { } } -impl Serialize for ResponsesWsEventType { - fn serialize(&self, serializer: S) -> Result - where - S: Serializer, - { - serializer.serialize_str(self.as_str()) - } -} - -impl<'de> Deserialize<'de> for ResponsesWsEventType { - fn deserialize(deserializer: D) -> Result - where - D: Deserializer<'de>, - { - let value = String::deserialize(deserializer)?; - Ok(match value.as_str() { - "response.create" => Self::ResponseCreate, - "response.created" => Self::ResponseCreated, - "response.completed" => Self::ResponseCompleted, - "response.failed" => Self::ResponseFailed, - "response.incomplete" => Self::ResponseIncomplete, - "error" => Self::Error, - _ => Self::Other(value), - }) - } -} - #[macro_rules_attribute::apply(wire_type)] pub struct ResponsesWsEvent { #[serde(rename = "type")] @@ -114,21 +96,6 @@ mod tests { use super::*; - #[rstest] - #[case::known("response.completed", ResponsesWsEventType::ResponseCompleted)] - #[case::unknown( - "response.output_text.delta", - ResponsesWsEventType::Other("response.output_text.delta".to_string()) - )] - fn event_type_round_trips_known_and_unknown_values( - #[case] value: &str, - #[case] expected: ResponsesWsEventType, - ) { - let actual: ResponsesWsEventType = - serde_json::from_str(&serde_json::to_string(value).unwrap()).expect("valid event type"); - assert_eq!(actual, expected); - } - #[test] fn error_frame_matches_proxy_shape() { let frame = ResponsesErrorFrame::invalid_request("missing model"); diff --git a/litellm-rust/crates/llms-types/tests/messages_request.rs b/litellm-rust/crates/llms-types/tests/messages_request.rs index 4ebc196fb12..a0515c21459 100644 --- a/litellm-rust/crates/llms-types/tests/messages_request.rs +++ b/litellm-rust/crates/llms-types/tests/messages_request.rs @@ -2,6 +2,27 @@ use litellm_llms_types::formats::messages::{ContentBlock, ContentBlockType}; use rstest::rstest; use serde_json::{Value, json}; +#[rstest] +#[case::null(json!(null))] +#[case::number(json!(1))] +#[case::boolean(json!(true))] +#[case::array(json!(["tool_use"]))] +#[case::object(json!({"type": "tool_use"}))] +fn content_block_type_rejects_non_string_json(#[case] value: Value) { + assert!(serde_json::from_value::(value).is_err()); +} + +#[cfg(feature = "schema")] +#[rstest] +fn content_block_type_schema_remains_a_string() { + let schema = schemars::schema_for!(ContentBlockType).to_value(); + assert_eq!(schema.get("type"), Some(&json!("string"))); + assert_eq!( + schema.get("title"), + Some(&json!(stringify!(ContentBlockType))) + ); +} + #[rstest] #[case::text("text", ContentBlockType::Text)] #[case::thinking("thinking", ContentBlockType::Thinking)] diff --git a/litellm-rust/crates/llms-types/tests/responses.rs b/litellm-rust/crates/llms-types/tests/responses.rs new file mode 100644 index 00000000000..92271757b3f --- /dev/null +++ b/litellm-rust/crates/llms-types/tests/responses.rs @@ -0,0 +1,48 @@ +use litellm_llms_types::formats::responses::streaming_websocket::ResponsesWsEventType; +use rstest::rstest; + +#[rstest] +#[case::create("response.create", ResponsesWsEventType::ResponseCreate)] +#[case::created("response.created", ResponsesWsEventType::ResponseCreated)] +#[case::completed("response.completed", ResponsesWsEventType::ResponseCompleted)] +#[case::failed("response.failed", ResponsesWsEventType::ResponseFailed)] +#[case::incomplete("response.incomplete", ResponsesWsEventType::ResponseIncomplete)] +#[case::error("error", ResponsesWsEventType::Error)] +#[case::unknown( + "response.output_text.delta", + ResponsesWsEventType::Other("response.output_text.delta".to_string()) +)] +#[case::empty("", ResponsesWsEventType::Other(String::new()))] +#[case::case_sensitive( + "Response.Completed", + ResponsesWsEventType::Other("Response.Completed".into()) +)] +#[case::escaped("future\"\\\n", ResponsesWsEventType::Other("future\"\\\n".into()))] +fn websocket_event_type_round_trips(#[case] wire: &str, #[case] expected: ResponsesWsEventType) { + let serialized = serde_json::to_string(&expected).unwrap(); + assert_eq!(serialized, serde_json::to_string(wire).unwrap()); + assert_eq!( + serde_json::from_str::(&serialized).unwrap(), + expected + ); +} + +#[rstest] +#[case::number("17")] +#[case::boolean("true")] +#[case::null("null")] +#[case::array("[]")] +#[case::object("{}")] +fn websocket_event_type_rejects_non_strings(#[case] wire: &str) { + assert!(serde_json::from_str::(wire).is_err()); +} + +#[cfg(feature = "schema")] +#[rstest] +fn websocket_event_type_schema_is_open_string() { + let schema = schemars::schema_for!(ResponsesWsEventType); + assert_eq!( + schema.to_value().get("type"), + Some(&serde_json::json!("string")) + ); +} diff --git a/litellm-rust/crates/llms/src/azure_ai/ocr/document_intelligence/transformation.rs b/litellm-rust/crates/llms/src/azure_ai/ocr/document_intelligence/transformation.rs index ab273d9dbe9..2a50989f4e4 100644 --- a/litellm-rust/crates/llms/src/azure_ai/ocr/document_intelligence/transformation.rs +++ b/litellm-rust/crates/llms/src/azure_ai/ocr/document_intelligence/transformation.rs @@ -6,7 +6,7 @@ use litellm_auth_azure::{AzureAuthInputs, SECRET_NAMES as AZURE_AUTH_SECRET_NAME use litellm_core_utils::{call_arguments::CallArguments, url_utils::ApiUrl}; use litellm_llms_types::serde_compat::{FiniteF64, LaxI64}; use reqwest::Url; -use serde::{Deserialize, Deserializer, Serialize}; +use serde::{Deserialize, Serialize}; use serde_json::{Map, Value}; use serde_with::serde_as; use tokio::time::Instant; @@ -54,39 +54,22 @@ pub enum DocumentIntelligenceRequest { }, } -#[derive(Clone, Debug, PartialEq)] +#[derive( + Clone, Debug, PartialEq, strum::EnumString, strum::Display, serde_with::DeserializeFromStr, +)] enum OperationStatus { + #[strum(serialize = "succeeded")] Succeeded, + #[strum(serialize = "running")] Running, + #[strum(serialize = "notStarted")] NotStarted, + #[strum(serialize = "failed")] Failed, + #[strum(default, transparent)] Unknown(String), } -impl<'de> Deserialize<'de> for OperationStatus { - fn deserialize>(deserializer: D) -> Result { - Ok(match String::deserialize(deserializer)?.as_str() { - "succeeded" => Self::Succeeded, - "running" => Self::Running, - "notStarted" => Self::NotStarted, - "failed" => Self::Failed, - value => Self::Unknown(value.to_string()), - }) - } -} - -impl std::fmt::Display for OperationStatus { - fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - formatter.write_str(match self { - Self::Succeeded => "succeeded", - Self::Running => "running", - Self::NotStarted => "notStarted", - Self::Failed => "failed", - Self::Unknown(value) => value, - }) - } -} - #[derive(Clone, Debug, Deserialize)] pub struct AzureDocumentIntelligenceOperation { status: Option, @@ -671,6 +654,43 @@ mod tests { use super::*; + #[rstest] + #[case::succeeded("succeeded", OperationStatus::Succeeded)] + #[case::running("running", OperationStatus::Running)] + #[case::not_started("notStarted", OperationStatus::NotStarted)] + #[case::failed("failed", OperationStatus::Failed)] + fn operation_status_parses_known_values( + #[case] input: &str, + #[case] expected: OperationStatus, + ) { + let parsed = serde_json::from_value::(json!(input)).unwrap(); + + assert_eq!(parsed, expected); + assert_eq!(parsed.to_string(), input); + } + + #[rstest] + #[case::unknown("queued")] + #[case::case_sensitive("NotStarted")] + #[case::escaped("future\"\\\n")] + #[case::empty("")] + fn operation_status_preserves_unknown_values(#[case] input: &str) { + let parsed = serde_json::from_value::(json!(input)).unwrap(); + + assert_eq!(parsed, OperationStatus::Unknown(input.into())); + assert_eq!(parsed.to_string(), input); + } + + #[rstest] + #[case::number(json!(1))] + #[case::boolean(json!(true))] + #[case::array(json!([]))] + #[case::null(Value::Null)] + #[case::object(json!({"status": "succeeded"}))] + fn operation_status_rejects_non_string_json(#[case] input: Value) { + assert!(serde_json::from_value::(input).is_err()); + } + fn map(value: Value) -> Result { let arguments = serde_json::from_value(value).unwrap(); AzureDocumentIntelligenceOcrConfig.map_ocr_params(&arguments, "model") diff --git a/litellm-rust/crates/traces/Cargo.toml b/litellm-rust/crates/traces/Cargo.toml index 12bb55551c3..05c3cc2aee9 100644 --- a/litellm-rust/crates/traces/Cargo.toml +++ b/litellm-rust/crates/traces/Cargo.toml @@ -18,6 +18,7 @@ opentelemetry-proto = { workspace = true, features = ["gen-tonic-messages", "tra prost.workspace = true serde = { workspace = true, features = ["rc"] } serde_json = { workspace = true, features = ["preserve_order"] } +serde_with.workspace = true strum.workspace = true thiserror.workspace = true time.workspace = true diff --git a/litellm-rust/crates/traces/src/normalize/metadata.rs b/litellm-rust/crates/traces/src/normalize/metadata.rs index 1994dcf3129..100008714c5 100644 --- a/litellm-rust/crates/traces/src/normalize/metadata.rs +++ b/litellm-rust/crates/traces/src/normalize/metadata.rs @@ -15,9 +15,15 @@ pub enum AgentType { } #[derive( - Clone, Debug, Eq, PartialEq, Serialize, Deserialize, strum::EnumString, strum::Display, + Clone, + Debug, + Eq, + PartialEq, + strum::EnumString, + strum::Display, + serde_with::DeserializeFromStr, + serde_with::SerializeDisplay, )] -#[serde(from = "String", into = "String")] #[strum(serialize_all = "kebab-case")] pub enum Integration { ClaudeCode, diff --git a/litellm-rust/crates/traces/src/normalize/mod.rs b/litellm-rust/crates/traces/src/normalize/mod.rs index c3ad76fde02..fa35e1d6795 100644 --- a/litellm-rust/crates/traces/src/normalize/mod.rs +++ b/litellm-rust/crates/traces/src/normalize/mod.rs @@ -10,7 +10,7 @@ use std::{ }; use crate::{Error, otlp::DecodedEvent}; -use serde::{Deserialize, Serialize, Serializer}; +use serde::{Deserialize, Serialize}; mod format; mod instrumentation; @@ -44,8 +44,16 @@ pub enum ObservationType { } /// A model request a span stands for, by the identifier its instrumentation recorded. -#[derive(Clone, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd)] -#[serde(try_from = "String")] +#[derive( + Clone, + Debug, + Eq, + Ord, + PartialEq, + PartialOrd, + serde_with::DeserializeFromStr, + serde_with::SerializeDisplay, +)] pub enum CallKey { /// LiteLLM's gateway call id, with a fallback to legacy spend request ids. LiteLlmRequest(String), @@ -101,12 +109,6 @@ pub enum CallEvidenceKind { Complete, } -impl Serialize for CallKey { - fn serialize(&self, serializer: S) -> Result { - serializer.collect_str(self) - } -} - /// Which model requests a span accounts for. `Complete` comes only from an instrumentation's known /// contract (one chat span is one response), never from how many ids happened to be found. #[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)] diff --git a/litellm-rust/crates/traces/tests/normalize.rs b/litellm-rust/crates/traces/tests/normalize.rs index ccc0c3bb224..923e2006088 100644 --- a/litellm-rust/crates/traces/tests/normalize.rs +++ b/litellm-rust/crates/traces/tests/normalize.rs @@ -1,4 +1,4 @@ -use litellm_traces::{DecodedSpan, ObservationType, decode_otlp}; +use litellm_traces::{DecodedSpan, Integration, ObservationType, decode_otlp}; use rstest::rstest; use serde_json::Value; @@ -101,6 +101,38 @@ fn assert_invariants(span: &DecodedSpan) { } } +#[rstest] +#[case::known("claude-code", Integration::ClaudeCode)] +#[case::unknown("future-agent", Integration::Other("future-agent".to_owned()))] +#[case::case_sensitive("Claude-Code", Integration::Other("Claude-Code".to_owned()))] +#[case::empty("", Integration::Other(String::new()))] +#[case::escaped_unknown( + "future\"agent\\path\nnext", + Integration::Other("future\"agent\\path\nnext".to_owned()) +)] +fn integration_string_round_trips(#[case] input: &str, #[case] expected: Integration) { + assert_eq!( + serde_json::from_value::(serde_json::json!(input)).unwrap(), + expected + ); + assert_eq!( + serde_json::to_value(&expected).unwrap(), + serde_json::json!(input) + ); + assert_eq!(Integration::from(input.to_owned()), expected); + assert_eq!(String::from(expected), input); +} + +#[rstest] +#[case::null("null")] +#[case::number("42")] +#[case::boolean("true")] +#[case::array("[]")] +#[case::object("{}")] +fn integration_rejects_non_string_json(#[case] input: &str) { + assert!(serde_json::from_str::(input).is_err()); +} + fn array<'a>(value: &'a Value, key: &str) -> &'a [Value] { value .get(key) @@ -260,6 +292,10 @@ fn call_keys_round_trip_through_storage(#[case] key: litellm_traces::CallKey) { key ); let encoded = serde_json::to_string(&key).unwrap(); + assert_eq!( + serde_json::from_str::(&encoded).unwrap(), + serde_json::json!(key.to_string()) + ); assert_eq!( serde_json::from_str::(&encoded).unwrap(), key @@ -278,3 +314,12 @@ fn malformed_call_keys_are_rejected_at_the_boundary(#[case] encoded: &str) { assert!(encoded.parse::().is_err()); assert!(serde_json::from_value::(serde_json::json!(encoded)).is_err()); } + +#[rstest] +#[case::null(serde_json::Value::Null)] +#[case::number(serde_json::json!(42))] +#[case::object(serde_json::json!({}))] +#[case::array(serde_json::json!([]))] +fn call_keys_reject_non_string_json(#[case] value: Value) { + assert!(serde_json::from_value::(value).is_err()); +}