aimd-cli 0.9.2__py3-none-any.whl

aimd/application/use_cases/list_engines.py

@@ -0,0 +1,34 @@
+"""Use-case for engine capability introspection."""
+
+from dataclasses import dataclass
+from typing import Callable
+
+from aimd_media import EngineCapability
+from aimd_media.errors import EngineUnavailableError
+
+
+@dataclass(slots=True)
+class ListEnginesResult:
+    auto_selected_engine: str | None
+    engines: dict[str, EngineCapability]
+
+
+@dataclass(slots=True)
+class ListEnginesUseCase:
+    """List available transcription engines and auto-selected preference."""
+
+    get_capabilities: Callable[[], dict[str, EngineCapability]]
+    resolve_engine: Callable[[str], str]
+
+    def execute(self) -> ListEnginesResult:
+        capabilities = self.get_capabilities()
+        auto_selected_engine: str | None = None
+        try:
+            auto_selected_engine = self.resolve_engine("auto")
+        except EngineUnavailableError:
+            auto_selected_engine = None
+
+        return ListEnginesResult(
+            auto_selected_engine=auto_selected_engine,
+            engines=capabilities,
+        )

aimd/application/use_cases/process_input.py

@@ -0,0 +1,40 @@
+"""Use-case for input processing orchestration."""
+
+from dataclasses import dataclass
+from typing import Mapping
+
+from ...errors import InputNotFoundError, ProcessingFailedError, UnsupportedInputError
+from ..models import InputRoute, ProcessInput, ProcessResult, TaskType
+from .input_routing import FileSupportChecker, ensure_supported_input
+from .processors import TaskProcessor
+
+
+@dataclass(slots=True)
+class ProcessInputUseCase:
+    """Core facade/router for processing routed inputs."""
+
+    processors: Mapping[TaskType, TaskProcessor]
+    is_supported_file: FileSupportChecker
+
+    def ensure_supported_input(self, input_source: str) -> InputRoute:
+        """Validate and return the source/task route for a source."""
+        return ensure_supported_input(input_source, self.is_supported_file)
+
+    async def execute(self, request: ProcessInput) -> ProcessResult:
+        route = self.ensure_supported_input(request.input_source)
+        task_type = route.task_type
+        if task_type is None:
+            raise UnsupportedInputError("Unsupported input source.")
+
+        processor = self.processors.get(task_type)
+        if processor is None:
+            raise UnsupportedInputError(
+                f"No processor configured for task: {task_type}"
+            )
+
+        try:
+            return await processor.process(request, route)
+        except (InputNotFoundError, UnsupportedInputError, ProcessingFailedError):
+            raise
+        except Exception as exc:
+            raise ProcessingFailedError(str(exc)) from exc

aimd/application/use_cases/processors/__init__.py

@@ -0,0 +1,13 @@
+"""Task processors used by the process input facade."""
+
+from ._base import TaskProcessor
+from .convert import ConvertProcessor, ConvertTaskProcessor
+from .transcript import TranscriptProcessor, TranscriptTaskProcessor
+
+__all__ = [
+    "ConvertProcessor",
+    "ConvertTaskProcessor",
+    "TaskProcessor",
+    "TranscriptProcessor",
+    "TranscriptTaskProcessor",
+]

aimd/application/use_cases/processors/_base.py

@@ -0,0 +1,17 @@
+"""Base task processor contract."""
+
+from typing import Protocol
+
+from ...models import InputRoute, ProcessInput, ProcessResult
+
+
+class TaskProcessor(Protocol):
+    """Process one routed task into a canonical result."""
+
+    async def process(
+        self,
+        request: ProcessInput,
+        route: InputRoute,
+    ) -> ProcessResult:
+        """Run task-specific processing for a routed input."""
+        ...

aimd/application/use_cases/processors/convert.py

@@ -0,0 +1,35 @@
+"""Document conversion task processor."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from ....types import TextContext
+from ...models import InputRoute, ProcessInput, ProcessResult
+
+ConvertProcessor = Callable[
+    [str, str, str | None, str | None, Path | None],
+    Awaitable[tuple[TextContext, Path | None]],
+]
+
+
+@dataclass(slots=True)
+class ConvertTaskProcessor:
+    """Run document conversion tasks."""
+
+    process_file: ConvertProcessor
+
+    async def process(
+        self,
+        request: ProcessInput,
+        route: InputRoute,  # noqa: ARG002
+    ) -> ProcessResult:
+        input_path = Path(request.input_source)
+        text_context, output_dir = await self.process_file(
+            input_path.as_posix(), "auto", None, None, request.temp_dir
+        )
+        return ProcessResult(
+            task_type="convert",
+            text_context=text_context,
+            output_dir=output_dir,
+        )

aimd/application/use_cases/processors/transcript.py

@@ -0,0 +1,92 @@
+"""Transcript task processor."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from ....errors import InputNotFoundError
+from ....types import TextContext
+from ....utils import is_url
+from ...models import InputRoute, ProcessInput, ProcessResult
+
+TranscriptProcessor = Callable[
+    [
+        str,
+        str,
+        str | None,
+        str | None,
+        Path | None,
+        Path | None,
+        str | None,
+        Path | None,
+        bool,
+    ],
+    Awaitable[tuple[TextContext, str | None]],
+]
+
+
+@dataclass(slots=True)
+class TranscriptTaskProcessor:
+    """Run transcript tasks for URLs and local audio/video files."""
+
+    process_url: Callable[
+        [
+            str,
+            str,
+            str | None,
+            str | None,
+            Path | None,
+            str | None,
+            str | None,
+            Path | None,
+            bool,
+        ],
+        Awaitable[tuple[TextContext, str]],
+    ]
+    process_file: Callable[
+        [str, str, str | None, str | None, Path | None],
+        Awaitable[tuple[TextContext, Path | None]],
+    ]
+    resolve_engine: Callable[[str], str]
+
+    async def process(
+        self,
+        request: ProcessInput,
+        route: InputRoute,  # noqa: ARG002
+    ) -> ProcessResult:
+        if is_url(request.input_source):
+            if request.transcribe_engine != "auto":
+                self.resolve_engine(request.transcribe_engine)
+            text_context, platform = await self.process_url(
+                request.input_source,
+                request.transcribe_engine,
+                request.language,
+                request.model,
+                request.save_original,
+                str(request.cookies) if request.cookies else None,
+                request.cookies_from_browser,
+                request.temp_dir,
+                request.raw_transcript,
+            )
+        else:
+            input_path = Path(request.input_source)
+            if not input_path.exists():
+                raise InputNotFoundError(
+                    f"Input file not found: {request.input_source}"
+                )
+
+            resolved_engine = self.resolve_engine(request.transcribe_engine)
+            text_context, _ = await self.process_file(
+                input_path.as_posix(),
+                resolved_engine,
+                request.language,
+                request.model,
+                request.temp_dir,
+            )
+            platform = None
+
+        return ProcessResult(
+            task_type="transcript",
+            text_context=text_context,
+            platform=platform,
+        )

aimd/cli.py

@@ -0,0 +1,9 @@
+"""CLI entrypoint."""
+
+from .adapters.cli.app import app, main
+
+__all__ = ["app", "main"]
+
+
+if __name__ == "__main__":
+    main()

aimd/const.py

@@ -0,0 +1,31 @@
+"""Constants used throughout the aimd package."""
+
+# =============================================================================
+# FILE PROCESSING CONSTANTS
+# =============================================================================
+
+from aimd_media.const import AUDIO_EXTENSIONS
+
+# Ebook file extensions (require special handling for image extraction)
+BOOK_EXTENSIONS = {".epub", ".mobi", ".azw3"}
+
+MARKITDOWN_FILE_EXTENSIONS = (
+    AUDIO_EXTENSIONS
+    | BOOK_EXTENSIONS
+    | {
+        ".csv",
+        ".doc",
+        ".docx",
+        ".html",
+        ".htm",
+        ".json",
+        ".md",
+        ".pdf",
+        ".ppt",
+        ".pptx",
+        ".txt",
+        ".xls",
+        ".xlsx",
+        ".xml",
+    }
+)

aimd/errors.py

@@ -0,0 +1,41 @@
+"""Domain-level exceptions used across CLI, service, and API layers."""
+
+
+class AimdError(Exception):
+    """Base exception for predictable aimd errors."""
+
+    status_code = 400
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+
+
+class UnsupportedInputError(AimdError):
+    """Raised when input source is unsupported."""
+
+    status_code = 400
+
+
+class UnsupportedEngineError(AimdError):
+    """Raised when an unknown transcription engine is requested."""
+
+    status_code = 400
+
+
+class EngineUnavailableError(AimdError):
+    """Raised when a known engine cannot run on current environment."""
+
+    status_code = 422
+
+
+class InputNotFoundError(AimdError):
+    """Raised when input path does not exist."""
+
+    status_code = 404
+
+
+class ProcessingFailedError(AimdError):
+    """Raised when processing fails in a known way."""
+
+    status_code = 500

aimd/infrastructure/AGENTS.md

@@ -0,0 +1,26 @@
+# packages/aimd/src/aimd/infrastructure
+
+Infrastructure layer in the main `aimd` package.
+
+## Responsibilities
+
+- MarkItDown runner for local file conversion (`markitdown_processor.py`).
+- Media adapter that wraps `aimd-media` URL extraction results as `TextContext`.
+- Markdown chunking/title helpers for MarkItDown output.
+
+## Model Notes
+
+- `aimd_media.const.MLX_AUDIO_MODELS` is a curated allow-list for mlx-audio STT IDs. It includes Qwen3-ASR quantized variants plus newer mlx-audio 0.4.4 STT models such as Whisper, Distil-Whisper, Parakeet, Nemotron ASR, Voxtral, VibeVoice-ASR, and Qwen2-Audio.
+- Do not add mlx-audio forced aligner models to transcription until the product/API accepts reference text and timestamp output.
+- mlx Qwen3-ASR gets a default `Chinese` language hint for existing behavior. Other mlx-audio STT models should receive no language hint unless the caller provided one and the model `generate()` signature accepts `language`.
+- `aimd_media.const.QWEN_ASR_MODELS` tracks official Qwen3-ASR models only: `Qwen/Qwen3-ASR-1.7B` and `Qwen/Qwen3-ASR-0.6B`.
+- Qwen3-ASR upstream supports more languages/dialects than the local `LANGUAGE_CODE_TO_NAME` table exposes; expanding the table is a valid small follow-up if the adapters need those codes.
+
+## Rules
+
+- Do not import adapters.
+- Keep modules focused and small by pipeline concern.
+- Raise domain errors from `aimd.errors`.
+- Keep capability checks fail-fast before expensive model work.
+- When using `tempfile.TemporaryDirectory` or `tempfile.NamedTemporaryFile`, always pass the `dir=temp_dir` parameter so callers can redirect temp I/O to a sandbox-safe location via `AIMD_TEMP_DIR`.
+- Do not add compatibility aliases for old internal paths; local file processors should use MarkItDown contracts.

aimd/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure layer package."""

aimd/infrastructure/documents/__init__.py

@@ -0,0 +1,19 @@
+"""Document processing infrastructure."""
+
+from .chunking import (
+    combine_sections_for_processing,
+    split_markdown_by_header_level,
+    split_markdown_by_headers,
+    split_processed_chunk_into_chapters,
+    split_text_by_paragraphs,
+)
+from .title_extractor import extract_title_from_content
+
+__all__ = [
+    "combine_sections_for_processing",
+    "extract_title_from_content",
+    "split_markdown_by_header_level",
+    "split_markdown_by_headers",
+    "split_processed_chunk_into_chapters",
+    "split_text_by_paragraphs",
+]

aimd/infrastructure/documents/chunking.py

@@ -0,0 +1,168 @@
+"""Chunking helpers for markdown document processing."""
+
+import re
+
+from logly import logger
+
+
+def combine_sections_for_processing(
+    section_data: list[tuple[str | None, str]], max_chunk_size: int = 40000
+) -> list[str]:
+    """Combine multiple sections into larger chunks to reduce API calls."""
+    combined_chunks = []
+    current_chunk_parts = []
+    current_chunk_size = 0
+    section_separator = "\n\n" + "=" * 80 + "\n\n"
+    separator_size = len(section_separator)
+
+    for _, content in section_data:
+        section_size = len(content)
+        would_exceed = (
+            current_chunk_size
+            + section_size
+            + (separator_size if current_chunk_parts else 0)
+        ) > max_chunk_size
+
+        if would_exceed and current_chunk_parts:
+            combined_chunks.append(section_separator.join(current_chunk_parts))
+            current_chunk_parts = []
+            current_chunk_size = 0
+
+        current_chunk_parts.append(content)
+        current_chunk_size += section_size
+        if len(current_chunk_parts) > 1:
+            current_chunk_size += separator_size
+
+    if current_chunk_parts:
+        combined_chunks.append(section_separator.join(current_chunk_parts))
+
+    return combined_chunks
+
+
+def split_text_by_paragraphs(text: str, max_chunk_size: int) -> list[str]:
+    """Split text by paragraph boundaries and then hard-wrap oversized blocks."""
+    paragraphs = [
+        block.strip() for block in re.split(r"\n\s*\n", text) if block.strip()
+    ]
+    if not paragraphs:
+        stripped = text.strip()
+        return [stripped] if stripped else []
+
+    chunks: list[str] = []
+    current_parts: list[str] = []
+    current_size = 0
+
+    for paragraph in paragraphs:
+        paragraph_len = len(paragraph)
+        separator = "\n\n" if current_parts else ""
+        projected = current_size + len(separator) + paragraph_len
+        if current_parts and projected > max_chunk_size:
+            chunks.append("\n\n".join(current_parts))
+            current_parts = []
+            current_size = 0
+
+        if paragraph_len <= max_chunk_size:
+            current_parts.append(paragraph)
+            current_size += (2 if current_size else 0) + paragraph_len
+            continue
+
+        if current_parts:
+            chunks.append("\n\n".join(current_parts))
+            current_parts = []
+            current_size = 0
+
+        for idx in range(0, paragraph_len, max_chunk_size):
+            piece = paragraph[idx : idx + max_chunk_size].strip()
+            if piece:
+                chunks.append(piece)
+
+    if current_parts:
+        chunks.append("\n\n".join(current_parts))
+    return chunks
+
+
+def split_markdown_by_header_level(
+    markdown_content: str,
+    header_level: int,
+) -> list[tuple[str | None, str]]:
+    """Split markdown content by a specific header level."""
+    header_pattern = f"^{'#' * header_level}\\s+(.+)$"
+    lines = markdown_content.split("\n")
+
+    sections = []
+    current_lines = []
+    current_title = None
+
+    def _save_current_section() -> None:
+        if current_lines:
+            content = "\n".join(current_lines).strip()
+            if content:
+                sections.append((current_title, content))
+
+    for line in lines:
+        header_match = re.match(header_pattern, line)
+
+        if header_match:
+            _save_current_section()
+            current_title = header_match.group(1).strip()
+            current_lines = [line]
+        else:
+            current_lines.append(line)
+
+    _save_current_section()
+    return sections
+
+
+def split_markdown_by_headers(
+    markdown_content: str,
+    max_chunk_size: int = 40000,
+) -> tuple[list[tuple[str | None, str]], int | None]:
+    """Split markdown by best-fit header level with paragraph fallback."""
+    for split_level in range(1, 7):
+        sections = split_markdown_by_header_level(markdown_content, split_level)
+        if len(sections) <= 1:
+            continue
+
+        all_under_limit = True
+        max_section_size = 0
+        for _, section_content in sections:
+            section_size = len(section_content)
+            max_section_size = max(max_section_size, section_size)
+            if section_size > max_chunk_size:
+                all_under_limit = False
+                break
+
+        if all_under_limit:
+            logger.info(
+                f"Using split level {split_level} - all chunks under {max_chunk_size} chars (max: {max_section_size})"
+            )
+            return sections, split_level
+
+    fallback_chunks = split_text_by_paragraphs(markdown_content, max_chunk_size)
+    return [(None, chunk) for chunk in fallback_chunks], None
+
+
+def split_processed_chunk_into_chapters(
+    processed_content: str,
+    header_level: int | None = None,
+) -> list[tuple[str, str]]:
+    """Split processed content back into chapters using stored header level."""
+    from .title_extractor import extract_title_from_content
+
+    if header_level is not None:
+        sections = split_markdown_by_header_level(processed_content, header_level)
+        chapters = []
+        for title, content in sections:
+            if content.strip():
+                clean_title = extract_title_from_content(
+                    content,
+                    title or "Chapter",
+                    for_filename=True,
+                )
+                chapters.append((clean_title, content.strip()))
+
+        if chapters:
+            return chapters
+
+    title = extract_title_from_content(processed_content, "Chapter", for_filename=True)
+    return [(title, processed_content.strip())]

aimd/infrastructure/documents/title_extractor.py

@@ -0,0 +1,90 @@
+"""Title extraction utilities for markdown content."""
+
+import re
+
+
+def extract_title_from_content(
+    content: str, fallback_title: str = "Untitled", for_filename: bool = False
+) -> str:
+    """Extract and clean title from content with unified logic."""
+    if not content or not content.strip():
+        return fallback_title
+
+    lines = content.strip().split("\n")
+    extracted_title = None
+
+    for line in lines:
+        line = line.strip()
+        if line.startswith("# "):
+            extracted_title = line[2:].strip()
+            break
+
+    if not extracted_title and content.strip().startswith("---"):
+        in_frontmatter = False
+        for line in lines:
+            if line.strip() == "---":
+                if in_frontmatter:
+                    break
+                in_frontmatter = True
+                continue
+            if in_frontmatter and line.strip().startswith("title:"):
+                title_match = re.match(r'title:\s*["\']?([^"\']+)["\']?', line.strip())
+                if title_match:
+                    extracted_title = title_match.group(1).strip()
+                    break
+
+    if not extracted_title:
+        for i, line in enumerate(lines):
+            if i + 1 < len(lines):
+                next_line = lines[i + 1].strip()
+                if next_line and (
+                    all(c == "=" for c in next_line) or all(c == "-" for c in next_line)
+                ):
+                    extracted_title = line.strip()
+                    break
+
+    if not extracted_title:
+        for line in lines[:5]:
+            line = line.strip()
+            if not line:
+                continue
+            if (
+                line.startswith("![")
+                or line.startswith("[]{")
+                or line.startswith(":::")
+                or line.startswith("<div")
+                or line.startswith("</div")
+                or "calibre" in line.lower()
+                or "kindle-cn" in line.lower()
+            ):
+                continue
+            if (
+                len(line) >= 2
+                and len(line) <= 100
+                and not line.lower().startswith("http")
+            ):
+                extracted_title = line
+                break
+
+    if not extracted_title:
+        return fallback_title
+
+    clean_text = re.sub(r"^#+\s*", "", extracted_title)
+    clean_text = re.sub(r"\*+([^*]+)\*+", r"\1", clean_text)
+    clean_text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", clean_text)
+    clean_text = re.sub(r"\{[^}]*\}", "", clean_text)
+    clean_text = re.sub(r"\[\^[^\]]*\](?:\([^)]*\))?", "", clean_text)
+    clean_text = re.sub(r"\^[^\]]*\]", "", clean_text)
+    clean_text = re.sub(r"#[a-zA-Z0-9_.-]+", "", clean_text)
+    clean_text = re.sub(r"\([^)]*\)", "", clean_text)
+    clean_text = re.sub(r'^["""\'\']+|["""\'\']+$', "", clean_text)
+    clean_text = re.sub(r"\s+", " ", clean_text).strip()
+    clean_text = re.sub(r"[。，、；：！？]+$", "", clean_text)
+
+    if for_filename:
+        clean_text = re.sub(r'[<>:"/\\|?*]', "", clean_text)
+        clean_text = re.sub(r"\s+", "_", clean_text.strip())
+        if len(clean_text) > 50:
+            clean_text = clean_text[:50].rstrip("_")
+
+    return clean_text or fallback_title