P11-S6: ship tier-2 packs and launch clarity assets (#141)

Co-authored-by: Sami Rusani <sr@samirusani>

Author: samrusani

BUILD_REPORT.md

@@ -1,73 +1,65 @@
 # BUILD_REPORT
 
 ## sprint objective
-Implement P11-S5: Azure Adapter + AutoGen Integration through the existing provider abstraction by adding Azure provider registration/test/invoke support, enterprise credential/auth hardening, Azure capability posture fields, and AutoGen integration documentation/sample path.
+Implement `P11-S6` by adding tier-2 model packs (DeepSeek, Kimi, Mistral) on the shipped model-pack abstraction, plus compatibility/setup clarity assets for local, self-hosted, enterprise, and external-agent paths, without reopening `P11-S1` through `P11-S5` architecture.
 
 ## completed work
-- Added Azure provider adapter support in the runtime adapter registry (`provider_key: azure`) with normalized capability discovery and invoke behavior using the existing `openai_responses` runtime contract.
-- Added Azure-specific helper module for:
-  - auth header handling (`azure_api_key`, `azure_ad_token`)
-  - `api-version` query handling
-  - model enumeration payload parsing
-  - OpenAI-compatible responses invoke payload/response normalization
-- Added additive provider data fields and migration support:
-  - `model_providers.azure_api_version`
-  - `model_providers.azure_auth_secret_ref`
-  - expanded `model_providers.auth_mode` constraint to include Azure auth modes
-- Added Azure secret-reference credential handling in runtime secret resolution:
-  - Azure modes now resolve credentials from `azure_auth_secret_ref`
-  - plaintext Azure credentials are not persisted in provider rows
-- Added Azure registration endpoint:
-  - `POST /v1/providers/azure/register`
-  - strict auth payload validation (mode-specific field requirements)
-- Preserved existing provider/runtime seams and behavior for shipped P11-S1 through P11-S4 paths.
-- Added Azure capability snapshot posture fields:
-  - `azure_api_version`
-  - `azure_auth_mode`
-- Added docs and sample integration path:
-  - Azure + AutoGen integration guide in `docs/integrations/phase11-azure-autogen.md`
-  - runtime bridge sample in `scripts/run_phase11_autogen_runtime_bridge.py`
-- Updated control-doc truth checker markers to P11-S5 active-sprint truth so required truth checks pass.
+- Added tier-2 built-in pack specs in `model_packs.py`:
+  - `deepseek@1.0.0`
+  - `kimi@1.0.0`
+  - `mistral@1.0.0`
+- Preserved shipped pack API behavior and selection semantics:
+  - seeded catalog still resolves through existing `/v1/model-packs` flow
+  - workspace binding and request override precedence are unchanged
+  - no new runtime/provider paths were introduced
+- Extended family contract/type support for tier-2 families:
+  - `deepseek`, `kimi`, `mistral`
+- Added additive migration `20260412_0056_phase11_model_packs_tier2_families.py` to widen `model_packs_family_check` without schema redesign.
+- Updated catalog reservation conflict text to cover built-in catalog entries (tier-1 + tier-2).
+- Added/updated sprint docs:
+  - `docs/integrations/phase11-model-pack-compatibility.md` with provider/pack compatibility matrices
+  - `docs/integrations/phase11-setup-paths.md` with operator setup paths for local, self-hosted, enterprise, and external-agent use
+  - `docs/integrations/phase11-azure-autogen.md` guardrails/references refreshed for P11-S6
+- Updated sprint-owned tests for tier-2 catalog presence, runtime override behavior, and migration coverage.
+- Updated control-doc truth checker markers to active `P11-S6` packet/state markers.
+- Updated `REVIEW_REPORT.md` for `P11-S6`.
 
 ## incomplete work
 - None within the sprint packet scope.
 
 ## files changed
-- `apps/api/src/alicebot_api/azure_provider_helpers.py` (new)
-- `apps/api/src/alicebot_api/provider_runtime.py`
-- `apps/api/src/alicebot_api/main.py`
-- `apps/api/src/alicebot_api/store.py`
+- `apps/api/src/alicebot_api/model_packs.py`
 - `apps/api/src/alicebot_api/contracts.py`
-- `apps/api/alembic/versions/20260412_0055_phase11_azure_provider_config_fields.py` (new)
-- `tests/unit/test_provider_runtime.py`
-- `tests/integration/test_phase11_provider_runtime_api.py`
-- `tests/unit/test_20260412_0055_phase11_azure_provider_config_fields.py` (new)
-- `docs/integrations/phase11-azure-autogen.md` (new)
-- `scripts/run_phase11_autogen_runtime_bridge.py` (new)
+- `apps/api/src/alicebot_api/main.py`
+- `apps/api/alembic/versions/20260412_0056_phase11_model_packs_tier2_families.py` (new)
+- `tests/unit/test_model_packs.py`
+- `tests/integration/test_phase11_model_packs_api.py`
+- `tests/unit/test_20260412_0056_phase11_model_packs_tier2_families.py` (new)
+- `docs/integrations/phase11-model-pack-compatibility.md`
+- `docs/integrations/phase11-setup-paths.md` (new)
+- `docs/integrations/phase11-azure-autogen.md`
 - `scripts/check_control_doc_truth.py`
-- `README.md`
-- `BUILD_REPORT.md`
 - `REVIEW_REPORT.md`
+- `BUILD_REPORT.md`
 
 ## tests run
 1. `python3 scripts/check_control_doc_truth.py`
 - Result: PASS
 
 2. `./.venv/bin/python -m pytest tests/unit tests/integration -q`
-- Result: PASS (`1142 passed in 196.54s (0:03:16)`)
+- Result: PASS (`1145 passed in 185.18s (0:03:05)`)
 
 3. `pnpm --dir apps/web test`
-- Result: PASS (`62 passed`, `199 passed`, duration `4.62s`)
+- Result: PASS (`62 files`, `199 tests passed`, duration `5.49s`)
 
 4. Focused sprint tests during implementation:
-- `./.venv/bin/python -m pytest tests/unit/test_provider_runtime.py tests/unit/test_provider_secrets.py tests/unit/test_20260412_0055_phase11_azure_provider_config_fields.py tests/integration/test_phase11_provider_runtime_api.py -q`
-- Result: PASS (`20 passed`)
+- `./.venv/bin/python -m pytest tests/unit/test_model_packs.py tests/integration/test_phase11_model_packs_api.py tests/unit/test_20260412_0056_phase11_model_packs_tier2_families.py -q`
+- Result: PASS (`14 passed in 1.62s`)
 
 ## blockers/issues
 - No functional blockers for sprint scope implementation.
-- Pre-existing dirty files not modified as sprint work and excluded from sprint merge scope:
-  - `ARCHITECTURE.md`
-  - `PRODUCT_BRIEF.md`
+- Pre-existing dirty file not modified as sprint work and excluded from sprint merge scope:
+  - `README.md`
 
 ## recommended next step
-Proceed to Control Tower merge approval for `P11-S5`, then run staging validation against a live Azure endpoint for both `azure_api_key` and `azure_ad_token` registration/invoke flows before production rollout.
+Proceed to merge review for `P11-S6`, then run staging smoke checks for one local provider, one self-hosted OpenAI-compatible provider, and one Azure provider with tier-2 and custom pack coverage.

REVIEW_REPORT.md

@@ -4,45 +4,49 @@
 PASS
 
 ## criteria met
-- `POST /v1/providers/azure/register` is implemented and validated with strict auth-mode payload checks.
-- Azure provider registration/test/invoke flows are covered through shipped APIs:
-  - `POST /v1/providers/azure/register`
-  - `POST /v1/providers/test`
-  - `POST /v1/runtime/invoke`
-  - `GET /v1/providers`
-  - `GET /v1/providers/{provider_id}`
-- Credential/auth hardening is implemented for Azure:
-  - Azure credentials are persisted via secret references (`azure_auth_secret_ref`)
-  - Integration tests verify no plaintext Azure credential leakage in `model_providers`
-- Azure invoke path uses the existing normalized provider abstraction/adapter registry (no continuity-semantic fork).
-- Azure capability posture additions are present (`azure_api_version`, `azure_auth_mode`).
-- AutoGen integration guide and sample path are present:
-  - `docs/integrations/phase11-azure-autogen.md`
-  - `scripts/run_phase11_autogen_runtime_bridge.py`
-- Required verification commands pass (re-run after fix):
-  - `python3 scripts/check_control_doc_truth.py` ✅
-  - `./.venv/bin/python -m pytest tests/unit tests/integration -q` ✅ (`1142 passed in 196.54s`)
-  - `pnpm --dir apps/web test` ✅ (`62 files / 199 tests passed`, duration `4.62s`)
-- Local identifier check: no local machine paths/usernames found in sprint-owned changed files.
+- Tier-2 packs are implemented on the existing model-pack seam: `deepseek@1.0.0`, `kimi@1.0.0`, `mistral@1.0.0` (`apps/api/src/alicebot_api/model_packs.py`).
+- Family contract support is added additively in code + DB constraint migration (no provider/runtime redesign):
+  - `apps/api/src/alicebot_api/contracts.py`
+  - `apps/api/alembic/versions/20260412_0056_phase11_model_packs_tier2_families.py`
+- Pack listing/detail/binding/invoke flows remain on shipped APIs and semantics:
+  - workspace default binding still applies when no request override is provided
+  - request-level pack override still takes precedence
+  - reserved built-in catalog IDs/versions are blocked from custom create
+- Compatibility and launch-clarity docs are present and within sprint scope:
+  - `docs/integrations/phase11-model-pack-compatibility.md`
+  - `docs/integrations/phase11-setup-paths.md`
+  - `docs/integrations/phase11-azure-autogen.md` (guardrail/reference update)
+- Sprint tests cover tier-2 catalog presence, runtime shaping override path, and migration statements:
+  - `tests/unit/test_model_packs.py`
+  - `tests/integration/test_phase11_model_packs_api.py`
+  - `tests/unit/test_20260412_0056_phase11_model_packs_tier2_families.py`
+- Required verification commands were executed and passed:
+  - `python3 scripts/check_control_doc_truth.py` -> PASS
+  - `./.venv/bin/python -m pytest tests/unit tests/integration -q` -> `1145 passed in 185.18s`
+  - `pnpm --dir apps/web test` -> `62 files passed, 199 tests passed in 5.49s`
+- Local identifier sweep on sprint-owned changes found no leaked local computer paths/usernames.
 
 ## criteria missed
 - None.
 
 ## quality issues
-- None blocking or non-blocking found in sprint-owned implementation after scope cleanup.
+- None blocking for `P11-S6`.
+- Overreach check: no new provider adapters, no new framework integrations beyond shipped AutoGen path, and no product-surface expansion detected.
 
 ## regression risks
-- Low residual risk: Azure behavior is validated in mocked integration tests; live-endpoint staging validation is still recommended for environment-specific routing/auth nuances.
+- Low: compatibility posture is declarative/documented, but real provider/model availability is deployment-dependent and should still be smoke-tested per environment.
 
 ## docs issues
-- Sprint docs are present and scoped correctly for P11-S5.
+- No scope violations found in sprint docs.
+- Process note: `README.md` is currently dirty in the workspace; ensure only intended sprint files are included in merge scope.
 
 ## should anything be added to RULES.md?
-- Optional improvement: add a standing rule that sprint PRs must exclude unrelated dirty local files before review.
+- No.
 
 ## should anything update ARCHITECTURE.md?
-- No required architecture update for P11-S5 acceptance.
+- No.
 
 ## recommended next action
-1. Proceed with sprint merge review/approval for `P11-S5`.
-2. Run staging smoke validation against live Azure for both `azure_api_key` and `azure_ad_token` before production rollout.
+1. Approve `P11-S6` for merge.
+2. Before merge, confirm the final PR file list excludes unrelated dirty files.
+3. Run staging smoke checks across one local provider path, one self-hosted openai-compatible path, and one Azure path using tier-2 pack bind/override flows.

apps/api/alembic/versions/20260412_0056_phase11_model_packs_tier2_families.py

@@ -0,0 +1,40 @@
+"""Expand model-pack family constraint for Phase 11 tier-2 packs."""
+
+from __future__ import annotations
+
+from alembic import op
+
+
+revision = "20260412_0056"
+down_revision = "20260412_0055"
+branch_labels = None
+depends_on = None
+
+_UPGRADE_STATEMENTS = (
+    "ALTER TABLE model_packs DROP CONSTRAINT IF EXISTS model_packs_family_check",
+    (
+        "ALTER TABLE model_packs ADD CONSTRAINT model_packs_family_check "
+        "CHECK (family IN ('llama', 'qwen', 'gemma', 'gpt-oss', 'deepseek', 'kimi', 'mistral', 'custom'))"
+    ),
+)
+
+_DOWNGRADE_STATEMENTS = (
+    "ALTER TABLE model_packs DROP CONSTRAINT IF EXISTS model_packs_family_check",
+    (
+        "ALTER TABLE model_packs ADD CONSTRAINT model_packs_family_check "
+        "CHECK (family IN ('llama', 'qwen', 'gemma', 'gpt-oss', 'custom'))"
+    ),
+)
+
+
+def _execute_statements(statements: tuple[str, ...]) -> None:
+    for statement in statements:
+        op.execute(statement)
+
+
+def upgrade() -> None:
+    _execute_statements(_UPGRADE_STATEMENTS)
+
+
+def downgrade() -> None:
+    _execute_statements(_DOWNGRADE_STATEMENTS)

apps/api/src/alicebot_api/contracts.py

@@ -192,7 +192,16 @@
 ProviderAdapterKey = Literal["openai_compatible", "ollama", "llamacpp", "azure"]
 ModelProviderStatus = Literal["active"]
 ProviderCapabilityDiscoveryStatus = Literal["ready", "failed"]
-ModelPackFamily = Literal["llama", "qwen", "gemma", "gpt-oss", "custom"]
+ModelPackFamily = Literal[
+    "llama",
+    "qwen",
+    "gemma",
+    "gpt-oss",
+    "deepseek",
+    "kimi",
+    "mistral",
+    "custom",
+]
 ModelPackStatus = Literal["active"]
 ModelPackBindingSource = Literal["manual", "runtime_override"]
 ModelFinishReason = Literal["completed", "incomplete"]

apps/api/src/alicebot_api/main.py

@@ -7022,7 +7022,7 @@ def create_v1_model_pack(request: Request, body: CreateModelPackRequest) -> JSON
                         content={
                             "detail": (
                                 f"model pack {normalized_pack_id}@{normalized_pack_version} "
-                                "is reserved for tier-1 catalog entries"
+                                "is reserved for built-in catalog entries"
                             )
                         },
                     )