hammad-python 0.0.18__py3-none-any.whl → 0.0.20__py3-none-any.whl

hammad/genai/agents/types/agent_stream.py

@@ -0,0 +1,242 @@
+"""hammad.genai.agents.types.agent_stream"""
+
+from typing import (
+    Generic,
+    TypeVar,
+    Iterator,
+    AsyncIterator,
+    List,
+    Any,
+    Dict,
+    Optional,
+    TYPE_CHECKING,
+    Type,
+    Union,
+    Literal,
+)
+from contextlib import contextmanager, asynccontextmanager
+
+from ...types.base import BaseGenAIModelStream
+from ...types.tools import (
+    Tool,
+    execute_tools_from_language_model_response,
+)
+from ...models.language.model import LanguageModel
+from ...models.language.types import (
+    LanguageModelMessages,
+    LanguageModelResponse,
+    LanguageModelResponseChunk,
+    LanguageModelStream,
+    LanguageModelSettings,
+)
+from ...models.language.utils.requests import (
+    parse_messages_input as parse_messages,
+    consolidate_system_messages,
+)
+
+from .agent_response import (
+    AgentResponse,
+    _create_agent_response_from_language_model_response,
+)
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+
+T = TypeVar("T")
+
+
+class AgentResponseChunk(LanguageModelResponseChunk[T], Generic[T]):
+    """A chunk from an agent response stream representing a single step."""
+
+    def __init__(
+        self,
+        step_number: int,
+        response: LanguageModelResponse[str],
+        output: T | None = None,
+        content: str | None = None,
+        model: str | None = None,
+        is_final: bool = False,
+        **kwargs: Any,
+    ):
+        """Initialize a AgentResponseChunk.
+
+        Args:
+            step_number: The step number of this chunk
+            response: The language model response for this step
+            output: The output value
+            content: The content string
+            model: The model name
+            is_final: Whether this is the final chunk
+            **kwargs: Additional keyword arguments
+        """
+        super().__init__(
+            output=output if output is not None else response.output,
+            content=content if content is not None else response.content,
+            model=model if model is not None else response.model,
+            is_final=is_final,
+            **kwargs,
+        )
+        self.step_number = step_number
+        self.response = response
+
+    def __bool__(self) -> bool:
+        """Check if this chunk has meaningful content."""
+        return bool(self.response)
+
+    def __str__(self) -> str:
+        """String representation of the chunk."""
+        return f"AgentResponseChunk(step={self.step_number}, final={self.is_final})"
+
+
+class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
+    """Stream of agent responses that can be used in sync and async contexts."""
+
+    def __init__(
+        self,
+        agent: "Agent[T]",
+        messages: LanguageModelMessages,
+        model: Optional[Union[LanguageModel, str]] = None,
+        max_steps: Optional[int] = None,
+        context: Optional[Any] = None,
+        output_type: Optional[Type[T]] = None,
+        stream: bool = False,
+        **kwargs: Any,
+    ):
+        self.agent = agent
+        self.messages = messages
+        self.context = context
+        self.output_type = output_type
+        self.stream = stream
+        self.kwargs = kwargs
+        self.current_step = 0
+        self.steps: List[LanguageModelResponse[str]] = []
+        self.current_messages = parse_messages(messages)
+        self.is_done = False
+        self._final_response: Optional[LanguageModelResponse[str]] = None
+
+        # Model setup
+        if model is None:
+            self.model = agent.model
+        elif isinstance(model, str):
+            self.model = LanguageModel(model=model)
+        else:
+            self.model = model
+
+        # Max steps setup
+        self.max_steps = max_steps or agent.settings.max_steps
+
+        # Context handling
+        self.current_context = context
+
+        # Model kwargs setup
+        self.model_kwargs = kwargs.copy()
+        if output_type:
+            self.model_kwargs["type"] = output_type
+        if agent.instructor_mode:
+            self.model_kwargs["instructor_mode"] = agent.instructor_mode
+        if stream:
+            self.model_kwargs["stream"] = stream
+
+    def _format_messages(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        if self.agent.instructions:
+            system_message = {"role": "system", "content": self.agent.instructions}
+            messages = [system_message] + messages
+        return consolidate_system_messages(messages)
+
+    def _process_response(
+        self, response: LanguageModelResponse
+    ) -> AgentResponseChunk[T]:
+        self.current_messages.append(response.to_message())
+
+        if response.has_tool_calls:
+            tool_responses = execute_tools_from_language_model_response(
+                tools=self.agent.tools, response=response
+            )
+            for tool_resp in tool_responses:
+                self.current_messages.append(tool_resp.to_dict())
+
+            self.steps.append(response)
+            return AgentResponseChunk(
+                step_number=self.current_step, response=response, is_final=False
+            )
+        else:
+            self.is_done = True
+            self._final_response = response
+            return AgentResponseChunk(
+                step_number=self.current_step, response=response, is_final=True
+            )
+
+    def __iter__(self) -> Iterator[AgentResponseChunk[T]]:
+        # The context manager handling should be managed by the agent's run method
+        while not self.is_done and self.current_step < self.max_steps:
+            self.current_step += 1
+
+            formatted_messages = self.current_messages
+            if self.current_step == 1:
+                formatted_messages = self._format_messages(self.current_messages)
+
+            response = self.model.run(
+                messages=formatted_messages,
+                tools=[tool.model_dump() for tool in self.agent.tools]
+                if self.agent.tools
+                else None,
+                **self.model_kwargs,
+            )
+
+            chunk = self._process_response(response)
+            yield chunk
+            if chunk.is_final:
+                break
+
+    def __aiter__(self) -> AsyncIterator[AgentResponseChunk[T]]:
+        return self
+
+    async def __anext__(self) -> AgentResponseChunk[T]:
+        if self.is_done or self.current_step >= self.max_steps:
+            raise StopAsyncIteration
+
+        # The context manager handling should be managed by the agent's run method
+        self.current_step += 1
+
+        formatted_messages = self.current_messages
+        if self.current_step == 1:
+            formatted_messages = self._format_messages(self.current_messages)
+
+        response = await self.model.async_run(
+            messages=formatted_messages,
+            tools=[tool.model_dump() for tool in self.agent.tools]
+            if self.agent.tools
+            else None,
+            **self.model_kwargs,
+        )
+
+        chunk = self._process_response(response)
+        if chunk.is_final:
+            self.is_done = True
+        return chunk
+
+    def _build_response(self) -> AgentResponse[T]:
+        if self._final_response:
+            final_response = self._final_response
+        elif self.steps:
+            final_response = self.steps[-1]
+        else:
+            raise RuntimeError("No response generated by the agent.")
+
+        return _create_agent_response_from_language_model_response(
+            response=final_response,
+            steps=self.steps,
+            context=self.current_context,
+        )
+
+    def collect(self) -> AgentResponse[T]:
+        """Collect all steps and return final response."""
+        for _ in self:
+            pass
+        return self._build_response()
+
+    async def async_collect(self) -> AgentResponse[T]:
+        """Collect all steps and return final response."""
+        async for _ in self:
+            pass
+        return self._build_response()

hammad/genai/models/__init__.py

@@ -0,0 +1 @@
+"""hammad.genai.models"""

hammad/genai/models/embeddings/__init__.py

@@ -0,0 +1,39 @@
+"""hammad.genai.models.embeddings"""
+
+from typing import TYPE_CHECKING
+from ...._internal import create_getattr_importer
+
+
+if TYPE_CHECKING:
+    from .model import EmbeddingModel
+    from .run import (
+        run_embedding_model,
+        async_run_embedding_model,
+    )
+    from .types import (
+        Embedding,
+        EmbeddingModelResponse,
+        EmbeddingModelSettings,
+    )
+
+
+__all__ = [
+    "EmbeddingModel",
+    # hammad.genai.models.embeddings.run
+    "run_embedding_model",
+    "async_run_embedding_model",
+    # hammad.genai.models.embeddings.types.embedding
+    "Embedding",
+    # hammad.genai.models.embeddings.types.embedding_model_response
+    "EmbeddingModelResponse",
+    # hammad.genai.models.embeddings.types.embedding_model_settings
+    "EmbeddingModelSettings",
+]
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    """Return the list of attributes to be shown in the REPL."""
+    return __all__

hammad/genai/{embedding_models/embedding_model.py → models/embeddings/model.py}

@@ -2,7 +2,7 @@
 
 import asyncio
 from dataclasses import dataclass
-from typing import Any, List, Literal, Optional, TYPE_CHECKING
+from typing import Any, List, Optional
 import sys
 
 if sys.version_info >= (3, 12):
@@ -10,21 +10,17 @@ if sys.version_info >= (3, 12):
 else:
     from typing_extensions import TypedDict
 
-if TYPE_CHECKING:
-    try:
-        from litellm import EmbeddingResponse as _LitellmEmbeddingResponse
-    except ImportError:
-        _LitellmEmbeddingResponse = Any
-
-from ..language_models.language_model import _AIProvider
-from .embedding_model_request import EmbeddingModelRequest
-from .embedding_model_name import EmbeddingModelName
-from .embedding_model_response import (
+from ..model_provider import litellm
+
+from .types import (
+    EmbeddingModelName,
+    EmbeddingModelRunParams,
+    EmbeddingModelSettings,
     Embedding,
     EmbeddingUsage,
     EmbeddingModelResponse,
 )
-from ...formatting.text import convert_to_text
+from ....formatting.text import convert_to_text
 
 
 __all__ = (
@@ -43,7 +39,9 @@ class EmbeddingModelError(Exception):
         super().__init__(self.message)
 
 
-def _parse_litellm_response_to_embedding_model_response(response: "_LitellmEmbeddingResponse") -> EmbeddingModelResponse:
+def _parse_litellm_response_to_embedding_model_response(
+    response: "litellm.EmbeddingResponse",
+) -> EmbeddingModelResponse:
     """Parse the response from `litellm` to an `EmbeddingModelResponse` object."""
     try:
         embedding_data: List[Embedding] = []
@@ -57,10 +55,11 @@ def _parse_litellm_response_to_embedding_model_response(response: "_LitellmEmbed
             total_tokens=response.usage.total_tokens,
         )
         return EmbeddingModelResponse(
-            data=embedding_data,
+            output=embedding_data,
             model=response.model,
             object="list",
             usage=usage,
+            type="embedding_model",
         )
     except Exception as e:
         raise EmbeddingModelError(
@@ -73,19 +72,30 @@ def _parse_litellm_response_to_embedding_model_response(response: "_LitellmEmbed
 class EmbeddingModel:
     """Embeddings provider client that utilizes the `litellm` module
     when generating embeddings."""
-    
-    model: EmbeddingModelName = "openai/text-embedding-3-small"
-    
+
+    model: EmbeddingModelName | str = "openai/text-embedding-3-small"
+
+    base_url: Optional[str] = None
+    """Optional base URL for a custom embedding provider."""
+
+    api_key: Optional[str] = None
+    """Optional API key for a custom embedding provider."""
+
+    api_type: Optional[str] = None
+    """Optional API type for a custom embedding provider."""
+
+    api_version: Optional[str] = None
+    """Optional API version for a custom embedding provider."""
+
+    settings: EmbeddingModelSettings = EmbeddingModelSettings()
+    """Optional settings for the embedding model."""
+
     async def async_run(
         self,
         input: List[Any] | Any,
         dimensions: Optional[int] = None,
         encoding_format: Optional[str] = None,
         timeout=600,
-        api_base: Optional[str] = None,
-        api_version: Optional[str] = None,
-        api_key: Optional[str] = None,
-        api_type: Optional[str] = None,
         caching: bool = False,
         user: Optional[str] = None,
         format: bool = False,
@@ -122,24 +132,26 @@ class EmbeddingModel:
                         i,
                     )
 
-        async_embedding_fn = _AIProvider.get_litellm().aembedding
+        async_embedding_fn = litellm.aembedding
 
         try:
             response = await async_embedding_fn(
                 model=self.model,
                 input=input,
-                dimensions=dimensions,
-                encoding_format=encoding_format,
-                timeout=timeout,
-                api_base=api_base,
-                api_version=api_version,
-                api_key=api_key,
-                api_type=api_type,
-                caching=caching,
-                user=user,
+                dimensions=dimensions or self.settings.dimensions,
+                encoding_format=encoding_format or self.settings.encoding_format,
+                timeout=timeout or self.settings.timeout,
+                api_base=self.base_url or self.settings.api_base,
+                api_version=self.api_version or self.settings.api_version,
+                api_key=self.api_key or self.settings.api_key,
+                api_type=self.api_type or self.settings.api_type,
+                caching=caching or self.settings.caching,
+                user=user or self.settings.user,
             )
         except Exception as e:
-            raise EmbeddingModelError(f"Error in embedding model request: {e}", response=None) from e
+            raise EmbeddingModelError(
+                f"Error in embedding model request: {e}", response=None
+            ) from e
 
         return _parse_litellm_response_to_embedding_model_response(response)
 
@@ -149,10 +161,6 @@ class EmbeddingModel:
         dimensions: Optional[int] = None,
         encoding_format: Optional[str] = None,
         timeout=600,
-        api_base: Optional[str] = None,
-        api_version: Optional[str] = None,
-        api_key: Optional[str] = None,
-        api_type: Optional[str] = None,
         caching: bool = False,
         user: Optional[str] = None,
         format: bool = False,
@@ -182,12 +190,8 @@ class EmbeddingModel:
                 dimensions=dimensions,
                 encoding_format=encoding_format,
                 timeout=timeout,
-                api_base=api_base,
-                api_version=api_version,
-                api_key=api_key,
-                api_type=api_type,
                 caching=caching,
                 user=user,
                 format=format,
             )
-        )
+        )

hammad/genai/{embedding_models → models/embeddings}/run.py

@@ -5,9 +5,11 @@ Standalone functions for running embedding models with full parameter typing.
 
 from typing import Any, List, Optional, overload, Union
 
-from .embedding_model_name import EmbeddingModelName
-from .embedding_model import EmbeddingModel
-from .embedding_model_response import EmbeddingModelResponse
+from .types import (
+    EmbeddingModelName,
+    EmbeddingModelResponse,
+)
+from .model import EmbeddingModel
 
 __all__ = [
     "run_embedding_model",
@@ -54,7 +56,7 @@ def run_embedding_model(
     format: bool = False,
 ) -> EmbeddingModelResponse:
     """Run an embedding model with the given input.
-    
+
     Args:
         input: The input text/content to generate embeddings for
         model: The embedding model to use
@@ -68,7 +70,7 @@ def run_embedding_model(
         caching: Whether to cache the request
         user: The user to use for the request
         format: Whether to format each non-string input as a markdown string
-        
+
     Returns:
         EmbeddingModelResponse: The embedding response
     """
@@ -127,7 +129,7 @@ async def async_run_embedding_model(
     format: bool = False,
 ) -> EmbeddingModelResponse:
     """Asynchronously run an embedding model with the given input.
-    
+
     Args:
         input: The input text/content to generate embeddings for
         model: The embedding model to use
@@ -141,7 +143,7 @@ async def async_run_embedding_model(
         caching: Whether to cache the request
         user: The user to use for the request
         format: Whether to format each non-string input as a markdown string
-        
+
     Returns:
         EmbeddingModelResponse: The embedding response
     """
@@ -158,4 +160,4 @@ async def async_run_embedding_model(
         caching=caching,
         user=user,
         format=format,
-    )
+    )

hammad/genai/models/embeddings/types/__init__.py

@@ -0,0 +1,37 @@
+"""hammad.genai.models.embeddings.types"""
+
+from typing import TYPE_CHECKING
+from ....._internal import create_getattr_importer
+
+
+if TYPE_CHECKING:
+    from .embedding_model_name import EmbeddingModelName
+    from .embedding_model_run_params import EmbeddingModelRunParams
+    from .embedding_model_response import (
+        Embedding,
+        EmbeddingUsage,
+        EmbeddingModelResponse,
+    )
+    from .embedding_model_settings import EmbeddingModelSettings
+
+
+__all__ = [
+    # hammad.genai.models.embeddings.types.embedding_model_name
+    "EmbeddingModelName",
+    # hammad.genai.models.embeddings.types.embedding_model_run_params
+    "EmbeddingModelRunParams",
+    # hammad.genai.models.embeddings.types.embedding_model_response
+    "Embedding",
+    "EmbeddingUsage",
+    "EmbeddingModelResponse",
+    # hammad.genai.models.embeddings.types.embedding_model_settings
+    "EmbeddingModelSettings",
+]
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    """Return the list of attributes to be shown in the REPL."""
+    return __all__

hammad/genai/{embedding_models → models/embeddings/types}/embedding_model_name.py

@@ -3,9 +3,7 @@
 from typing import Literal
 
 
-__all__ = (
-    "EmbeddingModelName",
-)
+__all__ = ("EmbeddingModelName",)
 
 
 EmbeddingModelName = Literal[
@@ -74,4 +72,4 @@ EmbeddingModelName = Literal[
     "ollama/all-minilm",
     "ollama/nomic-embed-text",
 ]
-"""Common embedding models supported by `litellm`."""
+"""Common embedding models supported by `litellm`."""

hammad/genai/{embedding_models → models/embeddings/types}/embedding_model_response.py

@@ -4,6 +4,8 @@ from typing import List, Literal
 
 from pydantic import BaseModel
 
+from ....types.base import BaseGenAIModelResponse
+
 __all__ = (
     "Embedding",
     "EmbeddingUsage",
@@ -41,8 +43,8 @@ class EmbeddingUsage(BaseModel):
     """The total number of tokens used by the request."""
 
 
-class EmbeddingModelResponse(BaseModel):
-    data: List[Embedding]
+class EmbeddingModelResponse(BaseGenAIModelResponse[List[Embedding]]):
+    output: List[Embedding]
     """The list of embeddings generated by the model."""
 
     model: str
@@ -54,10 +56,15 @@ class EmbeddingModelResponse(BaseModel):
     usage: EmbeddingUsage
     """The usage information for the request."""
 
+    @property
+    def data(self) -> List[Embedding]:
+        """The list of embeddings generated by the model."""
+        return self.output
+
     @property
     def dimensions(self) -> int:
         """The dimensions of the embedding."""
-        return len(self.data[0].embedding)
+        return len(self.output[0].embedding)
 
     def __str__(self) -> str:
         return (
@@ -65,5 +72,5 @@ class EmbeddingModelResponse(BaseModel):
             f">>> Model: {self.model}\n"
             f">>> Dimensions: {self.dimensions}\n"
             f">>> Usage: {self.usage}\n"
-            f">>> Number of Generated Embeddings: {len(self.data)}\n"
+            f">>> Number of Generated Embeddings: {len(self.output)}\n"
         )

hammad/genai/{embedding_models/embedding_model_request.py → models/embeddings/types/embedding_model_run_params.py}

@@ -1,6 +1,7 @@
-"""hammad.genai.embedding_models.embedding_model_request"""
+"""hammad.genai.embedding_models.embedding_model_run_params"""
 
 import sys
+
 if sys.version_info >= (3, 12):
     from typing import TypedDict, Required, NotRequired
 else:
@@ -20,11 +21,11 @@ from typing import (
 from .embedding_model_name import EmbeddingModelName
 
 __all__ = [
-    "EmbeddingModelRequest",
+    "EmbeddingModelRunParams",
 ]
 
 
-class EmbeddingModelRequest(TypedDict, total=False):
+class EmbeddingModelRunParams(TypedDict, total=False):
     """A request to an embedding model."""
 
     input: List[Any] | Any

hammad/genai/models/embeddings/types/embedding_model_settings.py

@@ -0,0 +1,47 @@
+"""hammad.genai.models.embeddings.types.embedding_model_settings"""
+
+from pydantic import BaseModel
+from typing import Any, List, Optional
+
+from .embedding_model_name import EmbeddingModelName
+from ....types.base import BaseGenAIModelSettings
+
+
+__all__ = [
+    "EmbeddingModelSettings",
+]
+
+
+class EmbeddingModelSettings(BaseGenAIModelSettings):
+    """A request to an embedding model."""
+
+    format: bool = False
+    """Whether to format each non-string input as a markdown string."""
+
+    # LiteLLM Settings
+    dimensions: Optional[int] = None
+    """The dimensions of the embedding."""
+
+    encoding_format: Optional[str] = None
+    """The encoding format of the embedding."""
+
+    timeout: Optional[int] = None
+    """The timeout for the embedding request."""
+
+    api_base: Optional[str] = None
+    """The API base for the embedding request."""
+
+    api_version: Optional[str] = None
+    """The API version for the embedding request."""
+
+    api_key: Optional[str] = None
+    """The API key for the embedding request."""
+
+    api_type: Optional[str] = None
+    """The API type for the embedding request."""
+
+    caching: bool = False
+    """Whether to cache the embedding request."""
+
+    user: Optional[str] = None
+    """The user for the embedding request."""