@sassoftware/sas-score-mcp-serverjs 0.4.0 → 0.4.1

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

@@ -1,91 +0,0 @@
----
-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.
----
-
-# SAS Read → Score Workflow
-
-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
-
-1. **Does the user already have data in hand?**
-   - Yes → skip to Step 2 (scoring)
-   - No → use `sas-read-strategy` to fetch data
-
-2. **Is the model name familiar?**
-   - Yes → proceed to score
-   - No → pause and use `find-model` / `model-info`
-
-3. **Invoke model-score** with the fetched data
-
-4. **Merge results** and present as a table
-
----
-
-## Common flows
-
-**Flow A — Score rows from a table directly**
-> "Score the first 10 customers in Public.customers with the churn model"
-
-1. Apply `sas-read-strategy` → use `read-table` to fetch 10 rows
-2. Apply `sas-score-workflow` → invoke `model-score` and present results
-
-**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
-
-**Flow C — User supplies scenario data directly**
-> "Score age=45, income=60000, region=South with the churn model"
-
-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"
-
-1. Model unfamiliar → use `find-model` to verify existence
-2. Apply `sas-read-strategy` to fetch data
-3. Apply `sas-score-workflow` to score
-
----
-
-## For detailed guidance
-
-- **Read strategy decisions?** See `sas-read-strategy` skill
-- **Scoring validation and presentation?** See `sas-score-workflow` skill
-
-**Flow D — Model unfamiliar**
-> "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`
-
----
-
-## Error handling
-
-| 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 |

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

@@ -1,143 +0,0 @@
----
-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
-  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.
----
-
-# 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.
-
----
-
-## Determine the server location
-
-Before retrieving data, check 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
-
----
-
-## Determine the read strategy
-
-Ask yourself: does the user already have the data in hand?
-
-- **Yes (user pasted values, or data is already in context)** → skip this strategy; data is ready to use.
-- **No** → choose the read tool based on intent:
-
-| 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" |
-
----
-
-## Using read-table
-
-**When:**
-- User asks for raw records, row-by-row data
-- Simple WHERE filtering (e.g., "where status = 'active'")
-- Pagination needed ("first 50 rows", "next 10 rows")
-
-**How:**
-```
-read-table({
-  table: "tablename",
-  lib: "libraryname",
-  server: "cas" or "sas",  // determined from 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`
-- 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?"*
-- If table exists in both servers, ask user which to use
-- Return raw column values; do not transform or aggregate
-
----
-
-## Using sas-query
-
-**When:**
-- User asks for aggregation (SUM, AVG, COUNT, GROUP BY)
-- User asks for joins, calculations, or analytical insights
-- User's question is phrased analytically ("compare", "analyze", "breakdown", "trend")
-
-**How:**
-```
-sas-query({
-  table: "lib.tablename",
-  query: "user's natural language question",
-  sql: "SELECT ... FROM ... WHERE ... GROUP BY ..."  // generated from query
-})
-```
-
-**Rules:**
-- Check which server(s) contain the table using `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
-- Do not add trailing semicolons to the SQL string
-- If table name is missing, ask: *"Which table should I query? (format: lib.tablename)"*
-- If the intent is unclear, ask for clarification: *"Do you want raw rows, or an aggregated summary?"*
-
----
-
-## Common patterns
-
-**Pattern A — Raw row retrieval**
-> "Show me the first 5 rows from Public.customers"
-
-→ `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" })`
-
-**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" })`
-
-**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
-
----
-
-## Error handling
-
-| Problem | Action |
-|---|---|
-| Table not found in either server | Ask: *"Which library contains the table? (e.g., Public, Samples, mylib)"* |
-| 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)"* |
-| 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 |
-
----
-
-## 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

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

@@ -1,282 +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.