langgraph-agent-toolkit 0.1.0__py3-none-any.whl

langgraph_agent_toolkit/service/exception_handlers.py

@@ -0,0 +1,46 @@
+import traceback
+
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+
+from langgraph_agent_toolkit.helper.logging import logger
+
+
+async def handle_value_error(request: Request, exc: ValueError) -> JSONResponse:
+    """Handle ValueError exceptions."""
+    logger.error(f"ValueError: {exc}")
+    return JSONResponse(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        content={"detail": str(exc)},
+    )
+
+
+async def handle_message_conversion_error(request: Request, exc: Exception) -> JSONResponse:
+    """Handle errors when converting between message types."""
+    if isinstance(exc, ValueError) and "Unsupported message type" in str(exc):
+        logger.error(f"Message conversion error: {exc}")
+        return JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content={"detail": str(exc)},
+        )
+
+    raise exc
+
+
+async def handle_unexpected_error(request: Request, exc: Exception) -> JSONResponse:
+    """Handle unexpected exceptions."""
+    error_detail = f"{exc.__class__.__name__}: {exc}"
+    logger.error(f"Unexpected error: {error_detail}")
+    logger.error(traceback.format_exc())
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={"detail": f"An unexpected error occurred: {str(exc)}"},
+    )
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """Register all exception handlers to the FastAPI app."""
+    app.exception_handler(ValueError)(handle_value_error)
+    app.exception_handler(Exception)(handle_unexpected_error)
+    # Register the message conversion error handler
+    app.add_exception_handler(ValueError, handle_message_conversion_error)

langgraph_agent_toolkit/service/factory.py

@@ -0,0 +1,213 @@
+import asyncio
+import json
+import os
+import sys
+from typing import Any, Dict, Optional
+
+import uvicorn
+from fastapi import FastAPI
+
+from langgraph_agent_toolkit.core import settings as base_settings
+from langgraph_agent_toolkit.helper.logging import logger
+from langgraph_agent_toolkit.service.handler import create_app
+from langgraph_agent_toolkit.service.types import RunnerType
+from langgraph_agent_toolkit.service.utils import setup_logging
+
+
+class ServiceRunner:
+    """A factory class to run the API service in different ways.
+
+    This class provides methods to run the service with different runners:
+    - With Uvicorn
+    - With Gunicorn
+    - With Mangum (AWS Lambda)
+    - With Azure Functions
+    """
+
+    def __init__(self, custom_settings: Optional[Dict[str, Any]] = None):
+        """Initialize the ServiceRunner.
+
+        Args:
+            custom_settings: Optional dictionary of settings to override the default settings.
+
+        """
+        _ = setup_logging()
+
+        # Override global settings if provided
+        if custom_settings:
+            for key, value in custom_settings.items():
+                if hasattr(base_settings, key):
+                    # Set the value in the global settings object
+                    setattr(base_settings, key, value)
+                    logger.info(f"Overriding setting {key}")
+
+                    # Also set it as an environment variable for child processes
+                    # Handle different types appropriately for environment variables
+                    env_value = None
+                    if isinstance(value, list):
+                        # Convert lists to JSON strings
+                        env_value = json.dumps(value)
+                    elif isinstance(value, bool):
+                        # Convert booleans to string "True" or "False"
+                        env_value = str(value)
+                    elif value is not None:
+                        # Convert other values to strings
+                        env_value = str(value)
+
+                    if env_value is not None:
+                        os.environ[f"LANGGRAPH_{key}"] = env_value
+                        logger.info(f"Set environment variable LANGGRAPH_{key}={env_value}")
+                else:
+                    logger.warning(f"Setting {key} not found in settings")
+
+        self.app = create_app()
+
+    def run_uvicorn(self):
+        """Run the API service with uvicorn."""
+        # Set Compatible event loop policy on Windows Systems.
+        if sys.platform == "win32":
+            asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+        # In development mode with reload=True, we need to use an import string
+        # instead of passing the app instance directly
+        if base_settings.is_dev():
+            logger.info("Starting in development mode with hot reload enabled")
+            uvicorn.run(
+                "langgraph_agent_toolkit.service.handler:create_app",
+                host=base_settings.HOST,
+                port=base_settings.PORT,
+                reload=True,
+                factory=True,
+            )
+        else:
+            # In production mode, use the app instance directly
+            uvicorn.run(
+                self.app,
+                host=base_settings.HOST,
+                port=base_settings.PORT,
+                reload=False,
+            )
+
+    def run_gunicorn(self, workers: int = 4):
+        """Run the API service with gunicorn.
+
+        Args:
+            workers: Number of worker processes.
+
+        """
+        try:
+            from gunicorn.app.base import BaseApplication
+
+            class GunicornApp(BaseApplication):
+                def __init__(self, app, options=None):
+                    self.options = options or {}
+                    self.application = app
+                    super().__init__()
+
+                def load_config(self):
+                    for key, value in self.options.items():
+                        self.cfg.set(key, value)
+
+                def load(self):
+                    return self.application
+
+            options = {
+                "bind": f"{base_settings.HOST}:{base_settings.PORT}",
+                "workers": workers,
+                "worker_class": "uvicorn.workers.UvicornWorker",
+            }
+
+            GunicornApp(self.app, options).run()
+        except ImportError:
+            logger.error("Gunicorn not installed. Install it with 'pip install gunicorn'")
+            sys.exit(1)
+
+    def run_aws_lambda(self):
+        """Prepare the API service for AWS Lambda."""
+        try:
+            from mangum import Mangum
+
+            return Mangum(self.app)
+        except ImportError:
+            logger.error("Mangum not installed. Install it with 'pip install mangum'")
+            sys.exit(1)
+
+    def run_azure_functions(self):
+        """Prepare the API service for Azure Functions."""
+        try:
+            import azure.functions as func
+
+            async def main(req: func.HttpRequest) -> func.HttpResponse:
+                # Process the request through ASGI app
+                return await self._handle_azure_request(self.app, req)
+
+            return main
+        except ImportError:
+            logger.error("Azure Functions package not installed. Install with 'pip install azure-functions'")
+            sys.exit(1)
+
+    @staticmethod
+    async def _handle_azure_request(app: FastAPI, req: "func.HttpRequest") -> "func.HttpResponse":
+        """Handle Azure Functions HTTP request."""
+        import azure.functions as func
+
+        # Convert request to ASGI format
+        scope = {
+            "type": "http",
+            "http_version": "1.1",
+            "method": req.method,
+            "path": req.url.path,
+            "query_string": req.url.query.encode(),
+            "headers": [(k.encode(), v.encode()) for k, v in req.headers.items()],
+        }
+
+        # Create response container
+        response_body = []
+        response_status = None
+        response_headers = []
+
+        async def receive():
+            return {"type": "http.request", "body": req.get_body() or b""}
+
+        async def send(message):
+            nonlocal response_status, response_headers
+
+            if message["type"] == "http.response.start":
+                response_status = message["status"]
+                response_headers = message["headers"]
+            elif message["type"] == "http.response.body":
+                response_body.append(message["body"])
+
+        # Process the request through ASGI app
+        await app(scope, receive, send)
+
+        # Build Azure Functions response
+        headers = {k.decode(): v.decode() for k, v in response_headers}
+        body = b"".join(response_body)
+
+        return func.HttpResponse(
+            body=body,
+            status_code=response_status,
+            headers=headers,
+        )
+
+    def run(self, runner_type: RunnerType = RunnerType.UVICORN, **kwargs):
+        """Run the API service with the specified runner type.
+
+        Args:
+            runner_type: The type of runner to use.
+            **kwargs: Additional arguments to pass to the runner.
+
+        """
+        match runner_type:
+            case RunnerType.UVICORN:
+                self.run_uvicorn()
+            case RunnerType.GUNICORN:
+                workers = kwargs.get("workers", 4)
+                self.run_gunicorn(workers=workers)
+            case RunnerType.AWS_LAMBDA:
+                return self.run_aws_lambda()
+            case RunnerType.AZURE_FUNCTIONS:
+                return self.run_azure_functions()
+            case _:
+                raise ValueError(f"Unknown runner type: {runner_type}")

langgraph_agent_toolkit/service/handler.py

@@ -0,0 +1,122 @@
+import warnings
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI
+from langchain_core._api import LangChainBetaWarning
+
+from langgraph_agent_toolkit import __version__
+from langgraph_agent_toolkit.agents.agent_executor import AgentExecutor
+from langgraph_agent_toolkit.core.memory.factory import MemoryFactory
+from langgraph_agent_toolkit.core.observability.empty import EmptyObservability
+from langgraph_agent_toolkit.core.observability.factory import ObservabilityFactory
+from langgraph_agent_toolkit.core.observability.types import ObservabilityBackend
+from langgraph_agent_toolkit.core.settings import settings
+from langgraph_agent_toolkit.helper.logging import logger
+from langgraph_agent_toolkit.service.exception_handlers import register_exception_handlers
+from langgraph_agent_toolkit.service.middleware import LoggingMiddleware
+from langgraph_agent_toolkit.service.routes import private_router, public_router
+from langgraph_agent_toolkit.service.utils import verify_bearer
+
+
+warnings.filterwarnings("ignore", category=LangChainBetaWarning)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Create a lifespan context manager for the FastAPI app."""
+    observability = None
+    initialized_agents = []
+
+    try:
+        # Initialize observability platform
+        try:
+            observability = ObservabilityFactory.create(settings.OBSERVABILITY_BACKEND or ObservabilityBackend.EMPTY)
+            logger.info(f"Initialized observability backend: {settings.OBSERVABILITY_BACKEND}")
+        except Exception as e:
+            logger.error(f"Failed to initialize observability backend: {e}")
+            observability = EmptyObservability()
+
+        # Initialize memory backend
+        try:
+            memory_backend = MemoryFactory.create(settings.MEMORY_BACKEND)
+            logger.info(f"Initialized memory backend: {settings.MEMORY_BACKEND}")
+        except Exception as e:
+            logger.error(f"Failed to initialize memory backend: {e}")
+            yield
+            return
+
+        # Initialize agent executor
+        try:
+            executor = AgentExecutor(*settings.AGENT_PATHS)
+            logger.info(f"Initialized AgentExecutor: {settings.AGENT_PATHS}")
+            # Store the executor in app.state for access in routes
+            app.state.agent_executor = executor
+        except Exception as e:
+            logger.error(f"Failed to initialize AgentExecutor: {e}")
+            yield
+            return
+
+        checkpoint = memory_backend.get_checkpoint_saver()
+        async with checkpoint as saver:
+            try:
+                await saver.setup()
+                agents = executor.get_all_agent_info()
+
+                if not agents:
+                    logger.warning("No agents found in the executor.")
+
+                for a in agents:
+                    try:
+                        agent = executor.get_agent(a.key)
+                        agent.graph.checkpointer = saver
+
+                        # do not set up observability if it's already set
+                        if not agent.observability:
+                            agent.observability = observability
+
+                        initialized_agents.append(a.key)
+                        logger.info(f"Successfully initialized agent: {a.key}")
+                    except Exception as e:
+                        logger.error(f"Error setting up agent {a.key}: {e}")
+
+                if initialized_agents:
+                    logger.info(f"Successfully initialized {len(initialized_agents)} agents")
+                else:
+                    logger.warning("No agents were successfully initialized")
+
+                yield
+            except Exception as e:
+                logger.error(f"Error during database setup: {e}")
+                yield
+    except Exception as e:
+        logger.error(f"Error during initialization: {e}")
+        yield
+    finally:
+        if observability:
+            try:
+                logger.info("Closing observability platform...")
+                observability.before_shutdown()
+            except Exception as e:
+                logger.error(f"Error closing observability: {e}")
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    logger.info(f"Initializing API service v{__version__}")
+
+    app = FastAPI(lifespan=lifespan)
+
+    # add middleware
+    app.add_middleware(LoggingMiddleware)
+
+    # Register exception handlers
+    register_exception_handlers(app)
+
+    # Include public router without authentication
+    app.include_router(public_router)
+
+    # Include private router with authentication
+    app.include_router(private_router, dependencies=[Depends(verify_bearer)])
+
+    return app

langgraph_agent_toolkit/service/middleware.py

@@ -0,0 +1,18 @@
+from http.client import responses
+
+from fastapi import Request
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from langgraph_agent_toolkit.helper.logging import logger
+
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    """Middleware to log incoming requests and outgoing responses."""
+
+    async def dispatch(self, request: Request, call_next):
+        logger.info(f"HTTP Request: {request.method} {request.url}")
+        response = await call_next(request)
+        logger.info(
+            f'HTTP Response: {request.method} {request.url} "{response.status_code} {responses[response.status_code]}"'
+        )
+        return response

langgraph_agent_toolkit/service/routes.py

@@ -0,0 +1,169 @@
+from fastapi import APIRouter, HTTPException, Request, status
+from fastapi.responses import RedirectResponse, StreamingResponse
+from langchain_core.messages import AnyMessage
+from langchain_core.runnables import RunnableConfig
+from langgraph.graph.state import CompiledStateGraph
+
+from langgraph_agent_toolkit import __version__
+from langgraph_agent_toolkit.agents.agent import Agent
+from langgraph_agent_toolkit.core import settings
+from langgraph_agent_toolkit.helper.constants import DEFAULT_AGENT
+from langgraph_agent_toolkit.helper.logging import logger
+from langgraph_agent_toolkit.helper.utils import langchain_to_chat_message
+from langgraph_agent_toolkit.schema import (
+    ChatHistory,
+    ChatHistoryInput,
+    ChatMessage,
+    Feedback,
+    FeedbackResponse,
+    HealthCheck,
+    ServiceMetadata,
+    StreamInput,
+    UserInput,
+)
+from langgraph_agent_toolkit.service.utils import (
+    _sse_response_example,
+    get_agent,
+    get_agent_executor,
+    get_all_agent_info,
+    message_generator,
+)
+
+
+# Create separate routers for private and public endpoints
+private_router = APIRouter()
+public_router = APIRouter()
+
+
+@private_router.get("/info", tags=["info"])
+async def info(request: Request) -> ServiceMetadata:
+    models = list(settings.AVAILABLE_MODELS)
+    models.sort()
+    return ServiceMetadata(
+        agents=get_all_agent_info(request),
+        models=models,
+        default_agent=DEFAULT_AGENT,
+        default_model=settings.DEFAULT_MODEL,
+    )
+
+
+@private_router.post("/{agent_id}/invoke", tags=["agent"])
+@private_router.post("/invoke", tags=["agent"])
+async def invoke(user_input: UserInput, agent_id: str = DEFAULT_AGENT, request: Request = None) -> ChatMessage:
+    """Invoke an agent with user input to retrieve a final response.
+
+    If agent_id is not provided, the default agent will be used.
+    Use thread_id to persist and continue a multi-turn conversation. run_id kwarg
+    is also attached to messages for recording feedback.
+    """
+    executor = get_agent_executor(request)
+
+    try:
+        return await executor.invoke(
+            agent_id=agent_id,
+            message=user_input.message,
+            thread_id=user_input.thread_id,
+            model=user_input.model,
+            agent_config=user_input.agent_config,
+            recursion_limit=user_input.recursion_limit,
+        )
+    except Exception as e:
+        logger.error(f"An exception occurred: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Unexpected error")
+
+
+@private_router.post(
+    "/{agent_id}/stream",
+    response_class=StreamingResponse,
+    responses=_sse_response_example(),
+    tags=["agent"],
+)
+@private_router.post(
+    "/stream",
+    response_class=StreamingResponse,
+    responses=_sse_response_example(),
+    tags=["agent"],
+)
+async def stream(user_input: StreamInput, agent_id: str = DEFAULT_AGENT, request: Request = None) -> StreamingResponse:
+    """Stream an agent's response to a user input, including intermediate messages and tokens.
+
+    If agent_id is not provided, the default agent will be used.
+    Use thread_id to persist and continue a multi-turn conversation. run_id kwarg
+    is also attached to all messages for recording feedback.
+
+    Set `stream_tokens=false` to return intermediate messages but not token-by-token.
+    """
+    return StreamingResponse(
+        message_generator(user_input, request, agent_id),
+        media_type="text/event-stream",
+    )
+
+
+@private_router.post("/feedback", status_code=status.HTTP_201_CREATED, tags=["feedback"])
+async def feedback(feedback: Feedback, agent_id: str = DEFAULT_AGENT, request: Request = None) -> FeedbackResponse:
+    """Record feedback for a run to the configured observability platform.
+
+    This routes the feedback to the appropriate platform based on the agent's configuration.
+    """
+    try:
+        agent = get_agent(request, agent_id)
+        agent.observability.record_feedback(
+            run_id=feedback.run_id,
+            key=feedback.key,
+            score=feedback.score,
+            **feedback.kwargs,
+        )
+
+        return FeedbackResponse(
+            run_id=feedback.run_id,
+            message=f"Feedback '{feedback.key}' recorded successfully for run {feedback.run_id}.",
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    except Exception as e:
+        logger.error(f"An exception occurred while recording feedback: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Unexpected error recording feedback"
+        )
+
+
+@private_router.post("/history", tags=["history"])
+def history(input: ChatHistoryInput, request: Request = None) -> ChatHistory:
+    """Get chat history."""
+    agent: Agent = get_agent(request, DEFAULT_AGENT)
+    try:
+        agent_graph: CompiledStateGraph = agent.graph
+        state_snapshot = agent_graph.get_state(
+            config=RunnableConfig(
+                configurable={
+                    "thread_id": input.thread_id,
+                }
+            )
+        )
+        messages: list[AnyMessage] = state_snapshot.values["messages"]
+        chat_messages: list[ChatMessage] = [langchain_to_chat_message(m) for m in messages]
+        return ChatHistory(messages=chat_messages)
+    except Exception as e:
+        logger.error(f"An exception occurred: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Unexpected error")
+
+
+@public_router.get("/", tags=["public"])
+async def redirect_to_docs() -> RedirectResponse:
+    return RedirectResponse(url="/docs")
+
+
+@public_router.get(
+    "/health",
+    tags=["public", "healthcheck"],
+    summary="Perform a Health Check",
+    response_description="Return HTTP Status Code 200 (OK)",
+    status_code=status.HTTP_200_OK,
+    response_model=HealthCheck,
+)
+async def health_check() -> HealthCheck:
+    """Health check endpoint."""
+    return HealthCheck(
+        content="healthy",
+        version=__version__,
+    )

langgraph_agent_toolkit/service/types.py

@@ -0,0 +1,8 @@
+from enum import StrEnum, auto
+
+
+class RunnerType(StrEnum):
+    UVICORN = auto()
+    GUNICORN = auto()
+    AWS_LAMBDA = auto()
+    AZURE_FUNCTIONS = auto()