llama-deploy-appserver 0.3.0a22__tar.gz → 0.3.0a24__tar.gz

{llama_deploy_appserver-0.3.0a22 → llama_deploy_appserver-0.3.0a24}/PKG-INFO

@@ -1,22 +1,23 @@
 Metadata-Version: 2.3
 Name: llama-deploy-appserver
-Version: 0.3.0a22
+Version: 0.3.0a24
 Summary: Application server components for LlamaDeploy
-Author: Massimiliano Pippi
-Author-email: Massimiliano Pippi <mpippi@gmail.com>
+Author: Massimiliano Pippi, Adrian Lyjak
+Author-email: Massimiliano Pippi <mpippi@gmail.com>, Adrian Lyjak <adrianlyjak@gmail.com>
 License: MIT
-Requires-Dist: llama-index-workflows[server]>=2.0.1
+Requires-Dist: llama-index-workflows[server]>=2.2.0
 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.0a22,<0.4.0
+Requires-Dist: llama-deploy-core>=0.3.0a24,<0.4.0
 Requires-Dist: httpx>=0.24.0,<1.0.0
 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-Dist: pyyaml>=6.0.2
+Requires-Dist: llama-cloud-services>=0.6.60
 Requires-Python: >=3.11, <4
 Description-Content-Type: text/markdown
 

{llama_deploy_appserver-0.3.0a22 → llama_deploy_appserver-0.3.0a24}/pyproject.toml

@@ -1,26 +1,28 @@
 [project]
 name = "llama-deploy-appserver"
-version = "0.3.0a22"
+version = "0.3.0a24"
 description = "Application server components for LlamaDeploy"
 readme = "README.md"
 license = { text = "MIT" }
 authors = [
-    { name = "Massimiliano Pippi", email = "mpippi@gmail.com" }
+    { name = "Massimiliano Pippi", email = "mpippi@gmail.com" },
+    { name = "Adrian Lyjak", email = "adrianlyjak@gmail.com" },
 ]
 requires-python = ">=3.11, <4"
 dependencies = [
-    "llama-index-workflows[server]>=2.0.1",
+    "llama-index-workflows[server]>=2.2.0",
     "pydantic-settings>=2.10.1",
     "uvicorn>=0.24.0",
     "fastapi>=0.100.0",
     "websockets>=12.0",
-    "llama-deploy-core>=0.3.0a22,<0.4.0",
+    "llama-deploy-core>=0.3.0a24,<0.4.0",
     "httpx>=0.24.0,<1.0.0",
     "prometheus-fastapi-instrumentator>=7.1.0",
     "packaging>=25.0",
     "structlog>=25.4.0",
     "rich>=14.1.0",
     "pyyaml>=6.0.2",
+    "llama-cloud-services>=0.6.60",
 ]
 
 [build-system]

{llama_deploy_appserver-0.3.0a22 → llama_deploy_appserver-0.3.0a24}/src/llama_deploy/appserver/app.py

@@ -7,7 +7,7 @@ import webbrowser
 from contextlib import asynccontextmanager
 from importlib.metadata import version
 from pathlib import Path
-from typing import Any, AsyncGenerator, cast
+from typing import Any, AsyncGenerator, Literal, cast
 
 import uvicorn
 from fastapi import FastAPI
@@ -40,7 +40,7 @@ from llama_deploy.appserver.workflow_loader import (
 )
 from llama_deploy.core.config import DEFAULT_DEPLOYMENT_FILE_PATH
 from prometheus_fastapi_instrumentator import Instrumentator
-from starlette.routing import Route
+from starlette.applications import Starlette
 from workflows.server import WorkflowServer
 
 from .deployment import Deployment
@@ -66,19 +66,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, Any]:
     deployment = Deployment(workflows)
     base_router = create_base_router(config.name)
     deploy_router = create_deployments_router(config.name, deployment)
-    server = deployment.create_workflow_server()
-
-    for route in server.app.routes:
-        # add routes directly rather than mounting, so that we can share a root
-        if isinstance(route, Route):
-            app.add_api_route(
-                f"/deployments/{config.name}{route.path}",
-                route.endpoint,
-                name=f"{config.name}_{route.name}",
-                methods=route.methods,
-                include_in_schema=True,  # change to false when schemas are added to workflow server
-                tags=["workflows"],
-            )
+    server = deployment.mount_workflow_server(app)
 
     app.include_router(base_router)
     app.include_router(deploy_router)
@@ -106,7 +94,9 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, Any]:
             return RedirectResponse(f"/deployments/{config.name}/docs")
 
     apiserver_state.state("running")
-    yield
+    # terrible sad cludge
+    async with server._lifespan(cast(Starlette, {})):
+        yield
 
     apiserver_state.state("stopped")
 
@@ -242,6 +232,9 @@ def start_server_in_target_venv(
     ui_port: int | None = None,
     log_level: str | None = None,
     log_format: str | None = None,
+    persistence: Literal["memory", "local", "cloud"] | None = None,
+    local_persistence_path: str | None = None,
+    cloud_persistence_name: str | None = None,
 ) -> None:
     # Ensure settings reflect the intended working directory before computing paths
 
@@ -250,6 +243,9 @@ def start_server_in_target_venv(
         deployment_file_path=deployment_file,
         reload=reload,
         proxy_ui=proxy_ui,
+        persistence=persistence,
+        local_persistence_path=local_persistence_path,
+        cloud_persistence_name=cloud_persistence_name,
     )
     base_dir = cwd or Path.cwd()
     path = settings.resolved_config_parent.relative_to(base_dir)

llama_deploy_appserver-0.3.0a24/src/llama_deploy/appserver/deployment.py

@@ -0,0 +1,153 @@
+import asyncio
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Tuple
+
+from fastapi import FastAPI
+from fastapi.responses import RedirectResponse
+from llama_deploy.appserver.deployment_config_parser import get_deployment_config
+from llama_deploy.appserver.settings import ApiserverSettings, settings
+from llama_deploy.appserver.types import generate_id
+from llama_deploy.appserver.workflow_loader import DEFAULT_SERVICE_ID
+from llama_deploy.appserver.workflow_store.agent_data_store import AgentDataStore
+from llama_deploy.core.deployment_config import DeploymentConfig
+from starlette.routing import Route
+from starlette.staticfiles import StaticFiles
+from workflows import Context, Workflow
+from workflows.handler import WorkflowHandler
+from workflows.server import SqliteWorkflowStore, WorkflowServer
+from workflows.server.abstract_workflow_store import EmptyWorkflowStore
+
+logger = logging.getLogger()
+
+
+class DeploymentError(Exception): ...
+
+
+class Deployment:
+    def __init__(
+        self,
+        workflows: dict[str, Workflow],
+    ) -> None:
+        """Creates a Deployment instance.
+
+        Args:
+            config: The configuration object defining this deployment
+            root_path: The path on the filesystem used to store deployment data
+            local: Whether the deployment is local. If true, sources won't be synced
+        """
+
+        self._default_service: str | None = workflows.get(DEFAULT_SERVICE_ID)
+        self._service_tasks: list[asyncio.Task] = []
+        # Ready to load services
+        self._workflow_services: dict[str, Workflow] = workflows
+        self._contexts: dict[str, Context] = {}
+        self._handlers: dict[str, WorkflowHandler] = {}
+        self._handler_inputs: dict[str, str] = {}
+
+    @property
+    def default_service(self) -> Workflow | None:
+        return self._default_service
+
+    @property
+    def name(self) -> str:
+        """Returns the name of this deployment."""
+        return self._name
+
+    @property
+    def service_names(self) -> list[str]:
+        """Returns the list of service names in this deployment."""
+        return list(self._workflow_services.keys())
+
+    async def run_workflow(
+        self, service_id: str, session_id: str | None = None, **run_kwargs: dict
+    ) -> Any:
+        workflow = self._workflow_services[service_id]
+        if session_id:
+            context = self._contexts[session_id]
+            return await workflow.run(context=context, **run_kwargs)
+
+        if run_kwargs:
+            return await workflow.run(**run_kwargs)
+
+        return await workflow.run()
+
+    def run_workflow_no_wait(
+        self, service_id: str, session_id: str | None = None, **run_kwargs: dict
+    ) -> Tuple[str, str]:
+        workflow = self._workflow_services[service_id]
+        if session_id:
+            context = self._contexts[session_id]
+            handler = workflow.run(context=context, **run_kwargs)
+        else:
+            handler = workflow.run(**run_kwargs)
+            session_id = generate_id()
+            self._contexts[session_id] = handler.ctx or Context(workflow)
+
+        handler_id = generate_id()
+        self._handlers[handler_id] = handler
+        self._handler_inputs[handler_id] = json.dumps(run_kwargs)
+        return handler_id, session_id
+
+    def create_workflow_server(
+        self, deployment_config: DeploymentConfig, settings: ApiserverSettings
+    ) -> WorkflowServer:
+        persistence = EmptyWorkflowStore()
+        if settings.persistence == "local":
+            persistence = SqliteWorkflowStore(
+                settings.local_persistence_path or "workflows.db"
+            )
+        elif settings.persistence == "cloud" or (
+            # default to cloud if api key is present to use
+            settings.persistence is None and os.getenv("LLAMA_DEPLOY_API_KEY")
+        ):
+            persistence = AgentDataStore(deployment_config, settings)
+        server = WorkflowServer(workflow_store=persistence)
+        for service_id, workflow in self._workflow_services.items():
+            server.add_workflow(service_id, workflow)
+        return server
+
+    def mount_workflow_server(self, app: FastAPI) -> WorkflowServer:
+        config = get_deployment_config()
+        server = self.create_workflow_server(config, settings)
+
+        for route in server.app.routes:
+            # add routes directly rather than mounting, so that we can share a root (only one ASGI app can be mounted at a path)
+            if isinstance(route, Route):
+                logger.info(f"Adding route {route.path} to app")
+                app.add_api_route(
+                    f"/deployments/{config.name}{route.path}",
+                    route.endpoint,
+                    name=f"{config.name}_{route.name}",
+                    methods=route.methods,
+                    include_in_schema=True,  # change to false when schemas are added to workflow server
+                    tags=["workflows"],
+                )
+                # kludge, temporarily make it accessible to the debugger, which hard codes
+                app.add_api_route(
+                    f"{route.path}",
+                    route.endpoint,
+                    name=f"_kludge_{config.name}_{route.name}",
+                    methods=route.methods,
+                    include_in_schema=False,
+                )
+
+        # be defensive since this is external and private
+        server_debugger = getattr(server, "_assets_path", None)
+        if isinstance(server_debugger, Path):
+            app.get(f"/deployments/{config.name}/debugger", include_in_schema=False)
+
+            @app.get(f"/deployments/{config.name}/debugger/", include_in_schema=False)
+            def redirect_to_debugger() -> RedirectResponse:
+                return RedirectResponse(
+                    f"/deployments/{config.name}/debugger/index.html"
+                )
+
+            app.mount(
+                f"/deployments/{config.name}/debugger",
+                StaticFiles(directory=server_debugger),
+                name=f"debugger-{config.name}",
+            )
+        return server

{llama_deploy_appserver-0.3.0a22 → llama_deploy_appserver-0.3.0a24}/src/llama_deploy/appserver/settings.py

@@ -1,5 +1,6 @@
 import os
 from pathlib import Path
+from typing import Literal
 
 from llama_deploy.core.config import DEFAULT_DEPLOYMENT_FILE_PATH
 from llama_deploy.core.deployment_config import resolve_config_parent
@@ -73,6 +74,19 @@ class ApiserverSettings(BaseSettings):
         description="If true, reload the workflow modules, for use in a dev server environment",
     )
 
+    persistence: Literal["memory", "local", "cloud"] | None = Field(
+        default=None,
+        description="The persistence mode to use for the workflow server",
+    )
+    local_persistence_path: str | None = Field(
+        default=None,
+        description="The path to the sqlite database to use for the workflow server",
+    )
+    cloud_persistence_name: str | None = Field(
+        default=None,
+        description="Agent Data deployment name to use for workflow persistence. May optionally include a `:` delimited collection name, e.g. 'my_agent:my_collection'. Leave none to use the current deployment name. Recommended to override with _public if running locally, and specify a collection name",
+    )
+
     @property
     def resolved_config_parent(self) -> Path:
         return resolve_config_parent(self.app_root, self.deployment_file_path)
@@ -86,6 +100,9 @@ def configure_settings(
     deployment_file_path: Path | None = None,
     app_root: Path | None = None,
     reload: bool | None = None,
+    persistence: Literal["memory", "local", "cloud"] | None = None,
+    local_persistence_path: str | None = None,
+    cloud_persistence_name: str | None = None,
 ) -> None:
     if proxy_ui is not None:
         settings.proxy_ui = proxy_ui
@@ -101,3 +118,16 @@ def configure_settings(
     if reload is not None:
         settings.reload = reload
         os.environ["LLAMA_DEPLOY_APISERVER_RELOAD"] = "true" if reload else "false"
+    if persistence is not None:
+        settings.persistence = persistence
+        os.environ["LLAMA_DEPLOY_APISERVER_PERSISTENCE"] = persistence
+    if local_persistence_path is not None:
+        settings.local_persistence_path = local_persistence_path
+        os.environ["LLAMA_DEPLOY_APISERVER_LOCAL_PERSISTENCE_PATH"] = (
+            local_persistence_path
+        )
+    if cloud_persistence_name is not None:
+        settings.cloud_persistence_name = cloud_persistence_name
+        os.environ["LLAMA_DEPLOY_APISERVER_CLOUD_PERSISTENCE_NAME"] = (
+            cloud_persistence_name
+        )

llama_deploy_appserver-0.3.0a24/src/llama_deploy/appserver/workflow_store/agent_data_store.py

@@ -0,0 +1,100 @@
+import logging
+import os
+from typing import List
+
+from llama_cloud.client import AsyncLlamaCloud, httpx
+from llama_cloud_services.beta.agent_data import AsyncAgentDataClient
+from llama_deploy.appserver.settings import ApiserverSettings
+from llama_deploy.core.deployment_config import DeploymentConfig
+from typing_extensions import override
+from workflows.server import AbstractWorkflowStore, HandlerQuery, PersistentHandler
+
+from .keyed_lock import AsyncKeyedLock
+from .lru_cache import LRUCache
+
+logger = logging.getLogger(__name__)
+
+
+class AgentDataStore(AbstractWorkflowStore):
+    def __init__(
+        self, settings: DeploymentConfig, server_settings: ApiserverSettings
+    ) -> None:
+        agent_url_id: str | None = server_settings.cloud_persistence_name
+        collection = "workflow_contexts"
+        if agent_url_id is not None:
+            parts = agent_url_id.split(":")
+            if len(parts) > 1:
+                collection = parts[1]
+            agent_url_id = parts[0]
+        else:
+            agent_url_id = settings.name
+
+        self.settings = settings
+        project_id = os.getenv("LLAMA_DEPLOY_PROJECT_ID")
+        self.client = AsyncAgentDataClient(
+            type=PersistentHandler,
+            collection=collection,
+            agent_url_id=agent_url_id,
+            client=AsyncLlamaCloud(
+                base_url=os.getenv("LLAMA_CLOUD_BASE_URL"),
+                token=os.getenv("LLAMA_CLOUD_API_KEY"),
+                httpx_client=httpx.AsyncClient(
+                    headers={"Project-Id": project_id} if project_id else None,
+                ),
+            ),
+        )
+        self.lock = AsyncKeyedLock()
+        # workflow id -> agent data id
+        self.cache = LRUCache[str, str](maxsize=1024)
+
+    @override
+    async def query(self, query: HandlerQuery) -> List[PersistentHandler]:
+        filters = {}
+        if query.handler_id_in is not None:
+            filters["handler_id"] = {
+                "includes": query.handler_id_in,
+            }
+        if query.workflow_name_in is not None:
+            filters["workflow_name"] = {
+                "includes": query.workflow_name_in,
+            }
+        if query.status_in is not None:
+            filters["status"] = {
+                "includes": query.status_in,
+            }
+        results = await self.client.search(
+            filter=filters,
+            page_size=1000,
+        )
+        return [x.data for x in results.items]
+
+    @override
+    async def update(self, handler: PersistentHandler) -> None:
+        async with self.lock.acquire(handler.handler_id):
+            id = await self._get_item_id(handler)
+            if id is None:
+                item = await self.client.create_item(
+                    data=handler,
+                )
+                if item.id is None:
+                    raise ValueError(f"Failed to create handler {handler.handler_id}")
+                self.cache.set(handler.handler_id, item.id)
+            else:
+                await self.client.update_item(
+                    item_id=id,
+                    data=handler,
+                )
+
+    async def _get_item_id(self, handler: PersistentHandler) -> str | None:
+        cached_id = self.cache.get(handler.handler_id, None)
+        if cached_id is not None:
+            return cached_id
+        results = await self.client.search(
+            filter={"handler_id": {"eq": handler.handler_id}},
+            page_size=1,
+        )
+        if not results.items:
+            return None
+        id = results.items[0].id
+        self.cache.set(handler.handler_id, id)
+        return id

llama_deploy_appserver-0.3.0a24/src/llama_deploy/appserver/workflow_store/keyed_lock.py

@@ -0,0 +1,32 @@
+import asyncio
+from collections import Counter
+from contextlib import asynccontextmanager
+
+
+class AsyncKeyedLock:
+    def __init__(self):
+        self._locks: dict[str, asyncio.Lock] = {}
+        self._refcnt = Counter()
+        self._registry_lock = asyncio.Lock()  # protects _locks/_refcnt
+
+    @asynccontextmanager
+    async def acquire(self, key: str):
+        async with self._registry_lock:
+            lock = self._locks.get(key)
+            if lock is None:
+                lock = asyncio.Lock()
+                self._locks[key] = lock
+            self._refcnt[key] += 1
+
+        try:
+            await lock.acquire()
+            try:
+                yield
+            finally:
+                lock.release()
+        finally:
+            async with self._registry_lock:
+                self._refcnt[key] -= 1
+                if self._refcnt[key] == 0:
+                    self._locks.pop(key, None)
+                    del self._refcnt[key]

llama_deploy_appserver-0.3.0a24/src/llama_deploy/appserver/workflow_store/lru_cache.py

@@ -0,0 +1,49 @@
+from collections import OrderedDict
+from typing import Generic, TypeVar, overload
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class LRUCache(Generic[K, V]):
+    def __init__(self, maxsize: int = 128):
+        self.maxsize = maxsize
+        self._store: OrderedDict[K, V] = OrderedDict()
+
+    @overload
+    def get(self, key: K) -> V | None: ...
+
+    @overload
+    def get(self, key: K, default: V) -> V: ...
+
+    def get(self, key: K, default: V | None = None) -> V | None:
+        if key not in self._store:
+            return default
+        # mark as recently used
+        value = self._store.pop(key)
+        self._store[key] = value
+        return value
+
+    def set(self, key: K, value: V):
+        if key in self._store:
+            # remove old so we can push to end
+            self._store.pop(key)
+        elif len(self._store) >= self.maxsize:
+            # evict least recently used (first item)
+            self._store.popitem(last=False)
+        self._store[key] = value
+
+    def __contains__(self, key: K) -> bool:
+        return key in self._store
+
+    def __getitem__(self, key: K) -> V:
+        return self.get(key)
+
+    def __setitem__(self, key: K, value: V):
+        self.set(key, value)
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+    def __iter__(self):
+        return iter(self._store)

llama_deploy_appserver-0.3.0a22/src/llama_deploy/appserver/deployment.py

@@ -1,87 +0,0 @@
-import asyncio
-import json
-import logging
-from typing import Any, Tuple
-
-from llama_deploy.appserver.types import generate_id
-from llama_deploy.appserver.workflow_loader import DEFAULT_SERVICE_ID
-from workflows import Context, Workflow
-from workflows.handler import WorkflowHandler
-from workflows.server import WorkflowServer
-
-logger = logging.getLogger()
-
-
-class DeploymentError(Exception): ...
-
-
-class Deployment:
-    def __init__(
-        self,
-        workflows: dict[str, Workflow],
-    ) -> None:
-        """Creates a Deployment instance.
-
-        Args:
-            config: The configuration object defining this deployment
-            root_path: The path on the filesystem used to store deployment data
-            local: Whether the deployment is local. If true, sources won't be synced
-        """
-
-        self._default_service: str | None = workflows.get(DEFAULT_SERVICE_ID)
-        self._service_tasks: list[asyncio.Task] = []
-        # Ready to load services
-        self._workflow_services: dict[str, Workflow] = workflows
-        self._contexts: dict[str, Context] = {}
-        self._handlers: dict[str, WorkflowHandler] = {}
-        self._handler_inputs: dict[str, str] = {}
-
-    @property
-    def default_service(self) -> Workflow | None:
-        return self._default_service
-
-    @property
-    def name(self) -> str:
-        """Returns the name of this deployment."""
-        return self._name
-
-    @property
-    def service_names(self) -> list[str]:
-        """Returns the list of service names in this deployment."""
-        return list(self._workflow_services.keys())
-
-    async def run_workflow(
-        self, service_id: str, session_id: str | None = None, **run_kwargs: dict
-    ) -> Any:
-        workflow = self._workflow_services[service_id]
-        if session_id:
-            context = self._contexts[session_id]
-            return await workflow.run(context=context, **run_kwargs)
-
-        if run_kwargs:
-            return await workflow.run(**run_kwargs)
-
-        return await workflow.run()
-
-    def run_workflow_no_wait(
-        self, service_id: str, session_id: str | None = None, **run_kwargs: dict
-    ) -> Tuple[str, str]:
-        workflow = self._workflow_services[service_id]
-        if session_id:
-            context = self._contexts[session_id]
-            handler = workflow.run(context=context, **run_kwargs)
-        else:
-            handler = workflow.run(**run_kwargs)
-            session_id = generate_id()
-            self._contexts[session_id] = handler.ctx or Context(workflow)
-
-        handler_id = generate_id()
-        self._handlers[handler_id] = handler
-        self._handler_inputs[handler_id] = json.dumps(run_kwargs)
-        return handler_id, session_id
-
-    def create_workflow_server(self) -> WorkflowServer:
-        server = WorkflowServer()
-        for service_id, workflow in self._workflow_services.items():
-            server.add_workflow(service_id, workflow)
-        return server