aimd-cli 0.9.2__py3-none-any.whl

aimd/AGENTS.md

@@ -0,0 +1,68 @@
+# packages/aimd/src/aimd
+
+Core package organized with ports/adapters architecture.
+
+## STRUCTURE
+
+- `application/` — use-cases, canonical request/response models, bootstrap wiring
+- `infrastructure/` — MarkItDown runner, media package adapter, and Markdown chunking helpers
+- `adapters/` — CLI interface adapter
+- `cli.py` — runtime entrypoint
+
+Feature packages live beside this package:
+
+- `packages/aimd-media/` — yt-dlp URLs, subtitles, audio fallback, ASR plugin, and capability checks
+- `packages/aimd-api/` — FastAPI service package
+- `packages/aimd-mcp/` — MCP stdio server package
+- `packages/aimd-book/` — MarkItDown plugin for ebook extraction and cleanup
+- `packages/aimd-ocr/` — OCR plugin scaffold
+- `packages/aimd-html/` — Defuddle CLI wrapper
+
+## CONVENTIONS
+
+- Keep orchestration in `application/use_cases/*`.
+- Keep IO/third-party integrations in `infrastructure/*`.
+- Keep interface-specific request/response mapping in `adapters/*`.
+
+- Keep platform-dependent dependency use behind capability checks; `mlx-audio` is Darwin-only and Qwen3-ASR runs through Transformers on Linux/CUDA.
+- Keep heavy local-file integrations behind MarkItDown plugins; keep this package as the facade/router and `TextContext` wrapper.
+- Keep output file persistence in adapters via `application/services/output_writer.py`; `ProcessInput` and `ProcessResult` do not carry `output_file`.
+- Keep API/MCP payload mapping in `application/services/interface_payloads.py` as plain helpers with no FastAPI/MCP imports.
+
+## BOOK CONVERSION
+
+`aimd-book` owns ebook conversion through the MarkItDown plugin entry point. Core routing treats `.epub`, `.mobi`, and `.azw3` as book inputs via `BOOK_EXTENSIONS`, but the current book pipeline is EPUB-compatible ZIP/spine extraction. Add true non-EPUB handling inside `aimd-book` rather than special-casing it in `aimd.infrastructure` or adapters.
+
+## TEMP DIRECTORY
+
+All temporary file operations (audio downloads, ebook extraction) use
+Python's `tempfile` module with a configurable base directory:
+
+- **CLI**: `--temp-dir` option (also reads `AIMD_TEMP_DIR` env var)
+- **MCP / HTTP**: reads `AIMD_TEMP_DIR` env var at request time
+- **Default**: when unset, falls back to the system temp directory (`/tmp`)
+
+In sandboxed environments where `/tmp` may not be writable, set `AIMD_TEMP_DIR`
+to redirect temp I/O. The `temp_dir` field flows through `ProcessInput` →
+use-cases → infrastructure functions via the `dir=` parameter of
+`tempfile.TemporaryDirectory` and `tempfile.NamedTemporaryFile`. ASR temp files are implemented in `aimd-media`; ebook extraction temp files are implemented in `aimd-book`.
+
+## SUBTITLE FORMATTING
+
+URL-sourced subtitles (SRT/VTT/TTML) are simplified to plain text by default.
+The `raw_transcript` field on `ProcessInput` (default `False`) controls this:
+
+- **CLI**: `--raw-transcript` flag
+- **HTTP API**: `raw_transcript` field in `ProcessRequest`
+- **MCP**: `raw_transcript` parameter on `process_input` tool
+
+The stripping is performed by `strip_subtitle_formatting()` in
+`aimd_media.url.formatter`, applied in `aimd_media.url.processor` before
+`format_content()` embeds the text into the markdown output.
+
+## TRANSCRIPTION MODELS
+
+- Engine names are fixed in `const.TRANSCRIPTION_ENGINES`: `auto`, `mlx`, `qwen`.
+- `mlx` is implemented in `aimd_media.mlx_engine` and uses `mlx_audio.stt.load()` on Apple Silicon. The default remains `mlx-community/Qwen3-ASR-1.7B-4bit`; `const.MLX_AUDIO_MODELS` also tracks newer mlx-audio 0.4.4 STT IDs. Do not add forced-aligner models to this list unless the calling code also supplies reference text.
+- `qwen` is implemented in `aimd_media.qwen_engine` and uses a direct Transformers backend on Linux/CUDA with `Qwen/Qwen3-ASR-1.7B` default and `Qwen/Qwen3-ASR-0.6B` as the lower-memory option.
+- mlx Qwen3-ASR defaults omitted language to `Chinese`; other mlx-audio STT models stay on their own default/auto language behavior.

aimd/__init__.py

@@ -0,0 +1,13 @@
+"""aimd: Context preparation tool for LLM workflows."""
+
+from .utils import (
+    sanitize_filename,
+    create_output_path_from_title,
+    is_url,
+)
+
+__all__ = [
+    "sanitize_filename",
+    "create_output_path_from_title",
+    "is_url",
+]

aimd/adapters/AGENTS.md

@@ -0,0 +1,23 @@
+# packages/aimd/src/aimd/adapters
+
+Interface adapters for the core CLI package.
+
+## Responsibilities
+
+- Parse interface-level input.
+- Map payloads/options to `application.models.ProcessInput`.
+- Map use-case output/errors to CLI output format.
+- Expose engine/model choices without duplicating backend validation logic.
+
+## Current Interfaces
+
+- CLI (`cli/app.py`): `aimd <input_source>` with `--output`, `--engine`, `--model`, `--language`, `--save-original`, `--cookies`, `--cookies-from-browser`, `--log-level`, `--raw-transcript`, and `--temp-dir` / `AIMD_TEMP_DIR`.
+- HTTP lives in the `aimd-api` package.
+- MCP lives in the `aimd-mcp` package.
+
+## Rules
+
+- Do not implement core processing logic in adapters.
+- Reuse shared output persistence helpers from `application/services`.
+- Keep CLI option descriptions aligned with ASR plugin model constants and `ProcessInput`.
+- Do not import infrastructure processing modules directly; adapters should call application use-cases.

aimd/adapters/__init__.py

@@ -0,0 +1 @@
+"""Core CLI adapter package."""

aimd/adapters/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI adapter package."""

aimd/adapters/cli/app.py

@@ -0,0 +1,216 @@
+"""CLI adapter for aimd."""
+
+import asyncio
+from pathlib import Path
+from typing import Optional
+
+import typer
+from dotenv import load_dotenv
+from logly import logger
+
+from ...application.bootstrap import build_container
+from ...application.models import ProcessInput
+from ...application.services.output_writer import persist_output
+from ...errors import AimdError
+from ...utils import create_output_path_from_title
+
+load_dotenv()
+
+logger.remove_all()
+logger.configure(color=True, auto_sink=False)
+logger.add(
+    "console",
+    filter_min_level="INFO",
+    format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {module}:{function} - {message}",
+)
+
+app = typer.Typer(
+    name="aimd",
+    help="Context preparation tool for LLM workflows - Transcribe audio/video and convert documents",
+    no_args_is_help=True,
+)
+
+
+def _configure_logging(log_level: str) -> None:
+    valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+    if str(log_level).upper() not in valid_levels:
+        typer.echo(
+            f"Error: Invalid log level '{log_level}'. Valid levels: {', '.join(valid_levels)}",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    logger.remove_all()
+    logger.configure(color=True, auto_sink=False)
+    logger.add(
+        "console",
+        filter_min_level=str(log_level).upper(),
+        format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {module}:{function} - {message}",
+    )
+
+    if str(log_level).upper() == "DEBUG":
+        logger.debug(f"Logging level configured to: {log_level}")
+
+
+@app.command()
+def process(
+    input_source: str = typer.Argument(
+        ...,
+        help="Audio file, video file, video URL, or document to process",
+    ),
+    output_file: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file path. If not specified, auto-generated from input",
+    ),
+    transcribe_engine: str = typer.Option(
+        "auto",
+        "--engine",
+        "-e",
+        help="Transcription engine: mlx (Apple Silicon, mlx-audio STT), qwen (Linux/CUDA, Qwen3-ASR via Transformers).",
+    ),
+    model: Optional[str] = typer.Option(
+        None,
+        "--model",
+        "-m",
+        help="Model for transcription. mlx defaults to mlx-community/Qwen3-ASR-1.7B-4bit "
+        "and also supports other documented mlx-audio STT model IDs. "
+        "qwen supports Qwen/Qwen3-ASR-1.7B (default) or Qwen/Qwen3-ASR-0.6B.",
+    ),
+    language: Optional[str] = typer.Option(
+        None,
+        "--language",
+        "-l",
+        help="Language code for transcription (e.g., zh, en, ja).",
+    ),
+    save_original: Optional[Path] = typer.Option(
+        None,
+        "--save-original",
+        "-s",
+        help="Save original downloaded audio/video file to a path or directory.",
+    ),
+    cookies: Optional[Path] = typer.Option(
+        None,
+        "--cookies",
+        "-c",
+        help="Path to Netscape-format cookies file for URL extraction.",
+    ),
+    cookies_from_browser: Optional[str] = typer.Option(
+        None,
+        "--cookies-from-browser",
+        help="Browser cookie source for URL extraction.",
+    ),
+    log_level: str = typer.Option(
+        "INFO",
+        "--log-level",
+        help="Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL",
+    ),
+    raw_transcript: bool = typer.Option(
+        False,
+        "--raw-transcript",
+        help="Preserve original subtitle formatting (SRT/VTT timestamps). "
+        "By default, subtitles are simplified to plain text.",
+    ),
+    temp_dir: Optional[Path] = typer.Option(
+        None,
+        "--temp-dir",
+        help="Custom temporary directory for intermediate files. "
+        "Overrides AIMD_TEMP_DIR env var. Useful for sandboxed environments.",
+        envvar="AIMD_TEMP_DIR",
+    ),
+) -> None:
+    """Process audio/video/url/doc inputs to markdown."""
+    _configure_logging(log_level)
+    container = build_container()
+
+    try:
+        route = container.process_input_use_case.ensure_supported_input(input_source)
+        task_type = route.task_type
+    except AimdError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    logger.info(f"Input: {input_source}")
+    logger.info(f"Source: {route.source_kind}")
+    logger.info(f"Task: {task_type}")
+    if task_type == "transcript":
+        logger.info(f"Transcription Engine: {transcribe_engine}")
+
+    async def run_processing() -> None:
+        try:
+            resolved_temp_dir = temp_dir
+            if resolved_temp_dir is not None:
+                resolved_temp_dir.mkdir(parents=True, exist_ok=True)
+                logger.info(f"Using custom temp directory: {resolved_temp_dir}")
+
+            result = await container.process_input_use_case.execute(
+                ProcessInput(
+                    input_source=input_source,
+                    transcribe_engine=transcribe_engine,
+                    model=model,
+                    language=language,
+                    save_original=save_original,
+                    cookies=cookies,
+                    cookies_from_browser=cookies_from_browser,
+                    temp_dir=resolved_temp_dir,
+                    raw_transcript=raw_transcript,
+                )
+            )
+
+            if result.platform:
+                logger.info(f"Platform: {result.platform}")
+
+            if result.task_type == "convert" and result.output_dir is not None:
+                input_path = Path(input_source)
+                logger.info(f"Book converted with images to: {result.output_dir}")
+                logger.info(f"Main file: {result.output_dir / f'{input_path.stem}.md'}")
+                logger.info(f"Images extracted to: {result.output_dir / 'images'}")
+                typer.echo("Successfully converted book with images")
+                typer.echo(f"Output saved to {result.output_dir}")
+                return
+
+            final_output_file = output_file
+            if final_output_file is None:
+                suffix = (
+                    "transcript" if result.task_type == "transcript" else "converted"
+                )
+                default_dir = (
+                    Path.cwd()
+                    if result.task_type == "transcript"
+                    else Path(input_source).parent
+                )
+                final_output_file = create_output_path_from_title(
+                    result.text_context.title,
+                    suffix,
+                    default_dir,
+                )
+
+            logger.info(f"Output: {final_output_file}")
+            persist_output(
+                final_output_file,
+                result.task_type,
+                result.text_context.chunk_list,
+            )
+
+            if result.task_type == "transcript":
+                logger.info(f"Transcript saved to: {final_output_file}")
+                typer.echo("Successfully transcribed")
+            else:
+                logger.info(f"Converted file saved to: {final_output_file}")
+                typer.echo("Successfully converted")
+            typer.echo(f"Output saved to {final_output_file}")
+        except AimdError as e:
+            logger.error(str(e))
+            raise typer.Exit(1)
+        except Exception as e:
+            task_name = "Transcription" if task_type == "transcript" else "Conversion"
+            logger.error(f"{task_name} failed: {e}")
+            raise typer.Exit(1)
+
+    asyncio.run(run_processing())
+
+
+def main() -> None:
+    """Entry point for CLI app."""
+    app()

aimd/application/AGENTS.md

@@ -0,0 +1,31 @@
+# packages/aimd/src/aimd/application
+
+Application layer: orchestration and canonical models.
+
+## Responsibilities
+
+- Define request/response models used across interfaces.
+- Implement use-cases (`process_input`, `input_routing`, `list_engines`) and task processors under `use_cases/processors/`.
+- Wire dependencies explicitly in `bootstrap.py`.
+- Keep output persistence in `services/output_writer.py` so CLI/API/MCP share identical file behavior.
+
+## Current Flow
+
+- `ProcessInput` carries `input_source`, output path, engine/model/language, URL cookie options, `save_original`, `raw_transcript`, and `temp_dir`.
+- `input_routing.py` returns `InputRoute(source_kind, task_type)`.
+- `source_kind` describes what the user supplied: `url`, `audio_file`, `video_file`, `document_file`, or `unknown`.
+- `task_type` describes which processing task runs: currently `transcript` or `convert`.
+- `process_input.py` is the facade/router: it dispatches `InputRoute` to configured `TaskProcessor` objects.
+- `processors/transcript.py` owns URL/audio transcript flow and resolves transcription engines early.
+- `processors/convert.py` owns local document conversion flow through MarkItDown.
+- `ListEnginesUseCase` returns capability detector output for adapter `/v1/engines` and MCP `list_engines`.
+
+## Rules
+
+- No direct adapter imports.
+- Keep business flow in use-cases; avoid embedding third-party integration logic here.
+- Keep each task implementation in its own processor module; local file conversion should call the MarkItDown runner rather than feature package internals.
+- Route by the pair `(source_kind, task_type)`; avoid collapsing source classification into task naming.
+- Keep dependency registration explicit in `bootstrap.py`; do not add a custom aimd plugin registry or priority routing until requirements justify it.
+- Do not hard-code platform/model availability in application code; use infrastructure capability detection and constants.
+- Preserve the `TextContext(title, chunk_list, split_header_level)` contract across interfaces.

aimd/application/__init__.py

@@ -0,0 +1,14 @@
+"""Application layer package."""
+
+from .bootstrap import AppContainer, build_container
+from .models import InputRoute, ProcessInput, ProcessResult, SourceKind, TaskType
+
+__all__ = [
+    "AppContainer",
+    "InputRoute",
+    "ProcessInput",
+    "ProcessResult",
+    "SourceKind",
+    "TaskType",
+    "build_container",
+]

aimd/application/bootstrap.py

@@ -0,0 +1,51 @@
+"""Application bootstrap and explicit dependency wiring."""
+
+from dataclasses import dataclass
+
+from aimd_media import (
+    get_engine_capabilities,
+    resolve_engine_with_preflight,
+)
+
+from ..infrastructure.markitdown_processor import (
+    convert_file_with_markitdown,
+    is_supported_file,
+)
+from ..infrastructure.media_processor import get_text_context_from_media_url
+from .use_cases.list_engines import ListEnginesUseCase
+from .use_cases.process_input import ProcessInputUseCase
+from .use_cases.processors import ConvertTaskProcessor, TranscriptTaskProcessor
+
+
+@dataclass(slots=True)
+class AppContainer:
+    """Resolved dependencies and use-cases for all adapters."""
+
+    process_input_use_case: ProcessInputUseCase
+    list_engines_use_case: ListEnginesUseCase
+
+
+def build_container() -> AppContainer:
+    """Build app container with explicit dependency wiring."""
+    transcript_processor = TranscriptTaskProcessor(
+        process_url=get_text_context_from_media_url,
+        process_file=convert_file_with_markitdown,
+        resolve_engine=resolve_engine_with_preflight,
+    )
+    convert_processor = ConvertTaskProcessor(
+        process_file=convert_file_with_markitdown,
+    )
+
+    return AppContainer(
+        process_input_use_case=ProcessInputUseCase(
+            processors={
+                "transcript": transcript_processor,
+                "convert": convert_processor,
+            },
+            is_supported_file=is_supported_file,
+        ),
+        list_engines_use_case=ListEnginesUseCase(
+            get_capabilities=get_engine_capabilities,
+            resolve_engine=resolve_engine_with_preflight,
+        ),
+    )

aimd/application/models.py

@@ -0,0 +1,43 @@
+"""Application-level request/response models."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from ..types import TextContext
+
+SourceKind = Literal["url", "audio_file", "video_file", "document_file", "unknown"]
+TaskType = Literal["transcript", "convert"]
+
+
+@dataclass(slots=True, frozen=True)
+class InputRoute:
+    """Classified input source and selected processing task."""
+
+    source_kind: SourceKind
+    task_type: TaskType | None
+
+
+@dataclass(slots=True)
+class ProcessInput:
+    """Canonical process request model consumed by use-cases."""
+
+    input_source: str
+    transcribe_engine: str = "auto"
+    model: str | None = None
+    language: str | None = None
+    save_original: Path | None = None
+    cookies: Path | None = None
+    cookies_from_browser: str | None = None
+    temp_dir: Path | None = None
+    raw_transcript: bool = False
+
+
+@dataclass(slots=True)
+class ProcessResult:
+    """Canonical process response model produced by use-cases."""
+
+    task_type: TaskType
+    text_context: TextContext
+    output_dir: Path | None = None
+    platform: str | None = None

aimd/application/services/__init__.py

@@ -0,0 +1 @@
+"""Application service helpers."""

aimd/application/services/interface_payloads.py

@@ -0,0 +1,81 @@
+"""Shared adapter mapping helpers."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+from ..models import ProcessInput, ProcessResult
+from ..use_cases.list_engines import ListEnginesResult
+
+
+def get_request_temp_dir() -> Path | None:
+    """Read and prepare AIMD_TEMP_DIR at request time."""
+    env_temp_dir = os.environ.get("AIMD_TEMP_DIR")
+    if not env_temp_dir:
+        return None
+
+    temp_dir = Path(env_temp_dir)
+    temp_dir.mkdir(parents=True, exist_ok=True)
+    return temp_dir
+
+
+def build_process_input(
+    *,
+    input_source: str,
+    transcribe_engine: str = "auto",
+    model: str | None = None,
+    language: str | None = None,
+    save_original: str | Path | None = None,
+    cookies: str | Path | None = None,
+    cookies_from_browser: str | None = None,
+    raw_transcript: bool = False,
+    temp_dir: Path | None = None,
+) -> ProcessInput:
+    """Build the canonical process request from adapter-level values."""
+    return ProcessInput(
+        input_source=input_source,
+        transcribe_engine=transcribe_engine,
+        model=model,
+        language=language,
+        save_original=Path(save_original) if save_original else None,
+        cookies=Path(cookies) if cookies else None,
+        cookies_from_browser=cookies_from_browser,
+        temp_dir=temp_dir,
+        raw_transcript=raw_transcript,
+    )
+
+
+def engine_capabilities_payload(result: ListEnginesResult) -> dict[str, Any]:
+    """Return a JSON-friendly engine capability payload."""
+    ordered_engines = ("mlx", "qwen")
+    return {
+        "auto_selected_engine": result.auto_selected_engine,
+        "engines": [
+            {
+                "name": engine,
+                "available": result.engines[engine].available,
+                "reason": result.engines[engine].reason,
+                "fix_hint": result.engines[engine].fix_hint,
+                "selected_by_auto": engine == result.auto_selected_engine,
+            }
+            for engine in ordered_engines
+        ],
+    }
+
+
+def process_result_payload(
+    result: ProcessResult,
+    *,
+    output_file: str | None,
+    output_dir: str | None,
+) -> dict[str, Any]:
+    """Return a JSON-friendly process result payload."""
+    return {
+        "task_type": result.task_type,
+        "title": result.text_context.title,
+        "chunk_list": result.text_context.chunk_list,
+        "split_header_level": result.text_context.split_header_level,
+        "platform": result.platform,
+        "output_file": output_file,
+        "output_dir": output_dir,
+    }

aimd/application/services/output_writer.py

@@ -0,0 +1,68 @@
+"""Shared output persistence helpers for adapters and use-cases."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from ..models import ProcessResult
+
+
+def build_output_text(
+    task_type: Literal["transcript", "convert"],
+    chunk_list: list[str],
+) -> str:
+    """Build persisted markdown text for the given task output."""
+    if task_type == "transcript":
+        text = chunk_list[0] if chunk_list else ""
+        if not text:
+            raise ValueError("Transcription returned empty content")
+        return text
+
+    return "\n\n".join(chunk_list)
+
+
+def persist_output(
+    output_file: Path,
+    task_type: Literal["transcript", "convert"],
+    chunk_list: list[str],
+) -> Path:
+    """Write task output to disk and return resolved path."""
+    text = build_output_text(task_type, chunk_list)
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    output_file.write_text(text, encoding="utf-8")
+    return output_file.resolve()
+
+
+@dataclass(slots=True, frozen=True)
+class PersistedOutput:
+    """Adapter-facing output locations after optional persistence."""
+
+    output_file: str | None
+    output_dir: str | None
+    ignored_output_file: bool = False
+
+
+def persist_result_output_if_requested(
+    result: ProcessResult,
+    requested_output_file: str | Path | None,
+) -> PersistedOutput:
+    """Persist a result when an adapter requested a file output."""
+    output_dir = (
+        str(result.output_dir.resolve()) if result.output_dir is not None else None
+    )
+    if requested_output_file is None:
+        return PersistedOutput(output_file=None, output_dir=output_dir)
+
+    if result.output_dir is not None:
+        return PersistedOutput(
+            output_file=None,
+            output_dir=output_dir,
+            ignored_output_file=True,
+        )
+
+    resolved = persist_output(
+        Path(requested_output_file),
+        result.task_type,
+        result.text_context.chunk_list,
+    )
+    return PersistedOutput(output_file=str(resolved), output_dir=None)

aimd/application/use_cases/__init__.py

@@ -0,0 +1 @@
+"""Application use-cases."""

aimd/application/use_cases/input_routing.py

@@ -0,0 +1,51 @@
+"""Input classification and support checks for processing use-cases."""
+
+from pathlib import Path
+from typing import Callable
+
+from ...errors import InputNotFoundError, UnsupportedInputError
+from ...utils import is_url
+from ..models import InputRoute
+
+from aimd_media.const import AUDIO_FILE_EXTENSIONS, VIDEO_FILE_EXTENSIONS
+
+FileSupportChecker = Callable[[str | Path], bool]
+
+
+def get_input_route(
+    input_source: str, is_supported_file: FileSupportChecker
+) -> InputRoute:
+    """Classify a source and select the processing task."""
+    if is_url(input_source):
+        return InputRoute(source_kind="url", task_type="transcript")
+
+    try:
+        file_path = Path(input_source)
+        if file_path.exists():
+            suffix = file_path.suffix.lower()
+            if suffix in AUDIO_FILE_EXTENSIONS:
+                return InputRoute(source_kind="audio_file", task_type="transcript")
+            if suffix in VIDEO_FILE_EXTENSIONS:
+                return InputRoute(source_kind="video_file", task_type="transcript")
+            if is_supported_file(file_path):
+                return InputRoute(source_kind="document_file", task_type="convert")
+    except (OSError, ValueError):
+        pass
+
+    return InputRoute(source_kind="unknown", task_type=None)
+
+
+def ensure_supported_input(
+    input_source: str, is_supported_file: FileSupportChecker
+) -> InputRoute:
+    """Validate and return supported input route, else raise domain error."""
+    route = get_input_route(input_source, is_supported_file)
+    if route.task_type is None:
+        input_path = Path(input_source)
+        if not is_url(input_source) and input_path.suffix and not input_path.exists():
+            raise InputNotFoundError(f"Input file not found: {input_source}")
+        raise UnsupportedInputError(
+            "Unsupported input source. Supported inputs: audio/video files, "
+            "video URLs, and supported document files."
+        )
+    return route