favlo 0.3.0__py3-none-any.whl

favlo/__init__.py

@@ -0,0 +1,3 @@
+"""Process entry for Favlo. Model math lives in the pipeline file."""
+
+__version__ = "0.3.0"

favlo/__main__.py

@@ -0,0 +1,3 @@
+from favlo.cli import main
+
+raise SystemExit(main())

favlo/chat_client.py

@@ -0,0 +1,117 @@
+"""Agent Framework client for the listener's chat completions.
+
+Every chat caller uses this client. Reasoning from a completion is sent back
+on ``reasoning_content``. A reply whose text already contains the tool-call
+markup is sent as that text.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def reasoning_text(message: Any) -> str:
+    """``reasoning_content`` on a completion message or a stream delta."""
+    if message is None:
+        return ""
+    value = getattr(message, "reasoning_content", None)
+    if isinstance(value, str) and value:
+        return value
+    extra = getattr(message, "model_extra", None)
+    if isinstance(extra, dict):
+        raw = extra.get("reasoning_content")
+        if isinstance(raw, str) and raw:
+            return raw
+    return ""
+
+
+def read_reasoning(message: Any, contents: list[Any]) -> list[Any]:
+    """Keep ``reasoning_content`` as reasoning, beside the reply text."""
+    text = reasoning_text(message)
+    if not text:
+        return contents
+    from agent_framework import Content
+
+    return [Content.from_text_reasoning(text=text), *contents]
+
+
+def prepare_messages(message: object, built: list[dict[str, object]]) -> list[dict[str, object]]:
+    """Put reasoning on ``reasoning_content`` for the chat template.
+
+    The listener reads that field when it renders the next prompt. A reply
+    whose text already contains the tool-call markup is sent as that text.
+    """
+    if getattr(message, "role", None) != "assistant":
+        return built
+    reasoning = "".join(
+        part.text or ""
+        for part in getattr(message, "contents", ())
+        if getattr(part, "type", None) == "text_reasoning"
+        and not getattr(part, "protected_data", None)
+    )
+    if not reasoning:
+        return built
+    kept: list[dict[str, object]] = []
+    placed = False
+    for item in built:
+        if item.get("role") != "assistant":
+            kept.append(item)
+            continue
+        text = _content_text(item.get("content"))
+        if text == reasoning and "tool_calls" not in item:
+            continue
+        copied = dict(item)
+        if not placed:
+            copied["reasoning_content"] = reasoning
+            placed = True
+        if "<tool_call>" in text:
+            copied.pop("tool_calls", None)
+        kept.append(copied)
+    if not placed:
+        kept.append({"role": "assistant", "reasoning_content": reasoning, "content": ""})
+    return kept
+
+
+def history_message(role: str, text: str, reasoning: str = "") -> Any:
+    """One stored turn. Reasoning stays a reasoning part, not reply text."""
+    from agent_framework import Content, Message
+
+    parts: list[Any] = []
+    if reasoning:
+        parts.append(Content.from_text_reasoning(text=reasoning))
+    parts.append(text)
+    return Message(role, parts)
+
+
+def open_chat_client(
+    model: str,
+    base_url: str,
+    async_client: Any | None = None,
+) -> Any:
+    """Chat client that sends reasoning back on the next request."""
+    from agent_framework.openai import OpenAIChatCompletionClient
+
+    kwargs: dict[str, Any] = {
+        "model": model,
+        "api_key": "favlo",
+        "base_url": base_url,
+        "response_parser": read_reasoning,
+        "message_preparer": prepare_messages,
+    }
+    if async_client is not None:
+        kwargs["async_client"] = async_client
+    return OpenAIChatCompletionClient(**kwargs)
+
+
+def _content_text(content: object) -> str:
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    parts: list[str] = []
+    for item in content:
+        if isinstance(item, str):
+            parts.append(item)
+        elif isinstance(item, dict) and item.get("type") == "text":
+            parts.append(str(item.get("text") or ""))
+    return "".join(parts)

favlo/cli.py

@@ -0,0 +1,225 @@
+"""Select one pipeline file and run it.
+
+A model flag is the filename without ``.py``. ``--<pipeline>`` loads
+``<pipeline>.py`` by path, and that file loads the model's package.
+The hyphenated file is not an import.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import os
+import sys
+import threading
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from types import ModuleType
+
+RUNTIMES = ("metal41", "cuda")
+_IMPORTS = threading.Lock()
+
+
+def repo_root() -> Path:
+    override = os.environ.get("FAVLO_ROOT")
+    if override:
+        return Path(override)
+    for parent in Path(__file__).resolve().parents:
+        marker = parent / "src" / "favlo" / "cli.py"
+        if (parent / "pyproject.toml").is_file() and marker.is_file():
+            return parent
+    message = "favlo package is not inside a checkout"
+    raise FileNotFoundError(message)
+
+
+def pipeline_tree(runtime: str, *, custom: bool = False, root: Path | None = None) -> Path:
+    """The directory that holds one runtime's entry files."""
+    if runtime not in RUNTIMES:
+        message = f"unknown runtime: {runtime}"
+        raise ValueError(message)
+    base = "custom-pipelines" if custom else "pipelines"
+    return (root or repo_root()) / base / runtime
+
+
+def pipeline_names(root: Path | None = None) -> tuple[str, ...]:
+    """Entry stems under the four pipeline trees.
+
+    A new runtime is a new file. Discovering it does not edit this module.
+    Two files with the same ``PIPELINE`` stem are an error.
+    """
+    return tuple(sorted(pipeline_entries(root)))
+
+
+def pipeline_entries(root: Path | None = None) -> dict[str, Path]:
+    """Stem to entry file. A duplicate stem raises ``ValueError``."""
+    found: dict[str, Path] = {}
+    for custom in (False, True):
+        for runtime in RUNTIMES:
+            directory = pipeline_tree(runtime, custom=custom, root=root)
+            if not directory.is_dir():
+                continue
+            for path in sorted(directory.glob("*.py")):
+                stem = _pipeline_stem(path)
+                if stem is None:
+                    continue
+                previous = found.get(stem)
+                if previous is not None:
+                    message = f"duplicate pipeline {stem}: {previous} and {path}"
+                    raise ValueError(message)
+                found[stem] = path
+    return found
+
+
+def _pipeline_stem(path: Path) -> str | None:
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError):
+        return None
+    for node in tree.body:
+        if not isinstance(node, ast.Assign) or len(node.targets) != 1:
+            continue
+        target = node.targets[0]
+        if not isinstance(target, ast.Name) or target.id != "PIPELINE":
+            continue
+        if isinstance(node.value, ast.Constant) and node.value.value == path.stem:
+            return path.stem
+    return None
+
+
+def _help(names: Sequence[str]) -> str:
+    lines = ["usage: favlo serve [--non-interactive]"]
+    lines.append("       favlo web")
+    lines.extend(f"       favlo --{name} [args]" for name in names)
+    lines.append("")
+    lines.append("  serve                  listen on this terminal")
+    lines.append("  serve --non-interactive")
+    lines.append("                         start the server daemon and exit")
+    lines.append("  web                    start the API and the Expo app")
+    width = max((len(name) for name in names), default=0)
+    for name in names:
+        lines.append(f"  --{name.ljust(width)}    {name}")
+    return "\n".join(lines) + "\n"
+
+
+def load_pipeline(
+    name: str,
+    root: Path | None = None,
+    *,
+    runtime: str | None = None,
+    custom: bool = False,
+) -> ModuleType:
+    if runtime is None:
+        path = pipeline_entries(root).get(name)
+        if path is None:
+            message = f"pipeline file is missing: {name}"
+            raise FileNotFoundError(message)
+    else:
+        path = pipeline_tree(runtime, custom=custom, root=root) / f"{name}.py"
+        if not path.is_file():
+            message = f"pipeline file is missing: {path}"
+            raise FileNotFoundError(message)
+    with _IMPORTS:
+        spec = importlib.util.spec_from_file_location(f"{name.replace('-', '_')}_pipeline", path)
+        if spec is None or spec.loader is None:
+            message = f"cannot load pipeline file: {path}"
+            raise ImportError(message)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+
+
+def pipeline_roots(root: Path | None = None) -> tuple[Path, ...]:
+    """Pipeline trees that exist in this checkout."""
+    found: list[Path] = []
+    for custom in (False, True):
+        for runtime in RUNTIMES:
+            directory = pipeline_tree(runtime, custom=custom, root=root)
+            if directory.is_dir():
+                found.append(directory.resolve())
+    return tuple(found)
+
+
+def drop_pipeline_modules(root: Path | None = None) -> int:
+    """Drop imported pipeline packages so the next load reads the files again.
+
+    The lock is the same one ``load_pipeline`` holds. A module under ``src/favlo`` stays.
+    """
+    with _IMPORTS:
+        roots = pipeline_roots(root)
+        names = [
+            name
+            for name, module in list(sys.modules.items())
+            if module is not None and _module_under(module, roots)
+        ]
+        for name in names:
+            sys.modules.pop(name, None)
+        return len(names)
+
+
+def _module_under(module: ModuleType, roots: tuple[Path, ...]) -> bool:
+    file = getattr(module, "__file__", None)
+    if isinstance(file, str) and file and _path_under(Path(file), roots):
+        return True
+    paths = getattr(module, "__path__", None)
+    if paths is None:
+        return False
+    return any(_path_under(Path(str(item)), roots) for item in paths)
+
+
+def _path_under(path: Path, roots: tuple[Path, ...]) -> bool:
+    try:
+        resolved = path.resolve()
+    except OSError:
+        return False
+    return any(resolved.is_relative_to(root) for root in roots)
+
+
+def pipeline_main(module: ModuleType) -> Callable[[Sequence[str]], int]:
+    entry = getattr(module, "main", None)
+    if not callable(entry):
+        message = f"{module.__file__} does not define main()"
+        raise TypeError(message)
+    return entry
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    from favlo.logs import install_rolling_stdio
+
+    install_rolling_stdio()
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        names = pipeline_names()
+    except ValueError as exc:
+        sys.stderr.write(f"{exc}\n")
+        return 2
+    if not args:
+        sys.stderr.write(_help(names))
+        return 2
+    if args[0] in {"-h", "--help"}:
+        sys.stdout.write(_help(names))
+        return 0
+    if args[0] == "serve":
+        from favlo.listener import serve_main
+
+        return int(serve_main(args[1:]))
+    if args[0] == "web":
+        from favlo.web_host import main as web_main
+
+        return int(web_main(args[1:]))
+    flag = args[0]
+    if not flag.startswith("--") or flag == "--":
+        sys.stderr.write(_help(names))
+        sys.stderr.write(f"\nunknown argument: {flag}\n")
+        return 2
+    name = flag[2:]
+    if name not in names:
+        known = ", ".join(f"--{item}" for item in names)
+        sys.stderr.write(f"unknown model flag: {flag}\nknown: {known}\n")
+        return 2
+    try:
+        module = load_pipeline(name)
+        entry = pipeline_main(module)
+    except (FileNotFoundError, ImportError, TypeError) as exc:
+        sys.stderr.write(f"{exc}\n")
+        return 2
+    return int(entry(args[1:]))

favlo/config_tools.py

@@ -0,0 +1,234 @@
+"""The configuration tool group. Favlo web enables it on the Favlo agent."""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+GROUP_ID = "favlo-config"
+GROUP_NAME = "Configuration tools"
+
+INSTRUCTIONS = (
+    "When someone asks how to connect a client, which address or model id to use, "
+    "how to download or quantize a supported model, or how to register one, "
+    "call config_read_guide before you answer. "
+    "Use clients for the server address, the model field, and reload. "
+    "Ctrl+C stops a terminal favlo serve. "
+    "Use models for which checkpoints can be downloaded and how registration works. "
+    "When someone wants to set up Qwen3.6-35B-A3B, call config_read_setup with qwen36-35b-a3b "
+    "before you answer. When someone wants to set up Qwen3.8-27B, call config_read_setup with "
+    "qwen38-27b before you answer. When someone wants to set up Z-Image-Turbo, call "
+    "config_read_setup with z-image-turbo before you answer. When someone wants to set up "
+    "Wan 2.2 I2V, call config_read_setup with wan22-i2v before you answer. When someone wants to "
+    "set up ACE-Step, call config_read_setup with ace-step-15-turbo before you answer. For any other "
+    "pipeline "
+    "they want to set up, download, quantize, or delete, call config_read_setup with that pipeline id. "
+    "Answer from that guide. "
+    "When they want you to run a step from it, call config_run_setup with that command. "
+    "config_run_setup only runs inside this install. Do not run a command the guide does not contain. "
+    "When someone asks which models are registered, or which model id to send, "
+    "call config_list_models before you answer. Report only the lines it returns. "
+    "When someone wants MTP on or off for a model, or a different draft depth, "
+    "call config_set_model_mtp. A row that omits MTP stays off. "
+    "When someone asks where your name came from, or who Amanda and Celestia are, "
+    "call config_read_guide with history and tell that story. Do not add events it does not contain. "
+    "Answer from that guide. If the guide does not say it, say you do not know."
+)
+
+
+def tools(base: str, home: Path | None) -> list[object]:
+    """The configuration tools, in the order the group offers them."""
+    return [
+        _guide_tool(),
+        _models_tool(),
+        _mtp_tool(),
+        _suggestions_tool(home),
+        _setup_guide_tool(),
+        _setup_run_tool(base),
+    ]
+
+
+def registered_models(root: Path | None = None) -> str:
+    """The registry listing. An empty registry says so."""
+    from favlo.registry import format_listing
+
+    listing = format_listing(root).strip()
+    if not listing:
+        return "no models are registered"
+    return listing
+
+
+def _guide_tool() -> object:
+    from typing import Annotated
+
+    from agent_framework import tool
+    from pydantic import Field
+
+    from favlo.guides import read_guide as load_guide
+
+    @tool(approval_mode="never_require", name="config_read_guide")
+    def read_guide(
+        name: Annotated[str, Field(description="clients, models, or history.")],
+    ) -> str:
+        """Read one guide.
+
+        clients points a program at this server and covers ``reload``.
+        Ctrl+C stops a terminal ``favlo serve``. models covers
+        download, quantize, and registration. history is where the name Favlo came from.
+        """
+        return load_guide(name)
+
+    return read_guide
+
+
+def _suggestions_tool(home: Path | None) -> object:
+    from typing import Annotated
+
+    from agent_framework import tool
+    from pydantic import Field
+
+    from favlo.machine import set_suggestions
+
+    @tool(approval_mode="never_require", name="config_download_suggestions")
+    def download_suggestions(
+        enabled: Annotated[
+            bool,
+            Field(description="False stores download reminders as off. True stores them as on."),
+        ],
+    ) -> str:
+        """Store whether download reminders are enabled.
+
+        The terminal does not start a reminder on its own. This records the preference.
+        """
+        return set_suggestions(enabled, home)
+
+    return download_suggestions
+
+
+def _setup_guide_tool() -> object:
+    from typing import Annotated
+
+    from agent_framework import tool
+    from pydantic import Field
+
+    from favlo.guides import read_setup as load_setup
+
+    @tool(approval_mode="never_require", name="config_read_setup")
+    def read_setup(
+        pipeline: Annotated[
+            str,
+            Field(description="Pipeline id, such as wan22-i2v."),
+        ],
+    ) -> str:
+        """Read one pipeline's setup guide.
+
+        Call this when someone wants to set up, download, quantize, or delete a model.
+        qwen36-35b-a3b is Qwen3.6-35B-A3B. qwen38-27b is Qwen3.8-27B.
+        z-image-turbo is Z-Image-Turbo. wan22-i2v is Wan 2.2 I2V.
+        ace-step-15-turbo is ACE-Step.
+        The result is that pipeline's setup page.
+        A pipeline with no setup page names the ones that have one.
+        """
+        return load_setup(pipeline)
+
+    return read_setup
+
+
+def _setup_run_tool(base: str) -> object:
+    from typing import Annotated
+
+    from agent_framework import tool
+    from pydantic import Field
+
+    from favlo.setup_run import accepted_argv, frees_model, run_setup_command
+
+    @tool(approval_mode="never_require", name="config_run_setup")
+    def run_setup(
+        command: Annotated[
+            str,
+            Field(description="One command copied from the setup guide."),
+        ],
+    ) -> str:
+        """Run one setup-guide command in this install.
+
+        The working directory is the folder where Favlo is installed. A path cannot
+        leave that folder. This is not a shell: pipes, cd, and other programs are refused.
+        """
+        try:
+            argv = accepted_argv(command, _install())
+        except ValueError as exc:
+            return str(exc)
+        if frees_model(argv):
+            closed = _close_resident(base)
+            if closed is not None:
+                return closed
+        try:
+            return run_setup_command(command)
+        except ValueError as exc:
+            return str(exc)
+
+    return run_setup
+
+
+def _install() -> Path:
+    from favlo.cli import repo_root
+
+    return repo_root()
+
+
+def _close_resident(base: str) -> str | None:
+    request = urllib.request.Request(base + "/pipelines/close", data=b"", method="POST")
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            response.read()
+    except (OSError, urllib.error.URLError) as exc:
+        return f"could not close the open model: {exc}"
+    return None
+
+
+def _models_tool() -> object:
+    from agent_framework import tool
+
+    @tool(approval_mode="never_require", name="config_list_models")
+    def list_models() -> str:
+        """List the registered models.
+
+        Each line is one record: folder, pipeline, alias, key/value mode,
+        and whether MTP is on with its draft depth.
+        An unregistered complete record is named too. This is the live registry,
+        not the download guide.
+        """
+        return registered_models()
+
+    return list_models
+
+
+def _mtp_tool() -> object:
+    from typing import Annotated
+
+    from agent_framework import tool
+    from pydantic import Field
+
+    from favlo.registry import set_model_mtp as store_model_mtp
+
+    @tool(approval_mode="never_require", name="config_set_model_mtp")
+    def set_model_mtp(
+        model: Annotated[str, Field(description="Folder, alias, or pipeline id.")],
+        enabled: Annotated[bool, Field(description="True drafts. False stays on one token.")],
+        depth: Annotated[
+            int | None,
+            Field(description="Draft length. Omit it to keep the depth already stored."),
+        ] = None,
+    ) -> str:
+        """Store MTP and its draft depth on one registry row.
+
+        The next completion for that model uses the row when the request omits
+        ``mtp`` or ``mtp_depth``. A request field still wins.
+        """
+        try:
+            return store_model_mtp(model, enabled=enabled, depth=depth)
+        except (LookupError, ValueError) as exc:
+            return str(exc)
+
+    return set_model_mtp