feat(read): add Read text-intelligence module

  Phase 4 of the spec-coverage rollout — analyze plain text or a
  remote URL via POST /v1/read for sentiment, summary, topics, and
  intents.

  Public surface:
```
    let response = dg.read()
        .analyze(
            &ReadRequest::text("Hello, world."),
            &Options::builder()
                .language("en")
                .summarize(true)
                .sentiment(true)
                .build(),
        )
        .await?;

    if let Some(text) = response.summary_text() {
        println!("Summary: {text}");
    }
```
  Notable wire-shape quirks (matching the spec, the Python SDK, and the
  JS SDK — all auto-generated from the same OpenAPI definition):

    - metadata is double-wrapped: `metadata.metadata.{request_id, ...}`.
      Use ReadResponse::metadata_inner() to skip the wrapper.

    - summary text is four levels deep: `results.summary.results.
      summary.text`. Use ReadResponse::summary_text() to climb it.

  Topics / Intents / Sentiments reuse the existing types from
  common::batch_response since the spec's schemas.shared.yml
  definitions are shared between Listen and Read. The `common` mod
  gate is widened from cfg(feature = "listen") to
  cfg(any(feature = "listen", feature = "read")).

  The new `read` Cargo feature is REST-only (no tungstenite deps).
  auth/base_url/client cfg_attrs updated to allow read, with a
  comment explaining why auth specifically is left listen+agent+speak
  only (auth is baked into reqwest default headers at construction
  and never re-read by REST code paths).

  Three examples under examples/read/: sentiment_url, summarize_text,
  intents_topics.

  12 new tests pass; 140 total. All feature combinations build clean.

Author: GregHolmes

Cargo.toml

@@ -60,6 +60,7 @@ manage = []
 listen = ["dep:tungstenite", "dep:tokio-tungstenite"]
 speak = ["dep:tungstenite", "dep:tokio-tungstenite"]
 agent = ["dep:tungstenite", "dep:tokio-tungstenite"]
+read = []
 
 [[example]]
 name = "grant_token"
@@ -150,6 +151,21 @@ name = "speak_websocket_flush_clear"
 path = "examples/speak/websocket/flush_clear.rs"
 required-features = ["speak"]
 
+[[example]]
+name = "read_sentiment_url"
+path = "examples/read/sentiment_url.rs"
+required-features = ["read"]
+
+[[example]]
+name = "read_summarize_text"
+path = "examples/read/summarize_text.rs"
+required-features = ["read"]
+
+[[example]]
+name = "read_intents_topics"
+path = "examples/read/intents_topics.rs"
+required-features = ["read"]
+
 [[example]]
 name = "agent_simple"
 path = "examples/agent/websocket/simple_agent.rs"

examples/read/intents_topics.rs

@@ -0,0 +1,93 @@
+/* Expected result from running this example program.
+Request ID: <uuid>
+--- Topics ---
+  travel
+  recommendation
+--- Intents ---
+  ask_recommendation
+*/
+
+//! Read API: run topics + intents on inline text, with custom topics
+//! and intents to demonstrate the `extended` and `strict` modes.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//!     cargo run --features read --example read_intents_topics
+//! ```
+
+use std::env;
+
+use deepgram::common::options::{CustomIntentMode, CustomTopicMode};
+use deepgram::read::{options::Options, request::ReadRequest};
+use deepgram::{Deepgram, DeepgramError};
+
+const TEXT: &str = "Hi! I'm planning a trip to Tokyo next month and I'd love any \
+                    restaurant recommendations near Shibuya. Also, what's the best \
+                    way to get from Narita Airport to the city?";
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+    let dg = Deepgram::new(&api_key)?;
+
+    let options = Options::builder()
+        .language("en")
+        .topics(true)
+        .custom_topics(["travel", "recommendation"])
+        .custom_topic_mode(CustomTopicMode::Extended)
+        .intents(true)
+        .custom_intents(["ask_recommendation"])
+        .custom_intent_mode(CustomIntentMode::Strict)
+        .build();
+
+    let response = dg
+        .read()
+        .analyze(&ReadRequest::text(TEXT), &options)
+        .await?;
+
+    if let Some(meta) = response.metadata_inner() {
+        if let Some(id) = &meta.request_id {
+            println!("Request ID: {id}");
+        }
+    }
+
+    println!("--- Topics ---");
+    if let Some(topics) = response.results.topics.as_ref() {
+        let v = serde_json::to_value(topics)?;
+        if let Some(segments) = v.get("segments").and_then(|s| s.as_array()) {
+            for seg in segments {
+                if let Some(arr) = seg.get("topics").and_then(|t| t.as_array()) {
+                    for topic in arr {
+                        if let Some(t) = topic.get("topic").and_then(|t| t.as_str()) {
+                            println!("  {t}");
+                        }
+                    }
+                }
+            }
+        }
+    } else {
+        println!("  (none)");
+    }
+
+    println!("--- Intents ---");
+    if let Some(intents) = response.results.intents.as_ref() {
+        let v = serde_json::to_value(intents)?;
+        if let Some(segments) = v.get("segments").and_then(|s| s.as_array()) {
+            for seg in segments {
+                if let Some(arr) = seg.get("intents").and_then(|i| i.as_array()) {
+                    for intent in arr {
+                        if let Some(name) = intent.get("intent").and_then(|n| n.as_str()) {
+                            println!("  {name}");
+                        }
+                    }
+                }
+            }
+        }
+    } else {
+        println!("  (none)");
+    }
+
+    Ok(())
+}

examples/read/sentiment_url.rs

@@ -0,0 +1,63 @@
+/* Expected result from running this example program.
+Request ID: <uuid>
+Language: en
+Sentiment: positive (avg 0.42)
+*/
+
+//! Read API: fetch a remote document and run sentiment analysis on it.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//!     cargo run --features read --example read_sentiment_url
+//! ```
+
+use std::env;
+
+use deepgram::read::{options::Options, request::ReadRequest};
+use deepgram::{Deepgram, DeepgramError};
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+    let dg = Deepgram::new(&api_key)?;
+
+    let options = Options::builder().language("en").sentiment(true).build();
+
+    let response = dg
+        .read()
+        .analyze(
+            &ReadRequest::url(
+                "https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.txt",
+            ),
+            &options,
+        )
+        .await?;
+
+    if let Some(meta) = response.metadata_inner() {
+        if let Some(id) = &meta.request_id {
+            println!("Request ID: {id}");
+        }
+        if let Some(lang) = &meta.language {
+            println!("Language: {lang}");
+        }
+    }
+
+    if let Some(sentiments) = response.results.sentiments.as_ref() {
+        // Sentiments has private internal fields; surface what serde gives us.
+        let v = serde_json::to_value(sentiments)?;
+        if let Some(avg) = v.get("average") {
+            let label = avg.get("sentiment").and_then(|s| s.as_str()).unwrap_or("?");
+            let score = avg
+                .get("sentiment_score")
+                .and_then(|s| s.as_f64())
+                .unwrap_or(0.0);
+            println!("Sentiment: {label} (avg {score:.2})");
+        }
+    } else {
+        println!("No sentiment data returned.");
+    }
+
+    Ok(())
+}

examples/read/summarize_text.rs

@@ -0,0 +1,51 @@
+/* Expected result from running this example program.
+Request ID: <uuid>
+Summary: A condensed paraphrase of the input text.
+*/
+
+//! Read API: pass an inline string and get back a summary.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//!     cargo run --features read --example read_summarize_text
+//! ```
+
+use std::env;
+
+use deepgram::read::{options::Options, request::ReadRequest};
+use deepgram::{Deepgram, DeepgramError};
+
+const TEXT: &str = "Deepgram's Voice AI platform powers speech-to-text, text-to-speech, \
+                    and full conversational agents. The Read API analyzes text content \
+                    using the same intelligence features (sentiment, summarize, topics, \
+                    intents) that the Listen API exposes for audio. This means you can \
+                    process transcripts, documents, or any plain text uniformly without \
+                    spinning up an audio pipeline.";
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+    let dg = Deepgram::new(&api_key)?;
+
+    let options = Options::builder().language("en").summarize(true).build();
+
+    let response = dg
+        .read()
+        .analyze(&ReadRequest::text(TEXT), &options)
+        .await?;
+
+    if let Some(meta) = response.metadata_inner() {
+        if let Some(id) = &meta.request_id {
+            println!("Request ID: {id}");
+        }
+    }
+
+    match response.summary_text() {
+        Some(text) => println!("Summary: {text}"),
+        None => println!("No summary returned."),
+    }
+
+    Ok(())
+}

src/lib.rs

@@ -27,12 +27,14 @@ use url::Url;
 #[cfg(feature = "agent")]
 pub mod agent;
 pub mod auth;
-#[cfg(feature = "listen")]
+#[cfg(any(feature = "listen", feature = "read"))]
 pub mod common;
 #[cfg(feature = "listen")]
 pub mod listen;
 #[cfg(feature = "manage")]
 pub mod manage;
+#[cfg(feature = "read")]
+pub mod read;
 #[cfg(feature = "speak")]
 pub mod speak;
 
@@ -65,6 +67,17 @@ pub struct Transcription<'a>(#[allow(unused)] pub &'a Deepgram);
 #[derive(Debug, Clone)]
 pub struct Speak<'a>(#[allow(unused)] pub &'a Deepgram);
 
+/// Analyze text using Deepgram's text intelligence API.
+///
+/// Constructed using [`Deepgram::read`].
+///
+/// See the [Deepgram API Reference][api] for more info.
+///
+/// [api]: https://developers.deepgram.com/reference/read-api
+#[cfg(feature = "read")]
+#[derive(Debug, Clone)]
+pub struct Read<'a>(#[allow(unused)] pub &'a Deepgram);
+
 impl Deepgram {
     /// Construct a new [`Transcription`] from a [`Deepgram`].
     pub fn transcription(&self) -> Transcription<'_> {
@@ -83,6 +96,15 @@ impl Deepgram {
     pub fn agent(&self) -> crate::agent::Agent<'_> {
         self.into()
     }
+
+    /// Construct a new [`Read`] sub-client.
+    ///
+    /// Use this to analyze text via Deepgram's `/v1/read` endpoint
+    /// (sentiment, summarize, topics, intents).
+    #[cfg(feature = "read")]
+    pub fn read(&self) -> Read<'_> {
+        self.into()
+    }
 }
 
 impl<'a> From<&'a Deepgram> for Transcription<'a> {
@@ -99,6 +121,13 @@ impl<'a> From<&'a Deepgram> for Speak<'a> {
     }
 }
 
+#[cfg(feature = "read")]
+impl<'a> From<&'a Deepgram> for Read<'a> {
+    fn from(deepgram: &'a Deepgram) -> Self {
+        Self(deepgram)
+    }
+}
+
 impl Transcription<'_> {
     /// Expose a method to access the inner `Deepgram` reference if needed.
     pub fn deepgram(&self) -> &Deepgram {
@@ -151,14 +180,24 @@ impl AuthMethod {
 /// Make transcriptions requests using [`Deepgram::transcription`].
 #[derive(Debug, Clone)]
 pub struct Deepgram {
+    // `auth` is consumed by `inner_constructor` to bake the
+    // Authorization header into the reqwest client's default headers.
+    // Only the WS code paths in listen/agent/speak read the field
+    // afterwards; the REST code paths (including `read`) don't.
     #[cfg_attr(
         not(any(feature = "listen", feature = "agent", feature = "speak")),
         allow(unused)
     )]
     auth: Option<AuthMethod>,
-    #[cfg_attr(not(feature = "listen"), allow(unused))]
+    #[cfg_attr(
+        not(any(feature = "listen", feature = "speak", feature = "read")),
+        allow(unused)
+    )]
     base_url: Url,
-    #[cfg_attr(not(feature = "listen"), allow(unused))]
+    #[cfg_attr(
+        not(any(feature = "listen", feature = "speak", feature = "read")),
+        allow(unused)
+    )]
     client: reqwest::Client,
 }
 

src/read/mod.rs

@@ -0,0 +1,43 @@
+//! Read API — analyze plain text or a remote document for sentiment,
+//! summary, topics, and intents.
+//!
+//! Mirrors `POST /v1/read` (`openapi/paths/read.v1.yml`).
+//!
+//! Entry point: [`crate::Deepgram::read`].
+//!
+//! ```no_run
+//! use deepgram::Deepgram;
+//! use deepgram::read::{options::Options, request::ReadRequest};
+//!
+//! # async fn run() -> Result<(), deepgram::DeepgramError> {
+//! let dg = Deepgram::new(std::env::var("DEEPGRAM_API_KEY").unwrap_or_default())?;
+//! let options = Options::builder()
+//!     .language("en")
+//!     .sentiment(true)
+//!     .summarize(true)
+//!     .topics(true)
+//!     .build();
+//!
+//! let response = dg
+//!     .read()
+//!     .analyze(&ReadRequest::text("Deepgram makes voice AI fast and easy."), &options)
+//!     .await?;
+//!
+//! if let Some(text) = response.summary_text() {
+//!     println!("Summary: {text}");
+//! }
+//! # Ok(())
+//! # }
+//! ```
+
+pub mod options;
+pub mod request;
+pub mod response;
+pub mod rest;
+
+pub use options::{Options, OptionsBuilder};
+pub use request::ReadRequest;
+pub use response::{
+    ReadMetadata, ReadMetadataWrapper, ReadResponse, ReadResults, ReadSummaryInner,
+    ReadSummaryText, ReadSummaryWrapper, TokenInfo,
+};