dscompanion 0.1.0__tar.gz

dscompanion-0.1.0/LICENSE

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

dscompanion-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: dscompanion
+Version: 0.1.0
+Summary: A production-grade ML pipeline toolkit: EDA, feature engineering, model training/tuning/calibration, and governance-ready model cards.
+Author-email: dsnaveen <mailtonaveenmittal@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/dsnaveen/dscompanion
+Project-URL: Repository, https://github.com/dsnaveen/dscompanion
+Project-URL: Issues, https://github.com/dsnaveen/dscompanion/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: numpy<2.4,>=2.1
+Requires-Dist: scikit-learn<2,>=1.7
+Requires-Dist: scipy<2,>=1.16
+Requires-Dist: statsmodels<0.15,>=0.14
+Requires-Dist: joblib<2,>=1.4
+Requires-Dist: plotly<6,>=5.20
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: pydantic<2.11,>=2.10
+Requires-Dist: pydantic-settings<3,>=2.10
+Requires-Dist: matplotlib<4,>=3.9
+Requires-Dist: seaborn<0.14,>=0.13
+Requires-Dist: xgboost<4,>=3.0
+Requires-Dist: optuna<4,>=3.6
+Requires-Dist: shap<0.52,>=0.44
+Requires-Dist: python-docx<2,>=1.1
+Requires-Dist: xlsxwriter<4,>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: black==24.10.0; extra == "dev"
+Requires-Dist: ruff==0.15.16; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Provides-Extra: databricks
+Requires-Dist: pyspark==4.0.0; extra == "databricks"
+Requires-Dist: databricks-sdk>=0.20; extra == "databricks"
+Provides-Extra: docs
+Requires-Dist: sphinx>=9.0; extra == "docs"
+Requires-Dist: furo>=2025.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=3.0; extra == "docs"
+Requires-Dist: myst-parser>=5.0; extra == "docs"
+Provides-Extra: app
+Requires-Dist: streamlit==1.59.1; extra == "app"
+Requires-Dist: openpyxl>=3.1; extra == "app"
+Provides-Extra: api
+Requires-Dist: fastapi==0.117.1; extra == "api"
+Requires-Dist: uvicorn==0.37.0; extra == "api"
+Provides-Extra: models
+Requires-Dist: lightgbm==4.6.0; extra == "models"
+Dynamic: license-file
+
+# dscompanion
+
+A production-grade ML pipeline toolkit for tabular data: EDA, feature engineering, model
+training/tuning/calibration, and governance-ready model cards — with sensible defaults
+everywhere and full override capability. Designed to work well in regulated or restricted
+environments (see [Architecture](docs/architecture.rst) for the constraints that shaped it),
+but useful for any tabular ML project.
+
+## Installation
+
+```bash
+pip install dscompanion
+```
+
+For local development:
+
+```bash
+git clone https://github.com/dsnaveen/dscompanion.git
+cd dscompanion
+pip install -e ".[dev]"
+```
+
+**One thing worth knowing about SHAP:** `ExplainConfig.shap_enabled` defaults to `False` —
+SHAP computation is relatively expensive, so it's opt-in rather than run automatically. See
+`explain.permutation_enabled` for a lighter-weight, model-agnostic alternative.
+
+**Run tracking via stdlib logging** — dscompanion logs pipeline execution (run start/finish,
+training metrics, parameters, artifacts) via Python's `logging` module, not a dedicated
+tracking server. A `dscompanion.tracking.run_context.tracking_run()` context manager handles
+this transparently during pipeline execution. If you need queryable run history or a tracking
+server UI, you'll need a separate mechanism outside dscompanion — it provides only local
+structured logs by default.
+
+## Quickstart
+
+```python
+from dscompanion.pipeline import PipelineConfig, PipelineRunner
+
+cfg = PipelineConfig(
+    name="my_first_model",
+    data={"path": "data.parquet", "target": "target_column"},
+    split={"method": "stratified", "test_size": 0.2, "val_size": 0.1},
+    model={"task": "classification", "algorithm": "xgboost"},
+    reporting={"output_dir": "outputs", "html_report": True},
+)
+result = PipelineRunner(cfg).run()
+
+print(result.metrics)                 # per-split evaluation metrics
+print(result.model_card.to_excel(...))  # governance-ready model card
+```
+
+`PipelineRunner` runs the full pipeline end-to-end — load, split, EDA, feature processing,
+selection, imbalance handling, train (or leaderboard comparison), tune, calibrate, explain,
+and report — with every stage overridable through `PipelineConfig`. See
+[`docs/pipeline.rst`](docs/pipeline.rst) for the full stage-by-stage reference and
+[`docs/quickstart.rst`](docs/quickstart.rst) for more examples.
+
+## Package Structure
+
+```
+src/dscompanion/
+├── config.py                  # DSCompanionConfig settings (pydantic-settings, env_prefix=DSCOMPANION_)
+├── pipeline/                  # PipelineConfig, PipelineRunner — the end-to-end orchestrator
+├── split/                     # DataSplitter — temporal, stratified, grouped, random
+├── eda/                       # UnivariateAnalyser, BivariateAnalyser, MultivariateAnalyser, EDAReport
+├── features/                  # SmartImputer, encoders, SmartScaler, AutoBinner,
+│                              #   DateFeatureExtractor, LeakageGuard, FeatureProcessingPipeline
+├── targets/                   # ImbalanceHandler (SMOTE/class_weight), TargetBinariser
+├── selection/                 # ConstantSelector, CorrelationSelector, IVSelector,
+│                              #   FeatureSelectionPipeline
+├── models/                    # ModelFactory, ClassificationModel, RegressionModel, ClusteringModel
+├── tuning/                    # Tuner, OptunaBackend, HyperoptBackend, search_spaces
+├── leaderboard/                # Leaderboard — multi-algorithm comparison
+├── explain/                   # SHAPExplainer, PermutationImportanceAnalyser
+├── calibration/                # Calibrator (isotonic, Platt, beta)
+├── docs/                      # ModelCard, HTML report generators (EDA/model cards, widgets)
+├── tracking/                   # tracking_run context manager, log_metrics/params/artifact via stdlib logging
+├── api/                       # optional FastAPI service (pip install dscompanion[api])
+└── utils/                     # metrics (KS, Gini, PSI, IV, WoE, ECE), validators, plotting
+```
+
+A Streamlit UI lives at [`app/`](app/) (`pip install dscompanion[app]`, then
+`streamlit run app/streamlit_app.py`) for interactively driving a pipeline run without
+writing config by hand.
+
+## Configuration
+
+All thresholds and defaults are controlled via `dscompanion.config.settings`. Override with environment
+variables prefixed `DSCOMPANION_`:
+
+```bash
+export DSCOMPANION_TARGET_LEAKAGE_CORRELATION_THRESHOLD=0.90
+export DSCOMPANION_HIGH_CARDINALITY_THRESHOLD=30
+export DSCOMPANION_RANDOM_STATE=0
+```
+
+Or in code:
+
+```python
+from dscompanion.config import settings
+settings.high_cardinality_threshold = 30
+```
+
+## Running Tests
+
+```bash
+git clone https://github.com/dsnaveen/dscompanion.git
+cd dscompanion
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Key Design Principles
+
+- **sklearn-compatible** — all transformers implement `fit` / `transform` / `get_feature_names_out`
+- **joblib-serialisable** — every fitted object can be pickled with `joblib.dump`
+- **Structured logging via stdlib** — all pipeline execution logs through Python's `logging` module
+- **pydantic v2** — config and report models use `BaseModel` / `BaseSettings`
+- **No hidden network calls** — works fully offline once installed, suited to restricted environments
+
+## Dependencies
+
+Core: `pandas`, `numpy`, `scikit-learn`, `xgboost`, `pydantic-settings`, `joblib`, `plotly`, `jinja2`
+
+Optional: `optuna`, `shap`, `python-docx` (core extras); `streamlit` (`[app]`); `fastapi`,
+`uvicorn` (`[api]`); `sphinx` (`[docs]`)
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

dscompanion-0.1.0/README.md

@@ -0,0 +1,134 @@
+# dscompanion
+
+A production-grade ML pipeline toolkit for tabular data: EDA, feature engineering, model
+training/tuning/calibration, and governance-ready model cards — with sensible defaults
+everywhere and full override capability. Designed to work well in regulated or restricted
+environments (see [Architecture](docs/architecture.rst) for the constraints that shaped it),
+but useful for any tabular ML project.
+
+## Installation
+
+```bash
+pip install dscompanion
+```
+
+For local development:
+
+```bash
+git clone https://github.com/dsnaveen/dscompanion.git
+cd dscompanion
+pip install -e ".[dev]"
+```
+
+**One thing worth knowing about SHAP:** `ExplainConfig.shap_enabled` defaults to `False` —
+SHAP computation is relatively expensive, so it's opt-in rather than run automatically. See
+`explain.permutation_enabled` for a lighter-weight, model-agnostic alternative.
+
+**Run tracking via stdlib logging** — dscompanion logs pipeline execution (run start/finish,
+training metrics, parameters, artifacts) via Python's `logging` module, not a dedicated
+tracking server. A `dscompanion.tracking.run_context.tracking_run()` context manager handles
+this transparently during pipeline execution. If you need queryable run history or a tracking
+server UI, you'll need a separate mechanism outside dscompanion — it provides only local
+structured logs by default.
+
+## Quickstart
+
+```python
+from dscompanion.pipeline import PipelineConfig, PipelineRunner
+
+cfg = PipelineConfig(
+    name="my_first_model",
+    data={"path": "data.parquet", "target": "target_column"},
+    split={"method": "stratified", "test_size": 0.2, "val_size": 0.1},
+    model={"task": "classification", "algorithm": "xgboost"},
+    reporting={"output_dir": "outputs", "html_report": True},
+)
+result = PipelineRunner(cfg).run()
+
+print(result.metrics)                 # per-split evaluation metrics
+print(result.model_card.to_excel(...))  # governance-ready model card
+```
+
+`PipelineRunner` runs the full pipeline end-to-end — load, split, EDA, feature processing,
+selection, imbalance handling, train (or leaderboard comparison), tune, calibrate, explain,
+and report — with every stage overridable through `PipelineConfig`. See
+[`docs/pipeline.rst`](docs/pipeline.rst) for the full stage-by-stage reference and
+[`docs/quickstart.rst`](docs/quickstart.rst) for more examples.
+
+## Package Structure
+
+```
+src/dscompanion/
+├── config.py                  # DSCompanionConfig settings (pydantic-settings, env_prefix=DSCOMPANION_)
+├── pipeline/                  # PipelineConfig, PipelineRunner — the end-to-end orchestrator
+├── split/                     # DataSplitter — temporal, stratified, grouped, random
+├── eda/                       # UnivariateAnalyser, BivariateAnalyser, MultivariateAnalyser, EDAReport
+├── features/                  # SmartImputer, encoders, SmartScaler, AutoBinner,
+│                              #   DateFeatureExtractor, LeakageGuard, FeatureProcessingPipeline
+├── targets/                   # ImbalanceHandler (SMOTE/class_weight), TargetBinariser
+├── selection/                 # ConstantSelector, CorrelationSelector, IVSelector,
+│                              #   FeatureSelectionPipeline
+├── models/                    # ModelFactory, ClassificationModel, RegressionModel, ClusteringModel
+├── tuning/                    # Tuner, OptunaBackend, HyperoptBackend, search_spaces
+├── leaderboard/                # Leaderboard — multi-algorithm comparison
+├── explain/                   # SHAPExplainer, PermutationImportanceAnalyser
+├── calibration/                # Calibrator (isotonic, Platt, beta)
+├── docs/                      # ModelCard, HTML report generators (EDA/model cards, widgets)
+├── tracking/                   # tracking_run context manager, log_metrics/params/artifact via stdlib logging
+├── api/                       # optional FastAPI service (pip install dscompanion[api])
+└── utils/                     # metrics (KS, Gini, PSI, IV, WoE, ECE), validators, plotting
+```
+
+A Streamlit UI lives at [`app/`](app/) (`pip install dscompanion[app]`, then
+`streamlit run app/streamlit_app.py`) for interactively driving a pipeline run without
+writing config by hand.
+
+## Configuration
+
+All thresholds and defaults are controlled via `dscompanion.config.settings`. Override with environment
+variables prefixed `DSCOMPANION_`:
+
+```bash
+export DSCOMPANION_TARGET_LEAKAGE_CORRELATION_THRESHOLD=0.90
+export DSCOMPANION_HIGH_CARDINALITY_THRESHOLD=30
+export DSCOMPANION_RANDOM_STATE=0
+```
+
+Or in code:
+
+```python
+from dscompanion.config import settings
+settings.high_cardinality_threshold = 30
+```
+
+## Running Tests
+
+```bash
+git clone https://github.com/dsnaveen/dscompanion.git
+cd dscompanion
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Key Design Principles
+
+- **sklearn-compatible** — all transformers implement `fit` / `transform` / `get_feature_names_out`
+- **joblib-serialisable** — every fitted object can be pickled with `joblib.dump`
+- **Structured logging via stdlib** — all pipeline execution logs through Python's `logging` module
+- **pydantic v2** — config and report models use `BaseModel` / `BaseSettings`
+- **No hidden network calls** — works fully offline once installed, suited to restricted environments
+
+## Dependencies
+
+Core: `pandas`, `numpy`, `scikit-learn`, `xgboost`, `pydantic-settings`, `joblib`, `plotly`, `jinja2`
+
+Optional: `optuna`, `shap`, `python-docx` (core extras); `streamlit` (`[app]`); `fastapi`,
+`uvicorn` (`[api]`); `sphinx` (`[docs]`)
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

dscompanion-0.1.0/pyproject.toml

@@ -0,0 +1,113 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dscompanion"
+version = "0.1.0"
+description = "A production-grade ML pipeline toolkit: EDA, feature engineering, model training/tuning/calibration, and governance-ready model cards."
+readme = "README.md"
+authors = [{ name = "dsnaveen", email = "mailtonaveenmittal@gmail.com" }]
+license = { text = "MIT" }
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pandas>=2.2,<3",          # pandas 2.x — does not default to Copy-on-Write
+    "numpy>=2.1,<2.4",         # upper-bounded for numba (a shap dependency) compatibility
+    "scikit-learn>=1.7,<2",
+    "scipy>=1.16,<2",
+    "statsmodels>=0.14,<0.15",
+    "joblib>=1.4,<2",
+    "plotly>=5.20,<6",
+    "jinja2>=3.1,<4",
+    "pyyaml>=6.0,<7",
+    "pydantic>=2.10,<2.11",    # v2 native — BaseSettings lives in pydantic-settings.
+                               # Narrowly bounded (not just <3): pydantic's generated JSON
+                               # schema shape has changed across minor versions before, and
+                               # api/openapi.json is committed and snapshot-tested against it.
+    "pydantic-settings>=2.10,<3",
+    "matplotlib>=3.9,<4",
+    "seaborn>=0.13,<0.14",
+    "xgboost>=3.0,<4",         # macOS dev requires Homebrew libomp (conda-forge llvm-openmp)
+    "optuna>=3.6,<4",
+    "shap>=0.44,<0.52",        # pre-0.52 API — shap_explainer.py returns list-of-arrays branch;
+                               # shap 0.52.0+ returns a 3-D ndarray instead
+    # imbalanced-learn is intentionally not a dependency — ImbalanceHandler's smote/undersample
+    # strategies are implemented from scratch on scikit-learn's NearestNeighbors alone, since
+    # imbalanced-learn has a history of version conflicts with recent scikit-learn releases.
+    "python-docx>=1.1,<2",
+    "xlsxwriter>=3.2,<4",      # engine for ModelCard.to_excel()
+]
+
+[project.urls]
+Homepage = "https://github.com/dsnaveen/dscompanion"
+Repository = "https://github.com/dsnaveen/dscompanion"
+Issues = "https://github.com/dsnaveen/dscompanion/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=4.1", "black==24.10.0", "ruff==0.15.16", "httpx>=0.27"]
+databricks = ["pyspark==4.0.0", "databricks-sdk>=0.20"]
+# Doc build tooling only — never imported by dscompanion's runtime code.
+docs = ["sphinx>=9.0", "furo>=2025.0", "sphinx-autodoc-typehints>=3.0", "myst-parser>=5.0"]
+# Local-dev UI only — drives PipelineRunner from a browser on a dev machine against
+# local data. app/ is never imported by dscompanion's runtime code, so this
+# extra is optional even for full local development.
+app = ["streamlit==1.59.1", "openpyxl>=3.1"]
+# Optional FastAPI service exposing PipelineRunner over HTTP, for a web-based
+# frontend. Not required for using dscompanion as a library.
+api = ["fastapi==0.117.1", "uvicorn==0.37.0"]
+# Optional gradient-boosting backend for ModelFactory's "lightgbm" algorithm choice —
+# not required unless that specific algorithm is selected.
+models = ["lightgbm==4.6.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["dscompanion*"]
+
+[tool.black]
+line-length = 100
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "F",      # pyflakes (F401 = unused imports, F403 = wildcard imports)
+    "W",      # pycodestyle warnings
+    "I",      # isort import order
+    "UP006",  # List[X] → list[X]
+    "UP007",  # Optional[X] → X | None
+    "UP035",  # deprecated typing imports
+    "T201",   # print() call
+    "F403",   # wildcard imports
+    "RUF100", # unused noqa directives
+]
+ignore = [
+    # This project requires `logger = logging.getLogger(__name__)` immediately
+    # after `import logging`, before all third-party imports — E402 flags exactly
+    # that placement as "import not at top of file". The convention is correct
+    # and deliberate, so this rule is disabled project-wide.
+    "E402",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Not pytest-collected — a manual, human-run CLI script (see its own docstring).
+# print() is the actual intended output mechanism here, not a logging omission.
+"tests/manual_verify_interactive_flow.py" = ["T201"]
+"tests/manual_verify_leaderboard_tuning.py" = ["T201"]
+"tests/manual_verify_environment.py" = ["T201"]
+
+[tool.mypy]
+# Placeholder — strict type-checking disabled for now; enable incrementally
+ignore_errors = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=dscompanion --cov-report=term-missing --cov-fail-under=80"

dscompanion-0.1.0/setup.cfg

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

dscompanion-0.1.0/src/dscompanion/__init__.py

@@ -0,0 +1,67 @@
+"""dscompanion — production-grade ML toolkit for financial modelling."""
+
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s  %(name)s  %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+from dscompanion.calibration import Calibrator
+from dscompanion.config import settings
+from dscompanion.docs import ModelCard
+from dscompanion.eda import EDAReport
+from dscompanion.explain import BootstrapSHAPExplainer, LIMEExplainer, SHAPExplainer
+from dscompanion.features import FeatureProcessingPipeline
+from dscompanion.leaderboard import Leaderboard
+from dscompanion.models import ModelFactory
+from dscompanion.pipeline import PipelineConfig, PipelineRunner, PipelineRunResult
+from dscompanion.selection import FeatureSelectionPipeline
+from dscompanion.split import DataSplit, DataSplitter
+from dscompanion.targets import ImbalanceHandler, TargetBinariser
+from dscompanion.tracking import tracking_run
+from dscompanion.tuning import Tuner
+from dscompanion.utils.synthetic import SyntheticDataGenerator
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Split
+    "DataSplitter",
+    "DataSplit",
+    # EDA
+    "EDAReport",
+    # Features
+    "FeatureProcessingPipeline",
+    # Targets
+    "ImbalanceHandler",
+    "TargetBinariser",
+    # Selection
+    "FeatureSelectionPipeline",
+    # Models
+    "ModelFactory",
+    # Leaderboard
+    "Leaderboard",
+    # Tuning
+    "Tuner",
+    # Explainability
+    "SHAPExplainer",
+    "BootstrapSHAPExplainer",
+    "LIMEExplainer",
+    # Calibration
+    "Calibrator",
+    # Docs
+    "ModelCard",
+    # Tracking
+    "tracking_run",
+    # Config
+    "settings",
+    # Pipeline
+    "PipelineConfig",
+    "PipelineRunner",
+    "PipelineRunResult",
+    # Utils
+    "SyntheticDataGenerator",
+]

dscompanion-0.1.0/src/dscompanion/api/__init__.py

@@ -0,0 +1,6 @@
+"""FastAPI service wrapping dscompanion for a web frontend.
+
+An optional extra (``pip install dscompanion[api]``), kept separate from the
+core library so the core has no FastAPI/web-framework dependency — mirrors
+``app/``'s relationship to the core package.
+"""

dscompanion-0.1.0/src/dscompanion/api/auth/__init__.py

@@ -0,0 +1,65 @@
+"""dscompanion.api.auth — pluggable auth backends, dispatched by APISettings.auth_backend."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["get_auth_backend", "AuthResult"]
+
+
+class AuthResult:
+    """Outcome of an auth check.
+
+    Args:
+        authenticated (bool): Whether the request is allowed through.
+        principal (str | None): Identifier for who/what made the request (e.g. the
+            API key's label, or an OAuth subject claim). ``None`` when
+            ``authenticated=False``.
+
+    Returns:
+        AuthResult: A simple, backend-agnostic result every auth module returns,
+        so ``deps.py`` never has to know which backend produced it.
+    """
+
+    def __init__(self, authenticated: bool, principal: str | None = None) -> None:
+        self.authenticated = authenticated
+        self.principal = principal
+
+
+def get_auth_backend():
+    """Returns the auth-check callable for the currently configured backend,
+    dispatched by ``api_settings.auth_backend`` exactly like ``Tuner.backend``
+    dispatches to ``OptunaBackend``/``HyperoptBackend`` — a plain string setting
+    plus a lazy import per branch, no abstract base class.
+
+    Args:
+        None
+
+    Returns:
+        Callable[[str | None], AuthResult]: A function taking the raw credential
+        (e.g. the ``X-API-Key`` header value) and returning an ``AuthResult``.
+
+    Raises:
+        ValueError: If ``api_settings.auth_backend`` is not a recognised value.
+    """
+    from dscompanion.api.config import api_settings
+
+    if api_settings.auth_backend == "api_key":
+        from dscompanion.api.auth.api_key import check_api_key
+
+        return check_api_key
+    elif api_settings.auth_backend == "databricks_oauth":
+        from dscompanion.api.auth.databricks_oauth import check_databricks_oauth
+
+        return check_databricks_oauth
+    elif api_settings.auth_backend == "azure_entra":
+        from dscompanion.api.auth.azure_entra import check_azure_entra
+
+        return check_azure_entra
+    else:
+        raise ValueError(
+            f"Unknown auth_backend: {api_settings.auth_backend!r}. "
+            "Choose api_key/databricks_oauth/azure_entra."
+        )

dscompanion-0.1.0/src/dscompanion/api/auth/api_key.py

@@ -0,0 +1,40 @@
+"""api_key auth backend — local-dev stub, checked against APISettings.api_key."""
+
+from __future__ import annotations
+
+import logging
+
+from dscompanion.api.auth import AuthResult
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["check_api_key"]
+
+
+def check_api_key(credential: str | None) -> AuthResult:
+    """Checks ``credential`` against ``api_settings.api_key``.
+
+    Local-dev only — needed regardless of eventual deployment target, easy to
+    upgrade later. Real auth (SSO/Entra, Databricks OAuth) is deferred until
+    that deployment channel is actually pursued.
+
+    Args:
+        credential (str | None): The raw ``X-API-Key`` header value, or ``None``
+            if the header was absent.
+
+    Returns:
+        AuthResult: ``authenticated=True`` when ``api_settings.api_key`` is
+        ``None`` (auth disabled — local dev only) or when ``credential`` matches
+        it exactly; ``authenticated=False`` otherwise.
+    """
+    from dscompanion.api.config import api_settings
+
+    if api_settings.api_key is None:
+        logger.debug("api_key auth: no key configured, allowing all requests (local dev only)")
+        return AuthResult(authenticated=True, principal="local-dev")
+
+    if credential == api_settings.api_key:
+        return AuthResult(authenticated=True, principal="api-key-user")
+
+    logger.warning("api_key auth: rejected request with invalid or missing credential")
+    return AuthResult(authenticated=False, principal=None)

dscompanion-0.1.0/src/dscompanion/api/auth/azure_entra.py

@@ -0,0 +1,31 @@
+"""azure_entra auth backend — stub only, not built.
+
+Same treatment as databricks_oauth.py: this file exists so the seam is ready,
+not implemented until the Azure channel is
+actually pursued. Would lazy-import azure-identity
+inside the function body when implemented, never at module level.
+"""
+
+from __future__ import annotations
+
+from dscompanion.api.auth import AuthResult
+
+__all__ = ["check_azure_entra"]
+
+
+def check_azure_entra(credential: str | None) -> AuthResult:
+    """Not implemented — see module docstring.
+
+    Args:
+        credential (str | None): The raw bearer token, once implemented.
+
+    Returns:
+        AuthResult: Never returns.
+
+    Raises:
+        NotImplementedError: Always — this backend has no implementation yet.
+    """
+    raise NotImplementedError(
+        "auth_backend='azure_entra' is not built yet. "
+        "Use 'api_key' (the default) until the Azure channel is actually pursued."
+    )