quality-studio 0.0.1__py3-none-any.whl

quality_studio/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

quality_studio/backend/__init__.py

@@ -0,0 +1,15 @@
+"""FastAPI backend (FR-10.1 / FR-10.2 / FR-10.3).
+
+`main.create_app()` returns the FastAPI ASGI app. `python -m
+quality_studio.backend` launches uvicorn bound to 127.0.0.1:9100
+(NFR-5.1) — the same entry point docker-compose uses.
+
+Startup config (target-repo path, DB DSN, Anthropic key) is resolved
+from environment variables at app-factory time; an invalid target-repo
+path fails fast at startup (FR-11.4 implementation-defined mechanism
+documented in `state.py`).
+"""
+
+from quality_studio.backend.main import create_app
+
+__all__ = ["create_app"]

quality_studio/backend/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m quality_studio.backend` entry — launches uvicorn."""
+
+from quality_studio.backend.main import main
+
+if __name__ == "__main__":
+    main()

quality_studio/backend/api/__init__.py

@@ -0,0 +1,6 @@
+"""API routers (FR-10.2, FR-10.3).
+
+Each module under `quality_studio.backend.api` exports a single
+`router: APIRouter` mounted by `backend.main.create_app` under `/api`.
+Routers are read-only except `runs.py`'s `POST /api/runs`.
+"""

quality_studio/backend/api/_deps.py

@@ -0,0 +1,77 @@
+"""Shared FastAPI dependencies for the api routers.
+
+v2.1 multi-target (#101/#102): pools live in `app.state.registry` keyed by
+target_id. `get_pool` is path-aware — when the matched route includes a
+`{target_id}` path parameter, it resolves that target's pool from the
+registry; when the legacy unprefixed route matches, it proxies to the
+first registered target. Handlers don't need to know which mount they're
+serving.
+"""
+
+from __future__ import annotations
+
+import asyncpg
+from fastapi import HTTPException, Request
+
+
+def get_pool(request: Request) -> asyncpg.Pool:
+    """Resolve the asyncpg pool for the current request.
+
+    Routing rules:
+    - When the matched path contains `{target_id}` (the v2.1 mount under
+      `/api/targets/{target_id}/...`), look up that target in the registry.
+      Unknown ids return 404.
+    - Otherwise (legacy mount under `/api/...`) proxy to the first
+      registered target. Lets existing UI tabs + scripts keep working
+      through the v2.1 → v3 deprecation window.
+    """
+    target_id = request.path_params.get("target_id")
+    registry = getattr(request.app.state, "registry", None)
+    if registry is None:
+        # Pre-v2.1 fallback path (e.g., a test that hasn't moved to the
+        # registry yet) — return the legacy singleton.
+        return request.app.state.pool
+
+    if target_id:
+        state = registry.get(target_id)
+        if state is None:
+            raise HTTPException(
+                status_code=404,
+                detail=f"target_id {target_id!r} not registered",
+            )
+        return state.pool
+
+    first = registry.first()
+    if first is None:
+        raise HTTPException(
+            status_code=503,
+            detail="no targets registered — run `quality init` in a target repo",
+        )
+    return first.pool
+
+
+def get_pool_for_target(target_id: str, request: Request) -> asyncpg.Pool:
+    """Explicit per-target pool dependency.
+
+    Equivalent to `get_pool` for prefixed routes, but takes `target_id` as
+    an explicit argument so handlers that want the parameter in their
+    signature can declare it. Same 404 / 503 semantics.
+    """
+    registry = getattr(request.app.state, "registry", None)
+    if registry is None:
+        raise HTTPException(status_code=503, detail="registry not initialised")
+    state = registry.get(target_id)
+    if state is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"target_id {target_id!r} not registered",
+        )
+    return state.pool
+
+
+def get_meta_pool(request: Request) -> asyncpg.Pool:
+    """Yield the shared `quality_meta` pool."""
+    registry = getattr(request.app.state, "registry", None)
+    if registry is None:
+        raise HTTPException(status_code=503, detail="registry not initialised")
+    return registry.meta_pool

quality_studio/backend/api/catalog.py

@@ -0,0 +1,160 @@
+"""GET /api/catalog (FR-10.2, v3.0 journey-composition model).
+
+Returns the domain catalog in the two-primitive model: domains → **steps**
+(atomic leaves carrying validations[] + risk_level + supported_levels[]) and
+**journeys** (recursive composition; each journey lists its ordered elements,
+where an element references either a step or a child journey). The shape is a
+single nested document the read-only UI renders without follow-up requests.
+
+Replaces the pre-v3 case/flow/story catalog (no alias shim — Vocabulary
+decision in the locked journey-composition-model doc).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import asyncpg
+from fastapi import APIRouter, Depends, Query
+
+from quality_studio.backend.api._deps import get_pool
+
+router = APIRouter(tags=["catalog"])
+
+
+def _maybe_json(value: Any) -> Any:
+    if isinstance(value, (str, bytes)):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return value
+    return value
+
+
+def _summarize_validations(validations: Any) -> dict[str, int]:
+    """Count validations[] by category — flat shape the UI renders as chips."""
+    if not isinstance(validations, list):
+        return {}
+    out: dict[str, int] = {}
+    for v in validations:
+        if isinstance(v, dict) and "category" in v:
+            out[v["category"]] = out.get(v["category"], 0) + 1
+    return out
+
+
+async def _load_catalog(
+    pool: asyncpg.Pool,
+    *,
+    domain: str | None,
+    risk_level: str | None,
+) -> list[dict[str, Any]]:
+    """Return the catalog as a list of per-domain dicts. The `risk_level`
+    filter applies at the step level — a domain still appears even if every
+    step is filtered out, so the UI shows the empty-state rather than mistaking
+    a filtered domain for a missing one."""
+    domain_args: list[Any] = []
+    domain_where = ""
+    if domain is not None:
+        domain_args.append(domain)
+        domain_where = "WHERE domain_id = $1"
+
+    async with pool.acquire() as conn:
+        domains = await conn.fetch(
+            f"SELECT domain_id, name, owner_team FROM quality_domains {domain_where} "
+            "ORDER BY domain_id",
+            *domain_args,
+        )
+        step_args: list[Any] = []
+        step_clauses: list[str] = []
+        if domain is not None:
+            step_args.append(domain)
+            step_clauses.append(f"domain_id = ${len(step_args)}")
+        if risk_level is not None:
+            step_args.append(risk_level)
+            step_clauses.append(f"risk_level = ${len(step_args)}")
+        step_where = "WHERE " + " AND ".join(step_clauses) if step_clauses else ""
+        steps = await conn.fetch(
+            f"""
+            SELECT step_id, domain_id, intent, risk_level, validations,
+                   supported_levels, metadata
+            FROM quality_steps {step_where} ORDER BY step_id
+            """,
+            *step_args,
+        )
+        journey_args: list[Any] = []
+        journey_where = ""
+        if domain is not None:
+            journey_args.append(domain)
+            journey_where = "WHERE domain_id = $1"
+        journeys = await conn.fetch(
+            f"""
+            SELECT journey_id, domain_id, title, kind, description
+            FROM quality_journeys {journey_where} ORDER BY journey_id
+            """,
+            *journey_args,
+        )
+        elements = await conn.fetch(
+            "SELECT journey_id, position, step_id, child_journey_id "
+            "FROM quality_journey_elements ORDER BY journey_id, position"
+        )
+
+    by_domain: dict[str, dict[str, Any]] = {
+        r["domain_id"]: {
+            "domain_id": r["domain_id"],
+            "name": r["name"],
+            "owner_team": r["owner_team"],
+            "steps": [],
+            "journeys": [],
+        }
+        for r in domains
+    }
+    for s in steps:
+        if s["domain_id"] not in by_domain:
+            continue
+        meta = _maybe_json(s["metadata"]) or {}
+        by_domain[s["domain_id"]]["steps"].append(
+            {
+                "step_id": s["step_id"],
+                "intent": s["intent"],
+                "risk_level": s["risk_level"],
+                "supported_levels": list(s["supported_levels"])
+                if s["supported_levels"] is not None
+                else [],
+                "outcome": meta.get("outcome") if isinstance(meta, dict) else None,
+                "validation_summary": _summarize_validations(_maybe_json(s["validations"])),
+            }
+        )
+
+    elements_by_journey: dict[str, list[dict[str, Any]]] = {}
+    for e in elements:
+        elements_by_journey.setdefault(e["journey_id"], []).append(
+            {
+                "position": e["position"],
+                "step_id": e["step_id"],
+                "child_journey_id": e["child_journey_id"],
+            }
+        )
+    for j in journeys:
+        if j["domain_id"] not in by_domain:
+            continue
+        by_domain[j["domain_id"]]["journeys"].append(
+            {
+                "journey_id": j["journey_id"],
+                "title": j["title"],
+                "kind": j["kind"],
+                "description": j["description"],
+                "elements": elements_by_journey.get(j["journey_id"], []),
+            }
+        )
+    return list(by_domain.values())
+
+
+@router.get("/catalog")
+async def get_catalog(
+    domain: str | None = Query(None),
+    risk_level: str | None = Query(None),
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> dict[str, Any]:
+    domains = await _load_catalog(pool, domain=domain, risk_level=risk_level)
+    return {"domains": domains}

quality_studio/backend/api/changesets.py

@@ -0,0 +1,103 @@
+"""GET /api/changesets (FR-10.2) + GET /api/changesets/{change_set_id}."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+import asyncpg
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from quality_studio.backend.api._deps import get_pool
+
+router = APIRouter(tags=["changesets"])
+
+
+@router.get("/changesets")
+async def list_changesets(
+    issue: str | None = Query(None, description="filter by github_issue_url"),
+    pr: str | None = Query(None, description="filter by github_pr_url"),
+    since: datetime | None = Query(None, description="ISO-8601 lower bound on created_at"),
+    limit: int = Query(50, ge=1, le=500),
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> dict[str, Any]:
+    args: list[Any] = []
+    clauses: list[str] = []
+    if issue is not None:
+        args.append(issue)
+        clauses.append(f"github_issue_url = ${len(args)}")
+    if pr is not None:
+        args.append(pr)
+        clauses.append(f"github_pr_url = ${len(args)}")
+    if since is not None:
+        args.append(since)
+        clauses.append(f"created_at >= ${len(args)}")
+    where = "WHERE " + " AND ".join(clauses) if clauses else ""
+    args.append(limit)
+    limit_pos = len(args)
+
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            f"""
+            SELECT change_set_id, github_issue_url, github_pr_url, commit_sha,
+                   author, summary, model, prompt_version, generation_run_id,
+                   created_at
+            FROM quality_change_sets
+            {where}
+            ORDER BY created_at DESC
+            LIMIT ${limit_pos}
+            """,
+            *args,
+        )
+    return {"changesets": [_row_to_dict(r) for r in rows]}
+
+
+@router.get("/changesets/{change_set_id}")
+async def get_changeset(
+    change_set_id: str,
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> dict[str, Any]:
+    """Single change-set lookup for `<ChangesetBadge>` (epic #67 / child #71).
+
+    Returns 404 with a structured body when the id is unknown or malformed.
+    """
+    try:
+        cs_uuid = UUID(change_set_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=404,
+            detail={"error": "invalid change_set_id", "value": change_set_id},
+        ) from exc
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            """
+            SELECT change_set_id, github_issue_url, github_pr_url, commit_sha,
+                   author, summary, model, prompt_version, generation_run_id,
+                   created_at
+            FROM quality_change_sets
+            WHERE change_set_id = $1
+            """,
+            cs_uuid,
+        )
+    if row is None:
+        raise HTTPException(
+            status_code=404,
+            detail={"error": "change_set not found", "value": change_set_id},
+        )
+    return _row_to_dict(row)
+
+
+def _row_to_dict(r: asyncpg.Record) -> dict[str, Any]:
+    return {
+        "change_set_id": str(r["change_set_id"]),
+        "github_issue_url": r["github_issue_url"],
+        "github_pr_url": r["github_pr_url"],
+        "commit_sha": r["commit_sha"],
+        "author": r["author"],
+        "summary": r["summary"],
+        "model": r["model"],
+        "prompt_version": r["prompt_version"],
+        "generation_run_id": (str(r["generation_run_id"]) if r["generation_run_id"] else None),
+        "created_at": r["created_at"].isoformat(),
+    }

quality_studio/backend/api/coverage.py

@@ -0,0 +1,103 @@
+"""GET /api/coverage + /api/coverage/live (FR-10.2, FR-7.4, v3.0).
+
+`/api/coverage` returns the per-step coverage matrix (step_id × domain × risk ×
+supported_levels × outcome) read from `quality_steps`. `/api/coverage/live`
+overlays the latest per-step result status via `runs.live_coverage` (FR-7.4) —
+status is the newest per-step result; the authoritative above-unit signal is
+the journey-run verdict (`quality_runs`).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import asyncpg
+from fastapi import APIRouter, Depends, Query
+
+from quality_studio.backend.api._deps import get_pool
+from quality_studio.runs import live_coverage
+
+router = APIRouter(tags=["coverage"])
+
+
+def _outcome(metadata: Any) -> str | None:
+    if isinstance(metadata, (str, bytes)):
+        try:
+            metadata = json.loads(metadata)
+        except json.JSONDecodeError:
+            return None
+    return metadata.get("outcome") if isinstance(metadata, dict) else None
+
+
+@router.get("/coverage")
+async def get_coverage(
+    domain: str | None = Query(None),
+    environment: str | None = Query(  # noqa: ARG001
+        None,
+        description="environment filter — currently passthrough to /live; the "
+        "static matrix is environment-agnostic by design",
+    ),
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> dict[str, Any]:
+    args: list[Any] = []
+    where = ""
+    if domain is not None:
+        args.append(domain)
+        where = "WHERE domain_id = $1"
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            f"""
+            SELECT domain_id, step_id, risk_level, supported_levels, metadata
+            FROM quality_steps {where} ORDER BY step_id
+            """,
+            *args,
+        )
+    return {
+        "rows": [
+            {
+                "domain_id": r["domain_id"],
+                "step_id": r["step_id"],
+                "risk_level": r["risk_level"],
+                "supported_levels": list(r["supported_levels"])
+                if r["supported_levels"] is not None
+                else [],
+                "outcome": _outcome(r["metadata"]),
+            }
+            for r in rows
+        ]
+    }
+
+
+@router.get("/coverage/live")
+async def get_coverage_live(
+    domain: str = Query(..., description="domain_id is required for live coverage"),
+    window: str | None = Query(
+        None,
+        description="window like '30d'; only `<n>d` is parsed in v1",
+        pattern=r"^\d+d$",
+    ),
+    environment: str | None = Query(None),
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> dict[str, Any]:
+    window_days = int(window.rstrip("d")) if window else None
+    rows = await live_coverage(
+        pool, domain_id=domain, window_days=window_days, environment=environment
+    )
+    return {
+        "domain_id": domain,
+        "window_days": window_days,
+        "environment": environment,
+        "rows": [
+            {
+                "step_id": r.step_id,
+                "domain_id": r.domain_id,
+                "risk_level": r.risk_level,
+                "last_run_status": r.last_run_status,
+                "last_run_at": r.last_run_at.isoformat() if r.last_run_at else None,
+                "last_environment": r.last_environment,
+                "last_level": r.last_level,
+            }
+            for r in rows
+        ],
+    }

quality_studio/backend/api/data.py

@@ -0,0 +1,148 @@
+"""GET /api/data[?domain=][/{name}] (FR-10.3 / FR-11.4, v3.0).
+
+Data list calls the target's `data_introspect_cmd` from `[data_generation]` in
+quality.toml and returns the parsed JSON. Data detail reads source via
+`target_repo.py.read_text` (FR-2.1 boundary) — the backend NEVER imports a data
+module. The detail handler resolves source path with this precedence:
+
+1. `file` field in the introspection metadata (if the target's
+   `data_introspect_cmd` populates it);
+2. fallback: `{output_dir_template}/{name}.py` from `[data_generation]` in
+   quality.toml, with `{domain}` substituted.
+
+This is the v3.0 rename of the pre-v3 `[seed_generation]` / `/api/seeds` surface
+(data = per-level test data bound to steps).
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query, Request, status
+
+from quality_studio.config import load_target_config
+from quality_studio.target_repo import TargetPathError
+
+router = APIRouter(tags=["data"])
+
+_INTROSPECT_TIMEOUT_SECONDS = 30.0
+
+
+def _run_introspect(cmd: str, *, cwd) -> list[dict[str, Any]]:
+    """Execute the configured introspection command and parse its JSON output."""
+    try:
+        completed = subprocess.run(  # noqa: S603 - cmd comes from operator-controlled toml
+            shlex.split(cmd),
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            timeout=_INTROSPECT_TIMEOUT_SECONDS,
+        )
+    except (subprocess.TimeoutExpired, OSError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"data_introspect_cmd execution failed: {exc!s}",
+        ) from exc
+    if completed.returncode != 0:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"data_introspect_cmd exited {completed.returncode}: {completed.stderr.strip()}",
+        )
+    try:
+        parsed = json.loads(completed.stdout or "{}")
+    except json.JSONDecodeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"data_introspect_cmd output is not JSON: {exc!s}",
+        ) from exc
+    items = parsed.get("data")
+    if not isinstance(items, list):
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="data_introspect_cmd output missing top-level 'data' list",
+        )
+    return items
+
+
+def _resolve_source_relpath(
+    *, data_meta: dict[str, Any], name: str, domain: str, data_generation: dict[str, Any]
+) -> str:
+    """Resolve the relative source path with the precedence documented above."""
+    explicit = data_meta.get("file") or data_meta.get("path")
+    if explicit:
+        return str(explicit)
+    template = data_generation.get("output_dir_template", "data/{domain}/")
+    base = template.format(domain=domain).rstrip("/")
+    return f"{base}/{name}.py"
+
+
+@router.get("/data")
+async def list_data(
+    request: Request,
+    domain: str = Query(..., description="domain_id; required for the introspect command lookup"),
+) -> dict[str, Any]:
+    target_repo = request.app.state.backend.target_repo
+    config = load_target_config(target_repo)
+    cmd = config.data_generation.get("data_introspect_cmd")
+    if not cmd:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="quality.toml [data_generation].data_introspect_cmd is not set",
+        )
+    items = _run_introspect(cmd, cwd=target_repo.root)
+    # Tag each entry with domain so the UI doesn't have to thread it.
+    for entry in items:
+        entry.setdefault("domain", domain)
+    return {"domain": domain, "data": items}
+
+
+@router.get("/data/{name}")
+async def get_data_detail(
+    request: Request,
+    name: str,
+    domain: str = Query(..., description="domain_id; required for source-path resolution"),
+) -> dict[str, Any]:
+    target_repo = request.app.state.backend.target_repo
+    config = load_target_config(target_repo)
+    cmd = config.data_generation.get("data_introspect_cmd")
+    if not cmd:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="quality.toml [data_generation].data_introspect_cmd is not set",
+        )
+    items = _run_introspect(cmd, cwd=target_repo.root)
+    match = next((d for d in items if d.get("name") == name), None)
+    if match is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"data module {name!r} not found in domain {domain!r}",
+        )
+    relpath = _resolve_source_relpath(
+        data_meta=match,
+        name=name,
+        domain=domain,
+        data_generation=config.data_generation,
+    )
+    try:
+        source = target_repo.read_text(relpath)
+    except TargetPathError as exc:
+        # Path outside the target root, or unsafe glob — refuse, never silently fall back.
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"data source path rejected: {exc!s}",
+        ) from exc
+    except FileNotFoundError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"data source file not found at {relpath!r}",
+        ) from exc
+    return {
+        "domain": domain,
+        "name": name,
+        "source_path": relpath,
+        "source": source,
+        "metadata": match,
+    }