hammad-python 0.0.22__tar.gz → 0.0.23__tar.gz

{hammad_python-0.0.22 → hammad_python-0.0.23}/PKG-INFO

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

hammad_python-0.0.23/hammad/__init__.py

@@ -0,0 +1,34 @@
+"""hammad-python"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from ._internal import create_getattr_importer as __hammad_importer__
+
+if TYPE_CHECKING:
+    from ._main._fn import fn
+    from ._main._new import new
+    from ._main._run import run
+    from ._main._to import to
+    from .cli import print, input, animate
+
+
+__all__ = (
+    # top level namespace modules for
+    # super duper fast access to things and stuff
+    "run",
+    "new",
+    "to",
+    "fn",
+    # cli
+    "print",
+    "input",
+    "animate",
+)
+
+
+__getattr__ = __hammad_importer__(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/_internal.py

@@ -108,7 +108,25 @@ def _parse_type_checking_imports(source_code: str) -> dict[str, tuple[str, str]]
                     # Process imports in this block
                     for stmt in node.body:
                         if isinstance(stmt, ast.ImportFrom) and stmt.module:
-                            module_path = f".{stmt.module}"
+                            # Only add '.' prefix for relative imports
+                            # If stmt.level > 0, it's already a relative import
+                            # If stmt.level == 0 and module doesn't start with '.', it's absolute
+                            if stmt.level > 0:
+                                # Already relative import
+                                module_path = "." * stmt.level + (stmt.module or "")
+                            elif stmt.module.startswith("."):
+                                # Explicit relative import
+                                module_path = stmt.module
+                            elif any(
+                                stmt.module.startswith(name)
+                                for name in ["litellm", "openai", "instructor", "httpx"]
+                            ):
+                                # Known absolute third-party imports
+                                module_path = stmt.module
+                            else:
+                                # Default to relative import for internal modules
+                                module_path = f".{stmt.module}"
+
                             for alias in stmt.names:
                                 original_name = alias.name
                                 local_name = alias.asname or original_name

hammad_python-0.0.23/hammad/_main/__init__.py

@@ -0,0 +1,4 @@
+"""hammad._main
+
+Main entrypoint for the `hammad` package.
+"""

hammad_python-0.0.23/hammad/_main/_fn.py

@@ -0,0 +1,20 @@
+"""hammad._fn
+
+Namespace resource for **DECORATORS** used at the top level
+of the `hammad` package."""
+
+
+class fn:
+    """Top level namespace resource for decorators. This can
+    be used as `@hammad.fn.cached`, hammad.fn...`. All functions within
+    this module are decorators."""
+
+    from ..cache import cached, auto_cached
+    from ..genai import define_tool
+    from ..logging import trace, trace_cls, trace_function, trace_http
+    from ..service import (
+        serve,
+    )
+
+
+__all__ = "fn"

hammad_python-0.0.23/hammad/_main/_new.py

@@ -0,0 +1,52 @@
+"""hammad._new
+
+Main entrypoint for the `new` resource.
+"""
+
+
+class new:
+    """Global factory resource for creating various objects available
+    throughout the package. You can find most things in here."""
+
+    from ..cache import create_cache as cache
+    from ..data.configurations import (
+        read_configuration_from_dotenv as configuration_from_dotenv,
+        read_configuration_from_file as configuration_from_file,
+        read_configuration_from_url as configuration_from_url,
+        read_configuration_from_os_vars as configuration_from_os_vars,
+        read_configuration_from_os_prefix as configuration_from_os_prefix,
+    )
+    from ..data.collections import (
+        create_collection as collection,
+    )
+    from ..data.sql import (
+        create_database as database,
+    )
+    from ..data.types import Text as text, Audio as audio, Image as image, File as file
+    from ..genai import (
+        create_embedding_model as embedding_model,
+        create_language_model as language_model,
+        create_agent as agent,
+    )
+    from ..logging import create_logger as logger
+    from ..mcp import (
+        MCPClient as mcp_client,
+        MCPServerSseSettings as mcp_server_sse_settings,
+        MCPClientSseSettings as mcp_client_sse_settings,
+        MCPClientStreamableHttpSettings as mcp_client_http_settings,
+        MCPServerStreamableHttpSettings as mcp_server_streamable_http_settings,
+        MCPServerStdioSettings as mcp_server_stdio_settings,
+        MCPClientStdioSettings as mcp_client_stdio_settings,
+    )
+    from ..service import (
+        create_service as service,
+        async_create_service as async_service,
+    )
+    from ..web import (
+        create_http_client as http_client,
+        create_openapi_client as openapi_client,
+        create_search_client as search_client,
+    )
+
+
+__all__ = "new"

hammad_python-0.0.23/hammad/_main/_run.py

@@ -0,0 +1,50 @@
+"""hammad._run
+
+Main entrypoint for the `run` command and resource at the
+top level of the hammad package.
+"""
+
+
+class run:
+    """Top level namespace resource for running various things and stuff."""
+
+    from ..genai import (
+        # agents
+        run_agent as agent,
+        run_agent_iter as agent_iter,
+        async_run_agent as async_agent,
+        async_run_agent_iter as async_agent_iter,
+        # models
+        run_embedding_model as embedding_model,
+        async_run_embedding_model as async_embedding_model,
+        run_language_model as language_model,
+        async_run_language_model as async_language_model,
+        run_image_edit_model as image_edit_model,
+        async_run_image_edit_model as async_image_edit_model,
+        run_image_generation_model as image_generation_model,
+        async_run_image_generation_model as async_image_generation_model,
+        run_image_variation_model as image_variation_model,
+        async_run_image_variation_model as async_image_variation_model,
+        run_reranking_model as reranking_model,
+        async_run_reranking_model as async_reranking_model,
+        run_transcription_model as transcription_model,
+        async_run_transcription_model as async_transcription_model,
+        run_tts_model as tts_model,
+        async_run_tts_model as async_tts_model,
+    )
+    from ..mcp import launch_mcp_servers as mcp_servers
+    from ..runtime import (
+        run_parallel as parallel,
+        run_sequentially as sequentially,
+        run_with_retry as with_retry,
+    )
+    from ..web import (
+        read_web_page as web_reader,
+        read_web_pages as web_reader_batch,
+        run_web_search as web_search,
+        run_news_search as news_search,
+        run_web_request as web_request,
+    )
+
+
+__all__ = ["run"]

hammad_python-0.0.23/hammad/_main/_to.py

@@ -0,0 +1,19 @@
+"""hammad._to
+
+Top level namspace resource for converters."""
+
+
+class to:
+    """Converter resource"""
+
+    from ..data import (
+        convert_to_pydantic_field as pydantic_field,
+        convert_to_pydantic_model as pydantic_model,
+    )
+    from ..formatting.json import (
+        convert_to_json_schema as json_schema,
+    )
+    from ..formatting.text import convert_to_text as text
+
+
+__all__ = "to"

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/data/__init__.py

@@ -21,6 +21,7 @@ if TYPE_CHECKING:
     )
     from .collections import (
         Collection,
+        create_collection,
         TantivyCollectionIndex,
         QdrantCollectionIndex,
         TantivyCollectionIndexSettings,
@@ -54,8 +55,12 @@ __all__ = (
     "validator",
     "is_field",
     "is_model",
+    "convert_to_pydantic_model",
+    "convert_to_pydantic_field",
+    "is_pydantic_model_class",
     # hammad.data.collections
     "Collection",
+    "create_collection",
     "TantivyCollectionIndex",
     "QdrantCollectionIndex",
     "TantivyCollectionIndexSettings",
@@ -68,6 +73,11 @@ __all__ = (
     "Database",
     # hammad.data.configurations
     "Configuration",
+    "read_configuration_from_file",
+    "read_configuration_from_url",
+    "read_configuration_from_os_vars",
+    "read_configuration_from_os_prefix",
+    "read_configuration_from_dotenv",
 )
 
 

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/data/collections/__init__.py

@@ -4,7 +4,10 @@ from typing import TYPE_CHECKING
 from ..._internal import create_getattr_importer
 
 if TYPE_CHECKING:
-    from .collection import Collection
+    from .collection import (
+        Collection,
+        create_collection,
+    )
 
     from .indexes import (
         TantivyCollectionIndex,
@@ -25,6 +28,7 @@ if TYPE_CHECKING:
 __all__ = (
     # hammad.data.collections.collection
     "Collection",
+    "create_collection",
     # hammad.data.collections.indexes
     "TantivyCollectionIndex",
     "QdrantCollectionIndex",

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/data/sql/__init__.py

@@ -5,13 +5,14 @@ from ..._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .types import DatabaseItemType, DatabaseItem
-    from .database import Database
+    from .database import Database, create_database
 
 
 __all__ = (
     "DatabaseItemType",
     "DatabaseItem",
     "Database",
+    "create_database",
 )
 
 

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/genai/__init__.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
         AgentContext,
         AgentMessages,
         AgentResponseChunk,
+        create_agent,
     )
     from .agents.run import (
         run_agent,
@@ -27,6 +28,7 @@ if TYPE_CHECKING:
         EmbeddingModelSettings,
         run_embedding_model,
         async_run_embedding_model,
+        create_embedding_model,
     )
     from .models.language import (
         LanguageModel,
@@ -40,6 +42,7 @@ if TYPE_CHECKING:
         LanguageModelStream,
         run_language_model,
         async_run_language_model,
+        create_language_model,
     )
     from .models.reranking import run_reranking_model, async_run_reranking_model
     from .models.multimodal import (
@@ -78,6 +81,7 @@ __all__ = [
     "AgentContext",
     "AgentMessages",
     "AgentResponseChunk",
+    "create_agent",
     # hammad.genai.agents.run
     "run_agent",
     "run_agent_iter",
@@ -90,6 +94,7 @@ __all__ = [
     "EmbeddingModelSettings",
     "run_embedding_model",
     "async_run_embedding_model",
+    "create_embedding_model",
     # hammad.genai.models.language
     "LanguageModel",
     "LanguageModelInstructorMode",
@@ -102,6 +107,7 @@ __all__ = [
     "LanguageModelStream",
     "run_language_model",
     "async_run_language_model",
+    "create_language_model",
     # hammad.genai.models.reranking
     "run_reranking_model",
     "async_run_reranking_model",

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/genai/agents/__init__.py

@@ -5,7 +5,10 @@ from ..._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:
-    from .agent import Agent
+    from .agent import (
+        Agent,
+        create_agent,
+    )
 
     # Types
     from .types.agent_context import AgentContext
@@ -22,6 +25,7 @@ if TYPE_CHECKING:
 __all__ = [
     # hammad.genai.agents.agent
     "Agent",
+    "create_agent",
     # hammad.genai.agents.types.agent_context
     "AgentContext",
     # hammad.genai.agents.types.agent_event

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/genai/agents/agent.py

@@ -1351,6 +1351,84 @@ Please update the appropriate fields based on the conversation. Only update fiel
         )
 
 
+def create_agent(
+    name: str = "agent",
+    instructions: Optional[str] = None,
+    model: Union[LanguageModel, LanguageModelName] = "openai/gpt-4o-mini",
+    description: Optional[str] = None,
+    tools: Union[List[Tool], Callable, None] = None,
+    settings: Optional[AgentSettings] = None,
+    instructor_mode: Optional[LanguageModelInstructorMode] = None,
+    # Context management parameters
+    context_updates: Optional[
+        Union[List[Literal["before", "after"]], Literal["before", "after"]]
+    ] = None,
+    context_confirm: bool = False,
+    context_strategy: Literal["selective", "all"] = "all",
+    context_max_retries: int = 3,
+    context_confirm_instructions: Optional[str] = None,
+    context_selection_instructions: Optional[str] = None,
+    context_update_instructions: Optional[str] = None,
+    context_format: Literal["json", "python", "markdown"] = "json",
+    **kwargs: Any,
+) -> Agent[T]:
+    """Create a new AI agent with specified capabilities and behavior.
+
+    An agent is an intelligent assistant that can use tools, follow instructions,
+    and maintain context across conversations. It combines a language model with
+    additional capabilities like tool execution and structured output generation.
+
+    Args:
+        name: A human-readable name for the agent (default: "agent")
+        instructions: System instructions that define the agent's behavior and personality
+        model: The language model to use - either a LanguageModel instance or model name string
+        description: Optional description of what the agent does
+        tools: List of tools/functions the agent can call, or a single callable
+        settings: AgentSettings object to customize default behavior
+        instructor_mode: Mode for structured output generation
+        context_updates: When to update context - "before", "after", or both
+        context_confirm: Whether to confirm context updates with the user
+        context_strategy: How to select context updates - "selective" or "all"
+        context_max_retries: Maximum attempts for context update operations
+        context_confirm_instructions: Custom instructions for context confirmation
+        context_selection_instructions: Custom instructions for context selection
+        context_update_instructions: Custom instructions for context updates
+        context_format: Format for context display - "json", "python", or "markdown"
+        **kwargs: Additional parameters passed to the underlying language model
+
+    Example:
+        Basic agent:
+        >>> agent = create_agent(name="assistant", instructions="You are helpful")
+
+        Agent with tools:
+        >>> def calculator(x: int, y: int) -> int:
+        ...     return x + y
+        >>> agent = create_agent(tools=[calculator])
+
+        Agent with custom settings:
+        >>> settings = AgentSettings(max_steps=5)
+        >>> agent = create_agent(settings=settings, model="gpt-4")
+    """
+    return Agent(
+        name=name,
+        instructions=instructions,
+        model=model,
+        description=description,
+        tools=tools,
+        settings=settings,
+        instructor_mode=instructor_mode,
+        context_updates=context_updates,
+        context_confirm=context_confirm,
+        context_strategy=context_strategy,
+        context_max_retries=context_max_retries,
+        context_confirm_instructions=context_confirm_instructions,
+        context_selection_instructions=context_selection_instructions,
+        context_update_instructions=context_update_instructions,
+        context_format=context_format,
+        **kwargs,
+    )
+
+
 __all__ = [
     "Agent",
     "AgentSettings",
@@ -1358,4 +1436,5 @@ __all__ = [
     "AgentEvent",
     "HookManager",
     "HookDecorator",
+    "create_agent",
 ]

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/genai/models/embeddings/__init__.py

@@ -5,7 +5,10 @@ from ...._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:
-    from .model import EmbeddingModel
+    from .model import (
+        EmbeddingModel,
+        create_embedding_model,
+    )
     from .run import (
         run_embedding_model,
         async_run_embedding_model,
@@ -19,6 +22,7 @@ if TYPE_CHECKING:
 
 __all__ = [
     "EmbeddingModel",
+    "create_embedding_model",
     # hammad.genai.models.embeddings.run
     "run_embedding_model",
     "async_run_embedding_model",

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/genai/models/embeddings/model.py

@@ -1,7 +1,7 @@
 """hammad.genai.embedding_models.embedding_model"""
 
 import asyncio
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, List, Optional
 import sys
 
@@ -26,6 +26,7 @@ from ....formatting.text import convert_to_text
 __all__ = (
     "EmbeddingModel",
     "EmbeddingModelError",
+    "create_embedding_model",
 )
 
 
@@ -87,7 +88,7 @@ class EmbeddingModel:
     api_version: Optional[str] = None
     """Optional API version for a custom embedding provider."""
 
-    settings: EmbeddingModelSettings = EmbeddingModelSettings()
+    settings: EmbeddingModelSettings = field(default_factory=EmbeddingModelSettings)
     """Optional settings for the embedding model."""
 
     async def async_run(
@@ -195,3 +196,31 @@ class EmbeddingModel:
                 format=format,
             )
         )
+
+
+def create_embedding_model(
+    model: str | EmbeddingModelName = "openai/text-embedding-3-small",
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    api_version: Optional[str] = None,
+    api_type: Optional[str] = None,
+    settings: Optional[EmbeddingModelSettings] = None,
+) -> EmbeddingModel:
+    """Create an embedding model instance.
+
+    Args:
+        model (str | EmbeddingModelName) : The model to use for the embedding.
+        base_url (Optional[str]) : The base URL for the API.
+        api_key (Optional[str]) : The API key to use for the request.
+        api_version (Optional[str]) : The version of the API.
+        api_type (Optional[str]) : The API type to use for the request.
+        settings (Optional[EmbeddingModelSettings]) : The settings for the embedding model.
+    """
+    return EmbeddingModel(
+        model=model,
+        base_url=base_url,
+        api_key=api_key,
+        api_version=api_version,
+        api_type=api_type,
+        settings=settings or EmbeddingModelSettings(),
+    )

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/genai/models/language/__init__.py

@@ -5,7 +5,10 @@ from ...._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:
-    from .model import LanguageModel
+    from .model import (
+        LanguageModel,
+        create_language_model,
+    )
     from .run import run_language_model, async_run_language_model
     from .types.language_model_instructor_mode import LanguageModelInstructorMode
     from .types.language_model_messages import LanguageModelMessages
@@ -19,6 +22,7 @@ if TYPE_CHECKING:
 __all__ = [
     # hammad.genai.models.language.model
     "LanguageModel",
+    "create_language_model",
     # hammad.genai.models.language.run
     "run_language_model",
     "async_run_language_model",

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/genai/models/language/model.py

@@ -46,6 +46,7 @@ from .utils import (
 __all__ = [
     "LanguageModel",
     "LanguageModelError",
+    "create_language_model",
 ]
 
 T = TypeVar("T")
@@ -1026,3 +1027,26 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
             )
 
         return response.output
+
+
+def create_language_model(
+    model: str | LanguageModelName = "openai/gpt-4o-mini",
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    api_version: Optional[str] = None,
+    organization: Optional[str] = None,
+    deployment_id: Optional[str] = None,
+    model_list: Optional[List[Any]] = None,
+    extra_headers: Optional[Dict[str, str]] = None,
+) -> LanguageModel:
+    """Create a language model instance."""
+    return LanguageModel(
+        model=model,
+        base_url=base_url,
+        api_key=api_key,
+        api_version=api_version,
+        organization=organization,
+        deployment_id=deployment_id,
+        model_list=model_list,
+        extra_headers=extra_headers,
+    )

{hammad_python-0.0.22 → hammad_python-0.0.23}/hammad/genai/models/language/run.py

@@ -26,14 +26,13 @@ if TYPE_CHECKING:
         ChatCompletionAudioParam,
     )
 
-    from .types import (
-        LanguageModelMessages,
-        LanguageModelInstructorMode,
-        LanguageModelName,
-        LanguageModelResponse,
-        LanguageModelStream,
-    )
-
+from .types import (
+    LanguageModelMessages,
+    LanguageModelInstructorMode,
+    LanguageModelName,
+    LanguageModelResponse,
+    LanguageModelStream,
+)
 from .model import LanguageModel
 
 

{hammad_python-0.0.22 → hammad_python-0.0.23}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hammad-python"
-version = "0.0.22"
+version = "0.0.23"
 license = {file = "LICENSE"}
 readme = "README.md"
 authors = [{name = "Hammad Saeed", email = "hammadaidev@gmail.com"}]

hammad_python-0.0.22/hammad/__init__.py

@@ -1,50 +0,0 @@
-"""hammad-python"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-from ._internal import create_getattr_importer as __hammad_importer__
-
-if TYPE_CHECKING:
-    # hammad.cache
-    from .cache import cached, Cache
-
-    # hammad.cli
-    from .cli import print, animate, input
-
-    # hammad.formatting
-    from .formatting.json import convert_to_json_schema
-    from .formatting.text import convert_to_text, convert_type_to_text
-
-    # hammad.logging
-    from .logging.logger import Logger, create_logger
-    from .logging.decorators import trace, trace_cls, trace_function, trace_http
-
-
-__all__ = [
-    # hammad.cache
-    "cached",
-    "Cache",
-    # hammad.cli
-    "print",
-    "animate",
-    "input",
-    # hammad.formatting
-    "convert_to_json_schema",
-    "convert_to_text",
-    "convert_type_to_text",
-    # hammad.logging
-    "Logger",
-    "create_logger",
-    "trace",
-    "trace_cls",
-    "trace_function",
-    "trace_http",
-]
-
-
-__getattr__ = __hammad_importer__(__all__)
-
-
-def __dir__() -> list[str]:
-    return __all__