@sassoftware/sas-score-mcp-serverjs 1.0.1-2 → 1.0.1-3

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

@@ -0,0 +1,200 @@
+---
+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 `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 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**: `sas-score-model-score`
+- **Use for**: Standard MAS-deployed predictive models
+- **Example**: `score with model churn.mas scenario =age=45,income=60000`
+- **Invocation**: `sas-score-model-score({ model: "churn", scenario: {...} })`
+
+### Type: `.job` (SAS Viya 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**: `sas-score-run-job({ name: "monthly_scorer", scenario: {...} })`
+
+### Type: `.jobdef` (SAS Viya Job Definition)
+- **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**: `sas-score-run-jobdef({ name: "fraud_detector", scenario: {...} })`
+
+### Type: `.scr` (Score Code Runtime)
+- **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**: `sas-score-scr-score({ url: "https://scr-host/models/loan", scenario: {...} })`
+
+### Type: `.sas` (SAS Program / SQL)
+- **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**: `sas-score-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} ]`
+
+---
+
+## 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:
+- 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 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.
+- 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
+sas-score-model-score({
+  model: "<modelname>",
+  scenario: scenario,  // object or array
+  uflag: false         // set true if you need field names prefixed with _
+})
+```
+
+**For `.job`:**
+```javascript
+sas-score-run-job({
+  name: "<jobname>",
+  scenario: scenario
+})
+```
+
+**For `.jobdef`:**
+```javascript
+sas-score-run-jobdef({
+  name: "<jobdefname>",
+  scenario: scenario
+})
+```
+
+**For `.scr`:**
+```javascript
+sas-score-scr-score({
+  url: "<scr_endpoint_url>",
+  scenario: scenario
+})
+```
+
+**For `.sas`:**
+```javascript
+sas-score-run-sas-program({
+  src: "<sas_or_sql_code>",
+  scenario: scenario
+})
+```

package/.skills_claude/skills-index.md

@@ -0,0 +1,345 @@
+# SAS Agent Skills Index
+
+Quick reference for all available SAS agent skills in this repository.
+
+## Skills Overview
+
+The SAS agent includes 6 specialized skills for different SAS workflows. Load the most relevant skill for your task.
+
+---
+
+## 1. sas-request-classifier
+
+**File:** `skills/sas-request-classifier/SKILL.md`
+
+**Purpose:** Disambiguate SAS domain terms before using MCP tools.
+
+**Use when:**
+- Request mentions jobs, code, models, scoring, CAS tables, content, or resources
+- The correct SAS domain is not yet clear
+- Multiple interpretations are possible
+
+**Trigger phrases:**
+- "find my model"
+- "run scoring"
+- "open the table"
+- Any ambiguous request using domain terms
+
+**What it does:**
+- Classifies the request into a SAS domain (jobs, data, models, scoring, etc.)
+- Identifies which downstream skill to use
+- Raises clarifying questions if needed
+- Routes to the most appropriate skill or tool
+
+**Routes to:**
+- `sas-find-library-smart` — Library discovery
+- `sas-list-tables-smart` — Table enumeration
+- `sas-read-strategy` — Data retrieval
+- `sas-read-and-score` — Combined read + score
+- `sas-score-workflow` — Model scoring
+
+---
+
+## 2. sas-find-library-smart
+
+**File:** `skills/sas-find-library-smart/SKILL.md`
+
+**Purpose:** Find a SAS Viya library (libref or caslib) with intelligent server detection.
+
+**Use when:**
+- User needs to verify a library exists
+- User wants to determine which server (CAS or SAS) contains a library
+- Before accessing tables within a library
+
+**Trigger phrases:**
+- "find library Public"
+- "does library exist"
+- "check if library staging"
+- "locate library SASHELP"
+- "is there a library named X"
+- "verify library"
+
+**What it does:**
+- Checks CAS first for the library
+- If not found in CAS, checks SAS (with uppercase)
+- Returns the server location where the library was found
+- Offers next steps (list tables, read data, etc.)
+
+**Server detection logic:**
+- **CAS first** — Always try CAS with the library name as-is
+- **SAS second** — If not in CAS, try SAS with uppercase name
+- **Smart naming** — Knows CAS is case-sensitive, SAS requires uppercase
+
+**Integration:**
+- Use before: `sas-list-tables-smart`, `sas-read-strategy`
+
+---
+
+## 3. sas-list-tables-smart
+
+**File:** `skills/sas-list-tables-smart/SKILL.md`
+
+**Purpose:** List all tables in a SAS Viya library with intelligent server detection.
+
+**Use when:**
+- User wants to browse or explore available tables
+- User wants to see what data is available in a library
+- User wants to verify a table exists before accessing it
+
+**Trigger phrases:**
+- "list tables in Public"
+- "show tables in SASHELP"
+- "what tables are in mylib"
+- "browse tables in"
+- "tables in library"
+- "enumerate tables"
+
+**What it does:**
+- Checks CAS first for tables in the library
+- If none found in CAS, checks SAS
+- Returns paginated list of table names
+- Suggests pagination if more tables exist
+
+**Server detection logic:**
+- Same as `sas-find-library-smart`
+- Automatically determines correct server
+- Handles case sensitivity per server
+
+**Pagination:**
+- Default: 10 tables per page
+- Adjust limit based on user request
+- Use `start` parameter for pagination
+
+**Integration:**
+- Use after: `sas-find-library-smart`
+- Use before: `sas-read-strategy`
+
+---
+
+## 4. sas-read-strategy
+
+**File:** `skills/sas-read-strategy/SKILL.md`
+
+**Purpose:** Guide selection of the right data retrieval tool (raw rows vs. analytical queries).
+
+**Use when:**
+- User wants to fetch records from a SAS/CAS table
+- User wants to read data with or without aggregation
+- Ambiguity about read tool choice
+
+**Trigger phrases:**
+- "read records from"
+- "get data where"
+- "fetch rows from"
+- "query the table"
+- "give me the first N records"
+- "aggregate by"
+- "join tables"
+- "count", "average", "sum by"
+
+**What it does:**
+1. Verifies library exists (uses `sas-find-library-smart`)
+2. Locates the specific table
+3. Determines user intent: raw rows vs. analytical query
+4. Routes to correct tool:
+   - **`sas-score-read-table`** — Raw rows, simple filters, pagination
+   - **`sas-score-sas-query`** — Aggregations, joins, calculations
+
+**Decision logic:**
+
+| User's Intent | Tool | Example |
+|---|---|---|
+| Get raw records, row-by-row | `read-table` | "Show me 10 rows where status='active'" |
+| Aggregate, summarize, calculate | `sas-query` | "Average price by make" |
+
+**Server detection:**
+- Uses `sas-find-library-smart` to locate library
+- Determines correct server (CAS or SAS)
+- Handles case sensitivity
+
+**Integration:**
+- Use after: `sas-find-library-smart`, optionally `sas-list-tables-smart`
+- Use before: `sas-read-and-score` (if scoring after reading)
+
+---
+
+## 5. sas-read-and-score
+
+**File:** `skills/sas-read-and-score/SKILL.md`
+
+**Purpose:** Guide the full read → score workflow: fetch table records and score them with a MAS model.
+
+**Use when:**
+- User wants to score records from a table
+- User wants to run a model against query results
+- User wants to predict outcomes for a set of rows
+- Any request combining data reading with model scoring
+
+**Trigger phrases:**
+- "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"
+
+**What it does:**
+1. Verifies library and table existence
+2. Validates model existence and schema
+3. Reads/fetches the table data
+4. Scores each record with the model
+5. Merges predictions with original data
+6. Returns combined results
+
+**Workflow:**
+
+```
+User Request
+    ↓
+Verify Library (sas-find-library-smart)
+    ↓
+Fetch Table Data (sas-read-strategy)
+    ↓
+Validate Model & Schema
+    ↓
+Score Records (sas-score-workflow or sas-score-model-score)
+    ↓
+Merge & Present Results
+```
+
+**Error handling:**
+- Missing table → Ask for correct lib.tablename
+- Missing model → Ask for model name or suggest discovery
+- Field mismatch → Warn about column name mismatches
+- Empty result → Ask to adjust query/filter
+
+**Integration:**
+- Depends on: `sas-find-library-smart`, `sas-read-strategy`
+- Uses: `sas-score-workflow` for routing
+
+---
+
+## 6. sas-score-workflow
+
+**File:** `skills/sas-score-workflow/SKILL.md`
+
+**Purpose:** Route scoring requests to the correct tool based on model type suffix.
+
+**Use when:**
+- User requests scoring with a model name
+- Model name contains a type suffix (.job, .jobdef, .mas, .scr, .sas)
+- Model type is ambiguous
+
+**Trigger phrases:**
+- "score with model X.job"
+- "score X.jobdef scenario"
+- "score with model X.mas"
+- "score X.scr using"
+- "score with model X.sas"
+- "score with model X" (bare name, defaults to .mas)
+
+**What it does:**
+1. Parses the model name to extract type suffix
+2. Routes to the appropriate scoring tool:
+   - `.job` → `sas-score-run-job`
+   - `.jobdef` → `sas-score-run-jobdef`
+   - `.mas` → `sas-score-model-score` (default)
+   - `.scr` → `sas-score-scr-score`
+   - `.sas` → `sas-score-run-sas-program`
+3. Prepares scenario data (key=value pairs)
+4. Invokes the appropriate tool
+5. Returns predictions
+
+**Type-based routing:**
+
+| Type | Tool | Use for | Example |
+|------|------|---------|---------|
+| `.mas` | `sas-score-model-score` | MAS models | `score churn.mas scenario =age=45` |
+| `.job` | `sas-score-run-job` | SAS jobs | `score scorer.job scenario =month=10` |
+| `.jobdef` | `sas-score-run-jobdef` | Job definitions | `score detector.jobdef using x=1` |
+| `.scr` | `sas-score-scr-score` | SCR containers | `score https://scr/model.scr using x=1` |
+| `.sas` | `sas-score-run-sas-program` | SAS programs | `score code.sas using x=1,y=2` |
+| (none) | `sas-score-model-score` | Assume MAS | `score churn scenario =age=45` |
+
+**Scenario parsing:**
+```
+scenario =age=45,income=60000,region=South
+  ↓ parsed as:
+{ age: "45", income: "60000", region: "South" }
+```
+
+**Batch scoring:**
+- If multiple records: scores each row
+- Falls back to row-by-row if batch not available
+- Merges predictions with original data
+
+**Integration:**
+- Used by: `sas-read-and-score` for scoring table data
+- Input from: User or `sas-read-strategy` (if chained)
+
+---
+
+## Skill Usage Matrix
+
+Quick guide to which skill(s) to use for different tasks:
+
+| Task | Primary Skill | Secondary Skills |
+|------|---------------|------------------|
+| Find a library | `sas-find-library-smart` | — |
+| Browse tables in a library | `sas-list-tables-smart` | `sas-find-library-smart` |
+| Read raw table data | `sas-read-strategy` | `sas-find-library-smart` |
+| Aggregate/analyze table data | `sas-read-strategy` | `sas-find-library-smart` |
+| Score records from table | `sas-read-and-score` | All read skills + `sas-score-workflow` |
+| Score with MAS model | `sas-score-workflow` | — |
+| Score with SAS job | `sas-score-workflow` | — |
+| Ambiguous request | `sas-request-classifier` | Any of above |
+
+---
+
+## Loading a Skill
+
+When you encounter a task that matches a skill's trigger phrases or purpose:
+
+1. **Ask the agent** — Most skill loading is automatic
+2. **Explicitly reference** — "Use the sas-find-library-smart skill"
+3. **Context clues** — Agent infers from your request
+
+Example:
+```
+You: "List tables in Public"
+
+Agent (automatic):
+  1. Recognizes "list tables in" → loads sas-list-tables-smart
+  2. Calls sas-score-list-tables
+  3. Returns table names
+```
+
+---
+
+## Skill Composition
+
+Skills can be used together:
+
+```
+Typical Workflow:
+  sas-request-classifier
+    → sas-find-library-smart (verify library)
+    → sas-list-tables-smart (browse tables)
+    → sas-read-strategy (choose read tool)
+    → sas-read-and-score (optional: score results)
+    → sas-score-workflow (if scoring needed)
+```
+
+---
+
+## Next Steps
+
+1. **Read a skill file** — Open any `.claude/skills/<name>/SKILL.md` for details
+2. **Try a task** — Make a request matching a skill's trigger phrase
+3. **Explore workflows** — Combine skills for complex tasks
+4. **Review patterns** — See "Common patterns" in each skill file
+
+For setup instructions, see `README.md`.
+For usage instructions, see `instructions.md`.

package/.skills_github/agents/sas-viya-scoring-expert.md

@@ -0,0 +1,58 @@
+---
+name: SAS Viya Scoring Expert
+description: Specialized SAS and Viya agent that classifies requests, selects the right SAS skill, and uses MCP tools safely for jobs, CAS data, libraries, models, scoring, and content workflows.
+---
+
+# SAS Viya Scoring Expert
+
+You are a SAS Viya expert agent.
+
+Your job is to help users work with SAS and Viya resources through the SAS MCP server.
+Treat requests as domain-specific SAS tasks, not generic coding tasks.
+
+## Default behavior
+Before using MCP tools:
+- Determine whether the request is about jobs, code, CAS data, libraries, models, scoring, content, or environment issues.
+- If the request includes ambiguous terms such as model, score, scoring, read, query, job, code, table, content, asset, or resource, classify the request before acting.
+- Prefer loading the most relevant SAS skill before using low-level tools.
+- If confidence is low, ask one focused clarifying question.
+- Prefer discovery and inspection before execution, publish, scoring, deploy, write, or destructive actions.
+
+## Skill-first policy
+Use skills as the primary source of SAS workflow guidance.
+Load one or more relevant SAS skills before using tools when the request is ambiguous, cross-domain, or execution-oriented.
+Do not load unrelated skills.
+
+## Routing policy
+When a request is ambiguous or could map to more than one SAS domain:
+- Start with classification.
+- Identify the most likely SAS asset or workflow type.
+- Choose the best matching SAS skill.
+- Only then select MCP tools.
+
+## Ambiguity policy
+These terms are overloaded in SAS and Viya workflows and should not be interpreted casually:
+- model
+- score
+- scoring
+- read
+- query
+- job
+- code
+- table
+- content
+- asset
+- resource
+
+If the meaning is unclear, ask one targeted clarifying question or use discovery-oriented skills before any execution step.
+
+## Tool usage policy
+- Prefer read-only discovery before execution.
+- Confirm the target asset type before running jobs, scoring data, publishing models, or modifying content.
+- If tool results contradict the initial interpretation, correct course explicitly and continue.
+- Never invent asset names, identifiers, libraries, or model types.
+
+## Response style
+Be concise, explicit, and domain-aware.
+State which SAS concept or asset type you are acting on when ambiguity is possible.
+Prefer short structured answers when guiding the user.