Tech Debt Audit — 2026-03-18 — repo root

[amankumarsingh77]

Tech Debt Audit — tarash (repo root)

Scanned: 115 files | Date: 2026-03-18
Findings: 0 critical, 11 high, 33 medium, 10 low

---

High

• providers/fal.py:1 — God module: 2288 lines, single class spanning video, image, and TTS — 3 domains in 1 file (architecture)
• providers/google.py:1 — God module: 1241 lines spanning video and image generation (architecture)
• providers/google.py:308 — Cyclomatic complexity CC=29 in _convert_request (complexity)
• providers/replicate.py:1 — God module: 1267 lines spanning video and image generation (architecture)
• providers/replicate.py:547 — Cyclomatic complexity CC=21 in _convert_response (complexity)
• providers/runway.py:297 — Cyclomatic complexity CC=22 in _convert_request (complexity)
• providers/field_mappers.py:168 — Cyclomatic complexity CC=16 in single_image_field_mapper (complexity)
• providers/field_mappers.py:195 — Cyclomatic complexity CC=16 in converter closure (complexity)
• tools/linter/runner.py:20 — Cyclomatic complexity CC=18 in parse_registry_mapping (complexity)
• tools/linter/runner.py:171 — Cyclomatic complexity CC=17 in run_lint (complexity)
• utils.py:242 — Swallowed exception: except Exception: pass in _extract_filename_from_url (error-handling)

Medium

• exceptions.py:11 — Circular dependency signal: TYPE_CHECKING import from models (dependency)
• exceptions.py:240 — Duplicated error-handling decorators: video vs audio are near-identical (duplication)
• image_format.py:77 — Cyclomatic complexity CC=13 in ensure_image_format (complexity)
• logging.py:21 — Cyclomatic complexity CC=14 in _redact_value; also Any overuse (complexity)
• mock.py:341 — Global mutable state: _async_cache dict grows unbounded, not thread-safe (code-smell)
• models.py:21 — Circular dependency signal: TYPE_CHECKING import from mock (dependency)
• orchestrator.py:60 — 8 near-identical execute methods repeating fallback-chain pattern (duplication)
• providers/cartesia.py:178 — _get_client() -> Any could use Cartesia | AsyncCartesia (code-smell)
• providers/cartesia.py:227 — _resolve_audio_local(audio: Any) could use MediaType (code-smell)
• providers/cartesia.py:240 — _resolve_audio_bytes(audio: Any) could use MediaType (code-smell)
• providers/cartesia.py:248 — _resolve_audio_bytes_async(audio: Any) could use MediaType (code-smell)
• providers/cartesia.py:292 — Deep nesting (6 levels) in _handle_error (complexity)
• providers/elevenlabs.py:120 — _get_client() -> Any could use union type (code-smell)
• providers/elevenlabs.py:148 — _resolve_audio_local(audio: Any) could use MediaType (code-smell)
• providers/elevenlabs.py:162 — _resolve_audio_bytes(audio: Any) could use MediaType (code-smell)
• providers/elevenlabs.py:170 — _resolve_audio_bytes_async(audio: Any) could use MediaType (code-smell)
• providers/elevenlabs.py:241 — Deep nesting (6 levels) in _handle_error (complexity)
• providers/google.py:560 — Cyclomatic complexity CC=15 in _handle_error (complexity)
• providers/google.py:770 — _convert_gemini_image_response(response: Any) — SDK exports types (code-smell)
• providers/hume.py:120 — _get_client() -> Any could use union type (code-smell)
• providers/hume.py:157 — _convert_tts_response(hume_result: Any) undocumented Any (code-smell)
• providers/hume.py:197 — Deep nesting (6 levels) in _handle_error; duplicated with sarvam (complexity)
• providers/openai.py:1082 — _convert_image_response(provider_response: Any) — SDK exports ImagesResponse (code-smell)
• providers/replicate.py:990 — Deep nesting (6 levels) in _convert_image_response (complexity)
• providers/runway.py:580 — Cyclomatic complexity CC=13 in _poll_until_complete (complexity)
• providers/sarvam.py:96 — _get_client() -> Any could use union type (code-smell)
• providers/sarvam.py:140 — _convert_tts_response(sarvam_result: Any) undocumented Any (code-smell)
• providers/sarvam.py:171 — Deep nesting (6 levels) in _handle_error; duplicated with hume (complexity)
• registry.py:28 — Global mutable state: _HANDLER_INSTANCES dict, not thread-safe (code-smell)
• registry.py:31 — CC=15 / deep nesting (12 levels) in get_handler if/elif chain (complexity)

Low

• pyproject.toml:4 — Placeholder project description "Add your description here" (dependency)
• tarash-gateway/pyproject.toml:11 — Pinning gap: pydantic>=2.0.0 no upper bound (dependency)
• tarash-gateway/pyproject.toml:12 — Pinning gap: httpx>=0.25.0 no upper bound (dependency)
• tarash-gateway/pyproject.toml:16 — Pinning gap: fal-client>=0.4.0 no upper bound (dependency)
• tarash-gateway/pyproject.toml:17 — Pinning gap: google-genai>=1.0.0 no upper bound (dependency)
• tarash-gateway/pyproject.toml:18 — Pinning gap: openai>=1.0.0 (installed 2.24.0 — crossed major) (dependency)
• tarash-gateway/pyproject.toml:20 — Unused dependency: google-cloud-aiplatform never imported (dependency)
• tarash-gateway/pyproject.toml:21 — Pinning gap: runwayml>=3.0.0 (installed 4.6.2 — crossed major) (dependency)
• tarash-gateway/pyproject.toml:23 — Pinning gap: elevenlabs>=1.0.0 (installed 2.37.0 — crossed major) (dependency)
• tarash-gateway/pyproject.toml:24 — Pinning gap: cartesia>=1.0.0 (installed 3.0.2 — crossed major) (dependency)

---

Summary

Category	Critical	High	Medium	Low	Total
dependency	0	0	2	10	12
architecture	0	3	0	0	3
complexity	0	7	12	0	19
duplication	0	0	3	0	3
error-handling	0	1	0	0	1
code-smell	0	0	16	0	16
async	0	0	0	0	0

Hotspots (files with 3+ findings)

File	Findings	Highest Severity
providers/google.py	4	High
providers/cartesia.py	5	Medium
providers/elevenlabs.py	5	Medium
providers/replicate.py	3	High
providers/hume.py	3	Medium
providers/sarvam.py	3	Medium
registry.py	3	Medium

Notes

• CVE checks skipped — pip-audit not installed
• Complexity computed via AST-based calculation (radon not available)

Recommended Actions

1. High — schedule for current sprint, use /refactor for code-level fixes
   • Split god modules (fal.py, google.py, replicate.py) by domain (video/image/tts)
   • Break down high-CC functions with extract-method refactoring
   • Fix the swallowed exception in utils.py
2. Medium — plan for next sprint
   • Replace Any return types with proper union types from SDKs
   • Deduplicate orchestrator execute methods and error-handling decorators
   • Add thread-safety to global mutable caches
3. Low — address opportunistically
   • Add upper-bound pins for dependencies that crossed major versions
   • Remove unused google-cloud-aiplatform dependency