hammad-python 0.0.25__py3-none-any.whl → 0.0.27__py3-none-any.whl

hammad/__init__.py

@@ -36,6 +36,7 @@ if TYPE_CHECKING:
 
     from ._main import (
         to,
+        run,
         fn,
         new,
         read,
@@ -68,6 +69,7 @@ __all__ = (
     "web_search",
     "web_request",
     "to",
+    "run",
     "fn",
     "new",
     "read",

hammad/data/collections/collection.py

@@ -222,7 +222,16 @@ def create_collection(
     distance_metric: "DistanceMetric" = "dot",
     settings: Optional["QdrantCollectionIndexSettings"] = None,
     query_settings: Optional["QdrantCollectionIndexQuerySettings"] = None,
-    embedding_function: Optional[Callable[[Any], List[float]]] = None,
+    embedding_model: Optional[
+        "EmbeddingModelName"
+    ] = "openai/text-embedding-3-small",
+    embedding_dimensions: Optional[int] = None,
+    embedding_api_key: Optional[str] = None,
+    embedding_base_url: Optional[str] = None,
+    # Rerank-specific parameters
+    rerank_model: Optional[str] = None,
+    rerank_api_key: Optional[str] = None,
+    rerank_base_url: Optional[str] = None,
 ) -> "QdrantCollectionIndex": ...
 
 
@@ -247,7 +256,16 @@ def create_collection(
     ] = None,
     # Vector/Qdrant-specific parameters
     distance_metric: "DistanceMetric" = "dot",
-    embedding_function: Optional[Callable[[Any], List[float]]] = None,
+    embedding_model: Optional[
+        "EmbeddingModelName"
+    ] = "openai/text-embedding-3-small",
+    embedding_dimensions: Optional[int] = None,
+    embedding_api_key: Optional[str] = None,
+    embedding_base_url: Optional[str] = None,
+    # Rerank-specific parameters
+    rerank_model: Optional[str] = None,
+    rerank_api_key: Optional[str] = None,
+    rerank_base_url: Optional[str] = None,
 ) -> Union["TantivyCollectionIndex", "QdrantCollectionIndex"]:
     """
     Create a data collection of the specified type. Collections are a unified
@@ -275,6 +293,11 @@ def create_collection(
         embedding_api_key: API key for the embedding service
         embedding_base_url: Base URL for the embedding service
 
+        # Rerank parameters (for vector collections):
+        rerank_model: The rerank model to use (e.g., 'cohere/rerank-english-v3.0')
+        rerank_api_key: API key for the rerank service
+        rerank_base_url: Base URL for the rerank service
+
     Returns:
         A TantivyCollectionIndex or QdrantCollectionIndex instance
     """
@@ -289,5 +312,11 @@ def create_collection(
         settings=settings,
         query_settings=query_settings,
         distance_metric=distance_metric,
-        embedding_function=embedding_function,
+        embedding_model=embedding_model,
+        embedding_dimensions=embedding_dimensions,
+        embedding_api_key=embedding_api_key,
+        embedding_base_url=embedding_base_url,
+        rerank_model=rerank_model,
+        rerank_api_key=rerank_api_key,
+        rerank_base_url=rerank_base_url,
     )

hammad/genai/graphs/_utils.py

@@ -0,0 +1,190 @@
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import BaseGraph
+
+
+def visualize_base_graph(graph: "BaseGraph", filename: str) -> None:
+    """Generate a visualization of the graph with clean, readable flow."""
+    if not graph._action_nodes or not graph._start_action_name:
+        raise ValueError("No actions defined in graph")
+    
+    # Build our own mermaid code for better control over layout
+    mermaid_lines = ["graph TD"]  # Top-Down layout
+    
+    # Track which nodes we've already added
+    added_nodes = set()
+    
+    # Style definitions
+    mermaid_lines.append("    %% Styles")
+    mermaid_lines.append("    classDef startNode fill:#4CAF50,stroke:#333,stroke-width:2px,color:#fff")
+    mermaid_lines.append("    classDef endNode fill:#f44336,stroke:#333,stroke-width:2px,color:#fff")
+    mermaid_lines.append("    classDef defaultNode fill:#2196F3,stroke:#333,stroke-width:2px,color:#fff")
+    mermaid_lines.append("")
+    
+    # Helper to get clean node ID
+    def get_node_id(action_name: str) -> str:
+        return action_name.replace(" ", "_").replace("-", "_")
+    
+    # Helper to add a node if not already added
+    def add_node(action_name: str, is_start: bool = False, is_end: bool = False) -> None:
+        if action_name not in added_nodes:
+            node_id = get_node_id(action_name)
+            # Use the action name as the display label
+            display_name = action_name
+            
+            if is_start:
+                mermaid_lines.append(f"    {node_id}[{display_name}]:::startNode")
+            elif is_end:
+                mermaid_lines.append(f"    {node_id}[{display_name}]:::endNode")
+            else:
+                mermaid_lines.append(f"    {node_id}[{display_name}]:::defaultNode")
+            added_nodes.add(action_name)
+    
+    # Add all nodes and connections
+    mermaid_lines.append("    %% Nodes and connections")
+    
+    # Start with the start node
+    add_node(graph._start_action_name, is_start=True)
+    
+    # Process all actions to find connections
+    for action_name in graph._action_nodes:
+        action_func = getattr(graph, action_name, None)
+        if action_func and hasattr(action_func, '_action_settings'):
+            settings = action_func._action_settings
+            
+            # Add the node
+            add_node(action_name, is_end=settings.terminates)
+            
+            # Add connections based on 'next' settings
+            if settings.next:
+                source_id = get_node_id(action_name)
+                
+                if isinstance(settings.next, str):
+                    # Simple string case
+                    target_id = get_node_id(settings.next)
+                    add_node(settings.next)
+                    mermaid_lines.append(f"    {source_id} --> {target_id}")
+                    
+                elif isinstance(settings.next, list):
+                    # List case - branches to multiple nodes
+                    for next_action in settings.next:
+                        if isinstance(next_action, str):
+                            target_id = get_node_id(next_action)
+                            add_node(next_action)
+                            mermaid_lines.append(f"    {source_id} --> {target_id}")
+                            
+                elif hasattr(settings.next, '__class__') and settings.next.__class__.__name__ == 'SelectionStrategy':
+                    # SelectionStrategy case
+                    if settings.next.actions:
+                        # Show all possible paths with a decision diamond
+                        decision_id = f"{source_id}_decision"
+                        mermaid_lines.append(f"    {source_id} --> {decision_id}{{LLM Selection}}")
+                        
+                        for next_action in settings.next.actions:
+                            target_id = get_node_id(next_action)
+                            add_node(next_action)
+                            mermaid_lines.append(f"    {decision_id} --> {target_id}")
+                    else:
+                        # If no specific actions, it can go to any node
+                        # For visualization, show connections to all non-start nodes
+                        decision_id = f"{source_id}_decision"
+                        mermaid_lines.append(f"    {source_id} --> {decision_id}{{LLM Selection}}")
+                        
+                        for other_action in graph._action_nodes:
+                            if other_action != action_name and other_action != graph._start_action_name:
+                                target_id = get_node_id(other_action)
+                                add_node(other_action)
+                                mermaid_lines.append(f"    {decision_id} -.-> {target_id}")
+    
+    # If start node has no explicit next, but there are other nodes, show possible connections
+    start_func = getattr(graph, graph._start_action_name, None)
+    if start_func and hasattr(start_func, '_action_settings'):
+        if not start_func._action_settings.next and len(graph._action_nodes) > 1:
+            source_id = get_node_id(graph._start_action_name)
+            # Find end nodes (terminates=True) to connect to
+            for action_name in graph._action_nodes:
+                if action_name != graph._start_action_name:
+                    action_func = getattr(graph, action_name, None)
+                    if action_func and hasattr(action_func, '_action_settings'):
+                        if action_func._action_settings.terminates:
+                            target_id = get_node_id(action_name)
+                            add_node(action_name, is_end=True)
+                            mermaid_lines.append(f"    {source_id} --> {target_id}")
+    
+    # Join all lines
+    mermaid_code = "\n".join(mermaid_lines)
+    
+    # Render the mermaid diagram and save it
+    try:
+        import subprocess
+        import tempfile
+        import os
+        import shutil
+        
+        # Check if mmdc (mermaid CLI) is available
+        if shutil.which('mmdc') is None:
+            raise FileNotFoundError("mermaid-cli (mmdc) not found. Install with: npm install -g @mermaid-js/mermaid-cli")
+        
+        # Create a temporary mermaid file
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.mmd', delete=False) as temp_file:
+            temp_file.write(mermaid_code)
+            temp_mmd_path = temp_file.name
+        
+        try:
+            # Determine output format from filename extension
+            output_format = 'png'  # default
+            if filename.lower().endswith('.svg'):
+                output_format = 'svg'
+            elif filename.lower().endswith('.pdf'):
+                output_format = 'pdf'
+            
+            # Use mermaid CLI to render the diagram
+            cmd = ['mmdc', '-i', temp_mmd_path, '-o', filename]
+            
+            # Add format flag only if not PNG (PNG is default)
+            if output_format != 'png':
+                cmd.extend(['-f', output_format])
+            
+            # Add theme and background color
+            cmd.extend(['-t', 'default', '-b', 'transparent'])
+            
+            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+            
+            if result.returncode == 0:
+                print(f"Graph visualization saved to: {filename}")
+            else:
+                raise subprocess.CalledProcessError(result.returncode, result.args, result.stderr)
+                
+        finally:
+            # Clean up temporary file
+            if os.path.exists(temp_mmd_path):
+                os.unlink(temp_mmd_path)
+                
+    except FileNotFoundError as e:
+        # Provide helpful error message for missing mermaid CLI
+        print(f"Warning: {e}")
+        # Save as .mmd file instead
+        mmd_filename = filename.rsplit('.', 1)[0] + '.mmd'
+        with open(mmd_filename, "w") as f:
+            f.write(mermaid_code)
+        print(f"Mermaid code saved to: {mmd_filename}")
+        print("To render as PNG, install mermaid-cli: npm install -g @mermaid-js/mermaid-cli")
+        
+    except subprocess.CalledProcessError as e:
+        # Handle mermaid CLI errors
+        print(f"Error rendering mermaid diagram: {e.stderr if e.stderr else str(e)}")
+        # Save as .mmd file as fallback
+        mmd_filename = filename.rsplit('.', 1)[0] + '.mmd'
+        with open(mmd_filename, "w") as f:
+            f.write(mermaid_code)
+        print(f"Mermaid code saved to: {mmd_filename} (rendering failed)")
+        
+    except Exception as e:
+        # General fallback: save the mermaid code
+        print(f"Unexpected error: {e}")
+        mmd_filename = filename.rsplit('.', 1)[0] + '.mmd'
+        with open(mmd_filename, "w") as f:
+            f.write(mermaid_code)
+        print(f"Mermaid code saved to: {mmd_filename}")

hammad/genai/graphs/base.py

@@ -1,4 +1,4 @@
-"""hammad.genai.graphs.base - Graph implementation using pydantic-graph with Agent/LanguageModel integration"""
+"""hammad.genai.graphs.base"""
 
 from typing import (
     Any,
@@ -44,6 +44,7 @@ from .types import (
     ActionSettings,
     GraphHistoryEntry,
 )
+from ._utils import visualize_base_graph
 
 if TYPE_CHECKING:
     try:
@@ -825,6 +826,29 @@ class ActionDecorator:
 
         def decorator(f: Callable) -> Callable:
             action_name = name or f.__name__
+            
+            # Check if action name is reserved
+            reserved_names = {
+                'run', 'async_run', 'iter', 'async_iter', 
+                'visualize', 'builder', 'as_a2a',
+                '_initialize', '_collect_state_class', '_collect_actions',
+                '_create_pydantic_graph', '_get_start_action_signature'
+            }
+            if action_name in reserved_names:
+                raise ValueError(
+                    f"Action name '{action_name}' is reserved and cannot be used. "
+                    f"Reserved names include: {', '.join(sorted(reserved_names))}. "
+                    "Please choose a different name for your action."
+                )
+            
+            # Check that the action has at least one parameter besides 'self'
+            sig = inspect.signature(f)
+            params = [p for p in sig.parameters if p != 'self']
+            if not params:
+                raise ValueError(
+                    f"Action '{action_name}' must have at least one parameter besides 'self'. "
+                    "Actions need input parameters to process."
+                )
 
             # Create a dynamic ActionNode class for this specific action with unique name
             class DynamicActionNode(ActionNode[StateT]):
@@ -921,7 +945,7 @@ class BaseGraph(Generic[StateT, T]):
         self,
         state: Optional[StateT] = None,
         *,
-        model: Optional[LanguageModelName | str] = None,
+        model: Optional[LanguageModelName | str] = "openai/gpt-4.1-nano",
         temperature: Optional[float] = None,
         max_tokens: Optional[int] = None,
         tools: Optional[List[Callable]] = None,
@@ -1160,6 +1184,10 @@ class BaseGraph(Generic[StateT, T]):
         # Merge global settings with provided kwargs
         merged_settings = self._global_settings.copy()
         merged_settings.update(language_model_kwargs)
+        
+        # Include the global model if it's set and not overridden
+        if self._global_model and "model" not in merged_settings:
+            merged_settings["model"] = self._global_model
 
         # Pass verbose/debug flags (prefer explicit params over global settings)
         start_node._verbose = (
@@ -1329,6 +1357,10 @@ class BaseGraph(Generic[StateT, T]):
         # Merge global settings with provided kwargs
         merged_settings = self._global_settings.copy()
         merged_settings.update(language_model_kwargs)
+        
+        # Include the global model if it's set and not overridden
+        if self._global_model and "model" not in merged_settings:
+            merged_settings["model"] = self._global_model
 
         # Pass verbose/debug flags (prefer explicit params over global settings)
         start_node._verbose = (
@@ -1466,6 +1498,10 @@ class BaseGraph(Generic[StateT, T]):
         # Merge global settings with provided kwargs
         merged_settings = self._global_settings.copy()
         merged_settings.update(language_model_kwargs)
+        
+        # Include the global model if it's set and not overridden
+        if self._global_model and "model" not in merged_settings:
+            merged_settings["model"] = self._global_model
 
         # Pass verbose/debug flags (prefer explicit params over global settings)
         start_node._verbose = (
@@ -1634,6 +1670,10 @@ class BaseGraph(Generic[StateT, T]):
         # Merge global settings with provided kwargs
         merged_settings = self._global_settings.copy()
         merged_settings.update(language_model_kwargs)
+        
+        # Include the global model if it's set and not overridden
+        if self._global_model and "model" not in merged_settings:
+            merged_settings["model"] = self._global_model
 
         # Pass verbose/debug flags (prefer explicit params over global settings)
         start_node._verbose = (
@@ -1678,18 +1718,6 @@ class BaseGraph(Generic[StateT, T]):
             **language_model_kwargs,
         )
 
-    def visualize(self, filename: str) -> None:
-        """Generate a visualization of the graph using pydantic-graph's mermaid support."""
-        if self._pydantic_graph and self._start_action_name:
-            start_node_class = self._action_nodes.get(self._start_action_name)
-            if start_node_class:
-                # Use pydantic-graph's built-in mermaid generation
-                mermaid_code = self._pydantic_graph.mermaid_code(
-                    start_node=start_node_class
-                )
-                with open(filename, "w") as f:
-                    f.write(mermaid_code)
-
     @classmethod
     def builder(cls) -> GraphBuilder[StateT, T]:
         """Create a builder for this graph."""
@@ -1784,3 +1812,17 @@ class BaseGraph(Generic[StateT, T]):
             lifespan_timeout=lifespan_timeout,
             **uvicorn_kwargs,
         )
+
+    def visualize(self, filename: str) -> None:
+        """Visualize the graph as mermaid.
+
+        Args:
+            filename: The filename to save the visualization to.
+
+            Ex: 'graph.png' / 'graph.mmd'
+
+        Returns:
+            None
+
+        """
+        visualize_base_graph(self, filename)

hammad/genai/models/language/types/language_model_response.py

@@ -13,6 +13,7 @@ from typing import (
 )
 
 from .....cache import cached
+from .....typing import get_type_description
 
 from ...model_provider import litellm
 from ....types.base import BaseGenAIModelResponse
@@ -210,6 +211,7 @@ class LanguageModelResponse(BaseGenAIModelResponse[T]):
             output += f"\n{self.completion}"
 
         output += f"\n\n>>> Model: {self.model}"
+        output += f"\n>>> Type: {get_type_description(type(self.output))}"
         output += f"\n>>> Tool Calls: {len(self.tool_calls) if self.tool_calls else 0}"
 
         return output

{hammad_python-0.0.25.dist-info → hammad_python-0.0.27.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hammad-python
-Version: 0.0.25
+Version: 0.0.27
 Author-email: Hammad Saeed <hammadaidev@gmail.com>
 License: MIT License
         

{hammad_python-0.0.25.dist-info → hammad_python-0.0.27.dist-info}/RECORD

@@ -1,4 +1,4 @@
-hammad/__init__.py,sha256=KeGEXWQEjoDi4hNzPQXhydXZV2knovoiBcwDX0Y5cpw,1681
+hammad/__init__.py,sha256=PtKUoTlLLfTA8cuhfvvaG1PCz6B4gkyl4d0OgZA0rNY,1705
 hammad/_internal.py,sha256=qQGXjzQyyCxzH5kMjCHwVdAojp-2OOVAO2T2QDxOBn8,8957
 hammad/_main.py,sha256=2y18WxvGqRtA0C4aaYK9-LhFXwhFvY6832kNmUyebRA,6902
 hammad/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -18,7 +18,7 @@ hammad/cli/styles/types.py,sha256=vNIeQY_23m10K8qVT7Iy-PMwosGL-La-UAZKszHJjEE,79
 hammad/cli/styles/utils.py,sha256=zzi0JdH1X7O8XWRlMVfJP2jB-OWt7zkpm_LeCHoSKVY,28287
 hammad/data/__init__.py,sha256=rga828Od--N3QeGlnOSweADD1WsRLjSTqkaZVk1VhW0,2232
 hammad/data/collections/__init__.py,sha256=xEORHnjoV75Fa6LFDMyFw90oDaJ0e9VmISLFV3mOsIQ,1110
-hammad/data/collections/collection.py,sha256=fi7jyT2GmXiGLNajjegBJMbefzggL0PIMHf-81ov7Bo,10833
+hammad/data/collections/collection.py,sha256=SvmZY0B5_VDMQGX72TxLs9BMeDs8kASmROQca_F3534,11989
 hammad/data/collections/indexes/__init__.py,sha256=RmXKWKq2sbtA1swz5vamKKWut-eKfc-Q2tUnij-E-IU,960
 hammad/data/collections/indexes/qdrant/__init__.py,sha256=KU89TIJkYmJPnVxWKHfXntkIYwhn86ejXtWG30hCyHg,49
 hammad/data/collections/indexes/qdrant/index.py,sha256=UzhW64i5Yq5AXyGZjkW4dljgQxwKUbjF6vhzendbjko,25634
@@ -68,7 +68,8 @@ hammad/genai/agents/types/agent_messages.py,sha256=csjEq42bElaTZYZW2dE6nlFZc142-
 hammad/genai/agents/types/agent_response.py,sha256=tQ3oNBZC_9dD7t-7tRuKA2h1a-XE5gGryVF9XcmZ5GA,3863
 hammad/genai/agents/types/agent_stream.py,sha256=VIfqZp55wq6jQh_OtPzZjiL_K4cEoVCkeEZS3s_MIXI,11069
 hammad/genai/graphs/__init__.py,sha256=bK59ilXuR46DgSjat7kOOr_KujIpJSfbCSgriceRhjw,3112
-hammad/genai/graphs/base.py,sha256=0Q4VgWmRbe6UTNVCCow7Dc9czR9YkFVyXoR7h6AQQZk,68024
+hammad/genai/graphs/_utils.py,sha256=kLPD9iAWhI7zRDTNLnYGRrD2f2IPre-0GYLMQcq1xzU,8854
+hammad/genai/graphs/base.py,sha256=02kLcQRFJxGw-rPlfFBDWW9C9_CAlPYHdlTwu7rg7nA,69633
 hammad/genai/graphs/plugins.py,sha256=AK_JSo2eLCD9cdrxZ5OxxZtLVrUDcQ8f_FWBxOQPzyw,10007
 hammad/genai/graphs/types.py,sha256=kpQvWpE7cKjK9TzNFa_I-z7LfxWdlCuIA-lfRTk_nFU,20701
 hammad/genai/models/__init__.py,sha256=e4TbEsiKIoXENOEsdIdQcWWt0RnFdTEqCz0nICHQHtM,26
@@ -91,7 +92,7 @@ hammad/genai/models/language/types/language_model_instructor_mode.py,sha256=7ywB
 hammad/genai/models/language/types/language_model_messages.py,sha256=e-HZ_YKXq17gwmMlpOmYUYUpBFm7Mu3aRawtjSslWXs,504
 hammad/genai/models/language/types/language_model_name.py,sha256=2V70cZ47L9yIcug6LCcMHcvEJaee7gRN6DUPhLUBlsE,8056
 hammad/genai/models/language/types/language_model_request.py,sha256=ZtzhCx8o6zkEBS3uTFXFLf_poDD7MnIp1y7MbKckOmI,3911
-hammad/genai/models/language/types/language_model_response.py,sha256=uUmcaSBBb0-CrWOx1axZ-INHmgyac5ktiAbR-HyW-fk,7520
+hammad/genai/models/language/types/language_model_response.py,sha256=CE-PWxmAB9RDzHqGjEUvYaVnbDnKYz4eEMW4Fz65F4s,7640
 hammad/genai/models/language/types/language_model_response_chunk.py,sha256=wIzGZw732KsI-a1-uASjATA6qvBuq-7rupWoFjsAgQo,1796
 hammad/genai/models/language/types/language_model_settings.py,sha256=C0EvLXZoOLgPZ4bX7mVFs_CWP-jam27qkseJRGsBAfQ,2794
 hammad/genai/models/language/types/language_model_stream.py,sha256=XgJ83JSbtTdf7jeLQMrDhMfI7zp0pRrdY7JWYbZV_h0,22043
@@ -128,7 +129,7 @@ hammad/web/openapi/__init__.py,sha256=JhJQ6_laBmB2djIYFc0vgGha2GsdUe4FP1LDdZCQ5J
 hammad/web/openapi/client.py,sha256=1pXz7KAO_0pN4kQZoWKWskXDYGiJ535TsPO1GGCiC0E,26816
 hammad/web/search/__init__.py,sha256=e9A6znPIiZCz-4secyHbUs0uUGf5yAqW6wGacgx961U,24
 hammad/web/search/client.py,sha256=LIx2MsHhn6cRTuq5i1mWowRTdIhPobY4GQV3S3bk9lk,36694
-hammad_python-0.0.25.dist-info/METADATA,sha256=cTOPOxOkgGaLI8kKAuRY1Expm0DVYLbpEDN8GCxcPbw,6785
-hammad_python-0.0.25.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-hammad_python-0.0.25.dist-info/licenses/LICENSE,sha256=h74yFUWjbBaodcWG5wNmm30npjl8obVcxD-1nQfUp2I,1069
-hammad_python-0.0.25.dist-info/RECORD,,
+hammad_python-0.0.27.dist-info/METADATA,sha256=WfL-hAEfVrPhAwRn3cBaEdm0EfaVIv3RYfz54OkLv08,6785
+hammad_python-0.0.27.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hammad_python-0.0.27.dist-info/licenses/LICENSE,sha256=h74yFUWjbBaodcWG5wNmm30npjl8obVcxD-1nQfUp2I,1069
+hammad_python-0.0.27.dist-info/RECORD,,