Milestone 11 of 12

CineQC integration and operation

Expose the detector as a bounded, observable local service.

Operational route

versioned requestfallback + reviewsafe response

Turn the selected detector into a bounded local service. Required route: contracts (70 min), service build (95 min), fallback and review (65 min), privacy/observability (55 min), local smoke and CineQC handoff (70 min), selected reading (65 min). Total: 7 hours.

Entry diagnostic

Trace one malformed request and one unavailable-model request through validation, structured failure, heuristic fallback, and human-review routing. Name what the client can rely on.

Self-check

Why must the response identify both API version and model version?

Why this matters in CineQC

A model file is not an integration. CineQC needs stable contracts, observable timing, recoverable failure, a privacy boundary, and a reviewer-visible reason for every route. The integration does not replace the human rubric; it supplies evidence and a recommendation.

Visual model — request to review route

Follow sanitized media reference → v1 validation → detector → heuristic fallback → review policy → v1 response. The request contains a public fixture ID or approved local opaque reference, never raw private media in logs. The response contains contract version, model identity, model version, score, route, latency, warnings, and a correlation ID.

Success, fallback, and structured failure share one versioned response shape. The request forbids undeclared fields. Its fixture ID is an opaque 1–80 character token containing only ASCII letters, digits, underscore, or hyphen—not a Windows path, POSIX path, URI, control character, filename, or private media value. Validation failures return a fixed error envelope and never echo rejected input. A fallback is not model success: set route="heuristic_fallback", include a warning, and route uncertain results to human review. Invalid requests return stable error codes. Unexpected internal details stay server-side.

Runtime: Local Python 3.12 · FastAPI 0.115.12 + Pydantic 2.x · CPU-safe TestClient · 35 min.

from time import perf_counter
from typing import Literal
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.testclient import TestClient
from fastapi.responses import JSONResponse
from pydantic import BaseModel, ConfigDict, Field

app = FastAPI()

class DetectV1(BaseModel):
    model_config = ConfigDict(extra="forbid")
    contract_version: Literal["1.0"]
    fixture_id: str = Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$")
    force_fallback: bool = False

class ErrorV1(BaseModel):
    code: Literal["INVALID_CONTRACT", "MEDIA_NOT_APPROVED"]
    retryable: bool

class DetectResponseV1(BaseModel):
    model_config = ConfigDict(extra="forbid")
    contract_version: Literal["1.0"] = "1.0"
    correlation_id: str
    model_identity: str | None = None
    model_version: str | None = None
    score: float | None = None
    route: Literal["model", "heuristic_fallback", "failure"]
    human_review: bool
    latency_ms: float | None = None
    warning: str | None = None
    error: ErrorV1 | None = None

def failure(code):
    return DetectResponseV1(correlation_id="demo-request-01", route="failure",
                            human_review=True,
                            error=ErrorV1(code=code, retryable=False))

@app.exception_handler(RequestValidationError)
async def invalid_contract(_request: Request, _error: RequestValidationError):
    return JSONResponse(status_code=422,
                        content=failure("INVALID_CONTRACT").model_dump())

@app.post("/v1/detect", response_model=DetectResponseV1,
          responses={403: {"model": DetectResponseV1},
                     422: {"model": DetectResponseV1}})
def detect(request: DetectV1):
    if request.fixture_id == "forbidden":
        return JSONResponse(status_code=403,
                            content=failure("MEDIA_NOT_APPROVED").model_dump())
    started = perf_counter()
    route = "heuristic_fallback" if request.force_fallback else "model"
    score = 0.42 if request.force_fallback else 0.83
    return DetectResponseV1(correlation_id="demo-request-01",
            model_identity="semantic-text", model_version="demo-1",
            score=score, route=route,
            human_review=request.force_fallback or 0.35 <= score <= 0.65,
            latency_ms=round((perf_counter() - started) * 1000, 3),
            warning="model unavailable" if request.force_fallback else None)

client = TestClient(app)
assert client.post("/v1/detect", json={"contract_version":"1.0", "fixture_id":"public-01"}).json()["route"] == "model"
assert client.post("/v1/detect", json={"contract_version":"1.0", "fixture_id":"public-01", "force_fallback":True}).json()["route"] == "heuristic_fallback"
assert client.post("/v1/detect", json={"contract_version":"1.0", "fixture_id":"forbidden"}).json()["route"] == "failure"
bad_version = client.post("/v1/detect", json={"contract_version":"2.0", "fixture_id":"public-01"})
assert bad_version.status_code == 422 and bad_version.json()["route"] == "failure"

Self-check

What log fields prove operation without exposing a filename, frame, prompt, transcript, or private media?

Privacy-safe observability and structured failures

Log timestamp, correlation ID, contract version, a synthetic public fixture ID or request-scoped opaque token, model identity/version, route, latency, result band, error code, and review decision. The token must not encode or reveal a private path or media identity. Logs are without private media: exclude media bytes, frames, thumbnails, full local paths, recognized text, prompts, and user notes. Configure retention and access; redaction is tested, not assumed.

Use structured failure codes such as INVALID_CONTRACT, MEDIA_NOT_APPROVED, MODEL_UNAVAILABLE, and INFERENCE_TIMEOUT, each with safe message, retryable flag, and correlation ID. Record latency as a distribution (median and p95 on the public fixture), not one heroic timing.

Sandbox lab

Package the API, detector adapter, heuristic adapter, review policy, configuration, and tests as separate modules. Test valid request, invalid contract, forbidden media, timeout, model unavailable, fallback, uncertainty-band review, privacy-safe logs, and client handling. Run an end-to-end local workflow from a public fixture through the API to a CineQC display adapter.

Then perform the graduation run locally on the RTX 4080. Record GPU, driver, CUDA, framework, checkpoint, request contract, median/p95 latency, and memory peak. The contract tests remain CPU-safe; GPU output proves the deployment path, not their correctness.

Runtime: Local PowerShell · RTX 4080 graduation smoke; explicit CPU fallback · 10 min.

python -c "import torch; ok=torch.cuda.is_available(); print({'device':torch.cuda.get_device_name(0) if ok else 'cpu','torch':torch.__version__,'cuda':torch.version.cuda,'smoke':'gpu' if ok else 'cpu-fallback'})"

Failure clinic

Repair a response whose fields change with route; logs containing local paths or OCR text; model timeout reported as a negative prediction; fallback labeled as model output; absent version identity; a client that ignores non-200 responses; unbounded retries; an uncertainty band silently accepted; and a GPU-only test suite. Preserve the last known-good contract while fixing internals.

CineQC transfer

Add one bounded panel that displays semantic score, route, version, latency, warning, and human-review recommendation alongside existing deterministic and temporal evidence. The adapter accepts only the versioned response. It does not upload media, train models, alter private assets, auto-approve output, or replace the human rubric. An architecture walkthrough identifies trust boundaries, private storage, service, adapters, logs, fallback, and reviewer.

Self-check

When inference times out, which is honest: return a heuristic fallback labeled as fallback and request review, or reuse the previous model score?

Evidence gate

Submit the tested FastAPI package, versioned request and versioned response examples, structured failures, heuristic fallback, human-review routing, privacy-safe log fixture, CPU contract-test report, local RTX 4080 smoke record, latency summary, end-to-end local workflow, CineQC screen capture, and architecture walkthrough. Demonstrate that CineQC remains usable when the model is unavailable.

One-page summary

• Version request, response, and model independently.
• Make success, fallback, and failure machine-readable.
• Log identity, timing, route, and error—not private media.
• Keep fallback explicit and uncertainty human-reviewed.
• Smoke-test contracts on CPU and graduate the model path on the local RTX 4080.
• CineQC displays evidence; its human rubric remains authoritative.