deep-learning-core 0.0.1__tar.gz

deep_learning_core-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: Validate Package
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Create virtual environment
+        run: uv venv
+
+      - name: Install test dependencies
+        run: |
+          python3 - <<'PY'
+          from pathlib import Path
+          import tomllib
+
+          pyproject = tomllib.loads(Path("pyproject.toml").read_text())
+          dependencies = pyproject["project"]["dependencies"]
+          dev_dependencies = pyproject["project"]["optional-dependencies"]["dev"]
+          Path("requirements-ci.txt").write_text(
+              "\n".join([*dependencies, *dev_dependencies, "twine"]) + "\n",
+              encoding="utf-8",
+          )
+          PY
+          uv pip install --python .venv/bin/python -r requirements-ci.txt
+          uv pip install --python .venv/bin/python --no-deps --editable .
+
+      - name: Run tests
+        run: VIRTUAL_ENV="$PWD/.venv" PATH="$PWD/.venv/bin:$PATH" .venv/bin/python -m pytest
+
+      - name: Compile package
+        run: .venv/bin/python -m compileall src/dl_core
+
+      - name: Build distribution artifacts
+        run: uv build --no-sources
+
+      - name: Check distribution metadata
+        run: .venv/bin/python -m twine check dist/*

deep_learning_core-0.0.1/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,92 @@
+name: Publish TestPyPI
+# TestPyPI setup required before first use:
+# 1. Create the `deep-learning-core` project on TestPyPI.
+# 2. Add a Trusted Publisher for:
+#    - owner: Blazkowiz47
+#    - repository: dl-core
+#    - workflow: publish-testpypi.yml
+#    - environment: dl-core
+# 3. Create the `dl-core` GitHub environment if you want approval gates.
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Create virtual environment
+        run: uv venv
+
+      - name: Install test dependencies
+        run: |
+          python3 - <<'PY'
+          from pathlib import Path
+          import tomllib
+
+          pyproject = tomllib.loads(Path("pyproject.toml").read_text())
+          dependencies = pyproject["project"]["dependencies"]
+          dev_dependencies = pyproject["project"]["optional-dependencies"]["dev"]
+          Path("requirements-ci.txt").write_text(
+              "\n".join([*dependencies, *dev_dependencies, "twine"]) + "\n",
+              encoding="utf-8",
+          )
+          PY
+          uv pip install --python .venv/bin/python -r requirements-ci.txt
+          uv pip install --python .venv/bin/python --no-deps --editable .
+
+      - name: Run tests
+        run: VIRTUAL_ENV="$PWD/.venv" PATH="$PWD/.venv/bin:$PATH" .venv/bin/python -m pytest
+
+      - name: Build distribution artifacts
+        run: uv build --no-sources
+
+      - name: Check distribution metadata
+        run: .venv/bin/python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: python-package-distributions-testpypi
+          path: dist/
+
+  publish:
+    name: Publish To TestPyPI
+    runs-on: ubuntu-latest
+    needs:
+      - build
+    permissions:
+      id-token: write
+
+    environment:
+      name: dl-core
+      url: https://test.pypi.org/p/deep-learning-core
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions-testpypi
+          path: dist/
+
+      - name: Publish distribution to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          verbose: true

deep_learning_core-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,91 @@
+name: Publish
+# PyPI setup required before first use:
+# 1. Create the `deep-learning-core` project on PyPI.
+# 2. Add a Trusted Publisher for:
+#    - owner: Blazkowiz47
+#    - repository: dl-core
+#    - workflow: publish.yml
+#    - environment: dl-core
+# 3. Create the `dl-core` GitHub environment if you want approval gates.
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Create virtual environment
+        run: uv venv
+
+      - name: Install test dependencies
+        run: |
+          python3 - <<'PY'
+          from pathlib import Path
+          import tomllib
+
+          pyproject = tomllib.loads(Path("pyproject.toml").read_text())
+          dependencies = pyproject["project"]["dependencies"]
+          dev_dependencies = pyproject["project"]["optional-dependencies"]["dev"]
+          Path("requirements-ci.txt").write_text(
+              "\n".join([*dependencies, *dev_dependencies, "twine"]) + "\n",
+              encoding="utf-8",
+          )
+          PY
+          uv pip install --python .venv/bin/python -r requirements-ci.txt
+          uv pip install --python .venv/bin/python --no-deps --editable .
+
+      - name: Run tests
+        run: VIRTUAL_ENV="$PWD/.venv" PATH="$PWD/.venv/bin:$PATH" .venv/bin/python -m pytest
+
+      - name: Build distribution artifacts
+        run: uv build --no-sources
+
+      - name: Check distribution metadata
+        run: .venv/bin/python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish To PyPI
+    runs-on: ubuntu-latest
+    needs:
+      - build
+    permissions:
+      id-token: write
+
+    environment:
+      name: dl-core
+      url: https://pypi.org/p/deep-learning-core
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

deep_learning_core-0.0.1/.gitignore

@@ -0,0 +1,35 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+.tmp-ci-venv/
+
+# Test and coverage artifacts
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Type checker and linter caches
+.mypy_cache/
+.ruff_cache/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+pip-wheel-metadata/
+
+# Local experiment outputs
+artifacts/
+
+# Notebook and editor metadata
+.ipynb_checkpoints/
+.DS_Store
+.idea/
+.vscode/

deep_learning_core-0.0.1/AGENTS.md

@@ -0,0 +1,109 @@
+<agent_spec>
+  <title>dl-core Repository Guidelines</title>
+
+  <project_structure>
+    <rule>Repository root includes <code>.github/</code>, <code>src/</code>, <code>tests/</code>, <code>readme/</code>, <code>README.md</code>, <code>pyproject.toml</code>, and <code>uv.lock</code>.</rule>
+    <rule><code>src/dl_core/</code> stores the reusable framework package.</rule>
+    <rule><code>src/dl_core/core/</code> stores base abstractions and registries.</rule>
+    <rule><code>src/dl_core/templates/</code> stores bundled scaffold files copied into generated experiment repositories.</rule>
+    <rule><code>tests/</code> stores repository-level <code>pytest</code> coverage for scaffolding, CLI behavior, and local components.</rule>
+    <rule><code>readme/</code> stores extended user and technical documentation.</rule>
+    <rule><code>.github/workflows/</code> stores CI and publishing workflows.</rule>
+    <rule><code>dist/</code> contains generated build artifacts; treat it as output, not source.</rule>
+  </project_structure>
+
+  <command_policy>
+    <rule>Run commands from the repository root unless a narrower directory is clearly better for the task.</rule>
+    <rule>Prefer fast search commands: <code>rg</code>, <code>rg --files</code>.</rule>
+    <rule>Use non-destructive commands by default.</rule>
+    <rule>Prefer repository-standard <code>uv</code> commands for Python execution, validation, and build steps.</rule>
+    <rule>Standard validation commands are <code>uv run --extra dev pytest</code>, <code>uv run python -m compileall src/dl_core</code>, and <code>uv build --no-sources</code>.</rule>
+    <rule>Do not invent alternate environment-management flows when <code>uv</code> already covers the task.</rule>
+  </command_policy>
+
+  <development_rules>
+    <rule>Type hints are required for Python code.</rule>
+    <rule>Public modules, public APIs, and CLI entry points should include concise docstrings.</rule>
+    <rule>Match the existing style: 4-space indentation, <code>snake_case</code> functions and modules, <code>PascalCase</code> classes, and short module docstrings.</rule>
+    <rule>Use f-strings for string formatting.</rule>
+    <rule>Keep functions focused and avoid unnecessary nesting.</rule>
+    <rule>No formatter or linter configuration is defined in <code>pyproject.toml</code>; mirror nearby files instead of re-styling code arbitrarily.</rule>
+  </development_rules>
+
+  <architecture_rules>
+    <rule>Keep <code>dl-core</code> reusable and vendor-neutral; company-specific integrations belong outside the core package.</rule>
+    <rule>Preserve the registry-driven extension model in <code>src/dl_core/core/registry.py</code> and related package exports.</rule>
+    <rule>Keep scaffold logic in <code>src/dl_core/init_experiment.py</code> aligned with the bundled files in <code>src/dl_core/templates/</code>.</rule>
+    <rule>Keep generated config conventions consistent: top-level <code>accelerator</code>, <code>dataset</code>, singular <code>trainer</code>, and plural component sections such as <code>models</code>, <code>optimizers</code>, <code>criterions</code>, <code>metric_managers</code>, and <code>callbacks</code>.</rule>
+    <rule>Use <code>dataset.classes</code> for class ordering, and keep sweep dotted paths aligned with the generated config structure.</rule>
+    <rule>Do not introduce experiment-specific assumptions into the library when the behavior belongs in a generated consumer repository.</rule>
+  </architecture_rules>
+
+  <execution_policy>
+    <rule>Never run training jobs, sweeps, worker processes, or publish workflows unless explicitly requested.</rule>
+    <rule>Prefer targeted validation for the files you changed; full test runs are appropriate for code, packaging, or release work.</rule>
+    <rule>If validation was not run, state it explicitly in the final response.</rule>
+    <rule>Do not push commits or trigger manual GitHub Actions unless the user asked for that outcome.</rule>
+  </execution_policy>
+
+  <editing_policy>
+    <rule>Keep edits minimal and task-scoped.</rule>
+    <rule>Do not refactor unrelated code.</rule>
+    <rule>Prefer <code>apply_patch</code> for focused, reviewable edits.</rule>
+    <rule>Do not overwrite user changes or revert unrelated work in a dirty tree.</rule>
+    <rule>When changing scaffolded files or config conventions, update both the generator and the bundled templates together.</rule>
+  </editing_policy>
+
+  <parallel_agent_policy>
+    <rule>Assume multiple agents may edit in parallel.</rule>
+    <rule>If a file changes while being edited, re-read the latest content and integrate safely.</rule>
+    <rule>Only stage or commit the specific changes created for the current task.</rule>
+    <rule>Before any commit, verify that staged changes match the intended scope.</rule>
+  </parallel_agent_policy>
+
+  <versioning_policy>
+    <rule>When bumping the package version, update <code>pyproject.toml</code>, <code>src/dl_core/__init__.py</code>, and the scaffold dependency floor in <code>src/dl_core/init_experiment.py</code>.</rule>
+    <rule>If the version bump affects package metadata or the local project entry in <code>uv.lock</code>, refresh the lockfile rather than editing it by hand.</rule>
+    <rule>Before any publish action, make sure version references are internally consistent and validation has passed.</rule>
+    <rule>Use concise release commits such as <code>release: bump dl-core to 0.1.8</code>.</rule>
+  </versioning_policy>
+
+  <github_actions_policy>
+    <rule>Use <code>gh</code> to inspect workflows and runs when GitHub Actions work is requested.</rule>
+    <rule>The repository workflows are <code>CI</code>, <code>Publish TestPyPI</code>, and <code>Publish</code>.</rule>
+    <rule>Prefer checking existing runs with <code>gh run list</code>, <code>gh run view</code>, and <code>gh run watch</code> before dispatching anything new.</rule>
+    <rule>When the user says <code>publish</code>, push the current commits and trigger <code>Publish TestPyPI</code> by default.</rule>
+    <rule>Only trigger the <code>Publish</code> workflow when the user explicitly says <code>publish on pypi</code> or clearly requests a PyPI release.</rule>
+    <rule>After dispatching a workflow with <code>gh workflow run</code>, monitor it and report the final status and run identifier or URL.</rule>
+    <rule>Do not cancel, rerun, or approve workflows unless the user explicitly asks for that action.</rule>
+  </github_actions_policy>
+
+  <jira_policy>
+    <rule>Use <code>acli</code> for Jira issue lookup, creation, and status tracking when Jira work is requested.</rule>
+    <rule>Before starting substantial new implementation work, first create appropriately nested Jira work items that match the repository task hierarchy.</rule>
+    <rule>When work spans multiple steps or components, create parent and child Jira tasks instead of tracking everything in a single flat issue.</rule>
+    <rule>Do not create Jira tasks for very small edits, narrow documentation changes, or other low-overhead work unless the user explicitly asks for Jira tracking.</rule>
+    <rule>When creating a Jira task, include a concise summary, repository context, affected paths, and clear acceptance criteria.</rule>
+    <rule>When tracking work against Jira, report the issue key and the exact status change or comment that was added.</rule>
+    <rule>After completing a task, transition the corresponding Jira issue to <code>Done</code>.</rule>
+    <rule>If the Jira project, issue type, assignee, or workflow step is unclear, inspect existing issues first instead of guessing.</rule>
+  </jira_policy>
+
+  <git_policy>
+    <rule>After every completed repository change, stage the task-scoped files and create a concise local git commit.</rule>
+    <rule>Do not push commits by default; pushing is reserved for an explicit <code>publish</code> request.</rule>
+    <rule>Use clear, imperative, prefix-based commit messages such as <code>docs: update contributor guide</code>, <code>test: add scaffold smoke coverage</code>, or <code>release: bump dl-core to 0.1.8</code>.</rule>
+    <rule>Keep pull requests focused and include scope summary, validation evidence, and any config or release implications.</rule>
+    <rule>When CLI behavior, scaffold output, or release flow changes, include sample commands or output in the PR description.</rule>
+    <rule>Never mention tool-generated authorship metadata such as <code>co-authored-by</code> unless the user explicitly asks for it.</rule>
+  </git_policy>
+
+  <agent_behavior>
+    <rule>Before substantial tool use, restate the goal and provide a short plan.</rule>
+    <rule>For multi-step tasks, provide concise progress updates.</rule>
+    <rule>Complete end-to-end resolution in one turn when feasible.</rule>
+    <rule>If uncertain, gather evidence with tools rather than guessing.</rule>
+    <rule>When a task involves release, packaging, GitHub Actions, or Jira, summarize the intended commands before executing them.</rule>
+    <rule>When helping with release work, prefer validating locally first, then using <code>gh</code> for workflow dispatch or inspection only if the user asked for it.</rule>
+  </agent_behavior>
+</agent_spec>

deep_learning_core-0.0.1/LICENSE

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

deep_learning_core-0.0.1/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: deep-learning-core
+Version: 0.0.1
+Summary: Reusable deep learning framework core.
+Project-URL: Homepage, https://github.com/Blazkowiz47/dl-core
+Project-URL: Documentation, https://github.com/Blazkowiz47/dl-core/tree/main/readme
+Project-URL: Repository, https://github.com/Blazkowiz47/dl-core
+Project-URL: Issues, https://github.com/Blazkowiz47/dl-core/issues
+Author-email: blazkowiz47 <sushrutpatwardhan@gmail.com>
+Maintainer-email: blazkowiz47 <sushrutpatwardhan@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Sushrut Patwardhan
+        
+        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.
+License-File: LICENSE
+Keywords: deep-learning,machine-learning,pytorch,sweeps,training
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: albumentations
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: psutil
+Requires-Dist: pyyaml
+Requires-Dist: scikit-learn
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: tqdm
+Provides-Extra: azure
+Requires-Dist: deep-learning-azure; extra == 'azure'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: mlflow
+Requires-Dist: deep-learning-mlflow; extra == 'mlflow'
+Provides-Extra: wandb
+Requires-Dist: deep-learning-wandb; extra == 'wandb'
+Description-Content-Type: text/markdown
+
+# dl-core
+
+Reusable deep learning framework core.
+
+`dl-core` contains the vendor-neutral training framework that can be reused
+across many experiment repositories. It is intended to be the public base
+package, while optional integrations such as Azure are layered on through
+extras and companion extension packages.
+
+## Install
+
+Current public validation releases are published on TestPyPI. Once the package
+is promoted to PyPI, the plain `pip install dl-core` forms below will be the
+normal install path.
+
+PyPI install target:
+
+```bash
+pip install dl-core
+```
+
+Install with Azure support:
+
+```bash
+pip install "dl-core[azure]"
+```
+
+Install with local MLflow support:
+
+```bash
+pip install "dl-core[mlflow]"
+```
+
+Install with W&B support:
+
+```bash
+pip install "dl-core[wandb]"
+```
+
+Install with multiple variants:
+
+```bash
+pip install "dl-core[azure,wandb]"
+```
+
+Install today from TestPyPI with `pip`:
+
+```bash
+pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  dl-core
+```
+
+Install today from TestPyPI in a `uv` project:
+
+```toml
+[tool.uv.sources]
+dl-core = { index = "testpypi" }
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+explicit = true
+```
+
+Then run:
+
+```bash
+uv add dl-core
+```
+
+Do not use `uv add --index https://test.pypi.org/simple/ dl-core` for this
+package. With `uv`'s default `first-index` strategy, that can pull unrelated
+dependency names from TestPyPI instead of PyPI.
+
+`dl-core` intentionally ships with the full public runtime dependencies,
+including `torch`, `torchvision`, and `opencv-python`. The Azure extra pulls in
+`dl-azure`, which pins the Azure package versions used by the validated Azure
+packaging stack. The MLflow extra pulls in `dl-mlflow` for local MLflow
+tracking. The W&B extra pulls in `dl-wandb` and leaves the `wandb` package
+itself unpinned.
+
+## Package Variants
+
+- `dl-core`: local training, local sweeps, local sweep analysis, and the
+  experiment scaffold
+- `dl-core[azure]`: adds the public
+  [`dl-azure`](https://github.com/Blazkowiz47/dl-azure)
+  package for Azure execution and Azure dataset foundations
+- `dl-core[mlflow]`: adds the public
+  [`dl-mlflow`](https://github.com/Blazkowiz47/dl-mlflow)
+  package for local MLflow integration
+- `dl-core[wandb]`: adds the public
+  [`dl-wandb`](https://github.com/Blazkowiz47/dl-wandb)
+  package for Weights & Biases integration
+
+The extension packages stay separate so the base package remains reusable and
+vendor-neutral.
+
+## Scope
+
+- Base abstractions and registries
+- Built-in accelerators, callbacks, criterions, metrics, and schedulers
+- The standard trainer and standard dataset flow
+- Built-in augmentations
+- Local execution and sweep orchestration
+- Local sweep analysis from saved artifact summaries
+- Experiment repository scaffolding via `dl-init-experiment`
+
+## Out Of Scope
+
+- Azure ML wiring unless the Azure extra is installed
+- Workspace or datastore conventions
+- Experiment-specific datasets, models, and trainers
+- User-owned configs and private data
+
+## Quick Start
+
+```bash
+dl-run --show-registry
+dl-init-experiment --name my-exp --root-dir .
+```
+
+To initialize the current directory in place, omit `--name`:
+
+```bash
+dl-init-experiment --root-dir .
+```
+
+The generated experiment repository is the normal consumer entry point. Install
+that repository in editable mode, then run:
+
+```bash
+uv run dl-run --config configs/base.yaml
+uv run dl-sweep --sweep experiments/lr_sweep.yaml
+uv run dl-analyze-sweep --sweep experiments/lr_sweep.yaml
+```
+
+If Azure support is installed, `dl-init-experiment --with-azure` will also
+scaffold Azure-ready config placeholders and `azure-config.json`.
+
+If local MLflow support is installed, `dl-init-experiment --with-mlflow` will
+also scaffold an `mlflow` callback block and local tracking defaults.
+
+If W&B support is installed, `dl-init-experiment --with-wandb` will also
+scaffold a `wandb` callback block, W&B tracking defaults, and `.env.example`.
+
+## Companion Packages
+
+- [`dl-azure`](https://github.com/Blazkowiz47/dl-azure)
+- [`dl-mlflow`](https://github.com/Blazkowiz47/dl-mlflow)
+- [`dl-wandb`](https://github.com/Blazkowiz47/dl-wandb)
+
+To add a new local component scaffold inside the experiment repo:
+
+```bash
+uv run dl-core add augmentation Custom1
+```
+
+Dataset scaffolds can now target a specific wrapper base:
+
+```bash
+uv run dl-core add dataset MyDataset
+uv run dl-core add dataset FrameSet --base frame
+```
+
+When `dl-azure` is importable, the dataset scaffold also exposes Azure bases:
+
+```bash
+uv run dl-core add dataset AzureFrames --base azure_compute_frame
+uv run dl-core add dataset AzureSeq --base azure_compute_multiframe
+```
+
+Plain `dl-core` currently exposes dataset bases for `BaseWrapper` and
+`FrameWrapper`. Multiframe dataset bases are provided through `dl-azure`.
+
+## Releases
+
+- `Publish TestPyPI` is the manual validation workflow for TestPyPI.
+- `Publish` is the production workflow for PyPI.
+- Trusted publishing is configured through GitHub Actions environments rather
+  than long-lived API tokens.
+- The publish action may upload digital attestations alongside the package.
+  That is expected behavior from `pypa/gh-action-pypi-publish`.
+- Package metadata keeps runtime dependencies unpinned, so the consuming
+  environment resolves the latest compatible public releases.
+
+## Documentation
+
+- [Documentation Index](https://github.com/Blazkowiz47/dl-core/tree/main/readme)
+- [GitHub Repository](https://github.com/Blazkowiz47/dl-core)
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Development Validation
+
+```bash
+uv run --extra dev pytest
+uv run python -m compileall src/dl_core
+```