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.9.0

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.9.0
File Size Uploaded Provenance Actions
hexastack_ai-0.9.0.tar.gz 22.3 kB Without provenance Details for hexastack_ai-0.9.0.tar.gz

Built distribution (wheel)

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

Total release size: 53.1 kB

Release files / hexastack_ai-0.9.0.tar.gz

Download URL hexastack_ai-0.9.0.tar.gz
Size 22.3 kB
Tags Source
SHA-256 checksum
How to use checksums
39c3b5c10083e3d9a785cf58934b791e39b170d9da602c6c404791a0f11b1058
BLAKE2b-256 checksum
How to use checksums
23ed0f41f7848c79ab6f60d5abe73d89c0799aa6b31fb84125a18204ba90a39b
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.9.0-py3-none-any.whl

Download URL hexastack_ai-0.9.0-py3-none-any.whl
Size 30.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f7c4b659248ca10fa89d56ce725c5cbdb463f03933ae5ef900b393e4bf57e837
BLAKE2b-256 checksum
How to use checksums
fea55502af32b498e2da1a4f90ccaf6685379ed5f75db6eeff27cc9e3bbb0e69
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.9.0

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