utilityhub_config 0.1.0__tar.gz

utilityhub_config-0.1.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.3
+Name: utilityhub_config
+Version: 0.1.0
+Summary: A deterministic, typed configuration engine for serious automation systems
+Author: Rajesh Das
+Author-email: Rajesh Das <rajesh@hyperoot.dev>
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# utilityhub_config
+
+A **deterministic, typed configuration loader** for modern Python applications. Load settings from multiple sources with clear precedence, comprehensive metadata tracking, and detailed validation errors.
+
+## Features ✨
+
+- **Multi-source configuration loading** with explicit precedence order
+- **Strongly typed** with Pydantic v2+ (full type safety)
+- **Metadata tracking** — see which source provided each field
+- **Multiple formats** — TOML, YAML, .env, environment variables
+- **Rich error reporting** — Validation failures show sources, checked files, and precedence
+- **Zero magic** — Deterministic, transparent resolution order
+
+## Installation
+
+```bash
+pip install utilityhub_config
+```
+
+## Quick Start
+
+```python
+from pydantic import BaseModel
+from utilityhub_config import load_settings
+
+class Config(BaseModel):
+    database_url: str = "sqlite:///default.db"
+    debug: bool = False
+
+# Load settings and metadata
+settings, metadata = load_settings(Config)
+
+# Type-safe access (no casting needed)
+print(settings.database_url)
+
+# Track which source provided a field
+source = metadata.get_source("database_url")
+print(f"database_url came from: {source.source}")
+```
+
+## How It Works
+
+Settings are resolved in **strict precedence order** (lowest to highest):
+
+1. **Defaults** — Field defaults from your Pydantic model
+2. **Global config** — `~/.config/{app_name}/{app_name}.{toml,yaml}`
+3. **Project config** — `{cwd}/{app_name}.{toml,yaml}` or `{cwd}/config/*.{toml,yaml}`
+4. **Dotenv** — `.env` file in current directory
+5. **Environment variables** — `{APP_NAME}_{FIELD_NAME}` or `{FIELD_NAME}`
+6. **Runtime overrides** — Passed via `overrides` parameter (highest priority)
+
+Each level overrides the previous one. Only sources that exist are consulted.
+
+## Examples
+
+### Basic usage with model defaults
+
+```python
+from pydantic import BaseModel
+from utilityhub_config import load_settings
+
+class PizzaShopConfig(BaseModel):
+    shop_name: str = "lazy_pepperoni_palace"
+    delivery_radius_km: int = 5
+    accepts_orders: bool = False  # closed by default
+
+settings, metadata = load_settings(PizzaShopConfig)
+print(f"🍕 {settings.shop_name} is {'open' if settings.accepts_orders else 'closed'}")
+```
+
+### Override with environment variables
+
+```python
+import os
+
+# Friday night rush: OPEN ALL THE STORES!
+os.environ["ACCEPTS_ORDERS"] = "true"
+os.environ["DELIVERY_RADIUS_KM"] = "15"
+
+settings, metadata = load_settings(PizzaShopConfig)
+print(f"🚗 Delivering pizza up to {settings.delivery_radius_km}km away!")
+```
+
+### Runtime overrides (highest priority)
+
+```python
+# Emergency: meteor incoming, expand radius and accept everything!
+settings, metadata = load_settings(
+    PizzaShopConfig,
+    overrides={
+        "accepts_orders": True,
+        "delivery_radius_km": 100,
+        "shop_name": "doomsday_pizza_bunker"
+    }
+)
+print(f"🚀 {settings.shop_name} now delivers {settings.delivery_radius_km}km!")
+```
+
+### Custom app name and config directory
+
+```python
+settings, metadata = load_settings(
+    PizzaShopConfig,
+    app_name="pizza_empire",
+    cwd="/etc/pizza_shops/"
+)
+# Looks for: /etc/pizza_shops/pizza_empire.toml or .yaml
+```
+
+### Environment variable prefix
+
+```python
+os.environ["PIZZASHOP_ACCEPTS_ORDERS"] = "true"
+os.environ["PIZZASHOP_DELIVERY_RADIUS_KM"] = "42"
+
+settings, metadata = load_settings(
+    PizzaShopConfig,
+    env_prefix="PIZZASHOP"
+)
+# Will check: PIZZASHOP_ACCEPTS_ORDERS, then ACCEPTS_ORDERS (in that order)
+print(f"🍕 Accepting orders: {settings.accepts_orders}")
+```
+
+### Inspect metadata (detective mode 🕵️)
+
+```python
+settings, metadata = load_settings(PizzaShopConfig)
+
+# Which source provided this field?
+source = metadata.get_source("delivery_radius_km")
+print(f"Delivery radius came from: {source.source}")
+print(f"Location: {source.source_path or 'model defaults'}")
+print(f"Raw value: {source.raw_value}")
+
+# Track all field origins
+for field, source_info in metadata.per_field.items():
+    print(f"  {field}: from {source_info.source}")
+```
+
+## Configuration Files
+
+### TOML example (`pizza_empire.toml`)
+
+```toml
+# 🍕 Pizza Empire Global Settings
+shop_name = "the_great_carb_dispensary"
+delivery_radius_km = 5
+accepts_orders = false
+
+# The business secret sauce 🔥
+[quality]
+cheese_ratio = 0.42  # more cheese = more problems (and happiness)
+crust_crispiness = "perfect"
+pineapple_tolerance = 0.0  # this is not a debate
+
+[timings]
+avg_prep_time_minutes = 15
+delivery_timeout_minutes = 45
+```
+
+### YAML example (`pizza_empire.yaml`)
+
+```yaml
+# 🍕 Pizza Empire Configuration
+shop_name: the_great_carb_dispensary
+delivery_radius_km: 5
+accepts_orders: false
+
+# The art of pizza
+quality:
+  cheese_ratio: 0.42
+  crust_crispiness: "perfect"
+  pineapple_tolerance: 0.0
+
+timings:
+  avg_prep_time_minutes: 15
+  delivery_timeout_minutes: 45
+```
+
+### Dotenv example (`.env`)
+
+```bash
+# 🍕 Quick overrides for this deployment
+SHOP_NAME=emergency_pizza_hut
+DELIVERY_RADIUS_KM=100
+ACCEPTS_ORDERS=true
+CHEESE_RATIO=0.99
+PINEAPPLE_TOLERANCE=0.0  # NEVER SURRENDER
+```
+
+## API Reference
+
+### `load_settings(model, *, app_name=None, cwd=None, env_prefix=None, overrides=None)`
+
+Load and validate settings from all sources.
+
+**Parameters:**
+
+- `model` (type[T]): A Pydantic BaseModel subclass to validate and populate.
+- `app_name` (str | None): Application name for config file lookup. Defaults to lowercased model class name.
+- `cwd` (Path | None): Working directory for config file search. Defaults to current directory.
+- `env_prefix` (str | None): Optional prefix for environment variables (e.g., `"MYAPP"`).
+- `overrides` (dict[str, Any] | None): Runtime overrides (highest precedence).
+
+**Returns:**
+
+A tuple `(settings, metadata)` where:
+- `settings` is an instance of your model type (fully type-safe, no casting needed).
+- `metadata` is a `SettingsMetadata` object tracking field sources.
+
+**Raises:**
+
+- `ConfigValidationError` — If validation fails, includes detailed context:
+  - Validation errors from Pydantic
+  - Files that were checked
+  - Precedence order
+  - Which source provided each field
+
+### `SettingsMetadata`
+
+Tracks where each field value came from.
+
+- `per_field: dict[str, FieldSource]` — Field name to source mapping.
+- `get_source(field: str) -> FieldSource | None` — Look up a single field's source.
+
+### `FieldSource`
+
+- `source: str` — Source name (`"defaults"`, `"env"`, `"project"`, etc.).
+- `source_path: str | None` — File path or env var name.
+- `raw_value: Any` — The raw value before type coercion.
+
+## Known Limitations
+
+- **Nested types**: Complex nested Pydantic models in TOML/YAML are supported (Pydantic handles validation), but the loader doesn't do special merging. Flat dictionaries are recommended.
+- **Case sensitivity**: Dotenv keys are normalized to lowercase; model field names are case-sensitive.
+- **Variable expansion**: Dotenv values don't expand environment variables (e.g., `$HOME` won't expand). Use `python-dotenv` directly if needed.
+
+## Error Handling
+
+When validation fails, you get a detailed error with full context (perfect for debugging at 3 AM):
+
+```python
+from utilityhub_config import load_settings
+from utilityhub_config.errors import ConfigValidationError
+
+class PizzaShopConfig(BaseModel):
+    delivery_radius_km: int  # REQUIRED (no default, no pizza!)
+
+try:
+    settings, metadata = load_settings(PizzaShopConfig)
+except ConfigValidationError as e:
+    # Shows:
+    # - What validation failed
+    # - Which files were checked
+    # - The precedence order
+    # - Which source provided each field
+    print(e)  # Complete context for debugging!
+```
+
+Output example:
+```
+Validation failed
+
+Validation errors:
+input should be a valid integer [type=int_parsing, input_value=None, input_type=NoneType]
+
+Files checked:
+ - ~/.config/pizzashop/pizzashop.toml
+ - ~/.config/pizzashop/pizzashop.yaml
+ - /home/user/.env
+
+Precedence (low -> high):
+defaults -> global -> project -> dotenv -> env -> overrides
+
+Field sources:
+ - delivery_radius_km: defaults (None)
+```
+
+## Contributing
+
+For issues, improvements, or questions, please open an issue or pull request.
+
+## Documentation
+
+Full documentation and examples will be available at: **[docs link TBD]**
+
+---
+
+**License**: See project LICENSE file.

utilityhub_config-0.1.0/README.md

@@ -0,0 +1,289 @@
+# utilityhub_config
+
+A **deterministic, typed configuration loader** for modern Python applications. Load settings from multiple sources with clear precedence, comprehensive metadata tracking, and detailed validation errors.
+
+## Features ✨
+
+- **Multi-source configuration loading** with explicit precedence order
+- **Strongly typed** with Pydantic v2+ (full type safety)
+- **Metadata tracking** — see which source provided each field
+- **Multiple formats** — TOML, YAML, .env, environment variables
+- **Rich error reporting** — Validation failures show sources, checked files, and precedence
+- **Zero magic** — Deterministic, transparent resolution order
+
+## Installation
+
+```bash
+pip install utilityhub_config
+```
+
+## Quick Start
+
+```python
+from pydantic import BaseModel
+from utilityhub_config import load_settings
+
+class Config(BaseModel):
+    database_url: str = "sqlite:///default.db"
+    debug: bool = False
+
+# Load settings and metadata
+settings, metadata = load_settings(Config)
+
+# Type-safe access (no casting needed)
+print(settings.database_url)
+
+# Track which source provided a field
+source = metadata.get_source("database_url")
+print(f"database_url came from: {source.source}")
+```
+
+## How It Works
+
+Settings are resolved in **strict precedence order** (lowest to highest):
+
+1. **Defaults** — Field defaults from your Pydantic model
+2. **Global config** — `~/.config/{app_name}/{app_name}.{toml,yaml}`
+3. **Project config** — `{cwd}/{app_name}.{toml,yaml}` or `{cwd}/config/*.{toml,yaml}`
+4. **Dotenv** — `.env` file in current directory
+5. **Environment variables** — `{APP_NAME}_{FIELD_NAME}` or `{FIELD_NAME}`
+6. **Runtime overrides** — Passed via `overrides` parameter (highest priority)
+
+Each level overrides the previous one. Only sources that exist are consulted.
+
+## Examples
+
+### Basic usage with model defaults
+
+```python
+from pydantic import BaseModel
+from utilityhub_config import load_settings
+
+class PizzaShopConfig(BaseModel):
+    shop_name: str = "lazy_pepperoni_palace"
+    delivery_radius_km: int = 5
+    accepts_orders: bool = False  # closed by default
+
+settings, metadata = load_settings(PizzaShopConfig)
+print(f"🍕 {settings.shop_name} is {'open' if settings.accepts_orders else 'closed'}")
+```
+
+### Override with environment variables
+
+```python
+import os
+
+# Friday night rush: OPEN ALL THE STORES!
+os.environ["ACCEPTS_ORDERS"] = "true"
+os.environ["DELIVERY_RADIUS_KM"] = "15"
+
+settings, metadata = load_settings(PizzaShopConfig)
+print(f"🚗 Delivering pizza up to {settings.delivery_radius_km}km away!")
+```
+
+### Runtime overrides (highest priority)
+
+```python
+# Emergency: meteor incoming, expand radius and accept everything!
+settings, metadata = load_settings(
+    PizzaShopConfig,
+    overrides={
+        "accepts_orders": True,
+        "delivery_radius_km": 100,
+        "shop_name": "doomsday_pizza_bunker"
+    }
+)
+print(f"🚀 {settings.shop_name} now delivers {settings.delivery_radius_km}km!")
+```
+
+### Custom app name and config directory
+
+```python
+settings, metadata = load_settings(
+    PizzaShopConfig,
+    app_name="pizza_empire",
+    cwd="/etc/pizza_shops/"
+)
+# Looks for: /etc/pizza_shops/pizza_empire.toml or .yaml
+```
+
+### Environment variable prefix
+
+```python
+os.environ["PIZZASHOP_ACCEPTS_ORDERS"] = "true"
+os.environ["PIZZASHOP_DELIVERY_RADIUS_KM"] = "42"
+
+settings, metadata = load_settings(
+    PizzaShopConfig,
+    env_prefix="PIZZASHOP"
+)
+# Will check: PIZZASHOP_ACCEPTS_ORDERS, then ACCEPTS_ORDERS (in that order)
+print(f"🍕 Accepting orders: {settings.accepts_orders}")
+```
+
+### Inspect metadata (detective mode 🕵️)
+
+```python
+settings, metadata = load_settings(PizzaShopConfig)
+
+# Which source provided this field?
+source = metadata.get_source("delivery_radius_km")
+print(f"Delivery radius came from: {source.source}")
+print(f"Location: {source.source_path or 'model defaults'}")
+print(f"Raw value: {source.raw_value}")
+
+# Track all field origins
+for field, source_info in metadata.per_field.items():
+    print(f"  {field}: from {source_info.source}")
+```
+
+## Configuration Files
+
+### TOML example (`pizza_empire.toml`)
+
+```toml
+# 🍕 Pizza Empire Global Settings
+shop_name = "the_great_carb_dispensary"
+delivery_radius_km = 5
+accepts_orders = false
+
+# The business secret sauce 🔥
+[quality]
+cheese_ratio = 0.42  # more cheese = more problems (and happiness)
+crust_crispiness = "perfect"
+pineapple_tolerance = 0.0  # this is not a debate
+
+[timings]
+avg_prep_time_minutes = 15
+delivery_timeout_minutes = 45
+```
+
+### YAML example (`pizza_empire.yaml`)
+
+```yaml
+# 🍕 Pizza Empire Configuration
+shop_name: the_great_carb_dispensary
+delivery_radius_km: 5
+accepts_orders: false
+
+# The art of pizza
+quality:
+  cheese_ratio: 0.42
+  crust_crispiness: "perfect"
+  pineapple_tolerance: 0.0
+
+timings:
+  avg_prep_time_minutes: 15
+  delivery_timeout_minutes: 45
+```
+
+### Dotenv example (`.env`)
+
+```bash
+# 🍕 Quick overrides for this deployment
+SHOP_NAME=emergency_pizza_hut
+DELIVERY_RADIUS_KM=100
+ACCEPTS_ORDERS=true
+CHEESE_RATIO=0.99
+PINEAPPLE_TOLERANCE=0.0  # NEVER SURRENDER
+```
+
+## API Reference
+
+### `load_settings(model, *, app_name=None, cwd=None, env_prefix=None, overrides=None)`
+
+Load and validate settings from all sources.
+
+**Parameters:**
+
+- `model` (type[T]): A Pydantic BaseModel subclass to validate and populate.
+- `app_name` (str | None): Application name for config file lookup. Defaults to lowercased model class name.
+- `cwd` (Path | None): Working directory for config file search. Defaults to current directory.
+- `env_prefix` (str | None): Optional prefix for environment variables (e.g., `"MYAPP"`).
+- `overrides` (dict[str, Any] | None): Runtime overrides (highest precedence).
+
+**Returns:**
+
+A tuple `(settings, metadata)` where:
+- `settings` is an instance of your model type (fully type-safe, no casting needed).
+- `metadata` is a `SettingsMetadata` object tracking field sources.
+
+**Raises:**
+
+- `ConfigValidationError` — If validation fails, includes detailed context:
+  - Validation errors from Pydantic
+  - Files that were checked
+  - Precedence order
+  - Which source provided each field
+
+### `SettingsMetadata`
+
+Tracks where each field value came from.
+
+- `per_field: dict[str, FieldSource]` — Field name to source mapping.
+- `get_source(field: str) -> FieldSource | None` — Look up a single field's source.
+
+### `FieldSource`
+
+- `source: str` — Source name (`"defaults"`, `"env"`, `"project"`, etc.).
+- `source_path: str | None` — File path or env var name.
+- `raw_value: Any` — The raw value before type coercion.
+
+## Known Limitations
+
+- **Nested types**: Complex nested Pydantic models in TOML/YAML are supported (Pydantic handles validation), but the loader doesn't do special merging. Flat dictionaries are recommended.
+- **Case sensitivity**: Dotenv keys are normalized to lowercase; model field names are case-sensitive.
+- **Variable expansion**: Dotenv values don't expand environment variables (e.g., `$HOME` won't expand). Use `python-dotenv` directly if needed.
+
+## Error Handling
+
+When validation fails, you get a detailed error with full context (perfect for debugging at 3 AM):
+
+```python
+from utilityhub_config import load_settings
+from utilityhub_config.errors import ConfigValidationError
+
+class PizzaShopConfig(BaseModel):
+    delivery_radius_km: int  # REQUIRED (no default, no pizza!)
+
+try:
+    settings, metadata = load_settings(PizzaShopConfig)
+except ConfigValidationError as e:
+    # Shows:
+    # - What validation failed
+    # - Which files were checked
+    # - The precedence order
+    # - Which source provided each field
+    print(e)  # Complete context for debugging!
+```
+
+Output example:
+```
+Validation failed
+
+Validation errors:
+input should be a valid integer [type=int_parsing, input_value=None, input_type=NoneType]
+
+Files checked:
+ - ~/.config/pizzashop/pizzashop.toml
+ - ~/.config/pizzashop/pizzashop.yaml
+ - /home/user/.env
+
+Precedence (low -> high):
+defaults -> global -> project -> dotenv -> env -> overrides
+
+Field sources:
+ - delivery_radius_km: defaults (None)
+```
+
+## Contributing
+
+For issues, improvements, or questions, please open an issue or pull request.
+
+## Documentation
+
+Full documentation and examples will be available at: **[docs link TBD]**
+
+---
+
+**License**: See project LICENSE file.

utilityhub_config-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "utilityhub_config"
+version = "0.1.0"
+description = "A deterministic, typed configuration engine for serious automation systems"
+readme = "README.md"
+authors = [{ name = "Rajesh Das", email = "rajesh@hyperoot.dev" }]
+requires-python = ">=3.14"
+dependencies = ["pydantic>=2.12.5", "PyYAML>=6.0.3", "python-dotenv>=1.0.0"]
+
+[project.scripts]
+utilityhub_config = "utilityhub_config:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"

utilityhub_config-0.1.0/src/utilityhub_config/__init__.py

@@ -0,0 +1,12 @@
+"""utilityhub_config
+
+Small, deterministic configuration loader for automation tools.
+"""
+
+from utilityhub_config.api import load_settings
+
+__all__: list[str] = ["load_settings"]
+
+
+def main() -> None:
+    print("utilityhub-config: use `load_settings()` in your code")

utilityhub_config-0.1.0/src/utilityhub_config/api.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from utilityhub_config.errors import ConfigValidationError
+from utilityhub_config.metadata import SettingsMetadata
+from utilityhub_config.resolver import PrecedenceResolver
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def load_settings[T: BaseModel](
+    model: type[T],
+    *,
+    app_name: str | None = None,
+    cwd: Path | None = None,
+    env_prefix: str | None = None,
+    overrides: dict[str, Any] | None = None,
+) -> tuple[T, SettingsMetadata]:
+    """Load and validate settings for the given Pydantic model.
+
+    Resolves configuration from multiple sources in precedence order:
+    defaults → global config → project config → dotenv → environment variables → runtime overrides.
+
+    Args:
+        model: A Pydantic BaseModel subclass to validate and populate.
+        app_name: Application name for config file lookup (defaults to model class name).
+        cwd: Working directory for config file search (defaults to current directory).
+        env_prefix: Optional prefix for environment variable lookup (e.g., 'MYAPP_').
+        overrides: Runtime overrides as a dictionary (highest precedence).
+
+    Returns:
+        A tuple of (settings_instance, metadata) where settings_instance is an instance
+        of the provided model type, and metadata tracks which source provided each field.
+
+    Raises:
+        ConfigValidationError: If validation fails, with detailed context about sources and files checked.
+    """
+    cwd = Path.cwd() if cwd is None else cwd
+
+    resolver = PrecedenceResolver(app_name=app_name, cwd=cwd, env_prefix=env_prefix)
+
+    merged, metadata, checked_files = resolver.resolve(model=model, overrides=overrides or {})
+
+    try:
+        instance = model.model_validate(merged)
+    except ValidationError as exc:  # pydantic v2
+        raise ConfigValidationError(
+            "Validation failed",
+            errors=exc,
+            metadata=metadata,
+            checked_files=checked_files,
+            precedence=resolver.precedence_order,
+        ) from exc
+
+    return instance, metadata

utilityhub_config-0.1.0/src/utilityhub_config/errors.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from pydantic import ValidationError
+
+from utilityhub_config.metadata import SettingsMetadata
+
+
+class ConfigError(Exception):
+    """Base configuration error."""
+
+
+@dataclass
+class ConfigValidationError(ConfigError):
+    message: str
+    errors: ValidationError
+    metadata: SettingsMetadata
+    checked_files: Iterable[str]
+    precedence: list[str]
+
+    def __str__(self) -> str:  # human-friendly
+        case_lines = [self.message, ""]
+        case_lines.append("Validation errors:")
+        case_lines.extend([str(self.errors)])
+        case_lines.append("")
+        case_lines.append("Files checked:")
+        case_lines.extend([f" - {p}" for p in self.checked_files])
+        case_lines.append("")
+        case_lines.append("Precedence (low -> high):")
+        case_lines.append(" -> ".join(self.precedence))
+        case_lines.append("")
+        case_lines.append("Field sources:")
+        for k, v in self.metadata.per_field.items():
+            case_lines.append(f" - {k}: {v.source} ({v.source_path})")
+        return "\n".join(case_lines)

utilityhub_config-0.1.0/src/utilityhub_config/metadata.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FieldSource:
+    source: str
+    source_path: str | None
+    raw_value: Any
+
+
+@dataclass
+class SettingsMetadata:
+    per_field: dict[str, FieldSource]
+
+    def get_source(self, field: str) -> FieldSource | None:
+        return self.per_field.get(field)

utilityhub_config-0.1.0/src/utilityhub_config/readers/__init__.py

@@ -0,0 +1,5 @@
+from utilityhub_config.readers.dotenv_reader import parse_dotenv
+from utilityhub_config.readers.toml_reader import read_toml
+from utilityhub_config.readers.yaml_reader import read_yaml
+
+__all__ = ["read_toml", "read_yaml", "parse_dotenv"]

utilityhub_config-0.1.0/src/utilityhub_config/readers/dotenv_reader.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def parse_dotenv(path: Path) -> dict[str, str]:
+    """Parse a .env file into a dictionary.
+
+    Uses python-dotenv for robust parsing with support for:
+    - Comments (lines starting with #)
+    - Quoted values (single and double quotes)
+    - Escape sequences
+    - Variable expansion (if expand_vars is True)
+
+    Args:
+        path: Path to the .env file.
+
+    Returns:
+        A dictionary of environment variables from the file, or empty dict if file doesn't exist.
+    """
+    if not path.exists():
+        return {}
+    try:
+        from dotenv import dotenv_values
+
+        values = dotenv_values(path) or {}
+        # Ensure all values are strings (python-dotenv can return None)
+        return {k: (v or "") for k, v in values.items()}
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            f"dotenv file found at {path}, but python-dotenv is not installed. "
+            "Install 'python-dotenv' to enable .env file support."
+        ) from exc
+    except Exception as exc:
+        raise RuntimeError(f"Failed to parse .env file at {path}: {exc}") from exc

utilityhub_config-0.1.0/src/utilityhub_config/readers/toml_reader.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def read_toml(path: Path) -> dict[str, Any]:
+    """Read a TOML file and return mapping, or empty dict if not found."""
+    if not path.exists():
+        return {}
+    try:
+        import tomllib
+
+        with path.open("rb") as fh:
+            return tomllib.load(fh) or {}
+    except Exception as exc:  # be explicit in errors upstream
+        raise RuntimeError(f"Failed to parse TOML at {path}: {exc}") from exc

utilityhub_config-0.1.0/src/utilityhub_config/readers/yaml_reader.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def read_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        import yaml
+
+        with path.open("r", encoding="utf8") as fh:
+            return yaml.safe_load(fh) or {}
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            f"YAML file found at {path}, but PyYAML is not installed. Install 'PyYAML' to enable YAML support."
+        ) from exc
+    except Exception as exc:
+        raise RuntimeError(f"Failed to parse YAML at {path}: {exc}") from exc

utilityhub_config-0.1.0/src/utilityhub_config/resolver.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from utilityhub_config.metadata import FieldSource, SettingsMetadata
+from utilityhub_config.readers import parse_dotenv, read_toml, read_yaml
+
+
+@dataclass
+class PrecedenceResolver:
+    """Resolves configuration from multiple sources in precedence order.
+
+    Attributes:
+        app_name: Application name for config file lookup. If None, derived from model class name.
+        cwd: Working directory for config file search (defaults: current working directory).
+        env_prefix: Optional prefix for environment variable lookup (e.g., 'MYAPP_').
+    """
+
+    app_name: str | None = None
+    cwd: Path = field(default_factory=Path.cwd)
+    env_prefix: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.cwd is None:
+            self.cwd = Path.cwd()
+        self.precedence_order = [
+            "defaults",
+            "global",
+            "project",
+            "dotenv",
+            "env",
+            "overrides",
+        ]
+
+    def resolve(
+        self, *, model: type[BaseModel], overrides: dict[str, Any]
+    ) -> tuple[dict[str, Any], SettingsMetadata, list[str]]:
+        app = self._determine_app_name(model)
+
+        checked_files: list[str] = []
+        per_field: dict[str, FieldSource] = {}
+
+        # 1. defaults from model
+        merged: dict[str, Any] = {}
+        defaults = self._model_defaults(model)
+        merged.update(defaults)
+        for k, v in defaults.items():
+            per_field[k] = FieldSource("defaults", None, v)
+
+        # 2. global config
+        global_paths = self._global_config_paths(app)
+        for p in global_paths:
+            checked_files.append(str(p))
+            if p.exists():
+                data = read_toml(p) if p.suffix.lower() == ".toml" else read_yaml(p)
+                self._merge_into(merged, per_field, data, source_name="global", source_path=str(p))
+
+        # 3. project config
+        project_files = self._project_config_paths(app)
+        for p in project_files:
+            checked_files.append(str(p))
+            if p.exists():
+                data = read_toml(p) if p.suffix.lower() == ".toml" else read_yaml(p)
+                self._merge_into(merged, per_field, data, source_name="project", source_path=str(p))
+
+        # 4. dotenv
+        dotenv_path = self.cwd / ".env"
+        checked_files.append(str(dotenv_path))
+        dotenv_data = parse_dotenv(dotenv_path)
+        # dotenv keys are usually uppercase; normalize to field names
+        normalized_dotenv = {self._normalize(k): v for k, v in dotenv_data.items()}
+        self._merge_into(merged, per_field, normalized_dotenv, source_name="dotenv", source_path=str(dotenv_path))
+
+        # 5. environment variables
+        env_map: dict[str, Any] = {}
+        for field_name in self._field_names(model):
+            candidates: list[str] = []
+            if self.env_prefix:
+                candidates.append(f"{self.env_prefix}_{field_name.upper()}")
+            candidates.append(field_name.upper())
+            for name in candidates:
+                if name in os.environ:
+                    env_map[field_name] = os.environ[name]
+                    per_field[field_name] = FieldSource("env", f"ENV:{name}", os.environ[name])
+                    break
+
+        merged.update(env_map)
+
+        # 6. overrides
+        if overrides:
+            self._merge_into(merged, per_field, overrides, source_name="overrides", source_path="runtime")
+
+        metadata = SettingsMetadata(per_field=per_field)
+        return merged, metadata, checked_files
+
+    def _model_defaults(self, model: type[BaseModel]) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        # pydantic v2
+        fields = getattr(model, "model_fields", None)
+        if fields is not None:
+            for k, info in fields.items():
+                if getattr(info, "default", None) not in (None, ...):
+                    out[k] = info.default
+        else:
+            # pydantic v1 style
+            fields = getattr(model, "__fields__", {})
+            for k, f in fields.items():
+                if f.default is not None:
+                    out[k] = f.default
+        return out
+
+    def _field_names(self, model: type[BaseModel]) -> list[str]:
+        fields = getattr(model, "model_fields", None)
+        if fields is not None:
+            return list(fields.keys())
+        return list(getattr(model, "__fields__", {}).keys())
+
+    def _determine_app_name(self, model: type[BaseModel]) -> str:
+        """Determine the app name from explicit arg, model default, or class name.
+
+        Precedence: explicit app_name > model field default > model class name (lowercased).
+        """
+        if self.app_name:
+            return self.app_name
+        # try to pull default from model field 'app_name' if present
+        fields = getattr(model, "model_fields", None)
+        if fields and "app_name" in fields:
+            default = fields["app_name"].default
+            if default not in (None, ...):
+                return str(default)
+        # fallback to model class name
+        return model.__name__.lower()
+
+    def _global_config_paths(self, app: str) -> list[Path]:
+        home = Path.home()
+        cfg_dir = home / ".config" / app
+        return [cfg_dir / f"{app}.toml", cfg_dir / f"{app}.yaml"]
+
+    def _project_config_paths(self, app: str) -> list[Path]:
+        out: list[Path] = []
+        root_toml = self.cwd / f"{app}.toml"
+        root_yaml = self.cwd / f"{app}.yaml"
+        out.extend([root_toml, root_yaml])
+        config_dir = self.cwd / "config"
+        if config_dir.exists() and config_dir.is_dir():
+            for ext in ("*.toml", "*.yaml", "*.yml"):
+                out.extend(sorted(config_dir.glob(ext)))
+        return out
+
+    def _normalize(self, key: str) -> str:
+        return key.strip().lower().replace("-", "_")
+
+    def _merge_into(
+        self,
+        target: dict[str, Any],
+        per_field: dict[str, FieldSource],
+        source: dict[str, Any],
+        *,
+        source_name: str,
+        source_path: str | None = None,
+    ) -> None:
+        # source keys may be in various forms; normalize and map to fields
+        for k, v in source.items():
+            nk = self._normalize(str(k))
+            # if key is nested mapping matching field exactly, allow
+            target[nk] = v
+            per_field[nk] = FieldSource(source_name, source_path, v)