ffai-cli 0.2.0__py3-none-any.whl

ffai/state.py

@@ -0,0 +1,291 @@
+"""Stateful, locally owned conversion task session.
+
+A session holds one task per conversion tool plus the currently selected tool.
+Inputs and outputs are shared user-facing files for the active tool, and are
+still changed exclusively through :meth:`SessionState.add_inputs` and
+:meth:`SessionState.set_output`, which validate paths locally. LLM patches can
+only update the technical fields of the tool they target.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from ffai.errors import StateError
+from ffai.models import (
+    FFmpegPatch,
+    FFmpegTask,
+    PandocPatch,
+    PandocTask,
+    ToolName,
+    ToolPatch,
+)
+from ffai.tools import TOOL_SPECS, ToolSpec, detect_tool, get_tool
+
+_LIST_PATCH_FIELDS = {
+    "video_filters",
+    "audio_filters",
+    "extra_options",
+    "maps",
+    "metadata",
+    "bibliography",
+    "resource_path",
+}
+_BOOL_PATCH_FIELDS = {
+    "standalone",
+    "toc",
+    "number_sections",
+    "embed_resources",
+    "citeproc",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class AddInputsResult:
+    added: tuple[str, ...]
+    duplicates: tuple[str, ...]
+    tool: ToolName
+    switched_tool: ToolName | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TaskChange:
+    field: str
+    before: Any
+    after: Any
+
+
+@dataclass(slots=True)
+class SessionState:
+    """Owns the tasks and all filesystem-facing mutations.
+
+    Each tool keeps its own task, so switching tools preserves the other
+    tool's work. When the active task is still empty, adding files whose
+    extensions clearly belong to the other tool selects that tool
+    automatically.
+    """
+
+    tool: ToolName = "ffmpeg"
+    ffmpeg_task: FFmpegTask = field(default_factory=FFmpegTask)
+    pandoc_task: PandocTask = field(default_factory=PandocTask)
+    revision: int = 0
+
+    @property
+    def task(self) -> FFmpegTask | PandocTask:
+        return self._task_for(self.tool)
+
+    @property
+    def spec(self) -> ToolSpec:
+        return get_tool(self.tool)
+
+    def _task_for(self, tool: ToolName) -> FFmpegTask | PandocTask:
+        return self.ffmpeg_task if tool == "ffmpeg" else self.pandoc_task
+
+    def _store_task(self, tool: ToolName, task: FFmpegTask | PandocTask) -> None:
+        if tool == "ffmpeg":
+            self.ffmpeg_task = task  # type: ignore[assignment]
+        else:
+            self.pandoc_task = task  # type: ignore[assignment]
+
+    def select_tool(self, tool: ToolName) -> bool:
+        """Switch the active tool. Returns whether the selection changed."""
+
+        if tool not in TOOL_SPECS:
+            raise StateError(f"Unknown conversion tool: {tool}")
+        if tool == self.tool:
+            return False
+        self.tool = tool
+        self.revision += 1
+        return True
+
+    def add_inputs(self, raw_paths: list[str] | tuple[str, ...]) -> AddInputsResult:
+        if not raw_paths:
+            raise StateError("add requires at least one input file")
+
+        candidates: list[Path] = []
+        seen: list[Path] = []
+        for raw in raw_paths:
+            if not raw.strip():
+                raise StateError("Input filenames must not be empty")
+            candidate = self._resolve_existing_file(raw)
+            if any(_same_file(candidate, existing) for existing in seen):
+                continue
+            seen.append(candidate)
+            candidates.append(candidate)
+
+        # Resolving every path above keeps the operation atomic: a missing
+        # file never leaves the session partially updated.
+        pending = [str(path) for path in candidates]
+        switched: ToolName | None = None
+        if not self.task.inputs and self.task.output is None:
+            detected = detect_tool(pending)
+            if detected is not None and detected != self.tool:
+                switched = detected
+
+        activation = switched or self.tool
+        task = self._task_for(activation)
+
+        added: list[str] = []
+        duplicates: list[str] = []
+        for candidate in candidates:
+            candidate_str = str(candidate)
+            if candidate_str in task.inputs or any(
+                _same_file(candidate, existing) for existing in task.inputs
+            ):
+                duplicates.append(candidate_str)
+                continue
+            if task.output is not None and _same_file(candidate, task.output):
+                raise StateError(
+                    f"Input file is also the current output: {candidate_str}. "
+                    "Choose a different output with setoutput."
+                )
+            added.append(candidate_str)
+
+        if not added and switched is None:
+            return AddInputsResult(
+                added=(),
+                duplicates=tuple(duplicates),
+                tool=self.tool,
+            )
+
+        self.tool = activation
+        task.inputs.extend(added)
+        self.revision += 1
+        return AddInputsResult(
+            added=tuple(added),
+            duplicates=tuple(duplicates),
+            tool=self.tool,
+            switched_tool=switched,
+        )
+
+    def set_output(self, raw_path: str) -> str:
+        if not raw_path.strip():
+            raise StateError("Output filename must not be empty")
+
+        path = Path(raw_path).expanduser()
+        if not path.is_absolute():
+            path = Path.cwd() / path
+        if path.name in {"", ".", ".."}:
+            raise StateError("Output must be a filename, not a directory")
+
+        try:
+            parent = path.parent.resolve(strict=True)
+        except OSError as exc:
+            raise StateError(f"Output directory does not exist: {path.parent}") from exc
+        if not parent.is_dir():
+            raise StateError(f"Output parent is not a directory: {parent}")
+        if not os.access(parent, os.W_OK | os.X_OK):
+            raise StateError(f"Output directory is not writable: {parent}")
+
+        target = parent / path.name
+        if target.exists() and target.is_dir():
+            raise StateError(f"Output path is a directory: {target}")
+        for source in self.task.inputs:
+            if _same_file(target, source):
+                raise StateError(
+                    f"Output would overwrite an input file: {target}. Choose a different path."
+                )
+
+        self.task.output = str(target)
+        self.revision += 1
+        return str(target)
+
+    def apply_patch(self, patch: ToolPatch) -> list[TaskChange]:
+        """Apply only explicitly supplied patch fields and return a diff.
+
+        A patch with no tool is a no-op. Selecting a different tool is itself
+        a visible change even when the tool payload is empty.
+        """
+
+        tool = patch.tool
+        fields = patch.fields
+        if tool is None or fields is None:
+            return []
+
+        target = self._task_for(tool)
+        updates = _patch_updates(fields)
+        if not updates and tool == self.tool:
+            return []
+
+        candidate_data = target.model_dump()
+        candidate_data.update(updates)
+        try:
+            candidate = type(target).model_validate(candidate_data)
+        except ValidationError as exc:
+            raise StateError(f"The proposed task is invalid: {exc}") from exc
+
+        if isinstance(candidate, FFmpegTask) and candidate.filter_complex and (
+            candidate.video_filters or candidate.audio_filters
+        ):
+            raise StateError(
+                "filter_complex cannot be combined with simple video_filters or "
+                "audio_filters. Clear the simple filters or remove filter_complex."
+            )
+
+        before_data = target.model_dump()
+        candidate_snapshot = candidate.model_dump()
+        changes: list[TaskChange] = []
+        if tool != self.tool:
+            changes.append(TaskChange(field="tool", before=self.tool, after=tool))
+        changes.extend(
+            TaskChange(field=name, before=before_data[name], after=candidate_snapshot[name])
+            for name in updates
+            if before_data[name] != candidate_snapshot[name]
+        )
+        if not changes:
+            return []
+
+        self._store_task(tool, candidate)
+        self.tool = tool
+        self.revision += 1
+        return changes
+
+    def reset(self) -> None:
+        self._store_task(self.tool, get_tool(self.tool).task_type())
+        self.revision += 1
+
+    def llm_context(self) -> dict[str, Any]:
+        context = self.task.model_dump()
+        context["tool"] = self.tool
+        context["revision"] = self.revision
+        return context
+
+    @staticmethod
+    def _resolve_existing_file(raw_path: str) -> Path:
+        try:
+            path = Path(raw_path).expanduser().resolve(strict=True)
+        except OSError as exc:
+            raise StateError(f"Input file does not exist: {raw_path}") from exc
+        if not path.is_file():
+            raise StateError(f"Input is not a regular file: {path}")
+        if not os.access(path, os.R_OK):
+            raise StateError(f"Input file is not readable: {path}")
+        return path
+
+
+def _patch_updates(fields: FFmpegPatch | PandocPatch) -> dict[str, Any]:
+    updates: dict[str, Any] = {}
+    for field_name in fields.model_fields_set:
+        value = getattr(fields, field_name)
+        if field_name in _LIST_PATCH_FIELDS and value is None:
+            value = []
+        if field_name in _BOOL_PATCH_FIELDS and value is None:
+            value = False
+        if field_name == "description" and value is None:
+            value = ""
+        updates[field_name] = value
+    return updates
+
+
+def _same_file(left: str | Path, right: str | Path) -> bool:
+    try:
+        return os.path.samefile(left, right)
+    except OSError:
+        # At least one path does not exist yet; lexical comparison is the only
+        # available check and is sufficient for normalized SessionState paths.
+        return Path(left) == Path(right)

ffai/tools.py

@@ -0,0 +1,177 @@
+"""Registry of external conversion tools and extension-based routing.
+
+Each supported tool exposes one task model, one patch model, and one argv
+builder. The registry is the single place that maps a tool name to its
+capabilities so the REPL, the prompt, and the session state stay tool-agnostic.
+"""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ffai import command_builder, pandoc_builder
+from ffai.models import (
+    FFMPEG_DISPLAY_FIELDS,
+    PANDOC_DISPLAY_FIELDS,
+    FFmpegPatch,
+    FFmpegTask,
+    PandocPatch,
+    PandocTask,
+    TaskBase,
+    ToolName,
+)
+
+# Media container/codec extensions routed to FFmpeg.
+MEDIA_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".3g2",
+        ".3gp",
+        ".aac",
+        ".aif",
+        ".aiff",
+        ".alac",
+        ".ape",
+        ".avi",
+        ".avif",
+        ".bmp",
+        ".flac",
+        ".flv",
+        ".gif",
+        ".jpeg",
+        ".jpg",
+        ".m2ts",
+        ".m4a",
+        ".m4v",
+        ".mkv",
+        ".mov",
+        ".mp3",
+        ".mp4",
+        ".mpeg",
+        ".mpg",
+        ".mts",
+        ".oga",
+        ".ogg",
+        ".ogv",
+        ".opus",
+        ".png",
+        ".tif",
+        ".tiff",
+        ".ts",
+        ".vob",
+        ".wav",
+        ".webm",
+        ".webp",
+        ".wma",
+        ".wmv",
+    }
+)
+
+# Document extensions routed to Pandoc.
+DOCUMENT_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".adoc",
+        ".asciidoc",
+        ".docx",
+        ".epub",
+        ".htm",
+        ".html",
+        ".ipynb",
+        ".latex",
+        ".markdown",
+        ".md",
+        ".mediawiki",
+        ".odt",
+        ".opml",
+        ".org",
+        ".pptx",
+        ".rst",
+        ".rtf",
+        ".tex",
+        ".text",
+        ".textile",
+        ".txt",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSpec:
+    """Everything the application needs to know about one external tool."""
+
+    name: ToolName
+    binary: str
+    label: str
+    task_type: type[TaskBase]
+    patch_type: type[FFmpegPatch] | type[PandocPatch]
+    display_fields: tuple[str, ...]
+    default_description: str
+    supports_progress: bool
+    builder: Callable[[Any], list[str]]
+
+
+TOOL_SPECS: dict[ToolName, ToolSpec] = {
+    "ffmpeg": ToolSpec(
+        name="ffmpeg",
+        binary="ffmpeg",
+        label="FFmpeg",
+        task_type=FFmpegTask,
+        patch_type=FFmpegPatch,
+        display_fields=FFMPEG_DISPLAY_FIELDS,
+        default_description="New FFmpeg task",
+        supports_progress=True,
+        builder=command_builder.build_command,
+    ),
+    "pandoc": ToolSpec(
+        name="pandoc",
+        binary="pandoc",
+        label="Pandoc",
+        task_type=PandocTask,
+        patch_type=PandocPatch,
+        display_fields=PANDOC_DISPLAY_FIELDS,
+        default_description="New pandoc task",
+        supports_progress=False,
+        builder=pandoc_builder.build_command,
+    ),
+}
+
+TOOL_NAMES: tuple[ToolName, ...] = tuple(TOOL_SPECS)
+
+_EXTENSION_TOOL: dict[str, ToolName] = {
+    **{extension: "ffmpeg" for extension in MEDIA_EXTENSIONS},
+    **{extension: "pandoc" for extension in DOCUMENT_EXTENSIONS},
+}
+
+
+def get_tool(name: ToolName) -> ToolSpec:
+    return TOOL_SPECS[name]
+
+
+def detect_tool(paths: Sequence[str]) -> ToolName | None:
+    """Infer the conversion tool from the extension of *paths*.
+
+    Returns ``None`` when the extensions are unknown or point at different
+    tools, in which case the caller keeps the currently selected tool.
+    """
+
+    detected = {
+        _EXTENSION_TOOL[Path(path).suffix.lower()]
+        for path in paths
+        if Path(path).suffix.lower() in _EXTENSION_TOOL
+    }
+    return detected.pop() if len(detected) == 1 else None
+
+
+def tool_available(name: ToolName) -> bool:
+    return shutil.which(TOOL_SPECS[name].binary) is not None
+
+
+def available_tools() -> tuple[ToolName, ...]:
+    return tuple(name for name in TOOL_NAMES if tool_available(name))
+
+
+def missing_tools() -> tuple[ToolName, ...]:
+    return tuple(name for name in TOOL_NAMES if not tool_available(name))

ffai/utils.py

@@ -0,0 +1,91 @@
+"""Small, side-effect-light helpers shared by the CLI and executor."""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import shutil
+import subprocess
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+_SECRET_ENV_NAME = re.compile(r"KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL", re.IGNORECASE)
+
+
+def format_command(args: Sequence[str]) -> str:
+    """Render argv as a copy-pasteable shell command for display only."""
+
+    return shlex.join(str(arg) for arg in args)
+
+
+def scrubbed_environment(source: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Return an environment without credentials for spawned media tools."""
+
+    environment = os.environ if source is None else source
+    return {name: value for name, value in environment.items() if not _SECRET_ENV_NAME.search(name)}
+
+
+def binary_available(binary: str) -> bool:
+    """Return whether *binary* can be found on PATH."""
+
+    return shutil.which(binary) is not None
+
+
+def probe_duration(path: str, timeout_seconds: float = 10.0) -> float | None:
+    """Best-effort media duration used only to render a progress bar.
+
+    The FFmpeg run itself is still reported from its real exit status. Missing
+    ffprobe, malformed media, and timeouts therefore degrade to an unknown
+    duration rather than masking or changing command execution.
+    """
+
+    if shutil.which("ffprobe") is None:
+        return None
+    command = [
+        "ffprobe",
+        "-v",
+        "error",
+        "-show_entries",
+        "format=duration",
+        "-of",
+        "default=noprint_wrappers=1:nokey=1",
+        str(Path(path)),
+    ]
+    try:
+        completed = subprocess.run(
+            command,
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            check=False,
+            env=scrubbed_environment(),
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if completed.returncode != 0:
+        return None
+    try:
+        duration = float(completed.stdout.strip().splitlines()[0])
+    except (IndexError, ValueError):
+        return None
+    return duration if duration > 0 else None
+
+
+def format_file_size(path: str) -> str | None:
+    try:
+        size = Path(path).stat().st_size
+    except OSError:
+        return None
+    units = ("B", "KiB", "MiB", "GiB", "TiB")
+    value = float(size)
+    for unit in units:
+        if value < 1024 or unit == units[-1]:
+            return f"{value:.0f} {unit}" if unit == "B" else f"{value:.1f} {unit}"
+        value /= 1024
+    return None
+
+
+def ffmpeg_available() -> bool:
+    return binary_available("ffmpeg")