confluid 0.1.0__tar.gz

confluid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gert Behiels
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

confluid-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: confluid
+Version: 0.1.0
+Summary: Modern, hierarchical configuration and dependency injection for Python.
+Author: Gert Behiels
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Gearlux/confluid
+Project-URL: Repository, https://github.com/Gearlux/confluid.git
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: loggair>=0.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: typing-extensions>=4.6.0
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0.0; extra == "pydantic"
+Provides-Extra: dev
+Requires-Dist: pydantic>=2.0.0; extra == "dev"
+Requires-Dist: black<25.0.0,>=24.0.0; extra == "dev"
+Requires-Dist: isort<6.0.0,>=5.13.0; extra == "dev"
+Requires-Dist: flake8<8.0.0,>=6.0.0; extra == "dev"
+Requires-Dist: flake8-junit-report>=2.1.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.0.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Requires-Dist: pytest<9.0.0,>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov<7.0.0,>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# Confluid
+
+**Confluid** is a modern, hierarchical configuration and dependency injection framework for Python, built for researchers and engineers who need modularity and 100% reproducibility in their experiment pipelines.
+
+## Key Features
+- **Works with plain Python classes:** Required constructor params and real work in `__init__` are fully supported for load/flow/dump — the lazy/zero-arg class-design convention is optional.
+- **Post-Construction Configuration:** Configure existing objects without requiring re-instantiation.
+- **Strict Gated Hierarchy:** Prevents deep-traversal into non-configurable third-party objects.
+- **Third-Party Registration:** Easily make third-party classes (like PyTorch Optimizers) — or plain builder **functions** — part of your configurable graph via `@configurable` / `register`.
+- **Smart Reference Resolution:** Uses `!ref:` syntax for cross-config references (shared instance), `!clone:` for a deep copy, and `${...}` for string interpolation of environment variables (`${HOME}`) AND config keys (`${train.dataset}`).
+- **Deferred Initialization:** A node is built eagerly (`!class:Model()`) or left as a deferred recipe (`!class:Model`); `!lazy:` keeps a node deferred until you `flow()` it with runtime-injected arguments (e.g. an optimizer needing `params=model.parameters()`).
+- **Full Hierarchy Dumping:** Export your runtime state to YAML/JSON and reconstruct it later.
+- **Schema Export & Validation:** Auto-generated pydantic schemas validate every `@configurable` constructor; docstring `Args:` blocks become machine-readable parameter help (`parse_param_docs`); `sanitize_schema` downgrades schemas to the subset strict LLM function-calling APIs accept.
+- **I/O Contract:** `@output` properties and `Mandatory[T]` inputs declare a Runnable's contract for GUIs and agents from one source.
+- **Flat-View Ordered Matching:** Bare keys broadcast tree-wide (an implicit `**.key`), addressed keys (`trainer.lr` / `trainer: {lr: …}`) are **exact** — no cascade to descendants — and glob wildcards opt back in (`trainer.*.lr` = direct children, `trainer.**.lr` = the node and all descendants). Matching scalars apply in YAML document order with **last-write-wins** semantics — no hidden priority tiers.
+- **Tag-Driven Scopes:** Conditional overlays (`!scope:debug`, `!scope:task=classification`, `!notscope:…`) activated per run.
+
+## Documentation
+
+Each topic has its own guide, and every guide has a runnable companion script in [`examples/`](https://github.com/Gearlux/confluid/tree/main/examples):
+
+| Guide | What it covers | Example |
+|---|---|---|
+| [Tags & Deferred Initialization](https://github.com/Gearlux/confluid/blob/main/docs/tags.md) | The six YAML tags, Fluid→Solid lifecycle, `!class:` eager-vs-deferred, `!lazy:` + `flow()`, `!ref:` vs `!clone:` | `tags_deferred.py` |
+| [Broadcasting & Ordered Matching](https://github.com/Gearlux/confluid/blob/main/docs/broadcasting.md) | Bare/addressed/glob scoping (`*` / `**`), document-order/last-write-wins matching, `NoBroadcast` / `broadcast=False` opt-outs, the frozen-deployment bake step | `broadcasting.py` |
+| [Configuration Reports](https://github.com/Gearlux/confluid/blob/main/docs/report.md) | `ConfigurationReport` — applied/failed/unused override keys; `configure()`'s return value, the `collect_report()` context manager for `load()`/`materialize()`/`flow()` | `report.py` |
+| [Interpolation & Config Files](https://github.com/Gearlux/confluid/blob/main/docs/interpolation.md) | `${ENV}` + `${config.key}` interpolation, capturing the `include:` tree | `interpolation_includes.py` |
+| [Config-File Search Paths](https://github.com/Gearlux/confluid/blob/main/docs/search-paths.md) | XDG-last resolution of relative paths and `include:` entries (CWD → `./config/` → XDG base dirs), `set_app_name` namespacing, `resolve_config_path` | `search_paths.py` |
+| [Class Design](https://github.com/Gearlux/confluid/blob/main/docs/class-design.md) | Lazy init & zero-arg construction — the four-rule convention for reconfigurable classes | `ml_pipeline.py` et al. |
+| [Eager Classes](https://github.com/Gearlux/confluid/blob/main/docs/eager-classes.md) | Plain constructors — required params, work in `__init__`, full dump round-trip via captured kwargs, the `capture=False` opt-out, the `eager=True` staleness warning | `eager_classes.py` |
+| [I/O Contract](https://github.com/Gearlux/confluid/blob/main/docs/io-contract.md) | `@output` properties, `Mandatory[T]` inputs, `output_specs` / `input_specs` | `io_contract.py` |
+| [Validation](https://github.com/Gearlux/confluid/blob/main/docs/validation.md) | The three strict/warn/off validation points, `Annotated[..., Field(...)]` constraints, `validate=False` | `validation.py` |
+| [Discovery](https://github.com/Gearlux/confluid/blob/main/docs/discovery.md) | `category` / `group` tags, behavioral marks (`random` / `constant`), docstring-derived help | `discovery.py` |
+| [Error Handling](https://github.com/Gearlux/confluid/blob/main/docs/errors.md) | The typed exception hierarchy (each also inherits the builtin it replaces) | `error_handling.py` |
+| [Scopes](https://github.com/Gearlux/confluid/blob/main/docs/scopes.md) | `!scope:` / `!notscope:` conditional overlays and their activation | `scopes.py` |
+| [Introspection](https://github.com/Gearlux/confluid/blob/main/docs/introspection.md) | `cast()` for type checkers, `resolve()` markers, `solidify=False`, dump/reconstruct | `introspection.py` |
+| [Threads & Async](https://github.com/Gearlux/confluid/blob/main/docs/concurrency.md) | ContextVar propagation, `active_context`, worker-thread recipes | `concurrency.py` |
+| [Performance](https://github.com/Gearlux/confluid/blob/main/docs/performance.md) | The engine-timing baseline: per-phase benchmark over a ~2,500-marker tree, `CONFLUID_BENCH_PROFILE=1` profiling mode | `performance.py` |
+
+### Real-world scenarios
+
+Two examples show the features working *together* at application scale (pure
+Python, no ML dependencies — run them as-is):
+
+- [`examples/ml_experiments/`](https://github.com/Gearlux/confluid/tree/main/examples/ml_experiments)
+  — an ML experiment suite in the Hydra style: one base config, model/optimizer
+  **config groups** selected per run via scopes (`scopes=["model=cnn"]`),
+  `include:` experiment overlays, `!class:`/`!ref:`/`!lazy:` object wiring,
+  bare-key broadcast of global knobs (`seed`, `device`), and a `dump()`
+  snapshot that reloads into the identical experiment. Its README maps each
+  Hydra concept to the confluid feature that plays its role.
+- [`examples/deep_injection.py`](https://github.com/Gearlux/confluid/blob/main/examples/deep_injection.py)
+  — the gin-config pitch: a four-level service tree (`Pipeline → Stage →
+  Worker → RetryPolicy`) where one bare YAML key configures the deepest leaf
+  with **zero parameter-threading code**, while addressed keys stay surgical,
+  globs scope a subtree, and `NoBroadcast` protects generic names.
+
+## Design Goals & Requirements
+
+### Configuration Engine
+- **Dotted-Key Resolution:** Allow flat overrides to target nested attributes (e.g. `model.layers: 10`).
+- **Tag-Based IR:** Use standard YAML tags (`!class:Name` deferred / `!class:Name()` eager, `!lazy:Name`, `!ref:path`, `!clone:path`) instead of proprietary symbols like `@`.
+- **Object-Based Internal Representation:** Use typed `Reference` and `ClassReference` objects for internal resolution.
+
+### Dependency Injection
+- **Automatic Hydration:** Support `@configurable` decorator for automatic class registration and instantiation.
+- **Fluid-Solid Protocol:** Implement a two-stage lifecycle where objects are defined ("Fluid") and then materialized ("Solid").
+- **Materialize API:** Provide an explicit `materialize()` function to instantiate objects from already-resolved configuration.
+
+### Robustness
+- **IR-Aware Merging:** `deep_merge` and `expand_dotted_keys` must traverse into `ClassReference` arguments.
+- **Circular Reference Detection:** Gracefully handle and report circular dependencies in the object graph.
+- **Type Coercion:** Integrate `parse_value` to ensure CLI strings (e.g. "100") are cast to correct types (int 100).
+
+## Quick Start
+
+### 1. Define Configurable Classes
+```python
+from typing import Optional
+
+from confluid import configurable
+
+@configurable
+class Model:
+    def __init__(self, layers: int = 3, dropout: float = 0.1):
+        self.layers = layers
+        self.dropout = dropout
+
+@configurable
+class Trainer:
+    # Lazy + zero-arg: every parameter is defaulted, so `Trainer()` works and the model is
+    # wired afterwards. See the "Class Design" guide.
+    def __init__(self, model: Optional[Model] = None, lr: float = 0.001):
+        self.model = model
+        self.lr = lr
+```
+
+### 2. Configure via YAML
+```yaml
+# experiment.yaml
+n_layers: 10
+
+Trainer:
+  lr: 0.0001
+  model: "!class:Model(layers=!ref:n_layers)"
+```
+
+### 3. Load and Apply
+```python
+from confluid import load_config, configure
+
+# Instantiate with defaults
+model = Model()
+trainer = Trainer(model=model)
+
+# Apply configuration — returns a ConfigurationReport (applied/failed/unused keys)
+config = load_config("experiment.yaml")
+report = configure(trainer, config=config)
+
+print(trainer.lr) # 0.0001
+print(trainer.model.layers) # 10
+print(report.summary()) # e.g. "2 applied, 0 failed, 0 unused"
+```
+
+`configure_from_file` collapses the load + apply into one call — handy when the config lives on disk:
+
+```python
+from confluid import configure_from_file
+
+# Equivalent to configure(trainer, config=load_config("experiment.yaml"))
+configure_from_file(trainer, path="experiment.yaml")
+```
+
+It reads the file via `load_config` (so `include:` / `import:` directives and `!class:` / `!ref:` markers are honoured) and then applies it exactly as `configure` does. A missing path raises `ConfigFileNotFoundError`. Matching follows the one rule described in the [Broadcasting guide](https://github.com/Gearlux/confluid/blob/main/docs/broadcasting.md): document order, last write wins.
+
+### 4. Dump and Reconstruct
+```python
+from confluid import dump, load
+
+# Export current state
+state_yaml = dump(trainer)
+
+# Recreate exact same hierarchy in a new process
+new_trainer = load(state_yaml)
+```
+
+## Installation
+```bash
+pip install confluid                     # from PyPI
+pip install "confluid[pydantic]"    # + pydantic-powered schema export & validation
+```
+
+Or straight from GitHub:
+
+```bash
+pip install git+https://github.com/Gearlux/confluid.git@main
+```
+
+## License
+MIT

confluid-0.1.0/README.md

@@ -0,0 +1,160 @@
+# Confluid
+
+**Confluid** is a modern, hierarchical configuration and dependency injection framework for Python, built for researchers and engineers who need modularity and 100% reproducibility in their experiment pipelines.
+
+## Key Features
+- **Works with plain Python classes:** Required constructor params and real work in `__init__` are fully supported for load/flow/dump — the lazy/zero-arg class-design convention is optional.
+- **Post-Construction Configuration:** Configure existing objects without requiring re-instantiation.
+- **Strict Gated Hierarchy:** Prevents deep-traversal into non-configurable third-party objects.
+- **Third-Party Registration:** Easily make third-party classes (like PyTorch Optimizers) — or plain builder **functions** — part of your configurable graph via `@configurable` / `register`.
+- **Smart Reference Resolution:** Uses `!ref:` syntax for cross-config references (shared instance), `!clone:` for a deep copy, and `${...}` for string interpolation of environment variables (`${HOME}`) AND config keys (`${train.dataset}`).
+- **Deferred Initialization:** A node is built eagerly (`!class:Model()`) or left as a deferred recipe (`!class:Model`); `!lazy:` keeps a node deferred until you `flow()` it with runtime-injected arguments (e.g. an optimizer needing `params=model.parameters()`).
+- **Full Hierarchy Dumping:** Export your runtime state to YAML/JSON and reconstruct it later.
+- **Schema Export & Validation:** Auto-generated pydantic schemas validate every `@configurable` constructor; docstring `Args:` blocks become machine-readable parameter help (`parse_param_docs`); `sanitize_schema` downgrades schemas to the subset strict LLM function-calling APIs accept.
+- **I/O Contract:** `@output` properties and `Mandatory[T]` inputs declare a Runnable's contract for GUIs and agents from one source.
+- **Flat-View Ordered Matching:** Bare keys broadcast tree-wide (an implicit `**.key`), addressed keys (`trainer.lr` / `trainer: {lr: …}`) are **exact** — no cascade to descendants — and glob wildcards opt back in (`trainer.*.lr` = direct children, `trainer.**.lr` = the node and all descendants). Matching scalars apply in YAML document order with **last-write-wins** semantics — no hidden priority tiers.
+- **Tag-Driven Scopes:** Conditional overlays (`!scope:debug`, `!scope:task=classification`, `!notscope:…`) activated per run.
+
+## Documentation
+
+Each topic has its own guide, and every guide has a runnable companion script in [`examples/`](https://github.com/Gearlux/confluid/tree/main/examples):
+
+| Guide | What it covers | Example |
+|---|---|---|
+| [Tags & Deferred Initialization](https://github.com/Gearlux/confluid/blob/main/docs/tags.md) | The six YAML tags, Fluid→Solid lifecycle, `!class:` eager-vs-deferred, `!lazy:` + `flow()`, `!ref:` vs `!clone:` | `tags_deferred.py` |
+| [Broadcasting & Ordered Matching](https://github.com/Gearlux/confluid/blob/main/docs/broadcasting.md) | Bare/addressed/glob scoping (`*` / `**`), document-order/last-write-wins matching, `NoBroadcast` / `broadcast=False` opt-outs, the frozen-deployment bake step | `broadcasting.py` |
+| [Configuration Reports](https://github.com/Gearlux/confluid/blob/main/docs/report.md) | `ConfigurationReport` — applied/failed/unused override keys; `configure()`'s return value, the `collect_report()` context manager for `load()`/`materialize()`/`flow()` | `report.py` |
+| [Interpolation & Config Files](https://github.com/Gearlux/confluid/blob/main/docs/interpolation.md) | `${ENV}` + `${config.key}` interpolation, capturing the `include:` tree | `interpolation_includes.py` |
+| [Config-File Search Paths](https://github.com/Gearlux/confluid/blob/main/docs/search-paths.md) | XDG-last resolution of relative paths and `include:` entries (CWD → `./config/` → XDG base dirs), `set_app_name` namespacing, `resolve_config_path` | `search_paths.py` |
+| [Class Design](https://github.com/Gearlux/confluid/blob/main/docs/class-design.md) | Lazy init & zero-arg construction — the four-rule convention for reconfigurable classes | `ml_pipeline.py` et al. |
+| [Eager Classes](https://github.com/Gearlux/confluid/blob/main/docs/eager-classes.md) | Plain constructors — required params, work in `__init__`, full dump round-trip via captured kwargs, the `capture=False` opt-out, the `eager=True` staleness warning | `eager_classes.py` |
+| [I/O Contract](https://github.com/Gearlux/confluid/blob/main/docs/io-contract.md) | `@output` properties, `Mandatory[T]` inputs, `output_specs` / `input_specs` | `io_contract.py` |
+| [Validation](https://github.com/Gearlux/confluid/blob/main/docs/validation.md) | The three strict/warn/off validation points, `Annotated[..., Field(...)]` constraints, `validate=False` | `validation.py` |
+| [Discovery](https://github.com/Gearlux/confluid/blob/main/docs/discovery.md) | `category` / `group` tags, behavioral marks (`random` / `constant`), docstring-derived help | `discovery.py` |
+| [Error Handling](https://github.com/Gearlux/confluid/blob/main/docs/errors.md) | The typed exception hierarchy (each also inherits the builtin it replaces) | `error_handling.py` |
+| [Scopes](https://github.com/Gearlux/confluid/blob/main/docs/scopes.md) | `!scope:` / `!notscope:` conditional overlays and their activation | `scopes.py` |
+| [Introspection](https://github.com/Gearlux/confluid/blob/main/docs/introspection.md) | `cast()` for type checkers, `resolve()` markers, `solidify=False`, dump/reconstruct | `introspection.py` |
+| [Threads & Async](https://github.com/Gearlux/confluid/blob/main/docs/concurrency.md) | ContextVar propagation, `active_context`, worker-thread recipes | `concurrency.py` |
+| [Performance](https://github.com/Gearlux/confluid/blob/main/docs/performance.md) | The engine-timing baseline: per-phase benchmark over a ~2,500-marker tree, `CONFLUID_BENCH_PROFILE=1` profiling mode | `performance.py` |
+
+### Real-world scenarios
+
+Two examples show the features working *together* at application scale (pure
+Python, no ML dependencies — run them as-is):
+
+- [`examples/ml_experiments/`](https://github.com/Gearlux/confluid/tree/main/examples/ml_experiments)
+  — an ML experiment suite in the Hydra style: one base config, model/optimizer
+  **config groups** selected per run via scopes (`scopes=["model=cnn"]`),
+  `include:` experiment overlays, `!class:`/`!ref:`/`!lazy:` object wiring,
+  bare-key broadcast of global knobs (`seed`, `device`), and a `dump()`
+  snapshot that reloads into the identical experiment. Its README maps each
+  Hydra concept to the confluid feature that plays its role.
+- [`examples/deep_injection.py`](https://github.com/Gearlux/confluid/blob/main/examples/deep_injection.py)
+  — the gin-config pitch: a four-level service tree (`Pipeline → Stage →
+  Worker → RetryPolicy`) where one bare YAML key configures the deepest leaf
+  with **zero parameter-threading code**, while addressed keys stay surgical,
+  globs scope a subtree, and `NoBroadcast` protects generic names.
+
+## Design Goals & Requirements
+
+### Configuration Engine
+- **Dotted-Key Resolution:** Allow flat overrides to target nested attributes (e.g. `model.layers: 10`).
+- **Tag-Based IR:** Use standard YAML tags (`!class:Name` deferred / `!class:Name()` eager, `!lazy:Name`, `!ref:path`, `!clone:path`) instead of proprietary symbols like `@`.
+- **Object-Based Internal Representation:** Use typed `Reference` and `ClassReference` objects for internal resolution.
+
+### Dependency Injection
+- **Automatic Hydration:** Support `@configurable` decorator for automatic class registration and instantiation.
+- **Fluid-Solid Protocol:** Implement a two-stage lifecycle where objects are defined ("Fluid") and then materialized ("Solid").
+- **Materialize API:** Provide an explicit `materialize()` function to instantiate objects from already-resolved configuration.
+
+### Robustness
+- **IR-Aware Merging:** `deep_merge` and `expand_dotted_keys` must traverse into `ClassReference` arguments.
+- **Circular Reference Detection:** Gracefully handle and report circular dependencies in the object graph.
+- **Type Coercion:** Integrate `parse_value` to ensure CLI strings (e.g. "100") are cast to correct types (int 100).
+
+## Quick Start
+
+### 1. Define Configurable Classes
+```python
+from typing import Optional
+
+from confluid import configurable
+
+@configurable
+class Model:
+    def __init__(self, layers: int = 3, dropout: float = 0.1):
+        self.layers = layers
+        self.dropout = dropout
+
+@configurable
+class Trainer:
+    # Lazy + zero-arg: every parameter is defaulted, so `Trainer()` works and the model is
+    # wired afterwards. See the "Class Design" guide.
+    def __init__(self, model: Optional[Model] = None, lr: float = 0.001):
+        self.model = model
+        self.lr = lr
+```
+
+### 2. Configure via YAML
+```yaml
+# experiment.yaml
+n_layers: 10
+
+Trainer:
+  lr: 0.0001
+  model: "!class:Model(layers=!ref:n_layers)"
+```
+
+### 3. Load and Apply
+```python
+from confluid import load_config, configure
+
+# Instantiate with defaults
+model = Model()
+trainer = Trainer(model=model)
+
+# Apply configuration — returns a ConfigurationReport (applied/failed/unused keys)
+config = load_config("experiment.yaml")
+report = configure(trainer, config=config)
+
+print(trainer.lr) # 0.0001
+print(trainer.model.layers) # 10
+print(report.summary()) # e.g. "2 applied, 0 failed, 0 unused"
+```
+
+`configure_from_file` collapses the load + apply into one call — handy when the config lives on disk:
+
+```python
+from confluid import configure_from_file
+
+# Equivalent to configure(trainer, config=load_config("experiment.yaml"))
+configure_from_file(trainer, path="experiment.yaml")
+```
+
+It reads the file via `load_config` (so `include:` / `import:` directives and `!class:` / `!ref:` markers are honoured) and then applies it exactly as `configure` does. A missing path raises `ConfigFileNotFoundError`. Matching follows the one rule described in the [Broadcasting guide](https://github.com/Gearlux/confluid/blob/main/docs/broadcasting.md): document order, last write wins.
+
+### 4. Dump and Reconstruct
+```python
+from confluid import dump, load
+
+# Export current state
+state_yaml = dump(trainer)
+
+# Recreate exact same hierarchy in a new process
+new_trainer = load(state_yaml)
+```
+
+## Installation
+```bash
+pip install confluid                     # from PyPI
+pip install "confluid[pydantic]"    # + pydantic-powered schema export & validation
+```
+
+Or straight from GitHub:
+
+```bash
+pip install git+https://github.com/Gearlux/confluid.git@main
+```
+
+## License
+MIT

confluid-0.1.0/confluid/__init__.py

@@ -0,0 +1,152 @@
+"""
+Confluid: Modern, hierarchical configuration and dependency injection.
+
+The pydantic-powered schema-export API (``to_pydantic``, ``confluid_class_of``)
+is exposed lazily via :pep:`562` ``__getattr__`` so importing confluid never
+requires pydantic — it is the optional ``confluid[pydantic]`` extra. Accessing
+those names without pydantic installed raises an ``ImportError`` naming the
+extra.
+
+``__all__`` is the CURATED public surface (pruned 2026-07): internal
+machinery (validation plumbing, scope resolution, annotation predicates,
+marker internals) stays importable from its home module but is deliberately
+not re-exported here.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from confluid.configurator import configure, configure_from_file
+from confluid.decorators import configurable, ignore_config, output, register
+from confluid.dumper import dump
+from confluid.engine import active_context, cast, collect_report, flow, get_configurable_attrs, materialize, resolve
+from confluid.exceptions import (
+    CircularIncludeError,
+    ConfigFileNotFoundError,
+    ConfigurableDefinitionError,
+    ConfigurationError,
+    ConfluidError,
+    ConstructionError,
+    IntrospectionError,
+    ReferenceResolutionError,
+    ScopeError,
+    UnknownClassError,
+    ValidationModeError,
+    WorkspaceEnvError,
+)
+from confluid.fluid import Class, Clone, Fluid, Instance
+from confluid.fluid import Lazy as LazyClass
+from confluid.fluid import Reference, format_yaml_loc
+from confluid.lazy import Lazy, lazy_param_names
+from confluid.llm_schema import sanitize_schema
+from confluid.loader import get_app_name, load, load_config, load_config_with_paths, resolve_config_path, set_app_name
+from confluid.mandatory import Mandatory, mandatory_param_names
+from confluid.merger import deep_merge, expand_dotted_keys
+from confluid.no_broadcast import NoBroadcast, no_broadcast_param_names
+from confluid.registry import get_registry
+from confluid.report import ConfigurationReport
+from confluid.resolver import parse_value
+from confluid.schema import (
+    InputSpec,
+    OutputSpec,
+    get_hierarchy,
+    get_hierarchy_from_instance,
+    input_specs,
+    output_specs,
+    parse_param_docs,
+    shortest_unique_paths,
+)
+from confluid.scopes import discover_dimensions
+from confluid.validation import ValidationMode, ValidationPolicy, get_policy, reset_policy, set_policy, validate_model
+
+__all__ = [
+    "ConfluidError",
+    "ConfigurationError",
+    "CircularIncludeError",
+    "ReferenceResolutionError",
+    "UnknownClassError",
+    "ConfigurableDefinitionError",
+    "ValidationModeError",
+    "ScopeError",
+    "ConfigFileNotFoundError",
+    "ConstructionError",
+    "WorkspaceEnvError",
+    "IntrospectionError",
+    "configurable",
+    "register",
+    "ignore_config",
+    "output",
+    "get_registry",
+    "load",
+    "load_config",
+    "load_config_with_paths",
+    "resolve_config_path",
+    "set_app_name",
+    "get_app_name",
+    "materialize",
+    "resolve",
+    "active_context",
+    "deep_merge",
+    "expand_dotted_keys",
+    "parse_value",
+    "dump",
+    "configure",
+    "configure_from_file",
+    "ConfigurationReport",
+    "collect_report",
+    "Fluid",
+    "Class",
+    "Clone",
+    "Instance",
+    "Reference",
+    "flow",
+    "cast",
+    "format_yaml_loc",
+    "Lazy",
+    "LazyClass",
+    "lazy_param_names",
+    "Mandatory",
+    "mandatory_param_names",
+    "NoBroadcast",
+    "no_broadcast_param_names",
+    "get_hierarchy",
+    "get_hierarchy_from_instance",
+    "input_specs",
+    "output_specs",
+    "InputSpec",
+    "OutputSpec",
+    "parse_param_docs",
+    "shortest_unique_paths",
+    "get_configurable_attrs",
+    "to_pydantic",
+    "confluid_class_of",
+    "discover_dimensions",
+    "ValidationMode",
+    "ValidationPolicy",
+    "get_policy",
+    "set_policy",
+    "reset_policy",
+    "validate_model",
+    "sanitize_schema",
+]
+
+if TYPE_CHECKING:
+    from confluid.pydantic_export import confluid_class_of, to_pydantic
+
+# Names served lazily from ``confluid.pydantic_export`` (requires the
+# ``confluid[pydantic]`` extra) — see the module docstring.
+_PYDANTIC_EXPORTS = ("to_pydantic", "confluid_class_of")
+
+
+def __getattr__(name: str) -> Any:
+    if name in _PYDANTIC_EXPORTS:
+        try:
+            from confluid import pydantic_export
+        except ModuleNotFoundError as exc:
+            if exc.name in ("pydantic", "annotated_types"):
+                raise ImportError(
+                    f"confluid.{name} requires pydantic, which is an optional dependency — "
+                    "install the extra: pip install 'confluid[pydantic]'"
+                ) from exc
+            raise
+        return getattr(pydantic_export, name)
+    raise AttributeError(f"module 'confluid' has no attribute {name!r}")