h-ai-brain 0.0.23__py3-none-any.whl → 0.0.24__py3-none-any.whl

h_ai/__init__.py

@@ -1,3 +1,12 @@
-__all__ = ['HaiService']
+"""
+h_ai package for interacting with LLM models.
 
-from .application.hai_service import HaiService
+This package provides a high-level API for interacting with LLM models.
+Users should import from this package, not from the application, domain, or infrastructure layers directly.
+"""
+
+__all__ = ['GraniteService', 'NomicService', 'BaseModelService']
+
+from .application.services.granite_service import GraniteService
+from .application.services.nomic_service import NomicService
+from .application.services.base_model_service import BaseModelService

h_ai/application/__init__.py

@@ -0,0 +1,12 @@
+"""
+Application layer for the h_ai package.
+
+This package contains the public API for the h_ai package.
+Users should only import from this package, not from the domain or infrastructure layers.
+"""
+
+__all__ = ['GraniteService', 'NomicService', 'BaseModelService']
+
+from .services.granite_service import GraniteService
+from .services.nomic_service import NomicService
+from .services.base_model_service import BaseModelService

h_ai/application/hai_service.py

@@ -1,18 +1,12 @@
-from ..domain.llm_config import LLMConfig
-from ..infrastructure.llm.ollama.ollama_generate_repository import OllamaGenerateRepository
-
-
-class HaiService:
-    def __init__(self, llm_config: LLMConfig):
-        self.llm_config = llm_config
-        self.llm_generate_repository = OllamaGenerateRepository(
-            self.llm_config.url,
-            self.llm_config.model_name,
-            temperature=self.llm_config.temperature,
-            max_tokens=self.llm_config.max_tokens,
-            api_token=self.llm_config.api_token)
-
-    def ask_question(self, question: str, system_prompt: str = None, max_tokens = None) -> str:
-        return self.llm_generate_repository.generate(question, system_prompt, max_tokens)
-
-
+"""
+This file has been intentionally emptied as part of the removal of HaiService.
+HaiService has been deprecated in favor of using GraniteService and NomicService directly.
+
+The correct model names are:
+- nomic-embed-text:137m-v1.5-fp16
+- granite3.3:8b
+
+Please use the model-specific services directly:
+- GraniteService for text generation and chat
+- NomicService for embeddings
+"""

h_ai/application/services/__init__.py

@@ -0,0 +1,11 @@
+"""
+Model-specific services for the h_ai package.
+
+This package contains service classes for specific LLM models.
+"""
+
+__all__ = ['GraniteService', 'NomicService', 'BaseModelService']
+
+from .granite_service import GraniteService
+from .nomic_service import NomicService
+from .base_model_service import BaseModelService

h_ai/application/services/base_model_service.py

@@ -0,0 +1,69 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+
+class BaseModelService(ABC):
+    """
+    Base class for model-specific services.
+    Defines the common interface that all model services must implement.
+    """
+
+    @abstractmethod
+    def generate(self, prompt: str, system_prompt: str = None, max_tokens: int = None) -> Optional[str]:
+        """
+        Generate text using the model.
+
+        Args:
+            prompt: The prompt to generate text from.
+            system_prompt: Optional system prompt to use.
+            max_tokens: Optional maximum number of tokens to generate.
+
+        Returns:
+            Optional[str]: The generated text, or None if an error occurs.
+        """
+        pass
+
+    @abstractmethod
+    def chat(self, message: str, session_id: str, chat_history: List[Dict[str, str]] = None) -> Optional[str]:
+        """
+        Chat with the model.
+
+        Args:
+            message: The user's message.
+            session_id: The ID of the chat session.
+            chat_history: Optional chat history to include in the conversation.
+
+        Returns:
+            Optional[str]: The model's response, or None if an error occurs.
+        """
+        pass
+
+    def embed(self, text: str) -> Optional[List[float]]:
+        """
+        Create an embedding for the given text.
+        Default implementation returns None as not all models support embeddings.
+
+        Args:
+            text: The text to create an embedding for.
+
+        Returns:
+            Optional[List[float]]: The embedding vector, or None if the model doesn't support embeddings.
+        """
+        return None
+
+    def chat_with_documents(self, message: str, session_id: str, documents: List[Dict[str, str]], 
+                           chat_history: List[Dict[str, str]] = None) -> Optional[str]:
+        """
+        Chat with the model using provided documents as context.
+        Default implementation returns None as not all models support document-based chat.
+
+        Args:
+            message: The user's message.
+            session_id: The ID of the chat session.
+            documents: List of documents to use as context.
+            chat_history: Optional chat history to include in the conversation.
+
+        Returns:
+            Optional[str]: The model's response, or None if the model doesn't support document-based chat.
+        """
+        return None

h_ai/application/services/granite_service.py

@@ -0,0 +1,139 @@
+from typing import Dict, List, Optional
+
+from .base_model_service import BaseModelService
+from ...infrastructure.llm.ollama.factories.granite_factory import GraniteModelFactory
+from ...infrastructure.llm.ollama.models.ollama_chat_message import OllamaChatMessage
+
+
+class GraniteService(BaseModelService):
+    """
+    Service for interacting with the Granite model.
+    Provides specialized methods for the Granite model, including document support.
+    """
+
+    def __init__(self, api_url: str, api_token: str = None, temperature: float = 0.6, max_tokens: int = 2500):
+        """
+        Initialize a new GraniteService.
+
+        Args:
+            api_url: The base URL of the LLM API.
+            api_token: Optional API token for authentication.
+            temperature: The temperature to use for generation.
+            max_tokens: The maximum number of tokens to generate.
+
+        Raises:
+            ValueError: If the api_url is empty or None, or if temperature or max_tokens are invalid.
+        """
+        if not api_url:
+            raise ValueError("API URL cannot be empty or None")
+        if temperature < 0:
+            raise ValueError("Temperature must be non-negative")
+        if max_tokens <= 0:
+            raise ValueError("Max tokens must be positive")
+
+        self.api_url = api_url
+        self.api_token = api_token
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+
+        # Create the Granite model factory
+        self.factory = GraniteModelFactory(
+            api_url=api_url,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            api_token=api_token,
+            use_templating=True
+        )
+
+        # Create repositories
+        self.chat_repository = self.factory.create_chat_repository()
+        self.generate_repository = self.factory.create_generate_repository()
+
+    def generate(self, prompt: str, system_prompt: str = None, max_tokens: int = None) -> Optional[str]:
+        """
+        Generate text using the Granite model.
+
+        Args:
+            prompt: The prompt to generate text from.
+            system_prompt: Optional system prompt to use.
+            max_tokens: Optional maximum number of tokens to generate.
+
+        Returns:
+            Optional[str]: The generated text, or None if an error occurs.
+
+        Raises:
+            ValueError: If the prompt is empty or None.
+        """
+        if not prompt:
+            raise ValueError("Prompt cannot be empty or None")
+
+        return self.generate_repository.generate(prompt, system_prompt, max_tokens)
+
+    def chat(self, message: str, session_id: str, chat_history: List[Dict[str, str]] = None) -> Optional[str]:
+        """
+        Chat with the Granite model.
+
+        Args:
+            message: The user's message.
+            session_id: The ID of the chat session.
+            chat_history: Optional chat history to include in the conversation.
+
+        Returns:
+            Optional[str]: The model's response, or None if an error occurs.
+
+        Raises:
+            ValueError: If the message is empty or None, or if the session_id is empty or None.
+        """
+        if not message:
+            raise ValueError("Message cannot be empty or None")
+        if not session_id:
+            raise ValueError("Session ID cannot be empty or None")
+
+        return self.chat_repository.chat(message, session_id, chat_history)
+
+    def chat_with_documents(self, message: str, session_id: str, documents: List[Dict[str, str]],
+                           chat_history: List[Dict[str, str]] = None) -> Optional[str]:
+        """
+        Chat with the Granite model using provided documents as context.
+
+        Args:
+            message: The user's message.
+            session_id: The ID of the chat session.
+            documents: List of documents to use as context. Each document should have 'id' and 'content' keys.
+            chat_history: Optional chat history to include in the conversation.
+
+        Returns:
+            Optional[str]: The model's response, or None if an error occurs.
+
+        Raises:
+            ValueError: If the message is empty or None, or if the session_id is empty or None.
+        """
+        if not message:
+            raise ValueError("Message cannot be empty or None")
+        if not session_id:
+            raise ValueError("Session ID cannot be empty or None")
+        if not documents:
+            raise ValueError("Documents list cannot be empty or None")
+
+        # Start with system prompts and user message
+        messages = []
+
+        # Add document messages
+        for doc in documents:
+            doc_id = doc.get('id', '')
+            content = doc.get('content', '')
+            if content:
+                # Use the document role with optional ID
+                role = f"document{doc_id}" if doc_id else "document"
+                messages.append(OllamaChatMessage(role, content))
+
+        # Add chat history if provided
+        if chat_history:
+            for msg in chat_history:
+                messages.append(OllamaChatMessage(msg.get("role", "user"), msg.get("content", "")))
+
+        # Add the current user message
+        messages.append(OllamaChatMessage("user", message))
+
+        # Call the chat repository with the prepared messages
+        return self.chat_repository.chat_with_messages(messages)

h_ai/application/services/nomic_service.py

@@ -0,0 +1,117 @@
+from typing import Dict, List, Optional
+
+from .base_model_service import BaseModelService
+from ...infrastructure.llm.ollama.factories.nomic_factory import NomicModelFactory
+
+
+class NomicService(BaseModelService):
+    """
+    Service for interacting with the Nomic model.
+    Provides specialized methods for the Nomic model, focusing on embeddings.
+    """
+
+    def __init__(self, api_url: str, api_token: str = None):
+        """
+        Initialize a new NomicService.
+
+        Args:
+            api_url: The base URL of the LLM API.
+            api_token: Optional API token for authentication.
+
+        Raises:
+            ValueError: If the api_url is empty or None.
+        """
+        if not api_url:
+            raise ValueError("API URL cannot be empty or None")
+
+        self.api_url = api_url
+        self.api_token = api_token
+
+        # Create the Nomic model factory
+        self.factory = NomicModelFactory(
+            api_url=api_url,
+            api_token=api_token
+        )
+
+        # Create repositories
+        self.embedding_repository = self.factory.create_embedding_repository()
+
+    def generate(self, prompt: str, system_prompt: str = None, max_tokens: int = None) -> Optional[str]:
+        """
+        Generate text using the Nomic model.
+        Nomic doesn't support text generation, so this always returns None.
+
+        Args:
+            prompt: The prompt to generate text from.
+            system_prompt: Optional system prompt to use.
+            max_tokens: Optional maximum number of tokens to generate.
+
+        Returns:
+            Optional[str]: Always None as Nomic doesn't support text generation.
+        """
+        return None
+
+    def chat(self, message: str, session_id: str, chat_history: List[Dict[str, str]] = None) -> Optional[str]:
+        """
+        Chat with the Nomic model.
+        Nomic doesn't support chat, so this always returns None.
+
+        Args:
+            message: The user's message.
+            session_id: The ID of the chat session.
+            chat_history: Optional chat history to include in the conversation.
+
+        Returns:
+            Optional[str]: Always None as Nomic doesn't support chat.
+        """
+        return None
+
+    def embed(self, text: str) -> Optional[List[float]]:
+        """
+        Create an embedding for the given text using the Nomic model.
+
+        Args:
+            text: The text to create an embedding for.
+
+        Returns:
+            Optional[List[float]]: The embedding vector, or None if an error occurs.
+
+        Raises:
+            ValueError: If the text is empty or None.
+        """
+        if not text:
+            raise ValueError("Text cannot be empty or None")
+
+        return self.embedding_repository.embed(text)
+
+    def batch_embed(self, texts: List[str]) -> Optional[List[List[float]]]:
+        """
+        Create embeddings for multiple texts in a single batch.
+
+        Args:
+            texts: List of texts to create embeddings for.
+
+        Returns:
+            Optional[List[List[float]]]: List of embedding vectors, or None if an error occurs.
+
+        Raises:
+            ValueError: If the texts list is empty or None.
+        """
+        if not texts:
+            raise ValueError("Texts list cannot be empty or None")
+
+        # Filter out empty texts
+        valid_texts = [text for text in texts if text]
+        if not valid_texts:
+            raise ValueError("All texts in the list are empty")
+
+        # Process each text individually
+        # In a real implementation, this could be optimized to use batch processing if supported by the API
+        embeddings = []
+        for text in valid_texts:
+            embedding = self.embedding_repository.embed(text)
+            if embedding is None:
+                return None  # If any embedding fails, return None
+            embeddings.append(embedding)
+
+        return embeddings

h_ai/domain/llm_config.py

@@ -1,7 +1,20 @@
 class LLMConfig:
+    """
+    Configuration for an LLM service.
+    """
     def __init__(self, url: str, model_name: str, temperature: float = 0.6, max_tokens: int = 2500, api_token: str = None):
+        """
+        Initialize a new LLMConfig.
+
+        Args:
+            url: The base URL of the LLM service.
+            model_name: The name of the model to use.
+            temperature: The temperature to use for generation (higher = more creative, lower = more deterministic).
+            max_tokens: The maximum number of tokens to generate.
+            api_token: Optional API token for authentication.
+        """
         self.url = url
         self.model_name = model_name
         self.temperature = temperature
         self.max_tokens = max_tokens
-        self.api_token = api_token
+        self.api_token = api_token

h_ai/domain/model_factory.py

@@ -0,0 +1,44 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from .reasoning.llm_chat_repository import LlmChatRepository
+from .reasoning.llm_embedding_repository import LlmEmbeddingRepository
+from .reasoning.llm_generate_respository import LlmGenerateRepository
+
+
+class ModelFactory(ABC):
+    """
+    Abstract factory for creating model-specific repositories.
+    This factory is responsible for creating the appropriate repositories for a given model.
+    """
+    
+    @abstractmethod
+    def create_chat_repository(self) -> LlmChatRepository:
+        """
+        Creates a chat repository for the model.
+        
+        Returns:
+            LlmChatRepository: A repository for chat interactions with the model.
+        """
+        pass
+    
+    @abstractmethod
+    def create_generate_repository(self) -> LlmGenerateRepository:
+        """
+        Creates a generate repository for the model.
+        
+        Returns:
+            LlmGenerateRepository: A repository for text generation with the model.
+        """
+        pass
+    
+    @abstractmethod
+    def create_embedding_repository(self) -> Optional[LlmEmbeddingRepository]:
+        """
+        Creates an embedding repository for the model.
+        
+        Returns:
+            Optional[LlmEmbeddingRepository]: A repository for creating embeddings with the model,
+                                             or None if the model doesn't support embeddings.
+        """
+        pass

h_ai/domain/reasoning/llm_chat_repository.py

@@ -1,9 +1,46 @@
 from abc import ABC, abstractmethod
-from typing import Optional
+from typing import Optional, List, Dict, Any, Protocol
+
+
+class ChatMessage(Protocol):
+    """Protocol for chat messages."""
+    role: str
+    content: str
 
 
 class LlmChatRepository(ABC):
+    """
+    Repository for chat interactions with an LLM.
+    """
+
+    @abstractmethod
+    def chat(self, user_message: str, session_id: str, chat_history: List[Dict[str, str]] = None) -> Optional[str]:
+        """
+        Chat with the LLM.
+
+        Args:
+            user_message: The user's message.
+            session_id: The ID of the chat session.
+            chat_history: Optional chat history to include in the conversation.
+
+        Returns:
+            Optional[str]: The LLM's response, or None if the request failed.
+        """
+        ...
 
     @abstractmethod
-    def chat(self, user_message: str, session_id: str) -> Optional[str]:
+    def chat_with_messages(self, messages: List[Any]) -> Optional[str]:
+        """
+        Chat with the model using a custom list of messages.
+
+        This method allows for more flexibility in message formatting, such as including
+        document messages or other special message types.
+
+        Args:
+            messages: The list of messages to send to the model. Each message should have
+                     'role' and 'content' attributes or keys.
+
+        Returns:
+            Optional[str]: The model's response, or None if the request failed.
+        """
         ...

h_ai/domain/reasoning/llm_embedding_repository.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+class LlmEmbeddingRepository(ABC):
+    """
+    Repository for creating embeddings with an LLM.
+    """
+
+    @abstractmethod
+    def embed(self, text: str) -> Optional[List[float]]:
+        """
+        Create an embedding for the given text.
+
+        Args:
+            text: The text to create an embedding for.
+
+        Returns:
+            Optional[List[float]]: The embedding vector, or None if the request failed.
+        """
+        pass

h_ai/domain/reasoning/llm_generate_respository.py

@@ -1,6 +1,23 @@
-from typing import Protocol
+from abc import ABC, abstractmethod
+from typing import Optional
 
 
-class LlmGenerateRepository(Protocol):
-    def generate(self, user_prompt: str, system_prompt: str, session_id: str = None) -> str:
-        ...
+class LlmGenerateRepository(ABC):
+    """
+    Repository for text generation with an LLM.
+    """
+
+    @abstractmethod
+    def generate(self, user_prompt: str, system_prompt: str = None, max_tokens: int = None) -> Optional[str]:
+        """
+        Generate text using the LLM.
+
+        Args:
+            user_prompt: The prompt to generate text from.
+            system_prompt: Optional system prompt to use.
+            max_tokens: Optional maximum number of tokens to generate.
+
+        Returns:
+            Optional[str]: The generated text, or None if the request failed.
+        """
+        ...

h_ai/domain/reasoning/llm_tool_repository.py

@@ -5,10 +5,33 @@ from ...domain.reasoning.tool_message import ToolMessage
 
 
 class LlmToolRepository(ABC):
+    """
+    Repository for tool interactions with an LLM.
+    """
+
     @abstractmethod
     def find_tools_in_message(self, message: str) -> List[ToolMessage] | None:
+        """
+        Extract tool calls from a message.
+
+        Args:
+            message: The message to extract tool calls from.
+
+        Returns:
+            List[ToolMessage] | None: A list of tool messages, or None if no tools were found.
+        """
         ...
 
     @abstractmethod
-    def build_tool_response_prompt(self, question: str, tool_results: list[str])-> str|None:
+    def build_tool_response_prompt(self, question: str, tool_results: list[str]) -> str | None:
+        """
+        Build a prompt for the LLM to respond to tool results.
+
+        Args:
+            question: The original question that triggered the tool calls.
+            tool_results: The results from executing the tools.
+
+        Returns:
+            str | None: The prompt for the LLM, or None if the prompt could not be built.
+        """
         ...