feat(controls): shared get_controls_for_use_case retrieval API

Read-only layer (service + thin route + tests) that returns the controls
mapped to a use-case/topic, ranked by a deterministic precision proxy
(is_primary + mapping confidence + registry keyword relevance) over the
existing mc_use_case_mappings seed. No schema change.

Shared handoff point: the document specialist agents AND the CRA
finding-mapper draw from this one controls index instead of separate
retrievals.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
2026-06-13 21:37:18 +02:00
parent 43ae33975d
commit a4b405077f
4 changed files with 268 additions and 0 deletions
@@ -0,0 +1,49 @@
"""Use-Case → Controls API — the shared retrieval layer.
GET /v1/controls/use-cases — registry + mapped counts
GET /v1/controls/use-cases/{use_case}/controls — ranked controls of a topic
Consumed by the document specialist agents and the CRA finding-mapper so both
draw from ONE controls index instead of separate retrievals. Read-only.
"""
from __future__ import annotations
from typing import Any
from fastapi import APIRouter, Depends, Query
from sqlalchemy.orm import Session
from classroom_engine.database import get_db
from compliance.api._http_errors import translate_domain_errors
from compliance.services.use_case_controls import UseCaseControlsService
router = APIRouter(prefix="/v1/controls", tags=["use-case-controls"])
def get_use_case_controls_service(
db: Session = Depends(get_db),
) -> UseCaseControlsService:
return UseCaseControlsService(db)
@router.get("/use-cases")
async def list_use_cases(
svc: UseCaseControlsService = Depends(get_use_case_controls_service),
) -> list[dict[str, Any]]:
"""All enabled use-cases (topics) with their live mapped-control counts."""
with translate_domain_errors():
return svc.list_use_cases()
@router.get("/use-cases/{use_case}/controls")
async def controls_for_use_case(
use_case: str,
primary_only: bool = Query(False, description="Nur Primaerzweck-Mappings"),
limit: int = Query(50, ge=1, le=200),
offset: int = Query(0, ge=0),
svc: UseCaseControlsService = Depends(get_use_case_controls_service),
) -> dict[str, Any]:
"""Controls mapped to a topic, ranked by the deterministic precision proxy."""
with translate_domain_errors():
return svc.controls_for_use_case(use_case, primary_only, limit, offset)