mca-sdk 0.9.2__tar.gz → 0.9.4.dev1__tar.gz

{mca_sdk-0.9.2 → mca_sdk-0.9.4.dev1}/CHANGELOG.md

@@ -4,6 +4,78 @@ All notable changes to the MCA SDK will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-07-08
+
+### Added
+- **`mca_sdk.ai_assist` subpackage** — public API for end-user data
+  scientists to program against the AI-assistant surface. Exposes
+  `get_guide_path()`, `read_guide()`, `render_prompt(variant, **fields)`,
+  `list_assistants()`, and `install(assistant, dest, force=False)`.
+- **`%mca_instrument` / `%mca_prompt` IPython magics** —
+  `%load_ext mca_sdk.ai_assist.jupyter` registers a notebook-native
+  onboarding path. `%mca_instrument` reuses the same `_auto_init` /
+  `_shutdown_with_timeout` bootstrap as `mca-instrument` / `mca-run`, so
+  env-var semantics are identical across surfaces. IPython is optional
+  (`pip install "mca-sdk[jupyter]"`); the module raises a clear error if
+  IPython is missing.
+- **`mca-init ai-assist` subcommand** — scaffolds per-assistant config
+  files into the caller's repo at each assistant's canonical location:
+  Claude Code (`.claude/skills/mca-instrument.md`), Cursor
+  (`.cursor/rules/mca-instrument.mdc`), Copilot
+  (`.github/copilot-instructions.md`), Gemini CLI (`GEMINI.md`). Also
+  supports `mca-init ai-assist prompt --model-id ... --type ...` to
+  render a fully-filled Variant A/B paste-in prompt to stdout. Every
+  template LINKS to `FOR_AI_ASSISTANTS.md` inside the wheel — none
+  duplicate pattern content.
+- Notebook starter template shipped in the wheel at
+  `mca_sdk/ai_assist/templates/notebook/mca_starter.ipynb`.
+
+### Changed
+- **`FOR_AI_ASSISTANTS.md`** received three rounds of post-0.9.2
+  corrections from live instrumentation observations: six additional
+  pattern gaps closed (association-id join keys, batch-vs-per-instance
+  `record_*` rules, and related edge cases); `model_types` values
+  corrected to the canonical set; and a new section covering MLOps
+  pipeline usage and dependency-installation guidance.
+
+### Fixed
+- **OTel SDK 1.35–1.38 import compatibility** — `mca_sdk` no longer
+  raises `ImportError: cannot import name 'ReadableLogRecord' from
+  'opentelemetry.sdk._logs'` when installed against `opentelemetry-sdk`
+  releases in the 1.35 through 1.38 window (where the symbol did not
+  exist). `mca_sdk/exporters/gcp_logging.py` and
+  `mca_sdk/buffering/exporters.py` now use try/except fallback chains
+  to import `LogRecord`, `LogRecordExporter`, and
+  `LogRecordExportResult` from whichever module path the installed
+  OTel version exposes them at (`_logs`, `_logs._internal`, or the
+  older `LogExporter` / `LogExportResult` aliases). Verified against
+  OTel 1.35.0, 1.36.0, and 1.43.0. Type annotations changed from
+  `Sequence[ReadableLogRecord]` to `Sequence[LogRecord]`; runtime
+  behavior is unchanged.
+- **MANIFEST.in** now includes `FOR_AI_ASSISTANTS.md` and all
+  `ai_assist/templates/*` files in sdists. The guide previously shipped
+  only in wheels via `setup.py package_data`; sdist consumers
+  (`pip install --no-binary`) lost it.
+- Lint and mypy strict-mode errors resolved across
+  `mca_sdk/ai_assist/cli_install.py`, `mca_sdk/ai_assist/jupyter.py`,
+  `mca_sdk/buffering/exporters.py`, and
+  `mca_sdk/exporters/gcp_logging.py`. No behavior change.
+- **Sphinx docs build** — `IPython` is now mocked in `docs/conf.py`
+  so the `mca_sdk.ai_assist.jupyter` autosummary page builds cleanly
+  in docs environments without IPython installed.
+
+### Security
+- **cryptography** upgraded to 48.0.1. Expired CVE-2026-4539 entry
+  removed from `.pip-audit-allowlist.txt`.
+
+### Notes
+- The `mca-init <project_dir>` invocation is unchanged. The new
+  `ai-assist` action is pre-dispatched in `main()` before argparse sees
+  the positional arg, so no argparse restructure was needed.
+- **PHI is still the application's responsibility.** Every template
+  body carries the "warn, do not auto-mask" language from
+  FOR_AI_ASSISTANTS.md §6.
+
 ## [0.9.2] - 2026-06-30
 
 ### Changed

{mca_sdk-0.9.2 → mca_sdk-0.9.4.dev1}/MANIFEST.in

@@ -3,3 +3,5 @@ include LICENSE
 include CHANGELOG.md
 recursive-include mca_sdk *.py
 recursive-include mca_sdk py.typed
+recursive-include mca_sdk *.md
+recursive-include mca_sdk/ai_assist/templates *

{mca_sdk-0.9.2/mca_sdk.egg-info → mca_sdk-0.9.4.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mca-sdk
-Version: 0.9.2
+Version: 0.9.4.dev1
 Summary: Model Collector Agent SDK for OpenTelemetry monitoring
 Author-email: Baptist Health South Florida <ai-ml@baptisthealth.net>
 License: Apache-2.0
@@ -50,12 +50,15 @@ Requires-Dist: numpy>=1.24.0; extra == "autolog"
 Provides-Extra: instrument
 Requires-Dist: opentelemetry-instrumentation>=0.48b0; extra == "instrument"
 Requires-Dist: opentelemetry-distro>=0.48b0; extra == "instrument"
+Provides-Extra: jupyter
+Requires-Dist: ipython>=7.0; extra == "jupyter"
 Provides-Extra: test
 Requires-Dist: pytest>=7.4.0; extra == "test"
 Requires-Dist: pytest-cov>=4.1.0; extra == "test"
 Requires-Dist: pytest-mock>=3.12.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
 Requires-Dist: opentelemetry-exporter-prometheus>=0.48b0; extra == "test"
+Requires-Dist: ipython>=7.0; extra == "test"
 Provides-Extra: dev
 Requires-Dist: black>=24.0.0; extra == "dev"
 Requires-Dist: mypy>=1.8.0; extra == "dev"
@@ -66,6 +69,7 @@ Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
 Requires-Dist: opentelemetry-exporter-prometheus>=0.48b0; extra == "dev"
 Requires-Dist: pdoc>=14.0.0; extra == "dev"
+Requires-Dist: ipython>=7.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: pdoc>=14.0.0; extra == "docs"
 Provides-Extra: all
@@ -296,6 +300,25 @@ If you are using an agentic coding assistant (like Claude Code, Gemini CLI, Curs
 Simply paste this prompt to your AI assistant:
 > "Please review my codebase and instrument my models using the MCA SDK. You can find the instructions on how to do this by reading the guide located at `mca_sdk/FOR_AI_ASSISTANTS.md` within the installed package."
 
+**Drop assistant configs into your repo with one command:**
+```bash
+mca-init ai-assist install --assistant all          # Claude Code + Cursor + Copilot + Gemini CLI
+mca-init ai-assist install --assistant cursor       # just Cursor rules
+mca-init ai-assist prompt --model-id mdl-001 --type predictive --shape script  # print a ready-to-paste prompt
+```
+
+**In a Jupyter notebook** (see also the `mca_starter.ipynb` template shipped with the SDK):
+```python
+%load_ext mca_sdk.ai_assist.jupyter
+%mca_instrument --model-id mdl-001 --team clinical-ai
+```
+
+**Programmatic access to the guide:**
+```python
+from mca_sdk.ai_assist import get_guide_path, read_guide
+print(get_guide_path())
+```
+
 ### Approach 2: Zero-Code Auto-Instrumentation (Recommended)
 This approach utilizes the `mca-instrument` CLI wrapper to automatically instrument your application's external calls and supported framework inferences without touching your source code.
 **Prerequisites**: Install the SDK with instrumentation dependencies: `pip install "mca-sdk[instrument]"` and run `opentelemetry-bootstrap -a install`.
@@ -323,7 +346,7 @@ Provide configuration via environment variables in your deployment manifest. The
 - **GCP Exporters**: To route telemetry to GCP buckets, you must set `MCA_GCP_LOGGING_ENABLED=true` and `MCA_GCP_TRACE_ENABLED=true` environment variables.
 
 ### Approach 3: Manual Instrumentation
-If you are not using standard HTTP/DB frameworks, **if you are working in a Jupyter Notebook**, or if you need precise programmatic control, use the SDK's Python API directly in your code.
+If you are not using standard HTTP/DB frameworks, or if you need precise programmatic control, use the SDK's Python API directly in your code. (In a Jupyter notebook, prefer the `%mca_instrument` magic under Approach 1.)
 
 ```python
 from mca_sdk import MCAClient

{mca_sdk-0.9.2 → mca_sdk-0.9.4.dev1}/README.md

@@ -209,6 +209,25 @@ If you are using an agentic coding assistant (like Claude Code, Gemini CLI, Curs
 Simply paste this prompt to your AI assistant:
 > "Please review my codebase and instrument my models using the MCA SDK. You can find the instructions on how to do this by reading the guide located at `mca_sdk/FOR_AI_ASSISTANTS.md` within the installed package."
 
+**Drop assistant configs into your repo with one command:**
+```bash
+mca-init ai-assist install --assistant all          # Claude Code + Cursor + Copilot + Gemini CLI
+mca-init ai-assist install --assistant cursor       # just Cursor rules
+mca-init ai-assist prompt --model-id mdl-001 --type predictive --shape script  # print a ready-to-paste prompt
+```
+
+**In a Jupyter notebook** (see also the `mca_starter.ipynb` template shipped with the SDK):
+```python
+%load_ext mca_sdk.ai_assist.jupyter
+%mca_instrument --model-id mdl-001 --team clinical-ai
+```
+
+**Programmatic access to the guide:**
+```python
+from mca_sdk.ai_assist import get_guide_path, read_guide
+print(get_guide_path())
+```
+
 ### Approach 2: Zero-Code Auto-Instrumentation (Recommended)
 This approach utilizes the `mca-instrument` CLI wrapper to automatically instrument your application's external calls and supported framework inferences without touching your source code.
 **Prerequisites**: Install the SDK with instrumentation dependencies: `pip install "mca-sdk[instrument]"` and run `opentelemetry-bootstrap -a install`.
@@ -236,7 +255,7 @@ Provide configuration via environment variables in your deployment manifest. The
 - **GCP Exporters**: To route telemetry to GCP buckets, you must set `MCA_GCP_LOGGING_ENABLED=true` and `MCA_GCP_TRACE_ENABLED=true` environment variables.
 
 ### Approach 3: Manual Instrumentation
-If you are not using standard HTTP/DB frameworks, **if you are working in a Jupyter Notebook**, or if you need precise programmatic control, use the SDK's Python API directly in your code.
+If you are not using standard HTTP/DB frameworks, or if you need precise programmatic control, use the SDK's Python API directly in your code. (In a Jupyter notebook, prefer the `%mca_instrument` magic under Approach 1.)
 
 ```python
 from mca_sdk import MCAClient

{mca_sdk-0.9.2 → mca_sdk-0.9.4.dev1}/mca_sdk/FOR_AI_ASSISTANTS.md

@@ -20,7 +20,7 @@ prompt at the bottom of this file (or one like it).
 The data scientist MUST tell you (or have written in the repo, e.g. a
 README, model card, or `mca.yaml`) two things:
 
-1. **`model_type`** — one of `predictive`, `generative`, `agentic`.
+1. **`model_type`** — one of `regression`, `time-series`, `classification`, `generative`, `agentic`.
 2. **`model_category`** — one of `internal`, `vendor`.
 
 You also need to infer (or ask):
@@ -62,6 +62,16 @@ underneath it — both can coexist.
 
 ## 1. Universal startup — pick one
 
+### 1.0 Internal HTTP collector — set `allow_insecure_collector=True`
+
+The fleet collector runs at `http://10.164.76.55:4318` (see
+`example_deployed/shared/config.py`). The SDK enforces HTTPS on non-localhost
+endpoints by default and will refuse to initialize against a bare `http://…`
+URL. Pass `allow_insecure_collector=True` to `MCAClient(...)` whenever
+`collector_endpoint` starts with `http://` and isn't `localhost` — every
+`example_deployed/*` client does this. Omit the flag only when the endpoint
+is `https://…` or `http://localhost:…`.
+
 ### 1.1 Vertex AI / Cloud Run FastAPI container (the production case)
 
 Use `lifespan` so startup runs inside the event loop and `asyncio.to_thread`
@@ -114,10 +124,13 @@ wraps any blocking I/O. This is what every container in
             MCAClient,
             service_name=service_name,
             model_id=model_id,
-            model_type="predictive",        # set to the declared type
+            model_type="classification",        # set to the declared type
             model_category="internal",      # set to the declared category
             team_name=team_name,
+            llm_provider="google",          # or "openai" | "anthropic" | "litellm"
+            llm_model="gemini-2.0-flash-001",  # whatever the model resolves to
             collector_endpoint=collector_endpoint,
+            allow_insecure_collector=True,  # required if collector is http://…
             registry_url=registry_url,
             use_gcp_auth=True,
             refresh_interval_secs=300,
@@ -125,6 +138,11 @@ wraps any blocking I/O. This is what every container in
             capture_output_data=True,
         )
 
+`llm_provider` / `llm_model` dimension GenAI metrics on the collector. Set
+them even when your agent talks to the LLM indirectly (LiteLLM proxy,
+LangChain wrapper) — otherwise the dashboard groups everything as
+`unknown/unknown` and per-model latency/cost splits are gone.
+
         yield
 
         if mca_client:
@@ -142,7 +160,7 @@ wraps any blocking I/O. This is what every container in
     client = MCAClient(
         service_name="readmission-predictor",
         model_id="mdl-001",
-        model_type="predictive",
+        model_type="classification",
         model_category="internal",
         team_name="clinical-ai",
     )
@@ -257,6 +275,20 @@ not hand-wrap. Call `autolog()` once and let the patchers handle it.
     from llama_index.core import Settings
     Settings.callback_manager.add_handler(MCALlamaIndexCallback(mca_client))
 
+**Build the callback in its own try-block.** `MCALangChainCallback` imports
+`langchain-core` at construction time. If that extra isn't installed, the
+constructor raises — and if you built the client and the callback in the
+same `try`, the exception unwinds the whole init, losing the agentic client
+that would have worked on its own. Split them:
+
+    client = MCAClient(...)                     # required
+    try:
+        from mca_sdk.integrations import MCALangChainCallback
+        callbacks = [MCALangChainCallback(client)]
+    except Exception:
+        callbacks = []                          # LLM-call telemetry off;
+                                                # agent traces (§2.6) still flow
+
 ### 2.6 Agentic (multi-step reasoning)
 
 One outer trace per user request; one `record_prediction` per agent
@@ -280,6 +312,55 @@ metrics underneath. Pattern is
                     },
                 )
 
+#### 2.6.1 Agentic on LangGraph (`StateGraph.astream`)
+
+When the agent is a LangGraph `StateGraph` (increasingly the default),
+you don't have a hand-rolled `for step in plan` loop — you have
+`app.astream(state, config)` yielding `{node_name: node_state}` events.
+Wrap the streaming loop instead:
+
+    with mca_client.trace("agent.run", attributes={
+        "agent.goal": "deploy_application",
+        "agent.request_id": request_id,     # also your association_id
+    }):
+        last_tick = time.perf_counter()
+        prev_error_count = 0
+        step_idx = 0
+        async for event in app.astream(initial_state, config):
+            for node_name, node_state in event.items():
+                if not isinstance(node_state, dict):
+                    continue
+                now = time.perf_counter()
+                err_n = len(node_state.get("errors", []) or [])
+                mca_client.record_prediction(
+                    latency=now - last_tick,          # per-step wall time
+                    prediction_id=f"{request_id}.{step_idx}",
+                    span_attributes={
+                        "agent.step.index": step_idx,
+                        "agent.step.node": node_name,
+                        "agent.step.success": err_n == prev_error_count,
+                    },
+                )
+                prev_error_count = err_n
+                last_tick = now
+                step_idx += 1
+        mca_client.flush(timeout_millis=2000)
+
+Notes:
+
+- Use the `thread_id` you already pass to LangGraph as your
+  `association_id` — it's the natural join key for downstream outcomes,
+  don't invent a second one.
+- Measure per-step latency between yields. LangGraph doesn't expose
+  per-node start times in the event stream; `now - last_tick` is the
+  right approximation.
+- Derive per-step success by comparing `len(errors)` before and after.
+  The `add_error()` helpers in most projects append without decrementing,
+  so growth ⇒ that node failed.
+- The LangChain callback (§2.5) still attaches to your `ChatLiteLLM` /
+  `ChatOpenAI` instances underneath and captures per-LLM-call
+  telemetry — the agent trace is one layer up, not a replacement.
+
 ### 2.7 Vendor model (you do not own the inference code)
 
 Two sub-cases:
@@ -317,6 +398,16 @@ Use `model_category="vendor"` on the `MCAClient` in both sub-cases.
    anything to `record_prediction`, `record_llm_generation`, trace
    attributes, or log `extra` fields. If the owner wants belt-and-braces
    filtering, set `MCA_ENABLE_PHI_FILTER=1` — it is opt-in.
+
+   **Free-form user input is a landmine.** If your model's input is a
+   natural-language field (chat prompt, ticket description, deploy
+   request, search query, free-text note), do **not** set
+   `capture_input_data=True` blindly — it ships the raw text into span
+   attributes where a downstream viewer with dashboard access will read
+   it. Default to `False`; only enable after you've written an
+   application-side scrubber, or after confirming the field truly can't
+   hold PHI. The same warning applies to `capture_output_data=True` when
+   the model returns generated text.
 2. **`association_id` is the join key** between prediction and outcome.
    Forward it from the request payload into per-row logs (see §2.1) so
    ground-truth labels can be joined later. Never use PHI as the
@@ -331,7 +422,22 @@ Use `model_category="vendor"` on the `MCAClient` in both sub-cases.
 
 ---
 
-## 4. Environment variables (canonical names)
+## 4. MLOps Pipelines & Dependencies
+
+To ensure telemetry successfully reaches the collector in production, you MUST instrument the build and deployment environment alongside the Python code. Do not skip this step.
+
+### 4.1 Dependency Management
+Search the project tree for `requirements.txt` or `pyproject.toml` files located within the serving or inference directories (e.g., `serve_image/requirements.txt`).
+Append `mca_sdk` to these files. If the repository has separate training and serving dependencies, ensure it is added to the serving dependencies at a minimum.
+
+### 4.2 Environment Orchestration
+The production container needs the telemetry environment variables injected at deployment time.
+Search the project for Vertex AI pipeline definitions (e.g., `pipeline.py`, `pipeline.json`), deployment shell scripts (e.g., `bootstrap.sh`), or environment configuration files (e.g., `config.env`).
+Ensure that `MCA_OTEL_ENDPOINT`, `MCA_SERVICE_NAME`, `MCA_MODEL_ID`, and `MCA_TEAM_NAME` are explicitly passed into the serving container's configuration (e.g., via `serving_container_environment_variables` in Vertex AI's `ModelDeployOp` or equivalent).
+
+---
+
+## 5. Environment variables (canonical names)
 
 | Var                                | Required? | Default                  | Notes |
 |------------------------------------|-----------|--------------------------|-------|
@@ -347,6 +453,9 @@ Use `model_category="vendor"` on the `MCAClient` in both sub-cases.
 | `MCA_REGISTRY_REFRESH_INTERVAL`    | no        | `600`                    | Seconds |
 | `MCA_ENABLE_PHI_FILTER`            | no        | `0`                      | Opt-in PHI scrubbing |
 | `MCA_DEBUG_MODE`                   | no        | `false`                  | Verbose logs |
+| `MCA_ENV`                          | no        | `production`             | Fleet mock-switch. `dev` / `development` / `mock` / `local` disable real telemetry (init a no-op client); anything else means production. Mirrors `example_deployed/*/main.py`. Also honor `MCA_DISABLED=true` for the same effect. |
+| `MCA_LLM_PROVIDER`                 | no        | —                        | GenAI metric dimension. Set to `google` / `openai` / `anthropic` / `litellm` etc. Pass into `MCAClient(llm_provider=...)`. |
+| `MCA_LLM_MODEL`                    | no        | —                        | GenAI metric dimension. Pass into `MCAClient(llm_model=...)`. Without both, dashboards group everything as `unknown/unknown`. |
 
 Earlier versions of this guide listed `MCA_COLLECTOR_ENDPOINT` as the
 primary endpoint variable. That is wrong. Use `MCA_OTEL_ENDPOINT` in new
@@ -355,24 +464,26 @@ manifests.
 
 ---
 
-## 5. Verification
+## 6. Verification
 
-After instrumenting, do all four:
+After instrumenting, do all six:
 
 1. **Import test** — `python -c "from mca_sdk import MCAClient; print('ok')"`.
-2. **Local collector** —
+2. **Dependencies check** — Confirm `mca_sdk` is added to the serving `requirements.txt` or `pyproject.toml`.
+3. **Pipeline config check** — Confirm pipeline deployment files (e.g., `pipeline.py`) explicitly inject `MCA_OTEL_ENDPOINT` and registry vars into the serving container.
+4. **Local collector** —
        docker-compose up -d otel-collector
        python <their_entrypoint>.py        # or hit the FastAPI endpoint
        docker logs -f otel-collector       # expect "exporting metrics"
-3. **Unit smoke** — call the instrumented function once with a tiny
+5. **Unit smoke** — call the instrumented function once with a tiny
    synthetic input, confirm no exception, confirm collector received a
    span with `service.name`, `model.id`, `model.type`, `model.category`.
-4. **Owner sign-off question** — confirm with the data scientist that the
+6. **Owner sign-off question** — confirm with the data scientist that the
    `model_type` and `model_category` you set match what they declared.
 
 ---
 
-## 6. When to refuse / escalate
+## 7. When to refuse / escalate
 
 Stop and ask the owner if any of these are true:
 
@@ -388,19 +499,20 @@ Stop and ask the owner if any of these are true:
 
 ---
 
-## 7. One-page summary you can paste back to the data scientist
+## 8. One-page summary you can paste back to the data scientist
 
 1. Confirm `model_type`, `model_category`, deployment shape, LLM access path.
 2. Pick the matching section above (§2.1 – §2.7).
 3. Copy the universal startup block (§1.1 for Vertex/Cloud Run, §1.2 for scripts).
 4. Apply the pattern. Strip PHI. Use `association_id` for joins.
-5. Verify with §5.
+5. Update MLOps configuration (§4) by injecting `MCA_*` environment variables in pipeline scripts and adding `mca_sdk` to `requirements.txt`.
+6. Verify with §6.
 
 That is the entire workflow.
 
 ---
 
-## 8. Prompt templates for data scientists
+## 9. Prompt templates for data scientists
 
 Paste one of the following into your AI coding assistant to start an
 instrumentation session.
@@ -409,7 +521,7 @@ instrumentation session.
 
 > Please instrument my model with the MCA SDK.
 >
-> - **model_type:** `<predictive | generative | agentic>`
+> - **model_type:** `<regression | time-series | classification | generative | agentic>`
 > - **model_category:** `<internal | vendor>`
 > - **Deployment shape:** `<vertex-fastapi | cloud-run-fastapi | script | notebook | cli-batch>`
 > - **LLM access path** (only if generative or agentic):

{mca_sdk-0.9.2 → mca_sdk-0.9.4.dev1}/mca_sdk/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.9.2'
-__version_tuple__ = version_tuple = (0, 9, 2)
+__version__ = version = '0.9.4.dev1'
+__version_tuple__ = version_tuple = (0, 9, 4, 'dev1')
 
-__commit_id__ = commit_id = 'g76060e153'
+__commit_id__ = commit_id = 'gb4af42fa0'

mca_sdk-0.9.4.dev1/mca_sdk/ai_assist/__init__.py

@@ -0,0 +1,149 @@
+"""AI-assistant packaging for MCA SDK end users.
+
+Exposes a small public API that lets a data scientist:
+- read the in-wheel FOR_AI_ASSISTANTS.md guide programmatically
+- render the Variant A/B paste-in prompts with model_id/team/etc filled in
+- install per-assistant config files (Cursor / Copilot / Gemini / Claude Code)
+  into their own repo via `mca-init ai-assist install ...`
+
+The Jupyter magic (`%mca_instrument`, `%mca_prompt`) lives in
+`mca_sdk.ai_assist.jupyter` and is not imported here so IPython stays optional.
+
+The guide (FOR_AI_ASSISTANTS.md) remains the single source of truth for
+instrumentation patterns; every template in this subpackage links back to
+it rather than duplicating pattern content.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+from typing import List
+
+if sys.version_info >= (3, 9):
+    from importlib.resources import files as _pkg_files
+else:  # pragma: no cover - project targets 3.10+
+    from importlib_resources import files as _pkg_files  # type: ignore[no-redef]
+
+__all__ = [
+    "get_guide_path",
+    "read_guide",
+    "render_prompt",
+    "list_assistants",
+    "install",
+    "ASSISTANT_TARGETS",
+]
+
+_KNOWN_ASSISTANTS = ("claude-code", "cursor", "copilot", "gemini")
+
+ASSISTANT_TARGETS: dict[str, str] = {
+    "claude-code": ".claude/skills/mca-instrument.md",
+    "cursor": ".cursor/rules/mca-instrument.mdc",
+    "copilot": ".github/copilot-instructions.md",
+    "gemini": "GEMINI.md",
+}
+
+_PROMPT_FIELDS = (
+    "model_type",
+    "model_category",
+    "deployment_shape",
+    "llm_access_path",
+    "model_id",
+    "service_name",
+    "team_name",
+)
+
+
+def get_guide_path() -> Path:
+    """Return the absolute filesystem path to FOR_AI_ASSISTANTS.md."""
+    return Path(str(_pkg_files("mca_sdk").joinpath("FOR_AI_ASSISTANTS.md")))
+
+
+def read_guide() -> str:
+    """Return the full text of the in-wheel FOR_AI_ASSISTANTS.md guide."""
+    return _pkg_files("mca_sdk").joinpath("FOR_AI_ASSISTANTS.md").read_text(encoding="utf-8")
+
+
+def list_assistants() -> List[str]:
+    """Return the assistant slugs this package can scaffold configs for."""
+    return list(_KNOWN_ASSISTANTS)
+
+
+def render_prompt(variant: str = "a", **fields: str) -> str:
+    """Render a Variant A or B prompt from §8 of the guide with fields filled in.
+
+    Args:
+        variant: "a" (owner-stated) or "b" (fallback classification).
+        **fields: Any of model_type, model_category, deployment_shape,
+            llm_access_path, model_id, service_name, team_name. Missing
+            fields are left as `<placeholder>` so the user can fill them.
+
+    Returns:
+        The rendered prompt as a string.
+
+    Raises:
+        ValueError: if variant is not one of {"a", "b"}.
+    """
+    variant = variant.lower().strip()
+    if variant not in {"a", "b"}:
+        raise ValueError(f"variant must be 'a' or 'b', got: {variant!r}")
+
+    template_path = (
+        _pkg_files("mca_sdk.ai_assist")
+        .joinpath("templates")
+        .joinpath("prompts")
+        .joinpath(f"variant_{variant}.md")
+    )
+    template = template_path.read_text(encoding="utf-8")
+
+    substitutions = {k: fields.get(k, f"<{k}>") for k in _PROMPT_FIELDS}
+    for placeholder, value in substitutions.items():
+        template = template.replace("{" + placeholder + "}", value)
+    return template
+
+
+def install(assistant: str, dest: Path, force: bool = False) -> List[Path]:
+    """Copy a template file for `assistant` into `dest` at its canonical location.
+
+    Args:
+        assistant: One of "claude-code", "cursor", "copilot", "gemini", or "all".
+        dest: Repository root to install into. The canonical relative path
+            (e.g. `.cursor/rules/mca-instrument.mdc`) is appended.
+        force: If True, overwrite existing files. Otherwise skip and log.
+
+    Returns:
+        List of absolute paths that were written.
+
+    Raises:
+        ValueError: if `assistant` is unknown.
+        FileExistsError: if the target file exists and `force` is False.
+    """
+    if assistant == "all":
+        written: List[Path] = []
+        for slug in _KNOWN_ASSISTANTS:
+            written.extend(install(slug, dest, force=force))
+        return written
+
+    if assistant not in ASSISTANT_TARGETS:
+        raise ValueError(
+            f"Unknown assistant: {assistant!r}. "
+            f"Expected one of {list(ASSISTANT_TARGETS)} or 'all'."
+        )
+
+    rel_path = ASSISTANT_TARGETS[assistant]
+    target = Path(dest).resolve() / rel_path
+    src_resource = (
+        _pkg_files("mca_sdk.ai_assist")
+        .joinpath("templates")
+        .joinpath(assistant)
+        .joinpath(Path(rel_path).name)
+    )
+
+    if target.exists() and not force:
+        raise FileExistsError(f"{target} already exists (pass force=True to overwrite)")
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with src_resource.open("rb") as src, open(target, "wb") as dst:
+        shutil.copyfileobj(src, dst)
+    return [target]