Update to DataRobot Skills

{
  "description": "Tools and guidance for making predictions with DataRobot deployments, including real-time predictions, batch scoring, prediction dataset generation, and prediction explanations (SHAP/XEMP). Use when making predictions, running batch scoring, generating prediction datasets, or explaining individual predictions from a deployment.",
  "included_files": [
    {
      "relative_path": "scripts/generate_prediction_data_template.py",
      "size_in_bytes": 3101
    },
    {
      "relative_path": "scripts/get_deployment_features.py",
      "size_in_bytes": 2845
    },
    {
      "relative_path": "scripts/make_prediction.py",
      "size_in_bytes": 4670
    },
    {
      "relative_path": "scripts/validate_prediction_data.py",
      "size_in_bytes": 4079
    }
  ],
  "name": "datarobot-predictions",
  "skill_md_contents": "---\nname: datarobot-predictions\ndescription: Tools and guidance for making predictions with DataRobot deployments, including real-time predictions, batch scoring, prediction dataset generation, and prediction explanations (SHAP/XEMP). Use when making predictions, running batch scoring, generating prediction datasets, or explaining individual predictions from a deployment.\n---\n\n# DataRobot Predictions Skill\n\nThis skill provides comprehensive guidance for working with DataRobot predictions, including real-time predictions, batch scoring, and generating prediction datasets.\n\n## Quick Start\n\n**Most common use case**: Generate predictions for a deployment\n\n1. **Get deployment features**: `get_deployment_features(deployment_id)` to understand required columns\n2. **Generate template**: `generate_prediction_data_template(deployment_id, n_rows)` to create CSV structure\n3. **Make predictions**: Use `deployment.predict_batch(...)` (works for both single-row “real-time” and batch scoring)\n\n**Example**: \"Generate a prediction dataset template for deployment abc123 with 10 rows\"\n\n**To also explain predictions**: pass `--max-explanations N` to `make_prediction.py` (or the\n`max_explanations=N` kwarg in code). See [Prediction Explanations](#prediction-explanations) below.\n\n## When to use this skill\n\nUse this skill when you need to:\n- Make predictions from deployed DataRobot models\n- Explain individual predictions from a deployment (SHAP or XEMP, per-row)\n- Generate prediction dataset templates\n- Validate prediction data before scoring\n- Understand deployment feature requirements\n- Perform batch predictions on large datasets\n- Get sample training data to understand expected formats\n\n> For post-hoc explanations against a **training project / leaderboard model** (not a deployment),\n> use the `datarobot-model-explainability` skill instead. This skill covers deployment-time\n> explanations returned alongside scoring.\n\n## Key capabilities\n\n### 1. Understanding Deployment Requirements\n\nBefore making predictions, you need to understand what features a deployment requires:\n\n- **Feature names and types**: Know which columns are needed (numeric, categorical, text, date)\n- **Feature importance**: Understand which features matter most\n- **Target information**: Know what you're predicting\n- **Time series configuration**: If applicable, understand datetime columns and series IDs\n\n### 2. Generating Prediction Datasets\n\nCreate properly formatted prediction datasets:\n\n- Generate CSV templates with all required columns\n- Include sample values appropriate for each feature type\n- Add metadata comments explaining the model structure\n- Ensure correct column ordering\n\n### 3. Validating Prediction Data\n\nValidate datasets before making predictions:\n\n- Check for missing required features\n- Verify data types match expected types\n- Identify missing low-importance features (warnings)\n- Note extra columns that will be ignored\n\n### 4. Making Predictions\n\nExecute predictions using various methods:\n\n- **Real-time predictions**: Fast, synchronous predictions for individual records\n- **Batch predictions**: Process large datasets efficiently\n- **Time series predictions**: Handle forecasting scenarios with proper datetime handling\n\n## Workflow examples\n\n### Example 1: Generate prediction dataset for a new scenario\n\n**User request**: \"I want to predict sales for next week for store_A with temperatures of 75°F each day and no promotions.\"\n\n**Agent workflow**:\n1. Get deployment features to understand required columns\n2. Generate a prediction data template with 7 rows (one week)\n3. Fill in the template with user's specific values:\n   - Set temperature = 75 for all rows\n   - Set promotion = 0 for all rows\n   - Set store_id = \"store_A\" for all rows\n   - Set dates for next 7 days\n4. Validate the data to ensure it's correct\n5. Make predictions using the validated dataset\n\n### Example 2: Batch scoring a CSV file\n\n**User request**: \"Score all records in my prediction_data.csv file using deployment abc123.\"\n\n**Agent workflow**:\n1. Validate the CSV file structure matches deployment requirements\n2. Upload the file or provide file path\n3. Submit batch prediction job\n4. Monitor job status\n5. Retrieve and return prediction results\n\n## Using DataRobot SDK\n\nThis skill guides you to use the DataRobot Python SDK directly. Install the SDK if needed:\n\n```bash\npip install datarobot datarobot-predict\n```\n\n### Key SDK Operations\n\nUse these DataRobot SDK methods to work with predictions:\n\n**Deployment Information**:\n- `dr.Deployment.get(deployment_id)` - Get deployment details\n- `deployment.get_features()` - Get required features (name/type/importance)\n\n**Predictions**:\n- `deployment.predict_batch(source)` - Convenience batch prediction API (CSV path, file object, or pandas DataFrame)\n- `dr.BatchPredictionJob.score(deployment=deployment, ...)` - Advanced batch prediction control\n- `job.get_result_when_complete()` - Wait for batch scoring to finish and download results\n\n**Data Management**:\n- `dr.Dataset.create_from_file(file_path)` - Upload dataset\n- `dr.Dataset.get(dataset_id)` - Get dataset info\n\nSee the [Common Patterns](#common-patterns) section below for complete examples.\n\n## Prediction Explanations\n\nDeployments can return per-row explanations (top feature contributions) alongside predictions.\nTwo algorithms are available depending on how the deployment was configured:\n\n- **SHAP** (`shap`): SHapley Additive exPlanations. Available on tree-based models when SHAP was\n  enabled at deployment time. Returns signed contributions in the model's score space.\n- **XEMP** (`xemp`): DataRobot's eXplainable AI for the eXact Model Prediction. Default when SHAP\n  is not enabled. Returns top-N strongest features with a qualitative strength (`+++`, `--`, etc.).\n\nIf you omit `explanation_algorithm`, the deployment's default is used.\n\n### How to request explanations\n\nPass `max_explanations=N` (and any optional filters) when calling `datarobot_predict.deployment.predict`:\n\n```python\nimport datarobot as dr\nimport pandas as pd\nfrom datarobot_predict.deployment import predict as dr_predict\n\ndr.Client()\ndeployment = dr.Deployment.get(\"abc123\")\n\nresult = dr_predict(\n    deployment=deployment,\n    data_frame=pd.DataFrame([{\"feature1\": 10, \"feature2\": 20}]),\n    max_explanations=3,  # top 3 contributors per row\n    explanation_algorithm=\"shap\",  # or \"xemp\"; omit for deployment default\n    # threshold_high=0.8,                # optional: only explain rows scoring > 0.8\n    # threshold_low=0.2,                 # optional: only explain rows scoring < 0.2\n    # passthrough_columns=\"all\",         # optional: echo input columns through to output\n)\nprint(result.dataframe.to_dict(orient=\"records\"))\n```\n\nThe result DataFrame includes columns like `EXPLANATION_1_FEATURE_NAME`,\n`EXPLANATION_1_ACTUAL_VALUE`, `EXPLANATION_1_STRENGTH`, `EXPLANATION_1_QUALITATIVE_STRENGTH` for\neach of the top-N contributors.\n\n### Parameter reference\n\n| Parameter | Purpose |\n|-----------|---------|\n| `max_explanations` | Top-N contributors per row. `0` (default) disables explanations. |\n| `max_ngram_explanations` | Text models only: cap text-segment explanations per row. |\n| `threshold_high` | Only explain rows with prediction probability **above** this (0–1). |\n| `threshold_low` | Only explain rows with prediction probability **below** this (0–1). |\n| `explanation_algorithm` | `\"shap\"` or `\"xemp\"`; omit to use deployment default. |\n| `passthrough_columns` | `\"all\"` or set of input column names to echo through to output. |\n\n### CLI shortcut\n\n```bash\npython scripts/make_prediction.py abc123 '{\"feature1\": 10, \"feature2\": 20}' \\\n    --max-explanations 3 --explanation-algorithm shap\n```\n\n### When to use which threshold\n\n- `threshold_high` is useful when only positive (high-risk / fraud / churn-likely) predictions need\n  explaining — saves compute on a large batch.\n- `threshold_low` is the mirror image for low-probability rows.\n- Setting both restricts explanations to rows outside the `[low, high]` band.\n\n### Common errors\n\n- **\"Prediction explanations not enabled\"**: the deployment was created without explanations support.\n  Re-deploy the model with explanations enabled, or use a deployment that has them.\n- **`max_explanations` ignored / no explanation columns in output**: confirm you're calling\n  `datarobot_predict.deployment.predict(...)` and that the deployment has explanations enabled.\n  The `deployment.predict_batch()` convenience wrapper on the SDK is intended for plain scoring;\n  use `datarobot_predict.deployment.predict` when you need explanation kwargs.\n\n## Helper Scripts\n\nThis skill includes executable helper scripts that Claude can run directly:\n\n- `scripts/get_deployment_features.py` - Get deployment feature requirements\n- `scripts/generate_prediction_data_template.py` - Generate CSV template\n- `scripts/validate_prediction_data.py` - Validate prediction data\n- `scripts/make_prediction.py` - Make real-time predictions\n\n**Usage example**:\n```bash\n# Get deployment features\npython scripts/get_deployment_features.py abc123\n\n# Generate template\npython scripts/generate_prediction_data_template.py abc123 10 template.csv\n\n# Validate data\npython scripts/validate_prediction_data.py abc123 prediction_data.csv\n\n# Make prediction\npython scripts/make_prediction.py abc123 '{\"feature1\": 10, \"feature2\": 20}'\n\n# Make prediction with top-3 SHAP explanations\npython scripts/make_prediction.py abc123 '{\"feature1\": 10, \"feature2\": 20}' \\\n    --max-explanations 3 --explanation-algorithm shap\n```\n\nClaude can run these scripts directly or use them as reference when writing code.\n\n## Best practices\n\n1. **Always validate first**: Validate prediction data before submitting predictions to catch errors early\n2. **Use templates**: Generate templates to ensure correct structure and avoid missing columns\n3. **Check feature types**: Ensure numeric features are numbers, categorical features match training values\n4. **Handle time series**: For time series models, ensure datetime columns and series IDs are properly formatted\n5. **Monitor batch jobs**: For large batch predictions, check job status and handle errors appropriately\n\n## Common patterns\n\n### Pattern 1: Get deployment features and make single prediction (optionally with explanations)\n```python\nimport datarobot as dr\nimport pandas as pd\nfrom datarobot_predict.deployment import predict as dr_predict\n\n# Initialize client\ndr.Client()\n\ndeployment = dr.Deployment.get(\"abc123\")\n\nprediction_data = {\n    \"feature1\": value1,\n    \"feature2\": value2,\n    # ... all required features (excluding target)\n}\n\n# Score one row. Add max_explanations=N to get top-N explanations per row.\nresult = dr_predict(\n    deployment=deployment,\n    data_frame=pd.DataFrame([prediction_data]),\n    max_explanations=3,  # optional; 0/omit to disable explanations\n    explanation_algorithm=\"shap\",  # optional; omit to use deployment default\n)\nprint(result.dataframe.to_dict(orient=\"records\"))\n```\n\n### Pattern 2: Generate template and batch predictions\n```python\nimport datarobot as dr\nimport pandas as pd\n\n# Initialize client\ndr.Client()\n\n# Get deployment features\ndeployment = dr.Deployment.get(\"abc123\")\nmodel = dr.Model.get(deployment.model[\"id\"])\nfeatures = model.get_features()\n\n# Create template DataFrame\nprediction_features = [f for f in features if f.name != model.target_name]\ntemplate_df = pd.DataFrame(columns=[f.name for f in prediction_features])\n\n# Add sample rows\nfor i in range(100):\n    row = {}\n    for feature in prediction_features:\n        if feature.feature_type == \"Numeric\":\n            row[feature.name] = 0.0\n        elif feature.feature_type == \"Categorical\":\n            row[feature.name] = \"sample_value\"\n        else:\n            row[feature.name] = \"\"\n    template_df = pd.concat([template_df, pd.DataFrame([row])], ignore_index=True)\n\n# Save template\ntemplate_df.to_csv(\"prediction_template.csv\", index=False)\n\n# Fill template with actual data (modify CSV as needed)\n# ...\n\n# Submit batch prediction\njob = dr.BatchPredictionJob.score(\n    deployment_id=deployment.id,\n    intake_settings={\"type\": \"localFile\", \"file\": \"prediction_template.csv\"},\n    output_settings={\"type\": \"localFile\", \"path\": \"predictions_output.csv\"},\n)\n\n# Monitor job\njob_status = dr.BatchPredictionJob.get(job.id)\nprint(f\"Job status: {job_status.status}\")\n\n# Download results when complete\nif job_status.status == \"completed\":\n    results = dr.BatchPredictionJob.download(job.id)\n```\n\n## Error handling\n\nCommon errors and solutions:\n\n- **Missing required features**: Use `get_deployment_features` to get complete list\n- **Wrong data types**: Check feature types and convert accordingly\n- **Invalid categorical values**: Use training data sample to see valid values\n- **Time series format errors**: Ensure datetime format matches training data\n\n## SDK Setup\n\n### Install DataRobot SDK\n\n```bash\npip install datarobot datarobot-predict\n```\n\n### Initialize Client\n\n```python\nimport datarobot as dr\n\n# Initialize client with API credentials\ndr.Client()\n```\n\n### Environment Variables\n\nSet these environment variables or pass them directly:\n\n- `DATAROBOT_API_TOKEN` - Your DataRobot API token\n- `DATAROBOT_ENDPOINT` - Your DataRobot endpoint (default: https://app.datarobot.com)\n\n## Resources\n\n- [DataRobot Python SDK Documentation](https://datarobot-public-api-client.readthedocs-hosted.com/)\n- [DataRobot Predictions Documentation](https://docs.datarobot.com/en/docs/predictions/index.html)\n- [DataRobot API Reference](https://docs.datarobot.com/en/docs/api/reference/index.html)\n- [Batch Predictions Guide](https://docs.datarobot.com/en/docs/api/reference/sdk/batch-predictions.html)\n\n"
}