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

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

@@ -0,0 +1,300 @@
+---
+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 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 `run-job`
+   - `churn.mas` → pass `churn` to `model-score`
+   - `fraud_detector.jobdef` → pass `fraud_detector` to `run-jobdef`
+
+### 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.

package/src/authpkce.js

@@ -0,0 +1,220 @@
+/**
+ * SAS Viya PKCE Authorization Flow
+ *
+ * Uses the Authorization Code flow with PKCE (RFC 7636).
+ * Starts a local HTTP server to capture the redirect callback.
+ *
+ * Usage:
+ *   node sas-viya-pkce-auth.js
+ *
+ * Prerequisites:
+ *   - A SAS Viya client registered with:
+ *       grant_types: authorization_code
+ *       redirect_uri: http://localhost:3000/callback
+ *       PKCE enabled (no client_secret required)
+ */
+
+import http from "http";
+import https from "https";
+import crypto from "crypto";
+import url from "url";
+
+function authpkce(_appContext) {
+    let {VIYA_SERVER,CLIENTID, PORT} = _appContext;
+    // ── Configuration ────────────────────────────────────────────────────────────
+  
+    const CONFIG = {
+        authBaseUrl: `${VIYA_SERVER}/oauth/SASLogon`,
+        clientId: CLIENTID,       // <-- replace with your client ID
+        redirectUri: `http://localhost:${PORT}/callback`,
+        scopes: "openid profile",
+        localPort: PORT,
+    };
+
+    main().catch((err) => {
+      console.error("Unexpected error:", err);
+      process.exit(1);
+    });
+
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    // Generate a cryptographically random code verifier (43–128 chars, base64url)
+    function generateCodeVerifier() {
+        return crypto.randomBytes(64).toString("base64url");
+    }
+
+    // Derive the code challenge: BASE64URL(SHA-256(verifier))
+    function generateCodeChallenge(verifier) {
+        return crypto.createHash("sha256").update(verifier).digest("base64url");
+    }
+
+    // Build the SASLogon authorization URL
+    function buildAuthUrl(codeChallenge, state) {
+        const params = new URLSearchParams({
+            response_type: "code",
+            client_id: CONFIG.clientId,
+            redirect_uri: CONFIG.redirectUri,
+            scope: CONFIG.scopes,
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: "S256",
+        });
+        return `${CONFIG.authBaseUrl}/authorize?${params}`;
+    }
+
+    // Exchange the authorization code for tokens
+    function exchangeCodeForTokens(code, codeVerifier) {
+        return new Promise((resolve, reject) => {
+            const body = new URLSearchParams({
+                grant_type: "authorization_code",
+                client_id: CONFIG.clientId,
+                redirect_uri: CONFIG.redirectUri,
+                code,
+                code_verifier: codeVerifier,
+            }).toString();
+
+            const tokenUrl = new URL(`${CONFIG.authBaseUrl}/token`);
+
+            const options = {
+                hostname: tokenUrl.hostname,
+                port: tokenUrl.port || 443,
+                path: tokenUrl.pathname,
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "Content-Length": Buffer.byteLength(body),
+                },
+                // Remove the line below if your Viya instance has a valid TLS cert
+                rejectUnauthorized: false,
+            };
+
+            const req = https.request(options, (res) => {
+                let data = "";
+                res.on("data", (chunk) => (data += chunk));
+                res.on("end", () => {
+                    try {
+                        const parsed = JSON.parse(data);
+                        if (res.statusCode >= 400) {
+                            reject(new Error(`Token error (${res.statusCode}): ${data}`));
+                        } else {
+                            resolve(parsed);
+                        }
+                    } catch {
+                        reject(new Error(`Failed to parse token response: ${data}`));
+                    }
+                });
+            });
+
+            req.on("error", reject);
+            req.write(body);
+            req.end();
+        });
+    }
+
+    // Wait for the browser redirect and extract code + state
+    function waitForCallback(expectedState) {
+        return new Promise((resolve, reject) => {
+            const server = http.createServer((req, res) => {
+                const parsed = url.parse(req.url, true);
+
+                if (parsed.pathname !== "/callback") {
+                    res.writeHead(404);
+                    res.end("Not found");
+                    return;
+                }
+
+                const { code, state, error, error_description } = parsed.query;
+
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end(`
+        <html><body>
+          <h2>${error ? "Authorization failed" : "Authorization successful!"}</h2>
+          <p>You may close this tab.</p>
+        </body></html>
+      `);
+
+                server.close();
+
+                if (error) {
+                    reject(new Error(`OAuth error: ${error} — ${error_description}`));
+                    return;
+                }
+                if (state !== expectedState) {
+                    reject(new Error("State mismatch — possible CSRF attack"));
+                    return;
+                }
+
+                resolve(code);
+            });
+
+            server.listen(CONFIG.localPort, () => {
+                console.error(`Listening on http://localhost:${CONFIG.localPort}/callback`);
+            });
+
+            server.on("error", reject);
+        });
+    }
+
+    // Main flow
+    async function main() {
+        const codeVerifier = generateCodeVerifier();
+        const codeChallenge = generateCodeChallenge(codeVerifier);
+        const state = crypto.randomBytes(16).toString("hex");
+
+        const authUrl = buildAuthUrl(codeChallenge, state);
+
+        console.error("\nOpen this URL in your browser to log in:\n");
+        console.error(authUrl);
+        console.error();
+
+        // Try to auto-open in the default browser (best-effort)
+        try {
+            const { exec } = require("child_process");
+            const cmd =
+                process.platform === "win32"
+                    ? `start "" "${authUrl}"`
+                    : process.platform === "darwin"
+                        ? `open "${authUrl}"`
+                        : `xdg-open "${authUrl}"`;
+            exec(cmd);
+        } catch {
+            // ignore — user can open manually
+        }
+
+        let code;
+        try {
+            code = await waitForCallback(state);
+        } catch (err) {
+            console.error("Callback error:", err.message);
+            return null;
+        }
+
+        console.error("Authorization code received. Exchanging for tokens...");
+
+        let tokens;
+        try {
+            tokens = await exchangeCodeForTokens(code, codeVerifier);
+        } catch (err) {
+            console.error("Token exchange error:", err.message);
+            return null;
+        }
+
+        console.error("\nTokens received:");
+        console.error("  access_token :", tokens.access_token?.slice(0, 40) + "...");
+        console.error("  token_type   :", tokens.token_type);
+        console.error("  expires_in   :", tokens.expires_in, "seconds");
+        if (tokens.refresh_token) {
+            console.error("  refresh_token:", tokens.refresh_token.slice(0, 20) + "...");
+        }
+        if (tokens.id_token) {
+            console.error("  id_token     :", tokens.id_token.slice(0, 40) + "...");
+        }
+
+        // tokens.access_token is ready to use as a Bearer token for Viya REST APIs
+        return tokens.access_token
+    }
+
+
+  
+
+}