# Release Notes - MCA SDK v0.8.22

**Release Date:** April 20, 2026

## Overview

Version 0.8.22 introduces the **status label** feature for prediction metrics, along with important bug fixes for Prometheus metrics export, security updates, and improved test coverage. This release enhances observability by enabling cleaner error rate calculations and better metric filtering in monitoring dashboards.

## 🎯 Key Features

### Status Label for Prediction Metrics

The SDK now automatically adds a `status` label to all prediction metrics, enabling better observability and simpler alerting rules.

**Metrics Affected:**
- `model.predictions_total` (counter)
- `model.latency_seconds` (histogram)

**Label Values:**
- `status="success"` - Successful predictions (via `record_prediction()`)
- `status="error"` - Failed predictions (via `record_error()`)

**Benefits:**
- **Clean error rate calculations**: `rate({status='error'}) / rate(total)`
- **Easy filtering in Grafana**: Filter by success/error status
- **Simpler Prometheus alerting rules**: Alert on error rates directly
- **Better observability**: Understand prediction outcomes at a glance

**Example Queries:**

```promql
# Error rate percentage
sum(rate(model_predictions_total{status="error"}[5m])) 
/ 
sum(rate(model_predictions_total[5m])) * 100

# Success count
sum(rate(model_predictions_total{status="success"}[5m]))

# Average latency for successful predictions only
histogram_quantile(0.95, 
  sum(rate(model_latency_seconds_bucket{status="success"}[5m])) by (le)
)
```

**Code Example:**

```python
from mca_sdk import MCAClient

client = MCAClient(
    service_name="readmission-model",
    model_id="mdl-001",
    team_name="clinical-ai"
)

# Successful prediction - automatically gets status="success"
client.record_prediction(latency=0.15, model_version="2.0")

# Failed prediction - automatically gets status="error"
try:
    result = model.predict(data)
except Exception as e:
    client.record_error(e, latency=0.20)

client.shutdown()
```

**Backward Compatibility:**
- **Additive change only** - existing queries continue to work
- Queries without status filter will include both success and error metrics
- No breaking changes to API or method signatures

---

## 🐛 Bug Fixes

### Prometheus Metrics Export
**Issue:** Duplicate label names causing Prometheus export failures  
**Fix:** Prevented duplicate label names from being added to metrics, resolving export errors

### Test Infrastructure
**Issue:** Import path errors in tests  
**Fix:** Updated test patches to use correct import path for `serialize_for_telemetry`

### Agentic AI
**Issue:** Prediction endpoint not working correctly for agentic AI use cases  
**Fix:** Corrected prediction endpoint handling for agentic AI models

### Configuration
**Issue:** Registry token audience not configurable  
**Fix:** Added support for `REGISTRY_TOKEN_AUDIENCE` environment variable

---

## 🔒 Security Updates

### Critical Dependency Upgrades

| Package | From | To | CVE/Issue |
|---------|------|-----|-----------|
| cryptography | 46.0.6 | 46.0.7 | CVE-2026-39892 |
| fastapi | 0.103.2 | 0.109.1 | Snyk security scan |
| axios | 1.14.0 | 1.15.0 | Snyk security scan |

**Additional Security Improvements:**
- Aligned security dependency versions across all package configuration files
- Reduced vulnerabilities in `requirements-security.txt`
- All security patches verified by automated scanning (Snyk, pip-audit)

---

## 🧪 Testing & Quality

### Test Coverage Improvements
- Updated tests to reflect auth error fallback behavior
- Added missing test parameters for better coverage
- New test for status label consistency
- Applied black formatting (line-length 100) to match CI configuration
- Removed unused imports to pass ruff linting

### Test Results
- All 40+ unit tests passing
- Integration tests verified
- Security scans passing (pip-audit, Snyk)

---

## 📚 Documentation Updates

- Streamlined SDK instrumentation documentation
- Updated CHANGELOG with detailed release notes
- Added status label examples and use cases
- Clarified backward compatibility guarantees

---

## 🔄 Migration Guide

### From v0.8.21 to v0.8.22

**No breaking changes** - this is a fully backward-compatible release.

### Optional: Update Monitoring Dashboards

If you want to take advantage of the new status labels:

**Grafana Dashboards:**
```yaml
# Add error rate panel
- title: Prediction Error Rate
  type: graph
  datasource: Prometheus
  targets:
    - expr: |
        sum(rate(model_predictions_total{status="error"}[5m])) 
        / 
        sum(rate(model_predictions_total[5m])) * 100
      legendFormat: "Error Rate %"
```

**Prometheus Alerting Rules:**
```yaml
groups:
  - name: model_health
    rules:
      - alert: HighPredictionErrorRate
        expr: |
          sum(rate(model_predictions_total{status="error"}[5m])) 
          / 
          sum(rate(model_predictions_total[5m])) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High prediction error rate detected"
          description: "Error rate is {{ $value | humanizePercentage }}"
```

---

## 📦 Installation

### PyPI (Recommended)

```bash
# Upgrade to latest version
pip install --upgrade mca-sdk

# Install with specific extras
pip install --upgrade "mca-sdk[genai,gcp]"

# Verify version
python -c "import mca_sdk; print(mca_sdk.__version__)"
# Output: 0.8.22
```

### From Source

```bash
git clone https://gitlab.com/bhsf/ai_ml/model-monitoring/sdk.git
cd sdk/mca-prototype
git checkout v0.8.22
pip install -e .
```

---

## ✅ Verification

### Test Status Label Feature

```python
from mca_sdk import MCAClient

# Initialize client
client = MCAClient(
    service_name="test-model",
    model_id="test-001",
    team_name="test-team"
)

# Record successful prediction
client.record_prediction(latency=0.15)

# Record error
error = ValueError("Test error")
client.record_error(error, latency=0.20)

# Shutdown and flush
client.shutdown()
```

Expected metrics in OpenTelemetry Collector logs:
```
Metric: model.predictions_total
  Value: 1
  Labels: status=success

Metric: model.predictions_total
  Value: 1
  Labels: status=error, error_type=ValueError
```

---

## 🔗 Links

- **PyPI Package:** https://pypi.org/project/mca-sdk/0.8.22/
- **GitLab Repository:** https://gitlab.com/bhsf/ai_ml/model-monitoring/sdk
- **Documentation:** See README.md and docs/ folder
- **Issue Tracker:** https://gitlab.com/bhsf/ai_ml/model-monitoring/sdk/-/issues

---

## 📝 Full Changelog

For complete commit history, see [CHANGELOG.md](CHANGELOG.md#0822---2026-04-20)

---

## 👥 Contributors

- Tolu Olukoga - Status label feature implementation
- BHSF AI/ML Team - Security updates and testing

---

## 🙏 Acknowledgments

Special thanks to the data science teams for feedback on metric observability requirements that drove the status label feature.

---

## ⚠️ Known Issues

None identified in this release.

---

## 🔮 Coming in v0.8.23+

- Additional metric cardinality optimizations
- Enhanced GCP integration features
- Improved documentation and examples

---

**Questions or issues?** Contact the AI/ML Platform team or open an issue on GitLab.
