ffai-cli 0.2.0__py3-none-any.whl

ffai/__init__.py

@@ -0,0 +1,5 @@
+"""ffai: a natural-language interface for media and document conversion."""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

ffai/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m ffai`` to launch the interactive REPL."""
+
+from ffai.cli import main
+
+raise SystemExit(main())

ffai/cli.py

@@ -0,0 +1,97 @@
+"""Command-line entry point for ffai."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from ffai import __version__
+from ffai.config import Settings
+from ffai.errors import ConfigError
+from ffai.i18n import Translator, resolve_language
+from ffai.repl import FFaiRepl
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ffai",
+        description=(
+            "Natural-language, stateful FFmpeg (media) and Pandoc (document) "
+            "conversion assistant."
+        ),
+    )
+    parser.add_argument(
+        "--lang",
+        choices=("en", "zh"),
+        default=None,
+        help="UI language (default: FFAI_LANG or system locale)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    translator = Translator(resolve_language(args.lang))
+    console = Console(highlight=False)
+
+    try:
+        settings = Settings.load()
+    except ConfigError as exc:
+        console.print(
+            Panel(
+                Text(str(exc), style="red"),
+                title=translator("cli.config_error_title"),
+                border_style="red",
+            )
+        )
+        return 2
+
+    # Settings.load populates os.environ from .env, so re-resolve here to let
+    # FFAI_LANG live in either the process environment or the project .env.
+    translator = Translator(resolve_language(args.lang))
+    _configure_readline()
+    try:
+        FFaiRepl(settings, console=console, translator=translator).run()
+    except ConfigError as exc:
+        console.print(
+            Panel(
+                Text(str(exc), style="red"),
+                title=translator("cli.config_required_title"),
+                border_style="red",
+            )
+        )
+        return 2
+    except KeyboardInterrupt:
+        console.print()
+        console.print(Text(translator("cli.interrupted"), style="dim"))
+        return 130
+    except BrokenPipeError:
+        return 0
+    return 0
+
+
+def _configure_readline() -> None:
+    try:
+        import readline
+    except ImportError:
+        # readline is unavailable on some platforms; Console.input still works,
+        # only arrow-key input history is lost.
+        return
+    try:
+        readline.set_history_length(1_000)
+    except (AttributeError, OSError):
+        # A stripped readline implementation may not expose history controls.
+        return
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ffai/command_builder.py

@@ -0,0 +1,287 @@
+"""Build FFmpeg argument lists from validated task state.
+
+No shell string is ever constructed. Every path and value is passed as its own
+argv entry, and model-provided extra options are restricted to a small set of
+common output options with known arity.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from ffai.errors import CommandBuildError
+from ffai.models import FFmpegTask
+
+FFMPEG_BINARY = "ffmpeg"
+
+# Extra options are output options with a fixed number of values. Unknown
+# options, stream mapping, filters, codec selection, and options that write
+# auxiliary files are deliberately not accepted here; those concerns are
+# represented by structured task fields and validated separately.
+_EXTRA_OPTION_ARITY: dict[str, int] = {
+    "-aspect": 1,
+    "-bf": 1,
+    "-bufsize": 1,
+    "-color_primaries": 1,
+    "-color_range": 1,
+    "-color_trc": 1,
+    "-colorspace": 1,
+    "-disposition": 1,
+    "-f": 1,
+    "-flags": 1,
+    "-frames": 1,
+    "-g": 1,
+    "-keyint_min": 1,
+    "-level": 1,
+    "-map_chapters": 1,
+    "-map_metadata": 1,
+    "-max_muxing_queue_size": 1,
+    "-maxrate": 1,
+    "-metadata": 1,
+    "-minrate": 1,
+    "-movflags": 1,
+    "-pix_fmt": 1,
+    "-profile": 1,
+    "-qmax": 1,
+    "-qmin": 1,
+    "-qscale": 1,
+    "-r": 1,
+    "-rc": 1,
+    "-rc-lookahead": 1,
+    "-refs": 1,
+    "-s": 1,
+    "-sc_threshold": 1,
+    "-shortest": 0,
+    "-ss": 1,
+    "-svtav1-params": 1,
+    "-t": 1,
+    "-tag": 1,
+    "-thread_type": 1,
+    "-threads": 1,
+    "-to": 1,
+    "-tune": 1,
+    "-x264-params": 1,
+    "-x265-params": 1,
+}
+
+_OPTION_TOKEN = re.compile(r"^-[A-Za-z0-9][A-Za-z0-9_.:+-]*$")
+# Specifier suffixes such as ":v", ":a:0", or ":s:v:0" are permitted for
+# these options.
+_SPECIFIER_OPTIONS = {
+    "-aspect",
+    "-disposition",
+    "-frames",
+    "-level",
+    "-map_chapters",
+    "-map_metadata",
+    "-metadata",
+    "-profile",
+    "-tag",
+}
+
+
+def build_command(task: FFmpegTask, *, overwrite: bool = True) -> list[str]:
+    """Validate *task* and return an FFmpeg argv list.
+
+    The current task must have at least one existing input and a usable output
+    path. Paths are normalized before use so an input named ``-foo.mp4`` cannot
+    be mistaken for an FFmpeg option.
+    """
+
+    inputs = [_validate_input(raw) for raw in task.inputs]
+    if not inputs:
+        raise CommandBuildError("No input files. Use 'add <file>' first.")
+    output = _validate_output(task.output)
+    _validate_no_overwrite(inputs, output)
+    _validate_encoding_combination(task)
+    _validate_filter_graph(task, input_count=len(inputs))
+    extra_options = _validate_extra_options(task.extra_options)
+
+    args = [FFMPEG_BINARY, "-hide_banner", "-nostdin"]
+    if overwrite:
+        args.append("-y")
+    for media_input in inputs:
+        args.extend(["-i", media_input])
+
+    if task.filter_complex:
+        args.extend(["-filter_complex", task.filter_complex])
+    for stream_map in task.maps:
+        args.extend(["-map", stream_map])
+    if task.video_filters:
+        args.extend(["-vf", ",".join(task.video_filters)])
+    if task.audio_filters:
+        args.extend(["-af", ",".join(task.audio_filters)])
+    if task.video_codec:
+        args.extend(["-c:v", task.video_codec])
+    if task.audio_codec:
+        args.extend(["-c:a", task.audio_codec])
+    if task.crf is not None:
+        args.extend(["-crf", str(task.crf)])
+    if task.preset:
+        args.extend(["-preset", task.preset])
+    if task.video_bitrate:
+        args.extend(["-b:v", task.video_bitrate])
+    if task.audio_bitrate:
+        args.extend(["-b:a", task.audio_bitrate])
+    args.extend(extra_options)
+    args.append(output)
+    return args
+
+
+def describe_allowed_extra_options() -> str:
+    """Return a stable, human-readable allowlist for prompts and docs."""
+
+    return ", ".join(sorted(_EXTRA_OPTION_ARITY))
+
+
+def _validate_input(raw_path: str) -> str:
+    try:
+        path = Path(raw_path).expanduser().resolve(strict=True)
+    except (OSError, RuntimeError) as exc:
+        raise CommandBuildError(f"Input file does not exist: {raw_path}") from exc
+    if not path.is_file():
+        raise CommandBuildError(f"Input is not a regular file: {path}")
+    if not os.access(path, os.R_OK):
+        raise CommandBuildError(f"Input file is not readable: {path}")
+    return str(path)
+
+
+def _validate_output(raw_output: str | None) -> str:
+    if raw_output is None or not raw_output.strip():
+        raise CommandBuildError("No output file. Use 'setoutput <file>' first.")
+
+    path = Path(raw_output).expanduser()
+    if not path.is_absolute():
+        path = Path.cwd() / path
+    if path.name in {"", ".", ".."}:
+        raise CommandBuildError("Output must be a filename, not a directory")
+    try:
+        parent = path.parent.resolve(strict=True)
+    except (OSError, RuntimeError) as exc:
+        raise CommandBuildError(f"Output directory does not exist: {path.parent}") from exc
+    if not parent.is_dir():
+        raise CommandBuildError(f"Output parent is not a directory: {parent}")
+    if not os.access(parent, os.W_OK | os.X_OK):
+        raise CommandBuildError(f"Output directory is not writable: {parent}")
+
+    target = parent / path.name
+    if target.exists() and target.is_dir():
+        raise CommandBuildError(f"Output path is a directory: {target}")
+    return str(target)
+
+
+def _validate_no_overwrite(inputs: list[str], output: str) -> None:
+    for media_input in inputs:
+        if _same_file(media_input, output):
+            raise CommandBuildError(
+                f"Output would overwrite an input file: {output}. Choose a different output."
+            )
+
+
+def _validate_encoding_combination(task: FFmpegTask) -> None:
+    if task.video_codec == "copy":
+        conflicts = []
+        if task.video_filters:
+            conflicts.append("video filters")
+        if task.filter_complex:
+            conflicts.append("filter_complex")
+        if task.crf is not None:
+            conflicts.append("CRF")
+        if task.preset:
+            conflicts.append("preset")
+        if task.video_bitrate:
+            conflicts.append("video bitrate")
+        if conflicts:
+            raise CommandBuildError(
+                "Video stream copy cannot be combined with "
+                + ", ".join(conflicts)
+                + ". Clear those fields or use a real video encoder."
+            )
+
+    if task.audio_codec == "copy":
+        conflicts = []
+        if task.audio_filters:
+            conflicts.append("audio filters")
+        if task.audio_bitrate:
+            conflicts.append("audio bitrate")
+        if conflicts:
+            raise CommandBuildError(
+                "Audio stream copy cannot be combined with "
+                + ", ".join(conflicts)
+                + ". Clear those fields or use a real audio encoder."
+            )
+
+
+def _validate_filter_graph(task: FFmpegTask, *, input_count: int) -> None:
+    if task.filter_complex and (task.video_filters or task.audio_filters):
+        raise CommandBuildError(
+            "filter_complex cannot be combined with simple video filters or "
+            "audio filters. Put the whole graph in filter_complex, or clear it."
+        )
+    if task.filter_complex and not task.maps:
+        raise CommandBuildError(
+            "filter_complex requires at least one -map entry (for example '[v]' and '[a]')."
+        )
+    if task.maps:
+        for stream_map in task.maps:
+            if stream_map.startswith("[") and not task.filter_complex:
+                raise CommandBuildError(
+                    f"Map label {stream_map} refers to filter_complex output, "
+                    "but filter_complex is empty."
+                )
+    if input_count > 1 and not task.maps and not task.filter_complex:
+        raise CommandBuildError(
+            "Multiple inputs need explicit maps or a filter_complex so FFmpeg does not "
+            "silently choose streams. Add maps such as '0:v:0' and '1:a:0'."
+        )
+
+
+def _validate_extra_options(options: list[str]) -> list[str]:
+    """Expand only allowlisted options with their exact number of values."""
+
+    validated: list[str] = []
+    index = 0
+    while index < len(options):
+        option = options[index]
+        if not _OPTION_TOKEN.match(option):
+            raise CommandBuildError(
+                f"Invalid extra option token {option!r}. Each argv token must be a "
+                "supported '-option' followed by its values."
+            )
+        base = option.split(":", 1)[0]
+        if base not in _EXTRA_OPTION_ARITY:
+            raise CommandBuildError(
+                f"Unsupported extra option {option!r}. Use structured task fields for "
+                "codecs, filters, and stream mapping."
+            )
+        if option != base and base not in _SPECIFIER_OPTIONS:
+            raise CommandBuildError(f"Stream specifier is not allowed for extra option {option!r}")
+
+        arity = _EXTRA_OPTION_ARITY[base]
+        values = options[index + 1 : index + 1 + arity]
+        if len(values) != arity:
+            raise CommandBuildError(f"Extra option {option!r} requires {arity} value(s)")
+        for value in values:
+            if not value or value.startswith("-"):
+                raise CommandBuildError(
+                    f"Invalid value {value!r} for extra option {option!r}; values must not "
+                    "start with '-'"
+                )
+            if "\x00" in value or "\n" in value or "\r" in value:
+                raise CommandBuildError(f"Invalid control character in value for {option!r}")
+
+        validated.extend(options[index : index + 1 + arity])
+        index += 1 + arity
+
+    return validated
+
+
+def _same_file(left: str | Path, right: str | Path) -> bool:
+    try:
+        return os.path.samefile(left, right)
+    except OSError:
+        # The output may not exist yet; normalized path equality still catches
+        # the common overwrite case.
+        return Path(left) == Path(right)

ffai/config.py

@@ -0,0 +1,251 @@
+"""Environment-backed configuration for the OpenAI-compatible client."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from dotenv import find_dotenv, load_dotenv
+from pydantic import BaseModel, ConfigDict, SecretStr, field_validator
+
+from ffai.errors import ConfigError
+
+API_KEY_ENV = "OPENAI_API_KEY"
+BASE_URL_ENV = "OPENAI_BASE_URL"
+MODEL_ENV = "OPENAI_MODEL"
+
+_ENV_ASSIGNMENT = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=")
+
+# Values shipped in .env.example are placeholders, not configuration.
+_PLACEHOLDER_API_KEYS = {
+    "sk-your-key-here",
+    "sk-your-deepseek-key",
+    "your-api-key",
+    "your-key-here",
+}
+
+
+class LLMConfig(BaseModel):
+    """Validated settings required to make an LLM request."""
+
+    model_config = ConfigDict(frozen=True)
+
+    api_key: SecretStr
+    model: str
+    base_url: str | None = None
+
+
+class Settings(BaseModel):
+    """Process configuration.
+
+    A complete LLM configuration is required before the interactive REPL
+    starts. ``Settings.load`` remains lenient so startup can distinguish a
+    missing configuration from invalid values and launch the setup wizard.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    api_key: SecretStr | None = None
+    base_url: str | None = None
+    model: str | None = None
+
+    @field_validator("api_key", mode="before")
+    @classmethod
+    def _clean_api_key(cls, value: object) -> object:
+        if isinstance(value, str):
+            _reject_env_control_characters(value, API_KEY_ENV)
+            value = value.strip()
+            if value.lower() in _PLACEHOLDER_API_KEYS or value.lower().startswith("sk-your-"):
+                return None
+            return SecretStr(value) if value else None
+        return value
+
+    @field_validator("base_url", mode="before")
+    @classmethod
+    def _clean_base_url(cls, value: object) -> object:
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            raise ValueError("OPENAI_BASE_URL must be a string")
+        _reject_env_control_characters(value, BASE_URL_ENV)
+        value = value.strip().rstrip("/")
+        if not value:
+            return None
+        parsed = urlsplit(value)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("OPENAI_BASE_URL must be an absolute http(s) URL")
+        if parsed.username or parsed.password:
+            raise ValueError("OPENAI_BASE_URL must not contain credentials")
+        return value
+
+    @field_validator("model", mode="before")
+    @classmethod
+    def _clean_model(cls, value: object) -> object:
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            raise ValueError("OPENAI_MODEL must be a string")
+        _reject_env_control_characters(value, MODEL_ENV)
+        value = value.strip()
+        return value or None
+
+    @classmethod
+    def load(
+        cls,
+        env: Mapping[str, str] | None = None,
+        *,
+        load_env_file: bool = True,
+    ) -> Settings:
+        """Load settings from ``.env`` and the process environment.
+
+        An explicit *env* mapping bypasses dotenv loading, which keeps tests
+        independent of the developer's environment.
+        """
+
+        if env is None:
+            if load_env_file:
+                dotenv_path = find_dotenv(usecwd=True)
+                if dotenv_path:
+                    load_dotenv(dotenv_path=Path(dotenv_path), override=False)
+            source: Mapping[str, str] = os.environ
+        else:
+            source = env
+
+        try:
+            return cls(
+                api_key=source.get(API_KEY_ENV),
+                base_url=source.get(BASE_URL_ENV),
+                model=source.get(MODEL_ENV),
+            )
+        except ValueError as exc:
+            raise ConfigError(f"Invalid API configuration: {exc}") from exc
+
+    @property
+    def llm_configured(self) -> bool:
+        return self.api_key is not None and self.model is not None
+
+    def require_llm(self) -> LLMConfig:
+        missing = []
+        if self.api_key is None:
+            missing.append(API_KEY_ENV)
+        if self.model is None:
+            missing.append(MODEL_ENV)
+        if missing:
+            raise ConfigError(
+                "API configuration is required. Missing "
+                + " and ".join(missing)
+                + ". Run the setup wizard or set the environment variables."
+            )
+        return LLMConfig(
+            api_key=self.api_key,
+            model=self.model,
+            base_url=self.base_url,
+        )
+
+
+def env_file_path() -> Path:
+    """Return the configuration file written by the REPL setup wizard."""
+
+    return Path.cwd() / ".env"
+
+
+def save_llm_settings(settings: Settings, *, env_path: Path | None = None) -> Path:
+    """Atomically persist LLM settings to an owner-only ``.env`` file.
+
+    Existing unrelated entries and comments are preserved. A missing base URL
+    removes any previously configured ``OPENAI_BASE_URL`` entry.
+    """
+
+    llm = settings.require_llm()
+    target = (env_path or env_file_path()).expanduser()
+    if not target.is_absolute():
+        target = Path.cwd() / target
+    try:
+        parent = target.parent.resolve(strict=True)
+    except OSError as exc:
+        raise ConfigError(f"Configuration directory does not exist: {target.parent}") from exc
+    target = parent / target.name
+
+    updates = {
+        API_KEY_ENV: llm.api_key.get_secret_value(),
+        MODEL_ENV: llm.model,
+    }
+    removals: set[str] = set()
+    if llm.base_url:
+        updates[BASE_URL_ENV] = llm.base_url
+    else:
+        removals.add(BASE_URL_ENV)
+
+    try:
+        existing = target.read_text(encoding="utf-8") if target.exists() else ""
+    except (OSError, UnicodeDecodeError) as exc:
+        raise ConfigError(f"Could not read configuration file {target}: {exc}") from exc
+
+    content = _rewrite_env(existing, updates, removals)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=parent,
+            prefix=".env.",
+            delete=False,
+        ) as temp_file:
+            temp_file.write(content)
+            temp_file.flush()
+            os.fsync(temp_file.fileno())
+            temp_path = Path(temp_file.name)
+        os.chmod(temp_path, 0o600)
+        os.replace(temp_path, target)
+        temp_path = None
+        os.chmod(target, 0o600)
+    except OSError as exc:
+        raise ConfigError(f"Could not write configuration file {target}: {exc}") from exc
+    finally:
+        if temp_path is not None:
+            # The write error is already being reported; a leftover temp file
+            # is owner-only and cannot expose the credentials.
+            with contextlib.suppress(OSError):
+                temp_path.unlink(missing_ok=True)
+
+    return target
+
+
+def _reject_env_control_characters(value: str, variable: str) -> None:
+    if any(char in value for char in ("\x00", "\n", "\r")):
+        raise ValueError(f"{variable} must not contain control characters")
+
+
+def _rewrite_env(existing: str, updates: dict[str, str], removals: set[str]) -> str:
+    lines = existing.splitlines(keepends=True)
+    output: list[str] = []
+    written: set[str] = set()
+
+    for line in lines:
+        match = _ENV_ASSIGNMENT.match(line)
+        key = match.group(1) if match else None
+        if key in removals:
+            continue
+        if key in updates:
+            if key not in written:
+                output.append(f"{key}={_quote_env_value(updates[key])}\n")
+                written.add(key)
+            continue
+        output.append(line)
+
+    if output and not output[-1].endswith(("\n", "\r")):
+        output[-1] += "\n"
+    for key, value in updates.items():
+        if key not in written:
+            output.append(f"{key}={_quote_env_value(value)}\n")
+    return "".join(output)
+
+
+def _quote_env_value(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace("'", "\\'")
+    return f"'{escaped}'"

ffai/errors.py

@@ -0,0 +1,31 @@
+"""Typed errors shared across ffai modules."""
+
+from __future__ import annotations
+
+
+class FFAIError(Exception):
+    """Base class for errors that can be presented to the user."""
+
+
+class ConfigError(FFAIError):
+    """API or runtime configuration is invalid."""
+
+
+class StateError(FFAIError):
+    """A task-state transition was rejected."""
+
+
+class ParseError(FFAIError):
+    """Command-line input could not be parsed."""
+
+
+class CommandBuildError(FFAIError):
+    """The current task cannot be converted into a safe tool command."""
+
+
+class ExecutionError(FFAIError):
+    """The external conversion tool could not run or produce the requested output."""
+
+
+class LLMError(FFAIError):
+    """The language-model request failed or returned unusable output."""