@sassoftware/sas-score-mcp-serverjs 0.4.1-1 → 0.4.1-5

package/skills/sas-score-workflow/SKILL.md

@@ -1,283 +0,0 @@
----
-name: sas-score-workflow
-description: >
-  Guide the full model scoring workflow: validate model familiarity, route to appropriate scoring tool 
-  based on model type, invoke scoring with scenario data, and present merged results. Use this skill 
-  when the user wants to run predictions on data (already fetched or user-supplied). Supports generic 
-  syntax: "score with model <name>.<type> scenario =<params>" where type is job|jobdef|mas|scr|sas.
-  Trigger phrases: "score these records", "predict using model", "run model on", "score with model X.mas".
----
-
-# SAS Score Workflow
-
-Orchestrates model validation, type-based routing, scoring invocation, and result presentation. 
-Handles both MAS models and alternative scoring engines (jobs, jobdefs, SCR, SAS programs).
-
----
-
-## Generic Scoring Syntax
-
-Users can invoke scoring with a unified syntax that automatically routes to the correct tool:
-
-```
-score with model <name>.<type> [scenario =<key=value pairs>]
-score <name>.<type> [scenario =<key=value pairs>]
-```
-
-**Type determines the routing:**
-- `.job` → route to `run-job` with scoring parameters
-- `.jobdef` → route to `run-jobdef` with scoring parameters
-- `.mas` → route to `model-score` (Model Analytical Service — default)
-- `.scr` → route to `scr-score` (SAS Container Runtime)
-- `.sas` → route to `run-sas-program` to run sas program in folder
-
-If no type is specified (bare model name), assume `.mas` (MAS model).
-
-
----
-
-## Type-Based Routing
-
-Parse the model name to extract the type suffix and route accordingly:
-
-### Type: `.mas` (Model Aggregation Service)
-- **Tool**: `model-score`
-- **Use for**: Standard MAS-deployed predictive models
-- **Example**: `score with model churn.mas scenario =age=45,income=60000`
-- **Invocation**: `model-score({ model: "churn", scenario: {...} })`
-
-### Type: `.job` (SAS Viya Job)
-- **Tool**: `run-job`
-- **Use for**: Pre-built scoring jobs with parameters
-- **Example**: `score with model monthly_scorer.job scenario =month=10,year=2025`
-- **Invocation**: `run-job({ name: "monthly_scorer", scenario: {...} })`
-
-### Type: `.jobdef` (SAS Viya Job Definition)
-- **Tool**: `run-jobdef`
-- **Use for**: Job definitions that perform scoring logic
-- **Example**: `score with model fraud_detector.jobdef using amount=500,merchant=online`
-- **Invocation**: `run-jobdef({ name: "fraud_detector", scenario: {...} })`
-
-### Type: `.scr` (Score Code Runtime)
-- **Tool**: `scr-score`
-- **Use for**: Models deployed in SCR containers (REST endpoints)
-- **Example**: `score https://scr-host/models/loan.scr using age=45,credit=700`
-- **Invocation**: `scr-score({ url: "https://scr-host/models/loan", scenario: {...} })`
-
-### Type: `.sas` (SAS Program / SQL)
-- **Tool**: `run-sas-program`
-- **Use for**: Custom SAS or SQL scoring code
-- **Example**: `score my_scoring_code.sas using x=1,y=2`
-- **Invocation**: `run-sas-program({ folder: "my_scoring_code", scenario: {...} })`
-
----
-
-## Scenario Parsing
-
-The scenario parameter (comma-separated key=value pairs) is parsed into an object:
-
-```
-scenario =age=45,income=60000,region=South
-  ↓ parsed as:
-{ age: "45", income: "60000", region: "South" }
-```
-
-Accepted formats:
-- **String**: `age=45,income=60000`
-- **Object**: `{ age: 45, income: 60000 }`
-- **Array** (batch): `[ {age:45, income:60000}, {age:50, income:75000} ]`
-
----
-
-## Step 1 — Check model familiarity before scoring
-
-Score immediately if:
-- The user names a specific model they've used before in this session, OR
-- The model name matches a previously confirmed model in the conversation
-
-Pause and suggest investigation if:
-- The model name is new, vague, or misspelled-looking (e.g. "the churn one", "that cancer model")
-- The user seems unsure of the required input variable names
-
-**Suggested message:**
-> "I don't recognize that model — want me to run `find-model` to confirm it exists,
-> or `model-info` to check its required inputs first?"
-
----
-
-## Step 2 — Prepare the scenario data
-
-**For a single record** (one object):
-```javascript
-scenario = { field1: value1, field2: value2, ... }
-```
-
-**For batch scoring** (multiple records — the typical case):
-```javascript
-scenario = [
-  { field1: val1, field2: val2, ... },
-  { field1: val3, field2: val4, ... },
-  ...
-]
-```
-
-**Critical rules:**
-- Loop or call model-score **once per row**.
-- Field names in the scenario must match the model's expected input variable names **exactly**.
-  - If table column names differ from model input names, **flag this to the user** and ask for confirmation before scoring.
-  - Example: Table has `age_years`, but model expects `age` → ask user which column maps to which input.
-- Do not add units, labels, or extra metadata — raw field values only.
-
----
-
-## Step 3 — Invoke the appropriate scoring tool
-
-Based on the type extracted from the model name, invoke the corresponding tool:
-
-**For `.mas` (default):**
-```javascript
-model-score({
-  model: "<modelname>",
-  scenario: scenario,  // object or array
-  uflag: false         // set true if you need field names prefixed with _
-})
-```
-
-**For `.job`:**
-```javascript
-run-job({
-  name: "<jobname>",
-  scenario: scenario
-})
-```
-
-**For `.jobdef`:**
-```javascript
-run-jobdef({
-  name: "<jobdefname>",
-  scenario: scenario
-})
-```
-
-**For `.scr`:**
-```javascript
-scr-score({
-  url: "<scr_endpoint_url>",
-  scenario: scenario
-})
-```
-
-**For `.sas`:**
-```javascript
-run-sas-program({
-  src: "<sas_or_sql_code>",
-  scenario: scenario
-})
-```
-
-**Rules:**
-- Pass the full batch in one call; do not loop over rows
-- If scoring fails, return the structured error and suggest troubleshooting
-- For MAS models, include uflag parameter if underscore-prefixed output is needed
-- For jobs/jobdefs, scenario becomes parameter arguments
-- For SCR, include full URL endpoint
-
----
-
-## Step 4 — Present the results
-
-Merge the scoring output back with the input records and present as a table where possible.
-
-**Always surface:**
-- The key prediction/score field(s) (e.g. `P_churn`, `score`, `prediction`, `P_risk`)
-- Any probability/confidence fields for classification models (e.g. `P_class0`, `P_class1`)
-- Selected input fields that drove the prediction, so the user can see context
-
-**Formatting:**
-- Present results in a table for clarity
-- If results exceed 10 rows, show the first 10 and ask: *"Want to see more results or export the full set?"*
-- Round numeric predictions to 2–4 decimal places for readability
-
----
-
-## Common flows
-
-**Flow A — Score rows with MAS model**
-> "Score the first 10 customers in Public.customers with the churn model"
-
-1. `read-table` → { table: "Public.customers", limit: 10 }
-2. `model-score` → { model: "churn", scenario: [ ...10 row objects ] }
-3. Present merged results with prediction + key inputs
-
-**Flow B — Score with a scoring job**
-> "Score December sales with the monthly_scorer job using month=12,year=2025"
-
-1. `run-job` → { name: "monthly_scorer", scenario: { month: "12", year: "2025" } }
-2. Capture job output and tables
-3. Present results
-
-**Flow C — Score with a job definition**
-> "Run fraud detection jobdef on transaction amount=500, merchant=online"
-
-1. `run-jobdef` → { name: "fraud_detection", scenario: { amount: "500", merchant: "online" } }
-2. Capture log, listings, and tables
-3. Present results
-
-**Flow D — Score with SCR endpoint**
-> "Score with the loan model at https://scr-host/models/loan using age=45, credit_score=700"
-
-1. `scr-score` → { url: "https://scr-host/models/loan", scenario: { age: "45", credit_score: "700" } }
-2. Capture prediction response
-3. Present result
-
-**Flow E — Score results of an analytical query with MAS**
-> "Score high-value customers (spend > 5000) in mylib.sales with the fraud model"
-
-1. `sas-query` → { table: "mylib.sales", sql: "SELECT * FROM mylib.sales WHERE spend > 5000" }
-2. `model-score` → { model: "fraud", scenario: [ ...result rows ] }
-3. Present merged results
-
-**Flow F — User supplies scenario data directly**
-> "Score age=45, income=60000, region=South with the churn model"
-
-1. Skip read step
-2. `model-score` → { model: "churn", scenario: { age: "45", income: "60000", region: "South" } }
-3. Present result
-
-**Flow G — Model unfamiliar, need to confirm**
-> "Score Public.applicants with the creditRisk2 model"
-
-1. Pause — "creditRisk2" is new
-2. Suggest: `find-model` to confirm it exists, `model-info` to get input variables
-3. Once confirmed → `read-table` + `model-score`
-
-**Flow H — Generic score syntax with type routing**
-> "score with model churn.mas scenario =age=45,income=60000"
-> "score fraud_detector.jobdef where scenario =amount=500"
-> "score monthly_report.job using month=10,year=2025"
-
-1. Parse model name to extract type (.mas, .job, .jobdef, .scr, .sas)
-2. Route to appropriate tool based on type
-3. Parse scenario and invoke tool with parameters
-4. Present results from routed tool
-
----
-
-## Error handling
-
-| Problem | Action |
-|---|---|
-| Model not found | Suggest `find-model` to verify the model is deployed |
-| Input field name mismatch | Show the mismatch (table has X, model expects Y), ask user to confirm mapping |
-| Scoring error / invalid inputs | Return structured error, suggest `model-info` to check required inputs and data types |
-| Empty read result | Tell user, ask if they want to adjust the query/filter before scoring |
-| Missing input fields | Ask which table columns map to the required model inputs |
-
----
-
-## Tips
-
-- **Batch is better:** Always pass the full set of records in one `model-score` call. Do not loop.
-- **Confirm mappings:** If column names don't match model inputs, ask before scoring.
-- **Show context:** Include key input columns in the result output so predictions make sense.
-- **Limit output:** For large result sets (>10 rows), ask before showing all.