quadkit 0.0.41__tar.gz → 0.0.42__tar.gz

quadkit-0.0.42/.gitignore

@@ -0,0 +1,214 @@
+*
+!tests/
+!tests/**
+!README.md
+!AGENTS.md
+!DEVELOPMENT.md
+!QUICKGUIDE.md
+!MILESTONE*.md
+!TESTS*.md
+!CHANGELOG.md
+!AUDIT*.md
+!REF*.md
+!AUDIT*.json
+!LICENSE
+!LICENSE-MIT.txt
+!NOTICE
+!TRADEMARK.md
+!conftest.py
+!CONTRIBUTING.md
+!CODE_OF_CONDUCT.md
+!SECURITY.md
+!GOVERNANCE.md
+!pyproject.toml
+!uv.lock
+!docker-compose.yml
+!.env.example
+!.env.full.example
+!.importlinter
+!.superpowers/
+!.superpowers/**
+!.gitattributes
+!.editorconfig
+!Makefile
+!docker-compose.test.yml
+!quadkit.yaml.example
+!.github/
+!.github/workflows/
+!.github/workflows/**
+!.github/dependabot.yml
+!.devcontainer/
+!.devcontainer/**
+!tools/
+!tools/**
+!*example.yaml
+
+# Quadkit Packages
+!quadkit*/
+!quadkit*/pyproject.toml
+!quadkit*/CHANGELOG.md
+!quadkit*/README.md
+!quadkit*/alembic.ini
+!quadkit*/mypy.ini
+!quadkit*/*.yaml.example
+!quadkit*/src/
+!quadkit*/src/**
+!quadkit*/docs/
+!quadkit*/docs/**
+!quadkit*/tests/
+!quadkit*/tests/**
+
+# Keep quadkit docs
+!/docs/
+!docs/**
+
+# Session / cutover plans at the repo root
+!plans/
+!plans/**
+
+# Keep example files for README examples
+!/examples/
+!/examples/**
+
+# Re-ignore these AFTER negations (last match wins)
+*.tape
+examples/*/runs/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+test.db
+!quadkit*/tests/fixtures/test.db
+*.log
+*.tmp
+
+# Company-specific files (keep private, do not commit)
+.company/
+COMPANY_*.md
+company-config/
+internal-docs/
+# Editor swap files
+*.swp
+
+!core/
+!packages/
+!core/quadkit*/
+!packages/quadkit*/
+!core/quadkit*/pyproject.toml
+!packages/quadkit*/pyproject.toml
+!core/quadkit*/CHANGELOG.md
+!packages/quadkit*/CHANGELOG.md
+!core/quadkit*/README.md
+!packages/quadkit*/README.md
+!core/quadkit*/alembic.ini
+!packages/quadkit*/alembic.ini
+!core/quadkit*/mypy.ini
+!packages/quadkit*/mypy.ini
+!core/quadkit*/*.yaml.example
+!packages/quadkit*/*.yaml.example
+!core/quadkit*/src/
+!core/quadkit*/src/**
+!packages/quadkit*/src/
+!packages/quadkit*/src/**
+!core/quadkit*/tests/
+!core/quadkit*/tests/**
+!packages/quadkit*/tests/
+!packages/quadkit*/tests/**
+!core/quadkit*/docs/
+!core/quadkit*/docs/**
+!packages/quadkit*/docs/
+!packages/quadkit*/docs/**
+
+# dev/
+!dev/
+!dev/**
+
+# Admin dev playground (committed dev asset; local SQLite files stay ignored)
+!packages/quadkit-admin/playground/
+!packages/quadkit-admin/playground/serve.py
+
+# gatewai apps
+!apps/
+!apps/**
+!apps/gatewai/
+!apps/gatewai/**
+apps/**/node_modules/
+apps/**/dist/
+apps/**/__pycache__/
+apps/**/*.pyc
+apps/**/*.db
+apps/**/*.db-wal
+apps/**/*.db-shm
+apps/**/.env
+apps/**/.env.*
+!apps/**/.env.example
+!apps/**/.env.full.example
+
+# Piccolina — nested app tracked in this monorepo (standalone .git removed).
+# Keep marketing packages and deployment secrets out of the tree.
+apps/piccolina/piccolina-marketing/
+apps/piccolina/piccolina-marketing-plans/
+apps/piccolina/secrets/
+apps/piccolina/**/secrets/
+apps/piccolina/**/*.pem
+apps/piccolina/**/*.key
+apps/piccolina/**/.venv/
+apps/piccolina/**/node_modules/
+apps/piccolina/**/__pycache__/
+apps/piccolina/**/*.pyc
+apps/piccolina/**/*.pbf
+apps/piccolina/**/.open-next/
+apps/piccolina/**/storage/
+apps/piccolina/**/.deploy-host
+
+# Re-exclude private content under the tiered paths.
+# MUST come after the !...docs/** negations above — last match wins.
+core/quadkit*/docs/plans/
+packages/quadkit*/docs/plans/
+core/quadkit*/docs/**/
+packages/quadkit*/docs/**/
+
+# Re-exclude tooling artifacts under the tiered paths
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+test.db
+*.tmp
+*.log
+!core/quadkit*/tests/fixtures/test.db
+!packages/quadkit*/tests/fixtures/test.db
+
+# Allow the generated example gifs to be tracked (README hero images).
+!core/quadkit*/docs/gifs/
+!core/quadkit*/docs/gifs/**
+!packages/*/quadkit*/docs/gifs/
+!packages/*/quadkit*/docs/gifs/**
+examples/*/screenshot.png
+!banner*
+apps/quadkit-playground/**/node_modules/
+apps/quadkit-playground/**/dist/
+apps/quadkit-playground/**/__pycache__/
+apps/quadkit-playground/**/*.pyc
+apps/quadkit-playground/**/*.db
+apps/quadkit-playground/**/*.db-wal
+apps/quadkit-playground/**/*.db-shm
+apps/quadkit-playground/projects/
+apps/quadkit-playground/quadkit/
+docs/superpowers/

quadkit-0.0.42/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+This project follows:
+- [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+- [Semantic Versioning](https://semver.org/)
+
+---
+
+## [Unreleased]
+
+### Added
+- 
+
+### Changed
+- 
+
+### Fixed
+- 
+
+### Removed
+- 
+
+### Deprecated
+- 
+
+---
+
+## [1.2.0] - 2026-04-25
+
+### Added
+- New `CacheProvider` for Redis backend
+- Support for async streaming responses
+
+### Changed
+- Improved container resolution performance (~20%)
+- Updated logging format to include request IDs
+
+### Fixed
+- Fixed circular dependency detection edge case
+- Fixed memory leak in scoped container
+
+---
+
+## [1.1.0] - 2026-03-10
+
+### Added
+- Introduced `Result[T, E]` helpers (`map`, `and_then`)
+- Added health check support in providers
+
+### Changed
+- Refactored provider lifecycle ordering
+
+---
+
+## [1.0.0] - 2026-01-01
+
+### Added
+- Initial release
+- Dependency Injection container
+- Provider system
+- Module system
+
+---
+
+## Types of Changes
+
+- **Added** → new features  
+- **Changed** → changes in existing functionality  
+- **Fixed** → bug fixes  
+- **Removed** → removed features  
+- **Deprecated** → soon-to-be removed features  

{quadkit-0.0.41 → quadkit-0.0.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit
-Version: 0.0.41
+Version: 0.0.42
 Summary: Async-first DI/IoC framework for Python — core package
 Project-URL: Homepage, https://dbtinoy-.github.io/quadkit/
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
@@ -27,6 +27,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: orjson<4,>=3.0.0
 Requires-Dist: pydantic<3,>=2.10.0
+Requires-Dist: pyyaml<7,>=6.0.0
 Requires-Dist: quadkit-contracts>=0.0.2
 Requires-Dist: structlog<27,>=25.1.0
 Provides-Extra: codegen
@@ -250,10 +251,10 @@ report vulnerabilities privately per
 
 ## Stability
 
-Version `0.0.3` in the `0.x` series, released in lockstep with the
+Version `0.0.42` in the `0.x` series, released in lockstep with the
 other four distributions; APIs may change between minor versions until
 1.0 — pin an exact version
-(`quadkit==0.0.3`) or a tight range (`>=0.0.3,<0.1.0`). Full policy:
+(`quadkit==0.0.42`) or a tight range (`>=0.0.42,<0.1.0`). Full policy:
 [stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
 
 ## Links

{quadkit-0.0.41 → quadkit-0.0.42}/README.md

@@ -199,10 +199,10 @@ report vulnerabilities privately per
 
 ## Stability
 
-Version `0.0.3` in the `0.x` series, released in lockstep with the
+Version `0.0.42` in the `0.x` series, released in lockstep with the
 other four distributions; APIs may change between minor versions until
 1.0 — pin an exact version
-(`quadkit==0.0.3`) or a tight range (`>=0.0.3,<0.1.0`). Full policy:
+(`quadkit==0.0.42`) or a tight range (`>=0.0.42,<0.1.0`). Full policy:
 [stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
 
 ## Links

quadkit-0.0.42/docs/ARCHITECTURE.md

@@ -0,0 +1,252 @@
+---
+title: "quadkit Architecture"
+description: "Architecture overview of the Quadkit core package and its role in the system."
+---
+# Architecture
+
+---
+
+## Role in the System
+
+`quadkit` is the **core package** — the foundation that every extension package builds on. It provides the DI container, application lifecycle, provider pattern, configuration system, and the `Result` type.
+
+```
+Extension packages (quadkit-web, quadkit-sql, …)
+         ↑ depends on
+    ┌────┴────┐
+    │ quadkit │  ← DI container, Application, Provider, Module, Config, Result
+    └────┬────┘
+         ↑ depends on
+    ┌────┴────────┐
+    │ quadkit-contracts │  ← Protocols, types, exceptions (zero deps)
+    └─────────────────┘
+```
+
+---
+
+## Key Components
+
+```
+┌────────────────────────────────────────────────────┐
+│                    Application                      │
+│  ┌──────────┐  ┌────────────────┐  ┌────────────┐ │
+│  │Container │  │ProviderOrch.   │  │ Invoker    │ │
+│  │          │  │                │  │            │ │
+│  │ register │  │ sort by        │  │ DI function│ │
+│  │ resolve  │  │ priority+deps  │  │ calling    │ │
+│  │ validate │  │ boot/shutdown  │  │            │ │
+│  └────┬─────┘  └────────────────┘  └────────────┘ │
+│       │                                              │
+│  ┌────┴──────────────────────────────────────┐       │
+│  │            MiddlewarePipeline              │       │
+│  └───────────────────────────────────────────┘       │
+│                                                      │
+│  ┌──────────────────────────────────────────┐        │
+│  │          QuadkitConfig                  │        │
+│  │  app_name, debug, env, logging, modules  │        │
+│  └──────────────────────────────────────────┘        │
+└──────────────────────────────────────────────────────┘
+```
+
+### Container (`quadkit.di.container`)
+
+The IoC container is a facade coordinating:
+
+| Sub-component | Responsibility |
+|---|---|
+| `ServiceRegistry` | Stores bindings (service type → descriptor) |
+| `ServiceResolver` | Resolves typed dependencies recursively |
+| `DependencyInjector` | Creates instances with constructor injection |
+| `ContainerRegistrarImpl` | Write operations (singleton, transient, scoped) |
+| `ContainerResolverImpl` | Read operations (resolve, resolve_optional, resolve_all) |
+| `ContainerValidator` | Pre-flight validation (missing deps, circular refs, scope violations) |
+| `FunctionInvoker` | Auto-injects arguments when calling functions |
+| `TypeHintResolverImpl` | Resolves type hints with caching |
+
+**Service scopes:**
+
+| Scope | Lifetime | Registration Method |
+|-------|----------|-------------------|
+| `SINGLETON` | One instance for the container lifetime | `container.singleton(T, instance)` or `container.singleton(T, factory=factory)` |
+| `TRANSIENT` | New instance per resolution | `container.transient(T, factory)` |
+| `SCOPED` | One instance per scope context | `container.scoped(T, factory)` |
+
+**Lifecycle:**
+
+```
+Register ──► Freeze ──► Resolve ──► Dispose
+                  │
+              validate()
+```
+
+### Provider (`quadkit.di.provider`)
+
+The `Provider` base class defines the lifecycle contract:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | `str` | `""` (auto-derived from class name) | Unique identifier |
+| `priority` | `ProviderPriority` | `NORMAL` | Boot ordering |
+| `dependencies` | `tuple[str, ...]` | `()` | Named provider dependencies |
+| `required` | `bool` | `True` | Fatal if boot fails |
+| `config_key` | `str \| None` | `None` | Config section to inject |
+| `config_model` | `type \| None` | `None` | Config model class |
+
+**Extension point:** Subclass `Provider` and override lifecycle hooks. Providers are discovered via `app.discover_providers()` or added explicitly via `app.add_provider()`.
+
+### Module (`quadkit.di.module`)
+
+Modules provide encapsulation over groups of providers:
+
+| Component | Purpose |
+|---|---|
+| `@module` decorator | Attaches `ModuleMetadata` to a class |
+| `Module` base class | `ClassVar` defaults, `configure()`, `scope()`, `stub()` factory methods |
+| `DynamicModule` | Runtime-created module descriptor |
+| `ModuleCompiler` | Compiles the module graph into an ordered provider list |
+| `ModuleMetadata` | Stores providers, imports, exports, scan paths |
+
+**Visibility rules:**
+- Services in a module are **private** by default
+- Only types listed in `exports` are resolvable by importing modules
+- `@global_module` exports are visible to all modules without `imports`
+
+### Result (`quadkit.result`)
+
+Re-exports from `quadkit.contracts.core.result`. The `Result[T, E]` type is a discriminated union:
+
+```python
+class Result(Generic[T, E]):
+    def is_ok(self) -> bool: ...
+    def is_err(self) -> bool: ...
+    def unwrap(self) -> T: ...         # raises UnwrapError on Err
+    def unwrap_err(self) -> E: ...
+    def unwrap_or(self, default: T) -> T: ...
+    def map(self, fn) -> Result[U, E]: ...      # async
+    def map_sync(self, fn) -> Result[U, E]: ... # sync
+    def and_then(self, fn) -> Result[U, E]: ... # async
+    def and_then_sync(self, fn) -> Result[U, E]: ...
+    def match(self, *, ok, err) -> U: ...
+    def inspect(self, fn) -> Self: ...
+    def inspect_err(self, fn) -> Self: ...
+    def flatten(self) -> Result[T, E]: ...
+    @staticmethod
+    def from_exception(exc) -> Result[Never, Exception]: ...
+```
+
+### Config (`quadkit.config`)
+
+Configuration loading uses a layered source model:
+
+```
+Sources (ordered by priority, later wins):
+  1. Class defaults (QuadkitConfig fields)
+  2. YAML file (application.yaml)
+  3. Additional YAML/files via ConfigLoader
+  4. Environment variables (QK_<KEY>)
+  5. .env file
+  6. CLI options
+         │
+         ▼
+   QuadkitConfig (Pydantic/BaseConfig model)
+         │
+         ▼
+   Container singleton (QuadkitConfig + ConfigProtocol)
+```
+
+`ConfigProvider` (priority `CRITICAL`) loads config during `register()` — this is the one **intentional exception** to the rule that providers shouldn't do I/O in `register()`.
+
+---
+
+## Providers
+
+**Core providers** (included with `quadkit`):
+
+| Provider | Name | Priority | Registers |
+|----------|------|----------|-----------|
+| `ConfigProvider` | `"config"` | `CRITICAL` | `QuadkitConfig`, `ConfigProtocol` |
+| `CoreProvider` | `"core"` | `INFRASTRUCTURE` | Core infrastructure services |
+| `CoreInfrastructureProvider` | `"common"` | `INFRASTRUCTURE` | Ambient primitives (clock, identity, hashing) |
+| `LoggingProvider` | `"logging"` | `INFRASTRUCTURE` | `LoggerProtocol`, structlog config |
+| `IdentityProvider` | `"identity"` | `INFRASTRUCTURE` | ID generation |
+| `MiddlewareProvider` | `"middleware"` | `INFRASTRUCTURE` | Middleware chain |
+| `DiProvider` | `"di"` | `INFRASTRUCTURE` | DI system extensions |
+
+---
+
+## Contracts Used
+
+`quadkit` depends on protocols from `quadkit-contracts`:
+
+| Protocol | Import | Used By |
+|----------|--------|---------|
+| `ContainerRegistrarProtocol` | `quadkit.contracts.core.di` | `Provider.register()` parameter |
+| `ContainerResolverProtocol` | `quadkit.contracts.core.di` | Resolution API |
+| `BootContainerProtocol` | `quadkit.contracts.core.di` | `Provider.boot()` parameter |
+| `ConfigProtocol` | `quadkit.contracts.core.config` | `QuadkitConfig` implements this |
+| `ProviderPriority` | `quadkit.contracts.core.provider` | `Provider.priority` field |
+| `HealthCheckResult` | `quadkit.contracts.core.health` | `Provider.health_check()` return |
+| `ClockProtocol` | `quadkit.contracts.core.clock` | Ambient clock capability |
+| `IdGeneratorProtocol` | `quadkit.contracts.core.identity` | Identity generation |
+| `LoggerProtocol` | (quadkit.logging) | Structured logging |
+
+---
+
+## Lifecycle
+
+### Application Boot Sequence
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Comp as ModuleCompiler
+    participant PC as ProviderOrchestrator
+    participant C as Container
+    participant P as Provider
+
+    App->>C: create
+    App->>PC: add providers
+    App->>App: start()
+    App->>Comp: compile() if modules
+    App->>PC: register_all()
+    loop for each provider
+        PC->>P: register(C)
+        P->>C: singleton(...) / transient(...) / scoped(...)
+    end
+    PC->>C: freeze(validate=True)
+    PC->>C: validate() if enabled
+    loop boot levels (topological order)
+        PC->>P: boot(C)
+        P->>C: resolve(...)
+    end
+    App-->>App: RUNNING
+    Note over App: Application running
+    App->>App: stop()
+    loop reverse priority
+        PC->>P: shutdown()
+    end
+    App->>C: dispose()
+    App-->>App: STOPPED
+```
+
+### Error Handling During Boot
+
+If any provider's `boot()` raises, all previously booted providers are shut down in reverse order, and the application transitions to `STOPPED`. The `on_error(error, phase)` hook is called for each failed provider.
+
+### Middleware Pipeline
+
+The `MiddlewarePipeline` wraps function calls via the `Invoker`. Middleware is ordered and applied around every `invoker.invoke()` call.
+
+---
+
+## Extension Points
+
+| Extension | How | Example |
+|-----------|-----|---------|
+| Custom Provider | Subclass `Provider` | Create a provider for your domain services |
+| Custom Module | `@module()` decorator | Encapsulate a vertical slice |
+| Config Source | Implement `ConfigSourceProtocol` | Load from Vault, SSM, custom backend |
+| Resolution Strategy | Implement `ResolutionStrategy` | Custom annotation-based injection |
+| Interceptor | Register on `InterceptorRegistry` | AOP around service resolution |
+| Service Registration | `container.singleton()` | Bind any protocol to an implementation |
+| Middleware | Implement `MiddlewareProtocol` | Logging, tracing, auth around function calls |

quadkit-0.0.42/docs/CONFIGURATION.md

@@ -0,0 +1,126 @@
+---
+title: "quadkit Configuration"
+description: "How Quadkit loads configuration from multiple sources with an overlay model."
+---
+# Configuration
+
+---
+
+## Overview
+
+Quadkit loads configuration from multiple sources with an overlay (later-wins) model. The `ConfigProvider` (priority `CRITICAL`) handles loading during the `register()` phase.
+
+**Config sources** (in priority order, later wins):
+
+1. In-code field defaults
+2. `application.yaml` in the working directory
+3. Custom file sources (via `ConfigLoader`)
+4. Environment variables (`QK_<KEY>`)
+5. `.env` file
+6. CLI arguments (via `CliConfigSource`)
+
+---
+
+## Config Section Key
+
+Quadkit's config lives at the **root** of the config hierarchy (there is no outer section key). Extension packages use sub-keys under the root (e.g. `cache:`, `web:`, `db:`), which are accessed via `config.get_section("cache", CacheConfig)`.
+
+---
+
+## Options
+
+### `QuadkitConfig` — Root Configuration
+
+| Key | Type | Default | Description | Env Var |
+|-----|------|---------|-------------|---------|
+| `app_name` | `str` | `"quadkit-app"` | Application name used in logging and telemetry | `QK_APP__APP_NAME` |
+| `debug` | `bool` | `False` | Enable debug mode (blocked in production) | `QK_DEBUG` |
+| `env` | `Environment` | `"development"` | Deployment environment | `QK_ENV` |
+| `logging.level` | `str` | `"INFO"` | Default log level | `QK_LOGGING__LEVEL` |
+| `logging.json_format` | `bool` | `false` | Render logs as JSON | `QK_LOGGING__JSON_FORMAT` |
+| `enabled_modules` | `list[str]` | `[]` | Enabled module names | `QK_MODULEDISCOVERY__ENABLED_MODULES` |
+| `discovery.auto_discover` | `bool` | `False` | Auto-discover modules | `QK_MODULEDISCOVERY__AUTO_DISCOVER` |
+| `discovery.entry_point_group` | `str` | `"quadkit.modules"` | Entry point group for module discovery | `QK_MODULEDISCOVERY__ENTRY_POINT_GROUP` |
+| `health.check_timeout` | `float` | `5.0` | Health check timeout (seconds) | `QK_HEALTH__CHECK_TIMEOUT` |
+| `health.include_details` | `bool` | `true` | Include detailed health output | `QK_HEALTH__INCLUDE_DETAILS` |
+
+### Environment Values
+
+| Environment | String Value |
+|-------------|-------------|
+| `DEVELOPMENT` | `"development"` |
+| `STAGING` | `"staging"` |
+| `PRODUCTION` | `"production"` |
+| `TEST` | `"test"` |
+
+---
+
+## Examples
+
+### Minimal YAML (`application.yaml`)
+
+```yaml
+app_name: my-api
+debug: false
+env: development
+logging:
+  level: INFO
+  json_format: true
+```
+
+### Production YAML
+
+```yaml
+app_name: my-api
+debug: false
+env: production
+logging:
+  level: WARN
+  json_format: true
+```
+
+### Environment Variables
+
+```bash
+export QK_APP__APP_NAME="my-api"
+export QK_DEBUG="false"
+export QK_ENV="production"
+export QK_LOGGING__LEVEL="WARN"
+export QK_LOGGING__JSON_FORMAT="true"
+```
+
+---
+
+## Programmatic Usage
+
+```python
+from quadkit import QuadkitConfig
+from quadkit.config.di.provider import ConfigProvider
+
+# Load from YAML + env
+config = QuadkitConfig.from_yaml("application.yaml")
+print(config.app_name)   # "my-api"
+print(config.is_production)  # True/False
+
+# Provider section access
+cache_cfg = config.get_section("cache", CacheConfig)
+
+# Validation
+issues = config.validate_for_environment()
+for issue in issues:
+    print(f"{issue.field}: {issue.message}")
+
+# ConfigProvider for DI
+provider = ConfigProvider()
+```
+
+---
+
+## Best Practices
+
+- **Never hardcode secrets** in YAML — use environment variables or a secret store
+- **Use `QK_` prefix** for all env var overrides
+- **Section naming** uses double-underscore: `QK_<SECTION>__<KEY>`
+- **Validate with `config.validate_for_environment()`** in production to catch `debug=True`
+- **Register secrets** via `app.register_secrets()` for boot-time validation
+- **Pin config model types** by registering them in `ConfigRegistry` for extension packages