quadkit 0.0.4__tar.gz → 0.0.41__tar.gz

quadkit-0.0.41/.gitignore

@@ -0,0 +1,24 @@
+# Generated public-repository ignore rules.
+# Private monorepo paths are intentionally not referenced here.
+
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+*.log
+.DS_Store
+.idea/
+.vscode/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit
-Version: 0.0.4
+Version: 0.0.41
 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

{quadkit-0.0.4 → quadkit-0.0.41}/example.yaml

@@ -5,7 +5,7 @@
 # Top-level env var prefix: QK_  (nested delimiter: __)
 #
 # Core fields are declared at the top level of this file.
-# Extension packages (quadkit-cache, quadkit-sql, etc.) each add their own
+# Extension packages (the optional provider, the optional provider, etc.) each add their own
 # top-level section (e.g. cache:, sql:, ai:) read by their own Config class.
 
 # -- Application Identity --------------------------------------------------
@@ -226,7 +226,7 @@ security:
     pbkdf2_iterations: 600000
 
 # -- Observability ---------------------------------------------------------
-# NEW -- Core observability hooks. Full OTLP/Prometheus config is in quadkit-monitor.
+# NEW -- Core observability hooks. Full OTLP/Prometheus config is in the optional provider.
 
 observability:
   # Master switch. When false, no-op implementations are used unconditionally.

{quadkit-0.0.4 → quadkit-0.0.41}/pyproject.toml

@@ -10,10 +10,7 @@
 #   - Structured logging foundation
 #
 # It does NOT contain:
-#   - Database code          → quadkit-sql
-#   - Auth/JWT/crypto        → quadkit-auth
 #   - HTTP/ASGI/routing      → quadkit-web
-#   - Message queue / email  → quadkit-queue / quadkit-mailer / quadkit-notification
 #   - Any domain-specific feature
 #
 # Core should be lightweight. `pip install quadkit` should take seconds,
@@ -30,7 +27,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit"
-version = "0.0.4"
+version = "0.0.41"
 description = "Async-first DI/IoC framework for Python — core package"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -130,7 +127,7 @@ web = [
 # events, tasks, monitor, graphql) were removed. Those packages are not
 # published, so the extras resolved against name-reservation placeholders
 # that contain no code: `pip install quadkit[cache]` succeeded and then
-# `import quadkit.cache` raised ModuleNotFoundError. Install extension
+# `import the optional provider module` raised ModuleNotFoundError. Install extension
 # packages directly once they are published.
 
 # =============================================================================

{quadkit-0.0.4 → quadkit-0.0.41}/src/quadkit/app/module.py

@@ -15,7 +15,7 @@ Kernel providers (boot order governed by provider ``priority`` and ``dependencie
 For a batteries-included bundle that also provides serialization and
 concurrency, use :class:`~quadkit.app.standard.StandardModule` instead.
 
-Extension packages (``quadkit-cache``, ``quadkit-auth``, ``quadkit-web``,
+Extension packages (``the optional provider``, ``the optional provider``, ``quadkit-web``,
 etc.) register their own providers via ``app.add_provider()`` or
 ``app.add_module()``.  ``CoreModule`` intentionally imports **only** from
 ``quadkit-contracts`` and the ``quadkit`` core package — zero cross-package

{quadkit-0.0.4 → quadkit-0.0.41}/src/quadkit/di/extensions/discovery.py

@@ -127,7 +127,7 @@ class ProviderScanner:
 def import_string(dotted_path: str) -> Any:
     """Import a dotted module path and return the attribute at the end.
 
-    E.g. 'quadkit.sql.DatabaseService' imports 'quadkit.sql' and returns
+    E.g. 'the optional provider module' imports 'the optional provider module' and returns
     the 'DatabaseService' attribute.
     """
     try:

{quadkit-0.0.4 → quadkit-0.0.41}/src/quadkit/domain/unit_of_work.py

@@ -8,7 +8,7 @@ This base is deliberately storage-agnostic -- it imports no database driver --
 so in-memory and SQL implementations can share it:
 
 - ``quadkit.testing.memory.uow.InMemoryUnitOfWork`` supplies a no-op flush.
-- ``quadkit-sql``'s ``SQLUnitOfWork`` flushes through the active session.
+- ``the optional provider``'s ``SQLUnitOfWork`` flushes through the active session.
 """
 
 from __future__ import annotations

{quadkit-0.0.4 → quadkit-0.0.41}/src/quadkit/logging/configurator.py

@@ -55,7 +55,7 @@ def configure_logging(
         service_name: Application name injected into log context.
         levels: Per-logger level overrides. Keys are logger name prefixes,
             values are level strings.  Example:
-            ``{"quadkit.di": "DEBUG", "quadkit.resilience": "WARNING"}``.
+            ``{"quadkit.di": "DEBUG", "the optional provider module": "WARNING"}``.
         sampling_enabled: Enable deterministic log sampling.
         sampling_default_rate: Default sample rate (1.0 = log everything,
             0.1 = log ~10%).

{quadkit-0.0.4 → quadkit-0.0.41}/src/quadkit/middleware/builtins/resilience.py

@@ -23,7 +23,7 @@ logger = get_logger(__name__)
 class RetryMiddleware:
     """Middleware that retries the downstream handler on transient failures.
 
-    Delegates to :func:`quadkit.resilience.retry` for backoff logic.
+    Delegates to :func:`the optional provider module` for backoff logic.
 
     Args:
         catch: Exception types considered retryable. Must be explicitly provided.

{quadkit-0.0.4 → quadkit-0.0.41}/src/quadkit/observability/core.py

@@ -1,7 +1,7 @@
 """Core no-op observability primitives for Quadkit Framework.
 
 These implementations satisfy the observability contracts without requiring
-``quadkit-monitor``. They are intentionally lightweight and safe to keep as
+``the optional provider``. They are intentionally lightweight and safe to keep as
 long-lived singletons in the container.
 """
 

{quadkit-0.0.4 → quadkit-0.0.41}/src/quadkit/primitives/pipeline.py

@@ -2,7 +2,7 @@
 
 These primitives live in the core ``quadkit`` package so that any extension
 package can build pipeline-compatible steps without depending on
-``quadkit-workflow``.
+``the optional provider``.
 """
 
 from __future__ import annotations

{quadkit-0.0.4 → quadkit-0.0.41}/src/quadkit/primitives/registry/introspection.py

@@ -83,7 +83,7 @@ def entry_point_catalog() -> dict[str, list[dict[str, str]]]:
     of entry-point metadata dicts.
 
     Returns:
-        ``{"quadkit.cache.backends": [{"name": "redis", "value": "..."}]}``
+        ``{"the optional provider module": [{"name": "redis", "value": "..."}]}``
     """
     catalog: dict[str, list[dict[str, str]]] = {}
 

quadkit-0.0.4/.gitignore

@@ -1,183 +0,0 @@
-*
-!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
-
-# 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*

quadkit-0.0.4/CHANGELOG.md

@@ -1,73 +0,0 @@
-# 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.4/docs/ARCHITECTURE.md

@@ -1,252 +0,0 @@
----
-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 |