llama-deploy-core 0.2.7a1__py3-none-any.whl → 0.3.0__py3-none-any.whl

llama_deploy/core/git/git_util.py

@@ -3,11 +3,11 @@ Git utilities for the purpose of exploring, cloning, and parsing llama-deploy re
 Responsibilities are lower level git access, as well as some application specific config parsing.
 """
 
-from dataclasses import dataclass
 import re
 import subprocess
-from pathlib import Path
 import tempfile
+from dataclasses import dataclass
+from pathlib import Path
 
 import yaml
 
@@ -46,20 +46,42 @@ def parse_github_repo_url(repo_url: str) -> tuple[str, str]:
 def inject_basic_auth(url: str, basic_auth: str | None = None) -> str:
     """Inject basic auth into a URL if provided"""
     if basic_auth and "://" in url and "@" not in url:
-        url = url.replace("https://", f"https://{basic_auth}@")
+        scheme, rest = url.split("://", 1)
+        url = f"{scheme}://{basic_auth}@{rest}"
     return url
 
 
-def _run_process(args: list[str], cwd: str | None = None) -> str:
-    """Run a process and raise an exception if it fails"""
-    result = subprocess.run(
-        args, cwd=cwd, capture_output=True, text=True, check=True, timeout=30
-    )
+def _run_process(args: list[str], cwd: str | None = None, timeout: int = 30) -> str:
+    """Run a process and raise a GitAccessError with detailed output if it fails.
+
+    The error message includes the command, return code, working directory,
+    and both stdout and stderr to aid debugging (e.g., git fetch failures).
+    """
+    try:
+        result = subprocess.run(
+            args, cwd=cwd, capture_output=True, text=True, check=False, timeout=timeout
+        )
+    except subprocess.TimeoutExpired:
+        cmd = " ".join(args)
+        where = f" (cwd={cwd})" if cwd else ""
+        raise GitAccessError(f"Command timed out after {timeout}s: {cmd}{where}")
+
     if result.returncode != 0:
-        raise subprocess.CalledProcessError(
-            result.returncode, args, result.stdout, result.stderr
+        cmd = " ".join(args)
+        where = f" (cwd={cwd})" if cwd else ""
+        stdout = (result.stdout or "").strip()
+        stderr = (result.stderr or "").strip()
+        details = []
+        if stdout:
+            details.append(f"stdout:\n{stdout}")
+        if stderr:
+            details.append(f"stderr:\n{stderr}")
+        detail_block = "\n\n".join(details) if details else "(no output)"
+        raise GitAccessError(
+            f"Command failed with exit code {result.returncode}: {cmd}{where}\n{detail_block}"
         )
-    return result.stdout.strip()
+
+    return (result.stdout or "").strip()
 
 
 class GitAccessError(Exception):
@@ -120,6 +142,7 @@ def clone_repo(
                 if resolved_branch:
                     git_ref = resolved_branch
                 else:
+                    # Try exact tag match; if it fails, we just ignore and proceed
                     try:
                         resolved_tag = _run_process(
                             ["git", "describe", "--tags", "--exact-match"],
@@ -127,34 +150,25 @@ def clone_repo(
                         )
                         if resolved_tag:
                             git_ref = resolved_tag
-                    except subprocess.CalledProcessError:
+                    except GitAccessError:
                         pass
             else:  # Checkout the ref
                 if did_exist:
-                    try:
-                        _run_process(
-                            ["git", "fetch", "origin"], cwd=str(dest_dir.absolute())
-                        )
-                    except subprocess.CalledProcessError:
-                        raise GitAccessError("Failed to resolve git reference")
-                try:
                     _run_process(
-                        ["git", "checkout", git_ref], cwd=str(dest_dir.absolute())
+                        ["git", "fetch", "origin"], cwd=str(dest_dir.absolute())
                     )
-                except subprocess.CalledProcessError as e:
-                    # Check error message to determine if it's a network issue or ref not found
-                    if "unable to access" in str(
-                        e.stderr
-                    ) or "fatal: unable to access repository" in str(e.stderr):
-                        raise GitAccessError("Failed to resolve git reference")
-                    else:
-                        raise GitAccessError(f"Commit SHA '{git_ref}' not found")
+                _run_process(
+                    ["git", "checkout", git_ref, "--"], cwd=str(dest_dir.absolute())
+                )
             # if no ref, stay on whatever the clone gave us/current commit
             # return the resolved sha
             resolved_sha = _run_process(
                 ["git", "rev-parse", "HEAD"], cwd=str(dest_dir.absolute())
             ).strip()
             return GitCloneResult(git_sha=resolved_sha, git_ref=git_ref)
+    except GitAccessError:
+        # Re-raise enriched errors from _run_process directly
+        raise
     except subprocess.TimeoutExpired:
         raise GitAccessError("Timeout while cloning repository")
 
@@ -191,7 +205,7 @@ def validate_deployment_file(repo_dir: Path, deployment_file_path: str) -> bool:
             return False
 
 
-async def validate_git_public_access(repository_url: str) -> bool:
+def validate_git_public_access(repository_url: str) -> bool:
     """Check if a git repository is publicly accessible using git ls-remote."""
 
     try:
@@ -207,7 +221,7 @@ async def validate_git_public_access(repository_url: str) -> bool:
         return False
 
 
-async def validate_git_credential_access(repository_url: str, basic_auth: str) -> bool:
+def validate_git_credential_access(repository_url: str, basic_auth: str) -> bool:
     """Check if a credential provides access to a git repository."""
 
     auth_url = inject_basic_auth(repository_url, basic_auth)
@@ -222,3 +236,101 @@ async def validate_git_credential_access(repository_url: str, basic_auth: str) -
         return result.returncode == 0
     except (subprocess.TimeoutExpired, Exception):
         return False
+
+
+def is_git_repo() -> bool:
+    """
+    checks if the cwd is a git repo
+    """
+    try:
+        _run_process(["git", "status"])
+        return True
+    except GitAccessError:
+        return False
+
+
+def list_remotes() -> list[str]:
+    """
+    list the remote urls for the current git repo
+    """
+    result = _run_process(["git", "remote", "-v"])
+    return [line.split()[1] for line in result.splitlines()]
+
+
+def get_current_branch() -> str | None:
+    """
+    get the current branch for the current git repo
+    """
+    result = _run_process(["git", "branch", "--show-current"])
+    return result.strip() if result.strip() else None
+
+
+def get_git_root() -> Path:
+    """
+    get the root of the current git repo
+    """
+    result = _run_process(["git", "rev-parse", "--show-toplevel"])
+    return Path(result.strip())
+
+
+def working_tree_has_changes() -> bool:
+    """
+    Returns True if the working tree has uncommitted or untracked changes.
+    Safe to call; returns False if unable to determine.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+        return bool((result.stdout or "").strip())
+    except Exception:
+        return False
+
+
+def get_unpushed_commits_count() -> int | None:
+    """
+    Returns the number of local commits ahead of the upstream.
+
+    - Returns an integer >= 0 when an upstream is configured
+    - Returns None when no upstream is configured
+    - Returns 0 if the status cannot be determined
+    """
+    try:
+        upstream = subprocess.run(
+            [
+                "git",
+                "rev-parse",
+                "--abbrev-ref",
+                "--symbolic-full-name",
+                "@{u}",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+        if upstream.returncode != 0:
+            return None
+
+        ahead_behind = subprocess.run(
+            ["git", "rev-list", "--left-right", "--count", "@{u}...HEAD"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+        output = (ahead_behind.stdout or "").strip()
+        if not output:
+            return 0
+        parts = output.split()
+        if len(parts) >= 2:
+            # format: behind ahead
+            ahead_count = int(parts[1])
+            return ahead_count
+        return 0
+    except Exception:
+        return 0

llama_deploy/core/iter_utils.py

@@ -0,0 +1,196 @@
+"""Iterator utilities for buffering, sorting, and debouncing streams."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, AsyncGenerator, Callable, TypeVar
+
+from typing_extensions import Literal
+
+T = TypeVar("T")
+
+
+async def debounced_sorted_prefix(
+    inner: AsyncGenerator[T, None],
+    *,
+    key: Callable[[T], Any],
+    debounce_seconds: float = 0.1,
+    max_window_seconds: float = 0.1,
+) -> AsyncGenerator[T, None]:
+    """Yield a stream where the initial burst is sorted, then passthrough.
+
+    Behavior:
+    - Buffer early items and sort them by the provided key.
+    - Flush the buffer when either:
+      - No new item arrives for `debounce_seconds`, or
+      - `max_window_seconds` elapses from the first buffered item, or
+    - After the first flush, subsequent items are yielded passthrough, in arrival order.
+
+    This async variant uses an asyncio.Queue and a background task to pump `inner`.
+    """
+
+    buffer: list[T] = []
+    debouncer = Debouncer(debounce_seconds, max_window_seconds)
+    merged = merge_generators(inner, debouncer.aiter())
+
+    async for item in merged:
+        if item == "__COMPLETE__":
+            buffer.sort(key=key)
+            for item in buffer:
+                yield item
+            buffer = []
+        else:
+            if debouncer.is_complete:
+                yield item
+            else:
+                debouncer.extend_window()
+                buffer.append(item)
+
+
+COMPLETE = Literal["__COMPLETE__"]
+
+
+async def merge_generators(
+    *generators: AsyncGenerator[T, None],
+    stop_on_first_completion: bool = False,
+) -> AsyncGenerator[T, None]:
+    """
+    Merge multiple async iterators into a single async iterator, yielding items as
+    soon as any source produces them.
+
+    - If stop_on_first_completion is False (default), continues until all inputs are exhausted.
+    - If stop_on_first_completion is True, stops as soon as any input completes.
+    - Propagates exceptions from any input immediately.
+    """
+    if not generators:
+        return
+
+    active_generators: dict[int, AsyncGenerator[T, None]] = {
+        index: gen for index, gen in enumerate(generators)
+    }
+
+    next_item_tasks: dict[int, asyncio.Task[T]] = {}
+    exception_to_raise: BaseException | None = None
+    stopped_on_first_completion = False
+
+    # Prime one pending task per generator to maintain fairness
+    for index, gen in active_generators.items():
+        next_item_tasks[index] = asyncio.create_task(anext(gen))
+
+    try:
+        while next_item_tasks and exception_to_raise is None:
+            done, _ = await asyncio.wait(
+                set(next_item_tasks.values()),
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            for finished in done:
+                # Locate which generator this task belonged to
+                task_index: int | None = None
+                for index, task in next_item_tasks.items():
+                    if task is finished:
+                        task_index = index
+                        break
+
+                if task_index is None:
+                    # Should not happen, but continue defensively
+                    continue
+
+                try:
+                    value = finished.result()
+                except StopAsyncIteration:
+                    # Generator exhausted
+                    if stop_on_first_completion:
+                        stopped_on_first_completion = True
+                        # Break out of the inner loop; the outer loop will
+                        # observe the stop flag and exit to the finally block
+                        # where pending tasks are cancelled and generators closed.
+                        break
+                    else:
+                        next_item_tasks.pop(task_index, None)
+                        active_generators.pop(task_index, None)
+                        continue
+                except Exception as exc:  # noqa: BLE001 - propagate specific generator error
+                    exception_to_raise = exc
+                    break
+                else:
+                    # Remove the finished task before yielding
+                    next_item_tasks.pop(task_index, None)
+                    yield value
+                    # Schedule the next item fetch for this generator
+                    gen = active_generators.get(task_index)
+                    if gen is not None:
+                        next_item_tasks[task_index] = asyncio.create_task(anext(gen))
+            # If we are configured to stop on first completion and observed one,
+            # exit the outer loop to perform cleanup in the finally block.
+            if stopped_on_first_completion:
+                break
+    finally:
+        # Ensure we do not leak tasks or open generators
+        for task in next_item_tasks.values():
+            task.cancel()
+        if next_item_tasks:
+            try:
+                await asyncio.gather(*next_item_tasks.values(), return_exceptions=True)
+            except Exception:
+                pass
+        for gen in active_generators.values():
+            try:
+                await gen.aclose()
+            except Exception:
+                pass
+
+    if exception_to_raise is not None:
+        raise exception_to_raise
+    if stopped_on_first_completion:
+        return
+
+
+class Debouncer:
+    """
+    Continually extends a complete time while extend is called, up to a max window.
+    Exposes methods that notify on completion
+    """
+
+    def __init__(
+        self,
+        debounce_seconds: float = 0.1,
+        max_window_seconds: float = 1,
+        get_time: Callable[[], float] = time.monotonic,
+    ):
+        self.debounce_seconds = debounce_seconds
+        self.max_window_seconds = max_window_seconds
+        self.complete_signal = asyncio.Event()
+        self.get_time = get_time
+        self.start_time = self.get_time()
+        self.complete_time = self.start_time + self.debounce_seconds
+        self.max_complete_time = self.start_time + self.max_window_seconds
+        asyncio.create_task(self._loop())
+
+    async def _loop(self):
+        while not self.complete_signal.is_set():
+            now = self.get_time()
+            remaining = min(self.complete_time, self.max_complete_time) - now
+            if remaining <= 0:
+                self.complete_signal.set()
+            else:
+                await asyncio.sleep(remaining)
+
+    @property
+    def is_complete(self) -> bool:
+        return self.complete_signal.is_set()
+
+    def extend_window(self) -> None:
+        """Mark a new item has arrived, extending the debounce window."""
+        now = self.get_time()
+        self.complete_time = now + self.debounce_seconds
+
+    async def wait(self) -> None:
+        """Wait for the debounce window to expire, or the max window to elapse."""
+        await self.complete_signal.wait()
+
+    async def aiter(self) -> AsyncGenerator[COMPLETE, None]:
+        """Yield a stream that emits an element when the wait event occurs."""
+        await self.wait()
+        yield "__COMPLETE__"

llama_deploy/core/path_util.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+
+def validate_path_traversal(
+    path: Path, source_root: Path, path_type: str = "path"
+) -> None:
+    """Validates that a path is within the source root to prevent path traversal attacks.
+
+    Args:
+        path: The path to validate
+        source_root: The root directory that paths should be relative to
+        path_type: Description of the path type for error messages
+
+    Raises:
+        DeploymentError: If the path is outside the source root
+    """
+    resolved_path = (source_root / path).resolve()
+    resolved_source_root = source_root.resolve()
+
+    if not resolved_path.is_relative_to(resolved_source_root):
+        msg = (
+            f"{path_type} {path} is not a subdirectory of the source root {source_root}"
+        )
+        raise RuntimeError(msg)

llama_deploy/core/schema/__init__.py

@@ -2,17 +2,20 @@ from .base import Base
 from .deployments import (
     DeploymentCreate,
     DeploymentResponse,
-    DeploymentUpdate,
     DeploymentsListResponse,
+    DeploymentUpdate,
+    LlamaDeploymentPhase,
     LlamaDeploymentSpec,
+    LogEvent,
     apply_deployment_update,
-    LlamaDeploymentPhase,
 )
-from .git_validation import RepositoryValidationResponse, RepositoryValidationRequest
-from .projects import ProjectSummary, ProjectsListResponse
+from .git_validation import RepositoryValidationRequest, RepositoryValidationResponse
+from .projects import ProjectsListResponse, ProjectSummary
+from .public import VersionResponse
 
 __all__ = [
     "Base",
+    "LogEvent",
     "DeploymentCreate",
     "DeploymentResponse",
     "DeploymentUpdate",
@@ -24,4 +27,5 @@ __all__ = [
     "RepositoryValidationRequest",
     "ProjectSummary",
     "ProjectsListResponse",
+    "VersionResponse",
 ]

llama_deploy/core/schema/deployments.py

@@ -1,11 +1,11 @@
-from typing import Literal
 from datetime import datetime
+from pathlib import Path
+from typing import Literal
 
 from pydantic import HttpUrl
 
 from .base import Base
 
-
 # K8s CRD phase values
 LlamaDeploymentPhase = Literal[
     "Syncing",  # Initial reconciliation phase - controller is processing the deployment
@@ -18,6 +18,15 @@ LlamaDeploymentPhase = Literal[
 ]
 
 
+class DeploymentEvent(Base):
+    message: str | None = None
+    reason: str | None = None
+    type: str | None = None
+    first_timestamp: datetime | None = None
+    last_timestamp: datetime | None = None
+    count: int | None = None
+
+
 class DeploymentResponse(Base):
     id: str
     name: str
@@ -30,6 +39,8 @@ class DeploymentResponse(Base):
     secret_names: list[str] | None = None
     apiserver_url: HttpUrl | None
     status: LlamaDeploymentPhase
+    warning: str | None = None
+    events: list[DeploymentEvent] | None = None
 
 
 class DeploymentsListResponse(Base):
@@ -65,11 +76,13 @@ class LlamaDeploymentSpec(Base):
 
     projectId: str
     repoUrl: str
-    deploymentFilePath: str = "llama_deploy.yaml"
+    deploymentFilePath: str = "."
     gitRef: str | None = None
     gitSha: str | None = None
     name: str
     secretName: str | None = None
+    # when true, the deployment will prebuild the UI assets and serve them from a static file server
+    staticAssetsPath: str | None = None
 
 
 class LlamaDeploymentStatus(Base):
@@ -108,6 +121,7 @@ class DeploymentUpdate(Base):
     git_sha: str | None = None
     personal_access_token: str | None = None
     secrets: dict[str, str | None] | None = None
+    static_assets_path: Path | None = None
 
 
 class DeploymentUpdateResult(Base):
@@ -157,6 +171,11 @@ def apply_deployment_update(
     if update.git_sha is not None:
         updated_spec.gitSha = None if update.git_sha == "" else update.git_sha
 
+    # always apply this, as it should be cleared out if none, and is only set by the server
+    updated_spec.staticAssetsPath = (
+        str(update.static_assets_path) if update.static_assets_path else None
+    )
+
     # Track secret changes
     secret_adds: dict[str, str] = {}
     secret_removes: list[str] = []
@@ -186,3 +205,10 @@ def apply_deployment_update(
         secret_adds=secret_adds,
         secret_removes=secret_removes,
     )
+
+
+class LogEvent(Base):
+    pod: str
+    container: str
+    text: str
+    timestamp: datetime

llama_deploy/core/schema/git_validation.py

@@ -1,4 +1,5 @@
-from typing import Optional
+from pathlib import Path
+
 from pydantic import BaseModel, Field
 
 
@@ -17,11 +18,11 @@ class RepositoryValidationResponse(BaseModel):
         default=False,
         description="True if validation succeeded via GitHub App for a deployment that previously used a PAT",
     )
-    github_app_name: Optional[str] = Field(
+    github_app_name: str | None = Field(
         default=None,
         description="Name of the GitHub App if repository is a private GitHub repo and server has GitHub App configured",
     )
-    github_app_installation_url: Optional[str] = Field(
+    github_app_installation_url: str | None = Field(
         default=None,
         description="GitHub App installation URL if repository is a private GitHub repo and server has GitHub App configured",
     )
@@ -29,8 +30,8 @@ class RepositoryValidationResponse(BaseModel):
 
 class RepositoryValidationRequest(BaseModel):
     repository_url: str
-    deployment_id: Optional[str] = None
-    pat: Optional[str] = None
+    deployment_id: str | None = None
+    pat: str | None = None
 
 
 class GitApplicationValidationResponse(BaseModel):
@@ -44,3 +45,7 @@ class GitApplicationValidationResponse(BaseModel):
     git_ref: str | None = None
     git_sha: str | None = None
     valid_deployment_file_path: str | None = None
+    ui_build_output_path: Path | None = Field(
+        default=None,
+        description="Path to the UI build output, if the deployment's UI has a package.json with a build script; None if no UI is configured",
+    )

llama_deploy/core/schema/projects.py

@@ -1,3 +1,7 @@
+from typing import Any
+
+from pydantic import model_validator
+
 from .base import Base
 
 
@@ -5,8 +9,18 @@ class ProjectSummary(Base):
     """Summary of a project with deployment count"""
 
     project_id: str
+    project_name: str
     deployment_count: int
 
+    @model_validator(mode="before")
+    @classmethod
+    def set_default_project_name(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            if "project_name" not in data or data.get("project_name") is None:
+                if "project_id" in data:
+                    data["project_name"] = data["project_id"]
+        return data
+
 
 class ProjectsListResponse(Base):
     """Response model for listing projects with deployment counts"""

llama_deploy/core/schema/public.py

@@ -0,0 +1,7 @@
+from .base import Base
+
+
+class VersionResponse(Base):
+    version: str
+    requires_auth: bool = False
+    min_llamactl_version: str | None = None

llama_deploy/core/server/manage_api/__init__.py

@@ -0,0 +1,14 @@
+from ._abstract_deployments_service import (
+    AbstractDeploymentsService,
+    AbstractPublicDeploymentsService,
+)
+from ._create_deployments_router import create_v1beta1_deployments_router
+from ._exceptions import DeploymentNotFoundError, ReplicaSetNotFoundError
+
+__all__ = [
+    "AbstractDeploymentsService",
+    "AbstractPublicDeploymentsService",
+    "create_v1beta1_deployments_router",
+    "DeploymentNotFoundError",
+    "ReplicaSetNotFoundError",
+]