llama-deploy-appserver 0.2.7a1__py3-none-any.whl

llama_deploy/appserver/settings.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class ApiserverSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="LLAMA_DEPLOY_APISERVER_")
+
+    host: str = Field(
+        default="127.0.0.1",
+        description="The host where to run the API Server",
+    )
+    port: int = Field(
+        default=4501,
+        description="The TCP port where to bind the API Server",
+    )
+    rc_path: Path = Field(
+        default=Path("./.llama_deploy_rc"),
+        description="Path to the folder containing the deployment configs that will be loaded at startup",
+    )
+    deployments_path: Path | None = Field(
+        default=None,
+        description="Path to the folder where deployments will create their root path, defaults to a temp dir",
+    )
+    deployment_file_path: str | None = Field(
+        default=None,
+        description="Optional path, relative to the rc_path, where the deployment file is located. If not provided, will glob all .yml/.yaml files in the rc_path",
+    )
+    use_tls: bool = Field(
+        default=False,
+        description="Use TLS (HTTPS) to communicate with the API Server",
+    )
+
+    # Metrics collection settings
+    prometheus_enabled: bool = Field(
+        default=True,
+        description="Whether to enable the Prometheus metrics exporter along with the API Server",
+    )
+    prometheus_port: int = Field(
+        default=9000,
+        description="The port where to serve Prometheus metrics",
+    )
+
+    # Tracing settings
+    tracing_enabled: bool = Field(
+        default=False,
+        description="Enable OpenTelemetry tracing. Defaults to False.",
+    )
+    tracing_service_name: str = Field(
+        default="llama-deploy-appserver",
+        description="Service name for tracing. Defaults to 'llama-deploy-appserver'.",
+    )
+    tracing_exporter: str = Field(
+        default="console",
+        description="Trace exporter type: 'console', 'jaeger', 'otlp'. Defaults to 'console'.",
+    )
+    tracing_endpoint: str | None = Field(
+        default=None,
+        description="Trace exporter endpoint. Required for 'jaeger' and 'otlp' exporters.",
+    )
+    tracing_sample_rate: float = Field(
+        default=1.0,
+        description="Trace sampling rate (0.0 to 1.0). Defaults to 1.0 (100% sampling).",
+    )
+    tracing_insecure: bool = Field(
+        default=True,
+        description="Use insecure connection for OTLP exporter. Defaults to True.",
+    )
+    tracing_timeout: int = Field(
+        default=30,
+        description="Timeout in seconds for trace export. Defaults to 30.",
+    )
+
+    @property
+    def url(self) -> str:
+        protocol = "https://" if self.use_tls else "http://"
+        if self.port == 80:
+            return f"{protocol}{self.host}"
+        return f"{protocol}{self.host}:{self.port}"
+
+
+settings = ApiserverSettings()

llama_deploy/appserver/source_managers/__init__.py

@@ -0,0 +1,5 @@
+from .base import SourceManager
+from .git import GitSourceManager
+from .local import LocalSourceManager
+
+__all__ = ["GitSourceManager", "LocalSourceManager", "SourceManager"]

llama_deploy/appserver/source_managers/base.py

@@ -0,0 +1,33 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from llama_deploy.appserver.deployment_config_parser import DeploymentConfig, SyncPolicy
+
+
+class SourceManager(ABC):
+    """Protocol to be implemented by classes responsible for managing Deployment sources."""
+
+    def __init__(self, config: DeploymentConfig, base_path: Path | None = None) -> None:
+        self._config = config
+        self._base_path = base_path
+
+    @abstractmethod
+    def sync(
+        self,
+        source: str,
+        destination: str | None = None,
+        sync_policy: SyncPolicy = SyncPolicy.REPLACE,
+    ) -> None:  # pragma: no cover
+        """Fetches resources from `source` so they can be used in a deployment.
+
+        Optionally uses `destination` to store data when this makes sense for the
+        specific source type.
+        """
+
+    def relative_path(self, source: str) -> str:
+        """Unfortunately, there's a difference in behavior of how the source managers sync.
+        The local source manager syncs the source into the <destination_path>/<source>, whereas
+        the git source manager just syncs the source into the <destination_path>. This is a temporary shim, since
+        changing this behavior is a breaking change to deployment.yaml configurations. Local source manager
+        overrides it. In a future major version, this behavior will be made consistent"""
+        return ""

llama_deploy/appserver/source_managers/git.py

@@ -0,0 +1,48 @@
+import shutil
+from pathlib import Path
+from typing import Any
+
+from git import Repo
+
+from .base import SourceManager, SyncPolicy
+
+
+class GitSourceManager(SourceManager):
+    """A SourceManager specialized for sources of type `git`."""
+
+    def sync(
+        self,
+        source: str,
+        destination: str | None = None,
+        sync_policy: SyncPolicy = SyncPolicy.REPLACE,
+    ) -> None:
+        """Clones the repository at URL `source` into a local path `destination`.
+
+        Args:
+            source: The URL of the git repository. It can optionally contain a branch target using the name convention
+                `git_repo_url@branch_name`. For example, "https://example.com/llama_deploy.git@branch_name".
+            destination: The path in the local filesystem where to clone the git repository.
+        """
+        if not destination:
+            raise ValueError("Destination cannot be empty")
+
+        if Path(destination).exists():
+            # FIXME: pull when SyncPolicy is MERGE
+            shutil.rmtree(destination)
+
+        url, branch_name = self._parse_source(source)
+        kwargs: dict[str, Any] = {"url": url, "to_path": destination}
+        if branch_name:
+            kwargs["multi_options"] = [f"-b {branch_name}", "--single-branch"]
+
+        Repo.clone_from(**kwargs)  # type: ignore
+
+    @staticmethod
+    def _parse_source(source: str) -> tuple[str, str | None]:
+        branch_name = None
+        toks = source.split("@")
+        url = toks[0]
+        if len(toks) > 1:
+            branch_name = toks[1]
+
+        return url, branch_name

llama_deploy/appserver/source_managers/local.py

@@ -0,0 +1,51 @@
+import shutil
+from pathlib import Path
+
+from .base import SourceManager, SyncPolicy
+
+
+class LocalSourceManager(SourceManager):
+    """A SourceManager specialized for sources of type `local`."""
+
+    def sync(
+        self,
+        source: str,
+        destination: str | None = None,
+        sync_policy: SyncPolicy = SyncPolicy.REPLACE,
+    ) -> None:
+        """Copies the folder with path `source` into a local path `destination`.
+
+        Args:
+            source: The filesystem path to the folder containing the source code.
+            destination: The path in the local filesystem where to copy the source directory.
+        """
+        if sync_policy == SyncPolicy.SKIP:
+            return
+
+        if not destination:
+            raise ValueError("Destination cannot be empty")
+
+        if Path(source).is_absolute():
+            raise ValueError("Source path must be relative to the deployment file")
+
+        base = self._base_path or Path()
+        final_path = base / source
+        destination_path = Path(destination)
+        dirs_exist_ok: bool = False
+        if destination_path.exists():
+            # Path is a non-empty directory
+            if sync_policy == SyncPolicy.REPLACE:
+                shutil.rmtree(destination_path)
+            elif sync_policy == SyncPolicy.MERGE:
+                dirs_exist_ok = True
+
+        try:
+            shutil.copytree(
+                final_path, destination_path / source, dirs_exist_ok=dirs_exist_ok
+            )
+        except Exception as e:
+            msg = f"Unable to copy {source} into {destination}: {e}"
+            raise ValueError(msg) from e
+
+    def relative_path(self, source: str) -> str:
+        return source

llama_deploy/appserver/stats.py

@@ -0,0 +1,36 @@
+from prometheus_client import Enum
+
+apiserver_state = Enum(
+    "apiserver_state",
+    "Current state of the API server",
+    states=[
+        "starting",
+        "running",
+        "stopped",
+    ],
+)
+
+deployment_state = Enum(
+    "deployment_state",
+    "Current state of a deployment",
+    ["deployment_name"],
+    states=[
+        "loading_services",
+        "ready",
+        "starting_services",
+        "running",
+        "stopped",
+    ],
+)
+
+service_state = Enum(
+    "service_state",
+    "Current state of a service attached to a deployment",
+    ["deployment_name", "service_name"],
+    states=[
+        "loading",
+        "syncing",
+        "installing",
+        "ready",
+    ],
+)

llama_deploy/appserver/tracing.py

@@ -0,0 +1,237 @@
+"""Tracing utilities for llama_deploy."""
+
+import logging
+from contextlib import contextmanager, nullcontext
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, Generator, TypeVar
+
+if TYPE_CHECKING:
+    from llama_deploy.appserver.settings import ApiserverSettings
+
+
+logger = logging.getLogger(__name__)
+
+# Since opentelemetry is optional, we have to use Any to type the tracer
+_tracer: Any | None = None
+_tracing_enabled = False
+_null_context = nullcontext()
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def configure_tracing(settings: "ApiserverSettings") -> None:
+    """Configure OpenTelemetry tracing based on the provided configuration."""
+    global _tracer, _tracing_enabled
+
+    if not settings.tracing_enabled:
+        logger.debug("Tracing is disabled")
+        _tracing_enabled = False
+        return
+
+    try:
+        from opentelemetry import trace  # type: ignore[import]
+        from opentelemetry.instrumentation.asyncio import AsyncioInstrumentor  # type: ignore[import]
+        from opentelemetry.sdk.resources import SERVICE_NAME, Resource  # type: ignore[import]
+        from opentelemetry.sdk.trace import TracerProvider  # type: ignore[import]
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor  # type: ignore[import]
+        from opentelemetry.sdk.trace.sampling import TraceIdRatioBased  # type: ignore[import]
+
+        # Create resource with service name
+        resource = Resource.create({SERVICE_NAME: settings.tracing_service_name})
+
+        # Create tracer provider with sampling
+        tracer_provider = TracerProvider(
+            resource=resource, sampler=TraceIdRatioBased(settings.tracing_sample_rate)
+        )
+
+        # Configure exporter based on config
+        if settings.tracing_exporter == "console":
+            from opentelemetry.sdk.trace.export import ConsoleSpanExporter  # type: ignore[import]
+
+            exporter = ConsoleSpanExporter()
+
+        elif settings.tracing_exporter == "otlp":
+            from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (  # type: ignore[import]
+                OTLPSpanExporter,
+            )
+
+            if not settings.tracing_endpoint:
+                raise ValueError("OTLP exporter requires an endpoint")
+            exporter = OTLPSpanExporter(
+                endpoint=f"{settings.tracing_endpoint}/v1/traces",
+                insecure=settings.tracing_insecure,
+                timeout=settings.tracing_timeout,
+            )
+        else:
+            raise ValueError(f"Unsupported exporter: {settings.tracing_exporter}")
+
+        # Add span processor
+        span_processor = BatchSpanProcessor(exporter)
+        tracer_provider.add_span_processor(span_processor)
+
+        # Set the global tracer provider
+        trace.set_tracer_provider(tracer_provider)
+
+        # Initialize global tracer
+        _tracer = trace.get_tracer(__name__)
+        _tracing_enabled = True
+
+        # Setup auto-instrumentation
+        AsyncioInstrumentor().instrument()
+
+        logger.info(
+            f"Tracing configured with {settings.tracing_exporter} exporter, service: {settings.tracing_service_name}"
+        )
+
+    except ImportError as e:
+        msg = (
+            f"Tracing is enabled but OpenTelemetry instrumentation packages are missing: {e}. "
+            "Run `pip install llama_deploy[observability]`"
+        )
+        logger.warning(msg)
+        _tracing_enabled = False
+    except Exception as e:
+        logger.error(f"Failed to configure tracing: {e}")
+        _tracing_enabled = False
+
+
+def get_tracer() -> Any | None:
+    """Get the configured tracer instance."""
+    return _tracer if _tracing_enabled else None
+
+
+def is_tracing_enabled() -> bool:
+    """Check if tracing is enabled."""
+    return _tracing_enabled
+
+
+def trace_method(
+    span_name: str | None = None, attributes: dict | None = None
+) -> Callable[[F], F]:
+    """Decorator to add tracing to synchronous methods."""
+
+    def decorator(func: F) -> F:
+        if not _tracing_enabled:
+            return func
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):  # type: ignore
+            tracer = get_tracer()
+            if not tracer:
+                return func(*args, **kwargs)
+
+            name = span_name or f"{func.__module__}.{func.__qualname__}"  # type: ignore
+            with tracer.start_as_current_span(name) as span:
+                if attributes:
+                    span.set_attributes(attributes)
+
+                if hasattr(func, "__annotations__"):
+                    for i, (param_name, _) in enumerate(func.__annotations__.items()):
+                        if i < len(args) and param_name not in {"self", "cls"}:
+                            span.set_attribute(
+                                f"arg.{param_name}", str(args[i])[:100]
+                            )  # Truncate long values
+
+                try:
+                    result = func(*args, **kwargs)
+                    span.set_attribute("success", True)
+                    return result
+                except Exception as e:
+                    span.set_attribute("success", False)
+                    span.set_attribute("error.type", type(e).__name__)
+                    span.set_attribute("error.message", str(e))
+                    raise
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def trace_async_method(
+    span_name: str | None = None, attributes: dict | None = None
+) -> Callable[[F], F]:
+    """Decorator to add tracing to asynchronous methods."""
+
+    def decorator(func: F) -> F:
+        if not _tracing_enabled:
+            return func
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):  # type: ignore
+            tracer = get_tracer()
+            if not tracer:
+                return await func(*args, **kwargs)
+
+            name = span_name or f"{func.__module__}.{func.__qualname__}"  # type: ignore
+            with tracer.start_as_current_span(name) as span:
+                if attributes:
+                    span.set_attributes(attributes)
+
+                if hasattr(func, "__annotations__"):
+                    for i, (param_name, _) in enumerate(func.__annotations__.items()):
+                        if i < len(args) and param_name not in {"self", "cls"}:
+                            span.set_attribute(
+                                f"arg.{param_name}", str(args[i])[:100]
+                            )  # Truncate long values
+
+                try:
+                    result = await func(*args, **kwargs)
+                    span.set_attribute("success", True)
+                    return result
+                except Exception as e:
+                    span.set_attribute("success", False)
+                    span.set_attribute("error.type", type(e).__name__)
+                    span.set_attribute("error.message", str(e))
+                    raise
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+@contextmanager
+def create_span(
+    name: str, attributes: dict | None = None
+) -> Generator[Any, None, None]:
+    tracer = get_tracer()
+    if tracer is None:
+        yield
+        return
+
+    with tracer.start_as_current_span(name) as span:
+        if attributes:
+            for k, v in attributes.items():
+                span.set_attribute(k, v)
+        yield span
+
+
+def add_span_attribute(key: str, value: Any) -> None:
+    """Add an attribute to the current span if tracing is enabled."""
+    if not _tracing_enabled:
+        return
+
+    try:
+        from opentelemetry import trace  # type: ignore[import]
+
+        current_span = trace.get_current_span()
+        if current_span:
+            current_span.set_attribute(key, str(value))
+    except Exception:
+        # Silently ignore tracing errors
+        pass
+
+
+def add_span_event(name: str, attributes: dict | None = None) -> None:
+    """Add an event to the current span if tracing is enabled."""
+    if not _tracing_enabled:
+        return
+
+    try:
+        from opentelemetry import trace  # type: ignore[import]
+
+        current_span = trace.get_current_span()
+        if current_span:
+            current_span.add_event(name, attributes or {})
+    except Exception:
+        # Silently ignore tracing errors
+        pass

llama_deploy/appserver/types.py

@@ -0,0 +1,100 @@
+import uuid
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+def generate_id() -> str:
+    return str(uuid.uuid4())
+
+
+class TaskDefinition(BaseModel):
+    """
+    The definition and state of a task.
+
+    Attributes:
+        input (str):
+            The task input.
+        session_id (str):
+            The session ID that the task belongs to.
+        task_id (str):
+            The task ID. Defaults to a random UUID.
+        service_id (str):
+            The service ID that the task should be sent to.
+            If blank, the orchestrator decides.
+    """
+
+    input: str
+    task_id: str = Field(default_factory=generate_id)
+    session_id: str | None = None
+    service_id: str | None = None
+
+
+class SessionDefinition(BaseModel):
+    """
+    The definition of a session.
+
+    Attributes:
+        session_id (str):
+            The session ID. Defaults to a random UUID.
+        task_definitions (list[str]):
+            The task ids in order, representing the session.
+        state (dict):
+            The current session state.
+    """
+
+    session_id: str = Field(default_factory=generate_id)
+    task_ids: list[str] = Field(default_factory=list)
+    state: dict = Field(default_factory=dict)
+
+
+class EventDefinition(BaseModel):
+    """The definition of event.
+
+    To be used as payloads for service endpoints when wanting to send serialized
+    Events.
+
+    Attributes:
+        event_object_str (str): serialized string of event.
+    """
+
+    service_id: str
+    event_obj_str: str
+
+
+class TaskResult(BaseModel):
+    """
+    The result of a task.
+
+    Attributes:
+        task_id (str):
+            The task ID.
+        history (list[str]):
+            The task history.
+        result (str):
+            The task result.
+        data (dict):
+            Additional data about the task or result.
+    """
+
+    task_id: str
+    history: list[str]
+    result: str
+    data: dict = Field(default_factory=dict)
+
+
+class StatusEnum(Enum):
+    HEALTHY = "Healthy"
+    UNHEALTHY = "Unhealthy"
+    DOWN = "Down"
+
+
+class Status(BaseModel):
+    status: StatusEnum
+    status_message: str
+    max_deployments: int | None = None
+    deployments: list[str] | None = None
+
+
+class DeploymentDefinition(BaseModel):
+    name: str

llama_deploy_appserver-0.2.7a1.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.3
+Name: llama-deploy-appserver
+Version: 0.2.7a1
+Summary: Application server components for LlamaDeploy
+Author: Massimiliano Pippi
+Author-email: Massimiliano Pippi <mpippi@gmail.com>
+License: MIT
+Requires-Dist: asgiref>=3.9.1
+Requires-Dist: llama-index-workflows>=1.1.0
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: prometheus-client>=0.20.0
+Requires-Dist: python-multipart>=0.0.18,<0.0.19
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: gitpython>=3.1.40,<4
+Requires-Dist: llama-deploy-core>=0.2.7a1,<0.3.0
+Requires-Dist: httpx>=0.28.1
+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_appserver-0.2.7a1.dist-info/RECORD

@@ -0,0 +1,28 @@
+llama_deploy/appserver/__init__.py,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+llama_deploy/appserver/__main__.py,sha256=2dd2fe1f9ceff01038198515f30c107a82dc83ffd8c038d123f41893bf7fe4cb,333
+llama_deploy/appserver/app.py,sha256=fbe5fa15e7dbb1ab4b98e29f838434023894b6adac8e099bc42ea9c4df990867,1506
+llama_deploy/appserver/bootstrap.py,sha256=13b332df52ef763e20fe2ff9bcc20917508fee8153fae80569d942dc6be03793,1505
+llama_deploy/appserver/client/__init__.py,sha256=1675fd1c7fb675700396e35fb9c83df093cc7ebb8ca01a4df4447d95991542f4,49
+llama_deploy/appserver/client/base.py,sha256=2d6e5b263b55b393bc3ff383109d868e3c7a1e298388958476ec028c810004cf,1137
+llama_deploy/appserver/client/client.py,sha256=7af5ab5359ed4cd8802749461f213b7b646984108023592eb15a04904dd96211,1312
+llama_deploy/appserver/client/models/__init__.py,sha256=d1cb7f4948b34831f88951d51b2bd63699ae60bee07dbcfe8d20c4c77719e213,142
+llama_deploy/appserver/client/models/apiserver.py,sha256=f258710196b55b5dd3d157a4d112d98947932314e6024019919749dced063a19,12511
+llama_deploy/appserver/client/models/model.py,sha256=1f81dff71866610735f30efa978182f568e6fec5eff262a73ad526ecf3ffba6b,2655
+llama_deploy/appserver/deployment.py,sha256=184dfe95476dd8eea8d3d63b9fed60ed37136f6f38ffa8d8fa66be107ded4e31,19207
+llama_deploy/appserver/deployment_config_parser.py,sha256=4b4e2f20336c3b46db5ae64fccb663a8f1c4f970d24daebc8362809ab665ff80,4032
+llama_deploy/appserver/routers/__init__.py,sha256=f882ea036d83f8239de66b6a17ae0a51865402e115310960680adff8ded49dab,129
+llama_deploy/appserver/routers/deployments.py,sha256=7839423ea6c4621ddf5e18d91394cf0caecb0f099779b79f8f199dfd8f2e7583,14570
+llama_deploy/appserver/routers/status.py,sha256=17b12f37ac92092fa5494b0ea3477f512972c05fc23c5fa56dc498e8e6120c75,1400
+llama_deploy/appserver/run_autodeploy.py,sha256=36316cbe2df413d374dcef013f90ed5774a02a2012576356160e22397ae91bed,5000
+llama_deploy/appserver/server.py,sha256=68b8db645e3b7323c140d12607812d9d21382aef5a5a1609d3cf30429440eddf,1991
+llama_deploy/appserver/settings.py,sha256=1f0bbc8e69edd4007b6be3988b3576699470a1fb06fd3a38d977ef45be1e688b,2891
+llama_deploy/appserver/source_managers/__init__.py,sha256=d52f325a4c84f16cfb220337afddcc6145dcfebc44564dc665d33442480e8f84,175
+llama_deploy/appserver/source_managers/base.py,sha256=f8ef6f6b851b39d37e7f5ddd631656a8d0e1015470adfc59a53699e83b33e533,1400
+llama_deploy/appserver/source_managers/git.py,sha256=ba197235f18297a29895f23a2534040337eddd0c2046fed88ac7f2d0a3038415,1577
+llama_deploy/appserver/source_managers/local.py,sha256=9e80d5f2a2247779e15c6a7b19ceef75dec7e9b0877ac350530d0f5d81ac2d3f,1690
+llama_deploy/appserver/stats.py,sha256=1f3989f6705a6de3e4d61ee8cdd189fbe04a2c53ec5e720b2e5168acc331427f,691
+llama_deploy/appserver/tracing.py,sha256=211e0695041f2ebf3a05471035fdcff582263b8150df2a459b54932bed9a9194,8199
+llama_deploy/appserver/types.py,sha256=f9e1e037f196d7a55af06095404ed33c8620d5c95f61c8bc87df75b6e714897f,2237
+llama_deploy_appserver-0.2.7a1.dist-info/WHEEL,sha256=cc8ae5806c5874a696cde0fcf78fdf73db4982e7c824f3ceab35e2b65182fa1a,79
+llama_deploy_appserver-0.2.7a1.dist-info/METADATA,sha256=7b2c8925c464b72bf518926eb786afff346ff5bb1dad7caf254802ecf8350dd2,845
+llama_deploy_appserver-0.2.7a1.dist-info/RECORD,,

llama_deploy_appserver-0.2.7a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.7.21
+Root-Is-Purelib: true
+Tag: py3-none-any