# Changelog

All notable changes to the MCA SDK will be documented in this file.

## [Unreleased]

## [0.5.0] - 2026-02-25

### Added
- **Registry API GCP Authentication Documentation**
  - New comprehensive guide: [`docs/registry-gcp-auth-guide.md`](docs/registry-gcp-auth-guide.md)
  - Covers all authentication methods: ADC, service account JSON, Workload Identity, gcloud CLI
  - Complete examples for Vertex AI Workbench, Cloud Run, GKE, and local development
  - Token management and automatic refresh documentation
  - Troubleshooting guide with common issues and solutions
  - Security best practices for production deployments
  - Verified with integration tests against real Registry API

- **GCP Cloud Trace Direct Export** (Story 6-3)
  - New `GCPCloudTraceExporter` for exporting traces directly to Google Cloud Trace
  - Configuration fields: `gcp_trace_enabled` (bool), `gcp_project_id` (str)
  - Environment variables: `MCA_GCP_TRACE_ENABLED`, `MCA_GCP_PROJECT_ID`
  - Full span fidelity: status codes, span kinds, links, events, resource attributes
  - Production features: retry logic, timeout protection, batch splitting, validation
  - Internal telemetry metrics for observability (spans exported, failures, retries)
  - Install with: `pip install mca-sdk[gcp-trace]` or `pip install mca-sdk[gcp]`
  - **Note**: Requires GCP credentials with scope `https://www.googleapis.com/auth/trace.append`

- **Registry API Response Structure Updates** (Story 2.2 - API Integration)
  - Updated [`ModelConfig`](mca-prototype/mca_sdk/registry/models.py) dataclass to match actual API response structure
  - Added `registry_id` field (optional, can be null for vendor models)
  - Added `deployment_id` field (optional, can be null for vendor models)
  - Added `association_id_column` field (optional, for time-series models)
  - Added `created_at` and `updated_at` timestamp fields (optional, for debugging)
  - Updated [`RegistryClient`](mca-prototype/mca_sdk/registry/client.py) to correctly extract fields from API response:
    - `model_version` now extracted from top-level (not nested in config)
    - `thresholds` extracted from top-level (not nested in config)
    - `extra_resource` extracted from nested `config.extra_resource` (not top-level)
    - Handles `config: null` case gracefully
    - Handles `phi_fields: {}` empty dict case
  - Added [`extract_phi_field_names()`](mca-prototype/mca_sdk/utils/phi_utils.py) utility function
    - Extracts field names from nested PHI structure: `{"patient_id": {"criticality": "yes"}}`
    - Handles empty dict case: `{}`
    - Used for PHI masking operations
  - **Note**: All `extra_resource` values are strings (JSONB storage), passed as-is to OpenTelemetry

### Changed
- **BREAKING CHANGE: predict() Decorator Defaults** (Story 1.13.6 - Adversarial Review Finding 1)
  - `capture_input` default changed from `True` to **`False`**
  - `capture_output` default changed from `True` to **`False`**
  - **Rationale**: Safer HIPAA compliance defaults - prevents accidental PHI capture
  - **Migration Guide**: If you rely on automatic input/output capture, explicitly set parameters:
    ```python
    # OLD (implicit True - will now be False)
    @client.predict()
    def predict(data):
        return model.predict(data)

    # NEW (explicit opt-in required)
    @client.predict(capture_input=True, capture_output=True)
    def predict(data):
        # IMPORTANT: Ensure data is sanitized before calling
        return model.predict(data)
    ```
  - **Impact**: Code using `@client.predict()` without parameters will no longer capture input/output data
  - **Security**: This change reduces risk of accidental PHI exposure in telemetry

### Added
- **Enhanced PHI Masking Patterns** (Story 1.13.6 - Adversarial Review Finding 2)
  - Added ZIP code pattern (5-digit and ZIP+4 formats)
  - Added common name patterns (First Last, Last First formats)
  - Added street address pattern (basic detection)
  - **Note**: Regex-based PHI masking has inherent limitations. Applications MUST sanitize data before instrumentation.

### Security
- Improved default security posture for data capture in predict() decorator
- Expanded PHI detection patterns for better protection in error messages and logs

### Changed (from Unreleased)
- **BREAKING CHANGE: HTTPS Enforcement** (Story 3.7)
  - Both `registry_url` and `collector_endpoint` now **require HTTPS** for non-localhost endpoints
  - HTTP connections to production endpoints are blocked with `ConfigurationError`
  - **Migration Guide**: Update all production endpoint URLs from `http://` to `https://`
  - Localhost exception: HTTP remains allowed for `localhost`, full `127.0.0.0/8` range, and `::1` for development
  - Enhanced security validation prevents credential exposure over unencrypted connections
  - **Previous Behavior**: HTTP to production endpoints raised a `SecurityWarning` but was allowed
  - **New Behavior**: HTTP to production endpoints raises `ConfigurationError` and blocks initialization

### Security
- Enhanced loopback detection with full IPv4 127.0.0.0/8 range support and IPv6 ::1
- Protection against hostname substring attacks (e.g., `localhost.attacker.com`)
- Case-insensitive localhost matching per RFC 4343

## [0.4.0] - 2026-01-26

### Added
- **Background Registry Refresh Thread** (Story 2.3)
  - Automatic refresh of registry config at configurable intervals
  - Daemon thread with graceful shutdown
  - Thread-safe config updates with locking
  - Comprehensive unit tests for thread safety and lifecycle

- **Attributes Processor Integration** (Story 4.3)
  - OpenTelemetry Collector attributes processor for metadata enrichment
  - Automatic addition of `gcp.region` and `environment` attributes
  - Non-overwriting insertion semantics to preserve existing attributes
  - Validated with functional testing across all telemetry types (metrics, logs, traces)

- **Enhanced Demo Scripts**
  - OTLP endpoint configuration for better local development
  - Improved logging and error handling

### Changed
- **OpenTelemetry Dependencies** - Updated from 1.20.0 to 1.39.0
  - `opentelemetry-api>=1.39.0`
  - `opentelemetry-sdk>=1.39.0`
  - `opentelemetry-exporter-otlp-proto-http>=1.39.0`
  - **Breaking Changes**: OTel 1.39.0 includes significant changes including `LogData` removal (replaced with `ReadableLogRecord`/`ReadWriteLogRecord`), Events API deprecation, and Python 3.8 support dropped. Review [OTel Python CHANGELOG](https://github.com/open-telemetry/opentelemetry-python/blob/main/CHANGELOG.md) for migration guidance.
- **Dependency Reorganization** - Moved `requests` from core dependencies to optional `[vendor]` extras. Install with `pip install mca-sdk[vendor]` if using vendor model integrations.

### Fixed
- CI pipeline refinements for better reliability
- Removed orphaned pyproject.toml scan after merge
- Updated pip-audit command to skip editable packages

### Security
- Added `protobuf>=5.0,<6.0` constraint to mitigate CVE-2026-0994 (DoS via nested Any messages) until patched version is available

## [0.3.0] - 2026-01-22

### Added
- **Custom Exception Hierarchy** (Story 1.14)
  - `MCASDKError` - Base exception class for all SDK errors
  - `ValidationError` - Raised when validation fails (metric names, attributes)
  - `BufferingError` - Raised when buffering operations fail (queue full, disk failure)
  - `ConfigurationError` - Raised when configuration is invalid or incomplete
  - `RegistryError` - Base exception for registry operations
  - `RegistryConnectionError` - Raised when unable to connect to registry
  - `RegistryConfigNotFoundError` - Raised when model config not found in registry
  - `RegistryAuthError` - Raised when registry authentication fails
  - All exceptions exported from main `mca_sdk` package for easy catching
  - Helpful error messages with context for debugging

### Changed
- **Enhanced Configuration Validation** (Story 1.15)
  - `MCAConfig.__post_init__` now raises `ConfigurationError` (was generic `Exception`)
  - `MCAConfig.from_env` raises `ConfigurationError` for invalid integer values
  - `MCAConfig.from_file` raises `ConfigurationError` for file/parsing errors
  - `MCAConfig.load` enforces security: `registry_token` via environment only
  - Better error messages with suggested fixes for missing `service_name`
  - URL validation for `collector_endpoint` and `registry_url`
  - Security warnings for HTTP endpoints (non-localhost) using `SecurityWarning` category

## [0.2.0] - 2026-01-12

### Added
- **Model Registry Integration**: Centralized configuration management system
  - `RegistryClient` for fetching model config from registry API
  - Support for `GET /models/{model_id}` and `GET /deployments/{deployment_id}` endpoints
  - Automatic retry with exponential backoff using existing `RetryPolicy`
  - In-memory cache with configurable TTL (default 10 minutes)
  - Bearer token authentication with HTTPS enforcement

- **Dynamic Configuration**
  - `MCAConfig` extended with 5 new fields: `registry_url`, `registry_token`, `refresh_interval_secs`, `prefer_registry`, `deployment_id`
  - Environment variable support: `MCA_REGISTRY_URL`, `MCA_REGISTRY_TOKEN`, etc.
  - Config precedence: kwargs > registry > env > YAML > defaults

- **Background Refresh**
  - Automatic refresh of thresholds and PHI fields every 10 minutes (configurable)
  - Identity fields (service_name, model_id) are immutable after startup
  - Graceful handling of registry failures with fallback to last-known config

- **PHI Fields Management**
  - Union of local and registry PHI fields for comprehensive masking
  - Dynamic updates via background refresh

- **Registry Telemetry**
  - Self-monitoring metrics: `mca.registry.refresh_success_total`, `mca.registry.refresh_latency_seconds`, `mca.registry.errors_total`

- **Security**
  - HTTPS required for non-localhost registry endpoints
  - Token never logged (even at DEBUG level)
  - Query parameters excluded from logs

- **Testing**
  - 22 unit tests for RegistryClient (fetch, cache, retry, auth)
  - 11 unit tests for hydration flow and config precedence
  - 8 integration tests with FastAPI mock registry

### Changed
- `MCAClient.__init__` now performs registry hydration before provider setup
- `MCAClient.shutdown` now stops background refresh thread and closes registry client
- `setup_all_providers` accepts `extra_resource` parameter for registry attributes
- Provider resource attributes now include registry-provided `extra_resource` fields

### API Additions
- `MCAClient.thresholds` property - Access current thresholds from registry
- `RegistryClient` class exported from main package
- `ModelConfig` and `DeploymentConfig` dataclasses exported from main package

## [0.1.0] - 2026-01-21

### Added
- Core MCA SDK with `MCAClient` for HIPAA-compliant OpenTelemetry instrumentation
- Multi-source configuration system with precedence: kwargs > registry > env > YAML > defaults
- Registry integration with automatic caching and retry mechanisms
- Validation and buffering systems for telemetry data
- Schema validation for metric naming and resource attributes
- Four working SDK examples:
  - Internal model instrumentation
  - GenAI model integration
  - Agentic AI workflows
  - Vendor model integration
- Docker Compose orchestration for local development
- Integration helpers for vendor models, GenAI, and Python decorators
- Comprehensive test suite with unit and integration tests
- Support for Python 3.10, 3.11, and 3.12

### Changed
- Buffering disabled by default for backward compatibility
- Improved demo scripts with better logging and metric handling
- Refactored metric names for consistency and clarity

### Removed
- PHI detection and masking features (architectural decision to simplify initial release)

### Fixed
- Buffering backward compatibility in `from_env()` configuration
- Critical `SecurityWarning` class placement in `MCAConfig`
- Multiple security and reliability issues identified in code review
- Test coverage expanded to meet 85% requirement

### Security
- Security hardening for multi-source configuration system
- Registry token blocked from YAML configuration files to prevent credential exposure
- Localhost validation fixed to prevent substring attacks
- Comprehensive security review addressing CRITICAL and HIGH priority issues

[unreleased]: https://gitlab.com/bhsf/ai_ml/mca-sdk/compare/v0.1.0...HEAD
[0.1.0]: https://gitlab.com/bhsf/ai_ml/mca-sdk/releases/tag/v0.1.0