dataknobs-bots 0.2.4__py3-none-any.whl

dataknobs_bots/reasoning/base.py

@@ -0,0 +1,50 @@
+"""Base reasoning strategy for DynaBot."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class ReasoningStrategy(ABC):
+    """Abstract base class for reasoning strategies.
+
+    Reasoning strategies control how the bot processes information
+    and generates responses. Different strategies can implement
+    different levels of reasoning complexity.
+
+    Examples:
+        - Simple: Direct LLM call
+        - Chain-of-Thought: Break down reasoning into steps
+        - ReAct: Reason and act in a loop with tools
+    """
+
+    @abstractmethod
+    async def generate(
+        self,
+        manager: Any,
+        llm: Any,
+        tools: list[Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Generate response using this reasoning strategy.
+
+        Args:
+            manager: ConversationManager instance
+            llm: LLM provider instance
+            tools: Optional list of available tools
+            **kwargs: Additional generation parameters (temperature, max_tokens, etc.)
+
+        Returns:
+            LLM response object
+
+        Example:
+            ```python
+            response = await strategy.generate(
+                manager=conversation_manager,
+                llm=llm_provider,
+                tools=[search_tool, calculator_tool],
+                temperature=0.7,
+                max_tokens=1000
+            )
+            ```
+        """
+        pass

dataknobs_bots/reasoning/react.py

@@ -0,0 +1,299 @@
+"""ReAct (Reasoning + Acting) reasoning strategy."""
+
+import logging
+from typing import Any
+
+from .base import ReasoningStrategy
+
+logger = logging.getLogger(__name__)
+
+
+class ReActReasoning(ReasoningStrategy):
+    """ReAct (Reasoning + Acting) strategy.
+
+    This strategy implements the ReAct pattern where the LLM:
+    1. Reasons about what to do (Thought)
+    2. Takes an action (using tools if needed)
+    3. Observes the result
+    4. Repeats until task is complete
+
+    This is useful for:
+    - Multi-step problem solving
+    - Tasks requiring tool use
+    - Complex reasoning chains
+
+    Attributes:
+        max_iterations: Maximum number of reasoning loops
+        verbose: Whether to enable debug-level logging
+        store_trace: Whether to store reasoning trace in conversation metadata
+
+    Example:
+        ```python
+        strategy = ReActReasoning(
+            max_iterations=5,
+            verbose=True,
+            store_trace=True
+        )
+        response = await strategy.generate(
+            manager=conversation_manager,
+            llm=llm_provider,
+            tools=[search_tool, calculator_tool]
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        max_iterations: int = 5,
+        verbose: bool = False,
+        store_trace: bool = False,
+    ):
+        """Initialize ReAct reasoning strategy.
+
+        Args:
+            max_iterations: Maximum reasoning/action iterations
+            verbose: Enable debug-level logging for reasoning steps
+            store_trace: Store reasoning trace in conversation metadata
+        """
+        self.max_iterations = max_iterations
+        self.verbose = verbose
+        self.store_trace = store_trace
+
+    async def generate(
+        self,
+        manager: Any,
+        llm: Any,
+        tools: list[Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Generate response using ReAct loop.
+
+        The ReAct loop:
+        1. Generate response (may include tool calls)
+        2. If tool calls present, execute them
+        3. Add observations to conversation
+        4. Repeat until no more tool calls or max iterations
+
+        Args:
+            manager: ConversationManager instance
+            llm: LLM provider instance
+            tools: Optional list of available tools
+            **kwargs: Generation parameters
+
+        Returns:
+            Final LLM response
+        """
+        if not tools:
+            # No tools available, fall back to simple generation
+            logger.info(
+                "ReAct: No tools available, falling back to simple generation",
+                extra={"conversation_id": manager.conversation_id},
+            )
+            return await manager.complete(**kwargs)
+
+        # Initialize trace if enabled
+        trace = [] if self.store_trace else None
+
+        # Get log level based on verbose setting
+        log_level = logging.DEBUG if self.verbose else logging.INFO
+
+        logger.log(
+            log_level,
+            "ReAct: Starting reasoning loop",
+            extra={
+                "conversation_id": manager.conversation_id,
+                "max_iterations": self.max_iterations,
+                "tools_available": len(tools),
+            },
+        )
+
+        # ReAct loop
+        for iteration in range(self.max_iterations):
+            iteration_trace = {
+                "iteration": iteration + 1,
+                "tool_calls": [],
+            }
+
+            logger.log(
+                log_level,
+                "ReAct: Starting iteration",
+                extra={
+                    "conversation_id": manager.conversation_id,
+                    "iteration": iteration + 1,
+                    "max_iterations": self.max_iterations,
+                },
+            )
+
+            # Generate response with tools
+            response = await manager.complete(tools=tools, **kwargs)
+
+            # Check if we have tool calls
+            if not hasattr(response, "tool_calls") or not response.tool_calls:
+                # No tool calls, we're done
+                logger.log(
+                    log_level,
+                    "ReAct: No tool calls in response, finishing",
+                    extra={
+                        "conversation_id": manager.conversation_id,
+                        "iteration": iteration + 1,
+                    },
+                )
+
+                if trace is not None:
+                    iteration_trace["status"] = "completed"
+                    trace.append(iteration_trace)
+                    await self._store_trace(manager, trace)
+
+                return response
+
+            num_tool_calls = len(response.tool_calls)
+            logger.log(
+                log_level,
+                "ReAct: Executing tool calls",
+                extra={
+                    "conversation_id": manager.conversation_id,
+                    "iteration": iteration + 1,
+                    "num_tools": num_tool_calls,
+                    "tools": [tc.name for tc in response.tool_calls],
+                },
+            )
+
+            # Execute all tool calls
+            for tool_call in response.tool_calls:
+                tool_trace = {
+                    "name": tool_call.name,
+                    "parameters": tool_call.parameters,
+                }
+
+                try:
+                    # Find the tool
+                    tool = self._find_tool(tool_call.name, tools)
+                    if not tool:
+                        observation = f"Error: Tool '{tool_call.name}' not found"
+                        tool_trace["status"] = "error"
+                        tool_trace["error"] = "Tool not found"
+
+                        logger.warning(
+                            "ReAct: Tool not found",
+                            extra={
+                                "conversation_id": manager.conversation_id,
+                                "iteration": iteration + 1,
+                                "tool_name": tool_call.name,
+                            },
+                        )
+                    else:
+                        # Execute the tool
+                        result = await tool.execute(**tool_call.parameters)
+                        observation = f"Tool result: {result}"
+                        tool_trace["status"] = "success"
+                        tool_trace["result"] = str(result)
+
+                        logger.log(
+                            log_level,
+                            "ReAct: Tool executed successfully",
+                            extra={
+                                "conversation_id": manager.conversation_id,
+                                "iteration": iteration + 1,
+                                "tool_name": tool_call.name,
+                                "result_length": len(str(result)),
+                            },
+                        )
+
+                    # Add observation to conversation
+                    await manager.add_message(
+                        content=f"Observation from {tool_call.name}: {observation}",
+                        role="system",
+                    )
+
+                except Exception as e:
+                    # Handle tool execution errors
+                    error_msg = f"Error executing tool {tool_call.name}: {e!s}"
+                    tool_trace["status"] = "error"
+                    tool_trace["error"] = str(e)
+
+                    logger.error(
+                        "ReAct: Tool execution failed",
+                        extra={
+                            "conversation_id": manager.conversation_id,
+                            "iteration": iteration + 1,
+                            "tool_name": tool_call.name,
+                            "error": str(e),
+                        },
+                        exc_info=True,
+                    )
+
+                    await manager.add_message(content=error_msg, role="system")
+
+                if trace is not None:
+                    iteration_trace["tool_calls"].append(tool_trace)
+
+            if trace is not None:
+                iteration_trace["status"] = "continued"
+                trace.append(iteration_trace)
+
+        # Max iterations reached, generate final response without tools
+        logger.log(
+            log_level,
+            "ReAct: Max iterations reached, generating final response",
+            extra={
+                "conversation_id": manager.conversation_id,
+                "iterations_used": self.max_iterations,
+            },
+        )
+
+        if trace is not None:
+            trace.append({"status": "max_iterations_reached"})
+            await self._store_trace(manager, trace)
+
+        return await manager.complete(**kwargs)
+
+    async def _store_trace(self, manager: Any, trace: list[dict[str, Any]]) -> None:
+        """Store reasoning trace in conversation metadata.
+
+        Args:
+            manager: ConversationManager instance
+            trace: Reasoning trace data
+        """
+        try:
+            # Get existing metadata
+            metadata = manager.conversation.metadata or {}
+
+            # Add trace to metadata
+            metadata["reasoning_trace"] = trace
+
+            # Update conversation metadata
+            await manager.storage.update_metadata(
+                conversation_id=manager.conversation_id,
+                metadata=metadata,
+            )
+
+            logger.debug(
+                "ReAct: Stored reasoning trace in conversation metadata",
+                extra={
+                    "conversation_id": manager.conversation_id,
+                    "trace_items": len(trace),
+                },
+            )
+        except Exception as e:
+            logger.warning(
+                "ReAct: Failed to store reasoning trace",
+                extra={
+                    "conversation_id": manager.conversation_id,
+                    "error": str(e),
+                },
+            )
+
+    def _find_tool(self, tool_name: str, tools: list[Any]) -> Any | None:
+        """Find a tool by name.
+
+        Args:
+            tool_name: Name of the tool to find
+            tools: List of available tools
+
+        Returns:
+            Tool instance or None if not found
+        """
+        for tool in tools:
+            if tool.name == tool_name:
+                return tool
+        return None

dataknobs_bots/reasoning/simple.py

@@ -0,0 +1,51 @@
+"""Simple reasoning strategy - direct LLM call."""
+
+from typing import Any
+
+from .base import ReasoningStrategy
+
+
+class SimpleReasoning(ReasoningStrategy):
+    """Simple reasoning strategy that makes direct LLM calls.
+
+    This is the most straightforward strategy - it simply passes
+    the conversation to the LLM and returns the response without
+    any additional reasoning steps.
+
+    Use this when:
+    - You want direct, fast responses
+    - The task doesn't require complex reasoning
+    - You're using a powerful model that doesn't need guidance
+
+    Example:
+        ```python
+        strategy = SimpleReasoning()
+        response = await strategy.generate(
+            manager=conversation_manager,
+            llm=llm_provider,
+            temperature=0.7
+        )
+        ```
+    """
+
+    async def generate(
+        self,
+        manager: Any,
+        llm: Any,
+        tools: list[Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Generate response with a simple LLM call.
+
+        Args:
+            manager: ConversationManager instance
+            llm: LLM provider instance (not used directly)
+            tools: Optional list of tools
+            **kwargs: Generation parameters
+
+        Returns:
+            LLM response
+        """
+        # Use the conversation manager's generate method
+        # which handles the LLM call with the conversation history
+        return await manager.complete(tools=tools, **kwargs)

dataknobs_bots/registry/__init__.py

@@ -0,0 +1,41 @@
+"""Registry module for bot registration storage and management.
+
+This module provides:
+- Registration: Dataclass for bot registration with metadata
+- RegistryBackend: Protocol for pluggable storage backends
+- InMemoryBackend: Simple dict-based storage for testing/development
+- Portability validation utilities
+
+Example:
+    ```python
+    from dataknobs_bots.registry import Registration, InMemoryBackend
+
+    backend = InMemoryBackend()
+    await backend.initialize()
+
+    reg = await backend.register("my-bot", {"llm": {...}})
+    print(f"Bot registered at {reg.created_at}")
+    ```
+"""
+
+from __future__ import annotations
+
+from .backend import RegistryBackend
+from .memory import InMemoryBackend
+from .models import Registration
+from .portability import (
+    PortabilityError,
+    has_resource_references,
+    is_portable,
+    validate_portability,
+)
+
+__all__ = [
+    "Registration",
+    "RegistryBackend",
+    "InMemoryBackend",
+    "PortabilityError",
+    "validate_portability",
+    "has_resource_references",
+    "is_portable",
+]

dataknobs_bots/registry/backend.py

@@ -0,0 +1,181 @@
+"""Registry backend protocol for pluggable storage."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .models import Registration
+
+
+@runtime_checkable
+class RegistryBackend(Protocol):
+    """Protocol for bot registry storage backends.
+
+    Implementations store bot configurations with metadata.
+    The backend is responsible for persistence; the BotRegistry
+    handles caching and bot instantiation.
+
+    This protocol defines the interface for storage backends:
+    - InMemoryBackend: Simple dict storage (default, good for tests)
+    - PostgreSQLBackend: Database persistence (future/external)
+    - RedisBackend: Distributed caching (future/external)
+
+    All methods are async to support both sync and async backends.
+
+    Example:
+        ```python
+        class MyCustomBackend:
+            async def initialize(self) -> None:
+                # Setup database connection
+                ...
+
+            async def register(self, bot_id: str, config: dict, status: str = "active"):
+                # Store in database
+                ...
+
+            # ... implement other methods
+        ```
+    """
+
+    async def initialize(self) -> None:
+        """Initialize the backend (create tables, connections, etc.).
+
+        Called before the backend is used. Should be idempotent.
+        """
+        ...
+
+    async def close(self) -> None:
+        """Close the backend (release connections, etc.).
+
+        Called when the registry is shutting down.
+        """
+        ...
+
+    async def register(
+        self,
+        bot_id: str,
+        config: dict[str, Any],
+        status: str = "active",
+    ) -> Registration:
+        """Register a bot or update existing registration.
+
+        If a registration with the same bot_id exists, it should be updated
+        (config replaced, status updated, updated_at set to now).
+
+        Args:
+            bot_id: Unique bot identifier
+            config: Bot configuration dictionary (should be portable)
+            status: Registration status (default: active)
+
+        Returns:
+            Registration object with metadata
+        """
+        ...
+
+    async def get(self, bot_id: str) -> Registration | None:
+        """Get registration by ID.
+
+        Should update last_accessed_at timestamp on access.
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            Registration if found, None otherwise
+        """
+        ...
+
+    async def get_config(self, bot_id: str) -> dict[str, Any] | None:
+        """Get just the config for a bot.
+
+        Convenience method that returns only the config dict.
+        Should also update last_accessed_at.
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            Config dict if found, None otherwise
+        """
+        ...
+
+    async def exists(self, bot_id: str) -> bool:
+        """Check if an active registration exists.
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            True if registration exists and is active
+        """
+        ...
+
+    async def unregister(self, bot_id: str) -> bool:
+        """Hard delete a registration.
+
+        Permanently removes the registration from storage.
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            True if deleted, False if not found
+        """
+        ...
+
+    async def deactivate(self, bot_id: str) -> bool:
+        """Soft delete (set status to inactive).
+
+        Marks the registration as inactive without deleting.
+        Inactive registrations should not be returned by exists()
+        or list_active().
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            True if deactivated, False if not found
+        """
+        ...
+
+    async def list_active(self) -> list[Registration]:
+        """List all active registrations.
+
+        Returns:
+            List of active Registration objects
+        """
+        ...
+
+    async def list_all(self) -> list[Registration]:
+        """List all registrations including inactive.
+
+        Returns:
+            List of all Registration objects
+        """
+        ...
+
+    async def list_ids(self) -> list[str]:
+        """List active bot IDs only.
+
+        More efficient than list_active() when only IDs are needed.
+
+        Returns:
+            List of active bot IDs
+        """
+        ...
+
+    async def count(self) -> int:
+        """Count active registrations.
+
+        Returns:
+            Number of active registrations
+        """
+        ...
+
+    async def clear(self) -> None:
+        """Clear all registrations.
+
+        Primarily useful for testing.
+        """
+        ...