hexastack-ai 0.1.0__tar.gz

hexastack_ai-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: hexastack-ai
+Version: 0.1.0
+Summary: AI engine, LLM provider integration (LiteLLM, Instructor, PydanticAI), and CQRS agent reflection for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: instructor>=1.7.0
+Requires-Dist: litellm>=1.50.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pydantic-ai>=0.0.24
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+![hexastack-ai](../../docs/assets/static/logos/packages/hexastack_ai.png)
+
+# hexastack-ai
+
+AI engine, LLM provider integration (LiteLLM, Instructor, PydanticAI), and CQRS agent tool reflection for the **Hexastack** hexagonal architecture framework.
+
+[![PyPI: hexastack-ai](https://img.shields.io/pypi/v/hexastack-ai.svg)](https://pypi.org/project/hexastack-ai/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://codecov.io/github/TheTrueSCU/hexastack/graph/badge.svg?component=hexastack_ai)](https://codecov.io/github/TheTrueSCU/hexastack)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
+
+---
+
+## 1. Overview
+
+`hexastack-ai` integrates an agnostic, production-grade AI stack directly into the Hexastack architecture:
+- **LiteLLM**: Unified driver abstraction across 100+ LLM providers (OpenAI, Anthropic Claude, Google Gemini, Ollama, Groq, Bedrock).
+- **Instructor**: Self-correcting structured output validation returning strongly typed Pydantic models.
+- **PydanticAI**: Type-safe agent loop orchestration and tool execution.
+- **CQRS Tool Reflection**: Automatically turns Hexastack CQRS Commands and Queries into callable AI Agent tools.
+
+---
+
+## 2. Architecture & Relationships
+
+```mermaid
+graph TD
+    subgraph Core ["hexastack-core"]
+        PORT["LlmProviderPort"]
+        MEM["InMemoryLlmProvider"]
+    end
+
+    subgraph AI ["hexastack-ai"]
+        BOOT["AiBootstrapper (order=18)"]
+        ADAPTER["LiteLlmAdapter"]
+        TOOLS["create_cqrs_agent / create_tool_for_message"]
+        AGENT_ADAPTER["PydanticAiAgentAdapter"]
+    end
+
+    subgraph CQRS ["hexastack-cqrs"]
+        PIPELINE["ExecutionPipeline"]
+        CMDS["Commands & Queries"]
+    end
+
+    subgraph UpstreamAI ["Agnostic AI Stack"]
+        LITE["LiteLLM (100+ Providers)"]
+        INST["Instructor (Schema Validation)"]
+        PY_AI["PydanticAI (Agent Execution)"]
+    end
+
+    BOOT -->|binds into DI| PORT
+    ADAPTER -. implements .-> PORT
+    ADAPTER --> LITE
+    ADAPTER --> INST
+    TOOLS --> PIPELINE
+    TOOLS --> PY_AI
+    AGENT_ADAPTER --> PY_AI
+```
+
+---
+
+## 3. Installation
+
+```bash
+# Standalone install
+pip install hexastack-ai
+
+# Via umbrella package
+pip install "hexastack[ai]"
+```
+
+---
+
+## 4. Configuration Reference
+
+```toml
+[hexastack.ai]
+# Provider: "memory" (default for testing), "litellm", "openai", "anthropic", "gemini", "ollama"
+provider = "litellm"
+model = "gpt-4o-mini"
+temperature = 0.2
+max_tokens = 2048
+api_key = "sk-..." # Or set standard env var OPENAI_API_KEY / ANTHROPIC_API_KEY
+
+# LiteLLM Dialect Settings
+[hexastack.ai.litellm]
+drop_params = true
+num_retries = 3
+timeout = 60.0
+api_base = "http://localhost:4000" # Optional LiteLLM proxy URL
+
+# Ollama Local Dialect Settings
+[hexastack.ai.ollama]
+base_url = "http://localhost:11434"
+
+# PydanticAI Agent Settings
+[hexastack.ai.agent]
+max_turns = 10
+system_prompt = "You are a helpful AI assistant."
+```
+
+---
+
+## 5. Usage Examples
+
+### 1. Structured Output Extraction
+
+```python
+from pydantic import BaseModel
+from hexastack_core.ports.ai import LlmProviderPort
+
+
+class InvoiceDTO(BaseModel):
+    customer_id: str
+    total_amount: float
+    items: list[str]
+
+
+def extract_invoice(llm: LlmProviderPort, text: str) -> InvoiceDTO:
+    return llm.generate_structured(
+        prompt=f"Extract invoice details from: {text}",
+        response_schema=InvoiceDTO,
+    )
+```
+
+### 2. Auto-Reflecting CQRS Commands as Agent Tools
+
+```python
+from hexastack_core.domain import Command, Query
+from hexastack_ai.infra.tools import create_cqrs_agent
+
+
+class CancelSubscriptionCommand(Command):
+    user_id: str
+    reason: str
+
+
+class GetUserPlanQuery(Query[str]):
+    user_id: str
+
+
+# Create PydanticAI agent with CQRS handlers as native tools:
+agent = create_cqrs_agent(
+    pipeline=runtime.pipeline,
+    messages=[CancelSubscriptionCommand, GetUserPlanQuery],
+    model="anthropic/claude-3-5-sonnet",
+    system_prompt="You are a customer support agent.",
+)
+
+# Agent selects appropriate tools and executes them via Hexastack ExecutionPipeline:
+result = agent.run_sync("Cancel subscription for user 123 due to pricing.")
+```

hexastack_ai-0.1.0/README.md

@@ -0,0 +1,152 @@
+![hexastack-ai](../../docs/assets/static/logos/packages/hexastack_ai.png)
+
+# hexastack-ai
+
+AI engine, LLM provider integration (LiteLLM, Instructor, PydanticAI), and CQRS agent tool reflection for the **Hexastack** hexagonal architecture framework.
+
+[![PyPI: hexastack-ai](https://img.shields.io/pypi/v/hexastack-ai.svg)](https://pypi.org/project/hexastack-ai/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://codecov.io/github/TheTrueSCU/hexastack/graph/badge.svg?component=hexastack_ai)](https://codecov.io/github/TheTrueSCU/hexastack)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
+
+---
+
+## 1. Overview
+
+`hexastack-ai` integrates an agnostic, production-grade AI stack directly into the Hexastack architecture:
+- **LiteLLM**: Unified driver abstraction across 100+ LLM providers (OpenAI, Anthropic Claude, Google Gemini, Ollama, Groq, Bedrock).
+- **Instructor**: Self-correcting structured output validation returning strongly typed Pydantic models.
+- **PydanticAI**: Type-safe agent loop orchestration and tool execution.
+- **CQRS Tool Reflection**: Automatically turns Hexastack CQRS Commands and Queries into callable AI Agent tools.
+
+---
+
+## 2. Architecture & Relationships
+
+```mermaid
+graph TD
+    subgraph Core ["hexastack-core"]
+        PORT["LlmProviderPort"]
+        MEM["InMemoryLlmProvider"]
+    end
+
+    subgraph AI ["hexastack-ai"]
+        BOOT["AiBootstrapper (order=18)"]
+        ADAPTER["LiteLlmAdapter"]
+        TOOLS["create_cqrs_agent / create_tool_for_message"]
+        AGENT_ADAPTER["PydanticAiAgentAdapter"]
+    end
+
+    subgraph CQRS ["hexastack-cqrs"]
+        PIPELINE["ExecutionPipeline"]
+        CMDS["Commands & Queries"]
+    end
+
+    subgraph UpstreamAI ["Agnostic AI Stack"]
+        LITE["LiteLLM (100+ Providers)"]
+        INST["Instructor (Schema Validation)"]
+        PY_AI["PydanticAI (Agent Execution)"]
+    end
+
+    BOOT -->|binds into DI| PORT
+    ADAPTER -. implements .-> PORT
+    ADAPTER --> LITE
+    ADAPTER --> INST
+    TOOLS --> PIPELINE
+    TOOLS --> PY_AI
+    AGENT_ADAPTER --> PY_AI
+```
+
+---
+
+## 3. Installation
+
+```bash
+# Standalone install
+pip install hexastack-ai
+
+# Via umbrella package
+pip install "hexastack[ai]"
+```
+
+---
+
+## 4. Configuration Reference
+
+```toml
+[hexastack.ai]
+# Provider: "memory" (default for testing), "litellm", "openai", "anthropic", "gemini", "ollama"
+provider = "litellm"
+model = "gpt-4o-mini"
+temperature = 0.2
+max_tokens = 2048
+api_key = "sk-..." # Or set standard env var OPENAI_API_KEY / ANTHROPIC_API_KEY
+
+# LiteLLM Dialect Settings
+[hexastack.ai.litellm]
+drop_params = true
+num_retries = 3
+timeout = 60.0
+api_base = "http://localhost:4000" # Optional LiteLLM proxy URL
+
+# Ollama Local Dialect Settings
+[hexastack.ai.ollama]
+base_url = "http://localhost:11434"
+
+# PydanticAI Agent Settings
+[hexastack.ai.agent]
+max_turns = 10
+system_prompt = "You are a helpful AI assistant."
+```
+
+---
+
+## 5. Usage Examples
+
+### 1. Structured Output Extraction
+
+```python
+from pydantic import BaseModel
+from hexastack_core.ports.ai import LlmProviderPort
+
+
+class InvoiceDTO(BaseModel):
+    customer_id: str
+    total_amount: float
+    items: list[str]
+
+
+def extract_invoice(llm: LlmProviderPort, text: str) -> InvoiceDTO:
+    return llm.generate_structured(
+        prompt=f"Extract invoice details from: {text}",
+        response_schema=InvoiceDTO,
+    )
+```
+
+### 2. Auto-Reflecting CQRS Commands as Agent Tools
+
+```python
+from hexastack_core.domain import Command, Query
+from hexastack_ai.infra.tools import create_cqrs_agent
+
+
+class CancelSubscriptionCommand(Command):
+    user_id: str
+    reason: str
+
+
+class GetUserPlanQuery(Query[str]):
+    user_id: str
+
+
+# Create PydanticAI agent with CQRS handlers as native tools:
+agent = create_cqrs_agent(
+    pipeline=runtime.pipeline,
+    messages=[CancelSubscriptionCommand, GetUserPlanQuery],
+    model="anthropic/claude-3-5-sonnet",
+    system_prompt="You are a customer support agent.",
+)
+
+# Agent selects appropriate tools and executes them via Hexastack ExecutionPipeline:
+result = agent.run_sync("Cancel subscription for user 123 due to pricing.")
+```

hexastack_ai-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "hexastack-ai"
+version = "0.1.0"
+description = "AI engine, LLM provider integration (LiteLLM, Instructor, PydanticAI), and CQRS agent reflection for Hexastack"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "instructor>=1.7.0",
+    "litellm>=1.50.0",
+    "pydantic>=2.10.0",
+    "pydantic-ai>=0.0.24",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.entry-points."hexastack.bootstrappers"]
+ai = "hexastack_ai.infra.bootstrap:AiBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_ai"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_ai"]
+layers = [
+    "adapters",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_ai.domain"]
+forbidden_modules = [
+    "hexastack_ai.adapters",
+    "hexastack_ai.infra",
+]

hexastack_ai-0.1.0/pyproject.toml.orig

@@ -0,0 +1,50 @@
+[project]
+name = "hexastack-ai"
+version = "0.1.0"
+description = "AI engine, LLM provider integration (LiteLLM, Instructor, PydanticAI), and CQRS agent reflection for Hexastack"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "instructor>=1.7.0",
+    "litellm>=1.50.0",
+    "pydantic>=2.10.0",
+    "pydantic-ai>=0.0.24",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+ai = "hexastack_ai.infra.bootstrap:AiBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_ai"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_ai"]
+layers = [
+    "adapters",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_ai.domain"]
+forbidden_modules = [
+    "hexastack_ai.adapters",
+    "hexastack_ai.infra",
+]

hexastack_ai-0.1.0/src/hexastack_ai/__init__.py

@@ -0,0 +1,7 @@
+from hexastack_ai import adapters, domain, infra
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+]

hexastack_ai-0.1.0/src/hexastack_ai/adapters/__init__.py

@@ -0,0 +1,7 @@
+from hexastack_ai.adapters.litellm import LiteLlmAdapter
+from hexastack_ai.adapters.pydantic_ai import PydanticAiAgentAdapter
+
+__all__ = [
+    "LiteLlmAdapter",
+    "PydanticAiAgentAdapter",
+]

hexastack_ai-0.1.0/src/hexastack_ai/adapters/litellm.py

@@ -0,0 +1,226 @@
+import inspect
+from typing import Any
+
+from pydantic import BaseModel
+
+from hexastack_ai.domain.exceptions import (
+    LlmProviderError,
+    StructuredOutputParsingError,
+)
+from hexastack_ai.infra.config import HexastackAiConfig
+from hexastack_core.ports.ai import LlmProviderPort
+
+
+class LiteLlmAdapter(LlmProviderPort):
+    """LiteLLM and Instructor adapter implementing LlmProviderPort.
+
+    Notes/Architectural Intent:
+        Wraps LiteLLM to provide vendor-agnostic LLM calls across 100+ providers
+        (OpenAI, Claude, Gemini, Ollama, Bedrock) while leveraging Instructor
+        for self-correcting structured output validation.
+    """
+
+    def __init__(self, config: HexastackAiConfig | None = None) -> None:
+        """Initialize LiteLlmAdapter with configuration.
+
+        Args:
+            config: HexastackAiConfig instance.
+        """
+        self._config = config or HexastackAiConfig()
+
+    @property
+    def _resolved_model(self) -> str:
+        """Resolve full model identifier ensuring provider prefix like 'gemini/' is handled."""
+        model = self._config.model
+        provider = self._config.provider.lower()
+        if provider == "gemini" and not model.startswith("gemini/"):
+            return f"gemini/{model}"
+        if provider == "anthropic" and not model.startswith("anthropic/"):
+            return f"anthropic/{model}"
+        if provider == "ollama" and not model.startswith("ollama/"):
+            return f"ollama/{model}"
+        return model
+
+    def generate_structured[T: BaseModel](
+        self, prompt: str, response_schema: type[T]
+    ) -> T:
+        """Generate structured Pydantic output using Instructor over LiteLLM.
+
+        Args:
+            prompt: The user prompt text.
+            response_schema: Target Pydantic model class.
+
+        Returns:
+            Validated instance of response_schema.
+
+        Raises:
+            StructuredOutputParsingError: If schema validation fails.
+            LlmProviderError: If API call fails.
+        """
+        import instructor
+        import litellm
+        from instructor.core import InstructorRetryException
+
+        client = instructor.from_litellm(litellm.completion)
+
+        kwargs: dict[str, Any] = {
+            "model": self._resolved_model,
+            "messages": [{"role": "user", "content": prompt}],
+            "response_model": response_schema,
+            "temperature": self._config.temperature,
+            "max_tokens": self._config.max_tokens,
+        }
+        if self._config.api_key:
+            kwargs["api_key"] = self._config.api_key
+        if self._config.litellm.api_base:
+            kwargs["api_base"] = self._config.litellm.api_base
+
+        try:
+            return client.chat.completions.create(**kwargs)
+        except InstructorRetryException as exc:
+            raise StructuredOutputParsingError(
+                f"Failed to generate structured {response_schema.__name__}: {exc}"
+            ) from exc
+        except Exception as exc:
+            raise LlmProviderError(
+                str(exc),
+                provider=self._config.provider,
+                model=self._config.model,
+            ) from exc
+
+    async def generate_structured_async[T: BaseModel](
+        self, prompt: str, response_schema: type[T]
+    ) -> T:
+        """Asynchronously generate structured Pydantic output using Instructor over LiteLLM."""
+        import instructor
+        import litellm
+        from instructor.core import InstructorRetryException
+
+        client = instructor.from_litellm(litellm.acompletion)
+
+        kwargs: dict[str, Any] = {
+            "model": self._resolved_model,
+            "messages": [{"role": "user", "content": prompt}],
+            "response_model": response_schema,
+            "temperature": self._config.temperature,
+            "max_tokens": self._config.max_tokens,
+        }
+        if self._config.api_key:
+            kwargs["api_key"] = self._config.api_key
+        if self._config.litellm.api_base:
+            kwargs["api_base"] = self._config.litellm.api_base
+
+        try:
+            raw_result: Any = client.chat.completions.create(**kwargs)
+            if inspect.isawaitable(raw_result):
+                return await raw_result
+            return raw_result
+        except InstructorRetryException as exc:
+            raise StructuredOutputParsingError(
+                f"Failed to generate structured {response_schema.__name__}: {exc}"
+            ) from exc
+        except Exception as exc:
+            raise LlmProviderError(
+                str(exc),
+                provider=self._config.provider,
+                model=self._config.model,
+            ) from exc
+
+    def generate_text(self, prompt: str, system_prompt: str | None = None) -> str:
+        """Generate unstructured text from a prompt via LiteLLM.
+
+        Args:
+            prompt: The user prompt text.
+            system_prompt: Optional system instruction prompt.
+
+        Returns:
+            Generated response text.
+
+        Raises:
+            LlmProviderError: If the upstream provider request fails.
+        """
+        import litellm
+
+        messages: list[dict[str, str]] = []
+        if system_prompt or self._config.agent.system_prompt:
+            sys = system_prompt or self._config.agent.system_prompt
+            if sys:
+                messages.append({"role": "system", "content": sys})
+        messages.append({"role": "user", "content": prompt})
+
+        kwargs: dict[str, Any] = {
+            "model": self._resolved_model,
+            "messages": messages,
+            "temperature": self._config.temperature,
+            "max_tokens": self._config.max_tokens,
+            "drop_params": self._config.litellm.drop_params,
+            "num_retries": self._config.litellm.num_retries,
+            "timeout": self._config.litellm.timeout,
+        }
+        if self._config.api_key:
+            kwargs["api_key"] = self._config.api_key
+        if self._config.litellm.api_base:
+            kwargs["api_base"] = self._config.litellm.api_base
+
+        try:
+            response = litellm.completion(**kwargs)
+            return response.choices[0].message.content or ""
+        except Exception as exc:
+            raise LlmProviderError(
+                str(exc),
+                provider=self._config.provider,
+                model=self._config.model,
+            ) from exc
+
+    async def generate_text_async(
+        self, prompt: str, system_prompt: str | None = None
+    ) -> str:
+        """Asynchronously generate unstructured text from a prompt via LiteLLM.
+
+        Args:
+            prompt: The user prompt text.
+            system_prompt: Optional system instruction prompt.
+
+        Returns:
+            Generated response text.
+
+        Raises:
+            LlmProviderError: If the upstream provider request fails.
+        """
+        import litellm
+
+        messages: list[dict[str, str]] = []
+        if system_prompt or self._config.agent.system_prompt:
+            sys = system_prompt or self._config.agent.system_prompt
+            if sys:
+                messages.append({"role": "system", "content": sys})
+        messages.append({"role": "user", "content": prompt})
+
+        kwargs: dict[str, Any] = {
+            "model": self._resolved_model,
+            "messages": messages,
+            "temperature": self._config.temperature,
+            "max_tokens": self._config.max_tokens,
+            "drop_params": self._config.litellm.drop_params,
+            "num_retries": self._config.litellm.num_retries,
+            "timeout": self._config.litellm.timeout,
+        }
+        if self._config.api_key:
+            kwargs["api_key"] = self._config.api_key
+        if self._config.litellm.api_base:
+            kwargs["api_base"] = self._config.litellm.api_base
+
+        try:
+            response = await litellm.acompletion(**kwargs)
+            return response.choices[0].message.content or ""
+        except Exception as exc:
+            raise LlmProviderError(
+                str(exc),
+                provider=self._config.provider,
+                model=self._config.model,
+            ) from exc
+
+
+__all__ = [
+    "LiteLlmAdapter",
+]

hexastack_ai-0.1.0/src/hexastack_ai/adapters/pydantic_ai.py

@@ -0,0 +1,66 @@
+from typing import Any
+
+from pydantic_ai import Agent
+
+from hexastack_ai.domain.exceptions import AgentExecutionError
+
+
+class PydanticAiAgentAdapter:
+    """Adapter wrapping a PydanticAI Agent instance.
+
+    Notes/Architectural Intent:
+        Encapsulates agent execution lifecycle, converting low-level exceptions
+        into Hexastack domain AgentExecutionError.
+    """
+
+    def __init__(self, agent: Agent[Any, Any]) -> None:
+        """Initialize adapter with a configured PydanticAI Agent instance."""
+        self._agent = agent
+
+    @property
+    def agent(self) -> Agent[Any, Any]:
+        """Access the underlying PydanticAI Agent instance."""
+        return self._agent
+
+    async def run(self, prompt: str, **kwargs: Any) -> Any:
+        """Asynchronously run the agent against a user prompt.
+
+        Args:
+            prompt: User request prompt.
+            **kwargs: Extra parameters passed to agent.run().
+
+        Returns:
+            The agent result data.
+
+        Raises:
+            AgentExecutionError: If agent execution or tool call fails.
+        """
+        try:
+            result = await self._agent.run(prompt, **kwargs)
+            return getattr(result, "output", getattr(result, "data", result))
+        except Exception as exc:
+            raise AgentExecutionError(str(exc)) from exc
+
+    def run_sync(self, prompt: str, **kwargs: Any) -> Any:
+        """Synchronously run the agent against a user prompt.
+
+        Args:
+            prompt: User request prompt.
+            **kwargs: Extra parameters passed to agent.run_sync().
+
+        Returns:
+            The agent result data.
+
+        Raises:
+            AgentExecutionError: If agent execution fails.
+        """
+        try:
+            result = self._agent.run_sync(prompt, **kwargs)
+            return getattr(result, "output", getattr(result, "data", result))
+        except Exception as exc:
+            raise AgentExecutionError(str(exc)) from exc
+
+
+__all__ = [
+    "PydanticAiAgentAdapter",
+]

hexastack_ai-0.1.0/src/hexastack_ai/domain/__init__.py

@@ -0,0 +1,13 @@
+from hexastack_ai.domain.exceptions import (
+    AgentExecutionError,
+    AiError,
+    LlmProviderError,
+    StructuredOutputParsingError,
+)
+
+__all__ = [
+    "AgentExecutionError",
+    "AiError",
+    "LlmProviderError",
+    "StructuredOutputParsingError",
+]

hexastack_ai-0.1.0/src/hexastack_ai/domain/exceptions.py

@@ -0,0 +1,53 @@
+from hexastack_core.domain import HexastackError
+
+
+class AiError(HexastackError):
+    """Base exception for all AI, LLM, and agent operations in Hexastack."""
+
+
+class LlmProviderError(AiError):
+    """Exception raised when an upstream LLM API call fails."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: str | None = None,
+        model: str | None = None,
+    ) -> None:
+        """Initialize LlmProviderError with model and provider context.
+
+        Args:
+            message: Error description.
+            provider: Name of the LLM provider (e.g. 'openai', 'anthropic').
+            model: Name of the target model (e.g. 'gpt-4o', 'claude-3-5-sonnet').
+        """
+        self.provider = provider
+        self.model = model
+        suffix = f" [provider={provider}, model={model}]" if provider or model else ""
+        super().__init__(f"{message}{suffix}")
+
+
+class StructuredOutputParsingError(AiError):
+    """Exception raised when LLM output fails schema validation."""
+
+    def __init__(self, message: str, raw_response: str | None = None) -> None:
+        """Initialize exception with raw output text.
+
+        Args:
+            message: Error description.
+            raw_response: Raw response string from the model.
+        """
+        self.raw_response = raw_response
+        super().__init__(message)
+
+
+class AgentExecutionError(AiError):
+    """Exception raised when an agent loop or tool execution fails."""
+
+
+__all__ = [
+    "AgentExecutionError",
+    "AiError",
+    "LlmProviderError",
+    "StructuredOutputParsingError",
+]

hexastack_ai-0.1.0/src/hexastack_ai/infra/__init__.py

@@ -0,0 +1,27 @@
+from hexastack_ai.infra.bootstrap import (
+    AiBootstrapper,
+    AiBootstrapResult,
+)
+from hexastack_ai.infra.config import (
+    HexastackAiConfig,
+    LiteLlmDialectConfig,
+    OllamaDialectConfig,
+    PydanticAiDialectConfig,
+    register_ai_config,
+)
+from hexastack_ai.infra.tools import (
+    create_cqrs_agent,
+    create_tool_for_message,
+)
+
+__all__ = [
+    "AiBootstrapper",
+    "AiBootstrapResult",
+    "create_cqrs_agent",
+    "create_tool_for_message",
+    "HexastackAiConfig",
+    "LiteLlmDialectConfig",
+    "OllamaDialectConfig",
+    "PydanticAiDialectConfig",
+    "register_ai_config",
+]

hexastack_ai-0.1.0/src/hexastack_ai/infra/bootstrap.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass
+
+from hexastack_ai.infra.config import HexastackAiConfig, register_ai_config
+from hexastack_core.adapters.ai import InMemoryLlmProvider
+from hexastack_core.infra.bootstrap import BootstrapContext
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.ports.ai import LlmProviderPort
+from hexastack_core.ports.bootstrap import BootstrapperPort
+
+
+@dataclass(frozen=True)
+class AiBootstrapResult:
+    """Dataclass holding initialized AI provider and configuration."""
+
+    config: HexastackAiConfig
+    llm_provider: LlmProviderPort
+
+
+class AiBootstrapper(BootstrapperPort):
+    """Bootstrap extension initializing LLM provider and agent integration.
+
+    Notes/Architectural Intent:
+        Implements BootstrapperPort at order=18, registering [hexastack.ai] config
+        and binding LlmProviderPort into the DI container. Automatically defaults
+        to InMemoryLlmProvider when provider='memory' for zero-infrastructure test isolation.
+    """
+
+    name: str = "ai"
+    order: int = 18
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Phase 2: Assemble LLM provider adapter in DI container.
+
+        Args:
+            context: BootstrapContext containing DI container and config.
+        """
+        di = context.container
+
+        # 1. Read AI Configuration
+        if HexastackAiConfig in di:
+            ai_config = di.resolve(HexastackAiConfig)
+        else:
+            ai_config = context.get_config("ai", HexastackAiConfig)
+
+        # 2. Build Provider based on config
+        llm_provider: LlmProviderPort
+        if ai_config.provider == "memory":
+            llm_provider = InMemoryLlmProvider()
+            di.add_instance(llm_provider, declared_class=InMemoryLlmProvider)
+        else:
+            from hexastack_ai.adapters.litellm import LiteLlmAdapter
+
+            llm_provider = LiteLlmAdapter(config=ai_config)
+            di.add_instance(llm_provider, declared_class=LiteLlmAdapter)
+
+        # 3. Register in DI container
+        if LlmProviderPort not in di:
+            di.add_instance(llm_provider, declared_class=LlmProviderPort)
+
+        # 4. Store result in context properties
+        ai_result = AiBootstrapResult(
+            config=ai_config,
+            llm_provider=llm_provider,
+        )
+        context.properties["ai_result"] = ai_result
+        context.properties["ai_provider"] = llm_provider
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Phase 1: Register AI configuration schema under 'ai'.
+
+        Args:
+            registry: Target ConfigRegistry instance.
+        """
+        register_ai_config(registry)
+
+
+__all__ = [
+    "AiBootstrapper",
+    "AiBootstrapResult",
+]

hexastack_ai-0.1.0/src/hexastack_ai/infra/config.py

@@ -0,0 +1,110 @@
+from pydantic import BaseModel, Field
+
+from hexastack_core.infra.decorators import config_section
+from hexastack_core.infra.registries.config import ConfigRegistry
+
+
+class LiteLlmDialectConfig(BaseModel):
+    """Dialect configuration options specific to LiteLLM."""
+
+    drop_params: bool = Field(
+        default=True,
+        description="Automatically drop unmapped provider parameters to prevent errors.",
+    )
+    num_retries: int = Field(
+        default=3,
+        description="Number of retry attempts on rate limits or transient errors.",
+    )
+    timeout: float = Field(
+        default=60.0,
+        description="Request timeout in seconds.",
+    )
+    api_base: str | None = Field(
+        default=None,
+        description="Custom API base URL (e.g. for self-hosted LiteLLM proxy or local endpoint).",
+    )
+
+
+class OllamaDialectConfig(BaseModel):
+    """Dialect configuration options for local Ollama instances."""
+
+    base_url: str = Field(
+        default="http://localhost:11434",
+        description="Base URL for the local Ollama daemon.",
+    )
+
+
+class PydanticAiDialectConfig(BaseModel):
+    """Configuration options for PydanticAI agents."""
+
+    max_turns: int = Field(
+        default=10,
+        description="Maximum turn limit for agent tool-calling loops.",
+    )
+    system_prompt: str | None = Field(
+        default=None,
+        description="Default system prompt for agent personas.",
+    )
+
+
+@config_section("ai")
+class HexastackAiConfig(BaseModel):
+    """Configuration schema for Hexastack AI engine under [hexastack.ai].
+
+    Notes/Architectural Intent:
+        Partitions global model settings (model, temperature, tokens) from
+        provider/dialect-specific subsections (LiteLLM, Ollama, PydanticAI).
+    """
+
+    provider: str = Field(
+        default="memory",
+        description="Target LLM provider ('memory', 'litellm', 'openai', 'anthropic', 'gemini', 'ollama').",
+    )
+    model: str = Field(
+        default="gpt-4o-mini",
+        description="Default model identifier (e.g. 'gpt-4o', 'claude-3-5-sonnet-20241022', 'gemini/gemini-1.5-pro').",
+    )
+    temperature: float = Field(
+        default=0.2,
+        description="Sampling temperature between 0.0 and 2.0.",
+    )
+    max_tokens: int = Field(
+        default=2048,
+        description="Maximum tokens for text generation.",
+    )
+    api_key: str | None = Field(
+        default=None,
+        description="Optional explicit API key override (prefers environment variables by default).",
+    )
+
+    # Dialect-specific sections
+    litellm: LiteLlmDialectConfig = Field(
+        default_factory=LiteLlmDialectConfig,
+        description="LiteLLM proxy and retry configuration.",
+    )
+    ollama: OllamaDialectConfig = Field(
+        default_factory=OllamaDialectConfig,
+        description="Ollama local model configuration.",
+    )
+    agent: PydanticAiDialectConfig = Field(
+        default_factory=PydanticAiDialectConfig,
+        description="PydanticAI agent configuration.",
+    )
+
+
+__all__ = [
+    "HexastackAiConfig",
+    "LiteLlmDialectConfig",
+    "OllamaDialectConfig",
+    "PydanticAiDialectConfig",
+    "register_ai_config",
+]
+
+
+def register_ai_config(registry: ConfigRegistry) -> None:
+    """Register AI configuration schema under 'ai' ([hexastack.ai]).
+
+    Args:
+        registry: Target ConfigRegistry instance.
+    """
+    registry.register_config_section("ai", HexastackAiConfig)

hexastack_ai-0.1.0/src/hexastack_ai/infra/tools.py

@@ -0,0 +1,111 @@
+import inspect
+from collections.abc import Sequence
+from typing import Any
+
+from pydantic_ai import Agent
+from pydantic_ai.models import Model
+from pydantic_core import PydanticUndefined
+
+from hexastack_core.domain import Command, Generic, Query
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+
+__all__ = [
+    "create_cqrs_agent",
+    "create_tool_for_message",
+]
+
+
+def create_cqrs_agent(
+    pipeline: ExecutionPipeline,
+    messages: Sequence[type[Command | Query[Any]]],
+    model: str | Model = "test",
+    system_prompt: str | None = None,
+) -> Agent[Any, Any]:
+    """Assemble a PydanticAI Agent with CQRS message handlers reflected as tools.
+
+    Notes/Architectural Intent:
+        Bridges the CQRS message bus with AI agent capabilities. The agent can
+        reason, select appropriate Commands/Queries, and invoke domain logic
+        through the standard Hexastack execution pipeline.
+
+    Args:
+        pipeline: Target ExecutionPipeline.
+        messages: Sequence of Command/Query classes to expose as tools.
+        model: Target model string ('test', 'openai:gpt-4o', 'anthropic:claude-3-5-sonnet') or Model instance.
+        system_prompt: Optional initial persona instructions.
+
+    Returns:
+        Configured PydanticAI Agent instance.
+    """
+    sys_prompt = system_prompt or (
+        "You are an AI assistant capable of executing domain operations "
+        "using the provided tools."
+    )
+    agent: Agent[Any, Any] = Agent(model=model, system_prompt=sys_prompt)
+
+    for msg_cls in messages:
+        tool_fn = create_tool_for_message(msg_cls, pipeline)
+        agent.tool_plain(tool_fn)
+
+    return agent
+
+
+def create_tool_for_message(
+    msg_cls: type[Generic],
+    pipeline: ExecutionPipeline,
+) -> Any:
+    """Create a typed tool function that constructs a CQRS message and executes it.
+
+    Notes/Architectural Intent:
+        Reflects Pydantic model fields dynamically onto the generated tool function's
+        `__signature__` and `__annotations__`. This allows PydanticAI to generate
+        accurate function-calling schemas while dispatching directly through
+        the Hexastack ExecutionPipeline.
+
+    Args:
+        msg_cls: Domain Generic, Command, or Query class.
+        pipeline: Target ExecutionPipeline instance.
+
+    Returns:
+        Callable tool function with dynamic signature and execution dispatcher.
+    """
+
+    async def tool_executor(**kwargs: Any) -> Any:
+        msg = msg_cls.model_validate(kwargs)
+        result = pipeline.execute(msg)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    # Reflect Pydantic model fields into parameter signature and annotations
+    parameters = [
+        inspect.Parameter(
+            name=field_name,
+            kind=inspect.Parameter.KEYWORD_ONLY,
+            annotation=field_info.annotation or Any,
+            default=(
+                field_info.default
+                if field_info.default is not PydanticUndefined
+                else inspect.Parameter.empty
+            ),
+        )
+        for field_name, field_info in msg_cls.model_fields.items()
+    ]
+    setattr(  # noqa: B010
+        tool_executor,
+        "__signature__",
+        inspect.Signature(parameters=parameters),
+    )
+    setattr(  # noqa: B010
+        tool_executor,
+        "__annotations__",
+        {
+            name: field_info.annotation or Any
+            for name, field_info in msg_cls.model_fields.items()
+        },
+    )
+    tool_executor.__name__ = msg_cls.__name__
+    tool_executor.__doc__ = (
+        msg_cls.__doc__ or f"Execute the {msg_cls.__name__} domain operation."
+    )
+    return tool_executor