dataknobs-bots 0.2.4__py3-none-any.whl

dataknobs_bots/__init__.py

@@ -0,0 +1,42 @@
+"""DataKnobs Bots - Configuration-driven AI agents."""
+
+from .bot import BotContext, BotManager, BotRegistry, DynaBot
+from .knowledge import RAGKnowledgeBase, create_knowledge_base_from_config
+from .memory import BufferMemory, Memory, VectorMemory, create_memory_from_config
+from .middleware import CostTrackingMiddleware, LoggingMiddleware, Middleware
+from .reasoning import (
+    ReActReasoning,
+    ReasoningStrategy,
+    SimpleReasoning,
+    create_reasoning_from_config,
+)
+from .tools import KnowledgeSearchTool
+
+__version__ = "0.2.4"
+
+__all__ = [
+    # Bot
+    "DynaBot",
+    "BotContext",
+    "BotManager",
+    "BotRegistry",
+    # Memory
+    "Memory",
+    "BufferMemory",
+    "VectorMemory",
+    "create_memory_from_config",
+    # Knowledge
+    "RAGKnowledgeBase",
+    "create_knowledge_base_from_config",
+    # Tools
+    "KnowledgeSearchTool",
+    # Reasoning
+    "ReasoningStrategy",
+    "SimpleReasoning",
+    "ReActReasoning",
+    "create_reasoning_from_config",
+    # Middleware
+    "Middleware",
+    "CostTrackingMiddleware",
+    "LoggingMiddleware",
+]

dataknobs_bots/api/__init__.py

@@ -0,0 +1,42 @@
+"""FastAPI integration components for dataknobs_bots."""
+
+from .dependencies import (
+    BotManagerDep,
+    get_bot_manager,
+    init_bot_manager,
+    reset_bot_manager,
+)
+from .exceptions import (
+    APIError,
+    BotCreationError,
+    BotNotFoundError,
+    ConfigurationError,
+    ConversationNotFoundError,
+    RateLimitError,
+    ValidationError,
+    api_error_handler,
+    general_exception_handler,
+    http_exception_handler,
+    register_exception_handlers,
+)
+
+__all__ = [
+    # Dependencies
+    "get_bot_manager",
+    "init_bot_manager",
+    "reset_bot_manager",
+    "BotManagerDep",
+    # Exceptions
+    "APIError",
+    "BotNotFoundError",
+    "BotCreationError",
+    "ConversationNotFoundError",
+    "ValidationError",
+    "ConfigurationError",
+    "RateLimitError",
+    # Handlers
+    "api_error_handler",
+    "http_exception_handler",
+    "general_exception_handler",
+    "register_exception_handlers",
+]

dataknobs_bots/api/dependencies.py

@@ -0,0 +1,140 @@
+"""Dependency injection helpers for FastAPI.
+
+This module provides singleton management and FastAPI dependency injection
+for bot-related services.
+
+Example:
+    ```python
+    from fastapi import FastAPI
+    from dataknobs_bots.api.dependencies import (
+        init_bot_manager,
+        BotManagerDep,
+    )
+
+    app = FastAPI()
+
+    @app.on_event("startup")
+    async def startup():
+        # Initialize with a config loader
+        init_bot_manager(config_loader=my_loader)
+
+    @app.post("/chat/{bot_id}")
+    async def chat(
+        bot_id: str,
+        message: str,
+        manager: BotManagerDep,
+    ):
+        bot = await manager.get_or_create(bot_id)
+        return await bot.chat(message, context)
+    ```
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Annotated, Any
+
+from dataknobs_bots.bot.manager import BotManager, ConfigLoaderType
+
+
+logger = logging.getLogger(__name__)
+
+
+class _BotManagerSingleton:
+    """Singleton container for BotManager instance.
+
+    Using a class-based approach avoids global statement warnings
+    while maintaining singleton semantics.
+    """
+
+    _instance: BotManager | None = None
+
+    @classmethod
+    def get(cls) -> BotManager:
+        """Get the singleton instance, creating with defaults if needed."""
+        if cls._instance is None:
+            cls._instance = BotManager()
+            logger.info("Created default BotManager singleton (no config loader)")
+        return cls._instance
+
+    @classmethod
+    def init(
+        cls,
+        config_loader: ConfigLoaderType | None = None,
+        **kwargs: Any,
+    ) -> BotManager:
+        """Initialize the singleton with configuration."""
+        cls._instance = BotManager(config_loader=config_loader, **kwargs)
+        logger.info("Initialized BotManager singleton")
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance."""
+        cls._instance = None
+        logger.info("Reset BotManager singleton")
+
+
+def get_bot_manager() -> BotManager:
+    """Get or create BotManager singleton instance.
+
+    Returns:
+        BotManager instance
+
+    Note:
+        Call `init_bot_manager()` during app startup to configure
+        the singleton before using this dependency.
+    """
+    return _BotManagerSingleton.get()
+
+
+def init_bot_manager(
+    config_loader: ConfigLoaderType | None = None,
+    **kwargs: Any,
+) -> BotManager:
+    """Initialize the BotManager singleton with configuration.
+
+    Call this during application startup to configure the singleton.
+
+    Args:
+        config_loader: Optional configuration loader for bots
+        **kwargs: Additional arguments passed to BotManager
+
+    Returns:
+        Configured BotManager instance
+
+    Example:
+        ```python
+        @app.on_event("startup")
+        async def startup():
+            init_bot_manager(
+                config_loader=MyConfigLoader("./configs")
+            )
+        ```
+    """
+    return _BotManagerSingleton.init(config_loader=config_loader, **kwargs)
+
+
+def reset_bot_manager() -> None:
+    """Reset the BotManager singleton.
+
+    Useful for testing or when reconfiguring the application.
+    """
+    _BotManagerSingleton.reset()
+
+
+# Dependency function for FastAPI
+def _get_bot_manager_dep() -> BotManager:
+    """Dependency function for FastAPI."""
+    return get_bot_manager()
+
+
+# Type alias for FastAPI dependency injection
+# Usage: async def endpoint(manager: BotManagerDep):
+try:
+    from fastapi import Depends
+
+    BotManagerDep = Annotated[BotManager, Depends(_get_bot_manager_dep)]
+except ImportError:
+    # FastAPI not installed - provide a placeholder
+    BotManagerDep = BotManager  # type: ignore

dataknobs_bots/api/exceptions.py

@@ -0,0 +1,289 @@
+"""Custom exceptions and exception handlers for FastAPI applications.
+
+This module provides a consistent exception hierarchy and handlers
+for bot-related API errors. The exceptions extend from dataknobs_common
+for consistency across the codebase.
+
+Example:
+    ```python
+    from fastapi import FastAPI
+    from dataknobs_bots.api.exceptions import (
+        register_exception_handlers,
+        BotNotFoundError,
+    )
+
+    app = FastAPI()
+    register_exception_handlers(app)
+
+    @app.get("/bots/{bot_id}")
+    async def get_bot(bot_id: str):
+        bot = await manager.get(bot_id)
+        if not bot:
+            raise BotNotFoundError(bot_id)
+        return {"bot_id": bot_id}
+    ```
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from dataknobs_common.exceptions import (
+    ConfigurationError as CommonConfigurationError,
+)
+from dataknobs_common.exceptions import (
+    DataknobsError,
+)
+from dataknobs_common.exceptions import (
+    NotFoundError as CommonNotFoundError,
+)
+from dataknobs_common.exceptions import (
+    ValidationError as CommonValidationError,
+)
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI, HTTPException, Request
+    from fastapi.responses import JSONResponse
+
+
+class APIError(DataknobsError):
+    """Base exception for API errors.
+
+    Extends DataknobsError to provide HTTP-specific error handling
+    with status codes and structured error responses.
+
+    Attributes:
+        message: Error message
+        status_code: HTTP status code
+        detail: Error details (maps to DataknobsError.context)
+        error_code: Machine-readable error code
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 500,
+        detail: dict[str, Any] | None = None,
+        error_code: str | None = None,
+    ):
+        """Initialize API error.
+
+        Args:
+            message: Human-readable error message
+            status_code: HTTP status code (default: 500)
+            detail: Optional dictionary with error details
+            error_code: Optional machine-readable error code
+        """
+        # Pass detail as context to DataknobsError
+        super().__init__(message, context=detail)
+        self.status_code = status_code
+        self.error_code = error_code or self.__class__.__name__
+
+    @property
+    def detail(self) -> dict[str, Any]:
+        """Alias for context to maintain API compatibility."""
+        return self.context
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert error to dictionary for JSON response.
+
+        Returns:
+            Dictionary representation of the error
+        """
+        return {
+            "error": self.error_code,
+            "message": str(self),
+            "detail": self.context,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+
+
+class BotNotFoundError(APIError, CommonNotFoundError):
+    """Exception raised when bot instance is not found."""
+
+    def __init__(self, bot_id: str):
+        APIError.__init__(
+            self,
+            message=f"Bot with ID '{bot_id}' not found",
+            status_code=404,
+            detail={"bot_id": bot_id},
+        )
+
+
+class BotCreationError(APIError):
+    """Exception raised when bot creation fails."""
+
+    def __init__(self, bot_id: str, reason: str):
+        super().__init__(
+            message=f"Failed to create bot '{bot_id}': {reason}",
+            status_code=500,
+            detail={"bot_id": bot_id, "reason": reason},
+        )
+
+
+class ConversationNotFoundError(APIError, CommonNotFoundError):
+    """Exception raised when conversation is not found."""
+
+    def __init__(self, conversation_id: str):
+        APIError.__init__(
+            self,
+            message=f"Conversation with ID '{conversation_id}' not found",
+            status_code=404,
+            detail={"conversation_id": conversation_id},
+        )
+
+
+class ValidationError(APIError, CommonValidationError):
+    """Exception raised when input validation fails."""
+
+    def __init__(self, message: str, detail: dict[str, Any] | None = None):
+        APIError.__init__(
+            self,
+            message=message,
+            status_code=422,
+            detail=detail,
+        )
+
+
+class ConfigurationError(APIError, CommonConfigurationError):
+    """Exception raised when configuration is invalid."""
+
+    def __init__(self, message: str, config_key: str | None = None):
+        detail = {}
+        if config_key:
+            detail["config_key"] = config_key
+        APIError.__init__(
+            self,
+            message=message,
+            status_code=500,
+            detail=detail,
+        )
+
+
+class RateLimitError(APIError):
+    """Exception raised when rate limit is exceeded."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: int | None = None,
+    ):
+        detail = {}
+        if retry_after:
+            detail["retry_after"] = retry_after
+        super().__init__(
+            message=message,
+            status_code=429,
+            detail=detail,
+        )
+
+
+# Exception Handlers
+# Note: These use TYPE_CHECKING imports to avoid requiring FastAPI at import time
+
+
+async def api_error_handler(
+    request: Request,  # type: ignore[name-defined]
+    exc: APIError,
+) -> JSONResponse:  # type: ignore[name-defined]
+    """Handle API errors with standardized response format.
+
+    Args:
+        request: FastAPI request object
+        exc: API error exception
+
+    Returns:
+        JSON response with error details
+    """
+    from fastapi.responses import JSONResponse
+
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=exc.to_dict(),
+    )
+
+
+async def http_exception_handler(
+    request: Request,  # type: ignore[name-defined]
+    exc: HTTPException,  # type: ignore[name-defined]
+) -> JSONResponse:  # type: ignore[name-defined]
+    """Handle FastAPI HTTP exceptions.
+
+    Args:
+        request: FastAPI request object
+        exc: HTTP exception
+
+    Returns:
+        JSON response with error details
+    """
+    from fastapi.responses import JSONResponse
+
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": "HTTPException",
+            "message": str(exc.detail),
+            "detail": {},
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        },
+    )
+
+
+async def general_exception_handler(
+    request: Request,  # type: ignore[name-defined]
+    exc: Exception,
+) -> JSONResponse:  # type: ignore[name-defined]
+    """Handle unexpected exceptions.
+
+    Args:
+        request: FastAPI request object
+        exc: Generic exception
+
+    Returns:
+        JSON response with error details
+
+    Note:
+        This handler logs the full exception but returns a generic
+        message to avoid leaking internal details.
+    """
+    import logging
+
+    from fastapi.responses import JSONResponse
+
+    logger = logging.getLogger(__name__)
+    logger.exception(f"Unhandled exception: {exc}")
+
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": "InternalServerError",
+            "message": "An unexpected error occurred",
+            "detail": {"exception_type": type(exc).__name__},
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        },
+    )
+
+
+def register_exception_handlers(
+    app: FastAPI,  # type: ignore[name-defined]
+) -> None:
+    """Register all exception handlers with a FastAPI app.
+
+    Args:
+        app: FastAPI application instance
+
+    Example:
+        ```python
+        from fastapi import FastAPI
+        from dataknobs_bots.api.exceptions import register_exception_handlers
+
+        app = FastAPI()
+        register_exception_handlers(app)
+        ```
+    """
+    from fastapi import HTTPException
+
+    app.add_exception_handler(APIError, api_error_handler)  # type: ignore
+    app.add_exception_handler(HTTPException, http_exception_handler)  # type: ignore
+    app.add_exception_handler(Exception, general_exception_handler)

dataknobs_bots/bot/__init__.py

@@ -0,0 +1,15 @@
+"""Bot core components."""
+
+from .base import DynaBot
+from .context import BotContext
+from .manager import BotManager
+from .registry import BotRegistry, InMemoryBotRegistry, create_memory_registry
+
+__all__ = [
+    "DynaBot",
+    "BotContext",
+    "BotManager",
+    "BotRegistry",
+    "InMemoryBotRegistry",
+    "create_memory_registry",
+]