bot-knows 0.1.0__py3-none-any.whl

bot_knows/infra/redis/client.py

@@ -0,0 +1,193 @@
+"""Redis client for bot_knows.
+
+This module provides an optional async Redis client wrapper.
+Redis is used for caching and is optional - if not configured,
+caching will be disabled gracefully.
+"""
+
+from typing import Any
+
+from redis.asyncio import Redis
+
+from bot_knows.config import RedisSettings
+from bot_knows.logging import get_logger
+
+__all__ = [
+    "RedisClient",
+]
+
+logger = get_logger(__name__)
+
+
+class RedisClient:
+    """Async Redis client wrapper (optional).
+
+    Provides connection management for Redis caching.
+    If Redis is not configured or unavailable, operations
+    will fail gracefully.
+
+    Example:
+        client = RedisClient(settings)
+        if await client.connect():
+            await client.set("key", "value")
+            value = await client.get("key")
+        await client.disconnect()
+    """
+
+    def __init__(self, settings: RedisSettings):
+        """Initialize client with settings.
+
+        Args:
+            settings: Redis connection settings
+        """
+        self._settings = settings
+        self._redis: Redis | None = None  # type: ignore[type-arg]
+        self._connected = False
+
+    @property
+    def is_enabled(self) -> bool:
+        """Check if Redis is enabled in configuration."""
+        return self._settings.enabled and self._settings.url is not None
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if connected to Redis."""
+        return self._connected
+
+    async def connect(self) -> bool:
+        """Initialize connection to Redis.
+
+        Returns:
+            True if connected successfully, False otherwise
+        """
+        if self._redis is not None:
+            return self._connected
+
+        if not self.is_enabled:
+            logger.info("redis_disabled", reason="not configured")
+            return False
+
+        try:
+            self._redis = Redis.from_url(
+                self._settings.url,  # type: ignore[arg-type]
+                decode_responses=True,
+            )
+            # Verify connection
+            await self._redis.ping()
+            self._connected = True
+            logger.info("connected_to_redis", url=self._settings.url)
+            return True
+        except Exception as e:
+            logger.warning(
+                "redis_connection_failed",
+                error=str(e),
+                reason="Redis unavailable, caching disabled",
+            )
+            self._redis = None
+            self._connected = False
+            return False
+
+    async def disconnect(self) -> None:
+        """Close connection to Redis."""
+        if self._redis:
+            await self._redis.close()
+            self._redis = None
+            self._connected = False
+            logger.info("disconnected_from_redis")
+
+    @property
+    def client(self) -> Redis | None:  # type: ignore[type-arg]
+        """Get Redis client instance.
+
+        Returns:
+            Redis client if connected, None otherwise
+        """
+        return self._redis if self._connected else None
+
+    async def get(self, key: str) -> str | None:
+        """Get value from Redis.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found/not connected
+        """
+        if not self._connected or not self._redis:
+            return None
+        try:
+            result = await self._redis.get(key)
+            return result  # type: ignore[return-value]
+        except Exception as e:
+            logger.debug("redis_get_error", key=key, error=str(e))
+            return None
+
+    async def set(
+        self,
+        key: str,
+        value: str,
+        ex: int | None = None,
+    ) -> bool:
+        """Set value in Redis.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ex: Expiration time in seconds
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self._connected or not self._redis:
+            return False
+        try:
+            await self._redis.set(key, value, ex=ex)
+            return True
+        except Exception as e:
+            logger.debug("redis_set_error", key=key, error=str(e))
+            return False
+
+    async def delete(self, key: str) -> bool:
+        """Delete key from Redis.
+
+        Args:
+            key: Cache key to delete
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self._connected or not self._redis:
+            return False
+        try:
+            await self._redis.delete(key)
+            return True
+        except Exception as e:
+            logger.debug("redis_delete_error", key=key, error=str(e))
+            return False
+
+    async def exists(self, key: str) -> bool:
+        """Check if key exists in Redis.
+
+        Args:
+            key: Cache key to check
+
+        Returns:
+            True if exists, False otherwise
+        """
+        if not self._connected or not self._redis:
+            return False
+        try:
+            result = await self._redis.exists(key)
+            return bool(result)
+        except Exception as e:
+            logger.debug("redis_exists_error", key=key, error=str(e))
+            return False
+
+    async def __aenter__(self) -> "RedisClient":
+        """Async context manager entry."""
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.disconnect()

bot_knows/interfaces/__init__.py

@@ -0,0 +1,18 @@
+"""Interface contracts for bot_knows.
+
+This module exports all Protocol-based interfaces for dependency injection.
+"""
+
+from bot_knows.interfaces.embedding import EmbeddingServiceInterface
+from bot_knows.interfaces.graph import GraphServiceInterface
+from bot_knows.interfaces.llm import LLMInterface
+from bot_knows.interfaces.recall import RecallServiceInterface
+from bot_knows.interfaces.storage import StorageInterface
+
+__all__ = [
+    "EmbeddingServiceInterface",
+    "GraphServiceInterface",
+    "LLMInterface",
+    "RecallServiceInterface",
+    "StorageInterface",
+]

bot_knows/interfaces/embedding.py

@@ -0,0 +1,55 @@
+"""Embedding service interface for bot_knows.
+
+This module defines the Protocol for embedding generation services.
+"""
+
+from typing import ClassVar, Protocol, runtime_checkable
+
+__all__ = [
+    "EmbeddingServiceInterface",
+]
+
+
+@runtime_checkable
+class EmbeddingServiceInterface(Protocol):
+    """Contract for embedding generation services.
+
+    Implementations should provide methods for generating
+    embeddings from text and computing similarity scores.
+    """
+
+    config_class: ClassVar[type | None] = None
+
+    async def embed(self, text: str) -> list[float]:
+        """Generate embedding vector for text.
+
+        Args:
+            text: Input text to embed
+
+        Returns:
+            Embedding vector as list of floats
+        """
+        ...
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for multiple texts.
+
+        Args:
+            texts: List of input texts
+
+        Returns:
+            List of embedding vectors
+        """
+        ...
+
+    async def similarity(self, embedding1: list[float], embedding2: list[float]) -> float:
+        """Compute cosine similarity between embeddings.
+
+        Args:
+            embedding1: First embedding vector
+            embedding2: Second embedding vector
+
+        Returns:
+            Similarity score between 0.0 and 1.0
+        """
+        ...

bot_knows/interfaces/graph.py

@@ -0,0 +1,194 @@
+"""Graph service interface for bot_knows.
+
+This module defines the Protocol for graph database operations.
+"""
+
+from typing import Any, ClassVar, Protocol, runtime_checkable
+
+from bot_knows.models.chat import ChatDTO
+from bot_knows.models.message import MessageDTO
+from bot_knows.models.topic import TopicDTO, TopicEvidenceDTO
+
+__all__ = [
+    "GraphServiceInterface",
+]
+
+
+@runtime_checkable
+class GraphServiceInterface(Protocol):
+    """Contract for graph database operations.
+
+    Implementations should provide methods for creating nodes,
+    edges, and querying the knowledge graph.
+    """
+
+    config_class: ClassVar[type | None] = None
+
+    # Node operations
+    async def create_chat_node(self, chat: ChatDTO) -> str:
+        """Create a Chat node in the graph.
+
+        Args:
+            chat: Chat data to store
+
+        Returns:
+            Node ID
+        """
+        ...
+
+    async def create_message_node(self, message: MessageDTO) -> str:
+        """Create a Message node in the graph.
+
+        Args:
+            message: Message data to store
+
+        Returns:
+            Node ID
+        """
+        ...
+
+    async def create_topic_node(self, topic: TopicDTO) -> str:
+        """Create a Topic node in the graph.
+
+        Args:
+            topic: Topic data to store
+
+        Returns:
+            Node ID
+        """
+        ...
+
+    async def update_topic_node(self, topic: TopicDTO) -> None:
+        """Update an existing Topic node.
+
+        Args:
+            topic: Updated topic data
+        """
+        ...
+
+    # Edge operations
+    async def create_is_part_of_edge(self, message_id: str, chat_id: str) -> None:
+        """Create IS_PART_OF edge: (Message)-[:IS_PART_OF]->(Chat).
+
+        Args:
+            message_id: Source message ID
+            chat_id: Target chat ID
+        """
+        ...
+
+    async def create_follows_after_edge(
+        self,
+        message_id: str,
+        previous_message_id: str,
+    ) -> None:
+        """Create FOLLOWS_AFTER edge: (Message)-[:FOLLOWS_AFTER]->(Message).
+
+        Args:
+            message_id: Current message ID
+            previous_message_id: Previous message ID
+        """
+        ...
+
+    async def create_is_supported_by_edge(
+        self,
+        topic_id: str,
+        message_id: str,
+        evidence: TopicEvidenceDTO,
+    ) -> None:
+        """Create IS_SUPPORTED_BY edge with evidence properties.
+
+        (Topic)-[:IS_SUPPORTED_BY {evidence properties}]->(Message)
+
+        Args:
+            topic_id: Topic ID
+            message_id: Supporting message ID
+            evidence: Evidence data to store as edge properties
+        """
+        ...
+
+    async def create_potentially_duplicate_of_edge(
+        self,
+        topic_id: str,
+        existing_topic_id: str,
+        similarity: float,
+    ) -> None:
+        """Create POTENTIALLY_DUPLICATE_OF edge between topics.
+
+        Args:
+            topic_id: New topic ID
+            existing_topic_id: Existing similar topic ID
+            similarity: Similarity score between topics
+        """
+        ...
+
+    async def create_relates_to_edge(
+        self,
+        topic_id: str,
+        related_topic_id: str,
+        relation_type: str,
+        weight: float,
+    ) -> None:
+        """Create RELATES_TO edge between topics.
+
+        Args:
+            topic_id: Source topic ID
+            related_topic_id: Related topic ID
+            relation_type: Type of relationship
+            weight: Relationship weight (0.0 - 1.0)
+        """
+        ...
+
+    # Query operations
+    async def get_messages_for_chat(self, chat_id: str) -> list[MessageDTO]:
+        """Get all messages in a chat, ordered by FOLLOWS_AFTER.
+
+        Args:
+            chat_id: Chat ID to query
+
+        Returns:
+            List of messages in order
+        """
+        ...
+
+    async def get_related_topics(
+        self,
+        topic_id: str,
+        limit: int = 10,
+    ) -> list[tuple[str, float]]:
+        """Get topics related to a given topic.
+
+        Args:
+            topic_id: Topic to find relations for
+            limit: Maximum number of results
+
+        Returns:
+            List of (topic_id, weight) tuples
+        """
+        ...
+
+    async def get_topic_evidence(
+        self,
+        topic_id: str,
+    ) -> list[dict[str, Any]]:
+        """Get all evidence for a topic from IS_SUPPORTED_BY edges.
+
+        Args:
+            topic_id: Topic ID
+
+        Returns:
+            List of evidence properties from edges
+        """
+        ...
+
+    async def get_chat_topics(self, chat_id: str) -> list[str]:
+        """Get all topic IDs associated with a chat's messages.
+
+        Traverses: (Chat)<-[:IS_PART_OF]-(Message)<-[:IS_SUPPORTED_BY]-(Topic)
+
+        Args:
+            chat_id: Chat ID to query
+
+        Returns:
+            List of unique topic IDs
+        """
+        ...

bot_knows/interfaces/llm.py

@@ -0,0 +1,70 @@
+"""LLM interface for bot_knows.
+
+This module defines the Protocol for LLM interactions
+including chat classification and topic extraction.
+"""
+
+from typing import ClassVar, Protocol, runtime_checkable
+
+from bot_knows.models.chat import ChatCategory
+
+__all__ = [
+    "LLMInterface",
+]
+
+
+@runtime_checkable
+class LLMInterface(Protocol):
+    """Contract for LLM interactions.
+
+    Implementations should provide methods for classifying chats
+    and extracting topics from messages.
+    """
+
+    config_class: ClassVar[type | None] = None
+
+    async def classify_chat(
+        self,
+        first_pair: tuple[str, str],
+        last_pair: tuple[str, str],
+    ) -> tuple[ChatCategory, list[str]]:
+        """Classify a chat and extract tags.
+
+        Uses the first and last user-assistant pairs to determine
+        the chat's category and relevant tags.
+
+        Args:
+            first_pair: (user_message, assistant_message) from start of chat
+            last_pair: (user_message, assistant_message) from end of chat
+
+        Returns:
+            Tuple of (ChatCategory, list of tags)
+        """
+        ...
+
+    async def extract_topics(
+        self,
+        user_content: str,
+        assistant_content: str,
+    ) -> list[tuple[str, float]]:
+        """Extract topic candidates from a message pair.
+
+        Args:
+            user_content: User's message content
+            assistant_content: Assistant's response content
+
+        Returns:
+            List of (topic_name, confidence) tuples
+        """
+        ...
+
+    async def normalize_topic_name(self, extracted_name: str) -> str:
+        """Normalize a topic name to canonical form.
+
+        Args:
+            extracted_name: Raw extracted topic name
+
+        Returns:
+            Normalized canonical topic name
+        """
+        ...

bot_knows/interfaces/recall.py

@@ -0,0 +1,92 @@
+"""Recall service interface for bot_knows.
+
+This module defines the Protocol for recall/spaced repetition operations.
+"""
+
+from typing import Literal, Protocol, runtime_checkable
+
+from bot_knows.models.recall import RecallItemDTO, TopicRecallStateDTO
+
+__all__ = [
+    "RecallServiceInterface",
+]
+
+
+@runtime_checkable
+class RecallServiceInterface(Protocol):
+    """Contract for recall/spaced repetition operations.
+
+    Implementations should provide methods for reinforcing topics,
+    applying decay, and getting topics due for review.
+    """
+
+    async def reinforce(
+        self,
+        topic_id: str,
+        confidence: float,
+        novelty_factor: float = 1.0,
+        context: Literal["passive", "active", "recall"] = "passive",
+    ) -> TopicRecallStateDTO:
+        """Reinforce a topic's recall strength.
+
+        Formula:
+            delta = confidence * novelty_factor * context_weight
+            strength = min(1.0, strength + delta)
+            stability += k * confidence
+
+        Args:
+            topic_id: Topic to reinforce
+            confidence: Evidence confidence (0.0 - 1.0)
+            novelty_factor: How novel this reinforcement is
+            context: Reinforcement context (passive=0.2, active=0.6, recall=1.0)
+
+        Returns:
+            Updated recall state
+        """
+        ...
+
+    async def apply_decay(
+        self,
+        topic_id: str,
+        current_time: int | None = None,
+    ) -> TopicRecallStateDTO:
+        """Apply time-based decay to a topic.
+
+        Formula:
+            strength *= exp(-Δt / (stability * 86400))
+
+        Args:
+            topic_id: Topic to decay
+            current_time: Current time in epoch seconds (default: now)
+
+        Returns:
+            Updated recall state
+        """
+        ...
+
+    async def batch_decay_update(self) -> int:
+        """Apply decay to all topics (scheduled task).
+
+        Returns:
+            Number of topics updated
+        """
+        ...
+
+    async def get_due_topics(
+        self,
+        threshold: float = 0.3,
+        limit: int = 10,
+    ) -> list[RecallItemDTO]:
+        """Get topics due for recall review.
+
+        Topics with strength below threshold are considered due.
+        Results are sorted by due_score (higher = more urgent).
+
+        Args:
+            threshold: Strength threshold for being "due"
+            limit: Maximum number of topics to return
+
+        Returns:
+            List of RecallItemDTO sorted by priority
+        """
+        ...