Skip to content

Distiller — professional tutorial

Released in FCC v1.2.1. You are integrating Distiller into a production FCC deployment with real compliance obligations. This tutorial covers the Helm chart wiring, the K8s probe expectations (the v1.2.1 probes were tuned specifically for this subsystem's cold-start characteristics), the observability hooks, and the failure modes you need to handle.

What this subsystem does

The Distiller subsystem provides the Distiller Bridge adapter for Fornax NanoCube integration, providing hierarchical data queries, synthetic data fabrication, and exchange contracts (mock mode by default).

The implementation lives at src/fcc/protocols/distiller_bridge.py. It ships with FCC core (no separate install needed) and is exercised by:

Focus persona: PCO — Protocol Compliance Officer

We anchor this professional-track tutorial on PCO because that's the persona most relevant to a professional use of the Distiller subsystem.

from fcc._resources import get_personas_dir
from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
persona = registry.get("PCO")
print(persona.name)
print(persona.role_title)
print(persona.riscear.role)

Production checklist

When deploying distiller in production:

  • Resource limits — see charts/fcc/values.yaml for the v1.2.1-tuned probe initialDelaySeconds (web-frontend = 30s, distiller = inherits backend, open-science = inherits backend, skyparlour = inherits backend) and timeoutSeconds (HTTP probes have 3s defaults). Cold-start times are dominated by sentence-transformers and plotly for streamlit; backend .ai_cache/ initialization for the WS bridge.
  • Helm chart — helm install fcc oci://ghcr.io/.../fcc --version 0.2.0 ships v1.2.1 of the application
  • K8s smoke test — .github/workflows/k8s-smoke.yml runs every PR; the v1.2.1 probe tuning was specifically driven by the cold-start characteristics of this subsystem's container
  • Observability — wire the subsystem's events into your tracing/metrics stack (see src/fcc/observability/)
  • Failure modes — read the relevant integration test for the subsystem to understand what failure looks like end-to-end

Failure modes

  • WebSocket bridge — disconnections are auto-handled (clients are removed from the connected set on broadcast failure). Watch for WebSocket event queue full warnings; bump the queue maxsize if persistent.
  • Distiller bridge — mock mode never fails. Real mode (with distiller_ext installed) can raise on schema mismatches.
  • Open Science — gates that fail their threshold raise no exception; the failure surfaces in the evaluate_fair_compliance() report's failed_gates list.
  • Sky-Parlour — transformer registration is the only fail point; the bridge doesn't validate transformer return types at registration time.

Audit trail

The PCO persona's riscear.role field documents the responsibility this persona holds when operating the subsystem in production. Use it as the source of truth in your incident postmortems.

What you learned

  • The Helm chart, K8s probes, and observability stack are all wired up
  • Failure modes are well-defined per subsystem
  • The persona R.I.S.C.E.A.R. spec is the audit trail for production responsibilities

Verification

Run the focused test suite for this subsystem:

pytest tests/test_distiller_bridge.py -v

All tests should pass on a clean v1.2.1 install. If they don't, check that you have the optional deps from the [full] extras group:

pip install -e ".[full]"

Next steps