Metadata-Version: 2.3
Name: hexastack
Version: 0.0.0
Summary: Hexastack - Modern Hexagonal Architecture & CQRS Framework for Python
Author: Richard West
Author-email: Richard West <dopplereffect.us@gmail.com>
Requires-Dist: hexastack-core
Requires-Dist: hexastack-cqrs
Requires-Dist: hexastack-logging
Requires-Dist: hexastack-ai ; extra == 'ai'
Requires-Dist: hexastack-ai ; extra == 'all'
Requires-Dist: hexastack-auth ; extra == 'all'
Requires-Dist: hexastack-cli ; extra == 'all'
Requires-Dist: hexastack-db ; extra == 'all'
Requires-Dist: hexastack-events ; extra == 'all'
Requires-Dist: hexastack-fastapi ; extra == 'all'
Requires-Dist: hexastack-flags ; extra == 'all'
Requires-Dist: hexastack-graphql ; extra == 'all'
Requires-Dist: hexastack-grpc ; extra == 'all'
Requires-Dist: hexastack-mcp ; extra == 'all'
Requires-Dist: hexastack-otel ; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.30.0 ; extra == 'all'
Requires-Dist: hexastack-auth ; extra == 'auth'
Requires-Dist: hexastack-cli ; extra == 'cli'
Requires-Dist: hexastack-db ; extra == 'db'
Requires-Dist: hexastack-fastapi[docs] ; extra == 'docs'
Requires-Dist: hexastack-events ; extra == 'events'
Requires-Dist: hexastack-fastapi ; extra == 'fastapi'
Requires-Dist: hexastack-flags ; extra == 'flags'
Requires-Dist: hexastack-graphql ; extra == 'graphql'
Requires-Dist: hexastack-grpc ; extra == 'grpc'
Requires-Dist: hexastack-mcp ; extra == 'mcp'
Requires-Dist: hexastack-otel ; extra == 'otel'
Requires-Dist: hexastack-db ; extra == 'sql'
Requires-Dist: faker>=33.0.0 ; extra == 'testing'
Requires-Dist: hypothesis>=6.100.0 ; extra == 'testing'
Requires-Dist: inline-snapshot>=0.35.4 ; extra == 'testing'
Requires-Dist: playwright>=1.49.0 ; extra == 'testing'
Requires-Dist: pytest-archon>=0.0.7 ; extra == 'testing'
Requires-Dist: schemathesis>=3.39.0 ; extra == 'testing'
Requires-Dist: hexastack-fastapi[ui] ; extra == 'ui'
Requires-Dist: hexastack-fastapi ; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.30.0 ; extra == 'web'
Requires-Python: >=3.13
Provides-Extra: ai
Provides-Extra: all
Provides-Extra: auth
Provides-Extra: cli
Provides-Extra: db
Provides-Extra: docs
Provides-Extra: events
Provides-Extra: fastapi
Provides-Extra: flags
Provides-Extra: graphql
Provides-Extra: grpc
Provides-Extra: mcp
Provides-Extra: otel
Provides-Extra: sql
Provides-Extra: testing
Provides-Extra: ui
Provides-Extra: web
Description-Content-Type: text/markdown

# hexastack

> The unified distribution package and diagnostic CLI for the Hexastack framework.

[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)

---

## 1. Overview & Capabilities

`hexastack` acts as the umbrella distribution for the entire Hexastack monorepo, offering:

- **Scoped Extras**: Single-command installs for scoped use cases (e.g., `pip install hexastack[cli]`, `pip install hexastack[web]`, `pip install hexastack[graphql]`, `pip install hexastack[mcp]`, `pip install hexastack[grpc]`, `pip install hexastack[db]`).
- **Zero-Install Project Scaffolding**: `hexastack new <template> <name>` instantly scaffolds production-grade microservices adhering strictly to Hexagonal Architecture, complete with tiered CI, import-linter contracts, and passing test suites.
- **Interactive Diagnostic CLI**: The `hexastack` terminal command provides system health checks, package inspection, CQRS message route exploration, local FastAPI dev server launching, MCP server execution, gRPC daemon hosting, and Alembic database migration management.

---

## 2. Monorepo & Sibling Relationships

```mermaid
graph TD
    subgraph Umbrella ["hexastack (Distribution & CLI App)"]
        CLI_APP["hexastack CLI Entrypoint"]
        DIAG["Diagnostics Handlers (info, inspect, ping)"]
        DEMO_SERVER["FastAPI Demo Server (serve)"]
        DB_CLI["Alembic Migration Tooling (db)"]
        MCP_CLI["MCP Server Runner (mcp)"]
        GRPC_CLI["gRPC Server Daemon (grpc)"]
    end

    subgraph BaseDependencies ["Default Direct Dependencies"]
        CORE["hexastack-core"]
        CQRS["hexastack-cqrs"]
        LOG["hexastack-logging"]
    end

    subgraph ScopedExtras ["Optional Scoped Extras"]
        AUTH["hexastack-auth (hexastack[auth])"]
        OTEL["hexastack-otel (hexastack[otel])"]
        EVENTS["hexastack-events (hexastack[events])"]
        AI["hexastack-ai (hexastack[ai])"]
        CLI["hexastack-cli (hexastack[cli])"]
        FASTAPI["hexastack-fastapi (hexastack[fastapi])"]
        GRAPHQL["hexastack-graphql (hexastack[graphql])"]
        MCP["hexastack-mcp (hexastack[mcp])"]
        GRPC["hexastack-grpc (hexastack[grpc])"]
        DB["hexastack-db (hexastack[db])"]
        FLAGS["hexastack-flags (hexastack[flags])"]
        UVICORN["uvicorn[standard] (hexastack[web])"]
    end

    Umbrella --> CORE
    Umbrella --> CQRS
    Umbrella --> LOG

    CLI_APP -. optional extra .-> CLI
    DEMO_SERVER -. optional extra .-> FASTAPI
    DEMO_SERVER -. optional extra .-> UVICORN
    DB_CLI -. optional extra .-> DB
    MCP_CLI -. optional extra .-> MCP
    GRPC_CLI -. optional extra .-> GRPC
```

### Explicit Dependencies (Direct)
- `hexastack-core`: Core kernel, DI container (`rodi`), and bootstrap engine.
- `hexastack-cqrs`: Command, query, and event execution buses.
- `hexastack-logging`: Structured logging and telemetry.

### Optional Integrations (Extras)
- `[auth]`: Installs `hexastack-auth` for security, RBAC, JWT, PBKDF2, and `@authorize` middleware.
- `[otel]`: Installs `hexastack-otel` for OpenTelemetry distributed tracing and OTLP export.
- `[events]`: Installs `hexastack-events` for CloudEvents 1.0, Transactional Outbox, and streaming buses.
- `[ai]`: Installs `hexastack-ai` for LiteLLM, Instructor, PydanticAI, and reflective agent tools.
- `[cli]`: Installs `hexastack-cli` for interactive CLI commands.
- `[db]` / `[sql]`: Installs `hexastack-db` for persistence and Alembic migrations.
- `[fastapi]`: Installs `hexastack-fastapi`.
- `[flags]`: Installs `hexastack-flags` for CNCF OpenFeature enterprise feature flag providers (Flagd, Unleash, Flipt).
- `[graphql]`: Installs `hexastack-graphql`.
- `[mcp]`: Installs `hexastack-mcp` for Model Context Protocol AI agent tools.
- `[grpc]`: Installs `hexastack-grpc` for high-performance RPC services.
- `[web]`: Installs `hexastack-fastapi` and `uvicorn[standard]`.
- `[docs]`: Installs `zensical` for static documentation generation and hosting.
- `[testing]`: Installs recommended testing tools (`hypothesis`, `inline-snapshot`, `playwright`, `pytest-archon`, `schemathesis`).
- `[all]`: Complete installation with all adapters and development tools.

---

## 3. Installation

```bash
# Minimal installation
pip install hexastack

# Testing toolkit (Archon boundary checks, Hypothesis fuzzing, Schemathesis)
pip install "hexastack[testing]"

# CNCF OpenFeature flags
pip install "hexastack[flags]"

# Security & RBAC
pip install "hexastack[auth]"

# OpenTelemetry Tracing
pip install "hexastack[otel]"

# CloudEvents & Transactional Outbox
pip install "hexastack[events]"

# AI Integration (LiteLLM, Instructor, PydanticAI)
pip install "hexastack[ai]"

# CLI support
pip install "hexastack[cli]"

# Full web stack (FastAPI + Uvicorn)
pip install "hexastack[web]"

# GraphQL support
pip install "hexastack[graphql]"

# Model Context Protocol support
pip install "hexastack[mcp]"

# gRPC support
pip install "hexastack[grpc]"

# Database support with migrations
pip install "hexastack[db]"

# Complete ecosystem
pip install "hexastack[all]"
```

---

## 4. CLI Diagnostic Commands

When installed with `hexastack[all]` or `hexastack[cli]`:

```bash
# Check installed packages and optional dependency statuses
hexastack info

# Inspect registered CQRS commands, queries, and configs
hexastack inspect registry

# Send a test ping command through the CQRS pipeline
hexastack ping --message "Hello Hexastack"

# Launch local FastAPI dev server with live reload (requires hexastack[web])
hexastack serve --host 127.0.0.1 --port 8000

# Launch MCP server in stdio mode (requires hexastack[mcp])
hexastack mcp run

# Launch gRPC daemon (requires hexastack[grpc])
hexastack grpc serve --host 0.0.0.0 --port 50051

# Manage database migrations (requires hexastack[db])
hexastack db init migrations/
hexastack db revision "add users table"
hexastack db upgrade head
hexastack db current
hexastack db history
```
