dataknobs-bots 0.2.4__py3-none-any.whl

dataknobs_bots/registry/memory.py

@@ -0,0 +1,244 @@
+"""In-memory implementation of RegistryBackend."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any
+
+from .models import Registration
+
+
+class InMemoryBackend:
+    """In-memory implementation of RegistryBackend.
+
+    Simple dict-based storage suitable for:
+    - Testing without database dependencies
+    - Single-instance deployments
+    - Development environments
+
+    Not suitable for:
+    - Multi-instance deployments (no persistence)
+    - Production with persistence requirements
+
+    Thread-safety is provided via asyncio.Lock.
+
+    Example:
+        ```python
+        backend = InMemoryBackend()
+        await backend.initialize()
+
+        reg = await backend.register("my-bot", {"llm": {...}})
+        print(f"Created at: {reg.created_at}")
+
+        config = await backend.get_config("my-bot")
+        print(f"Config: {config}")
+
+        # List all bots
+        for reg in await backend.list_active():
+            print(f"Bot: {reg.bot_id}")
+
+        # Cleanup
+        await backend.close()
+        ```
+    """
+
+    def __init__(self) -> None:
+        """Initialize the in-memory backend."""
+        self._registrations: dict[str, Registration] = {}
+        self._lock = asyncio.Lock()
+        self._initialized = False
+
+    async def initialize(self) -> None:
+        """Initialize the backend (no-op for in-memory)."""
+        self._initialized = True
+
+    async def close(self) -> None:
+        """Close the backend (clears all data)."""
+        async with self._lock:
+            self._registrations.clear()
+            self._initialized = False
+
+    async def register(
+        self,
+        bot_id: str,
+        config: dict[str, Any],
+        status: str = "active",
+    ) -> Registration:
+        """Register or update a bot.
+
+        Args:
+            bot_id: Unique bot identifier
+            config: Bot configuration dictionary
+            status: Registration status (default: active)
+
+        Returns:
+            Registration object with metadata
+        """
+        async with self._lock:
+            now = datetime.now(timezone.utc)
+
+            if bot_id in self._registrations:
+                # Update existing - preserve created_at
+                old = self._registrations[bot_id]
+                reg = Registration(
+                    bot_id=bot_id,
+                    config=config,
+                    status=status,
+                    created_at=old.created_at,
+                    updated_at=now,
+                    last_accessed_at=now,
+                )
+            else:
+                # Create new
+                reg = Registration(
+                    bot_id=bot_id,
+                    config=config,
+                    status=status,
+                    created_at=now,
+                    updated_at=now,
+                    last_accessed_at=now,
+                )
+
+            self._registrations[bot_id] = reg
+            return reg
+
+    async def get(self, bot_id: str) -> Registration | None:
+        """Get registration and update access time.
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            Registration if found, None otherwise
+        """
+        async with self._lock:
+            reg = self._registrations.get(bot_id)
+            if reg:
+                # Update access time
+                self._registrations[bot_id] = Registration(
+                    bot_id=reg.bot_id,
+                    config=reg.config,
+                    status=reg.status,
+                    created_at=reg.created_at,
+                    updated_at=reg.updated_at,
+                    last_accessed_at=datetime.now(timezone.utc),
+                )
+                return self._registrations[bot_id]
+            return None
+
+    async def get_config(self, bot_id: str) -> dict[str, Any] | None:
+        """Get just the config.
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            Config dict if found, None otherwise
+        """
+        reg = await self.get(bot_id)
+        return reg.config if reg else None
+
+    async def exists(self, bot_id: str) -> bool:
+        """Check if active registration exists.
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            True if registration exists and is active
+        """
+        async with self._lock:
+            reg = self._registrations.get(bot_id)
+            return reg is not None and reg.status == "active"
+
+    async def unregister(self, bot_id: str) -> bool:
+        """Hard delete registration.
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            True if deleted, False if not found
+        """
+        async with self._lock:
+            if bot_id in self._registrations:
+                del self._registrations[bot_id]
+                return True
+            return False
+
+    async def deactivate(self, bot_id: str) -> bool:
+        """Soft delete (set inactive).
+
+        Args:
+            bot_id: Bot identifier
+
+        Returns:
+            True if deactivated, False if not found
+        """
+        async with self._lock:
+            if bot_id in self._registrations:
+                reg = self._registrations[bot_id]
+                self._registrations[bot_id] = Registration(
+                    bot_id=reg.bot_id,
+                    config=reg.config,
+                    status="inactive",
+                    created_at=reg.created_at,
+                    updated_at=datetime.now(timezone.utc),
+                    last_accessed_at=reg.last_accessed_at,
+                )
+                return True
+            return False
+
+    async def list_active(self) -> list[Registration]:
+        """List active registrations.
+
+        Returns:
+            List of active Registration objects
+        """
+        async with self._lock:
+            return [
+                reg for reg in self._registrations.values() if reg.status == "active"
+            ]
+
+    async def list_all(self) -> list[Registration]:
+        """List all registrations.
+
+        Returns:
+            List of all Registration objects
+        """
+        async with self._lock:
+            return list(self._registrations.values())
+
+    async def list_ids(self) -> list[str]:
+        """List active bot IDs.
+
+        Returns:
+            List of active bot IDs
+        """
+        async with self._lock:
+            return [
+                reg.bot_id
+                for reg in self._registrations.values()
+                if reg.status == "active"
+            ]
+
+    async def count(self) -> int:
+        """Count active registrations.
+
+        Returns:
+            Number of active registrations
+        """
+        async with self._lock:
+            return sum(
+                1 for reg in self._registrations.values() if reg.status == "active"
+            )
+
+    async def clear(self) -> None:
+        """Clear all registrations."""
+        async with self._lock:
+            self._registrations.clear()
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"InMemoryBackend(count={len(self._registrations)})"

dataknobs_bots/registry/models.py

@@ -0,0 +1,102 @@
+"""Registration model for bot registry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class Registration:
+    """Bot registration with metadata.
+
+    Stores a bot configuration along with lifecycle metadata like
+    timestamps and status. Used by registry backends to persist
+    bot configurations.
+
+    Attributes:
+        bot_id: Unique bot identifier
+        config: Bot configuration dictionary (should be portable)
+        status: Registration status (active, inactive, error)
+        created_at: When the registration was created
+        updated_at: When the registration was last updated
+        last_accessed_at: When the bot was last accessed
+
+    Example:
+        ```python
+        reg = Registration(
+            bot_id="my-bot",
+            config={"bot": {"llm": {"$resource": "default", "type": "llm_providers"}}},
+        )
+        print(f"Bot {reg.bot_id} created at {reg.created_at}")
+
+        # Serialize for storage
+        data = reg.to_dict()
+
+        # Restore from storage
+        restored = Registration.from_dict(data)
+        ```
+    """
+
+    bot_id: str
+    config: dict[str, Any]
+    status: str = "active"
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    last_accessed_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary representation with ISO format timestamps
+        """
+        return {
+            "bot_id": self.bot_id,
+            "config": self.config,
+            "status": self.status,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+            "last_accessed_at": (
+                self.last_accessed_at.isoformat() if self.last_accessed_at else None
+            ),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Registration:
+        """Create from dictionary.
+
+        Args:
+            data: Dictionary with registration data
+
+        Returns:
+            Registration instance
+        """
+        return cls(
+            bot_id=data["bot_id"],
+            config=data["config"],
+            status=data.get("status", "active"),
+            created_at=(
+                datetime.fromisoformat(data["created_at"])
+                if data.get("created_at")
+                else datetime.now(timezone.utc)
+            ),
+            updated_at=(
+                datetime.fromisoformat(data["updated_at"])
+                if data.get("updated_at")
+                else datetime.now(timezone.utc)
+            ),
+            last_accessed_at=(
+                datetime.fromisoformat(data["last_accessed_at"])
+                if data.get("last_accessed_at")
+                else datetime.now(timezone.utc)
+            ),
+        )
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return (
+            f"Registration(bot_id={self.bot_id!r}, status={self.status!r}, "
+            f"created_at={self.created_at.isoformat() if self.created_at else None})"
+        )

dataknobs_bots/registry/portability.py

@@ -0,0 +1,210 @@
+"""Portability validation utilities for bot configurations.
+
+This module provides utilities to validate that bot configurations
+are portable across environments. Portable configs use $resource
+references instead of hardcoded values like local paths or localhost URLs.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+class PortabilityError(Exception):
+    r"""Raised when a config contains non-portable values.
+
+    Non-portable values include:
+    - Local file paths (/Users/..., /home/..., C:\Users\...)
+    - Localhost URLs (localhost:port, 127.0.0.1, 0.0.0.0)
+
+    Portable configs should use $resource references that are
+    resolved at runtime based on the environment.
+
+    Example:
+        ```python
+        # This will raise PortabilityError
+        validate_portability({
+            "storage": {"path": "/Users/dev/data"}  # Local path!
+        })
+
+        # This is OK
+        validate_portability({
+            "storage": {"$resource": "default", "type": "databases"}
+        })
+        ```
+    """
+
+    pass
+
+
+# Patterns that indicate resolved local values (not portable)
+# Note: Windows paths may appear with single or double backslashes depending
+# on whether we're matching against repr() output or actual string values
+SUSPICIOUS_PATTERNS: list[tuple[str, str]] = [
+    (r"/Users/\w+", "macOS home directory"),
+    (r"/home/\w+", "Linux home directory"),
+    (r"C:\\+Users\\+\w+", "Windows home directory"),  # Matches C:\Users or C:\\Users
+    (r"localhost:\d+", "localhost with port"),
+    (r"127\.0\.0\.1", "localhost IP"),
+    (r"0\.0\.0\.0", "all interfaces IP"),
+]
+
+# Patterns that are OK (environment variable placeholders)
+SAFE_PATTERNS: list[str] = [
+    r"\$\{[^}]+\}",  # ${VAR} or ${VAR:default}
+    r"\$[A-Z_][A-Z0-9_]*",  # $VAR
+]
+
+
+def validate_portability(
+    config: dict[str, Any],
+    raise_on_error: bool = True,
+) -> list[str]:
+    """Validate that a config is portable (no resolved local values).
+
+    Checks for patterns that indicate resolved environment values
+    that would break portability across environments.
+
+    Args:
+        config: Configuration dictionary to validate
+        raise_on_error: If True, raise PortabilityError; otherwise return issues
+
+    Returns:
+        List of portability issues found (empty if portable)
+
+    Raises:
+        PortabilityError: If non-portable and raise_on_error=True
+
+    Example:
+        ```python
+        # This will raise PortabilityError
+        validate_portability({
+            "llm": {"api_key": "sk-..."},  # OK - not a path
+            "storage": {"path": "/Users/dev/data"},  # NOT OK - local path
+        })
+
+        # Check without raising
+        issues = validate_portability(config, raise_on_error=False)
+        if issues:
+            print(f"Found {len(issues)} portability issues")
+
+        # This is OK - uses $resource references
+        validate_portability({
+            "llm": {"$resource": "default", "type": "llm_providers"},
+            "storage": {"$resource": "db", "type": "databases"},
+        })
+
+        # Environment variables are OK
+        validate_portability({
+            "storage": {"path": "${DATA_PATH}"},  # OK - env var placeholder
+        })
+        ```
+    """
+    config_str = str(config)
+    issues: list[str] = []
+
+    for pattern, description in SUSPICIOUS_PATTERNS:
+        matches = re.findall(pattern, config_str)
+        for match in matches:
+            # Check if this match is inside a safe pattern (env var)
+            is_safe = _is_in_safe_pattern(match, config_str)
+
+            if not is_safe:
+                issues.append(f"Found {description}: '{match}'")
+
+    if issues and raise_on_error:
+        raise PortabilityError(
+            "Config appears to contain resolved local values that would break "
+            "portability. Store portable config with $resource references instead.\n"
+            "Issues found:\n" + "\n".join(f"  - {issue}" for issue in issues)
+        )
+
+    return issues
+
+
+def _is_in_safe_pattern(match: str, config_str: str) -> bool:
+    """Check if a suspicious match is inside a safe pattern (env var).
+
+    Args:
+        match: The suspicious string that was matched
+        config_str: The full config string
+
+    Returns:
+        True if the match appears inside an env var pattern
+    """
+    for safe_pattern in SAFE_PATTERNS:
+        # Check if the suspicious pattern appears inside a safe pattern
+        # e.g., "${HOME}/data" contains "/home" but it's inside ${...}
+        combined_pattern = f"{safe_pattern}[^'\"]*{re.escape(match)}"
+        if re.search(combined_pattern, config_str):
+            return True
+    return False
+
+
+def has_resource_references(config: dict[str, Any]) -> bool:
+    """Check if config contains $resource references.
+
+    $resource references indicate a portable config that needs
+    environment resolution before use.
+
+    Args:
+        config: Configuration dictionary
+
+    Returns:
+        True if config contains $resource references
+
+    Example:
+        ```python
+        # Portable config with $resource refs
+        config = {
+            "bot": {
+                "llm": {"$resource": "default", "type": "llm_providers"},
+            }
+        }
+        assert has_resource_references(config) is True
+
+        # Resolved config (no $resource refs)
+        config = {
+            "bot": {
+                "llm": {"provider": "openai", "model": "gpt-4"},
+            }
+        }
+        assert has_resource_references(config) is False
+        ```
+    """
+    return "$resource" in str(config)
+
+
+def is_portable(config: dict[str, Any]) -> bool:
+    """Check if config appears to be portable.
+
+    A config is considered portable if it either:
+    - Contains $resource references (for late binding), or
+    - Contains no suspicious local values
+
+    Args:
+        config: Configuration dictionary
+
+    Returns:
+        True if config appears to be portable
+
+    Example:
+        ```python
+        # Portable: uses $resource
+        assert is_portable({"llm": {"$resource": "default"}}) is True
+
+        # Portable: no local paths
+        assert is_portable({"llm": {"provider": "openai"}}) is True
+
+        # Not portable: contains local path
+        assert is_portable({"path": "/Users/dev/data"}) is False
+        ```
+    """
+    # If it has $resource refs, it's portable (will be resolved later)
+    if has_resource_references(config):
+        return True
+
+    # Otherwise, check for suspicious patterns
+    issues = validate_portability(config, raise_on_error=False)
+    return len(issues) == 0

dataknobs_bots/tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tools for DynaBot."""
+
+from .knowledge_search import KnowledgeSearchTool
+
+__all__ = ["KnowledgeSearchTool"]

dataknobs_bots/tools/knowledge_search.py

@@ -0,0 +1,113 @@
+"""Knowledge search tool for RAG integration."""
+
+from typing import Any
+
+from dataknobs_llm.tools import Tool
+
+
+class KnowledgeSearchTool(Tool):
+    """Tool for searching the knowledge base.
+
+    This tool allows LLMs to search the bot's knowledge base
+    for relevant information during conversations.
+
+    Example:
+        ```python
+        # Create tool with knowledge base
+        tool = KnowledgeSearchTool(knowledge_base=kb)
+
+        # Register with bot
+        bot.tool_registry.register_tool(tool)
+
+        # LLM can now call the tool
+        results = await tool.execute(
+            query="How do I configure the database?",
+            max_results=3
+        )
+        ```
+    """
+
+    def __init__(self, knowledge_base: Any, name: str = "knowledge_search"):
+        """Initialize knowledge search tool.
+
+        Args:
+            knowledge_base: RAGKnowledgeBase instance to search
+            name: Tool name (default: knowledge_search)
+        """
+        super().__init__(
+            name=name,
+            description="Search the knowledge base for relevant information. "
+            "Use this when you need to find documentation, examples, or "
+            "specific information to answer user questions.",
+        )
+        self.knowledge_base = knowledge_base
+
+    @property
+    def schema(self) -> dict[str, Any]:
+        """Get JSON schema for tool parameters.
+
+        Returns:
+            JSON Schema for the tool parameters
+        """
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "The search query or question to find information about",
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of results to return",
+                    "default": 3,
+                    "minimum": 1,
+                    "maximum": 10,
+                },
+            },
+            "required": ["query"],
+        }
+
+    async def execute(self, query: str, max_results: int = 3, **kwargs: Any) -> dict[str, Any]:
+        """Execute knowledge base search.
+
+        Args:
+            query: Search query text
+            max_results: Maximum number of results (default: 3)
+            **kwargs: Additional arguments (ignored)
+
+        Returns:
+            Dictionary with search results:
+                - query: Original query
+                - results: List of relevant chunks
+                - num_results: Number of results found
+
+        Example:
+            ```python
+            result = await tool.execute(
+                query="How do I configure the database?",
+                max_results=3
+            )
+            for chunk in result['results']:
+                print(f"{chunk['heading_path']}: {chunk['text']}")
+            ```
+        """
+        # Clamp max_results to valid range
+        max_results = max(1, min(10, max_results))
+
+        # Search knowledge base
+        results = await self.knowledge_base.query(query, k=max_results)
+
+        # Format response
+        return {
+            "query": query,
+            "results": [
+                {
+                    "text": r["text"],
+                    "source": r["source"],
+                    "heading": r["heading_path"],
+                    "similarity": round(r["similarity"], 3),
+                }
+                for r in results
+            ],
+            "num_results": len(results),
+        }

dataknobs_bots/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions and helpers for the dataknobs_bots package."""