Improve core ergonomics: runtime client, deps, media safety, model dedup

A focused, non-breaking pass over four first-principles issues surfaced by
a design review. (Streaming and tool-calling are intentionally deferred to
separate follow-up PRs.)

1. Runtime-selectable client (`AnyClient`)
   `LLMClient::materialize` is generic, so the trait is not object-safe and
   `Box<dyn LLMClient>` is impossible. Add `AnyClient` — an enum over the
   concrete clients that itself implements `LLMClient` — plus a `Provider`
   enum, `from_env_for`, an env-autodetecting `from_env`, and
   `From<ConcreteClient>` impls. Gives a single `Clone + Send + Sync` type for
   picking a provider at runtime.

2. Dependency / feature hygiene + schema-only build
   - Move `chrono` to `dev-dependencies` (only examples/tests used it) so it
     leaves the public dependency closure entirely.
   - Make `base64` optional.
   - Gate the networked stack (`utils`, `media`, `openai_compatible`, the
     `reqwest`-backed `HttpError` variant, media `from_bytes`) behind an
     internal `_client` feature that the provider features enable.
   - `default-features = false, features = ["derive"]` now compiles with no
     `tokio`/`reqwest` — a dependency-light, schema-only build that still
     exposes the derive macro, `SchemaType`, `Instructor`, and `LLMClient`.

3. Media is never silently dropped
   The default `materialize_with_media` used to ignore media for clients
   without media support. It now forwards to `materialize` only when no media
   is given and otherwise returns `RStructorError::Unsupported` (new variant).
   All four built-in clients already override it, so their behavior is
   unchanged.

4. De-duplicate the per-provider `Model` enums
   Add the internal `define_model_enum!` macro that generates each provider's
   `Model` enum plus `as_str`, `from_string`, `FromStr`, `From<&str>` and
   `From<String>`. Replaces ~60 lines of identical boilerplate in each of the
   four backends with a single declaration; behavior and string identifiers
   are unchanged.

Adds tests for the media default and `AnyClient`; verified across the full
feature matrix (default, schema-only, and each single provider),
`clippy --all-targets`, doctests (0 ignored), and the non-network suites.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: clifton

Cargo.toml

@@ -59,18 +59,28 @@ tracing-subscriber = { version = "0.3.23", features = [
 ], optional = true }
 tracing-futures = { version = "0.2.5", optional = true }
 rstructor_derive = { version = "0.2.11", path = "./rstructor_derive", optional = true }
-chrono = "0.4.44" # For date/time validation in examples
-base64 = "0.22.1"
+base64 = { version = "0.22.1", optional = true }
 
 # Feature flags
 [features]
 default = ["openai", "anthropic", "grok", "gemini", "derive", "logging"]
-openai = ["reqwest", "tokio"]
-anthropic = ["reqwest", "tokio"]
-grok = ["reqwest", "tokio"]
-gemini = ["reqwest", "tokio"]
+# Each provider pulls in the shared networking + media stack via `_client`.
+openai = ["_client"]
+anthropic = ["_client"]
+grok = ["_client"]
+gemini = ["_client"]
 derive = ["rstructor_derive"]
 logging = ["tracing-subscriber", "tracing-futures"]
+# Internal: the HTTP client + media stack shared by every networked provider.
+# Not meant to be enabled directly — enable a provider feature instead. Disabling
+# all providers yields a dependency-light, schema-only build (derive + schema, no
+# tokio/reqwest) suitable for generating JSON Schema without making API calls.
+_client = ["reqwest", "tokio", "base64"]
+
+[dev-dependencies]
+# Used only by examples and tests (date/time fields, custom types); not part of
+# the public dependency closure.
+chrono = { version = "0.4.44", features = ["serde"] }
 
 [workspace]
 members = ["rstructor_derive"]

README.md

@@ -79,6 +79,25 @@ let client = OpenAIClient::new("key")?
     .model("llama-3.1-70b");
 ```
 
+### Selecting a provider at runtime
+
+`LLMClient::materialize` is generic, so the trait isn't object-safe (`Box<dyn LLMClient>` is impossible). Use `AnyClient` when the provider is decided at runtime (CLI flag, config, env) and you want to store it in a single type:
+
+```rust
+use rstructor::{AnyClient, Provider, LLMClient};
+
+// Pick a provider dynamically, reading its key from the environment.
+let provider = Provider::Anthropic; // e.g. parsed from a config file
+let client = AnyClient::from_env_for(provider)?;
+let movie: Movie = client.materialize("Describe Inception").await?;
+
+// Or auto-detect from whichever API key is set:
+let client = AnyClient::from_env()?;
+
+// Or wrap a pre-configured client:
+let client: AnyClient = OpenAIClient::from_env()?.model("gpt-5.5").into();
+```
+
 ## Validation
 
 Add custom validation with automatic retry on failure:
@@ -313,10 +332,19 @@ match client.materialize::<Movie>("...").await {
 rstructor = { version = "0.2", features = ["openai", "anthropic", "grok", "gemini"] }
 ```
 
-- `openai`, `anthropic`, `grok`, `gemini` — Provider backends
+- `openai`, `anthropic`, `grok`, `gemini` — Provider backends (each pulls in the shared HTTP/`tokio` stack)
 - `derive` — Derive macro (default)
 - `logging` — Tracing integration
 
+All features are on by default. For a **schema-only build** — generate JSON Schema from your types with no networking, `tokio`, or `reqwest` — disable the providers:
+
+```toml
+[dependencies]
+rstructor = { version = "0.2", default-features = false, features = ["derive"] }
+```
+
+This keeps the derive macro, `SchemaType`, the `Instructor` trait, and the `LLMClient` trait (so you can implement your own backend) without the async/HTTP dependency tree.
+
 ## Examples
 
 See `examples/` for complete working examples:

src/backend/anthropic.rs

@@ -2,10 +2,10 @@ use async_trait::async_trait;
 use serde::de::DeserializeOwned;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
-use std::str::FromStr;
 use std::time::Duration;
 use tracing::{debug, error, info, instrument, trace, warn};
 
+use crate::backend::model_macro::define_model_enum;
 use crate::backend::{
     AnthropicMessageContent, ChatMessage, GenerateResult, LLMClient, MaterializeInternalOutput,
     MaterializeResult, ModelInfo, ThinkingLevel, TokenUsage, ValidationFailureContext,
@@ -16,110 +16,50 @@ use crate::backend::{
 use crate::error::{ApiErrorKind, RStructorError, Result};
 use crate::model::Instructor;
 
-/// Anthropic models available for completion
-///
-/// For the latest available models and their identifiers, check the
-/// [Anthropic Models Documentation](https://docs.anthropic.com/en/docs/about-claude/models/all-models).
-///
-/// # Using Custom Models
-///
-/// You can specify any model name as a string using `Custom` variant or `FromStr`:
-///
-/// ```rust
-/// use rstructor::AnthropicModel;
-/// use std::str::FromStr;
-///
-/// // Using Custom variant
-/// let model = AnthropicModel::Custom("claude-custom".to_string());
-///
-/// // Using FromStr (useful for config files)
-/// let model = AnthropicModel::from_str("claude-custom").unwrap();
-///
-/// // Or use the convenience method
-/// let model = AnthropicModel::from_string("claude-custom");
-/// ```
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum AnthropicModel {
-    /// Claude Opus 4.8 (latest most capable generally available model)
-    ClaudeOpus48,
-    /// Claude Opus 4.7 (previous most capable model)
-    ClaudeOpus47,
-    /// Claude Sonnet 4.6 (latest balanced model)
-    ClaudeSonnet46,
-    /// Claude Opus 4.6 (previous most capable model)
-    ClaudeOpus46,
-    /// Claude Opus 4.5 (enhanced Opus 4.5)
-    ClaudeOpus45,
-    /// Claude Haiku 4.5 (latest fastest model)
-    ClaudeHaiku45,
-    /// Claude Sonnet 4.5 (previous balanced model)
-    ClaudeSonnet45,
-    /// Claude Opus 4.1 (enhanced reasoning capabilities)
-    ClaudeOpus41,
-    /// Claude Opus 4 (high-intelligence model)
-    ClaudeOpus4,
-    /// Claude Sonnet 4 (balanced performance model)
-    ClaudeSonnet4,
-    /// Custom model name (for new models or Anthropic-compatible endpoints)
-    Custom(String),
-}
-
-impl AnthropicModel {
-    pub fn as_str(&self) -> &str {
-        match self {
-            AnthropicModel::ClaudeOpus48 => "claude-opus-4-8",
-            AnthropicModel::ClaudeOpus47 => "claude-opus-4-7",
-            AnthropicModel::ClaudeSonnet46 => "claude-sonnet-4-6",
-            AnthropicModel::ClaudeOpus46 => "claude-opus-4-6",
-            AnthropicModel::ClaudeOpus45 => "claude-opus-4-5-20251101",
-            AnthropicModel::ClaudeHaiku45 => "claude-haiku-4-5-20251001",
-            AnthropicModel::ClaudeSonnet45 => "claude-sonnet-4-5-20250929",
-            AnthropicModel::ClaudeOpus41 => "claude-opus-4-1-20250805",
-            AnthropicModel::ClaudeOpus4 => "claude-opus-4-20250514",
-            AnthropicModel::ClaudeSonnet4 => "claude-sonnet-4-20250514",
-            AnthropicModel::Custom(name) => name,
-        }
-    }
-
-    /// Create a model from a string. This is a convenience method that always succeeds.
+define_model_enum! {
+    /// Anthropic models available for completion
     ///
-    /// If the string matches a known model variant, it returns that variant.
-    /// Otherwise, it returns `Custom(name)`.
-    pub fn from_string(name: impl Into<String>) -> Self {
-        let name = name.into();
-        match name.as_str() {
-            "claude-opus-4-8" => AnthropicModel::ClaudeOpus48,
-            "claude-opus-4-7" => AnthropicModel::ClaudeOpus47,
-            "claude-sonnet-4-6" => AnthropicModel::ClaudeSonnet46,
-            "claude-opus-4-6" => AnthropicModel::ClaudeOpus46,
-            "claude-opus-4-5-20251101" => AnthropicModel::ClaudeOpus45,
-            "claude-haiku-4-5-20251001" => AnthropicModel::ClaudeHaiku45,
-            "claude-sonnet-4-5-20250929" => AnthropicModel::ClaudeSonnet45,
-            "claude-opus-4-1-20250805" => AnthropicModel::ClaudeOpus41,
-            "claude-opus-4-20250514" => AnthropicModel::ClaudeOpus4,
-            "claude-sonnet-4-20250514" => AnthropicModel::ClaudeSonnet4,
-            _ => AnthropicModel::Custom(name),
-        }
-    }
-}
-
-impl FromStr for AnthropicModel {
-    type Err = std::convert::Infallible;
-
-    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
-        Ok(AnthropicModel::from_string(s))
-    }
-}
-
-impl From<&str> for AnthropicModel {
-    fn from(s: &str) -> Self {
-        AnthropicModel::from_string(s)
-    }
-}
-
-impl From<String> for AnthropicModel {
-    fn from(s: String) -> Self {
-        AnthropicModel::from_string(s)
+    /// For the latest available models and their identifiers, check the
+    /// [Anthropic Models Documentation](https://docs.anthropic.com/en/docs/about-claude/models/all-models).
+    ///
+    /// # Using Custom Models
+    ///
+    /// You can specify any model name as a string using `Custom` variant or `FromStr`:
+    ///
+    /// ```rust
+    /// use rstructor::AnthropicModel;
+    /// use std::str::FromStr;
+    ///
+    /// // Using Custom variant
+    /// let model = AnthropicModel::Custom("claude-custom".to_string());
+    ///
+    /// // Using FromStr (useful for config files)
+    /// let model = AnthropicModel::from_str("claude-custom").unwrap();
+    ///
+    /// // Or use the convenience method
+    /// let model = AnthropicModel::from_string("claude-custom");
+    /// ```
+    pub enum AnthropicModel {
+        /// Claude Opus 4.8 (latest most capable generally available model)
+        ClaudeOpus48 => "claude-opus-4-8",
+        /// Claude Opus 4.7 (previous most capable model)
+        ClaudeOpus47 => "claude-opus-4-7",
+        /// Claude Sonnet 4.6 (latest balanced model)
+        ClaudeSonnet46 => "claude-sonnet-4-6",
+        /// Claude Opus 4.6 (previous most capable model)
+        ClaudeOpus46 => "claude-opus-4-6",
+        /// Claude Opus 4.5 (enhanced Opus 4.5)
+        ClaudeOpus45 => "claude-opus-4-5-20251101",
+        /// Claude Haiku 4.5 (latest fastest model)
+        ClaudeHaiku45 => "claude-haiku-4-5-20251001",
+        /// Claude Sonnet 4.5 (previous balanced model)
+        ClaudeSonnet45 => "claude-sonnet-4-5-20250929",
+        /// Claude Opus 4.1 (enhanced reasoning capabilities)
+        ClaudeOpus41 => "claude-opus-4-1-20250805",
+        /// Claude Opus 4 (high-intelligence model)
+        ClaudeOpus4 => "claude-opus-4-20250514",
+        /// Claude Sonnet 4 (balanced performance model)
+        ClaudeSonnet4 => "claude-sonnet-4-20250514",
     }
 }