beamlit 0.0.51__py3-none-any.whl → 0.0.53__py3-none-any.whl

beamlit/deploy/deploy.py

@@ -1,3 +1,9 @@
+"""
+This module provides functionalities to generate and manage Beamlit deployment configurations.
+It includes functions to set default deployment values, create deployment configurations from resources,
+format deployments, and clean up auto-generated deployments.
+"""
+
 import ast
 import json
 import os
@@ -31,6 +37,16 @@ sys.path.insert(0, os.getcwd())
 sys.path.insert(0, os.path.join(os.getcwd(), "src"))
 
 def set_default_values(resource: Resource, deployment: Agent | Function):
+    """
+    Sets default values for a deployment based on the resource and deployment type.
+
+    Parameters:
+        resource (Resource): The resource information.
+        deployment (Agent | Function): The deployment instance to set defaults for.
+
+    Returns:
+        Agent | Function: The updated deployment with default values set.
+    """
     settings = get_settings()
     deployment.metadata.workspace = settings.workspace
     deployment.metadata.environment = settings.environment
@@ -46,13 +62,13 @@ def get_beamlit_deployment_from_resource(
     resource: Resource,
 ) -> Agent | Function:
     """
-    Creates a deployment configuration from a resource.
+    Creates a deployment configuration from a given resource.
 
     Args:
-        resource (Resource): The resource to create a deployment for
+        resource (Resource): The resource to create a deployment for.
 
     Returns:
-        Agent | Function: The deployment configuration
+        Agent | Function: The deployment configuration.
     """
     for arg in resource.decorator.keywords:
         if arg.arg == "agent":
@@ -80,16 +96,15 @@ def get_beamlit_deployment_from_resource(
         return set_default_values(resource, func)
     return None
 
-
 def get_flavors(flavors: list[Flavor]) -> str:
     """
-    Converts a list of Flavor objects to JSON string.
+    Converts a list of Flavor objects to a JSON string.
 
     Args:
-        flavors (list[Flavor]): List of Flavor objects
+        flavors (list[Flavor]): List of Flavor objects.
 
     Returns:
-        str: JSON string representation of flavors
+        str: JSON string representation of flavors.
     """
     if not flavors:
         return "[]"
@@ -176,7 +191,7 @@ def dockerfile(
 FROM python:3.12-slim
 
 ARG UV_VERSION="latest"
-RUN apt update && apt install -y curl
+RUN apt update && apt install -y curl build-essential
 
 # Install uv.
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
@@ -207,9 +222,9 @@ def clean_auto_generated(
     Cleans up auto-generated deployments of a specific type.
 
     Args:
-        directory (str): Base directory containing deployments
-        type (str): Type of deployment ("agent" or "function")
-        deployments (list[tuple[Resource, Agent | Function]]): List of deployment resources and configurations
+        directory (str): Base directory containing deployments.
+        type (Literal["agent", "function"]): Type of deployment to clean ("agent" or "function").
+        deployments (list[tuple[Resource, Agent | Function]]): List of deployment resources and configurations.
     """
 
     deploy_dir = Path(directory) / f"{type}s"
@@ -233,12 +248,13 @@ def generate_beamlit_deployment(directory: str, name: str):
     Generates all necessary deployment files for Beamlit agents and functions.
 
     Args:
-        directory (str): Target directory for generated files
+        directory (str): Target directory for generated files.
+        name (str): Name identifier for the deployment.
 
     Creates:
-        - Agent and function YAML configurations
-        - Dockerfiles for each deployment
-        - Directory structure for agents and functions
+        - Agent and function YAML configurations.
+        - Dockerfiles for each deployment.
+        - Directory structure for agents and functions.
     """
     settings = init()
     client = new_client()

beamlit/deploy/format.py

@@ -1,3 +1,7 @@
+"""
+This module provides utility functions to format deployment configurations into YAML-compatible strings.
+It includes functions to convert arguments, parameters, dictionaries, and agent chains into properly formatted JSON or YAML strings.
+"""
 
 import ast
 
@@ -11,6 +15,15 @@ def arg_to_list(arg: ast.List):
     return value
 
 def format_value(v):
+    """
+    Formats an AST node value into its Python equivalent.
+
+    Args:
+        v (ast.AST): The AST node to format.
+
+    Returns:
+        Any: The formatted Python value.
+    """
     if isinstance(v, ast.Constant):
         return v.value
     elif isinstance(v, ast.Dict):
@@ -19,6 +32,15 @@ def format_value(v):
         return arg_to_list(v)
 
 def arg_to_dict(arg: ast.keyword):
+    """
+    Converts an AST keyword argument to a dictionary.
+
+    Args:
+        arg (ast.keyword): The AST keyword argument.
+
+    Returns:
+        dict: The resulting dictionary.
+    """
     value = {}
     for k, v in zip(arg.keys, arg.values):
         if isinstance(k, ast.Constant):
@@ -27,13 +49,13 @@ def arg_to_dict(arg: ast.keyword):
 
 def format_parameters(parameters: list[StoreFunctionParameter]) -> str:
     """
-    Formats function parameters into YAML-compatible string.
+    Formats function parameters into a YAML-compatible string.
 
     Args:
-        parameters (list[StoreFunctionParameter]): List of parameter objects
+        parameters (list[StoreFunctionParameter]): List of parameter objects.
 
     Returns:
-        str: YAML-formatted string of parameters
+        str: YAML-formatted string of parameters.
     """
     if not parameters:
         return "[]"
@@ -49,6 +71,15 @@ def format_parameters(parameters: list[StoreFunctionParameter]) -> str:
     return "\n".join(formatted)
 
 def format_dict(obj: dict) -> str:
+    """
+    Converts a dictionary to a YAML-compatible string.
+
+    Args:
+        obj (dict): The dictionary to format.
+
+    Returns:
+        str: YAML-formatted string representation of the dictionary.
+    """
     if not obj:
         return "null"
     ret = ""
@@ -61,13 +92,13 @@ def format_dict(obj: dict) -> str:
 
 def format_agent_chain(agentChain: list[AgentChain]) -> str:
     """
-    Formats agent chain configuration into YAML-compatible string.
+    Formats agent chain configuration into a YAML-compatible string.
 
     Args:
-        agentChain (list[AgentChain]): List of agent chain configurations
+        agentChain (list[AgentChain]): List of agent chain configurations.
 
     Returns:
-        str: YAML-formatted string of agent chain
+        str: YAML-formatted string of agent chain.
     """
     if not agentChain:
         return "[]"
@@ -75,8 +106,8 @@ def format_agent_chain(agentChain: list[AgentChain]) -> str:
 
     for agent in agentChain:
         formatted.append(f"""
-      - agent: {agent.name}
-        enabled: {agent.enabled}""")
+  - agent: {agent.name}
+    enabled: {agent.enabled}""")
         if agent.description:
             formatted.append(f"        description: {agent.description}")
     return "\n".join(formatted)

beamlit/deploy/parser.py

@@ -1,3 +1,9 @@
+"""
+This module provides classes and functions for parsing deployment resources within Beamlit.
+It includes the Resource dataclass for representing deployment resources and functions to extract and process resources
+decorated within Python files.
+"""
+
 import ast
 import importlib
 import os
@@ -10,6 +16,16 @@ from beamlit.models import StoreFunctionParameter
 
 @dataclass
 class Resource:
+    """
+    A dataclass representing a deployment resource.
+
+    Attributes:
+        type (Literal["agent", "function"]): The type of deployment ("agent" or "function").
+        module (Callable): The module containing the deployment.
+        name (str): The name of the deployment.
+        decorator (ast.Call): The decorator AST node used on the deployment function.
+        func (Callable): The deployment function.
+    """
     type: Literal["agent", "function"]
     module: Callable
     name: str

beamlit/functions/__init__.py

@@ -1,4 +1,5 @@
-"""Functions package providing function decorators and utilities."""
+"""Functions package providing function decorators and utilities for Beamlit integration.
+It includes decorators for creating function tools and utilities for managing and retrieving functions."""
 
 from .common import get_functions
 from .decorator import function, kit

beamlit/functions/common.py

@@ -1,4 +1,18 @@
-"""Decorators for creating function tools with Beamlit and LangChain integration."""
+"""Decorators for creating function tools with Beamlit and LangChain integration.
+
+This module provides functionality to discover and load function tools from Python files,
+supporting both local and remote function execution.
+
+Key Features:
+- Automatic function discovery in specified directories
+- Support for both synchronous and asynchronous functions
+- Integration with LangChain's StructuredTool system
+- Remote function toolkit handling
+- Chain toolkit integration
+
+Main Components:
+- get_functions(): Core function that discovers and loads function tools
+"""
 import ast
 import asyncio
 import importlib.util
@@ -20,14 +34,49 @@ from beamlit.models import AgentChain
 logger = getLogger(__name__)
 
 def get_functions(
-    remote_functions:Union[list[str], None]=None,
-    client:Union[AuthenticatedClient, None]=None,
-    dir:Union[str, None]=None,
-    chain:Union[list[AgentChain], None]=None,
-    remote_functions_empty:bool=True,
-    from_decorator:str="function",
-    warning:bool=True,
+    remote_functions: Union[list[str], None] = None,
+    client: Union[AuthenticatedClient, None] = None,
+    dir: Union[str, None] = None,
+    chain: Union[list[AgentChain], None] = None,
+    remote_functions_empty: bool = True,
+    from_decorator: str = "function",
+    warning: bool = True,
 ):
+    """Discovers and loads function tools from Python files and remote sources.
+
+    This function walks through Python files in a specified directory, looking for
+    decorated functions to convert into LangChain tools. It also handles remote
+    functions and chain toolkits.
+
+    Args:
+        remote_functions (Union[list[str], None]): List of remote function names to load
+        client (Union[AuthenticatedClient, None]): Authenticated client instance for API calls
+        dir (Union[str, None]): Directory to search for Python files containing functions
+        chain (Union[list[AgentChain], None]): List of agent chains to include
+        remote_functions_empty (bool): Whether to allow empty remote functions
+        from_decorator (str): Name of the decorator to look for (default: "function")
+        warning (bool): Whether to show warning messages
+
+    Returns:
+        list: List of discovered and loaded function tools
+
+    The function performs the following steps:
+    1. Walks through Python files in the specified directory
+    2. Parses each file to find decorated functions
+    3. Converts found functions into LangChain StructuredTools
+    4. Handles both synchronous and asynchronous functions
+    5. Processes remote functions if specified
+    6. Integrates chain toolkits if provided
+
+    Example:
+        ```python
+        tools = get_functions(
+            dir="./functions",
+            from_decorator="function",
+            warning=True
+        )
+        ```
+    """
     from beamlit.agents.chain import ChainToolkit
 
     settings = get_settings()

beamlit/functions/decorator.py

@@ -11,7 +11,16 @@ from beamlit.models import Function, FunctionKit
 logger = getLogger(__name__)
 
 def kit(bl_kit: FunctionKit = None, **kwargs: dict) -> Callable:
-    """Create function tools with Beamlit and LangChain integration."""
+    """
+    Decorator to create function tools with Beamlit and LangChain integration.
+
+    Args:
+        bl_kit (FunctionKit | None): Optional FunctionKit to associate with the function.
+        **kwargs (dict): Additional keyword arguments for function configuration.
+
+    Returns:
+        Callable: The decorated function.
+    """
 
     def wrapper(func: Callable) -> Callable:
         if bl_kit and not func.__doc__ and bl_kit.description:
@@ -22,7 +31,17 @@ def kit(bl_kit: FunctionKit = None, **kwargs: dict) -> Callable:
 
 
 def function(*args, function: Function | dict = None, kit=False, **kwargs: dict) -> Callable:
-    """Create function tools with Beamlit and LangChain integration."""
+    """
+    Decorator to create function tools with Beamlit and LangChain integration.
+
+    Args:
+        function (Function | dict): Function metadata or a dictionary representing it.
+        kit (bool): Whether to associate a function kit.
+        **kwargs (dict): Additional keyword arguments for function configuration.
+
+    Returns:
+        Callable: The decorated function.
+    """
     if function is not None and not isinstance(function, dict):
         raise Exception(
             'function must be a dictionary, example: @function(function={"metadata": {"name": "my_function"}})'

beamlit/functions/mcp/mcp.py

@@ -1,3 +1,8 @@
+"""
+This module provides functionalities to interact with MCP (Multi-Client Platform) servers.
+It includes classes for managing MCP clients, creating dynamic schemas, and integrating MCP tools into Beamlit.
+"""
+
 import asyncio
 import warnings
 from typing import Any, Callable
@@ -87,7 +92,11 @@ class MCPClient:
 
 class MCPTool(BaseTool):
     """
-    MCP server tool
+    Tool for interacting with MCP server-hosted tools.
+
+    Attributes:
+        client (MCPClient): The MCP client instance.
+        handle_tool_error (bool | str | Callable[[ToolException], str] | None): Error handling strategy.
     """
 
     client: MCPClient
@@ -119,7 +128,11 @@ class MCPTool(BaseTool):
 
 class MCPToolkit(BaseToolkit):
     """
-    MCP server toolkit
+    Toolkit for managing MCP server tools.
+
+    Attributes:
+        client (MCPClient): The MCP client instance.
+        _tools (ListToolsResult | None): Cached list of tools from the MCP server.
     """
 
     client: MCPClient

beamlit/functions/remote/remote.py

@@ -1,3 +1,8 @@
+"""
+This module provides functionalities to integrate remote functions into Beamlit.
+It includes classes for creating dynamic schemas based on function parameters and managing remote toolkits.
+"""
+
 import asyncio
 import warnings
 from dataclasses import dataclass
@@ -17,6 +22,16 @@ from beamlit.run import RunClient
 
 
 def create_dynamic_schema(name: str, parameters: list[StoreFunctionParameter]) -> type[pydantic.BaseModel]:
+    """
+    Creates a dynamic Pydantic schema based on function parameters.
+
+    Args:
+        name (str): The name of the schema.
+        parameters (list[StoreFunctionParameter]): List of parameter objects.
+
+    Returns:
+        type[pydantic.BaseModel]: The dynamically created Pydantic model.
+    """
     field_definitions = {}
     for param in parameters:
         field_type = str
@@ -39,7 +54,13 @@ def create_dynamic_schema(name: str, parameters: list[StoreFunctionParameter]) -
 
 class RemoteTool(BaseTool):
     """
-    Remote tool
+    Tool for interacting with remote functions.
+
+    Attributes:
+        client (RunClient): The client used to execute remote function calls.
+        resource_name (str): The name of the remote resource.
+        kit (bool): Indicates whether the tool is part of a function kit.
+        handle_tool_error (bool | str | Callable[[ToolException], str] | None): Error handling strategy.
     """
 
     client: RunClient
@@ -79,7 +100,12 @@ class RemoteTool(BaseTool):
 @dataclass
 class RemoteToolkit:
     """
-    Remote toolkit
+    Toolkit for managing remote function tools.
+
+    Attributes:
+        client (AuthenticatedClient): The authenticated client instance.
+        function (str): The name of the remote function to integrate.
+        _function (Function | None): Cached Function object after initialization.
     """
     client: AuthenticatedClient
     function: str
@@ -87,7 +113,7 @@ class RemoteToolkit:
     model_config = pydantic.ConfigDict(arbitrary_types_allowed=True)
 
     def initialize(self) -> None:
-        """Initialize the session and retrieve tools list"""
+        """Initialize the session and retrieve the remote function details."""
         if self._function is None:
             try:
                 response = get_function.sync_detailed(self.function, client=self.client)
@@ -106,7 +132,6 @@ class RemoteToolkit:
                     f"error: {e.status_code}. Available functions: {', '.join(names)}"
                 )
 
-    @t.override
     def get_tools(self) -> list[BaseTool]:
         settings = get_settings()
         if self._function is None:

beamlit/run.py

@@ -1,3 +1,6 @@
+"""
+This module provides functionality for executing HTTP requests against Beamlit resources.
+"""
 import urllib.parse
 from typing import Any
 
@@ -8,6 +11,29 @@ from beamlit.common import HTTPError, get_settings
 
 
 class RunClient:
+    """Provides functionality for executing HTTP requests against Beamlit resources.
+
+    This module contains the RunClient class which handles authenticated HTTP requests to Beamlit
+    resources. It allows users to interact with different resource types (like functions or services)
+    in specific environments, supporting various HTTP methods and request parameters.
+
+    Example:
+        ```python
+        client = new_client()
+        run_client = RunClient(client)
+        response = run_client.run(
+            resource_type="function",
+            resource_name="my-function",
+            environment="prod",
+            method="POST",
+            json={"key": "value"}
+        )
+        ```
+
+    Args:
+        client (AuthenticatedClient): An authenticated client instance for making HTTP requests.
+    """
+
     def __init__(self, client: AuthenticatedClient):
         self.client = client
 
@@ -23,6 +49,25 @@ class RunClient:
         data: str | None = None,
         params: dict[str, str] | None = None,
     ) -> requests.Response:
+        """Execute an HTTP request against a Beamlit resource.
+
+        Args:
+            resource_type (str): The type of resource to interact with (e.g., 'function', 'service').
+            resource_name (str): The name of the specific resource.
+            environment (str): The environment to execute the request in.
+            method (str): The HTTP method to use (e.g., 'GET', 'POST', 'PUT', 'DELETE').
+            path (str, optional): Additional path segments to append to the resource URL. Defaults to "".
+            headers (dict[str, str] | None, optional): HTTP headers to include in the request. Defaults to None.
+            json (dict[str, Any] | None, optional): JSON payload to send with the request. Defaults to None.
+            data (str | None, optional): Raw data to send with the request. Defaults to None.
+            params (dict[str, str] | None, optional): Query parameters to include in the URL. Defaults to None.
+
+        Returns:
+            requests.Response: The HTTP response from the server.
+
+        Raises:
+            HTTPError: If the server responds with a status code >= 400.
+        """
         settings = get_settings()
         headers = headers or {}
         params = params or {}

beamlit/serve/app.py

@@ -1,9 +1,15 @@
+"""Module: app
+
+This module sets up and runs the Beamlit server using FastAPI.
+It configures middleware, handles server lifespan events, and defines endpoints.
+"""
+
 import asyncio
 import importlib
+import inspect
 import os
 import sys
 import traceback
-import inspect
 from contextlib import asynccontextmanager
 from logging import getLogger
 from uuid import uuid4
@@ -13,10 +19,7 @@ from fastapi import FastAPI, Request, Response, WebSocket
 from fastapi.responses import JSONResponse
 
 from beamlit.common import HTTPError, get_settings, init
-from beamlit.common.instrumentation import (
-    instrument_app,
-    shutdown_instrumentation,
-)
+from beamlit.common.instrumentation import instrument_app, shutdown_instrumentation
 
 from .middlewares import AccessLogMiddleware, AddProcessTimeHeader
 
@@ -25,6 +28,11 @@ sys.path.insert(0, os.path.join(os.getcwd(), "src"))
 
 
 def import_module():
+    """Dynamically imports the main server module based on settings.
+
+    Returns:
+        Callable: The main function to run the server.
+    """
     settings = get_settings()
     main_module = importlib.import_module(".".join(settings.server.module.split(".")[0:-1]))
     func = getattr(main_module, settings.server.module.split(".")[-1])
@@ -46,6 +54,11 @@ if "websocket" in func_params:
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
+    """Manages the lifespan events of the FastAPI application.
+
+    Args:
+        app (FastAPI): The FastAPI application instance.
+    """
     yield
     shutdown_instrumentation()
 
@@ -62,6 +75,11 @@ instrument_app(app)
 
 @app.get("/health")
 async def health():
+    """Health check endpoint.
+
+    Returns:
+        dict: A simple status message indicating the server is running.
+    """
     return {"status": "ok"}
 
 if websocket_detected:

beamlit/serve/middlewares/__init__.py

@@ -1,3 +1,9 @@
+"""Package: middlewares
+
+This package contains custom middleware classes for the Beamlit server,
+including access logging and process time header addition.
+"""
+
 from .accesslog import AccessLogMiddleware
 from .processtime import AddProcessTimeHeader
 

beamlit/serve/middlewares/accesslog.py

@@ -1,10 +1,26 @@
+"""Module: accesslog
+
+Defines the AccessLogMiddleware for logging HTTP requests and responses.
+"""
+
 from logging import getLogger
 
 from starlette.middleware.base import BaseHTTPMiddleware
 
 
 class AccessLogMiddleware(BaseHTTPMiddleware):
+    """Middleware for logging access information of each HTTP request."""
+
     async def dispatch(self, request, call_next):
+        """Processes each request to log access details.
+
+        Args:
+            request (Request): The incoming HTTP request.
+            call_next (Callable): The next middleware or endpoint handler.
+
+        Returns:
+            Response: The HTTP response generated by the next handler.
+        """
         logger = getLogger(__name__)
         response = await call_next(request)
         process_time = response.headers.get("X-Process-Time")

beamlit/serve/middlewares/processtime.py

@@ -1,10 +1,26 @@
+"""Module: processtime
+
+Defines the AddProcessTimeHeader middleware for adding process time information to responses.
+"""
+
 import time
 
 from starlette.middleware.base import BaseHTTPMiddleware
 
 
 class AddProcessTimeHeader(BaseHTTPMiddleware):
+    """Middleware to add the X-Process-Time header to each HTTP response."""
+
     async def dispatch(self, request, call_next):
+        """Calculates and adds the processing time to the response headers.
+
+        Args:
+            request (Request): The incoming HTTP request.
+            call_next (Callable): The next middleware or endpoint handler.
+
+        Returns:
+            Response: The HTTP response with the X-Process-Time header added.
+        """
         start_time = time.perf_counter()
         response = await call_next(request)
         process_time = (time.perf_counter() - start_time) * 1000

{beamlit-0.0.51.dist-info → beamlit-0.0.53.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beamlit
-Version: 0.0.51
+Version: 0.0.53
 Summary: Add your description here
 Author-email: cploujoux <ch.ploujoux@gmail.com>
 License-File: LICENSE