# Guide for AI Coding Assistants

**Purpose:** Help data scientists integrate MCA SDK into their code.

**Location:** This file is included when they `pip install mca-sdk`. You can find it at:
```python
import mca_sdk
import os
guide_path = os.path.join(os.path.dirname(mca_sdk.__file__), 'FOR_AI_ASSISTANTS.md')
```

---

## What the Data Scientist Does

```bash
pip install mca-sdk
```

Then asks you: "Help me add MCA SDK to instrument my model."

---

## Your Job (Simple 3-Step Process)

### 1. Look at Their Code

Find their prediction function:
```python
def predict(features):
    return model.predict(features)
```

### 2. Apply the Pattern

Read the working examples in `sdk-examples/`:
- `internal-model/instrumented_model.py` - Decorator pattern for ML models
- `litellm-genai/genai_chatbot.py` - LiteLLM callback for GenAI
- `internal-agentic/agentic_assistant.py` - Goal tracking for agents
- `vendor-model/vendor_bridge.py` - Bridge pattern for external APIs

Pick the pattern that matches their code and apply it.

### 3. Help with Environment Setup

Create `.env` file:
```bash
MCA_SERVICE_NAME="their-model-name"
MCA_MODEL_ID="mdl-001"
MCA_TEAM_NAME="their-team"
MCA_COLLECTOR_ENDPOINT="http://localhost:4318"
```

---

## Example: Internal ML Model

**Their code:**
```python
from sklearn.ensemble import RandomForestClassifier

model = RandomForestClassifier()

def predict_readmission(patient_features):
    prediction = model.predict(patient_features)
    return {'risk': prediction[0]}
```

**You add:**
```python
from sklearn.ensemble import RandomForestClassifier
from mca_sdk import MCAClient
import atexit

# Initialize SDK
client = MCAClient(
    service_name="readmission-predictor",
    model_id="mdl-001",
    team_name="clinical-ai"
)
atexit.register(client.shutdown)

model = RandomForestClassifier()

# Add decorator
@client.predict()
def predict_readmission(patient_features):
    prediction = model.predict(patient_features)
    return {'risk': prediction[0]}
```

**Done.** That's it.

---

## Example: GenAI/LLM Model

**Their code:**
```python
import litellm

def summarize_note(clinical_note):
    response = litellm.completion(
        model="gpt-4",
        messages=[{"role": "user", "content": clinical_note}]
    )
    return response.choices[0].message.content
```

**You add:**
```python
import litellm
from mca_sdk import MCAClient
from mca_sdk.integrations import MCALiteLLMCallback
import atexit

# Initialize SDK
client = MCAClient(
    service_name="clinical-summarizer",
    model_id="mdl-002",
    team_name="genai-team"
)
atexit.register(client.shutdown)

# Attach callback - automatically instruments all LLM calls
callback = MCALiteLLMCallback(client)
litellm.callbacks.append(callback)

def summarize_note(clinical_note):
    response = litellm.completion(
        model="gpt-4",
        messages=[{"role": "user", "content": clinical_note}]
    )
    return response.choices[0].message.content
```

**Done.** All LLM calls now automatically instrumented.

---

## Critical Reminders

### Always Warn About PHI

```
⚠️ IMPORTANT: Remove PHI before using SDK:

❌ BAD:
client.record_prediction(patient_name="John Doe", mrn="12345")

✅ GOOD:
client.record_prediction(patient_id=hash("12345"), risk_score=0.85)
```

### Testing

```bash
# Start collector
docker-compose up -d otel-collector

# Run their code
python model.py

# Check metrics
open http://localhost:9090
```

---

## When They Ask Questions

**"What environment variables do I need?"**
→ Show them the 4 required: `MCA_SERVICE_NAME`, `MCA_MODEL_ID`, `MCA_TEAM_NAME`, `MCA_COLLECTOR_ENDPOINT`

**"How do I know it's working?"**
→ `docker logs -f otel-collector` should show "exporting metrics"

**"Will this slow down my model?"**
→ No, SDK uses async export with 10-second batching

**"Do I need the Model Registry?"**
→ No, it's optional. SDK works with just environment variables.

---

## That's It

Don't overcomplicate. The SDK is designed to be simple:
1. One import: `from mca_sdk import MCAClient`
2. One decorator: `@client.predict()`
3. Done

Read the examples in `sdk-examples/` for patterns. Apply them to the data scientist's code. Help with `.env` setup. That's the entire workflow.

---

## Reference

- Examples: `sdk-examples/`
- README: `mca-prototype/README.md`
- API docs: `docs/api-contracts.md`
- Full guides: `docs/integration-guides/`
