chore: release v0.2.0

[w7-mgfcode]

Summary

Merge dev into main to trigger automatic release.

Changes in this release

• feat(registry): Implement model registry for run tracking and deployments (feat(registry): implement model registry for run tracking and deployments #36)

  • ORM models for ModelRun (JSONB columns) and DeploymentAlias with state machine validation
  • LocalFSProvider for artifact storage with SHA-256 integrity verification
  • 10 API endpoints for runs CRUD, aliases management, artifact verification, and run comparison
  • Comprehensive test suite (103 unit + 24 integration tests)
  • PHASE documentation for phases 4 (Forecasting), 5 (Backtesting), and 6 (Model Registry)

• fix: Code improvements and documentation fixes

  • Add date range filter to SalesDaily cleanup in ingest tests
  • Enforce artifact_hash presence before verification in registry routes
  • Compute SHA256 from saved file instead of source in storage
  • Fix override_get_db to mirror production transaction semantics
  • Update database port to 5433 in config and .env.example
  • Fix markdownlint MD040/MD060 issues in docs

Test plan

• All CI checks passing on dev branch
• Registry tests passing (103 unit + 24 integration)
• Type checks passing (mypy + pyright)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Model Registry: run lifecycle (PENDING→RUNNING→SUCCESS/FAILED→ARCHIVED), aliases for successful runs, run comparison, artifact verification (SHA‑256), pluggable storage (LocalFS implemented), runtime & agent snapshots, duplicate-detection policy, full API surface.

• Documentation

  • Architecture and Phase docs updated; README and examples (registry_demo) added.

• Database

  • New migrations for registry tables (runs & aliases).

• Tests

  • Extensive unit/integration tests and test fixtures for registry, storage, service, and routes.

• Config

  • New registry settings (artifact root, duplicate policy) and updated ports.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[sourcery-ai]

Sorry @w7-mgfcode, your pull request is larger than the review limit of 150000 diff characters

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a Model Registry feature: ORM models and Alembic migration, Pydantic schemas, a RegistryService with lifecycle/state-machine, API routes, pluggable artifact storage (LocalFS) with SHA‑256 integrity, deployment aliases, config settings, examples, and comprehensive tests and docs.

Changes

Cohort / File(s)	Summary
Registry Core app/features/registry/models.py, app/features/registry/schemas.py, app/features/registry/service.py, app/features/registry/storage.py, app/features/registry/__init__.py	New ORM (ModelRun, DeploymentAlias) and RunStatus; Pydantic schemas for runs/aliases; RegistryService with lifecycle/duplicate detection, diffing, runtime capture; AbstractStorageProvider + LocalFSProvider and storage exceptions; public exports.
API Routes app/features/registry/routes.py	Adds /registry endpoints: create/list/get/update/verify runs, compare runs, and CRUD for aliases with error handling and HTTP mappings.
Migrations & DB Integration alembic/versions/a2f7b3c8d901_create_model_registry_tables.py, alembic/env.py, app/core/config.py	Alembic migration creating model_run and deployment_alias tables, GIN/indexes, constraints; import wired into env; new settings registry_artifact_root and registry_duplicate_policy.
Tests & Fixtures app/features/registry/tests/..., app/features/registry/tests/conftest.py, tests/conftest.py	Extensive unit & integration tests for schemas, service, storage, routes; test fixtures for DB, sample runs, artifacts; test infra updated to rely on migrations and explicit cleanup.
App Integration & Examples app/main.py, examples/registry_demo.py, README.md, docs/...	Registers registry router in main app; adds demo script and docs (ARCHITECTURE, PHASEs, README) describing registry, backtesting, forecasting phases and APIs.
Test Adjustments Elsewhere app/features/*/tests/*, app/features/ingest/tests/test_routes.py, app/features/data_platform/tests/conftest.py	Tests updated to rely on migrations (removed create_all/drop_all), added explicit cleanup and some mypy type-ignore comments for frozen-model mutation sites.
Config & Tooling docker-compose.yml, .env.example, pyproject.toml	Postgres host port changed to 5433; pyproject adds pydantic.mypy plugin and pydantic-mypy settings.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant APIRouter
    participant RegistryService
    participant DB as AsyncSession
    participant Storage as LocalFSProvider

    Client->>APIRouter: POST /registry/runs (RunCreate)
    APIRouter->>RegistryService: create_run(run_data)
    RegistryService->>RegistryService: compute_config_hash()
    RegistryService->>DB: query for duplicate
    DB-->>RegistryService: result
    RegistryService->>DB: insert ModelRun (PENDING)
    DB-->>RegistryService: ModelRun
    RegistryService-->>APIRouter: RunResponse
    APIRouter-->>Client: 201

    Client->>APIRouter: PATCH /registry/runs/{id} (status=SUCCESS, artifact_uri, artifact_hash)
    APIRouter->>RegistryService: update_run(id, update_data)
    RegistryService->>RegistryService: validate_transition()
    RegistryService->>DB: update ModelRun (status, timestamps, artifact metadata)
    DB-->>RegistryService: updated ModelRun
    RegistryService-->>APIRouter: RunResponse
    APIRouter-->>Client: 200

    Client->>APIRouter: GET /registry/runs/{id}/verify
    APIRouter->>RegistryService: verify_artifact(id)
    RegistryService->>DB: fetch ModelRun (artifact_uri, hash)
    DB-->>RegistryService: ModelRun
    RegistryService->>Storage: load(artifact_uri, expected_hash)
    Storage-->>RegistryService: Path (hash validated)
    RegistryService-->>APIRouter: {valid: true, hash: "..."}
    APIRouter-->>Client: 200

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Suggested reviewers

• w7-learn

Poem

🐇✨ I hopped through code with eager paws,
Saved runs and hashes, checked the laws,
Aliases point where winners rest,
SHA‑256 keeps artifacts blessed—
A tiny rabbit cheers: "Registry, applause!"

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title 'chore: release v0.2.0' is partially related to the changeset but does not capture the primary feature addition: a comprehensive model registry implementation with ORM models, storage provider, service layer, and extensive test coverage.	Consider using a more descriptive title like 'feat(registry): implement model registry with run tracking and deployments' to better reflect the main technical work, or keep 'chore: release v0.2.0' if this PR purely merges dev into main for automated release.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 99.45% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch dev

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 13

🤖 Fix all issues with AI agents

In `@app/features/ingest/tests/test_routes.py`:
- Around line 45-55: The SalesDaily cleanup is unscoped and can remove unrelated
rows; change the delete call for SalesDaily in the async cleanup block to
include the same 2024 date range filter used for Calendar (i.e. use a WHERE on
SalesDaily.date between date(2024,1,1) and date(2024,12,31)) so it only deletes
test rows; update the delete(SalesDaily) statement inside the
async_session_maker cleanup_session context to apply that date-range predicate
alongside the existing filtered deletes for Product, Store, and Calendar.

In `@app/features/registry/routes.py`:
- Around line 346-364: The endpoint currently calls LocalFSProvider.load(...)
with run.artifact_hash possibly None which causes load to skip validation and
return "verified": True; before calling storage.load() enforce that
run.artifact_hash is present and non-None and if missing raise an
HTTPException(status_code=400, detail="Run has no stored artifact hash") so
verification cannot proceed without a stored hash; update the route logic around
the LocalFSProvider usage (the block referencing run.artifact_uri,
run.artifact_hash, storage.load, and storage.compute_hash) to perform this
pre-check and only call load() with expected_hash when run.artifact_hash is
provided.

In `@app/features/registry/storage.py`:
- Around line 169-199: In save (function save in storage.py) compute the SHA256
and size from the stored file rather than the source: perform
shutil.copy2(source_path, dest_path) first, then call compute_hash(dest_path)
and use dest_path.stat().st_size for file_size; keep the same logger call and
return values so the reported hash/size reflect the actual saved artifact.

In `@app/features/registry/tests/conftest.py`:
- Around line 55-70: The test override_get_db should mirror production get_db's
transaction semantics: wrap the yield in try/except so that after the yielded
db_session returns normally you call await db_session.commit(), and on exception
you call await db_session.rollback() and re-raise; keep yielding db_session as
before and then clear app.dependency_overrides in the fixture cleanup. Update
the override_get_db async generator used in the client fixture to perform await
db_session.commit() after a successful yield and await db_session.rollback() on
exception so test request behavior matches production.
- Around line 26-52: The cleanup currently calls delete(DeploymentAlias) which
deletes all aliases; change the db_session fixture cleanup to only remove
aliases for test runs by filtering DeploymentAlias.run_id to those ModelRun IDs
with model_type.like("test-%") (e.g., use a subquery/select of ModelRun.id where
model_type.like("test-%") and apply DeploymentAlias.run_id.in_(that select) in
the where() for delete). Update the delete(DeploymentAlias) call in the
db_session fixture to include this WHERE clause so only test-related aliases are
removed; keep the existing ModelRun delete and commit logic and engine.dispose.

In `@docker-compose.yml`:
- Around line 9-10: Update the default local DB connection to match the new host
port mapping (5433) so developer setup doesn't break: change the default value
in Settings.database_url (or the DATABASE_URL in the .env used by the app) and
any README/docs that reference the previous 5432 host port to use 5433, or
alternatively revert the docker-compose ports mapping back to "5432:5432" if you
prefer no config changes; ensure the environment variable and
Settings.database_url are consistent with the docker-compose ports entry.

In `@docs/ARCHITECTURE.md`:
- Around line 324-326: The fenced code block containing the lifecycle string
"PENDING → RUNNING → SUCCESS/FAILED → ARCHIVED" lacks a language identifier;
update the opening fence from ``` to ```text (or another suitable language) so
the block becomes ```text and keep the closing fence as ``` to satisfy
markdownlint rule MD040.

In `@docs/PHASE/4-FORECASTING.md`:
- Around line 41-46: The markdown tables (e.g., the one listing models like
`naive`/`NaiveForecaster`, `seasonal_naive`/`SeasonalNaiveForecaster`,
`moving_average`/`MovingAverageForecaster`, and `lightgbm`) use padded pipes and
trigger MD060; remove the spaces between pipes and cell content so the tables
follow the compact style (no padding around `|`). Apply the same change to all
other affected tables referenced in the file (the subsequent model/config
tables) so every table uses the compact pipe style.
- Around line 261-299: Update the two unlabeled fenced code blocks in
docs/PHASE/4-FORECASTING.md: add the "text" language identifier to the directory
tree fence that begins with "app/features/forecasting/" and add the "bash"
language identifier to the Validation Results fence that begins with "$ uv run
ruff check..."; ensure the opening triple-backticks are changed to ```text and
```bash respectively so markdownlint MD040 is satisfied.

In `@docs/PHASE/5-BACKTESTING.md`:
- Around line 45-49: Fix the markdownlint MD040/MD060 issues by adding a
language tag (e.g., ```text) to all fenced CLI/output blocks (the examples like
the block starting with "$ uv run ruff check app/features/backtesting/") and by
normalizing table pipe spacing to match the repo style for the Strategy table
(the table starting with "| Strategy | Training Window | Use Case |") and any
other tables (including the block around the content noted for lines 324-341);
ensure fenced blocks include the language identifier and adjust table cell
spacing so pipes align consistently with the configured markdownlint rules.

In `@docs/PHASE/6-MODEL_REGISTRY.md`:
- Around line 3-6: Update the stale release PR number in the phase doc: locate
the "Release: PR `#35`" line in docs/PHASE/6-MODEL_REGISTRY.md (near the "Date
Completed" and "PRP" header lines) and change the reference to "Release: PR `#37`"
so the document correctly points to the current PR.

In `@INITIAL-7.md`:
- Around line 35-36: Replace the two bare URLs
"https://scalegrid.io/blog/using-jsonb-in-postgresql-how-to-effectively-store-index-json-data-in-postgresql/"
and "https://www.fortra.com/blog/supply-chain-vulnerability" with proper
markdown links (e.g. [Descriptive text](https://...) ) or wrap them in angle
brackets (<https://...>) to satisfy MD034; update the lines where those URLs
appear in INITIAL-7.md so the markdown linter no longer reports bare URLs.

In `@PRPs/PRP-7-model-registry.md`:
- Around line 1053-1061: The markdown uses underscores around __init__.py which
triggers MD050 strong-style warnings; update the task description in the
PRPs/PRP-7-model-registry.md diff so that instances of __init__.py are wrapped
in inline code backticks (i.e., `__init__.py`) wherever they appear in the "Task
18: Update module __init__.py exports" section to prevent underscore emphasis
and satisfy the linter.

🧹 Nitpick comments (4)

app/features/ingest/tests/test_routes.py (1)

41-48: Avoid broad suppress(Exception) during rollback/cleanup.

Swallowing all exceptions can hide cleanup failures and leave dirty state that causes flaky tests. Consider narrowing to expected DB exceptions and logging or re‑raising unexpected ones.

💡 Possible tightening (example)

-from contextlib import suppress
+from contextlib import suppress
+from sqlalchemy.exc import SQLAlchemyError

 ...
-            with suppress(Exception):
+            with suppress(SQLAlchemyError):
                 await session.rollback()

app/features/data_platform/tests/conftest.py (1)

54-70: Don’t swallow cleanup failures silently.
Suppressing all exceptions during teardown can hide failed deletes/commits and leave test data behind, leading to flaky integration tests. Prefer explicit error handling (rollback + fail/log) so issues surface quickly.

Proposed adjustment

-    async with async_session_maker() as cleanup_session:
-        with suppress(Exception):
-            # Clean up test data (delete in correct order due to FK constraints)
-            await cleanup_session.execute(delete(SalesDaily))
-            await cleanup_session.execute(delete(InventorySnapshotDaily))
-            await cleanup_session.execute(delete(PriceHistory))
-            await cleanup_session.execute(delete(Promotion))
-            await cleanup_session.execute(delete(Product).where(Product.sku.like("SKU-TEST%")))
-            await cleanup_session.execute(delete(Product).where(Product.sku.like("TEST-%")))
-            await cleanup_session.execute(delete(Store).where(Store.code.like("TEST%")))
-            await cleanup_session.execute(
-                delete(Calendar).where(
-                    (Calendar.date >= date(2024, 1, 1)) & (Calendar.date <= date(2024, 12, 31))
-                )
-            )
-            await cleanup_session.commit()
+    async with async_session_maker() as cleanup_session:
+        try:
+            # Clean up test data (delete in correct order due to FK constraints)
+            await cleanup_session.execute(delete(SalesDaily))
+            await cleanup_session.execute(delete(InventorySnapshotDaily))
+            await cleanup_session.execute(delete(PriceHistory))
+            await cleanup_session.execute(delete(Promotion))
+            await cleanup_session.execute(delete(Product).where(Product.sku.like("SKU-TEST%")))
+            await cleanup_session.execute(delete(Product).where(Product.sku.like("TEST-%")))
+            await cleanup_session.execute(delete(Store).where(Store.code.like("TEST%")))
+            await cleanup_session.execute(
+                delete(Calendar).where(
+                    (Calendar.date >= date(2024, 1, 1)) & (Calendar.date <= date(2024, 12, 31))
+                )
+            )
+            await cleanup_session.commit()
+        except Exception as exc:
+            await cleanup_session.rollback()
+            pytest.fail(f"Test cleanup failed: {exc!r}")

examples/registry_demo.py (2)

54-65: Close the HTTP client on all exit paths.
This demo exits early in multiple branches; adding explicit close avoids leaking sockets.

Suggested fix

     client = httpx.Client(base_url=API_BASE, timeout=30)

     # Check API is running
     try:
         health = client.get("/health")
         if health.status_code != 200:
             print(f"API not healthy: {health.status_code}")
-            return 1
+            client.close()
+            return 1
     except httpx.ConnectError:
         print(f"Cannot connect to API at {API_BASE}")
         print("Start the API with: uv run uvicorn app.main:app --reload --port 8123")
-        return 1
+        client.close()
+        return 1
 ...
     if response.status_code != 201:
         print("\nFailed to create run. Exiting.")
-        return 1
+        client.close()
+        return 1
 ...
-    return 0
+    client.close()
+    return 0

Also applies to: 102-105, 247-247

---

116-121: Guard against non‑2xx responses before dereferencing JSON.
If any PATCH fails, run_data may be missing keys and the script will crash. Consider a quick status check (or raise_for_status) after each update/compare request.

Suggested pattern (apply to PATCH/GET requests as needed)

     response = client.patch(f"/registry/runs/{run_id}", json={"status": "running"})
     run_data = print_response(response, f"PATCH /registry/runs/{run_id}")
+    if response.status_code != 200:
+        client.close()
+        return 1

Also applies to: 145-151, 188-197