llamactl 0.3.23__py3-none-any.whl → 0.3.25__py3-none-any.whl

llama_deploy/cli/commands/dev.py

@@ -6,14 +6,6 @@ from pathlib import Path
 
 import click
 from click.exceptions import Abort, Exit
-from llama_deploy.appserver.app import prepare_server, start_preflight_in_target_venv
-from llama_deploy.appserver.deployment_config_parser import get_deployment_config
-from llama_deploy.appserver.settings import configure_settings, settings
-from llama_deploy.appserver.workflow_loader import (
-    load_environment_variables,
-    parse_environment_variables,
-    validate_required_env_vars,
-)
 from llama_deploy.cli.commands.aliased_group import AliasedGroup
 from llama_deploy.cli.commands.serve import (
     _maybe_inject_llama_cloud_credentials,
@@ -29,6 +21,8 @@ from rich import print as rprint
 
 from ..app import app
 
+_ClickPath = getattr(click, "Path")
+
 
 @app.group(
     name="dev",
@@ -52,7 +46,7 @@ dev.add_command(serve_command, name="serve")
     "deployment_file",
     required=False,
     default=DEFAULT_DEPLOYMENT_FILE_PATH,
-    type=click.Path(dir_okay=True, resolve_path=True, path_type=Path),
+    type=_ClickPath(dir_okay=True, resolve_path=True, path_type=Path),
 )
 @interactive_option
 @global_options
@@ -85,6 +79,69 @@ def validate_command(deployment_file: Path, interactive: bool) -> None:
     rprint(f"[green]Validated workflows in {config_dir} successfully.[/green]")
 
 
+@dev.command(
+    "export-json-graph",
+    help="Produce a JSON graph representation of registered workflows",
+    hidden=True,  # perhaps expose if we have a built in visualization (mermaid, etc.)
+)
+@click.argument(
+    "deployment_file",
+    required=False,
+    default=DEFAULT_DEPLOYMENT_FILE_PATH,
+    type=_ClickPath(dir_okay=True, resolve_path=True, path_type=Path),
+)
+@click.option(
+    "--output",
+    help=(
+        "File where output JSON graph will be saved. "
+        "Defaults to workflows.json in the current directory."
+    ),
+    required=False,
+    default=None,
+    type=_ClickPath(dir_okay=True, resolve_path=True, path_type=Path),
+)
+@interactive_option
+@global_options
+def export_json_graph_command(
+    deployment_file: Path,
+    output: Path | None,
+    interactive: bool,
+) -> None:
+    """Export the configured workflows to a JSON document that may be used for graph visualization."""
+    if not deployment_file.exists():
+        rprint(f"[red]Deployment file '{deployment_file}' does not exist[/red]")
+        raise click.Abort()
+
+    _ensure_project_layout(
+        deployment_file, command_name="llamactl dev export-json-graph"
+    )
+    _maybe_inject_llama_cloud_credentials(
+        deployment_file, interactive, require_cloud=False
+    )
+
+    prepare_server(
+        deployment_file=deployment_file,
+        install=True,
+        build=False,
+        install_ui_deps=False,
+    )
+
+    wd = Path.cwd()
+    if output is None:
+        output = wd / "workflows.json"
+
+    try:
+        start_export_json_graph_in_target_venv(
+            cwd=wd,
+            deployment_file=deployment_file,
+            output=output,
+        )
+    except subprocess.CalledProcessError as exc:
+        rprint("[red]Workflow JSON graph export failed. See errors above.[/red]")
+        raise Exit(exc.returncode)
+    rprint(f"[green]Exported workflow JSON graph to {output}[/green]")
+
+
 @dev.command(
     "run",
     help=(
@@ -98,7 +155,7 @@ def validate_command(deployment_file: Path, interactive: bool) -> None:
     "deployment_file",
     "--deployment-file",
     default=DEFAULT_DEPLOYMENT_FILE_PATH,
-    type=click.Path(dir_okay=True, resolve_path=True, path_type=Path),
+    type=_ClickPath(dir_okay=True, resolve_path=True, path_type=Path),
     help="The deployment file to use for the command",
 )
 @click.option(
@@ -159,6 +216,15 @@ def _ensure_project_layout(deployment_file: Path, *, command_name: str) -> Path:
 def _prepare_environment(
     deployment_file: Path, interactive: bool, *, require_cloud: bool
 ) -> tuple[DeploymentConfig, Path]:
+    from llama_deploy.appserver.deployment_config_parser import (
+        get_deployment_config,
+    )
+    from llama_deploy.appserver.settings import configure_settings, settings
+    from llama_deploy.appserver.workflow_loader import (
+        load_environment_variables,
+        validate_required_env_vars,
+    )
+
     _maybe_inject_llama_cloud_credentials(
         deployment_file, interactive, require_cloud=require_cloud
     )
@@ -173,4 +239,53 @@ def _prepare_environment(
     return config, config_parent
 
 
-__all__ = ["dev", "validate_command", "run_command"]
+def prepare_server(
+    *, deployment_file: Path, install: bool, build: bool, install_ui_deps: bool
+) -> None:
+    """Thin wrapper so tests can monkeypatch `dev.prepare_server` without importing appserver at import time."""
+    from llama_deploy.appserver.app import prepare_server as _prepare_server
+
+    _prepare_server(
+        deployment_file=deployment_file,
+        install=install,
+        build=build,
+        install_ui_deps=install_ui_deps,
+    )
+
+
+def start_preflight_in_target_venv(*, cwd: Path, deployment_file: Path) -> None:
+    """Thin wrapper so tests can monkeypatch `dev.start_preflight_in_target_venv`."""
+    from llama_deploy.appserver.app import (
+        start_preflight_in_target_venv as _start_preflight_in_target_venv,
+    )
+
+    _start_preflight_in_target_venv(cwd=cwd, deployment_file=deployment_file)
+
+
+def start_export_json_graph_in_target_venv(
+    *, cwd: Path, deployment_file: Path, output: Path
+) -> None:
+    """Thin wrapper so tests can monkeypatch `dev.start_export_json_graph_in_target_venv`."""
+    from llama_deploy.appserver.app import (
+        start_export_json_graph_in_target_venv as _start_export_json_graph_in_target_venv,
+    )
+
+    _start_export_json_graph_in_target_venv(
+        cwd=cwd,
+        deployment_file=deployment_file,
+        output=output,
+    )
+
+
+def parse_environment_variables(
+    config: DeploymentConfig, config_parent: Path
+) -> dict[str, str]:
+    """Wrapper used by tests; imports workflow loader lazily."""
+    from llama_deploy.appserver.workflow_loader import (
+        parse_environment_variables as _parse_environment_variables,
+    )
+
+    return _parse_environment_variables(config, config_parent)
+
+
+__all__ = ["dev", "validate_command", "run_command", "export_json_graph_command"]

llama_deploy/cli/commands/env.py

@@ -1,7 +1,9 @@
+from __future__ import annotations
+
 from importlib import metadata as importlib_metadata
+from typing import TYPE_CHECKING
 
 import click
-import questionary
 from llama_deploy.cli.config.schema import Environment
 from llama_deploy.cli.styles import (
     ACTIVE_INDICATOR,
@@ -16,10 +18,23 @@ from rich.table import Table
 from rich.text import Text
 
 from ..app import console
-from ..config.env_service import service
 from ..options import global_options, interactive_option
 from .auth import auth
 
+if TYPE_CHECKING:
+    from llama_deploy.cli.config.env_service import EnvService
+
+
+def _env_service() -> EnvService:
+    """Return the shared EnvService instance via a local import.
+
+    This keeps CLI startup light while remaining easy to patch in tests via
+    ``llama_deploy.cli.config.env_service.service``.
+    """
+    from ..config.env_service import service
+
+    return service
+
 
 @auth.group(
     name="env",
@@ -35,6 +50,7 @@ def env_group() -> None:
 @global_options
 def list_environments_cmd() -> None:
     try:
+        service = _env_service()
         envs = service.list_environments()
         current_env = service.get_current_environment()
 
@@ -67,11 +83,14 @@ def list_environments_cmd() -> None:
 @global_options
 def add_environment_cmd(api_url: str | None, interactive: bool) -> None:
     try:
+        service = _env_service()
         if not api_url:
             if not interactive:
                 raise click.ClickException("API URL is required when not interactive")
             current_env = service.get_current_environment()
-            entered = questionary.text(
+            from questionary import text
+
+            entered = text(
                 "Enter control plane API URL", default=current_env.api_url
             ).ask()
             if not entered:
@@ -79,6 +98,8 @@ def add_environment_cmd(api_url: str | None, interactive: bool) -> None:
                 return
             api_url = entered.strip()
 
+        if api_url is None:
+            raise click.ClickException("API URL is required")
         api_url = api_url.rstrip("/")
         env = service.probe_environment(api_url)
         service.create_or_update_environment(env)
@@ -97,6 +118,7 @@ def add_environment_cmd(api_url: str | None, interactive: bool) -> None:
 @global_options
 def delete_environment_cmd(api_url: str | None, interactive: bool) -> None:
     try:
+        service = _env_service()
         if not api_url:
             if not interactive:
                 raise click.ClickException("API URL is required when not interactive")
@@ -111,6 +133,8 @@ def delete_environment_cmd(api_url: str | None, interactive: bool) -> None:
                 return
             api_url = result.api_url
 
+        if api_url is None:
+            raise click.ClickException("API URL is required")
         api_url = api_url.rstrip("/")
         deleted = service.delete_environment(api_url)
         if not deleted:
@@ -129,6 +153,7 @@ def delete_environment_cmd(api_url: str | None, interactive: bool) -> None:
 @global_options
 def switch_environment_cmd(api_url: str | None, interactive: bool) -> None:
     try:
+        service = _env_service()
         selected_url = api_url
 
         if not selected_url and interactive:
@@ -193,12 +218,12 @@ def _select_environment(
     current_env: Environment,
     message: str = "Select environment",
 ) -> Environment | None:
-    envs = service.list_environments()
-    current_env = service.get_current_environment()
     if not envs:
         raise click.ClickException(
             "No environments found. This is a bug and shouldn't happen."
         )
+    import questionary
+
     return questionary.select(
         message,
         choices=[

llama_deploy/cli/commands/init.py

@@ -6,10 +6,9 @@ import shutil
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
+from typing import TYPE_CHECKING, cast
 
 import click
-import copier
-import questionary
 from click.exceptions import Exit
 from llama_deploy.cli.app import app
 from llama_deploy.cli.options import (
@@ -19,7 +18,12 @@ from llama_deploy.cli.options import (
 from llama_deploy.cli.styles import HEADER_COLOR_HEX
 from rich import print as rprint
 from rich.text import Text
-from vibe_llama_core.docs import get_agent_rules
+
+if TYPE_CHECKING:
+    pass
+
+
+_ClickPath = getattr(click, "Path")
 
 
 @app.command()
@@ -35,8 +39,12 @@ from vibe_llama_core.docs import get_agent_rules
 @click.option(
     "--dir",
     help="The directory to create the new app in",
-    type=click.Path(
-        file_okay=False, dir_okay=True, writable=True, resolve_path=True, path_type=Path
+    type=_ClickPath(
+        file_okay=False,
+        dir_okay=True,
+        writable=True,
+        resolve_path=True,
+        path_type=Path,
     ),
 )
 @click.option(
@@ -63,6 +71,8 @@ def init(
 def _create(
     template: str | None, dir: Path | None, force: bool, interactive: bool
 ) -> None:
+    import questionary
+
     @dataclass
     class TemplateOption:
         id: str
@@ -271,8 +281,15 @@ def _create(
         else:
             shutil.rmtree(dir, ignore_errors=True)
 
+    # Import copier lazily at call time to keep CLI startup light while still
+    # allowing tests to patch ``copier.run_copy`` directly.
+    import copier
+
     copier.run_copy(
-        resolved_template.source.url, dir, quiet=True, defaults=not interactive
+        resolved_template.source.url,
+        dir,
+        quiet=True,
+        defaults=not interactive,
     )
 
     # Change to the new directory and initialize git repo
@@ -392,15 +409,19 @@ def _create(
     rprint("")
 
 
-def _update():
+def _update() -> None:
     """Update the app to the latest version"""
     try:
+        # Import copier lazily so the init command remains lightweight when
+        # unused, while tests can patch ``copier.run_update`` directly.
+        import copier
+
         copier.run_update(
             overwrite=True,
             skip_answered=True,
             quiet=True,
         )
-    except copier.UserMessageError as e:
+    except Exception as e:  # scoped to copier errors; type opaque here
         rprint(f"{e}")
         raise Exit(1)
 
@@ -448,6 +469,8 @@ async def _download_and_write_agents_md(include_llama_cloud: bool) -> bool:
 
     Returns True if any documentation was fetched, False otherwise.
     """
+    from vibe_llama_core.docs import get_agent_rules
+    from vibe_llama_core.docs.utils import LibraryName
 
     selected_services: list[str] = [
         "LlamaDeploy",
@@ -463,10 +486,10 @@ async def _download_and_write_agents_md(include_llama_cloud: bool) -> bool:
         try:
             await get_agent_rules(
                 agent="OpenAI Codex CLI",
-                service=service,
+                service=cast(LibraryName, service),
                 overwrite_files=False,
                 verbose=False,
-            )  # type: ignore
+            )
         except Exception:
             rprint(f"[yellow]Failed to fetch documentation for {service}, skipping[/]")
         else:

llama_deploy/cli/commands/pkg.py

@@ -41,7 +41,7 @@ def create_container_file(
     output_file: str = "Dockerfile",
     dockerignore_path: str = ".dockerignore",
     overwrite: bool = False,
-):
+) -> None:
     _create_file_for_container(
         deployment_file=deployment_file,
         python_version=python_version,
@@ -93,7 +93,7 @@ def _create_file_for_container(
     exclude: tuple[str, ...] | None = None,
     dockerignore_path: str = ".dockerignore",
     overwrite: bool = False,
-):
+) -> None:
     config_dir = _check_deployment_config(deployment_file=deployment_file)
 
     if not python_version:

llama_deploy/cli/commands/serve.py

@@ -1,22 +1,20 @@
+from __future__ import annotations
+
 import asyncio
 import logging
 import os
 from pathlib import Path
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 import click
-import questionary
 from click.exceptions import Abort, Exit
 from llama_deploy.cli.commands.auth import validate_authenticated_profile
-from llama_deploy.cli.config.env_service import service
-from llama_deploy.cli.config.schema import Auth
 from llama_deploy.cli.options import (
     interactive_option,
     native_tls_option,
 )
 from llama_deploy.cli.styles import WARNING
 from llama_deploy.cli.utils.redact import redact_api_key
-from llama_deploy.core.client.manage_client import ControlPlaneClient
 from llama_deploy.core.config import DEFAULT_DEPLOYMENT_FILE_PATH
 from llama_deploy.core.deployment_config import (
     read_deployment_config_from_git_root_or_cwd,
@@ -26,7 +24,11 @@ from rich import print as rprint
 
 from ..app import app
 
+if TYPE_CHECKING:
+    from llama_deploy.cli.config.schema import Auth
+
 logger = logging.getLogger(__name__)
+_ClickPath = getattr(click, "Path")
 
 
 @app.command(
@@ -37,7 +39,7 @@ logger = logging.getLogger(__name__)
     "deployment_file",
     required=False,
     default=DEFAULT_DEPLOYMENT_FILE_PATH,
-    type=click.Path(dir_okay=True, resolve_path=True, path_type=Path),
+    type=_ClickPath(dir_okay=True, resolve_path=True, path_type=Path),
 )
 @click.option(
     "--no-install", is_flag=True, help="Skip installing python and js dependencies"
@@ -72,7 +74,7 @@ logger = logging.getLogger(__name__)
 )
 @click.option(
     "--local-persistence-path",
-    type=click.Path(dir_okay=True, resolve_path=True, path_type=Path),
+    type=_ClickPath(dir_okay=True, resolve_path=True, path_type=Path),
     help="The path to the sqlite database to use for the workflow server if using local persistence",
 )
 @click.option(
@@ -165,13 +167,13 @@ def serve(
         raise click.Abort()
 
 
-def _set_env_vars_from_profile(profile: Auth):
+def _set_env_vars_from_profile(profile: Auth) -> None:
     if profile.api_key:
         _set_env_vars(profile.api_key, profile.api_url)
     _set_project_id_from_profile(profile)
 
 
-def _set_env_vars_from_env(env_vars: dict[str, str]):
+def _set_env_vars_from_env(env_vars: dict[str, str]) -> None:
     key = env_vars.get("LLAMA_CLOUD_API_KEY")
     url = env_vars.get("LLAMA_CLOUD_BASE_URL", "https://api.cloud.llamaindex.ai")
     # Also propagate project id if present in the environment
@@ -180,7 +182,7 @@ def _set_env_vars_from_env(env_vars: dict[str, str]):
         _set_env_vars(key, url)
 
 
-def _set_env_vars(key: str, url: str):
+def _set_env_vars(key: str, url: str) -> None:
     os.environ["LLAMA_CLOUD_API_KEY"] = key
     os.environ["LLAMA_CLOUD_BASE_URL"] = url
     # kludge for common web servers to inject local auth key
@@ -189,13 +191,13 @@ def _set_env_vars(key: str, url: str):
         os.environ[f"{prefix}LLAMA_CLOUD_BASE_URL"] = url
 
 
-def _set_project_id_from_env(env_vars: dict[str, str]):
+def _set_project_id_from_env(env_vars: dict[str, str]) -> None:
     project_id = env_vars.get("LLAMA_DEPLOY_PROJECT_ID")
     if project_id:
         os.environ["LLAMA_DEPLOY_PROJECT_ID"] = project_id
 
 
-def _set_project_id_from_profile(profile: Auth):
+def _set_project_id_from_profile(profile: Auth) -> None:
     if profile.project_id:
         os.environ["LLAMA_DEPLOY_PROJECT_ID"] = profile.project_id
 
@@ -211,6 +213,10 @@ def _maybe_inject_llama_cloud_credentials(
     - If no profile/api_key and session is interactive, prompt to log in and inject afterward.
     - If user declines or session is non-interactive, warn that deployment may not work.
     """
+    import questionary
+    from llama_deploy.appserver.workflow_loader import parse_environment_variables
+    from llama_deploy.cli.config.env_service import service
+
     # Read config directly to avoid cached global settings
     try:
         config = read_deployment_config_from_git_root_or_cwd(
@@ -225,9 +231,6 @@ def _maybe_inject_llama_cloud_credentials(
     if not config.llama_cloud and not require_cloud:
         return
 
-    # Import lazily to avoid loading appserver dependencies on general CLI startup
-    from llama_deploy.appserver.workflow_loader import parse_environment_variables
-
     vars = parse_environment_variables(
         config, deployment_file.parent if deployment_file.is_file() else deployment_file
     )
@@ -306,6 +309,9 @@ def _maybe_select_project_for_env_key() -> None:
 
     If more than one project exists, prompt the user to select one.
     """
+    import questionary
+    from llama_deploy.core.client.manage_client import ControlPlaneClient
+
     api_key = os.environ.get("LLAMA_CLOUD_API_KEY")
     base_url = os.environ.get("LLAMA_CLOUD_BASE_URL", "https://api.cloud.llamaindex.ai")
     if not api_key:

llama_deploy/cli/config/_config.py

@@ -67,11 +67,11 @@ class ConfigManager:
             config_dir = Path.home() / ".config" / "llamactl"
         return config_dir.expanduser()
 
-    def _ensure_config_dir(self):
+    def _ensure_config_dir(self) -> None:
         """Create configuration directory if it doesn't exist"""
         self.config_dir.mkdir(parents=True, exist_ok=True)
 
-    def _init_database(self):
+    def _init_database(self) -> None:
         """Initialize SQLite database and run migrations; then seed defaults."""
 
         with sqlite3.connect(self.db_path) as conn:
@@ -80,7 +80,7 @@ class ConfigManager:
 
             conn.commit()
 
-    def destroy_database(self):
+    def destroy_database(self) -> None:
         """Destroy the database"""
         self.db_path.unlink()
         self._init_database()
@@ -89,7 +89,7 @@ class ConfigManager:
     ## Settings
     #############################################
 
-    def set_settings_current_profile(self, name: str | None):
+    def set_settings_current_profile(self, name: str | None) -> None:
         """Set or clear the current active profile.
 
         If name is None, the setting is removed.

llama_deploy/cli/config/_migrations.py

@@ -8,8 +8,13 @@ from __future__ import annotations
 import logging
 import re
 import sqlite3
+import sys
 from importlib import import_module, resources
-from importlib.resources.abc import Traversable
+
+if sys.version_info >= (3, 11):
+    from importlib.resources.abc import Traversable
+else:
+    from importlib.abc import Traversable
 
 logger = logging.getLogger(__name__)
 
@@ -22,7 +27,7 @@ def _iter_migration_files() -> list[Traversable]:
     """Yield packaged SQL migration files in lexicographic order."""
     pkg = import_module(_MIGRATIONS_PKG)
     root = resources.files(pkg)
-    files = (p for p in root.iterdir() if p.name.endswith(".sql"))
+    files: list[Traversable] = [p for p in root.iterdir() if p.name.endswith(".sql")]
     if not files:
         raise ValueError("No migration files found")
     return sorted(files, key=lambda p: p.name)

llama_deploy/cli/config/auth_service.py

@@ -86,7 +86,7 @@ class AuthService:
         return asyncio.run(_fetch_server_version())
 
     def _validate_token_and_list_projects(self, api_key: str) -> list[ProjectSummary]:
-        async def _run():
+        async def _run() -> list[ProjectSummary]:
             async with ControlPlaneClient.ctx(self.env.api_url, api_key) as client:
                 return await client.list_projects()
 

llama_deploy/cli/config/migrations/0001_init.sql

@@ -32,4 +32,4 @@ SELECT DISTINCT api_url, 0 FROM profiles;
 
 -- 3) Ensure the default cloud environment exists with auth required
 INSERT OR IGNORE INTO environments (api_url, requires_auth, min_llamactl_version)
-VALUES ('https://api.cloud.llamaindex.ai', 1, NULL);
+VALUES ('https://api.cloud.llamaindex.ai', 1, NULL);

llama_deploy/cli/config/migrations/0002_add_auth_fields.sql

@@ -20,5 +20,3 @@ WHERE id IS NULL;
 
 -- Ensure id values are unique
 CREATE UNIQUE INDEX IF NOT EXISTS idx_profiles_id ON profiles(id);
-
-

llama_deploy/cli/pkg/options.py

@@ -7,13 +7,16 @@ from llama_deploy.core.config import DEFAULT_DEPLOYMENT_FILE_PATH
 P = ParamSpec("P")
 R = TypeVar("R")
 
+# hack around for mypy not letting you set path_type=Path on click.Path
+_ClickPath = getattr(click, "Path")
+
 
 def _deployment_file_option(f: Callable[P, R]) -> Callable[P, R]:
     return click.argument(
         "deployment_file",
         required=False,
         default=DEFAULT_DEPLOYMENT_FILE_PATH,
-        type=click.Path(dir_okay=True, resolve_path=True, path_type=Path),
+        type=_ClickPath(dir_okay=True, resolve_path=True, path_type=Path),
     )(f)
 
 

llama_deploy/cli/pkg/utils.py

@@ -1,8 +1,9 @@
 from pathlib import Path
-from tomllib import load as load_toml
 
+from llama_deploy.core._compat import load_toml_file
 
-def _get_min_py_version(requires_python: str):
+
+def _get_min_py_version(requires_python: str) -> str:
     min_v = requires_python.split(",")[0].strip()
     return (
         min_v.replace("=", "")
@@ -13,7 +14,7 @@ def _get_min_py_version(requires_python: str):
     )
 
 
-def infer_python_version(config_dir: Path):
+def infer_python_version(config_dir: Path) -> str:
     if (config_dir / ".python-version").exists():
         with open(config_dir / ".python-version", "r") as f:
             content = f.read()
@@ -21,11 +22,13 @@ def infer_python_version(config_dir: Path):
                 py_version = content.strip()
                 return py_version
     with open(config_dir / "pyproject.toml", "rb") as f:
-        data = load_toml(f)
+        data = load_toml_file(f)
     return _get_min_py_version(data.get("project", {}).get("requires-python", "3.12"))
 
 
-def build_dockerfile_content(python_version: str | None = None, port: int = 4501):
+def build_dockerfile_content(
+    python_version: str | None = None, port: int = 4501
+) -> str:
     return f"""
 FROM python:{python_version}-slim-trixie