raqeem 0.2.1__tar.gz

raqeem-0.2.1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: raqeem
+Version: 0.2.1
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: Arabic
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Summary: رقيم — the easy way to use Cohere's open Arabic speech-recognition model from Python.
+Keywords: arabic,asr,speech-to-text,transcription,cohere
+Home-Page: https://github.com/SufficientDaikon/raqeem
+Author-email: Ahmed Taha <tahaa755@gmail.com>
+License: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/SufficientDaikon/raqeem/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/SufficientDaikon/raqeem
+Project-URL: Repository, https://github.com/SufficientDaikon/raqeem
+
+# رقيم · raqeem
+
+**The easy way to use Cohere's open Arabic speech-recognition model from Python.**
+
+`raqeem` wraps
+[`CohereLabs/cohere-transcribe-arabic-07-2026`](https://huggingface.co/CohereLabs/cohere-transcribe-arabic-07-2026)
+— the most accurate open-source Arabic ASR model (dialects + Arabic/English
+code-switching), Apache-2.0.
+
+It is a **compiled Rust extension**, not a pure-Python wrapper: no `torch`, no model
+weights, no subprocess. Inference is delegated to an endpoint you choose — Cohere's
+hosted API, or your own vLLM.
+
+```bash
+pip install raqeem
+```
+
+```python
+import raqeem
+
+# Cohere hosted API (reads $COHERE_API_KEY)
+t = raqeem.transcribe("voice_note.ogg", lang="ar")
+print(t.text)              # verbatim, for humans
+print(t.text_normalized)   # Arabic-folded, for parsing
+print(t.to_dict())
+
+# your own vLLM — the Cohere key is never sent to a self-hosted endpoint
+t = raqeem.transcribe(
+    "clip.wav",
+    provider="openai",
+    endpoint="http://localhost:8000/v1/audio/transcriptions",
+)
+
+# the Arabic normalizer on its own
+raqeem.normalize_ar("الطماطم بـ ١٢٫٥ جنيه")   # 'الطماطم ب 12.5 جنيه'
+```
+
+`text_normalized` folds alef/hamza, taa-marbuta, strips tatweel and diacritics, and
+converts Arabic-Indic and Persian digits to ASCII — note `١٢٫٥` becomes `12.5`, **one**
+number rather than two, which matters if anything downstream parses prices or quantities.
+
+Failures raise `raqeem.TranscriptionError`; a bad provider or a missing key/endpoint
+raises `ValueError`.
+
+Full docs, the CLI, and the roadmap (subtitles, diarization, more bindings):
+**https://github.com/SufficientDaikon/raqeem**
+
+All model accuracy credit belongs to Cohere Labs — this package is the ergonomics.
+Apache-2.0.
+

raqeem-0.2.1/README.md

@@ -0,0 +1,49 @@
+# رقيم · raqeem
+
+**The easy way to use Cohere's open Arabic speech-recognition model from Python.**
+
+`raqeem` wraps
+[`CohereLabs/cohere-transcribe-arabic-07-2026`](https://huggingface.co/CohereLabs/cohere-transcribe-arabic-07-2026)
+— the most accurate open-source Arabic ASR model (dialects + Arabic/English
+code-switching), Apache-2.0.
+
+It is a **compiled Rust extension**, not a pure-Python wrapper: no `torch`, no model
+weights, no subprocess. Inference is delegated to an endpoint you choose — Cohere's
+hosted API, or your own vLLM.
+
+```bash
+pip install raqeem
+```
+
+```python
+import raqeem
+
+# Cohere hosted API (reads $COHERE_API_KEY)
+t = raqeem.transcribe("voice_note.ogg", lang="ar")
+print(t.text)              # verbatim, for humans
+print(t.text_normalized)   # Arabic-folded, for parsing
+print(t.to_dict())
+
+# your own vLLM — the Cohere key is never sent to a self-hosted endpoint
+t = raqeem.transcribe(
+    "clip.wav",
+    provider="openai",
+    endpoint="http://localhost:8000/v1/audio/transcriptions",
+)
+
+# the Arabic normalizer on its own
+raqeem.normalize_ar("الطماطم بـ ١٢٫٥ جنيه")   # 'الطماطم ب 12.5 جنيه'
+```
+
+`text_normalized` folds alef/hamza, taa-marbuta, strips tatweel and diacritics, and
+converts Arabic-Indic and Persian digits to ASCII — note `١٢٫٥` becomes `12.5`, **one**
+number rather than two, which matters if anything downstream parses prices or quantities.
+
+Failures raise `raqeem.TranscriptionError`; a bad provider or a missing key/endpoint
+raises `ValueError`.
+
+Full docs, the CLI, and the roadmap (subtitles, diarization, more bindings):
+**https://github.com/SufficientDaikon/raqeem**
+
+All model accuracy credit belongs to Cohere Labs — this package is the ergonomics.
+Apache-2.0.

raqeem-0.2.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "raqeem"
+description = "رقيم — the easy way to use Cohere's open Arabic speech-recognition model from Python."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Ahmed Taha", email = "tahaa755@gmail.com" }]
+keywords = ["arabic", "asr", "speech-to-text", "transcription", "cohere"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Natural Language :: Arabic",
+  "Programming Language :: Rust",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/SufficientDaikon/raqeem"
+Repository = "https://github.com/SufficientDaikon/raqeem"
+Changelog = "https://github.com/SufficientDaikon/raqeem/blob/main/CHANGELOG.md"
+
+[tool.maturin]
+features = ["pyo3/extension-module"]
+module-name = "raqeem"
+include = [{ path = "raqeem.pyi", format = "wheel" }]
+manifest-path = "raqeem-python/Cargo.toml"

raqeem-0.2.1/raqeem-core/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "raqeem-core"
+version = "0.2.1"
+edition = "2021"
+license = "Apache-2.0"
+repository = "https://github.com/SufficientDaikon/raqeem"
+authors = ["Ahmed Taha <tahaa755@gmail.com>"]
+homepage = "https://github.com/SufficientDaikon/raqeem"
+keywords = ["arabic", "asr", "speech-to-text", "transcription", "cohere"]
+categories = ["command-line-utilities", "api-bindings", "multimedia::audio"]
+description = "Core library for raqeem — an easy client for Cohere's open Arabic ASR model."
+
+[dependencies]
+serde = { version = "^1", features = ["derive"] }
+serde_json = "^1"
+reqwest = { version = "^0.12", default-features = false, features = ["blocking", "multipart", "rustls-tls"] }
+thiserror = "^2"
+
+[dev-dependencies]
+mockito = "1"

raqeem-0.2.1/raqeem-core/src/arabic.rs

@@ -0,0 +1,94 @@
+//! Arabic text normalization — a Rust port of scout's verified `normalize_ar`
+//! (from the `arabic-first` convention). We fold audio transcripts to a
+//! matching-stable form so downstream parsers (price extraction, commodity
+//! matching) never fuzzy-match raw, unnormalized Arabic.
+//!
+//! Faithful to the Python reference — identical output on all Arabic and ASCII
+//! input: strip diacritics / tatweel / Quranic marks, unify alef and hamza
+//! carriers, taa-marbuta → haa, Arabic-Indic & Persian digits → ASCII, and the
+//! Arabic decimal separator U+066B → `.` (so «١٢٫٥» folds to `12.5`, one number,
+//! not two). Context-sensitive Unicode case tailoring aside — Python lower-cases a
+//! word-final Greek `Σ` to `ς`, Rust to `σ` — which is out of domain for Arabic
+//! transcripts, and scout re-normalizes via the Python function downstream anyway.
+
+/// Fold Arabic text to a matching-stable form. Idempotent; ASCII passes through
+/// lower-cased, so it is safe to run unconditionally on any transcript.
+pub fn normalize_ar(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    for ch in text.chars() {
+        match ch {
+            // Strip: Quranic annotations, harakat/diacritics, tatweel, superscript alef.
+            '\u{0610}'..='\u{061A}'
+            | '\u{064B}'..='\u{065F}'
+            | '\u{0640}'
+            | '\u{0670}'
+            | '\u{06D6}'..='\u{06ED}' => {}
+            // Alef variants → bare alef.
+            'آ' | 'أ' | 'إ' | 'ٱ' => out.push('ا'),
+            // Hamza-carrier and taa-marbuta folds.
+            'ى' => out.push('ي'), // alef maqsura → yaa
+            'ة' => out.push('ه'), // taa marbuta → haa
+            'ؤ' => out.push('و'),
+            'ئ' => out.push('ي'),
+            // Arabic-Indic (U+0660–0669) and Persian (U+06F0–06F9) digits → ASCII.
+            '\u{0660}'..='\u{0669}' => out.push((b'0' + (ch as u32 - 0x0660) as u8) as char),
+            '\u{06F0}'..='\u{06F9}' => out.push((b'0' + (ch as u32 - 0x06F0) as u8) as char),
+            // Arabic decimal separator → ASCII point.
+            '\u{066B}' => out.push('.'),
+            // Everything else: lower-case ASCII, pass Arabic/other through unchanged.
+            other => out.extend(other.to_lowercase()),
+        }
+    }
+    // Collapse internal whitespace runs and trim.
+    out.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::normalize_ar;
+
+    #[test]
+    fn folds_alef_and_hamza_carriers() {
+        assert_eq!(normalize_ar("أ"), "ا");
+        assert_eq!(normalize_ar("إ"), "ا");
+        assert_eq!(normalize_ar("آ"), "ا");
+        assert_eq!(normalize_ar("ٱ"), "ا");
+        assert_eq!(normalize_ar("مصطفى"), "مصطفي"); // alef maqsura → yaa
+        assert_eq!(normalize_ar("مسؤول"), "مسوول"); // ؤ → و
+    }
+
+    #[test]
+    fn taa_marbuta_becomes_haa() {
+        let r = normalize_ar("طماطة");
+        assert!(!r.contains('ة'));
+        assert!(r.ends_with('ه'));
+    }
+
+    #[test]
+    fn strips_tatweel_and_diacritics() {
+        assert_eq!(normalize_ar("سـلام"), "سلام"); // tatweel U+0640
+        assert_eq!(normalize_ar("سَلاَم"), "سلام"); // harakat
+    }
+
+    #[test]
+    fn digits_and_decimal_separator() {
+        assert_eq!(normalize_ar("١٢٣"), "123"); // arabic-indic
+        assert_eq!(normalize_ar("۱۲۳"), "123"); // persian
+        assert_eq!(normalize_ar("١٢٫٥"), "12.5"); // U+066B decimal → one number
+    }
+
+    #[test]
+    fn ascii_lowercased_and_whitespace_collapsed() {
+        assert_eq!(normalize_ar("Tomato"), "tomato");
+        assert_eq!(normalize_ar("  a   b  "), "a b");
+    }
+
+    #[test]
+    fn idempotent() {
+        let samples = ["أحمد", "طماطة ١٢٫٥ جنيه", "Hello  World", "سـلامٌ عليكم"];
+        for s in samples {
+            let once = normalize_ar(s);
+            assert_eq!(normalize_ar(&once), once, "not idempotent on {s:?}");
+        }
+    }
+}

raqeem-0.2.1/raqeem-core/src/endpoint.rs

@@ -0,0 +1,52 @@
+//! The one adapter. Cohere-hosted and self-hosted vLLM differ only in URL,
+//! auth header, and model id — so a single `Endpoint` struct + two constructors
+//! covers both, and any future OpenAI-compatible backend.
+
+use crate::provider::Provider;
+
+/// Cohere's hosted transcription endpoint.
+pub const COHERE_URL: &str = "https://api.cohere.com/v2/audio/transcriptions";
+/// Default model id for the Arabic transcriber. Cohere requires a **dated** model
+/// id — undated aliases (`cohere-transcribe-arabic`) return HTTP 404 "model not
+/// found". Bump this when Cohere ships a newer dated Arabic transcription model.
+pub const DEFAULT_COHERE_MODEL: &str = "cohere-transcribe-arabic-07-2026";
+
+/// Where and how to reach a transcription server.
+#[derive(Debug, Clone)]
+pub struct Endpoint {
+    /// Full URL to POST the multipart form to.
+    pub url: String,
+    /// Bearer token, if the backend requires auth.
+    pub api_key: Option<String>,
+    /// Model id sent as the `model` form field.
+    pub model: String,
+    /// Provenance tag recorded on the transcript.
+    pub provider: Provider,
+}
+
+impl Endpoint {
+    /// Cohere's hosted API. `model` defaults to [`DEFAULT_COHERE_MODEL`].
+    pub fn cohere(api_key: impl Into<String>, model: Option<String>) -> Self {
+        Endpoint {
+            url: COHERE_URL.to_string(),
+            api_key: Some(api_key.into()),
+            model: model.unwrap_or_else(|| DEFAULT_COHERE_MODEL.to_string()),
+            provider: Provider::Cohere,
+        }
+    }
+
+    /// A self-hosted OpenAI-compatible endpoint — pass the full route URL
+    /// (e.g. `http://localhost:8000/v1/audio/transcriptions`).
+    pub fn openai_compatible(
+        url: impl Into<String>,
+        model: impl Into<String>,
+        api_key: Option<String>,
+    ) -> Self {
+        Endpoint {
+            url: url.into(),
+            api_key,
+            model: model.into(),
+            provider: Provider::OpenAiCompatible,
+        }
+    }
+}

raqeem-0.2.1/raqeem-core/src/error.rs

@@ -0,0 +1,22 @@
+use std::path::PathBuf;
+
+/// Everything that can go wrong on the way from an audio file to a transcript.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error("could not read audio file {path}: {source}")]
+    ReadFile {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+
+    #[error("request to {url} failed: {source}")]
+    Http { url: String, source: reqwest::Error },
+
+    #[error("endpoint returned HTTP {status}: {body}")]
+    Api { status: u16, body: String },
+
+    #[error("could not parse endpoint response (expected a JSON object with a string \"text\" field), got: {body}")]
+    BadResponse { body: String },
+}
+
+pub type Result<T> = std::result::Result<T, Error>;

raqeem-0.2.1/raqeem-core/src/lib.rs

@@ -0,0 +1,150 @@
+//! `raqeem-core` — رقيم. Turn an audio file into Arabic text by delegating
+//! inference to a transcription endpoint (Cohere's hosted API, or your own
+//! vLLM). This crate never loads model weights: it decodes nothing, runs no
+//! model — it POSTs the audio and folds the result. That is what keeps it
+//! light and callable from any language over the CLI.
+//!
+//! ```no_run
+//! use raqeem_core::{Endpoint, Transcriber};
+//!
+//! let endpoint = Endpoint::cohere(std::env::var("COHERE_API_KEY").unwrap(), None);
+//! let transcript = Transcriber::new(endpoint)
+//!     .language("ar")
+//!     .transcribe(std::path::Path::new("voice_note.ogg"))?;
+//! println!("{}", transcript.text);
+//! # Ok::<(), raqeem_core::Error>(())
+//! ```
+
+mod arabic;
+mod endpoint;
+mod error;
+mod output;
+mod provider;
+
+pub use arabic::normalize_ar;
+pub use endpoint::{Endpoint, COHERE_URL, DEFAULT_COHERE_MODEL};
+pub use error::{Error, Result};
+pub use output::OutputFormat;
+pub use provider::Provider;
+
+use std::path::Path;
+use std::time::Duration;
+
+/// Default transcription language (ISO-639-1). Arabic-first, by design.
+pub const DEFAULT_LANGUAGE: &str = "ar";
+
+/// Default total-request timeout, in seconds. Generous on purpose: it must cover
+/// upload + model inference + download, and CPU inference of a voice note can take
+/// many seconds. (reqwest's blocking client otherwise silently defaults to 30s,
+/// which truncates a slow transcription mid-inference.)
+pub const DEFAULT_TIMEOUT_SECS: u64 = 300;
+
+/// A completed transcription. `text` is the model's verbatim output; the folded
+/// `text_normalized` (see [`normalize_ar`]) is what downstream parsers consume.
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct Transcript {
+    pub text: String,
+    pub text_normalized: String,
+    pub provider: String,
+    pub model: String,
+    pub language: String,
+}
+
+/// Transcribes audio by POSTing it to a configured [`Endpoint`].
+pub struct Transcriber {
+    endpoint: Endpoint,
+    language: String,
+    client: reqwest::blocking::Client,
+}
+
+impl Transcriber {
+    /// Build a transcriber for the given endpoint, defaulting to Arabic and a
+    /// [`DEFAULT_TIMEOUT_SECS`] total-request timeout.
+    pub fn new(endpoint: Endpoint) -> Self {
+        Self::with_timeout(endpoint, Duration::from_secs(DEFAULT_TIMEOUT_SECS))
+    }
+
+    /// Like [`new`](Self::new) but with an explicit total-request timeout — raise it
+    /// for slow CPU inference or large files, lower it to fail faster. The timeout
+    /// spans the whole round-trip (connect + upload + inference + download).
+    pub fn with_timeout(endpoint: Endpoint, timeout: Duration) -> Self {
+        let client = reqwest::blocking::Client::builder()
+            .timeout(timeout)
+            .build()
+            .unwrap_or_else(|_| reqwest::blocking::Client::new());
+        Transcriber {
+            endpoint,
+            language: DEFAULT_LANGUAGE.to_string(),
+            client,
+        }
+    }
+
+    /// Override the transcription language (ISO-639-1).
+    pub fn language(mut self, lang: impl Into<String>) -> Self {
+        self.language = lang.into();
+        self
+    }
+
+    /// Read `audio`, send it to the endpoint, and return the transcript.
+    pub fn transcribe(&self, audio: &Path) -> Result<Transcript> {
+        let bytes = std::fs::read(audio).map_err(|source| Error::ReadFile {
+            path: audio.to_path_buf(),
+            source,
+        })?;
+        let filename = audio
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("audio")
+            .to_string();
+
+        // Same multipart shape for every backend: model + language + file.
+        // Order matters: Cohere rejects the request unless the text fields
+        // (model, language) appear BEFORE the file part in the body.
+        let file_part = reqwest::blocking::multipart::Part::bytes(bytes).file_name(filename);
+        let form = reqwest::blocking::multipart::Form::new()
+            .text("model", self.endpoint.model.clone())
+            .text("language", self.language.clone())
+            .part("file", file_part);
+
+        let mut req = self.client.post(&self.endpoint.url).multipart(form);
+        if let Some(key) = &self.endpoint.api_key {
+            req = req.bearer_auth(key);
+        }
+
+        let resp = req.send().map_err(|source| Error::Http {
+            url: self.endpoint.url.clone(),
+            source,
+        })?;
+        let status = resp.status();
+        let body = resp.text().map_err(|source| Error::Http {
+            url: self.endpoint.url.clone(),
+            source,
+        })?;
+        if !status.is_success() {
+            return Err(Error::Api {
+                status: status.as_u16(),
+                body,
+            });
+        }
+
+        let text = extract_text(&body).ok_or_else(|| Error::BadResponse { body: body.clone() })?;
+        Ok(Transcript {
+            text_normalized: normalize_ar(&text),
+            text,
+            provider: self.endpoint.provider.as_str().to_string(),
+            model: self.endpoint.model.clone(),
+            language: self.language.clone(),
+        })
+    }
+}
+
+/// Pull the transcript out of an endpoint response.
+///
+// ponytail: assumes the OpenAI-standard `{"text": "..."}` shape, which vLLM and
+// (per Cohere's docs) the hosted API both return. If a backend nests it
+// differently, add a branch here rather than a whole response type — the raw
+// body is surfaced in `Error::BadResponse` so a mismatch is obvious on first run.
+fn extract_text(body: &str) -> Option<String> {
+    let v: serde_json::Value = serde_json::from_str(body).ok()?;
+    v.get("text")?.as_str().map(str::to_string)
+}

raqeem-0.2.1/raqeem-core/src/output.rs

@@ -0,0 +1,24 @@
+//! Render a [`Transcript`] for a caller. `Text` is the human-readable verbatim
+//! transcription; `Json` carries both the verbatim and normalized forms plus
+//! provenance (what scout consumes).
+
+use crate::Transcript;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OutputFormat {
+    Text,
+    Json,
+}
+
+impl OutputFormat {
+    pub fn render(self, t: &Transcript) -> String {
+        match self {
+            OutputFormat::Text => t.text.clone(),
+            OutputFormat::Json => {
+                // Transcript derives Serialize; serialization of these plain
+                // fields cannot fail, so the fallback is unreachable in practice.
+                serde_json::to_string_pretty(t).unwrap_or_else(|_| "{}".to_string())
+            }
+        }
+    }
+}

raqeem-0.2.1/raqeem-core/src/provider.rs

@@ -0,0 +1,25 @@
+//! Backend presets. Every supported transcription server speaks the same
+//! OpenAI-compatible multipart `/audio/transcriptions` shape, so a "provider"
+//! is just a label + the defaults ([`crate::Endpoint`] carries the actual
+//! URL / auth / model). Adding a backend = adding a variant here and a
+//! constructor on `Endpoint` — see `.claude/skills/add-endpoint-adapter`.
+
+/// A known transcription backend.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Provider {
+    /// Cohere's hosted API — `https://api.cohere.com/v2/audio/transcriptions`.
+    Cohere,
+    /// Any self-hosted OpenAI-compatible server (e.g. vLLM at
+    /// `/v1/audio/transcriptions`), reached via an explicit URL.
+    OpenAiCompatible,
+}
+
+impl Provider {
+    /// Stable machine-readable tag, recorded on every [`crate::Transcript`].
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Provider::Cohere => "cohere",
+            Provider::OpenAiCompatible => "openai-compatible",
+        }
+    }
+}

raqeem-0.2.1/raqeem-core/tests/endpoint_mock.rs

@@ -0,0 +1,68 @@
+//! End-to-end test of the transcribe path against a mocked HTTP endpoint — no
+//! network, no API key, no model. Asserts the multipart body carries the fields
+//! every backend expects and that an Arabic response parses + normalizes.
+
+use raqeem_core::{Endpoint, Transcriber};
+
+#[test]
+fn posts_multipart_with_auth_and_parses_arabic_text() {
+    let mut server = mockito::Server::new();
+
+    let mock = server
+        .mock("POST", "/v2/audio/transcriptions")
+        .match_header("authorization", "Bearer testkey")
+        .match_body(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::Regex("cohere-transcribe-arabic".to_string()),
+            // Order matters: Cohere requires model + language BEFORE the file part.
+            mockito::Matcher::Regex(
+                r#"(?s)name="model".*name="language".*name="file""#.to_string(),
+            ),
+        ]))
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        // Arabic-Indic digits + U+066B on purpose, to prove normalization runs.
+        .with_body(r#"{"text": "الطماطم بـ ١٢٫٥ جنيه"}"#)
+        .create();
+
+    let url = format!("{}/v2/audio/transcriptions", server.url());
+    let endpoint =
+        Endpoint::openai_compatible(url, "cohere-transcribe-arabic", Some("testkey".into()));
+
+    let audio = std::env::temp_dir().join("RAQEEM_test_clip.wav");
+    std::fs::write(&audio, b"RIFF....WAVEfake").unwrap();
+
+    let t = Transcriber::new(endpoint)
+        .language("ar")
+        .transcribe(&audio)
+        .expect("transcribe should succeed against the mock");
+
+    assert_eq!(t.text, "الطماطم بـ ١٢٫٥ جنيه"); // verbatim, untouched
+    assert!(t.text_normalized.contains("12.5")); // digits + decimal folded
+    assert!(!t.text_normalized.contains('ـ')); // tatweel stripped
+    assert_eq!(t.language, "ar");
+    assert_eq!(t.provider, "openai-compatible");
+
+    mock.assert();
+    let _ = std::fs::remove_file(&audio);
+}
+
+#[test]
+fn surfaces_api_errors_with_status_and_body() {
+    let mut server = mockito::Server::new();
+    let _mock = server
+        .mock("POST", "/v1/audio/transcriptions")
+        .with_status(401)
+        .with_body("unauthorized")
+        .create();
+
+    let url = format!("{}/v1/audio/transcriptions", server.url());
+    let endpoint = Endpoint::openai_compatible(url, "m", None);
+
+    let audio = std::env::temp_dir().join("RAQEEM_test_clip2.wav");
+    std::fs::write(&audio, b"x").unwrap();
+
+    let err = Transcriber::new(endpoint).transcribe(&audio).unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("401"), "expected status in error, got: {msg}");
+    let _ = std::fs::remove_file(&audio);
+}