thumbforge 0.1.0__tar.gz

thumbforge-0.1.0/LICENSE

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

thumbforge-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: thumbforge
+Version: 0.1.0
+Summary: Generate consistent, spec-compliant YouTube thumbnails from a hero image and a playlist.
+Keywords: youtube,thumbnail,cli,image-generation,typer
+Author: Gishant Singh
+Author-email: Gishant Singh <khiladisngh@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Dist: alembic>=1.14
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: keyring>=25.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: platformdirs>=4.11.10
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: rich-pixels>=3.0.1
+Requires-Dist: sqlalchemy>=2.0,<2.1
+Requires-Dist: structlog>=26.1.0
+Requires-Dist: tenacity>=9.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer
+Requires-Dist: yt-dlp>=2026.8.19
+Requires-Dist: google-api-python-client ; extra == 'api'
+Requires-Dist: google-auth ; extra == 'api'
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/khiladisngh/thumbforge
+Project-URL: Documentation, https://khiladisngh.github.io/thumbforge/
+Project-URL: Repository, https://github.com/khiladisngh/thumbforge
+Project-URL: Issues, https://github.com/khiladisngh/thumbforge/issues
+Project-URL: Changelog, https://github.com/khiladisngh/thumbforge/blob/main/CHANGELOG.md
+Provides-Extra: api
+Description-Content-Type: text/markdown
+
+# thumbforge
+
+[![ci](https://github.com/khiladisngh/thumbforge/actions/workflows/ci.yml/badge.svg)](https://github.com/khiladisngh/thumbforge/actions/workflows/ci.yml)
+[![docs](https://github.com/khiladisngh/thumbforge/actions/workflows/docs.yml/badge.svg)](https://khiladisngh.github.io/thumbforge/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/khiladisngh/thumbforge/blob/main/LICENSE)
+![Python 3.14](https://img.shields.io/badge/python-3.14-blue)
+
+Generate consistent, spec-compliant YouTube thumbnails from a hero image and a playlist — from the terminal.
+
+- **Hero first.** Generate several candidates for one video, compare, pick, refine.
+- **Batch second.** Use the picked hero as the style reference for every video in a playlist, with deterministic titles and "Part N" badges rendered by Pillow over AI-generated art.
+- **Pluggable providers.** Antigravity CLI first; add your own via the `thumbforge.providers` entry-point group. A deterministic `fake` provider keeps tests offline.
+- **Local database.** Channels, playlists, videos, templates, runs, iterations and assets in SQLite; images content-addressed on disk; interrupted batches resume without regenerating finished items.
+
+> **Status: pre-release.** `v0.1.0` has not been tagged or published yet, so Thumbforge is not on PyPI. Install it from GitHub as shown below. The [changelog](https://github.com/khiladisngh/thumbforge/blob/main/CHANGELOG.md) lists what is on `main`.
+
+## Install
+
+Thumbforge needs [uv](https://docs.astral.sh/uv/) and Python 3.14 (uv downloads Python if it is missing). Install from GitHub:
+
+```
+uv tool install git+https://github.com/khiladisngh/thumbforge
+```
+
+or from a checkout:
+
+```
+git clone https://github.com/khiladisngh/thumbforge
+cd thumbforge
+uv tool install .
+```
+
+Check it:
+
+```
+thumbforge --version
+```
+
+> **Once v0.1.0 is published** (not yet): `uv tool install thumbforge`.
+
+## Quick start
+
+This reproduces the three examples of [`PLAN.md` §5.3](https://github.com/khiladisngh/thumbforge/blob/main/PLAN.md#53-examples) — fetch a playlist, generate a hero, run a batch — with the offline `fake` provider, so it needs no account and no API key. `fetch` reads public YouTube metadata, so it needs network access. The images the `fake` provider returns are placeholders, not artwork.
+
+Point Thumbforge at a scratch config and data directory first, so nothing touches your real setup. These two lines are the only shell-specific part:
+
+```
+# Linux / macOS
+export THUMBFORGE_CONFIG="$PWD/scratch/config.toml"
+export THUMBFORGE_GENERAL__DATA_DIR="$PWD/scratch/data"
+```
+
+```
+# Windows PowerShell
+$env:THUMBFORGE_CONFIG = "$PWD\scratch\config.toml"
+$env:THUMBFORGE_GENERAL__DATA_DIR = "$PWD\scratch\data"
+```
+
+Create the database, which also stores the built-in templates:
+
+```
+$ thumbforge db init
+initialized database at <data-dir>/thumbforge.sqlite3 (0001)
+```
+
+**1. Fetch a playlist.** This one is public and large (about 180 videos); `batch --only` below keeps the run short. It prints the playlist and one row per video, with the video's part number and id:
+
+```
+$ thumbforge fetch "https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI"
+…
+Stored 1 channel, 1 playlist, <n> videos.
+```
+
+**2. Generate a hero.** Pass the id of the first video from the table above as `<video-id>`:
+
+```
+$ thumbforge thumb generate <video-id> --template bold-title --provider fake --n 4
+Run <run-id>
+Kind      hero
+Status    completed
+Template  bold-title@1
+Provider  fake@0.1.0:<fingerprint>
+Video     <video-id>
+Started   <timestamp>
+Finished  <timestamp>
+┏━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━┓
+┃ # ┃ Status    ┃ Size      ┃ Compliant ┃ Key          ┃ Cost ┃ Asset / Error ┃
+┡━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━┩
+│ 1 │ completed │ 1920x1080 │ ✔         │ <key>        │ —    │ <asset>       │
+│ 2 │ completed │ 1920x1080 │ ✔         │ <key>        │ —    │ <asset>       │
+│ 3 │ completed │ 1920x1080 │ ✔         │ <key>        │ —    │ <asset>       │
+│ 4 │ completed │ 1920x1080 │ ✔         │ <key>        │ —    │ <asset>       │
+└───┴───────────┴───────────┴───────────┴──────────────┴──────┴───────────────┘
+…
+Pick one with: thumbforge thumb pick <run-id> <ordinal>
+```
+
+The `…` is a table of file paths (a terminal that can draw images shows a preview instead). Copy the run id from the first line.
+
+**3. Pick one candidate.** The picked image becomes the style reference for the batch:
+
+```
+$ thumbforge thumb pick <run-id> 2
+Picked #2 of run <run-id> (iteration <iteration-id>)
+Export it with: thumbforge thumb export <run-id> --to PATH
+```
+
+**4. Run a batch** for the first three videos of the playlist, in the hero's style:
+
+```
+$ thumbforge batch PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI --hero <run-id> --template series-parts --only 1-3
+Batch run <batch-run-id>
+Playlist    <playlist-title>
+Template    series-parts@1
+Provider    fake@0.1.0:<fingerprint>
+Reference   <asset> (final)
+Parent run  <run-id>
+Status      completed
+Items       3 completed, 0 failed, 0 pending of 3
+…
+```
+
+Run ids, asset hashes and timestamps differ on every run, and the playlist's videos change over time. Progress lines such as `run started` go to stderr and are left out above; `--quiet` hides them. `batch --dry-run` prints the plan and generates nothing. If a batch is interrupted or some items fail, `thumbforge runs resume <batch-run-id>` finishes the rest without regenerating the completed ones.
+
+Where to go next:
+
+- [Getting started](https://khiladisngh.github.io/thumbforge/user-guide/getting-started/): the same flow with templates, exporting and playlist numbering.
+- [Generate a hero](https://khiladisngh.github.io/thumbforge/user-guide/how-to/generate-a-hero/) and [Pick and refine](https://khiladisngh.github.io/thumbforge/user-guide/how-to/pick-and-refine/).
+- [Providers](https://khiladisngh.github.io/thumbforge/user-guide/concepts/providers/): the real image providers and their keys.
+- [Shell completion](https://khiladisngh.github.io/thumbforge/user-guide/how-to/shell-completion/).
+
+## Documentation
+
+Published at **https://khiladisngh.github.io/thumbforge/**, in three sections: a user guide, developer docs (architecture, conventions, testing, specs) and maintainer docs (release process, CI, roadmap, decision records).
+
+- [`PLAN.md`](https://github.com/khiladisngh/thumbforge/blob/main/PLAN.md) — full project plan
+- [`CHANGELOG.md`](https://github.com/khiladisngh/thumbforge/blob/main/CHANGELOG.md) — changes by Conventional Commit type
+- [`AGENTS.md`](https://github.com/khiladisngh/thumbforge/blob/main/AGENTS.md) — instructions for coding agents (this repo is built spec-first by agents)
+- [`OPEN_QUESTIONS.md`](https://github.com/khiladisngh/thumbforge/blob/main/OPEN_QUESTIONS.md) — spikes and decisions
+
+## Development
+
+```
+uv sync --locked
+uv run pytest -q
+uv run ruff check . && uv run ruff format .
+uv run pyright
+uv run zensical serve      # docs at http://localhost:8000
+pre-commit install
+```
+
+## License
+
+[MIT](https://github.com/khiladisngh/thumbforge/blob/main/LICENSE) © 2026 Gishant Singh

thumbforge-0.1.0/README.md

@@ -0,0 +1,154 @@
+# thumbforge
+
+[![ci](https://github.com/khiladisngh/thumbforge/actions/workflows/ci.yml/badge.svg)](https://github.com/khiladisngh/thumbforge/actions/workflows/ci.yml)
+[![docs](https://github.com/khiladisngh/thumbforge/actions/workflows/docs.yml/badge.svg)](https://khiladisngh.github.io/thumbforge/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/khiladisngh/thumbforge/blob/main/LICENSE)
+![Python 3.14](https://img.shields.io/badge/python-3.14-blue)
+
+Generate consistent, spec-compliant YouTube thumbnails from a hero image and a playlist — from the terminal.
+
+- **Hero first.** Generate several candidates for one video, compare, pick, refine.
+- **Batch second.** Use the picked hero as the style reference for every video in a playlist, with deterministic titles and "Part N" badges rendered by Pillow over AI-generated art.
+- **Pluggable providers.** Antigravity CLI first; add your own via the `thumbforge.providers` entry-point group. A deterministic `fake` provider keeps tests offline.
+- **Local database.** Channels, playlists, videos, templates, runs, iterations and assets in SQLite; images content-addressed on disk; interrupted batches resume without regenerating finished items.
+
+> **Status: pre-release.** `v0.1.0` has not been tagged or published yet, so Thumbforge is not on PyPI. Install it from GitHub as shown below. The [changelog](https://github.com/khiladisngh/thumbforge/blob/main/CHANGELOG.md) lists what is on `main`.
+
+## Install
+
+Thumbforge needs [uv](https://docs.astral.sh/uv/) and Python 3.14 (uv downloads Python if it is missing). Install from GitHub:
+
+```
+uv tool install git+https://github.com/khiladisngh/thumbforge
+```
+
+or from a checkout:
+
+```
+git clone https://github.com/khiladisngh/thumbforge
+cd thumbforge
+uv tool install .
+```
+
+Check it:
+
+```
+thumbforge --version
+```
+
+> **Once v0.1.0 is published** (not yet): `uv tool install thumbforge`.
+
+## Quick start
+
+This reproduces the three examples of [`PLAN.md` §5.3](https://github.com/khiladisngh/thumbforge/blob/main/PLAN.md#53-examples) — fetch a playlist, generate a hero, run a batch — with the offline `fake` provider, so it needs no account and no API key. `fetch` reads public YouTube metadata, so it needs network access. The images the `fake` provider returns are placeholders, not artwork.
+
+Point Thumbforge at a scratch config and data directory first, so nothing touches your real setup. These two lines are the only shell-specific part:
+
+```
+# Linux / macOS
+export THUMBFORGE_CONFIG="$PWD/scratch/config.toml"
+export THUMBFORGE_GENERAL__DATA_DIR="$PWD/scratch/data"
+```
+
+```
+# Windows PowerShell
+$env:THUMBFORGE_CONFIG = "$PWD\scratch\config.toml"
+$env:THUMBFORGE_GENERAL__DATA_DIR = "$PWD\scratch\data"
+```
+
+Create the database, which also stores the built-in templates:
+
+```
+$ thumbforge db init
+initialized database at <data-dir>/thumbforge.sqlite3 (0001)
+```
+
+**1. Fetch a playlist.** This one is public and large (about 180 videos); `batch --only` below keeps the run short. It prints the playlist and one row per video, with the video's part number and id:
+
+```
+$ thumbforge fetch "https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI"
+…
+Stored 1 channel, 1 playlist, <n> videos.
+```
+
+**2. Generate a hero.** Pass the id of the first video from the table above as `<video-id>`:
+
+```
+$ thumbforge thumb generate <video-id> --template bold-title --provider fake --n 4
+Run <run-id>
+Kind      hero
+Status    completed
+Template  bold-title@1
+Provider  fake@0.1.0:<fingerprint>
+Video     <video-id>
+Started   <timestamp>
+Finished  <timestamp>
+┏━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━┓
+┃ # ┃ Status    ┃ Size      ┃ Compliant ┃ Key          ┃ Cost ┃ Asset / Error ┃
+┡━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━┩
+│ 1 │ completed │ 1920x1080 │ ✔         │ <key>        │ —    │ <asset>       │
+│ 2 │ completed │ 1920x1080 │ ✔         │ <key>        │ —    │ <asset>       │
+│ 3 │ completed │ 1920x1080 │ ✔         │ <key>        │ —    │ <asset>       │
+│ 4 │ completed │ 1920x1080 │ ✔         │ <key>        │ —    │ <asset>       │
+└───┴───────────┴───────────┴───────────┴──────────────┴──────┴───────────────┘
+…
+Pick one with: thumbforge thumb pick <run-id> <ordinal>
+```
+
+The `…` is a table of file paths (a terminal that can draw images shows a preview instead). Copy the run id from the first line.
+
+**3. Pick one candidate.** The picked image becomes the style reference for the batch:
+
+```
+$ thumbforge thumb pick <run-id> 2
+Picked #2 of run <run-id> (iteration <iteration-id>)
+Export it with: thumbforge thumb export <run-id> --to PATH
+```
+
+**4. Run a batch** for the first three videos of the playlist, in the hero's style:
+
+```
+$ thumbforge batch PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI --hero <run-id> --template series-parts --only 1-3
+Batch run <batch-run-id>
+Playlist    <playlist-title>
+Template    series-parts@1
+Provider    fake@0.1.0:<fingerprint>
+Reference   <asset> (final)
+Parent run  <run-id>
+Status      completed
+Items       3 completed, 0 failed, 0 pending of 3
+…
+```
+
+Run ids, asset hashes and timestamps differ on every run, and the playlist's videos change over time. Progress lines such as `run started` go to stderr and are left out above; `--quiet` hides them. `batch --dry-run` prints the plan and generates nothing. If a batch is interrupted or some items fail, `thumbforge runs resume <batch-run-id>` finishes the rest without regenerating the completed ones.
+
+Where to go next:
+
+- [Getting started](https://khiladisngh.github.io/thumbforge/user-guide/getting-started/): the same flow with templates, exporting and playlist numbering.
+- [Generate a hero](https://khiladisngh.github.io/thumbforge/user-guide/how-to/generate-a-hero/) and [Pick and refine](https://khiladisngh.github.io/thumbforge/user-guide/how-to/pick-and-refine/).
+- [Providers](https://khiladisngh.github.io/thumbforge/user-guide/concepts/providers/): the real image providers and their keys.
+- [Shell completion](https://khiladisngh.github.io/thumbforge/user-guide/how-to/shell-completion/).
+
+## Documentation
+
+Published at **https://khiladisngh.github.io/thumbforge/**, in three sections: a user guide, developer docs (architecture, conventions, testing, specs) and maintainer docs (release process, CI, roadmap, decision records).
+
+- [`PLAN.md`](https://github.com/khiladisngh/thumbforge/blob/main/PLAN.md) — full project plan
+- [`CHANGELOG.md`](https://github.com/khiladisngh/thumbforge/blob/main/CHANGELOG.md) — changes by Conventional Commit type
+- [`AGENTS.md`](https://github.com/khiladisngh/thumbforge/blob/main/AGENTS.md) — instructions for coding agents (this repo is built spec-first by agents)
+- [`OPEN_QUESTIONS.md`](https://github.com/khiladisngh/thumbforge/blob/main/OPEN_QUESTIONS.md) — spikes and decisions
+
+## Development
+
+```
+uv sync --locked
+uv run pytest -q
+uv run ruff check . && uv run ruff format .
+uv run pyright
+uv run zensical serve      # docs at http://localhost:8000
+pre-commit install
+```
+
+## License
+
+[MIT](https://github.com/khiladisngh/thumbforge/blob/main/LICENSE) © 2026 Gishant Singh

thumbforge-0.1.0/pyproject.toml

@@ -0,0 +1,197 @@
+[project]
+name = "thumbforge"
+version = "0.1.0"
+description = "Generate consistent, spec-compliant YouTube thumbnails from a hero image and a playlist."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+keywords = [
+    "youtube",
+    "thumbnail",
+    "cli",
+    "image-generation",
+    "typer",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "alembic>=1.14",
+    "jinja2>=3.1.6",
+    "keyring>=25.0",
+    "pillow>=10.0",
+    "platformdirs>=4.11.10",
+    "pydantic>=2.13.5",
+    "pydantic-settings>=2.15.0",
+    "rich>=15.0.0",
+    "rich-pixels>=3.0.1",
+    "sqlalchemy>=2.0,<2.1",
+    "structlog>=26.1.0",
+    "tenacity>=9.0",
+    "tomli-w>=1.2.0",
+    "typer",
+    "yt-dlp>=2026.8.19",
+]
+
+[[project.authors]]
+name = "Gishant Singh"
+email = "khiladisngh@hotmail.com"
+
+[project.optional-dependencies]
+api = [
+    "google-api-python-client",
+    "google-auth",
+]
+
+[project.urls]
+Homepage = "https://github.com/khiladisngh/thumbforge"
+Documentation = "https://khiladisngh.github.io/thumbforge/"
+Repository = "https://github.com/khiladisngh/thumbforge"
+Issues = "https://github.com/khiladisngh/thumbforge/issues"
+Changelog = "https://github.com/khiladisngh/thumbforge/blob/main/CHANGELOG.md"
+
+[project.scripts]
+thumbforge = "thumbforge.cli.app:main"
+
+[project.entry-points."thumbforge.providers"]
+
+[dependency-groups]
+dev = [
+    "ruff",
+    "pyright",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "pre-commit",
+    "import-linter",
+    "zensical",
+    "testcontainers>=4.15.0",
+    "google-api-python-client",
+    "google-api-python-client-stubs",
+    "google-auth",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.16,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "TCH",
+    "RUF",
+]
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = [
+    "pydantic.BaseModel",
+    "pydantic_settings.BaseSettings",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/thumbforge/cli/*.py" = [
+    "TC001",
+    "TC002",
+    "TC003",
+]
+
+[tool.pyright]
+strict = ["src"]
+pythonVersion = "3.14"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "integration: hits the network or a real provider; opt in with -m integration",
+    "golden: image or prompt-text snapshot comparison",
+]
+testpaths = ["tests"]
+addopts = "-m 'not integration'"
+
+[tool.coverage.run]
+source = ["thumbforge"]
+branch = true
+omit = ["src/thumbforge/__main__.py"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+
+[tool.importlinter]
+root_package = "thumbforge"
+
+[[tool.importlinter.contracts]]
+name = "nothing imports cli"
+type = "forbidden"
+source_modules = [
+    "thumbforge.core",
+    "thumbforge.storage",
+    "thumbforge.sources",
+    "thumbforge.providers",
+    "thumbforge.settings",
+    "thumbforge.logging",
+    "thumbforge.credentials",
+    "thumbforge.imaging",
+    "thumbforge.templates",
+]
+forbidden_modules = ["thumbforge.cli"]
+
+[[tool.importlinter.contracts]]
+name = "core is pure"
+type = "forbidden"
+source_modules = ["thumbforge.core"]
+forbidden_modules = [
+    "thumbforge.storage",
+    "thumbforge.sources",
+    "thumbforge.providers",
+    "thumbforge.cli",
+    "thumbforge.settings",
+    "thumbforge.logging",
+    "thumbforge.credentials",
+    "thumbforge.imaging",
+    "thumbforge.templates",
+]
+
+[[tool.importlinter.contracts]]
+name = "adapters are independent"
+type = "independence"
+modules = [
+    "thumbforge.storage",
+    "thumbforge.sources",
+    "thumbforge.providers",
+    "thumbforge.templates",
+    "thumbforge.imaging",
+]
+
+[[tool.importlinter.contracts]]
+name = "core leaf modules import nothing from core"
+type = "forbidden"
+source_modules = [
+    "thumbforge.core.enums",
+    "thumbforge.core.errors",
+    "thumbforge.core.ids",
+    "thumbforge.core.json",
+]
+forbidden_modules = [
+    "thumbforge.core.models",
+    "thumbforge.core.providers",
+    "thumbforge.core.urls",
+]