llama-deploy-core 0.2.7a1__tar.gz

llama_deploy_core-0.2.7a1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: llama-deploy-core
+Version: 0.2.7a1
+Summary: Core models and schemas for LlamaDeploy
+License: MIT
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Python: >=3.12, <4
+Description-Content-Type: text/markdown
+
+> [!WARNING]
+> This repository contains pre-release software. It is unstable, incomplete, and subject to breaking changes. Not recommended for use.

llama_deploy_core-0.2.7a1/README.md

@@ -0,0 +1,2 @@
+> [!WARNING]
+> This repository contains pre-release software. It is unstable, incomplete, and subject to breaking changes. Not recommended for use.

llama_deploy_core-0.2.7a1/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "llama-deploy-core"
+version = "0.2.7a1"
+description = "Core models and schemas for LlamaDeploy"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12, <4"
+dependencies = [
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.7.20,<0.8.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "llama_deploy.core"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+]

llama_deploy_core-0.2.7a1/src/llama_deploy/core/__init__.py

@@ -0,0 +1,3 @@
+from . import schema
+
+__all__ = ["schema"]

llama_deploy_core-0.2.7a1/src/llama_deploy/core/config.py

@@ -0,0 +1 @@
+DEFAULT_DEPLOYMENT_FILE_PATH = "llama_deploy.yaml"

llama_deploy_core-0.2.7a1/src/llama_deploy/core/git/git_util.py

@@ -0,0 +1,224 @@
+"""
+Git utilities for the purpose of exploring, cloning, and parsing llama-deploy repositories.
+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
+
+import yaml
+
+
+def parse_github_repo_url(repo_url: str) -> tuple[str, str]:
+    """
+    Parse GitHub repository URL to extract owner and repo name.
+
+    Args:
+        repo_url: GitHub repository URL (various formats supported)
+
+    Returns:
+        Tuple of (owner, repo_name)
+
+    Raises:
+        ValueError: If URL format is not recognized
+    """
+    # Remove .git suffix if present
+    url = repo_url.rstrip("/").removesuffix(".git")
+
+    # Handle different GitHub URL formats
+    patterns = [
+        r"https://github\.com/([^/]+)/([^/]+)",
+        r"git@github\.com:([^/]+)/([^/]+)",
+        r"github\.com/([^/]+)/([^/]+)",
+    ]
+
+    for pattern in patterns:
+        match = re.match(pattern, url)
+        if match:
+            return match.group(1), match.group(2)
+
+    raise ValueError(f"Could not parse GitHub repository URL: {repo_url}")
+
+
+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}@")
+    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
+    )
+    if result.returncode != 0:
+        raise subprocess.CalledProcessError(
+            result.returncode, args, result.stdout, result.stderr
+        )
+    return result.stdout.strip()
+
+
+class GitAccessError(Exception):
+    """Error raised when a user reportable git error occurs, e.g connection fails, cannot access repository, timeout, ref not found, etc."""
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+
+@dataclass
+class GitCloneResult:
+    git_sha: str
+    git_ref: str | None = None
+
+
+def clone_repo(
+    repository_url: str,
+    git_ref: str | None = None,
+    basic_auth: str | None = None,
+    dest_dir: Path | str | None = None,
+) -> GitCloneResult:
+    """
+    Clone a repository and checkout a specific ref, if provided. If user reportable access errors occur, raises a GitAccessError.
+
+    Args:
+        repository_url: The URL of the repository to clone
+        git_ref: The git reference to checkout, if provided
+        basic_auth: The basic auth to use to clone the repository
+        dest_dir: The directory to clone the repository to, if provided
+
+    Returns:
+        GitCloneResult: A dataclass containing the git SHA and resolved git ref (e.g. main if None was provided)
+    """
+    try:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            dest_dir = Path(temp_dir) if dest_dir is None else Path(dest_dir)
+            authenticated_url = inject_basic_auth(repository_url, basic_auth)
+            did_exist = (
+                dest_dir.exists() and dest_dir.is_dir() and list(dest_dir.iterdir())
+            )
+            if not did_exist:
+                # need to do a full clone to resolve any kind of ref without exploding in
+                # complexity (tag, branch, commit, short commit)
+                clone_args = [
+                    "git",
+                    "clone",
+                    authenticated_url,
+                    str(dest_dir.absolute()),
+                ]
+                _run_process(clone_args)
+
+            if not git_ref:
+                resolved_branch = _run_process(
+                    ["git", "branch", "--show-current"],
+                    cwd=str(dest_dir.absolute()),
+                )
+                if resolved_branch:
+                    git_ref = resolved_branch
+                else:
+                    try:
+                        resolved_tag = _run_process(
+                            ["git", "describe", "--tags", "--exact-match"],
+                            cwd=str(dest_dir.absolute()),
+                        )
+                        if resolved_tag:
+                            git_ref = resolved_tag
+                    except subprocess.CalledProcessError:
+                        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())
+                    )
+                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")
+            # 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 subprocess.TimeoutExpired:
+        raise GitAccessError("Timeout while cloning repository")
+
+
+def validate_deployment_file(repo_dir: Path, deployment_file_path: str) -> bool:
+    """
+    Validate that the deployment file exists in the repository.
+
+    Args:
+        repo_dir: The directory of the repository
+        deployment_file_path: The path to the deployment file, relative to the repository root
+
+    Returns:
+        True if the deployment file exists and appears to be valid, False otherwise
+    """
+    deployment_file = repo_dir / deployment_file_path
+    if not deployment_file.exists():
+        return False
+    with open(deployment_file, "r") as f:
+        try:
+            loaded = yaml.safe_load(f)
+            if not isinstance(loaded, dict):
+                return False
+            if "name" not in loaded:
+                return False
+            if not isinstance(loaded["name"], str):
+                return False
+            if "services" not in loaded:
+                return False
+            if not isinstance(loaded["services"], dict):
+                return False
+            return True  # good nuff for now. Eventually this should parse it into a model validated format
+        except yaml.YAMLError:
+            return False
+
+
+async def validate_git_public_access(repository_url: str) -> bool:
+    """Check if a git repository is publicly accessible using git ls-remote."""
+
+    try:
+        result = subprocess.run(
+            ["git", "ls-remote", "--heads", repository_url],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,  # Don't raise on non-zero exit
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, Exception):
+        return False
+
+
+async 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)
+    try:
+        result = subprocess.run(
+            ["git", "ls-remote", "--heads", auth_url],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, Exception):
+        return False

llama_deploy_core-0.2.7a1/src/llama_deploy/core/schema/__init__.py

@@ -0,0 +1,27 @@
+from .base import Base
+from .deployments import (
+    DeploymentCreate,
+    DeploymentResponse,
+    DeploymentUpdate,
+    DeploymentsListResponse,
+    LlamaDeploymentSpec,
+    apply_deployment_update,
+    LlamaDeploymentPhase,
+)
+from .git_validation import RepositoryValidationResponse, RepositoryValidationRequest
+from .projects import ProjectSummary, ProjectsListResponse
+
+__all__ = [
+    "Base",
+    "DeploymentCreate",
+    "DeploymentResponse",
+    "DeploymentUpdate",
+    "DeploymentsListResponse",
+    "LlamaDeploymentSpec",
+    "apply_deployment_update",
+    "LlamaDeploymentPhase",
+    "RepositoryValidationResponse",
+    "RepositoryValidationRequest",
+    "ProjectSummary",
+    "ProjectsListResponse",
+]

llama_deploy_core-0.2.7a1/src/llama_deploy/core/schema/base.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel, ConfigDict
+
+base_config = ConfigDict(
+    from_attributes=True,
+    arbitrary_types_allowed=True,
+    use_enum_values=False,
+    # ===== timedelta serialization =====
+    # Serialize timedelta as float
+    # This was the default behavior in pydantic v1, but was changed in v2 to be "iso8601"
+    # We want to keep the same behavior as v1 for now
+    # ================================
+    ser_json_timedelta="float",
+    # NOTE: we often use data model with fields that have "model_" prefix,
+    # so we need to set protected_namespaces=() to avoid conflict
+    protected_namespaces=(),
+)
+
+
+class Base(BaseModel):
+    model_config = base_config

llama_deploy_core-0.2.7a1/src/llama_deploy/core/schema/deployments.py

@@ -0,0 +1,188 @@
+from typing import Literal
+from datetime import datetime
+
+from pydantic import HttpUrl
+
+from .base import Base
+
+
+# K8s CRD phase values
+LlamaDeploymentPhase = Literal[
+    "Syncing",  # Initial reconciliation phase - controller is processing the deployment
+    "Pending",  # Waiting for deployment resources to be ready (pods starting up)
+    "Running",  # Deployment is healthy and serving traffic
+    "Failed",  # Complete deployment failure - no pods available
+    "Succeeded",  # Deployment completed successfully (for one-time jobs)
+    "RollingOut",  # Rolling update in progress - new pods being created while old ones still serve traffic
+    "RolloutFailed",  # New deployment failed but old pods are still available and serving traffic
+]
+
+
+class DeploymentResponse(Base):
+    id: str
+    name: str
+    repo_url: str
+    deployment_file_path: str
+    git_ref: str | None = None
+    git_sha: str | None = None
+    has_personal_access_token: bool = False
+    project_id: str
+    secret_names: list[str] | None = None
+    apiserver_url: HttpUrl | None
+    status: LlamaDeploymentPhase
+
+
+class DeploymentsListResponse(Base):
+    deployments: list[DeploymentResponse]
+
+
+class DeploymentCreate(Base):
+    name: str
+    repo_url: str
+    deployment_file_path: str | None = None
+    git_ref: str | None = None
+    personal_access_token: str | None = None
+    secrets: dict[str, str] | None = None
+
+
+class LlamaDeploymentMetadata(Base):
+    name: str
+    namespace: str
+    uid: str | None = None
+    resourceVersion: str | None = None
+    creationTimestamp: datetime | None = None
+    annotations: dict[str, str] | None = None
+    labels: dict[str, str] | None = None
+
+
+class LlamaDeploymentSpec(Base):
+    """
+    LlamaDeployment spec fields as defined in the Kubernetes CRD.
+
+    Maps to the spec section of the LlamaDeployment custom resource.
+    Field names match exactly with the K8s CRD for direct conversion.
+    """
+
+    projectId: str
+    repoUrl: str
+    deploymentFilePath: str = "llama_deploy.yaml"
+    gitRef: str | None = None
+    gitSha: str | None = None
+    name: str
+    secretName: str | None = None
+
+
+class LlamaDeploymentStatus(Base):
+    """
+    LlamaDeployment status fields as defined in the Kubernetes CRD.
+
+    Maps to the status section of the LlamaDeployment custom resource.
+    """
+
+    phase: LlamaDeploymentPhase | None = None
+    message: str | None = None
+    lastUpdated: datetime | None = None
+    authToken: str | None = None
+
+
+class LlamaDeploymentCRD(Base):
+    metadata: LlamaDeploymentMetadata
+    spec: LlamaDeploymentSpec
+    status: LlamaDeploymentStatus
+
+
+class DeploymentUpdate(Base):
+    """
+    Patch-style update model for deployments.
+
+    Fields not included in the request will remain unchanged.
+    Fields explicitly set to None will clear/delete the field value.
+
+    For secrets: provide a dict where string values add/update secrets
+    and null values remove secrets.
+    """
+
+    repo_url: str | None = None
+    deployment_file_path: str | None = None
+    git_ref: str | None = None
+    git_sha: str | None = None
+    personal_access_token: str | None = None
+    secrets: dict[str, str | None] | None = None
+
+
+class DeploymentUpdateResult(Base):
+    """
+    Result of applying a DeploymentUpdate to a LlamaDeploymentSpec.
+
+    Contains the updated spec and lists of secret changes to apply.
+    """
+
+    updated_spec: LlamaDeploymentSpec
+    secret_adds: dict[str, str]
+    secret_removes: list[str]
+
+
+def apply_deployment_update(
+    update: DeploymentUpdate,
+    existing_spec: LlamaDeploymentSpec,
+) -> DeploymentUpdateResult:
+    """
+    Apply a DeploymentUpdate to an existing LlamaDeploymentSpec.
+
+    Returns the updated spec and lists of secret changes.
+
+    Args:
+        update: The update to apply (snake_case fields from API)
+        existing_spec: The current LlamaDeploymentSpec (camelCase fields)
+        git_sha: The resolved git SHA to set
+
+    Returns:
+        DeploymentUpdateResult with updated spec and secret changes
+    """
+    # Start with a copy of the existing spec
+    updated_spec = existing_spec.model_copy()
+
+    # Apply direct field updates (only if not None)
+    # Convert from snake_case API fields to camelCase spec fields
+    if update.repo_url is not None:
+        updated_spec.repoUrl = update.repo_url
+
+    if update.deployment_file_path is not None:
+        updated_spec.deploymentFilePath = update.deployment_file_path
+
+    if update.git_ref is not None:
+        updated_spec.gitRef = update.git_ref
+
+    # Update gitSha if provided
+    if update.git_sha is not None:
+        updated_spec.gitSha = None if update.git_sha == "" else update.git_sha
+
+    # Track secret changes
+    secret_adds: dict[str, str] = {}
+    secret_removes: list[str] = []
+
+    # Handle personal access token (stored as GITHUB_PAT secret)
+    if update.personal_access_token is not None:
+        if update.personal_access_token == "":
+            # Empty string means remove the PAT
+            secret_removes.append("GITHUB_PAT")
+        else:
+            # Non-empty string means add/update the PAT
+            secret_adds["GITHUB_PAT"] = update.personal_access_token
+
+    # Handle explicit secret updates
+    secrets = update.secrets
+    if secrets is not None:
+        for key, value in secrets.items():
+            if value is None:
+                # None means remove this secret
+                secret_removes.append(key)
+            else:
+                # String value means add/update this secret
+                secret_adds[key] = value
+
+    return DeploymentUpdateResult(
+        updated_spec=updated_spec,
+        secret_adds=secret_adds,
+        secret_removes=secret_removes,
+    )

llama_deploy_core-0.2.7a1/src/llama_deploy/core/schema/git_validation.py

@@ -0,0 +1,46 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class RepositoryValidationResponse(BaseModel):
+    """
+    Unified response for repository validation that works for any git repository.
+    This is the primary schema that should be used for the /validate-repository endpoint.
+    """
+
+    accessible: bool = Field(
+        ...,
+        description="Whether the repository can be accessed by any means available to the server",
+    )
+    message: str = Field(..., description="Human-readable string explaining the status")
+    pat_is_obsolete: bool = Field(
+        default=False,
+        description="True if validation succeeded via GitHub App for a deployment that previously used a PAT",
+    )
+    github_app_name: Optional[str] = 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(
+        default=None,
+        description="GitHub App installation URL if repository is a private GitHub repo and server has GitHub App configured",
+    )
+
+
+class RepositoryValidationRequest(BaseModel):
+    repository_url: str
+    deployment_id: Optional[str] = None
+    pat: Optional[str] = None
+
+
+class GitApplicationValidationResponse(BaseModel):
+    """
+    After general repository validation, a model that describes further validation of configuration, such as the
+    git reference, it's resolved SHA (if resolveable), and whether the deployment file is valid.
+    """
+
+    is_valid: bool
+    error_message: str | None = None
+    git_ref: str | None = None
+    git_sha: str | None = None
+    valid_deployment_file_path: str | None = None

llama_deploy_core-0.2.7a1/src/llama_deploy/core/schema/projects.py

@@ -0,0 +1,14 @@
+from .base import Base
+
+
+class ProjectSummary(Base):
+    """Summary of a project with deployment count"""
+
+    project_id: str
+    deployment_count: int
+
+
+class ProjectsListResponse(Base):
+    """Response model for listing projects with deployment counts"""
+
+    projects: list[ProjectSummary]