---
name: mca-instrument
description: Instrument a Python model with the MCA SDK by following the in-wheel FOR_AI_ASSISTANTS.md guide. Trigger when the user asks to add MCA telemetry, wire OTel, add @client.predict(), or set up model monitoring.
---

# MCA SDK instrumentation

The canonical instrumentation guide lives inside the installed `mca-sdk`
wheel at `mca_sdk/FOR_AI_ASSISTANTS.md`. Resolve it with:

```python
import mca_sdk, os
guide = os.path.join(os.path.dirname(mca_sdk.__file__), "FOR_AI_ASSISTANTS.md")
```

Or via the SDK's public helper:

```python
from mca_sdk.ai_assist import get_guide_path, read_guide
print(read_guide())
```

## What to do

1. Read the guide top to bottom before touching any code.
2. Use the §0 code-signal decision table to pick a pattern (§2.1–§2.7).
3. If the four declarations in §0 (`model_type`, `model_category`,
   deployment shape, LLM access path) are missing or ambiguous, **stop
   and ask the owner** — do not guess.
4. Apply the matching startup block (§1.1 for Vertex / Cloud Run
   FastAPI, §1.2 for scripts / notebooks / CLI batch).
5. Verify with the four steps in §5.

## Hard rules (§3 of the guide)

- **Do not auto-mask PHI.** Warn about PHI fields you find (names, MRNs,
  DOBs, free-text notes) and let the owner sanitize before instrumenting.
- Use `association_id` as the join key between predictions and outcomes.
- One metric per batch; per-row data belongs in logs.
- Flush once per request, not per row.
- HTTPS is required for non-localhost endpoints.
- Never log tokens, API keys, or registry secrets.

## When to refuse (§6 of the guide)

Stop and escalate if the owner asks you to bypass HTTPS, log secrets,
disable validation, or auto-mask PHI inside the SDK. PHI masking is an
application responsibility, not an SDK responsibility.
