Enforce Pydantic Schemas for ASR Job Result Models

Overview

This MR improves type safety and API consistency in the ASR backend by replacing unstructured dict[str, Any] usage with strongly typed Pydantic models for transcription and diarization results.

The result field in job-related APIs is now fully schema-driven, improving validation, maintainability, and OpenAPI documentation.

---

Key Changes

1. Structured Data Models (app/models/shared_models.py)

• Introduced TranscriptionChunk

  • Represents word/segment-level transcription data
  • Includes text, start, and end timestamps

• Refactored TranscriptionResult

  • Replaced raw list of dictionaries with list[TranscriptionChunk]
  • Ensures strict typing for chunked transcription output

• Updated result field typing

  • JobStatusResponse and JobDetailResponse now use:

    TranscriptionResult | DiarizationResponse | None

  • Supports both transcription and diarization outputs with full validation

• Reordered model definitions to resolve dependency issues and avoid runtime NameError

---

2. Test Updates (tests/test_main.py)

• Updated mocks to match new strict Pydantic schemas

• Added required fields:

  • language
  • model
  • chunks

• Fixed test failures caused by previous unstructured dictionary-based responses

---

Impact

🔹 API Consumers

• Fixed response structure for job results
• No more ambiguous or dynamic JSON parsing

🔹 Documentation

• Swagger/OpenAPI now reflects accurate nested schemas
• Clear visibility into transcription and diarization output structure

🔹 Reliability

• Invalid or malformed results are now caught at validation level
• Stronger contract between services and API layer

---

Testing Status

• ✅ Unit Tests: 285 passed
• ✅ Integration Tests: Verified /transcribe/{job_id} response schema
• ✅ Linting: ruff + mypy passed

---

Summary

This change replaces flexible but unsafe dictionary-based responses with strict Pydantic models, significantly improving type safety, API clarity, and long-term maintainability.

*Closes #28 (closed)