llama-deploy-appserver 0.3.0a8__tar.gz → 0.3.0a10__tar.gz

{llama_deploy_appserver-0.3.0a8 → llama_deploy_appserver-0.3.0a10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: llama-deploy-appserver
-Version: 0.3.0a8
+Version: 0.3.0a10
 Summary: Application server components for LlamaDeploy
 Author: Massimiliano Pippi
 Author-email: Massimiliano Pippi <mpippi@gmail.com>
@@ -10,10 +10,12 @@ Requires-Dist: pydantic-settings>=2.10.1
 Requires-Dist: uvicorn>=0.24.0
 Requires-Dist: fastapi>=0.100.0
 Requires-Dist: websockets>=12.0
-Requires-Dist: llama-deploy-core>=0.3.0a8,<0.4.0
+Requires-Dist: llama-deploy-core>=0.3.0a10,<0.4.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: prometheus-fastapi-instrumentator>=7.1.0
 Requires-Dist: packaging>=25.0
+Requires-Dist: structlog>=25.4.0
+Requires-Dist: rich>=14.1.0
 Requires-Python: >=3.12, <4
 Description-Content-Type: text/markdown
 

{llama_deploy_appserver-0.3.0a8 → llama_deploy_appserver-0.3.0a10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "llama-deploy-appserver"
-version = "0.3.0a8"
+version = "0.3.0a10"
 description = "Application server components for LlamaDeploy"
 readme = "README.md"
 license = { text = "MIT" }
@@ -14,10 +14,12 @@ dependencies = [
     "uvicorn>=0.24.0",
     "fastapi>=0.100.0",
     "websockets>=12.0",
-    "llama-deploy-core>=0.3.0a8,<0.4.0",
+    "llama-deploy-core>=0.3.0a10,<0.4.0",
     "httpx>=0.28.1",
     "prometheus-fastapi-instrumentator>=7.1.0",
     "packaging>=25.0",
+    "structlog>=25.4.0",
+    "rich>=14.1.0",
 ]
 
 [build-system]

{llama_deploy_appserver-0.3.0a8 → llama_deploy_appserver-0.3.0a10}/src/llama_deploy/appserver/app.py

@@ -13,6 +13,10 @@ import uvicorn
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.openapi.utils import get_openapi
+from llama_deploy.appserver.configure_logging import (
+    add_log_middleware,
+    setup_logging,
+)
 from llama_deploy.appserver.deployment_config_parser import (
     get_deployment_config,
 )
@@ -41,15 +45,21 @@ from starlette.schemas import SchemaGenerator
 from workflows.server import WorkflowServer
 
 from .deployment import Deployment
+from .interrupts import shutdown_event
 from .process_utils import run_process
 from .routers import health_router
 from .stats import apiserver_state
 
 logger = logging.getLogger("uvicorn.info")
 
+# Auto-configure logging on import when requested (e.g., uvicorn reload workers)
+if os.getenv("LLAMA_DEPLOY_AUTO_LOGGING", "0") == "1":
+    setup_logging(os.getenv("LOG_LEVEL", "INFO"))
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, Any]:
+    shutdown_event.clear()
     apiserver_state.state("starting")
     config = get_deployment_config()
 
@@ -137,6 +147,7 @@ def _setup_openapi(name: str, app: FastAPI, server: WorkflowServer) -> None:
 app = FastAPI(lifespan=lifespan)
 Instrumentator().instrument(app).expose(app)
 
+
 # Configure CORS middleware if the environment variable is set
 if not os.environ.get("DISABLE_CORS", False):
     app.add_middleware(
@@ -148,6 +159,7 @@ if not os.environ.get("DISABLE_CORS", False):
     )
 
 app.include_router(health_router)
+add_log_middleware(app)
 
 
 def open_browser_async(host: str, port: int) -> None:
@@ -181,6 +193,7 @@ def start_server(
     cwd: Path | None = None,
     deployment_file: Path | None = None,
     open_browser: bool = False,
+    configure_logging: bool = True,
 ) -> None:
     # Configure via environment so uvicorn reload workers inherit the values
     configure_settings(
@@ -199,12 +212,19 @@ def start_server(
     try:
         if open_browser:
             open_browser_async(settings.host, settings.port)
-
+        # Ensure reload workers configure logging on import
+        os.environ["LLAMA_DEPLOY_AUTO_LOGGING"] = "1"
+        # Configure logging for the launcher process as well
+        if configure_logging:
+            setup_logging(os.getenv("LOG_LEVEL", "INFO"))
         uvicorn.run(
             "llama_deploy.appserver.app:app",
             host=settings.host,
             port=settings.port,
             reload=reload,
+            timeout_graceful_shutdown=60,
+            access_log=False,
+            log_config=None,
         )
     finally:
         if ui_process is not None:
@@ -219,6 +239,8 @@ def start_server_in_target_venv(
     open_browser: bool = False,
     port: int | None = None,
     ui_port: int | None = None,
+    log_level: str | None = None,
+    log_format: str | None = None,
 ) -> None:
     # Ensure settings reflect the intended working directory before computing paths
 
@@ -246,6 +268,10 @@ def start_server_in_target_venv(
         env["LLAMA_DEPLOY_APISERVER_PORT"] = str(port)
     if ui_port:
         env["LLAMA_DEPLOY_APISERVER_PROXY_UI_PORT"] = str(ui_port)
+    if log_level:
+        env["LOG_LEVEL"] = log_level
+    if log_format:
+        env["LOG_FORMAT"] = log_format
 
     ret = run_process(
         args,

llama_deploy_appserver-0.3.0a10/src/llama_deploy/appserver/configure_logging.py

@@ -0,0 +1,189 @@
+import logging
+import logging.config
+import os
+import time
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from typing import Any, AsyncGenerator, Awaitable, Callable
+
+import structlog
+from fastapi import FastAPI, Request, Response
+from llama_deploy.appserver.correlation_id import (
+    create_correlation_id,
+    get_correlation_id,
+    set_correlation_id,
+)
+from llama_deploy.appserver.process_utils import should_use_color
+
+access_logger = logging.getLogger("app.access")
+
+
+def _get_or_create_correlation_id(request: Request) -> str:
+    return request.headers.get("X-Request-ID", create_correlation_id())
+
+
+def add_log_middleware(app: FastAPI):
+    @app.middleware("http")
+    async def add_log_id(
+        request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ):
+        set_correlation_id(_get_or_create_correlation_id(request))
+        return await call_next(request)
+
+    @app.middleware("http")
+    async def access_log_middleware(
+        request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ):
+        if _is_proxy_request(request):
+            return await call_next(request)
+        start = time.perf_counter()
+        response = await call_next(request)
+        dur_ms = (time.perf_counter() - start) * 1000
+        qp = str(request.query_params)
+        if qp:
+            qp = f"?{qp}"
+        access_logger.info(
+            f"{request.method} {request.url.path}{qp}",
+            extra={
+                "duration_ms": round(dur_ms, 2),
+                "status_code": response.status_code,
+            },
+        )
+        return response
+
+
+def _add_request_id(_: Any, __: str, event_dict: dict[str, Any]) -> dict[str, Any]:
+    req_id = get_correlation_id()
+    if req_id and "request_id" not in event_dict:
+        event_dict["request_id"] = req_id
+    return event_dict
+
+
+def _drop_uvicorn_color_message(
+    _: Any, __: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    # Uvicorn injects an ANSI-colored duplicate of the message under this key
+    event_dict.pop("color_message", None)
+    return event_dict
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """
+    Configure console logging via structlog with a compact, dev-friendly format.
+    Includes request_id and respects logging.extra.
+    """
+    # Choose renderer and timestamp format based on LOG_FORMAT
+    log_format = os.getenv("LOG_FORMAT", "console").lower()
+    is_console = log_format == "console"
+
+    if log_format == "json":
+        renderer = structlog.processors.JSONRenderer()
+        timestamper = structlog.processors.TimeStamper(fmt="iso", key="timestamp")
+    else:
+        renderer = structlog.dev.ConsoleRenderer(colors=should_use_color())
+        timestamper = structlog.processors.TimeStamper(fmt="%H:%M:%S", key="timestamp")
+
+    pre_chain = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        timestamper,
+        _add_request_id,
+    ]
+
+    # Ensure stdlib logs (foreign to structlog) also include `extra={...}` fields
+    # and that exceptions/stack info are rendered nicely (esp. for JSON format)
+    foreign_pre_chain = [
+        *pre_chain,
+        structlog.stdlib.ExtraAdder(),
+        *(  # otherwise ConsoleRenderer will render nice rich stack traces
+            [
+                structlog.processors.StackInfoRenderer(),
+                structlog.processors.format_exc_info,
+            ]
+            if not is_console
+            else []
+        ),
+        _drop_uvicorn_color_message,
+    ]
+
+    structlog.configure(
+        processors=[
+            *pre_chain,
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            structlog.stdlib.ExtraAdder(),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    handler = {
+        "class": "logging.StreamHandler",
+        "level": level,
+        "formatter": "console",
+        "stream": "ext://sys.stdout",
+    }
+
+    logging.config.dictConfig(
+        {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "formatters": {
+                "console": {
+                    "()": structlog.stdlib.ProcessorFormatter,
+                    # With Rich, let it handle the final formatting; otherwise use our renderer
+                    "processor": renderer,
+                    "foreign_pre_chain": foreign_pre_chain,
+                }
+            },
+            "handlers": {"console": handler, "default": handler},
+            "root": {
+                "handlers": ["console"],
+                "level": level,
+            },
+            "loggers": {
+                "uvicorn.access": {  # disable access logging, we have our own access log
+                    "level": "WARNING",
+                    "handlers": ["console"],
+                    "propagate": False,
+                },
+            },
+        }
+    )
+
+    # Reduce noise from httpx globally, with fine-grained suppression controlled per-request
+    logging.getLogger("httpx").addFilter(_HttpxProxyNoiseFilter())
+
+
+#####################################################################################
+### Proxying through the fastapi server in dev mode is noisy, various suppressions
+###
+def _is_proxy_request(request: Request) -> bool:
+    parts = request.url.path.split("/")
+    return len(parts) >= 4 and parts[1] == "deployments" and parts[3] == "ui"
+
+
+_suppress_httpx_logging: ContextVar[bool] = ContextVar(
+    "suppress_httpx_logging", default=False
+)
+
+
+class _HttpxProxyNoiseFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Return False to drop httpx info/debug logs when suppression is active."""
+        try:
+            if record.name.startswith("httpx") and record.levelno <= logging.INFO:
+                return not _suppress_httpx_logging.get()
+        except Exception:
+            return True
+        return True
+
+
+@asynccontextmanager
+async def suppress_httpx_logs() -> AsyncGenerator[None, None]:
+    _suppress_httpx_logging.set(True)
+    yield
+    _suppress_httpx_logging.set(False)

llama_deploy_appserver-0.3.0a10/src/llama_deploy/appserver/correlation_id.py

@@ -0,0 +1,24 @@
+import random
+import string
+from contextvars import ContextVar
+
+correlation_id_var: ContextVar[str] = ContextVar("correlation_id", default="")
+
+
+def get_correlation_id() -> str:
+    return correlation_id_var.get()
+
+
+def set_correlation_id(correlation_id: str) -> None:
+    correlation_id_var.set(correlation_id)
+
+
+def create_correlation_id() -> str:
+    return random_alphanumeric_string(8)
+
+
+_alphanumeric_chars = string.ascii_letters + string.digits
+
+
+def random_alphanumeric_string(length: int) -> str:
+    return "".join(random.choices(_alphanumeric_chars, k=length))

llama_deploy_appserver-0.3.0a10/src/llama_deploy/appserver/interrupts.py

@@ -0,0 +1,55 @@
+import asyncio
+import signal
+from asyncio import Event
+from contextlib import suppress
+from typing import Awaitable, TypeVar
+
+shutdown_event = Event()
+
+
+def setup_interrupts() -> None:
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, shutdown_event.set)
+
+
+class OperationAborted(Exception):
+    """Raised when an operation is aborted due to shutdown/interrupt."""
+
+
+T = TypeVar("T")
+
+
+async def wait_or_abort(
+    awaitable: Awaitable[T], shutdown_event: asyncio.Event = shutdown_event
+) -> T:
+    """Await an operation, aborting early if shutdown is requested.
+
+    If the shutdown event is set before the awaitable completes, cancel the
+    awaitable and raise OperationAborted. Otherwise, return the awaitable's result.
+    """
+    event = shutdown_event
+    if event.is_set():
+        raise OperationAborted()
+
+    op_task = asyncio.create_task(awaitable)
+    stop_task = asyncio.create_task(event.wait())
+    try:
+        done, _ = await asyncio.wait(
+            {op_task, stop_task}, return_when=asyncio.FIRST_COMPLETED
+        )
+        if stop_task in done:
+            op_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await op_task
+            raise OperationAborted()
+        # Operation finished first
+        stop_task.cancel()
+        with suppress(asyncio.CancelledError):
+            await stop_task
+        return await op_task
+    finally:
+        # Ensure no leaked tasks if an exception propagates
+        for t in (op_task, stop_task):
+            if not t.done():
+                t.cancel()

{llama_deploy_appserver-0.3.0a8 → llama_deploy_appserver-0.3.0a10}/src/llama_deploy/appserver/process_utils.py

@@ -103,7 +103,11 @@ def _should_use_pty(use_tty: bool | None) -> bool:
         return False
     if use_tty is None:
         return sys.stdout.isatty()
-    return use_tty and sys.stdout.isatty()
+    return use_tty and sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def should_use_color() -> bool:
+    return _should_use_pty(None)
 
 
 def _spawn_process(

{llama_deploy_appserver-0.3.0a8 → llama_deploy_appserver-0.3.0a10}/src/llama_deploy/appserver/routers/ui_proxy.py

@@ -1,5 +1,6 @@
 import asyncio
 import logging
+from contextlib import suppress
 from typing import List
 
 import httpx
@@ -13,51 +14,63 @@ from fastapi import (
 )
 from fastapi.responses import StreamingResponse
 from fastapi.staticfiles import StaticFiles
+from llama_deploy.appserver.configure_logging import suppress_httpx_logs
+from llama_deploy.appserver.interrupts import (
+    OperationAborted,
+    shutdown_event,
+    wait_or_abort,
+)
 from llama_deploy.appserver.settings import ApiserverSettings
 from llama_deploy.core.deployment_config import DeploymentConfig
-from starlette.background import BackgroundTask
 
 logger = logging.getLogger(__name__)
 
 
 async def _ws_proxy(ws: WebSocket, upstream_url: str) -> None:
     """Proxy WebSocket connection to upstream server."""
-    await ws.accept()
+    if shutdown_event.is_set():
+        await ws.close()
+        return
+
+    # Defer accept until after upstream connects so we can mirror the selected subprotocol
 
     # Forward most headers except WebSocket-specific ones
+    header_prefix_blacklist = ["sec-websocket-"]
     header_blacklist = {
         "host",
         "connection",
         "upgrade",
-        "sec-websocket-key",
-        "sec-websocket-version",
-        "sec-websocket-extensions",
     }
-    hdrs = [(k, v) for k, v in ws.headers.items() if k.lower() not in header_blacklist]
+    hdrs = []
+    for k, v in ws.headers.items():
+        if k.lower() not in header_blacklist:
+            for prefix in header_prefix_blacklist:
+                if k.lower().startswith(prefix):
+                    break
+            else:
+                hdrs.append((k, v))
 
     try:
         # Parse subprotocols if present
-        subprotocols: List[websockets.Subprotocol] | None = None
-        if "sec-websocket-protocol" in ws.headers:
-            # Parse comma-separated subprotocols
-            subprotocols = [
-                websockets.Subprotocol(p.strip())
-                for p in ws.headers["sec-websocket-protocol"].split(",")
-            ]
-
-        # Open upstream WebSocket connection
+        subprotocols: List[str] | None = None
+        requested = ws.headers.get("sec-websocket-protocol")
+        if requested:
+            # Parse comma-separated subprotocols (as plain strings)
+            subprotocols = [p.strip() for p in requested.split(",")]
+
+        # Open upstream WebSocket connection, offering the same subprotocols
         async with websockets.connect(
             upstream_url,
             additional_headers=hdrs,
             subprotocols=subprotocols,
-            open_timeout=None,
-            ping_interval=None,
+            open_timeout=5,
         ) as upstream:
+            await ws.accept(subprotocol=upstream.subprotocol)
 
             async def client_to_upstream() -> None:
                 try:
                     while True:
-                        msg = await ws.receive()
+                        msg = await wait_or_abort(ws.receive(), shutdown_event)
                         if msg["type"] == "websocket.receive":
                             if "text" in msg:
                                 await upstream.send(msg["text"])
@@ -65,26 +78,49 @@ async def _ws_proxy(ws: WebSocket, upstream_url: str) -> None:
                                 await upstream.send(msg["bytes"])
                         elif msg["type"] == "websocket.disconnect":
                             break
-                except Exception as e:
-                    logger.debug(f"Client to upstream connection ended: {e}")
+                except OperationAborted:
+                    pass
+                except Exception:
+                    pass
 
             async def upstream_to_client() -> None:
                 try:
-                    async for message in upstream:
+                    while True:
+                        message = await wait_or_abort(upstream.recv(), shutdown_event)
                         if isinstance(message, str):
                             await ws.send_text(message)
                         else:
                             await ws.send_bytes(message)
-                except Exception as e:
-                    logger.debug(f"Upstream to client connection ended: {e}")
-
-            # Pump both directions concurrently
-            await asyncio.gather(
-                client_to_upstream(), upstream_to_client(), return_exceptions=True
+                except OperationAborted:
+                    pass
+                except Exception:
+                    pass
+
+            # Pump both directions concurrently, cancel the peer when one side closes
+            t1 = asyncio.create_task(client_to_upstream())
+            t2 = asyncio.create_task(upstream_to_client())
+            _, pending = await asyncio.wait(
+                {t1, t2}, return_when=asyncio.FIRST_COMPLETED
             )
+            for task in pending:
+                task.cancel()
+                with suppress(asyncio.CancelledError):
+                    await task
+
+            # On shutdown, proactively close both sides to break any remaining waits
+            if shutdown_event.is_set():
+                with suppress(Exception):
+                    await ws.close()
+                with suppress(Exception):
+                    await upstream.close()
 
     except Exception as e:
         logger.error(f"WebSocket proxy error: {e}")
+        # Accept then close so clients (and TestClient) don't error on enter
+        with suppress(Exception):
+            await ws.accept()
+        with suppress(Exception):
+            await ws.close()
     finally:
         try:
             await ws.close()
@@ -105,7 +141,7 @@ def create_ui_proxy_router(name: str, port: int) -> APIRouter:
         path: str | None = None,
     ) -> None:
         # Build the upstream WebSocket URL using FastAPI's extracted path parameter
-        slash_path = f"/{path}" if path else ""
+        slash_path = f"/{path}" if path is not None else ""
         upstream_path = f"/deployments/{name}/ui{slash_path}"
 
         # Convert to WebSocket URL
@@ -113,8 +149,6 @@ def create_ui_proxy_router(name: str, port: int) -> APIRouter:
         if websocket.url.query:
             upstream_url += f"?{websocket.url.query}"
 
-        logger.debug(f"Proxying WebSocket {websocket.url} -> {upstream_url}")
-
         await _ws_proxy(websocket, upstream_url)
 
     @deployment_router.api_route(
@@ -167,22 +201,28 @@ def create_ui_proxy_router(name: str, port: int) -> APIRouter:
                 headers=headers,
                 content=request.stream(),  # stream uploads
             )
-            upstream = await client.send(req, stream=True)
+            async with suppress_httpx_logs():
+                upstream = await client.send(req, stream=True)
 
             resp_headers = {
                 k: v for k, v in upstream.headers.items() if k.lower() not in hop_by_hop
             }
 
-            # Close client when upstream response is done
-            async def cleanup() -> None:
-                await upstream.aclose()
-                await client.aclose()
+            # Stream downloads and ensure cleanup in the generator's finally block
+            async def upstream_body():
+                try:
+                    async for chunk in upstream.aiter_raw():
+                        yield chunk
+                finally:
+                    try:
+                        await upstream.aclose()
+                    finally:
+                        await client.aclose()
 
             return StreamingResponse(
-                upstream.aiter_raw(),  # stream downloads
+                upstream_body(),
                 status_code=upstream.status_code,
                 headers=resp_headers,
-                background=BackgroundTask(cleanup),  # tidy up when finished
             )
 
         except httpx.ConnectError:

{llama_deploy_appserver-0.3.0a8 → llama_deploy_appserver-0.3.0a10}/src/llama_deploy/appserver/workflow_loader.py

@@ -1,3 +1,4 @@
+import configparser
 import functools
 import importlib
 import logging
@@ -5,8 +6,10 @@ import os
 import socket
 import subprocess
 import sys
+from dataclasses import dataclass
 from importlib.metadata import version as pkg_version
 from pathlib import Path
+from textwrap import dedent
 
 from dotenv import dotenv_values
 from llama_deploy.appserver.deployment_config_parser import (
@@ -104,7 +107,7 @@ def inject_appserver_into_target(
     path = settings.resolved_config_parent
     logger.info(f"Installing ensuring venv at {path} and adding appserver to it")
     _ensure_uv_available()
-    _add_appserver_if_missing(path, source_root, sdists=sdists)
+    _install_and_add_appserver_if_missing(path, source_root, sdists=sdists)
 
 
 def _get_installed_version_within_target(path: Path) -> Version | None:
@@ -115,9 +118,16 @@ def _get_installed_version_within_target(path: Path) -> Version | None:
                 "run",
                 "python",
                 "-c",
-                """from importlib.metadata import version; print(version("llama-deploy-appserver"))""",
+                dedent("""
+                        from importlib.metadata import version
+                        try:
+                            print(version("llama-deploy-appserver"))
+                        except Exception:
+                            pass
+                       """),
             ],
             cwd=path,
+            stderr=subprocess.DEVNULL,
         )
         try:
             return Version(result.decode("utf-8").strip())
@@ -142,14 +152,14 @@ def _is_missing_or_outdated(path: Path) -> Version | None:
     return None
 
 
-def _add_appserver_if_missing(
+def _install_and_add_appserver_if_missing(
     path: Path,
     source_root: Path,
     save_version: bool = False,
     sdists: list[Path] | None = None,
 ) -> None:
     """
-    Add the appserver to the venv if it's not already there.
+    Ensure venv, install project deps, and add the appserver to the venv if it's missing or outdated
     """
 
     if not (source_root / path / "pyproject.toml").exists():
@@ -158,7 +168,10 @@ def _add_appserver_if_missing(
         )
         return
 
-    def run_uv(cmd: str, args: list[str]):
+    def run_uv(cmd: str, args: list[str] = [], extra_env: dict[str, str] | None = None):
+        env = os.environ.copy()
+        if extra_env:
+            env.update(extra_env)
         run_process(
             ["uv", cmd] + args,
             cwd=source_root / path,
@@ -166,6 +179,7 @@ def _add_appserver_if_missing(
             color_code="36",
             use_tty=False,
             line_transform=_exclude_venv_warning,
+            env=env,
         )
 
     def ensure_venv(path: Path, force: bool = False) -> Path:
@@ -174,14 +188,30 @@ def _add_appserver_if_missing(
             run_uv("venv", [str(venv_path)])
         return venv_path
 
+    editable = are_we_editable_mode()
+    venv_path = ensure_venv(path, force=editable)
+    run_uv(
+        "sync",
+        ["--no-dev", "--inexact"],
+        extra_env={"UV_PROJECT_ENVIRONMENT": str(venv_path)},
+    )
+
     if sdists:
         run_uv(
             "pip",
             ["install"]
             + [str(s.absolute()) for s in sdists]
-            + ["--prefix", str(ensure_venv(path))],
+            + ["--prefix", str(venv_path)],
         )
     elif are_we_editable_mode():
+        same_python_version = _same_python_version(venv_path)
+        if not same_python_version.is_same:
+            logger.error(
+                f"Python version mismatch. Current: {same_python_version.current_version} != Project: {same_python_version.target_version}. During development, the target environment must be running the same Python version, otherwise the appserver cannot be installed."
+            )
+            raise RuntimeError(
+                f"Python version mismatch. Current: {same_python_version.current_version} != Project: {same_python_version.target_version}"
+            )
         pyproject = _find_development_pyproject()
         if pyproject is None:
             raise RuntimeError("No pyproject.toml found in llama-deploy-appserver")
@@ -195,7 +225,7 @@ def _add_appserver_if_missing(
                 "llama-deploy-appserver",
                 target,
                 "--prefix",
-                str(ensure_venv(path, force=True)),
+                str(venv_path),
             ],
         )
 
@@ -211,7 +241,7 @@ def _add_appserver_if_missing(
                         "install",
                         f"llama-deploy-appserver=={version}",
                         "--prefix",
-                        str(ensure_venv(path)),
+                        str(venv_path),
                     ],
                 )
 
@@ -262,16 +292,53 @@ def _ensure_uv_available() -> None:
             raise RuntimeError(msg)
 
 
+@dataclass
+class SamePythonVersionResult:
+    is_same: bool
+    current_version: str
+    target_version: str | None
+
+
+def _same_python_version(venv_path: Path) -> SamePythonVersionResult:
+    current_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    target_version = None
+    cfg = venv_path / "pyvenv.cfg"
+    if cfg.exists():
+        parser = configparser.ConfigParser()
+        parser.read_string("[venv]\n" + cfg.read_text())
+        ver_str = parser["venv"].get("version_info", "").strip()
+        if ver_str:
+            try:
+                v = Version(ver_str)
+                target_version = f"{v.major}.{v.minor}"
+            except InvalidVersion:
+                pass
+    return SamePythonVersionResult(
+        is_same=current_version == target_version,
+        current_version=current_version,
+        target_version=target_version,
+    )
+
+
 def install_ui(config: DeploymentConfig, config_parent: Path) -> None:
     if config.ui is None:
         return
     package_manager = config.ui.package_manager
-    run_process(
-        [package_manager, "install"],
-        cwd=config_parent / config.ui.directory,
-        prefix=f"[{package_manager} install]",
-        color_code="33",
-    )
+    try:
+        run_process(
+            [package_manager, "install"],
+            cwd=config_parent / config.ui.directory,
+            prefix=f"[{package_manager} install]",
+            color_code="33",
+            # auto download the package manager
+            env={**os.environ.copy(), "COREPACK_ENABLE_DOWNLOAD_PROMPT": "0"},
+        )
+    except BaseException as e:
+        if "No such file or directory" in str(e):
+            raise RuntimeError(
+                f"Package manager {package_manager} not found. Please download and enable corepack, or install the package manager manually."
+            )
+        raise e
 
 
 def _ui_env(config: DeploymentConfig, settings: ApiserverSettings) -> dict[str, str]:

llama_deploy_appserver-0.3.0a8/src/llama_deploy/appserver/__main__.py

@@ -1,10 +0,0 @@
-import uvicorn
-
-from .settings import settings
-
-if __name__ == "__main__":
-    uvicorn.run(
-        "llama_deploy.appserver.app:app",
-        host=settings.host,
-        port=settings.port,
-    )