hexastack-core 0.0.0__tar.gz

hexastack_core-0.0.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.3
+Name: hexastack-core
+Version: 0.0.0
+Summary: Add your description here
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: rodi>=2.1.0
+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: pytest-archon>=0.0.7 ; extra == 'testing'
+Requires-Python: >=3.13
+Provides-Extra: testing
+Description-Content-Type: text/markdown
+
+# hexastack-core
+
+> The foundational kernel of Hexastack: dependency injection, abstract ports, domain abstractions, configuration registry, and the modular bootstrap lifecycle.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-core` serves as the zero-dependency (excluding `pydantic` and `rodi`) microkernel for all Hexastack packages. It establishes:
+
+- **Dependency Injection Engine**: Powered by `rodi`, managing service lifecycles (singleton, scoped, transient).
+- **Feature Flag Port & Providers**: Vendor-agnostic feature toggling (`FeatureFlagPort`, `EvaluationContext`, `ConfigFeatureFlagAdapter`, `InMemoryFeatureFlagAdapter`) with multi-tenant and ambient `UserContext` targeting.
+- **Core Domain Primitives**: Generic `Result[T, E]`, generic types, and standard exception hierarchies (`HexastackError`, `ConfigurationError`, `MissingDependencyError`).
+- **Core Port Contracts**: Standard abstract protocols and ABCs for repositories (`Repository[E, ID]`), unit of work (`UnitOfWork`), logging (`LoggerPort`), presenters (`PresenterPort`), feature flags (`FeatureFlagPort`), and bootstrappers (`BootstrapperPort`).
+- **Configuration & Type Registries**: Type-safe Pydantic configuration parsing from TOML (`ConfigRegistry`) and generic type registries (`GenericTypeRegistry`).
+- **Three-Phase Bootstrap Engine**: Deterministic orchestration of Phase 1 config registration, Phase 2 container assembly, and Phase 3 reflective scanning.
+- **Testing & Quality Toolkit**:
+  - `assert_clean_architecture(...)`: Hexagonal architecture boundary verification powered by `pytest-archon`.
+  - `create_test_runtime(...)`: Lightweight in-memory DI test harness and doubles (`TestRuntime`).
+  - `cqrs_strategy(...)`: Hypothesis property-based fuzzing strategy generator for Pydantic/dataclass CQRS models.
+  - Feature flag testing: `@parametrize_flags`, `flag_scope`, `@require_feature`, and `@require_extra`.
+- **Context Utilities**: Async-safe correlation ID and context variable management (`get_correlation_id`, `set_correlation_id`, `UserContext`).
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_core/
+├── domain/          # Result[T, E], HexastackError, Entity, ValueObject, EvaluationContext
+├── ports/           # Repository, UnitOfWork, BootstrapperPort, LoggerPort, PresenterPort, FeatureFlagPort
+├── adapters/        # InMemoryRepository, InMemoryUnitOfWork, InMemoryFeatureFlagAdapter, ConfigFeatureFlagAdapter
+├── infra/           # Bootstrap engine, ConfigRegistry, GenericTypeRegistry, decorators
+├── testing/         # assert_clean_architecture, create_test_runtime, cqrs_strategy, flag_scope, isolation
+└── utils/           # Context variable utilities, reflection helpers
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Bootstrap** | `bootstrap`, `BootstrapContext`, `BootstrapResult`, `scan_modules` |
+| **Config** | `ConfigRegistry`, `HexastackConfig`, `HexastackCoreConfig`, `@config_section` |
+| **Context** | `get_correlation_id`, `set_correlation_id`, `correlation_scope`, `UserContext` |
+| **Domain** | `Result`, `Ok`, `Err`, `HexastackError`, `ConfigurationError`, `MissingDependencyError`, `EntityNotFoundError` |
+| **Feature Flags** | `EvaluationContext`, `FlagEvaluationDetails`, `InMemoryFeatureFlagAdapter`, `ConfigFeatureFlagAdapter` |
+| **Ports** | `BootstrapperPort`, `Repository`, `AsyncRepository`, `UnitOfWork`, `AsyncUnitOfWork`, `LoggerPort`, `PresenterPort`, `FeatureFlagPort` |
+| **Registries** | `GenericTypeRegistry`, `ExceptionRegistry` |
+| **Testing** | `assert_clean_architecture`, `create_test_runtime`, `TestRuntime`, `cqrs_strategy`, `faker_strategy`, `flag_scope`, `generate_synthetic_payload`, `isolate_registries`, `parametrize_flags`, `@require_extra`, `@require_feature`, `seeded_faker` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph SiblingPackages ["Dependent Sibling Packages"]
+        CQRS["hexastack-cqrs"]
+        LOG["hexastack-logging"]
+        DB["hexastack-db"]
+        FASTAPI["hexastack-fastapi"]
+        GRAPHQL["hexastack-graphql"]
+        MCP["hexastack-mcp"]
+        GRPC["hexastack-grpc"]
+        CLI["hexastack-cli"]
+        UMBRELLA["hexastack"]
+    end
+
+    subgraph CoreKernel ["hexastack-core"]
+        DI["rodi.Container"]
+        BOOT["Bootstrap Engine"]
+        PORTS["Abstract Ports (UoW, Repo, Logger)"]
+        CONF["ConfigRegistry"]
+    end
+
+    CQRS -->|implements BootstrapperPort, uses rodi| CoreKernel
+    LOG -->|implements LoggerPort & BootstrapperPort| CoreKernel
+    DB -->|implements Repository & UnitOfWork ports| CoreKernel
+    FASTAPI -->|implements BootstrapperPort, consumes DI| CoreKernel
+    GRAPHQL -->|implements BootstrapperPort, consumes DI| CoreKernel
+    MCP -->|implements BootstrapperPort, consumes DI| CoreKernel
+    GRPC -->|implements BootstrapperPort, consumes DI| CoreKernel
+    CLI -->|implements BootstrapperPort, consumes DI| CoreKernel
+    UMBRELLA -->|orchestrates bootstrap| CoreKernel
+```
+
+### Explicit Dependencies (Direct)
+- `pydantic>=2.13.4`: Schema validation and config parsing.
+- `rodi>=2.1.0`: Fast, lightweight dependency injection container.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **Provides Ports**: Defines `UnitOfWorkPort` and `Repository` implemented by `hexastack-db`.
+- **Provides Telemetry Contract**: Defines `LoggerPort` implemented by `hexastack-logging`.
+- **Provides Bootstrap Framework**: All siblings expose extension entry points implementing `BootstrapperPort`.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone installation
+pip install hexastack-core
+
+# Via umbrella package
+pip install hexastack
+```
+
+---
+
+## 5. Configuration Reference
+
+Configuration schemas are registered under `[hexastack]`:
+
+```toml
+[hexastack]
+app_name = "my-application"
+environment = "production" # "development", "staging", "production", "test"
+debug = false
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_core.ports.bootstrap import BootstrapperPort, BootstrapContext
+from hexastack_core.domain.result import Ok, Err, Result
+
+
+# 1. Implement a custom extension
+class ServiceBootstrapper(BootstrapperPort):
+    name = "custom_service"
+    order = 10
+
+    def configure(self, context: BootstrapContext) -> None:
+        context.container.add_instance("Service Configured", declared_class=str)
+
+
+# 2. Run deterministic bootstrap
+result = bootstrap(bootstrappers=[ServiceBootstrapper()], auto_discover=False)
+value = result.container.get(str)
+print(value)  # "Service Configured"
+```

hexastack_core-0.0.0/README.md

@@ -0,0 +1,146 @@
+# hexastack-core
+
+> The foundational kernel of Hexastack: dependency injection, abstract ports, domain abstractions, configuration registry, and the modular bootstrap lifecycle.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-core` serves as the zero-dependency (excluding `pydantic` and `rodi`) microkernel for all Hexastack packages. It establishes:
+
+- **Dependency Injection Engine**: Powered by `rodi`, managing service lifecycles (singleton, scoped, transient).
+- **Feature Flag Port & Providers**: Vendor-agnostic feature toggling (`FeatureFlagPort`, `EvaluationContext`, `ConfigFeatureFlagAdapter`, `InMemoryFeatureFlagAdapter`) with multi-tenant and ambient `UserContext` targeting.
+- **Core Domain Primitives**: Generic `Result[T, E]`, generic types, and standard exception hierarchies (`HexastackError`, `ConfigurationError`, `MissingDependencyError`).
+- **Core Port Contracts**: Standard abstract protocols and ABCs for repositories (`Repository[E, ID]`), unit of work (`UnitOfWork`), logging (`LoggerPort`), presenters (`PresenterPort`), feature flags (`FeatureFlagPort`), and bootstrappers (`BootstrapperPort`).
+- **Configuration & Type Registries**: Type-safe Pydantic configuration parsing from TOML (`ConfigRegistry`) and generic type registries (`GenericTypeRegistry`).
+- **Three-Phase Bootstrap Engine**: Deterministic orchestration of Phase 1 config registration, Phase 2 container assembly, and Phase 3 reflective scanning.
+- **Testing & Quality Toolkit**:
+  - `assert_clean_architecture(...)`: Hexagonal architecture boundary verification powered by `pytest-archon`.
+  - `create_test_runtime(...)`: Lightweight in-memory DI test harness and doubles (`TestRuntime`).
+  - `cqrs_strategy(...)`: Hypothesis property-based fuzzing strategy generator for Pydantic/dataclass CQRS models.
+  - Feature flag testing: `@parametrize_flags`, `flag_scope`, `@require_feature`, and `@require_extra`.
+- **Context Utilities**: Async-safe correlation ID and context variable management (`get_correlation_id`, `set_correlation_id`, `UserContext`).
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_core/
+├── domain/          # Result[T, E], HexastackError, Entity, ValueObject, EvaluationContext
+├── ports/           # Repository, UnitOfWork, BootstrapperPort, LoggerPort, PresenterPort, FeatureFlagPort
+├── adapters/        # InMemoryRepository, InMemoryUnitOfWork, InMemoryFeatureFlagAdapter, ConfigFeatureFlagAdapter
+├── infra/           # Bootstrap engine, ConfigRegistry, GenericTypeRegistry, decorators
+├── testing/         # assert_clean_architecture, create_test_runtime, cqrs_strategy, flag_scope, isolation
+└── utils/           # Context variable utilities, reflection helpers
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Bootstrap** | `bootstrap`, `BootstrapContext`, `BootstrapResult`, `scan_modules` |
+| **Config** | `ConfigRegistry`, `HexastackConfig`, `HexastackCoreConfig`, `@config_section` |
+| **Context** | `get_correlation_id`, `set_correlation_id`, `correlation_scope`, `UserContext` |
+| **Domain** | `Result`, `Ok`, `Err`, `HexastackError`, `ConfigurationError`, `MissingDependencyError`, `EntityNotFoundError` |
+| **Feature Flags** | `EvaluationContext`, `FlagEvaluationDetails`, `InMemoryFeatureFlagAdapter`, `ConfigFeatureFlagAdapter` |
+| **Ports** | `BootstrapperPort`, `Repository`, `AsyncRepository`, `UnitOfWork`, `AsyncUnitOfWork`, `LoggerPort`, `PresenterPort`, `FeatureFlagPort` |
+| **Registries** | `GenericTypeRegistry`, `ExceptionRegistry` |
+| **Testing** | `assert_clean_architecture`, `create_test_runtime`, `TestRuntime`, `cqrs_strategy`, `faker_strategy`, `flag_scope`, `generate_synthetic_payload`, `isolate_registries`, `parametrize_flags`, `@require_extra`, `@require_feature`, `seeded_faker` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph SiblingPackages ["Dependent Sibling Packages"]
+        CQRS["hexastack-cqrs"]
+        LOG["hexastack-logging"]
+        DB["hexastack-db"]
+        FASTAPI["hexastack-fastapi"]
+        GRAPHQL["hexastack-graphql"]
+        MCP["hexastack-mcp"]
+        GRPC["hexastack-grpc"]
+        CLI["hexastack-cli"]
+        UMBRELLA["hexastack"]
+    end
+
+    subgraph CoreKernel ["hexastack-core"]
+        DI["rodi.Container"]
+        BOOT["Bootstrap Engine"]
+        PORTS["Abstract Ports (UoW, Repo, Logger)"]
+        CONF["ConfigRegistry"]
+    end
+
+    CQRS -->|implements BootstrapperPort, uses rodi| CoreKernel
+    LOG -->|implements LoggerPort & BootstrapperPort| CoreKernel
+    DB -->|implements Repository & UnitOfWork ports| CoreKernel
+    FASTAPI -->|implements BootstrapperPort, consumes DI| CoreKernel
+    GRAPHQL -->|implements BootstrapperPort, consumes DI| CoreKernel
+    MCP -->|implements BootstrapperPort, consumes DI| CoreKernel
+    GRPC -->|implements BootstrapperPort, consumes DI| CoreKernel
+    CLI -->|implements BootstrapperPort, consumes DI| CoreKernel
+    UMBRELLA -->|orchestrates bootstrap| CoreKernel
+```
+
+### Explicit Dependencies (Direct)
+- `pydantic>=2.13.4`: Schema validation and config parsing.
+- `rodi>=2.1.0`: Fast, lightweight dependency injection container.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **Provides Ports**: Defines `UnitOfWorkPort` and `Repository` implemented by `hexastack-db`.
+- **Provides Telemetry Contract**: Defines `LoggerPort` implemented by `hexastack-logging`.
+- **Provides Bootstrap Framework**: All siblings expose extension entry points implementing `BootstrapperPort`.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone installation
+pip install hexastack-core
+
+# Via umbrella package
+pip install hexastack
+```
+
+---
+
+## 5. Configuration Reference
+
+Configuration schemas are registered under `[hexastack]`:
+
+```toml
+[hexastack]
+app_name = "my-application"
+environment = "production" # "development", "staging", "production", "test"
+debug = false
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_core.ports.bootstrap import BootstrapperPort, BootstrapContext
+from hexastack_core.domain.result import Ok, Err, Result
+
+
+# 1. Implement a custom extension
+class ServiceBootstrapper(BootstrapperPort):
+    name = "custom_service"
+    order = 10
+
+    def configure(self, context: BootstrapContext) -> None:
+        context.container.add_instance("Service Configured", declared_class=str)
+
+
+# 2. Run deterministic bootstrap
+result = bootstrap(bootstrappers=[ServiceBootstrapper()], auto_discover=False)
+value = result.container.get(str)
+print(value)  # "Service Configured"
+```

hexastack_core-0.0.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "hexastack-core"
+version = "0.0.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.13.4",
+    "rodi>=2.1.0",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+testing = [
+    "faker>=33.0.0",
+    "hypothesis>=6.100.0",
+    "inline-snapshot>=0.35.4",
+    "pytest-archon>=0.0.7",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.importlinter]
+root_packages = ["hexastack_core"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_core"]
+layers = [
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_core.domain"]
+forbidden_modules = [
+    "hexastack_core.ports",
+    "hexastack_core.adapters",
+    "hexastack_core.infra",
+    "hexastack_core.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for ports"
+type = "forbidden"
+source_modules = ["hexastack_core.ports"]
+forbidden_modules = [
+    "hexastack_core.adapters",
+    "hexastack_core.infra",
+    "hexastack_core.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for adapters"
+type = "forbidden"
+source_modules = ["hexastack_core.adapters"]
+forbidden_modules = ["hexastack_core.testing"]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for infra"
+type = "forbidden"
+source_modules = ["hexastack_core.infra"]
+forbidden_modules = ["hexastack_core.testing"]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for utils"
+type = "forbidden"
+source_modules = ["hexastack_core.utils"]
+forbidden_modules = [
+    "hexastack_core.domain",
+    "hexastack_core.ports",
+    "hexastack_core.adapters",
+    "hexastack_core.infra",
+    "hexastack_core.testing",
+]

hexastack_core-0.0.0/pyproject.toml.orig

@@ -0,0 +1,87 @@
+[project]
+name = "hexastack-core"
+version = "0.0.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.13.4",
+    "rodi>=2.1.0",
+]
+
+[project.optional-dependencies]
+testing = [
+    "faker>=33.0.0",
+    "hypothesis>=6.100.0",
+    "inline-snapshot>=0.35.4",
+    "pytest-archon>=0.0.7",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.importlinter]
+root_packages = ["hexastack_core"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_core"]
+layers = [
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_core.domain"]
+forbidden_modules = [
+    "hexastack_core.ports",
+    "hexastack_core.adapters",
+    "hexastack_core.infra",
+    "hexastack_core.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for ports"
+type = "forbidden"
+source_modules = ["hexastack_core.ports"]
+forbidden_modules = [
+    "hexastack_core.adapters",
+    "hexastack_core.infra",
+    "hexastack_core.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for adapters"
+type = "forbidden"
+source_modules = ["hexastack_core.adapters"]
+forbidden_modules = [
+    "hexastack_core.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for infra"
+type = "forbidden"
+source_modules = ["hexastack_core.infra"]
+forbidden_modules = [
+    "hexastack_core.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for utils"
+type = "forbidden"
+source_modules = ["hexastack_core.utils"]
+forbidden_modules = [
+    "hexastack_core.domain",
+    "hexastack_core.ports",
+    "hexastack_core.adapters",
+    "hexastack_core.infra",
+    "hexastack_core.testing",
+]

hexastack_core-0.0.0/src/hexastack_core/__init__.py

@@ -0,0 +1,10 @@
+from hexastack_core import adapters, domain, infra, ports, testing, utils
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+    "ports",
+    "testing",
+    "utils",
+]

hexastack_core-0.0.0/src/hexastack_core/adapters/__init__.py

@@ -0,0 +1,43 @@
+from hexastack_core.adapters.ai import (
+    InMemoryLlmProvider,
+    InMemoryVectorStore,
+    LlmCallRecord,
+)
+from hexastack_core.adapters.cache import (
+    AsyncInMemoryCache,
+    InMemoryCache,
+)
+from hexastack_core.adapters.clock import (
+    FrozenClock,
+    InMemoryClock,
+)
+from hexastack_core.adapters.logging import (
+    InMemoryLogger,
+    LogEntry,
+    StandardLogger,
+)
+from hexastack_core.adapters.repository import (
+    AsyncInMemoryRepository,
+    InMemoryRepository,
+)
+from hexastack_core.adapters.unit_of_work import (
+    AsyncInMemoryUnitOfWork,
+    InMemoryUnitOfWork,
+)
+
+__all__ = [
+    "AsyncInMemoryCache",
+    "AsyncInMemoryRepository",
+    "AsyncInMemoryUnitOfWork",
+    "FrozenClock",
+    "InMemoryCache",
+    "InMemoryClock",
+    "InMemoryLlmProvider",
+    "InMemoryLogger",
+    "InMemoryRepository",
+    "InMemoryUnitOfWork",
+    "InMemoryVectorStore",
+    "LlmCallRecord",
+    "LogEntry",
+    "StandardLogger",
+]

hexastack_core-0.0.0/src/hexastack_core/adapters/ai/__init__.py

@@ -0,0 +1,11 @@
+from hexastack_core.adapters.ai.in_memory import (
+    InMemoryLlmProvider,
+    InMemoryVectorStore,
+    LlmCallRecord,
+)
+
+__all__ = [
+    "InMemoryLlmProvider",
+    "InMemoryVectorStore",
+    "LlmCallRecord",
+]