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

package/skills/sas-read-and-score/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: sas-read-and-score
 description: >
-  Guide the full read → score workflow in SAS Viya: reading records from a table (using read-table
-  or sas-query) and then scoring them with a MAS model (using model-score). Use this skill whenever
-  the user wants to score records from a table, run a model against query results, predict outcomes
-  for a set of rows, or any combination of fetching data and scoring it. Trigger phrases include:
-  "score these records", "score results of my query", "run the model on this table",
-  "predict for these customers", "fetch and score", "read and score", "score rows from",
-  "run model on table data", or any request that combines reading table data with model prediction.
+  Guide the full read → score workflow in SAS Viya: reading records from a table and then scoring
+  them with a MAS model (using sas-score-model-score). Use this skill whenever the user wants to score records
+  from a table, run a model against query results, predict outcomes for a set of rows, or any
+  combination of fetching data and scoring it. Trigger phrases include: "score these records",
+  "score results of my query", "run the model on this table", "predict for these customers",
+  "fetch and score", "read and score", "score rows from", "run model on table data", or any request
+  that combines reading/querying table data with model prediction.
 ---
 
 # SAS Read → Score Workflow
@@ -15,68 +15,79 @@ description: >
 Orchestrates the full two-step pattern of reading records from a SAS/CAS table and scoring them
 with a deployed MAS model.
 
-This skill chains two sub-skills:
-1. **sas-read-strategy** — Choose between `read-table` and `sas-query`
-2. **sas-score-workflow** — Validate model, invoke scoring, present results
-
 ---
 
-## Quick reference
+## Pre-flight verification
 
-1. **Does the user already have data in hand?**
-   - Yes → skip to Step 2 (scoring)
-   - No → use `sas-read-strategy` to fetch data
+**Before attempting to read or score table data:**
+1. **Verify library exists**: Use `sas-find-library-smart` to check the library in CAS first, then SAS if needed
+2. **Verify table exists**: Use `sas-score-find-table` to confirm the table is in the library
+3. **Confirm server location**: Ensure you know which server (CAS or SAS) contains the data
 
-2. **Is the model name familiar?**
-   - Yes → proceed to score
-   - No → pause and use `find-model` / `model-info`
+This ensures consistent behavior with other data access operations.
 
-3. **Invoke model-score** with the fetched data
+---
 
-4. **Merge results** and present as a table
+## Workflow overview
 
----
+The typical flow involves:
+1. **Fetch data** — Identify which table/query will provide input records
+2. **Validate model** — Confirm the model exists and understand its input schema
+3. **Score** — Invoke the model on the fetched records
+4. **Present results** — Merge predictions with original data and display
 
-## Common flows
+---
 
-**Flow A — Score rows from a table directly**
-> "Score the first 10 customers in Public.customers with the churn model"
+## Scenario: User already has data
 
-1. Apply `sas-read-strategy` → use `read-table` to fetch 10 rows
-2. Apply `sas-score-workflow` → invoke `model-score` and present results
+If the user provides scenario data directly (e.g., "Score age=45, income=60000 with model X"):
+- Extract the scenario values
+- Validate against model's input schema
+- Invoke scoring
+- Return prediction
 
-**Flow B — Score results of an analytical query**
-> "Score high-value customers (spend > 5000) in mylib.sales with the fraud model"
+---
 
-1. Apply `sas-read-strategy` → use `sas-query` for aggregation
-2. Apply `sas-score-workflow` → invoke `model-score` and present results
+## Scenario: User wants to score table rows
 
-**Flow C — User supplies scenario data directly**
-> "Score age=45, income=60000, region=South with the churn model"
+If the user specifies a table (e.g., "Score all customers in Public.customers with model X"):
+- Fetch raw rows (possibly filtered: "where status='active'")
+- Validate model compatibility with input columns
+- Invoke scoring on each row
+- Merge results with original data
+- Display combined table
 
-1. Skip read strategy
-2. Apply `sas-score-workflow` → invoke `model-score` and present result
+---
 
-**Flow D — Model unfamiliar**
-> "Score Public.applicants with the creditRisk2 model"
+## Scenario: User wants to score query results
 
-1. Model unfamiliar → use `find-model` to verify existence
-2. Apply `sas-read-strategy` to fetch data
-3. Apply `sas-score-workflow` to score
+If the user wants to score aggregated/filtered results (e.g., "Score high-value customers (spend > 5000) with model X"):
+- Determine which records meet criteria (aggregation/filtering)
+- Validate model expects these input columns
+- Invoke scoring
+- Merge predictions with summary data
+- Display results
 
 ---
 
-## For detailed guidance
+## Scenario: User unfamiliar with model
 
-- **Read strategy decisions?** See `sas-read-strategy` skill
-- **Scoring validation and presentation?** See `sas-score-workflow` skill
+If the user specifies a model name that's new/unknown:
+- Check if model exists
+- Retrieve model schema (inputs, outputs)
+- Show user what inputs the model expects
+- Confirm before proceeding with scoring
 
-**Flow D — Model unfamiliar**
-> "Score Public.applicants with the creditRisk2 model"
+---
+
+## Rules
 
-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`
+- Always validate table/library existence before attempting to read
+- Always check model exists before invoking `sas-score-model-score`
+- Match table columns to model input variables; warn on mismatch
+- If multiple records: score batch if possible; fall back to row-by-row
+- Merge predictions with original data using row index or key column
+- Present results as table with original columns + new prediction columns
 
 ---
 
@@ -85,7 +96,16 @@ This skill chains two sub-skills:
 | Problem | Action |
 |---|---|
 | Table not found | Ask for correct lib.tablename |
-| Model not found | Suggest find-model |
-| Field name mismatch | Show mismatch, ask user to confirm mapping |
-| Scoring error | Return structured error, suggest model-info |
-| Empty read result | Tell user, ask if they want to adjust the query/filter |
+| Model not found | Inform user; suggest verifying model name |
+| Field/column mismatch | Show mismatch, ask user to confirm or adjust query |
+| Scoring error | Return structured error, suggest checking model inputs |
+| Empty read result | Inform user, ask if they want to adjust the query/filter |
+| Data type mismatch | Warn user about type conversion, proceed or ask for clarification |
+
+---
+
+## Integration with other skills
+
+- **Before this workflow**: Use `sas-find-library-smart` to verify the library exists
+- **For data retrieval**: Use `sas-read-strategy` to choose the right read tool (read-table vs sas-query)
+- **For scoring**: Use `sas-score-workflow` for advanced scoring options beyond MAS models

package/skills/sas-read-strategy/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: sas-read-strategy
 description: >
-  Guide the user in choosing the right data retrieval tool: read-table (for raw row access with filters)
-  or sas-query (for analytical queries, aggregations, joins). Use this skill when the user wants to
+  Guide the user in choosing the right data retrieval tool: sas-score-read-table (for raw row access with filters)
+  or sas-score-sas-query (for analytical queries, aggregations, joins). Use this skill when the user wants to
   fetch records from a SAS/CAS table. Trigger phrases include: "read records from", "get data where",
   "fetch rows from", "query the table", "give me the first N records", "aggregate by", "join tables",
   or any request that starts with data retrieval.
@@ -10,21 +10,25 @@ description: >
 
 # SAS Read Strategy
 
-Guides the decision between `read-table` and `sas-query` based on the user's intent and the nature
-of the data operation.
-
----
+Guides the decision between `sas-score-read-table` and `sas-score-sas-query` based on the user's intent and the nature
+of the data operation. Determines which server contains the data and which retrieval tool is most appropriate.
 
 ## Determine the server location
 
-Before retrieving data, check which server(s) contain the table:
+Before retrieving data, verify the library and determine which server(s) contain the table:
 
-1. **Check both servers**: Use `find-table` to check if the table exists in CAS and/or SAS
-2. **Decide server placement**:
-   - If table exists **only in CAS** → set `server: "cas"`
-   - If table exists **only in SAS** → set `server: "sas"`
-   - If table exists **in both** → ask the user: *"The table exists in both CAS and SAS. Which server would you prefer to query from?"*
-   - If table exists **in neither** → inform user and ask which library to search in
+**Step 1: Verify library existence**
+- Use `sas-find-library-smart` skill to check the library in CAS first, then SAS if needed
+- This establishes the correct server and uppercase convention for SAS libraries
+- Informs the user which server contains the library
+
+**Step 2: Locate the specific table**
+- Use `sas-score-find-table` to check if the table exists in the library
+- Possible outcomes:
+  - If table exists **only in CAS** → set `server: "cas"`
+  - If table exists **only in SAS** → set `server: "sas"`
+  - If table exists **in both** → ask the user: *"The table exists in both CAS and SAS. Which server would you prefer to query from?"*
+  - If table exists **in neither** → inform user and suggest verifying the table name
 
 ---
 
@@ -37,8 +41,8 @@ Ask yourself: does the user already have the data in hand?
 
 | User's Intent | Tool | Example |
 |---|---|---|
-| Get specific raw rows, apply simple filter, retrieve first N records | `read-table` | "Show me 10 rows from customers where status='active'" |
-| Aggregate/summarize, calculate, join tables, analytical question | `sas-query` | "Average salary by department", "Count orders by region" |
+| Get specific raw rows, apply simple filter, retrieve first N records | `sas-score-read-table` | "Show me 10 rows from customers where status='active'" |
+| Aggregate/summarize, calculate, join tables, analytical question | `sas-score-sas-query` | "Average salary by department", "Count orders by region" |
 
 ---
 
@@ -51,17 +55,17 @@ Ask yourself: does the user already have the data in hand?
 
 **How:**
 ```
-read-table({
+sas-score-read-table({
   table: "tablename",
   lib: "libraryname",
-  server: "cas" or "sas",  // determined from find-table check
+  server: "cas" or "sas",  // determined from sas-score-find-table check
   limit: N,        // default 10, adjust based on user request
   where: "..."     // optional SQL WHERE clause
 })
 ```
 
 **Rules:**
-- Always determine the server first using `find-table`
+- Always determine the server first using `sas-score-find-table`
 - Keep batch size ≤ 50 rows unless the user explicitly requests more
 - If table name is missing, ask: *"Which table should I read from? (format: lib.tablename)"*
 - If library is missing, ask: *"Which library contains the table?"*
@@ -87,7 +91,7 @@ sas-query({
 ```
 
 **Rules:**
-- Check which server(s) contain the table using `find-table` first
+- Check which server(s) contain the table using `sas-score-find-table` first
 - If table exists in both CAS and SAS, ask user which to query from
 - Parse the user's natural language question into a PROC SQL SELECT statement
 - Ensure SELECT statement is valid SQL syntax
@@ -102,22 +106,22 @@ sas-query({
 **Pattern A — Raw row retrieval**
 > "Show me the first 5 rows from Public.customers"
 
-→ `read-table({ table: "customers", lib: "Public", limit: 5 })`
+→ `sas-score-read-table({ table: "customers", lib: "Public", limit: 5 })`
 
 **Pattern B — Filtered retrieval**
 > "Get all high-value orders (amount > 5000) from mylib.orders"
 
-→ `read-table({ table: "orders", lib: "mylib", where: "amount > 5000" })`
+→ `sas-score-read-table({ table: "orders", lib: "mylib", where: "amount > 5000" })`
 
 **Pattern C — Aggregation**
 > "What is the average price by make in Public.cars?"
 
-→ `sas-query({ table: "Public.cars", query: "average price by make", sql: "SELECT make, AVG(msrp) AS avg_price FROM Public.cars GROUP BY make" })`
+→ `sas-score-sas-query({ table: "Public.cars", query: "average price by make", sql: "SELECT make, AVG(msrp) AS avg_price FROM Public.cars GROUP BY make" })`
 
 **Pattern D — Join + analysis**
 > "Show me total sales by customer in the sales and customers tables"
 
-→ `sas-query()` with a JOIN in the generated SQL
+→ `sas-score-sas-query()` with a JOIN in the generated SQL
 
 ---
 
@@ -125,19 +129,28 @@ sas-query({
 
 | Problem | Action |
 |---|---|
-| Table not found in either server | Ask: *"Which library contains the table? (e.g., Public, Samples, mylib)"* |
+| Library not found | Use `sas-find-library-smart` skill to verify the library exists |
+| Table not found in either server | Inform user and suggest checking the table name |
 | Table exists in both CAS and SAS | Ask: *"The table exists in both servers. Which would you prefer: CAS or SAS?"* |
 | Table exists only in one server | Use that server automatically in your request |
-| Library not found | Ask: *"Which library contains the table? (e.g., Public, Samples, mylib)"* |
+| Table name missing entirely | Ask: *"Which table should I read from?"* |
 | Ambiguous intent (raw vs aggregate) | Ask: *"Do you want individual rows or a summary by some field?"* |
 | Empty result | Inform user, ask to adjust filter or query |
 
 ---
 
+## Integration with other skills
+
+- **Before this skill**: Use `sas-find-library-smart` to verify and locate the library
+- **After this skill**: Use `sas-read-and-score` to score the retrieved data
+
+---
+
 ## Next steps
 
-Once data is retrieved, decide the next action based on context:
-- If user wants to **score** the data → move to `sas-score-workflow`
-- If user wants to **visualize** → present as table or chart
-- If user wants to **export** → format and offer download
-- If user wants to **analyze further** → ask clarifying questions
+Once data is retrieved, typical follow-ups include:
+- **Visualize** — present as table or chart
+- **Export** — format and offer download
+- **Analyze further** — ask clarifying questions
+- **Score** — run predictions on the data
+- **Combine** — join with other datasets

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

@@ -1,4 +1,4 @@
----
+gi ---
 name: sas-score-workflow
 description: >
   Guide the full model scoring workflow: validate model familiarity, route to appropriate scoring tool 
@@ -25,50 +25,67 @@ 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
+- `.job` → route to `sas-score-run-job` with scoring parameters
+- `.jobdef` → route to `sas-score-run-jobdef` with scoring parameters
+- `.mas` → route to `sas-score-model-score` (Model Analytical Service — default)
+- `.scr` → route to `sas-score-scr-score` (SAS Container Runtime)
+- `.sas` → route to `sas-score-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:
+### Parse and Strip Model Type
+
+When a user provides a model name with a type suffix (e.g., `simplejon.job`, `churn.mas`):
+
+1. **Extract the type:** Split on the last dot to identify the type suffix
+   - `simplejon.job` → type = `job`, base name = `simplejon`
+   - `churn.mas` → type = `mas`, base name = `churn`
+   - `fraud_detector.jobdef` → type = `jobdef`, base name = `fraud_detector`
+
+2. **Validate the type:** Confirm it matches one of the supported types: `job`, `jobdef`, `mas`, `scr`, `sas`
+   - If type is unrecognized, assume `.mas` (default MAS model) and treat the entire input as the model name
+
+3. **Strip the type suffix:** Remove the `.type` from the model name before passing to the routing tool
+   - **Critical:** Always pass the base name (without the dot and type) to the invoked tool
+   - `simplejon.job` → pass `simplejon` to `sas-score-run-job`
+   - `churn.mas` → pass `churn` to `sas-score-model-score`
+   - `fraud_detector.jobdef` → pass `fraud_detector` to `sas-score-run-jobdef`
 
 ### Type: `.mas` (Model Aggregation Service)
-- **Tool**: `model-score`
+- **Tool**: `sas-score-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: {...} })`
+- **Invocation**: `sas-score-model-score({ model: "churn", scenario: {...} })`
 
 ### Type: `.job` (SAS Viya Job)
-- **Tool**: `run-job`
+- **Tool**: `sas-score-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: {...} })`
+- **Invocation**: `sas-score-run-job({ name: "monthly_scorer", scenario: {...} })`
 
 ### Type: `.jobdef` (SAS Viya Job Definition)
-- **Tool**: `run-jobdef`
+- **Tool**: `sas-score-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: {...} })`
+- **Invocation**: `sas-score-run-jobdef({ name: "fraud_detector", scenario: {...} })`
 
 ### Type: `.scr` (Score Code Runtime)
-- **Tool**: `scr-score`
+- **Tool**: `sas-score-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: {...} })`
+- **Invocation**: `sas-score-scr-score({ url: "https://scr-host/models/loan", scenario: {...} })`
 
 ### Type: `.sas` (SAS Program / SQL)
-- **Tool**: `run-sas-program`
+- **Tool**: `sas-score-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: {...} })`
+- **Invocation**: `sas-score-run-sas-program({ folder: "my_scoring_code", scenario: {...} })`
+
+
 
 ---
 
@@ -89,6 +106,13 @@ Accepted formats:
 
 ---
 
+## Integration with other skills
+
+- **Before scoring table data**: Use `sas-find-library-smart` to verify the library, then `sas-read-strategy` to fetch records
+- **For read + score workflows**: Use `sas-read-and-score` for the complete end-to-end pattern
+
+---
+
 ## Step 1 — Check model familiarity before scoring
 
 Score immediately if:
@@ -122,7 +146,7 @@ scenario = [
 ```
 
 **Critical rules:**
-- Loop or call model-score **once per row**.
+- Loop or call sas-score-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.
@@ -136,7 +160,7 @@ Based on the type extracted from the model name, invoke the corresponding tool:
 
 **For `.mas` (default):**
 ```javascript
-model-score({
+sas-score-model-score({
   model: "<modelname>",
   scenario: scenario,  // object or array
   uflag: false         // set true if you need field names prefixed with _
@@ -145,7 +169,7 @@ model-score({
 
 **For `.job`:**
 ```javascript
-run-job({
+sas-score-run-job({
   name: "<jobname>",
   scenario: scenario
 })
@@ -153,7 +177,7 @@ run-job({
 
 **For `.jobdef`:**
 ```javascript
-run-jobdef({
+sas-score-run-jobdef({
   name: "<jobdefname>",
   scenario: scenario
 })
@@ -161,7 +185,7 @@ run-jobdef({
 
 **For `.scr`:**
 ```javascript
-scr-score({
+sas-score-scr-score({
   url: "<scr_endpoint_url>",
   scenario: scenario
 })
@@ -169,7 +193,7 @@ scr-score({
 
 **For `.sas`:**
 ```javascript
-run-sas-program({
+sas-score-run-sas-program({
   src: "<sas_or_sql_code>",
   scenario: scenario
 })
@@ -205,43 +229,43 @@ Merge the scoring output back with the input records and present as a table wher
 **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 ] }
+1. `sas-score-read-table` → { table: "Public.customers", limit: 10 }
+2. `sas-score-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" } }
+1. `sas-score-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" } }
+1. `sas-score-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" } }
+1. `sas-score-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 ] }
+1. `sas-score-sas-query` → { table: "mylib.sales", sql: "SELECT * FROM mylib.sales WHERE spend > 5000" }
+2. `sas-score-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" } }
+2. `sas-score-model-score` → { model: "churn", scenario: { age: "45", income: "60000", region: "South" } }
 3. Present result
 
 **Flow G — Model unfamiliar, need to confirm**
@@ -249,7 +273,7 @@ Merge the scoring output back with the input records and present as a table wher
 
 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`
+3. Once confirmed → `sas-score-read-table` + `sas-score-model-score`
 
 **Flow H — Generic score syntax with type routing**
 > "score with model churn.mas scenario =age=45,income=60000"
@@ -277,7 +301,14 @@ Merge the scoring output back with the input records and present as a table wher
 
 ## Tips
 
-- **Batch is better:** Always pass the full set of records in one `model-score` call. Do not loop.
+- **Batch is better:** Always pass the full set of records in one `sas-score-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.
+
+---
+
+## Integration with other skills
+
+- **Before scoring table data**: Use `sas-find-library-smart` to verify the library, then `sas-read-strategy` to fetch records
+- **For read + score workflows**: Use `sas-read-and-score` for the complete end-to-end pattern