Skip to main content

hexastack-ai

hexastack-ai

AI engine, LLM provider integration (LiteLLM, Instructor, PydanticAI), and CQRS agent tool reflection for the Hexastack hexagonal architecture framework.

PyPI: hexastack-ai Python 3.13+ Coverage Part of Hexastack Governed by Hexaqual License: Apache 2.0

Part of the Hexastack Framework · Governed by Hexaqual.


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

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

# Standalone install
pip install hexastack-ai

# With MCP integration (external servers & local registry)
pip install "hexastack-ai[mcp]"

# Via umbrella package
pip install "hexastack[ai,mcp]"

4. Configuration Reference

[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

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

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.")

3. In-Process Auto-Binding of Local @mcp_tool Registry

from hexastack_ai.infra.tools import create_cqrs_agent
from hexastack_mcp.infra.decorators import get_mcp_registry

# Any command/query annotated with @mcp_tool is automatically bound in-process:
agent = create_cqrs_agent(
    pipeline=runtime.pipeline,
    registry=get_mcp_registry(),
    read_only=True,  # Restricts agent to read-only queries (least-privilege)
    model="openai/gpt-4o",
)

4. Consuming External MCP Servers (Filesystem, SQLite, Playwright)

from mcp.client.session import ClientSession
from hexastack_ai.adapters.mcp import attach_external_mcp_tools


# Connect external MCP tools dynamically to any PydanticAI agent:
async def setup_agent_with_mcp(agent, session: ClientSession):
    registered_tools = await attach_external_mcp_tools(agent, session)
    print(f"Attached external tools: {registered_tools}")

Metadata

Release files for hexastack-ai 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hexastack-ai 0.10.1
File Size Uploaded Provenance Actions
hexastack_ai-0.10.1.tar.gz 22.3 kB Without provenance Details for hexastack_ai-0.10.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hexastack-ai 0.10.1
File Interpreter ABI Platform Actions
hexastack_ai-0.10.1-py3-none-any.whl Python 3 none any Details for hexastack_ai-0.10.1-py3-none-any.whl

Total release size: 53.1 kB

Release files / hexastack_ai-0.10.1.tar.gz

Download URL hexastack_ai-0.10.1.tar.gz
Size 22.3 kB
Tags Source
SHA-256 checksum
How to use checksums
a50a28b1e2773c5deaedd1515bf0c7edede585371b544e885f9d560cfec27bbc
BLAKE2b-256 checksum
How to use checksums
b4507ee80004b0c1b92b3ff12278771684be252bf7fa0f3d0728378aad0163a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / hexastack_ai-0.10.1-py3-none-any.whl

Download URL hexastack_ai-0.10.1-py3-none-any.whl
Size 30.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1810851cf4040c4f2a82cca3a8a580c4788acf86cae418daf3ac8251c2b8d32f
BLAKE2b-256 checksum
How to use checksums
d927db8539a28384930fde255cb99c050d52e82f671b0f60292119c0cdf21e28
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for hexastack-ai 0.10.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page