@pitcher/cli-scripts 3.1.1 → 3.2.0

package/dist/src/mcp/tools/roleplay.js

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { ROLEPLAY_DIFFICULTIES, ROLEPLAY_GROUP_BY, ROLEPLAY_SESSION_SORT, runRoleplayKpis, runRoleplayRepSummary, runRoleplayScenariosList, runRoleplaySessionGet, runRoleplaySessions, runRoleplayTeam, } from '../../commands/roleplay.js';
+const instanceId = z.string().describe('Instance ID (required)');
+/** The shared roleplay_statements filters. Dates have NO default window: omitted means all time. */
+const filters = {
+    instanceId,
+    startDate: z.string().optional().describe('Window start, ISO date. Omitted = all time (no default window)'),
+    endDate: z.string().optional().describe('Window end, ISO date. Omitted = all time (no default window)'),
+    rep: z.string().optional().describe('Rep name or email contains (case-insensitive)'),
+    scenario: z.string().optional().describe('Scenario or persona name contains (case-insensitive)'),
+    difficulty: z.enum(ROLEPLAY_DIFFICULTIES).optional().describe('Scenario difficulty'),
+};
+const UNSCORED = 'A session without a score (score null: the AI evaluation failed or is pending) is UNSCORED, never 0: ' +
+    'never count it in an average or as a fail.';
+const CH_SOURCE = 'Reads the AI Roleplay analytics replica (ClickHouse roleplay_statements, the Admin Analytics tab). ' +
+    'Dates are optional and there is no default window: omitted means all time.';
+const ADMIN_ONLY = 'Instance or org admins only; anyone else gets an AUTH error, and a coaching manager should use pitcher_roleplay_team.';
+export const roleplayTools = [
+    {
+        name: 'pitcher_roleplay_kpis',
+        title: 'AI Roleplay KPIs',
+        description: 'AI Roleplay totals for an instance: total, scored and unscored sessions, the mean score of SCORED sessions, ' +
+            `mean duration and active reps, with optional rep/scenario/difficulty filters. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY}`,
+        inputShape: filters,
+        run: runRoleplayKpis,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_sessions',
+        title: 'AI Roleplay sessions',
+        description: 'AI Roleplay session list for an instance, newest first: entry_id, session_at, rep_name, who (rep email), ' +
+            'scenario_name, persona_name, difficulty, score, evaluated, rating, duration_ms. Default 20 rows, max 100 per ' +
+            `page; total_count/has_more say when there are more. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY} ` +
+            'Open one session with pitcher_roleplay_session_get (its entry_id).',
+        inputShape: {
+            ...filters,
+            sortBy: z.enum(ROLEPLAY_SESSION_SORT).optional().describe('Sort field (default session_at)'),
+            sortOrder: z.enum(['asc', 'desc']).optional().describe('Sort direction (default desc); unscored sessions sort last'),
+            page: z.number().int().optional().describe('Page number (default 1)'),
+            limit: z.number().int().optional().describe('Rows per page (default 20, max 100)'),
+        },
+        run: runRoleplaySessions,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_rep_summary',
+        title: 'AI Roleplay per-rep or per-scenario summary',
+        description: 'Per-rep (groupBy rep, keyed on the rep email) or per-scenario (groupBy scenario) session counts, scored ' +
+            'counts, mean score of scored sessions and last session, up to 50 groups with the most sessions. Exact up to ' +
+            '5000 sessions in the window (read newest first); `complete: false` means the figures cover only the newest ' +
+            `5000, so narrow the dates. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY}`,
+        inputShape: {
+            ...filters,
+            groupBy: z.enum(ROLEPLAY_GROUP_BY).optional().describe('Group by rep (default) or scenario'),
+        },
+        run: runRoleplayRepSummary,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_team',
+        title: 'AI Roleplay assignment completion',
+        description: 'Roleplay assignment completion per rep, as the AI Roleplay manager app shows it: per assignment its passing ' +
+            'score and due date, each rep\'s status (passed, in_progress, not_started, overdue, needs_coaching), sessions, ' +
+            'scored sessions, best and mean score, trend, last session, plus per-skill mean scores. Instance or org admins ' +
+            'get every roleplay assignment on the instance (scope "instance"); a coaching manager gets the assignments ' +
+            'they coach (scope "coach"). Works for any member (an empty list when they coach nobody). ' +
+            `${UNSCORED} Reads Postgres appsDB through next-core (cch-assignment, cch-session-result), not ClickHouse. ` +
+            'The server returns at most the newest 1000 sessions; `complete: false` says the cap was hit. ' +
+            'Up to 50 assignments and 100 reps each; filter with assignmentId or status.',
+        inputShape: {
+            instanceId,
+            assignmentId: z.string().optional().describe('Only this assignment (its id from an earlier call)'),
+            status: z
+                .enum(['passed', 'in_progress', 'not_started', 'overdue', 'needs_coaching'])
+                .optional()
+                .describe('Only reps with this status'),
+        },
+        run: runRoleplayTeam,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_session_get',
+        title: 'AI Roleplay session detail',
+        description: 'One AI Roleplay session: scenario, difficulty, time, duration, overall score (null = unscored, never 0), ' +
+            'evaluation status, and the evaluation summary, strengths, improvements and per-skill scores with feedback. ' +
+            'Never the transcript, messages or recordings. Opens to the rep, a coach of that rep, or an instance or org ' +
+            'admin; anyone else gets an AUTH error. Reads Postgres appsDB (cch-session-result) through next-core. ' +
+            'Takes entryId = entry_id from pitcher_roleplay_sessions.',
+        inputShape: {
+            instanceId,
+            entryId: z.string().describe('Session entry ID (entry_id from pitcher_roleplay_sessions)'),
+        },
+        run: runRoleplaySessionGet,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_roleplay_scenarios_list',
+        title: 'AI Roleplay scenarios',
+        description: 'The AI Roleplay scenario catalog of an instance: id, kind, name, persona title, description, difficulty, ' +
+            'active, time limit and the skills it is graded on (title and weight). Never a prompt. Any member. ' +
+            'Reads the instance config (appsDB cch-config) through next-core.',
+        inputShape: { instanceId },
+        run: runRoleplayScenariosList,
+        readOnly: true,
+    },
+];

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PitcherAG/web.git",
+    "directory": "packages/libs/cli-scripts"
+  },
   "keywords": [
     "pitcher",
     "cli",