Metadata-Version: 2.4
Name: hexastack
Version: 0.9.0
Summary: Hexastack - Modern Hexagonal Architecture & CQRS Framework for Python
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: hexastack-logging
Requires-Dist: hexastack-ai ; extra == 'ai'
Requires-Dist: hexastack-ai[all] ; extra == 'all'
Requires-Dist: hexastack-auth ; extra == 'all'
Requires-Dist: hexastack-cli ; extra == 'all'
Requires-Dist: hexastack-core[ssh] ; extra == 'all'
Requires-Dist: hexastack-db[all] ; extra == 'all'
Requires-Dist: hexastack-events ; extra == 'all'
Requires-Dist: hexastack-fastapi[ziti] ; extra == 'all'
Requires-Dist: hexastack-flags ; extra == 'all'
Requires-Dist: hexastack-flow ; extra == 'all'
Requires-Dist: hexastack-graphql ; extra == 'all'
Requires-Dist: hexastack-grpc[reflection] ; extra == 'all'
Requires-Dist: hexastack-logging[all,sentry] ; extra == 'all'
Requires-Dist: hexastack-mcp ; extra == 'all'
Requires-Dist: hexastack-otel[otlp] ; extra == 'all'
Requires-Dist: hexastack-qual[all] ; extra == 'all'
Requires-Dist: hexastack-ui[all] ; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.30.0 ; extra == 'all'
Requires-Dist: hexastack-events[apprise] ; extra == 'apprise'
Requires-Dist: hexastack-auth ; extra == 'auth'
Requires-Dist: hexastack-cli ; extra == 'cli'
Requires-Dist: questionary>=2.1.0 ; extra == 'cli'
Requires-Dist: hexastack-db ; extra == 'db'
Requires-Dist: hexastack-flow[db] ; extra == 'db'
Requires-Dist: hexastack-ui[devtools] ; extra == 'devtools'
Requires-Dist: hexastack-events[dlt] ; extra == 'dlt'
Requires-Dist: hexastack-fastapi[docs] ; extra == 'docs'
Requires-Dist: hexastack-db[duckdb] ; extra == 'duckdb'
Requires-Dist: hexastack-events ; extra == 'events'
Requires-Dist: hexastack-flow[events] ; extra == 'events'
Requires-Dist: hexastack-fastapi ; extra == 'fastapi'
Requires-Dist: hexastack-core[filelock] ; extra == 'filelock'
Requires-Dist: hexastack-events[filelock] ; extra == 'filelock'
Requires-Dist: hexastack-flags[flagd] ; extra == 'flagd'
Requires-Dist: hexastack-flags ; extra == 'flags'
Requires-Dist: hexastack-flow ; extra == 'flow'
Requires-Dist: hexastack-core[fsspec] ; extra == 'fsspec'
Requires-Dist: hexastack-graphql ; extra == 'graphql'
Requires-Dist: hexastack-grpc ; extra == 'grpc'
Requires-Dist: hexastack-cqrs[huey] ; extra == 'huey'
Requires-Dist: hexastack-events[huey] ; extra == 'huey'
Requires-Dist: hexastack-events[janus] ; extra == 'janus'
Requires-Dist: hexastack-events[kafka] ; extra == 'kafka'
Requires-Dist: hexastack-logging[loguru] ; extra == 'loguru'
Requires-Dist: hexastack-ai[mcp] ; extra == 'mcp'
Requires-Dist: hexastack-mcp ; extra == 'mcp'
Requires-Dist: hexastack-db[migrations] ; extra == 'migrations'
Requires-Dist: hexastack-events[msgspec] ; extra == 'msgspec'
Requires-Dist: hexastack-events[nats] ; extra == 'nats'
Requires-Dist: hexastack-ui[nicegui] ; extra == 'nicegui'
Requires-Dist: hexastack-auth[opa] ; extra == 'opa'
Requires-Dist: hexastack-auth[openfga] ; extra == 'openfga'
Requires-Dist: hexastack-flow[otel] ; extra == 'otel'
Requires-Dist: hexastack-otel ; extra == 'otel'
Requires-Dist: hexastack-otel[otlp] ; extra == 'otlp'
Requires-Dist: hexastack-db[pgvector] ; extra == 'pgvector'
Requires-Dist: hexastack-db[postgresql] ; extra == 'postgresql'
Requires-Dist: locust>=2.46.6 ; extra == 'profiling'
Requires-Dist: memray>=1.20.0 ; extra == 'profiling'
Requires-Dist: py-spy>=0.4.2 ; extra == 'profiling'
Requires-Dist: hexastack-ai[qdrant] ; extra == 'qdrant'
Requires-Dist: hexastack-qual ; extra == 'qual'
Requires-Dist: hexastack-qual[events] ; extra == 'qual-events'
Requires-Dist: hexastack-qual[mcp] ; extra == 'qual-mcp'
Requires-Dist: hexastack-qual[ui] ; extra == 'qual-ui'
Requires-Dist: hexastack-fastapi[ratelimit] ; extra == 'ratelimit'
Requires-Dist: hexastack-core[redis] ; extra == 'redis'
Requires-Dist: hexastack-grpc[reflection] ; extra == 'reflection'
Requires-Dist: hexastack-logging[rich] ; extra == 'rich'
Requires-Dist: hexastack-logging[sentry] ; extra == 'sentry'
Requires-Dist: hexastack-auth[spiffe] ; extra == 'spiffe'
Requires-Dist: hexastack-db ; extra == 'sql'
Requires-Dist: hexastack-events[sql] ; extra == 'sql'
Requires-Dist: hexastack-db[sqlite] ; extra == 'sqlite'
Requires-Dist: hexastack-core[ssh] ; extra == 'ssh'
Requires-Dist: hexastack-logging[structlog] ; extra == 'structlog'
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-ui[textual] ; extra == 'textual'
Requires-Dist: hexastack-ui[all] ; extra == 'ui'
Requires-Dist: hexastack-core[valkey] ; extra == 'valkey'
Requires-Dist: hexastack-fastapi ; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.30.0 ; extra == 'web'
Requires-Dist: hexastack-fastapi[ziti] ; extra == 'ziti'
Requires-Python: >=3.13
Provides-Extra: ai
Provides-Extra: all
Provides-Extra: apprise
Provides-Extra: auth
Provides-Extra: cli
Provides-Extra: db
Provides-Extra: devtools
Provides-Extra: dlt
Provides-Extra: docs
Provides-Extra: duckdb
Provides-Extra: events
Provides-Extra: fastapi
Provides-Extra: filelock
Provides-Extra: flagd
Provides-Extra: flags
Provides-Extra: flow
Provides-Extra: fsspec
Provides-Extra: graphql
Provides-Extra: grpc
Provides-Extra: huey
Provides-Extra: janus
Provides-Extra: kafka
Provides-Extra: loguru
Provides-Extra: mcp
Provides-Extra: migrations
Provides-Extra: msgspec
Provides-Extra: nats
Provides-Extra: nicegui
Provides-Extra: opa
Provides-Extra: openfga
Provides-Extra: otel
Provides-Extra: otlp
Provides-Extra: pgvector
Provides-Extra: postgresql
Provides-Extra: profiling
Provides-Extra: qdrant
Provides-Extra: qual
Provides-Extra: qual-events
Provides-Extra: qual-mcp
Provides-Extra: qual-ui
Provides-Extra: ratelimit
Provides-Extra: redis
Provides-Extra: reflection
Provides-Extra: rich
Provides-Extra: sentry
Provides-Extra: spiffe
Provides-Extra: sql
Provides-Extra: sqlite
Provides-Extra: ssh
Provides-Extra: structlog
Provides-Extra: testing
Provides-Extra: textual
Provides-Extra: ui
Provides-Extra: valkey
Provides-Extra: web
Provides-Extra: ziti
Description-Content-Type: text/markdown

![hexastack](../../docs/assets/static/logos/packages/hexastack.png)

# hexastack

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

[![Use this template](https://img.shields.io/badge/GitHub-Use%20this%20template-2ea44f?logo=github)](https://github.com/TheTrueSCU/hexastack-template/generate)
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/TheTrueSCU/hexastack-template)
[![PyPI: hexastack](https://img.shields.io/pypi/v/hexastack.svg)](https://pypi.org/project/hexastack/)
[![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)](https://codecov.io/github/TheTrueSCU/hexastack)
[![Part of Hexastack](https://img.shields.io/badge/part%20of-hexastack-blueviolet.svg)](https://dopplereffect.us/hexastack/)
[![Accessibility: WCAG 2.1 AA](https://img.shields.io/badge/accessibility-WCAG%202.1%20AA-brightgreen.svg)](https://www.w3.org/WAI/WCAG21/quickref/?levels=aa)
[![Tested with: axe--core](https://img.shields.io/badge/tested%20with-axe--core-4353ff.svg?logo=deque)](https://github.com/dequelabs/axe-core)
[![Governed by Hexaqual](https://img.shields.io/badge/governed%20by-hexaqual-10b981.svg)](https://dopplereffect.us/hexaqual/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)

> Part of the [**Hexastack Framework**](https://dopplereffect.us/hexastack/) · Governed by [**Hexaqual**](https://dopplereffect.us/hexaqual/).
---

## 1. Overview & Capabilities

- **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]`, `pip install hexastack[ui]`, `pip install hexastack[flow]`).
- **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.
- **Typo-Tolerant Diagnostic CLI**: Powered by `TyperSuggest`, the `hexastack` terminal command provides auto-suggestions for misspelled commands and flags, 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.
- **Turnkey DevTools Console**: Launch the reactive developer dashboard (`hexastack ui`) with live resource interconnect topology, Hexaflow workflow DAG visualizer, saga simulations, and dynamic feature flag hot-swapping.

---

## 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])"]
        FLOW["hexastack-flow (hexastack[flow])"]
        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).
- `[flow]`: Installs `hexastack-flow` for durable workflow and saga orchestration with hexaflow, CQRS step runners, DB checkpoints, and event streaming.
- `[graphql]`: Installs `hexastack-graphql`.
- `[mcp]`: Installs `hexastack-mcp` for Model Context Protocol AI agent tools.
- `[grpc]`: Installs `hexastack-grpc` for high-performance RPC services.
- `[qual]`: Installs `hexastack-qual` for quality, governance, and release engineering with hexaqual.
- `[ui]`: Installs `hexastack-ui` for NiceGUI & Textual interactive DevTools consoles.
- `[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]"

# Durable workflows & saga orchestration
pip install "hexastack[flow]"

# 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. Project Scaffolding & Archetypes (`hexastack new` & `hexastack init`)

Hexastack includes a production-grade scaffolding engine that creates fully functioning, decoupled microservices adhering strictly to Hexagonal Architecture, complete with pre-configured `.importlinter` boundaries, GitHub Actions CI workflows, multi-stage rootless Dockerfiles, passing test suites, and secret scanning.

### Installation & Execution

You can run the scaffolding engine ephemerally with `uvx`, or install the CLI globally as an isolated tool:

```bash
# Option A: Run ephemerally without installing
uvx hexastack init
uvx hexastack new web-api my-service

# Option B: Install globally via uv tool
uv tool install "hexastack[all]"

# For local framework development (editable checkout):
uv tool install --editable "packages/hexastack[all]"
```

### Interactive Scaffolding Wizard (`hexastack init`)

Launch an interactive terminal wizard that guides you through template selection, database drivers, auth, transports, and telemetry:

```bash
hexastack init
```

### Direct Archetype Scaffolding (`hexastack new`)

Generate microservices in a single command using one of the pre-built blueprints:

```bash
# Enterprise grade multi-transport service (FastAPI + gRPC + GraphQL + MCP + Outbox + Release + OpenSSF)
hexastack new enterprise core-platform

# Asynchronous event-driven microservice with CloudEvents 1.0 and Transactional Outbox
hexastack new event-driven billing-worker

# GraphQL presentation service with Strawberry schema and CQRS bus
hexastack new graphql-service analytics-service

# High-throughput gRPC binary RPC microservice with in-process ProtoCompiler and Buf linting
hexastack new grpc-service payment-gateway

# AI Agent service equipped with Model Context Protocol (MCP) server & tools
hexastack new mcp-agent customer-assistant

# Ultra-minimal CQRS microservice
hexastack new minimal lightweight-worker

# Web API service with FastAPI, SQLite/Postgres, and OpenAPI specs
hexastack new web-api order-service
```

### Scaffolded Service Anatomy

Every scaffolded service immediately includes:
1. **Strict Layer Isolation**: `domain/` (0 framework dependencies), `ports/` (abstract protocols), `adapters/driving/` (FastAPI / gRPC / CLI / MCP), `adapters/driven/` (SQLAlchemy / InMemory / Outbox), and `infra/` (bootstrappers & configuration).
2. **Golden-Path Multi-Stage Dockerfile**: Ultra-fast `uv`-cached builder layer, rootless non-root runtime user (`appuser:10001`), `/health` probe `HEALTHCHECK`, and `.dockerignore`.
3. **Automated Quality Gates**: `.importlinter` rules enforcing directional purity, pre-commit config with `detect-secrets`, `pip-audit`, and `ruff`, plus a complete `pytest` unit test suite.
4. **Automated Release Pipeline (`--with-release`)**: `.github/workflows/release.yml` with `uv build`, `pypa/gh-action-pypi-publish`, and SPDX/CycloneDX SBOM generation via `anchore/sbom-action`, plus a `CHANGELOG.md`.
5. **OpenSSF Security Suite (`--with-openssf`)**: `.github/workflows/scorecard.yml` (weekly security analysis), `SECURITY.md`, `GOVERNANCE.md`, and `CODE_OF_CONDUCT.md`.


---

## 5. 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 migrate
hexastack db current
hexastack db history
```
