mca-sdk 0.0.0__py3-none-any.whl

mca_sdk/FOR_AI_ASSISTANTS.md

@@ -0,0 +1,202 @@
+# 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/`

mca_sdk/__init__.py

@@ -0,0 +1,76 @@
+"""MCA SDK - Model Collector Agent SDK for OpenTelemetry instrumentation.
+
+This SDK simplifies model instrumentation by providing schema validation,
+buffering, and resilience features while reducing boilerplate code from
+170+ lines to ~10 lines.
+
+Example:
+    >>> from mca_sdk import MCAClient
+    >>>
+    >>> client = MCAClient(
+    ...     service_name="readmission-model",
+    ...     model_id="mdl-001",
+    ...     team_name="clinical-ai"
+    ... )
+    >>>
+    >>> def predict(data):
+    ...     with client.trace("model.predict"):
+    ...         result = model.predict(data)
+    ...         client.record_prediction(data, result, latency=0.15)
+    ...         return result
+    >>>
+    >>> client.shutdown()
+"""
+
+from .version import __version__
+
+from .core import MCAClient
+from .config import MCAConfig
+from .registry import RegistryClient, ModelConfig, DeploymentConfig
+from .security.encryption import QueueEncryption, EncryptionManager
+from .security.migration import migrate_queue_to_encrypted, verify_encrypted_queue
+from .autolog import autolog
+from .utils.exceptions import (
+    MCASDKError,
+    ConfigurationError,
+    RegistryError,
+    RegistryConnectionError,
+    RegistryConfigNotFoundError,
+    RegistryAuthError,
+    ValidationError,
+    BufferingError,
+    SecurityError,
+    CertificateError,
+    CertificateLoadError,
+    CertificateValidationError,
+    CertificateExpiredError,
+    CertificateNotLoadedError,
+)
+
+__all__ = [
+    "MCAClient",
+    "MCAConfig",
+    "RegistryClient",
+    "ModelConfig",
+    "DeploymentConfig",
+    "QueueEncryption",
+    "EncryptionManager",
+    "migrate_queue_to_encrypted",
+    "verify_encrypted_queue",
+    "autolog",
+    "MCASDKError",
+    "ConfigurationError",
+    "RegistryError",
+    "RegistryConnectionError",
+    "RegistryConfigNotFoundError",
+    "RegistryAuthError",
+    "ValidationError",
+    "BufferingError",
+    "SecurityError",
+    "CertificateError",
+    "CertificateLoadError",
+    "CertificateValidationError",
+    "CertificateExpiredError",
+    "CertificateNotLoadedError",
+    "__version__",
+]

mca_sdk/autolog/__init__.py

@@ -0,0 +1,185 @@
+"""Auto-instrumentation for popular ML frameworks.
+
+This module provides automatic instrumentation (monkey-patching) for popular
+ML frameworks like scikit-learn, XGBoost, and LightGBM, enabling zero-code
+observability for model predictions.
+"""
+
+import logging
+import sys
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def autolog(
+    frameworks: Optional[List[str]] = None,
+    exclude: Optional[List[str]] = None,
+    capture_input: bool = False,
+    capture_output: bool = False,
+    max_payload_size: int = 10000,
+) -> None:
+    """Enable automatic instrumentation for ML frameworks.
+
+    Automatically patches popular ML frameworks to emit OpenTelemetry spans
+    and metrics when making predictions. This provides zero-code instrumentation
+    for models using standard framework APIs.
+
+    IMPORTANT: MCAClient must be initialized BEFORE calling autolog().
+    The autolog() function uses MCAClient.get_instance() to access the active client.
+
+    Args:
+        frameworks: List of specific frameworks to instrument (e.g., ["sklearn", "xgboost"]).
+            If None, automatically detects and instruments all available frameworks.
+        exclude: List of frameworks to exclude from instrumentation (e.g., ["lightgbm"]).
+        capture_input: Whether to capture input data in spans (default: False for security).
+        capture_output: Whether to capture output data in spans (default: False for security).
+        max_payload_size: Maximum size in bytes for captured input/output data (default: 10000).
+            Prevents memory bloat from large batch predictions.
+
+    Raises:
+        RuntimeError: If MCAClient has not been initialized before calling autolog().
+        ValueError: If invalid framework names provided in frameworks or exclude parameters.
+
+    Examples:
+        Enable autolog for all available frameworks:
+        >>> from mca_sdk import MCAClient, autolog
+        >>> client = MCAClient(service_name="ml-model", model_id="mdl-001", team_name="ds")
+        >>> autolog()  # Automatically instruments sklearn, xgboost, lightgbm if installed
+
+        Enable autolog for specific frameworks only:
+        >>> autolog(frameworks=["sklearn", "xgboost"])
+
+        Exclude specific frameworks:
+        >>> autolog(exclude=["lightgbm"])
+
+        Capture input/output data with size limits (use with caution - PHI risks):
+        >>> autolog(capture_input=True, capture_output=True, max_payload_size=5000)
+
+    Supported Frameworks:
+        - sklearn: scikit-learn estimators (predict, predict_proba, fit)
+        - xgboost: XGBoost Booster and sklearn API (predict)
+        - lightgbm: LightGBM Booster (predict)
+
+    Note:
+        TensorFlow and PyTorch are not currently supported but are planned for future releases.
+    """
+    from ..core.client import MCAClient
+
+    # Validate framework names
+    SUPPORTED_FRAMEWORKS = {"sklearn", "xgboost", "lightgbm"}
+
+    if frameworks is not None:
+        invalid_frameworks = set(frameworks) - SUPPORTED_FRAMEWORKS
+        if invalid_frameworks:
+            raise ValueError(
+                f"Invalid framework names: {invalid_frameworks}. "
+                f"Supported frameworks: {SUPPORTED_FRAMEWORKS}"
+            )
+
+    if exclude is not None:
+        invalid_exclude = set(exclude) - SUPPORTED_FRAMEWORKS
+        if invalid_exclude:
+            raise ValueError(
+                f"Invalid framework names in exclude: {invalid_exclude}. "
+                f"Supported frameworks: {SUPPORTED_FRAMEWORKS}"
+            )
+
+    # Check that MCAClient has been initialized
+    client_instance = MCAClient.get_instance()
+    if client_instance is None:
+        raise RuntimeError(
+            "MCAClient must be initialized before calling autolog(). "
+            "Example: client = MCAClient(service_name='...', model_id='...', team_name='...')"
+        )
+
+    # Determine which frameworks to patch
+    if frameworks is None:
+        # Auto-detect all available frameworks
+        frameworks_to_patch = _detect_installed_frameworks()
+    else:
+        # Use explicitly requested frameworks
+        frameworks_to_patch = frameworks
+
+    # Remove excluded frameworks
+    if exclude:
+        frameworks_to_patch = [f for f in frameworks_to_patch if f not in exclude]
+
+    if not frameworks_to_patch:
+        logger.warning("No ML frameworks detected or all frameworks excluded. Autolog is a no-op.")
+        return
+
+    logger.info(f"Enabling autolog for frameworks: {frameworks_to_patch}")
+
+    # Patch each framework
+    for framework_name in frameworks_to_patch:
+        try:
+            _patch_framework(framework_name, capture_input, capture_output, max_payload_size)
+            logger.info(f"Successfully patched {framework_name}")
+        except Exception as e:
+            # Graceful failure: log warning but continue
+            logger.warning(
+                f"Failed to patch {framework_name}: {e}. Continuing without instrumentation for this framework."
+            )
+
+
+def _detect_installed_frameworks() -> List[str]:
+    """Detect which ML frameworks are currently imported.
+
+    Returns:
+        List of framework names that are available in sys.modules.
+    """
+    available = []
+
+    # Check for sklearn (may be imported as 'sklearn' or 'sklearn.base')
+    if "sklearn" in sys.modules or "sklearn.base" in sys.modules:
+        available.append("sklearn")
+
+    # Check for xgboost
+    if "xgboost" in sys.modules:
+        available.append("xgboost")
+
+    # Check for lightgbm
+    if "lightgbm" in sys.modules:
+        available.append("lightgbm")
+
+    return available
+
+
+def _patch_framework(
+    framework_name: str,
+    capture_input: bool,
+    capture_output: bool,
+    max_payload_size: int,
+) -> None:
+    """Patch a specific ML framework.
+
+    Args:
+        framework_name: Name of the framework to patch ("sklearn", "xgboost", "lightgbm").
+        capture_input: Whether to capture input data.
+        capture_output: Whether to capture output data.
+        max_payload_size: Maximum size in bytes for captured data.
+
+    Raises:
+        ValueError: If framework_name is not recognized.
+        ImportError: If framework module cannot be imported.
+    """
+    if framework_name == "sklearn":
+        from ._sklearn import patch_sklearn
+
+        patch_sklearn(capture_input, capture_output, max_payload_size)
+    elif framework_name == "xgboost":
+        from ._xgboost import patch_xgboost
+
+        patch_xgboost(capture_input, capture_output, max_payload_size)
+    elif framework_name == "lightgbm":
+        from ._lightgbm import patch_lightgbm
+
+        patch_lightgbm(capture_input, capture_output, max_payload_size)
+    else:
+        raise ValueError(
+            f"Unknown framework: {framework_name}. Supported: sklearn, xgboost, lightgbm"
+        )
+
+
+__all__ = ["autolog"]