hexastack-ai
AI engine, LLM provider integration (LiteLLM, Instructor, PydanticAI), and CQRS agent tool reflection for the Hexastack hexagonal architecture framework.
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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hexastack_ai-0.10.0.tar.gz | 22.3 kB | Without provenance | Details for hexastack_ai-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hexastack_ai-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for hexastack_ai-0.10.0-py3-none-any.whl |
Total release size: 53.1 kB
Release files / hexastack_ai-0.10.0.tar.gz
| Download URL | hexastack_ai-0.10.0.tar.gz |
|---|---|
| Size | 22.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b52546d950b1121218a73389c2f1d5ac5767cb43af9cf0020d92947d4fe81c7a
|
|
BLAKE2b-256 checksum How to use checksums |
179ea163eab872cf842c27465a0ab43c80bcfc3bca4fc55ce2b3063f9eeb0624
|
| 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.0-py3-none-any.whl
| Download URL | hexastack_ai-0.10.0-py3-none-any.whl |
|---|---|
| Size | 30.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac90d89b2d5d4f66c5592a3d98829c713877df5b83276d9fcf4bd10e92b33f38
|
|
BLAKE2b-256 checksum How to use checksums |
3368a45d0260becdc9b5d2ee01b6afb17de219aa7b69063603e4807431883b42
|
| 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.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.