singularitysql 0.1.0__tar.gz

singularitysql-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel Urrego
+
+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.

singularitysql-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: singularitysql
+Version: 0.1.0
+Summary: SQL Server stored procedure introspection and Pydantic model generator
+Author: Samuel Urrego
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyodbc>=5.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.9
+Requires-Dist: tomli>=2.0
+Requires-Dist: rich>=15.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.png" alt="Singularity" width="400">
+</p>
+
+> SQL Server → Pydantic v2. Automatically.
+
+[![CI](https://github.com/Samuel-Urrego/Singularity/actions/workflows/ci.yml/badge.svg)](https://github.com/Samuel-Urrego/Singularity/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/singularity.svg)](https://pypi.org/project/singularity/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Singularity bridges the gap between SQL Server and Python. Connect to your database, point at a stored procedure, and get a **Pydantic v2 model** — as a runtime class or a `.py` file you can commit.
+
+```bash
+singularity --config config.toml
+```
+
+```python
+from singularity import SQLServerIntrospector, generate_model
+
+introspector = SQLServerIntrospector("DRIVER={ODBC Driver 17};SERVER=...;DATABASE=...")
+meta = introspector.introspect("usp_GetOrders")
+model = generate_model(meta, mode="dynamic")
+# <class 'pydantic.main.UspGetOrders'>
+```
+
+## Why Singularity?
+
+**The problem**: You have dozens of complex stored procedures in SQL Server. Calling them from Python means manually writing Pydantic models for every parameter and result set. One typo, and you get a runtime error.
+
+**The solution**: Singularity reads SQL Server's system catalog (`sys.parameters`, `sp_describe_first_result_set`) and generates the models for you. Zero manual mapping.
+
+| Approach | Lines of code | Maintainable | Type-safe |
+|---|---|---|---|
+| Manual Pydantic models | 100s–1000s | ❌ | ⚠️ (manual) |
+| Raw dicts / tuples | Fewer | ❌ | ❌ |
+| **Singularity** | **Zero** | ✅ | ✅ |
+
+## Features
+
+- 🔌 **Auto-connect** — pyodbc connection with `@@VERSION` detection
+- 🧠 **Version-aware** — Modern (2016+), Legacy (2008–2014), and Azure SQL strategies
+- 📦 **Two output modes**:
+  - `"dynamic"` — `create_model()` at runtime, usable immediately
+  - `"source"` — `.py` files you can commit and review
+- 🏷️ **Full type mapping** — `INT`→`int`, `VARCHAR`→`str`, `DATETIME`→`datetime`, `BIT`→`bool`, etc.
+- 🎨 **Configurable naming** — snake_case, camelCase, PascalCase for field names
+- 🗂️ **File naming templates** — `{schema}_{sp_name}.py`, `{database}_{sp_name}.py`, etc.
+- 🛡️ **Nullable awareness** — `Optional[T]` for nullable columns
+- ⚡ **UV-first** — fast dependency management
+
+## Installation
+
+```bash
+uv add singularity
+# or
+pip install singularity
+```
+
+**Prerequisite**: [ODBC Driver for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server) (17 or 18).
+
+## Quick Start
+
+### 1. Create a config file
+
+```toml
+# config.toml
+[connection]
+server = "localhost"
+database = "AdventureWorks"
+driver = "ODBC Driver 18 for SQL Server"
+trusted_connection = true
+
+[sp_selection]
+pattern = "usp_%"
+
+[output]
+directory = "generated_models"
+mode = "source"
+file_naming = "{schema}_{sp_name}.py"
+naming_convention = "snake_case"
+```
+
+### 2. Generate models
+
+```bash
+singularity --config config.toml
+```
+
+```
+Connected. Detected version: modern
+  Introspecting usp_GetOrders... → generated_models/dbo_usp_GetOrders.py
+  Introspecting usp_GetCustomers... → generated_models/dbo_usp_GetCustomers.py
+
+Done. 2 succeeded, 0 failed.
+```
+
+### 3. Use the generated models
+
+```python
+from generated_models.dbo_usp_GetOrders import UspGetOrders
+
+order = UspGetOrders(id=1, customer_name="Acme Corp", total=99.99)
+```
+
+## Library Usage
+
+```python
+from singularity import SQLServerIntrospector, generate_model
+
+# Connect and introspect
+introspector = SQLServerIntrospector(conn_str)
+introspector.connect()
+version = introspector.detect_version()  # ServerVersion.MODERN
+metadata = introspector.introspect("usp_GetOrders")
+
+# Runtime model
+DynamicModel = generate_model(metadata, mode="dynamic")
+instance = DynamicModel(id=1, customer_name="Acme")
+
+# Source code string
+source_code = generate_model(metadata, mode="source")
+with open("models/usp_GetOrders.py", "w") as f:
+    f.write(source_code)
+```
+
+## Configuration Reference
+
+### `[connection]`
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `server` | ✅ | — | Server hostname or IP |
+| `database` | ✅ | — | Database name |
+| `driver` | ❌ | `ODBC Driver 18 for SQL Server` | ODBC driver name |
+| `trusted_connection` | ❌ | `true` | Use Windows auth |
+| `username` | ❌ | — | SQL auth username |
+| `password` | ❌ | — | SQL auth password |
+
+### `[sp_selection]`
+
+| Field | Required | Description |
+|---|---|---|
+| `procedures` | ❌ | Explicit list of SP names |
+| `pattern` | ❌ | Wildcard pattern (e.g. `usp_%`) |
+
+At least one of `procedures` or `pattern` must be specified.
+
+### `[output]`
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `directory` | ❌ | `.` | Output directory |
+| `mode` | ❌ | `source` | `source` or `dynamic` |
+| `file_naming` | ❌ | `{sp_name}.py` | Template with `{schema}`, `{database}`, `{sp_name}` |
+| `naming_convention` | ❌ | `snake_case` | `snake_case`, `camelCase`, or `PascalCase` |
+
+## Supported SQL Server Versions
+
+| Version | Strategy | Parameter introspection | Result set metadata |
+|---|---|---|---|
+| 2016+ | Modern | `sys.parameters` | `sp_describe_first_result_set` |
+| 2008–2014 | Legacy | `sys.parameters` | `sp_describe_first_result_set` + `sys.columns` fallback |
+| Azure SQL | Azure | `sys.parameters` | `sys.dm_exec_describe_first_result_set` |
+
+## Type Mapping
+
+| SQL Server | Python | Pydantic |
+|---|---|---|
+| `INT`, `BIGINT`, `SMALLINT`, `TINYINT` | `int` | `int` |
+| `VARCHAR`, `NVARCHAR`, `CHAR`, `NCHAR`, `TEXT` | `str` | `str` |
+| `DATETIME`, `DATETIME2`, `DATE`, `SMALLDATETIME` | `datetime` | `datetime` |
+| `BIT` | `bool` | `bool` |
+| `DECIMAL`, `NUMERIC`, `FLOAT`, `REAL`, `MONEY` | `float` | `float` |
+| `UNIQUEIDENTIFIER` | `str` | `str` |
+| Unknown types | `str` + warning | `str` |
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/Samuel-Urrego/Singularity
+cd singularity
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and type-check
+uv run ruff check .
+uv run mypy singularity/
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

singularitysql-0.1.0/README.md

@@ -0,0 +1,198 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Singularity" width="400">
+</p>
+
+> SQL Server → Pydantic v2. Automatically.
+
+[![CI](https://github.com/Samuel-Urrego/Singularity/actions/workflows/ci.yml/badge.svg)](https://github.com/Samuel-Urrego/Singularity/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/singularity.svg)](https://pypi.org/project/singularity/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Singularity bridges the gap between SQL Server and Python. Connect to your database, point at a stored procedure, and get a **Pydantic v2 model** — as a runtime class or a `.py` file you can commit.
+
+```bash
+singularity --config config.toml
+```
+
+```python
+from singularity import SQLServerIntrospector, generate_model
+
+introspector = SQLServerIntrospector("DRIVER={ODBC Driver 17};SERVER=...;DATABASE=...")
+meta = introspector.introspect("usp_GetOrders")
+model = generate_model(meta, mode="dynamic")
+# <class 'pydantic.main.UspGetOrders'>
+```
+
+## Why Singularity?
+
+**The problem**: You have dozens of complex stored procedures in SQL Server. Calling them from Python means manually writing Pydantic models for every parameter and result set. One typo, and you get a runtime error.
+
+**The solution**: Singularity reads SQL Server's system catalog (`sys.parameters`, `sp_describe_first_result_set`) and generates the models for you. Zero manual mapping.
+
+| Approach | Lines of code | Maintainable | Type-safe |
+|---|---|---|---|
+| Manual Pydantic models | 100s–1000s | ❌ | ⚠️ (manual) |
+| Raw dicts / tuples | Fewer | ❌ | ❌ |
+| **Singularity** | **Zero** | ✅ | ✅ |
+
+## Features
+
+- 🔌 **Auto-connect** — pyodbc connection with `@@VERSION` detection
+- 🧠 **Version-aware** — Modern (2016+), Legacy (2008–2014), and Azure SQL strategies
+- 📦 **Two output modes**:
+  - `"dynamic"` — `create_model()` at runtime, usable immediately
+  - `"source"` — `.py` files you can commit and review
+- 🏷️ **Full type mapping** — `INT`→`int`, `VARCHAR`→`str`, `DATETIME`→`datetime`, `BIT`→`bool`, etc.
+- 🎨 **Configurable naming** — snake_case, camelCase, PascalCase for field names
+- 🗂️ **File naming templates** — `{schema}_{sp_name}.py`, `{database}_{sp_name}.py`, etc.
+- 🛡️ **Nullable awareness** — `Optional[T]` for nullable columns
+- ⚡ **UV-first** — fast dependency management
+
+## Installation
+
+```bash
+uv add singularity
+# or
+pip install singularity
+```
+
+**Prerequisite**: [ODBC Driver for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server) (17 or 18).
+
+## Quick Start
+
+### 1. Create a config file
+
+```toml
+# config.toml
+[connection]
+server = "localhost"
+database = "AdventureWorks"
+driver = "ODBC Driver 18 for SQL Server"
+trusted_connection = true
+
+[sp_selection]
+pattern = "usp_%"
+
+[output]
+directory = "generated_models"
+mode = "source"
+file_naming = "{schema}_{sp_name}.py"
+naming_convention = "snake_case"
+```
+
+### 2. Generate models
+
+```bash
+singularity --config config.toml
+```
+
+```
+Connected. Detected version: modern
+  Introspecting usp_GetOrders... → generated_models/dbo_usp_GetOrders.py
+  Introspecting usp_GetCustomers... → generated_models/dbo_usp_GetCustomers.py
+
+Done. 2 succeeded, 0 failed.
+```
+
+### 3. Use the generated models
+
+```python
+from generated_models.dbo_usp_GetOrders import UspGetOrders
+
+order = UspGetOrders(id=1, customer_name="Acme Corp", total=99.99)
+```
+
+## Library Usage
+
+```python
+from singularity import SQLServerIntrospector, generate_model
+
+# Connect and introspect
+introspector = SQLServerIntrospector(conn_str)
+introspector.connect()
+version = introspector.detect_version()  # ServerVersion.MODERN
+metadata = introspector.introspect("usp_GetOrders")
+
+# Runtime model
+DynamicModel = generate_model(metadata, mode="dynamic")
+instance = DynamicModel(id=1, customer_name="Acme")
+
+# Source code string
+source_code = generate_model(metadata, mode="source")
+with open("models/usp_GetOrders.py", "w") as f:
+    f.write(source_code)
+```
+
+## Configuration Reference
+
+### `[connection]`
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `server` | ✅ | — | Server hostname or IP |
+| `database` | ✅ | — | Database name |
+| `driver` | ❌ | `ODBC Driver 18 for SQL Server` | ODBC driver name |
+| `trusted_connection` | ❌ | `true` | Use Windows auth |
+| `username` | ❌ | — | SQL auth username |
+| `password` | ❌ | — | SQL auth password |
+
+### `[sp_selection]`
+
+| Field | Required | Description |
+|---|---|---|
+| `procedures` | ❌ | Explicit list of SP names |
+| `pattern` | ❌ | Wildcard pattern (e.g. `usp_%`) |
+
+At least one of `procedures` or `pattern` must be specified.
+
+### `[output]`
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `directory` | ❌ | `.` | Output directory |
+| `mode` | ❌ | `source` | `source` or `dynamic` |
+| `file_naming` | ❌ | `{sp_name}.py` | Template with `{schema}`, `{database}`, `{sp_name}` |
+| `naming_convention` | ❌ | `snake_case` | `snake_case`, `camelCase`, or `PascalCase` |
+
+## Supported SQL Server Versions
+
+| Version | Strategy | Parameter introspection | Result set metadata |
+|---|---|---|---|
+| 2016+ | Modern | `sys.parameters` | `sp_describe_first_result_set` |
+| 2008–2014 | Legacy | `sys.parameters` | `sp_describe_first_result_set` + `sys.columns` fallback |
+| Azure SQL | Azure | `sys.parameters` | `sys.dm_exec_describe_first_result_set` |
+
+## Type Mapping
+
+| SQL Server | Python | Pydantic |
+|---|---|---|
+| `INT`, `BIGINT`, `SMALLINT`, `TINYINT` | `int` | `int` |
+| `VARCHAR`, `NVARCHAR`, `CHAR`, `NCHAR`, `TEXT` | `str` | `str` |
+| `DATETIME`, `DATETIME2`, `DATE`, `SMALLDATETIME` | `datetime` | `datetime` |
+| `BIT` | `bool` | `bool` |
+| `DECIMAL`, `NUMERIC`, `FLOAT`, `REAL`, `MONEY` | `float` | `float` |
+| `UNIQUEIDENTIFIER` | `str` | `str` |
+| Unknown types | `str` + warning | `str` |
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/Samuel-Urrego/Singularity
+cd singularity
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and type-check
+uv run ruff check .
+uv run mypy singularity/
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

singularitysql-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "singularitysql"
+version = "0.1.0"
+description = "SQL Server stored procedure introspection and Pydantic model generator"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Samuel Urrego" },
+]
+
+dependencies = [
+    "pyodbc>=5.0",
+    "pydantic>=2.0",
+    "typer>=0.9",
+    "tomli>=2.0",
+    "rich>=15.0.0",
+]
+
+[project.scripts]
+singularity = "singularity.cli._app:_main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-mock>=3.14",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: marks tests that require a real SQL Server database (deselect with '-m \"not integration\"')",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+exclude = ["assets", "assets.*", "tests", "tests.*", "generated_models", "docs"]

singularitysql-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

singularitysql-0.1.0/singularity/__init__.py

@@ -0,0 +1,18 @@
+"""Singularity — SQL Server stored procedure introspection and Pydantic model generation."""
+
+from singularity.exceptions import SingularityError, SpNotFoundError
+from singularity.introspector import SQLServerIntrospector
+from singularity.model_generator import generate_model
+from singularity.types import ColumnInfo, Parameter, SPMetadata
+from singularity.version import ServerVersion
+
+__all__ = [
+    "SQLServerIntrospector",
+    "generate_model",
+    "SPMetadata",
+    "ColumnInfo",
+    "Parameter",
+    "ServerVersion",
+    "SingularityError",
+    "SpNotFoundError",
+]

singularitysql-0.1.0/singularity/cli/__init__.py

@@ -0,0 +1,8 @@
+"""Singularity CLI — Typer app and commands."""
+
+from singularity.cli._app import _main, app
+
+__all__ = ["app", "main"]
+
+# main is an alias for _main for entry point consistency
+main = _main

singularitysql-0.1.0/singularity/cli/_app.py

@@ -0,0 +1,25 @@
+"""Singularity Typer app instance — isolated to avoid circular imports."""
+
+import sys
+
+import typer
+
+
+def _main() -> None:
+    """Entry point with UTF-8 encoding support for Windows consoles."""
+    if sys.platform == "win32":
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    app()
+
+
+app = typer.Typer(
+    name="singularity",
+    help="SQL Server stored procedure introspection and Pydantic model generator.",
+    no_args_is_help=True,
+    invoke_without_command=True,
+)
+
+# Register commands — import triggers @app.command() decorators
+import singularity.cli.docs_generate  # noqa: E402, F401 — registers docs command
+import singularity.cli.generate  # noqa: E402, F401 — registers generate command

singularitysql-0.1.0/singularity/cli/config.py

@@ -0,0 +1,142 @@
+"""TOML configuration loading and Pydantic config models."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, field_validator
+
+
+class ConnectionConfig(BaseModel):
+    """SQL Server connection settings."""
+
+    server: str
+    """Server hostname or IP address (required)."""
+
+    database: str
+    """Database name (required)."""
+
+    driver: str = "ODBC Driver 18 for SQL Server"
+    """ODBC driver name."""
+
+    trusted_connection: bool = True
+    """Use Windows Authentication when True."""
+
+    username: str | None = None
+    """SQL Server login username (used when trusted_connection is False)."""
+
+    password: str | None = None
+    """SQL Server login password (used when trusted_connection is False)."""
+
+    def build_connection_string(self) -> str:
+        """Build a pyodbc-compatible connection string from the config.
+
+        Returns:
+            A DRIVER=SERVER=DATABASE=... connection string.
+        """
+        parts = [
+            f"DRIVER={{{self.driver}}}",
+            f"SERVER={self.server}",
+            f"DATABASE={self.database}",
+        ]
+        if self.trusted_connection:
+            parts.append("Trusted_Connection=yes")
+        else:
+            if self.username:
+                parts.append(f"UID={self.username}")
+            if self.password:
+                parts.append(f"PWD={self.password}")
+        return ";".join(parts)
+
+
+class SpSelectionConfig(BaseModel):
+    """Stored procedure selection criteria."""
+
+    procedures: list[str] | None = None
+    """Explicit list of stored procedure names to introspect."""
+
+    pattern: str | None = None
+    """Wildcard pattern (e.g. 'usp_%') to resolve against the database."""
+
+    @field_validator("procedures", "pattern")
+    @classmethod
+    def _at_least_one(cls, v: list[str] | str | None) -> list[str] | str | None:
+        return v
+
+
+class OutputConfig(BaseModel):
+    """Output preferences for generated models."""
+
+    directory: str = "."
+    """Output directory for generated files."""
+
+    mode: Literal["dynamic", "source"] = "source"
+    """Generation mode: 'dynamic' for runtime models, 'source' for .py files."""
+
+    file_naming: str = "{sp_name}.py"
+    """File naming template with {sp_name}, {schema}, {database} variables."""
+
+    naming_convention: Literal["snake_case", "camelCase", "PascalCase"] = "snake_case"
+    """Field naming convention for generated models."""
+
+    docs_directory: str | None = None
+    """Output directory for generated Markdown documentation.
+    If set, ``singularity docs`` writes docs here. Defaults to ``docs/``."""
+
+    @field_validator("mode")
+    @classmethod
+    def _validate_mode(cls, v: str) -> str:
+        allowed = {"dynamic", "source"}
+        if v not in allowed:
+            raise ValueError(f"mode must be one of {allowed}, got '{v}'")
+        return v
+
+    @field_validator("naming_convention")
+    @classmethod
+    def _validate_convention(cls, v: str) -> str:
+        allowed = {"snake_case", "camelCase", "PascalCase"}
+        if v not in allowed:
+            raise ValueError(
+                f"naming_convention must be one of {allowed}, got '{v}'"
+            )
+        return v
+
+
+class SingularityConfig(BaseModel):
+    """Top-level configuration model."""
+
+    connection: ConnectionConfig
+    """SQL Server connection settings."""
+
+    sp_selection: SpSelectionConfig
+    """Stored procedure selection criteria."""
+
+    output: OutputConfig = OutputConfig()
+    """Output preferences (defaults apply if section omitted)."""
+
+
+def load_config(path: str | Path) -> SingularityConfig:
+    """Load and validate a TOML configuration file.
+
+    Args:
+        path: Path to the TOML config file.
+
+    Returns:
+        A validated SingularityConfig instance.
+
+    Raises:
+        FileNotFoundError: If the config file does not exist.
+        pydantic.ValidationError: If the config is invalid.
+    """
+    import tomli
+
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    raw = path.read_text(encoding="utf-8")
+    data = tomli.loads(raw)
+
+    return SingularityConfig(**data)