@roarkanalytics/sdk-mcp 4.20.0 → 4.22.1

package/server.mjs

@@ -10,7 +10,7 @@ import { getInstructions } from "./instructions.mjs";
 import { blockedMethodsForCodeTool } from "./methods.mjs";
 export const newMcpServer = async ({ stainlessApiKey, customInstructionsPath, }) => new McpServer({
     name: 'roarkanalytics_sdk_api',
-    version: '4.20.0', // x-release-please-version
+    version: '4.22.1', // x-release-please-version
 }, {
     instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }),
     capabilities: { tools: {}, logging: {} },

package/src/code-tool-worker.ts

@@ -146,13 +146,20 @@ const fuse = new Fuse(
     'client.simulationToolFixture.delete',
     'client.simulationToolFixture.list',
     'client.simulationToolFixture.update',
+    'client.simulationRunGroup.create',
+    'client.simulationRunGroup.delete',
+    'client.simulationRunGroup.getByID',
+    'client.simulationRunGroup.list',
+    'client.simulationRunGroup.regenerateReport',
     'client.simulationRunPlan.create',
     'client.simulationRunPlan.delete',
     'client.simulationRunPlan.getByID',
     'client.simulationRunPlan.list',
     'client.simulationRunPlan.update',
     'client.simulationRunPlanJob.cancel',
+    'client.simulationRunPlanJob.createDebrief',
     'client.simulationRunPlanJob.getByID',
+    'client.simulationRunPlanJob.getResults',
     'client.simulationRunPlanJob.list',
     'client.simulationRunPlanJob.start',
     'client.simulationPersona.create',

package/src/local-docs-search.ts

@@ -1311,6 +1311,159 @@ const EMBEDDED_METHODS: MethodEntry[] = [
       },
     },
   },
+  {
+    name: 'list',
+    endpoint: '/v1/simulation/run-group',
+    httpMethod: 'get',
+    summary: 'List run groups',
+    description:
+      'Returns the run groups in the project, newest first, with their runs and where each group report stands. Read a report document from GET /v1/simulation/run-group/{groupId}.',
+    stainlessPath: '(resource) simulationRunGroup > (method) list',
+    qualified: 'client.simulationRunGroup.list',
+    params: ['limit?: number;', 'offset?: number;'],
+    response:
+      "{ data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }[]; pagination: { hasMore: boolean; limit: number; offset: number; total: number; }; }",
+    markdown:
+      "## list\n\n`client.simulationRunGroup.list(limit?: number, offset?: number): { data: object[]; pagination: object; }`\n\n**get** `/v1/simulation/run-group`\n\nReturns the run groups in the project, newest first, with their runs and where each group report stands. Read a report document from GET /v1/simulation/run-group/{groupId}.\n\n### Parameters\n\n- `limit?: number`\n  Maximum number of run groups to return (default: 20, max: 100)\n\n- `offset?: number`\n  Pagination offset\n\n### Returns\n\n- `{ data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }[]; pagination: { hasMore: boolean; limit: number; offset: number; total: number; }; }`\n\n  - `data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }[]`\n  - `pagination: { hasMore: boolean; limit: number; offset: number; total: number; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst simulationRunGroups = await client.simulationRunGroup.list();\n\nconsole.log(simulationRunGroups);\n```",
+    perLanguage: {
+      typescript: {
+        method: 'client.simulationRunGroup.list',
+        example:
+          "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunGroups = await client.simulationRunGroup.list();\n\nconsole.log(simulationRunGroups.data);",
+      },
+      python: {
+        method: 'simulation_run_group.list',
+        example:
+          'import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted\n)\nsimulation_run_groups = client.simulation_run_group.list()\nprint(simulation_run_groups.data)',
+      },
+      http: {
+        example:
+          'curl https://api.roark.ai/v1/simulation/run-group \\\n    -H "Authorization: Bearer $ROARK_API_BEARER_TOKEN"',
+      },
+    },
+  },
+  {
+    name: 'getById',
+    endpoint: '/v1/simulation/run-group/{groupId}',
+    httpMethod: 'get',
+    summary: 'Get a run group',
+    description:
+      'Returns a run group with its runs in group order and its latest group report, including the report document once READY.',
+    stainlessPath: '(resource) simulationRunGroup > (method) getById',
+    qualified: 'client.simulationRunGroup.getByID',
+    params: ['groupId: string;'],
+    response:
+      "{ data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; document: object; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }; }",
+    markdown:
+      "## getById\n\n`client.simulationRunGroup.getByID(groupId: string): { data: object; }`\n\n**get** `/v1/simulation/run-group/{groupId}`\n\nReturns a run group with its runs in group order and its latest group report, including the report document once READY.\n\n### Parameters\n\n- `groupId: string`\n\n### Returns\n\n- `{ data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; document: object; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }; }`\n\n  - `data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; document: { aggregates: object[]; executiveSummary: object[]; generatedAtIso: string; headline: object; issues: object[]; methodology: string; model: string; recommendations: object[]; runs: object[]; scorecard: object[]; simulationRunGroupId: string; smallerItems: object[]; version: 1; wentWell: object[]; }; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationRunGroup.getByID('5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e');\n\nconsole.log(response);\n```",
+    perLanguage: {
+      typescript: {
+        method: 'client.simulationRunGroup.getByID',
+        example:
+          "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunGroup.getByID('5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e');\n\nconsole.log(response.data);",
+      },
+      python: {
+        method: 'simulation_run_group.get_by_id',
+        example:
+          'import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted\n)\nresponse = client.simulation_run_group.get_by_id(\n    "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",\n)\nprint(response.data)',
+      },
+      http: {
+        example:
+          'curl https://api.roark.ai/v1/simulation/run-group/$GROUP_ID \\\n    -H "Authorization: Bearer $ROARK_API_BEARER_TOKEN"',
+      },
+    },
+  },
+  {
+    name: 'create',
+    endpoint: '/v1/simulation/run-group',
+    httpMethod: 'post',
+    summary: 'Create a run group',
+    description:
+      'Groups several simulation runs so they read as one, and starts generating the group report:\none document across every run, with a scorecard summed across them and the issues found,\neach merged from the per-run debriefs.\n\nSend `simulationRunPlanJobIds` to group runs that already exist (runs still in progress are\nfine: the report waits for them). Send `simulationRunPlanIds` to start one run of each plan\nand group those; this places real calls, exactly as starting each plan would.\n\nPoll GET /v1/simulation/run-group/{groupId} until `latestReport.status` is READY.',
+    stainlessPath: '(resource) simulationRunGroup > (method) create',
+    qualified: 'client.simulationRunGroup.create',
+    params: ['name?: string;', 'simulationRunPlanIds?: string[];', 'simulationRunPlanJobIds?: string[];'],
+    response:
+      "{ data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; document: object; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }; }",
+    markdown:
+      "## create\n\n`client.simulationRunGroup.create(name?: string, simulationRunPlanIds?: string[], simulationRunPlanJobIds?: string[]): { data: object; }`\n\n**post** `/v1/simulation/run-group`\n\nGroups several simulation runs so they read as one, and starts generating the group report:\none document across every run, with a scorecard summed across them and the issues found,\neach merged from the per-run debriefs.\n\nSend `simulationRunPlanJobIds` to group runs that already exist (runs still in progress are\nfine: the report waits for them). Send `simulationRunPlanIds` to start one run of each plan\nand group those; this places real calls, exactly as starting each plan would.\n\nPoll GET /v1/simulation/run-group/{groupId} until `latestReport.status` is READY.\n\n### Parameters\n\n- `name?: string`\n  What to call the group. Defaults to the plans' names when starting plans, and to the runs' plan names when grouping existing runs.\n\n- `simulationRunPlanIds?: string[]`\n  Plans to run once each, in display order (2 to 20). Each plan starts a run, exactly as POST /v1/simulation/plan/{planId}/job would. Send this or `simulationRunPlanJobIds`, not both.\n\n- `simulationRunPlanJobIds?: string[]`\n  Runs that already exist, in display order (2 to 20). Runs still in progress are fine: the group report waits for them. Send this or `simulationRunPlanIds`, not both.\n\n### Returns\n\n- `{ data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; document: object; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }; }`\n\n  - `data: { id: string; createdAt: string; latestReport: { id: string; completedAt: string; createdAt: string; document: { aggregates: object[]; executiveSummary: object[]; generatedAtIso: string; headline: object; issues: object[]; methodology: string; model: string; recommendations: object[]; runs: object[]; scorecard: object[]; simulationRunGroupId: string; smallerItems: object[]; version: 1; wentWell: object[]; }; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; name: string; runCount: number; runs: { createdAt: string; endedAt: string; planName: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; startedAt: string; status: string; }[]; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst simulationRunGroup = await client.simulationRunGroup.create();\n\nconsole.log(simulationRunGroup);\n```",
+    perLanguage: {
+      typescript: {
+        method: 'client.simulationRunGroup.create',
+        example:
+          "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunGroup = await client.simulationRunGroup.create();\n\nconsole.log(simulationRunGroup.data);",
+      },
+      python: {
+        method: 'simulation_run_group.create',
+        example:
+          'import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted\n)\nsimulation_run_group = client.simulation_run_group.create()\nprint(simulation_run_group.data)',
+      },
+      http: {
+        example:
+          'curl https://api.roark.ai/v1/simulation/run-group \\\n    -H "Authorization: Bearer $ROARK_API_BEARER_TOKEN"',
+      },
+    },
+  },
+  {
+    name: 'delete',
+    endpoint: '/v1/simulation/run-group/{groupId}',
+    httpMethod: 'delete',
+    summary: 'Delete a run group',
+    description: 'Deletes a run group. Its runs, and their results, are untouched.',
+    stainlessPath: '(resource) simulationRunGroup > (method) delete',
+    qualified: 'client.simulationRunGroup.delete',
+    params: ['groupId: string;'],
+    response: '{ data: { deleted: boolean; }; }',
+    markdown:
+      "## delete\n\n`client.simulationRunGroup.delete(groupId: string): { data: object; }`\n\n**delete** `/v1/simulation/run-group/{groupId}`\n\nDeletes a run group. Its runs, and their results, are untouched.\n\n### Parameters\n\n- `groupId: string`\n\n### Returns\n\n- `{ data: { deleted: boolean; }; }`\n\n  - `data: { deleted: boolean; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst simulationRunGroup = await client.simulationRunGroup.delete(\n  '5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e',\n);\n\nconsole.log(simulationRunGroup);\n```",
+    perLanguage: {
+      typescript: {
+        method: 'client.simulationRunGroup.delete',
+        example:
+          "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunGroup = await client.simulationRunGroup.delete(\n  '5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e',\n);\n\nconsole.log(simulationRunGroup.data);",
+      },
+      python: {
+        method: 'simulation_run_group.delete',
+        example:
+          'import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted\n)\nsimulation_run_group = client.simulation_run_group.delete(\n    "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",\n)\nprint(simulation_run_group.data)',
+      },
+      http: {
+        example:
+          'curl https://api.roark.ai/v1/simulation/run-group/$GROUP_ID \\\n    -X DELETE \\\n    -H "Authorization: Bearer $ROARK_API_BEARER_TOKEN"',
+      },
+    },
+  },
+  {
+    name: 'regenerateReport',
+    endpoint: '/v1/simulation/run-group/{groupId}/report',
+    httpMethod: 'post',
+    summary: 'Regenerate a run group report',
+    description:
+      'Generates the group report again over the latest state of its runs. Returns the report generation; if one is already in flight it is returned instead of starting another. Poll GET /v1/simulation/run-group/{groupId} until `latestReport.status` is READY.',
+    stainlessPath: '(resource) simulationRunGroup > (method) regenerateReport',
+    qualified: 'client.simulationRunGroup.regenerateReport',
+    params: ['groupId: string;'],
+    response:
+      "{ data: { id: string; completedAt: string; createdAt: string; document: { aggregates: object[]; executiveSummary: object[]; generatedAtIso: string; headline: object; issues: object[]; methodology: string; model: string; recommendations: object[]; runs: object[]; scorecard: object[]; simulationRunGroupId: string; smallerItems: object[]; version: 1; wentWell: object[]; }; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; }",
+    markdown:
+      "## regenerateReport\n\n`client.simulationRunGroup.regenerateReport(groupId: string): { data: object; }`\n\n**post** `/v1/simulation/run-group/{groupId}/report`\n\nGenerates the group report again over the latest state of its runs. Returns the report generation; if one is already in flight it is returned instead of starting another. Poll GET /v1/simulation/run-group/{groupId} until `latestReport.status` is READY.\n\n### Parameters\n\n- `groupId: string`\n\n### Returns\n\n- `{ data: { id: string; completedAt: string; createdAt: string; document: { aggregates: object[]; executiveSummary: object[]; generatedAtIso: string; headline: object; issues: object[]; methodology: string; model: string; recommendations: object[]; runs: object[]; scorecard: object[]; simulationRunGroupId: string; smallerItems: object[]; version: 1; wentWell: object[]; }; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; }`\n\n  - `data: { id: string; completedAt: string; createdAt: string; document: { aggregates: { averageLabel: string; evaluatedCount: number; medianLabel: string; metricName: string; p95Label: string; }[]; executiveSummary: { body: string; heading: string; }[]; generatedAtIso: string; headline: { callCount: number; completedAtIso: string; groupName: string; passedRunCount: number; reportedRunCount: number; runCount: number; statTiles: object[]; verdict: 'PASSED' | 'THRESHOLD_FAILED'; verdictProse: string; }; issues: { affectedCallCount: number; body: string; calls: object[]; checkNames: string[]; evidence: object[]; order: number; rootCauseChannel: 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL'; runLabels: string[]; severity: 'HIGH' | 'MEDIUM' | 'LOW'; sourceThemes: object[]; title: string; }[]; methodology: string; model: string; recommendations: { body: string; channel: 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL'; issueOrders: number[]; order: number; title: string; }[]; runs: { callCount: number; checksPassed: number; checksTotal: number; completedAtIso: string; runLabel: string; runNumber: number; simulationRunPlanJobId: string; status: string; summary: string; themeCount: number; verdict: 'PASSED' | 'THRESHOLD_FAILED'; }[]; scorecard: { checkName: string; evaluatedCount: number; failedCount: number; failedRunCount: number; passRatePct: number; runCount: number; }[]; simulationRunGroupId: string; smallerItems: { affectedCallCount: number; body: string; calls: object[]; checkNames: string[]; evidence: object[]; order: number; rootCauseChannel: 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL'; runLabels: string[]; severity: 'HIGH' | 'MEDIUM' | 'LOW'; sourceThemes: object[]; title: string; }[]; version: 1; wentWell: { body: string; evidence: object[]; title: string; }[]; }; errorMessage: string; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationRunGroup.regenerateReport(\n  '5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e',\n);\n\nconsole.log(response);\n```",
+    perLanguage: {
+      typescript: {
+        method: 'client.simulationRunGroup.regenerateReport',
+        example:
+          "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunGroup.regenerateReport(\n  '5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e',\n);\n\nconsole.log(response.data);",
+      },
+      python: {
+        method: 'simulation_run_group.regenerate_report',
+        example:
+          'import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted\n)\nresponse = client.simulation_run_group.regenerate_report(\n    "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",\n)\nprint(response.data)',
+      },
+      http: {
+        example:
+          'curl https://api.roark.ai/v1/simulation/run-group/$GROUP_ID/report \\\n    -H "Authorization: Bearer $ROARK_API_BEARER_TOKEN"',
+      },
+    },
+  },
   {
     name: 'list',
     endpoint: '/v1/simulation/plan',
@@ -1619,6 +1772,68 @@ const EMBEDDED_METHODS: MethodEntry[] = [
       },
     },
   },
+  {
+    name: 'getResults',
+    endpoint: '/v1/simulation/plan/job/{jobId}/results',
+    httpMethod: 'get',
+    summary: 'Get simulation run results',
+    description:
+      'Everything the run report shows, in one request: the summary and score, the pass/fail verdict,\nper-metric aggregates, every simulation with its check results, breakdowns by agent and persona,\nthe comparison against the previous run (or `compareToJobId`), the sweep attribution, and the\nwritten debrief with its executive summary, failure themes and recommendations.\n\nSafe to call while the run is in progress: counts reflect what has landed so far. `verdict` and\n`sweepAttribution` stay null until the run ends. The debrief is generated automatically a few\nminutes after a run with graded calls settles; poll until `debrief.status` is READY, or request\none with POST /v1/simulation/plan/job/{jobId}/debrief.',
+    stainlessPath: '(resource) simulationRunPlanJob > (method) getResults',
+    qualified: 'client.simulationRunPlanJob.getResults',
+    params: ['jobId: string;', 'compareToJobId?: string;'],
+    response:
+      "{ data: { attemptSummary: { attemptCount: number; retryCount: number; silentAttemptCount: number; stillSilentTestCaseCount: number; testCaseCount: number; }; breakdowns: { byAgent: object[]; byPersona: object[]; }; calls: { agentName: string; attemptNumber: number; callId: string; checks: object[]; counted: boolean; durationMs: number; passed: boolean; personaName: string; retryOfSimulationJobId: string; simulationJobId: string; status: string; values: object[]; }[]; comparison: { baselineCallPassRate: number; baselineRun: object; baselineScore: number; baselineSource: 'PREVIOUS_RUN' | 'REQUESTED'; callPassRateDelta: number; checks: object[]; currentCallPassRate: number; currentScore: number; scoreDelta: number; }; debrief: { completedAt: string; createdAt: string; debriefId: string; errorMessage: string; report: object; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; metrics: { check: object; distribution: object[]; evaluatedCalls: number; isCheck: boolean; metricDefinitionId: string; metricId: string; name: string; numeric: object; outputType: 'COUNT' | 'NUMERIC' | 'BOOLEAN' | 'SCALE' | 'TEXT' | 'CLASSIFICATION' | 'OFFSET'; sampleSize: number; unitSymbol: string; }[]; run: { createdAt: string; durationMs: number; endedAt: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; simulationRunPlanName: string; startedAt: string; status: string; triggeredBy: 'SCHEDULED' | 'USER_TRIGGERED_FROM_UI' | 'RE_RUN' | 'TRIGGERED_FROM_API' | 'SYSTEM'; }; summary: { callPassRate: number; checkPassRate: number; completedCalls: number; countedCalls: number; evaluatedCalls: number; failedCalls: number; passedCalls: number; score: number; totalCalls: number; }; sweepAttribution: { caveats: string[]; checks: object[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; neverSpokeValues: object[]; testableValueCount: number; testedComparisonCount: number; values: object[]; }; verdict: { checks: object[]; failures: object[]; passed: boolean; score: number; }; }; }",
+    markdown:
+      "## getResults\n\n`client.simulationRunPlanJob.getResults(jobId: string, compareToJobId?: string): { data: object; }`\n\n**get** `/v1/simulation/plan/job/{jobId}/results`\n\nEverything the run report shows, in one request: the summary and score, the pass/fail verdict,\nper-metric aggregates, every simulation with its check results, breakdowns by agent and persona,\nthe comparison against the previous run (or `compareToJobId`), the sweep attribution, and the\nwritten debrief with its executive summary, failure themes and recommendations.\n\nSafe to call while the run is in progress: counts reflect what has landed so far. `verdict` and\n`sweepAttribution` stay null until the run ends. The debrief is generated automatically a few\nminutes after a run with graded calls settles; poll until `debrief.status` is READY, or request\none with POST /v1/simulation/plan/job/{jobId}/debrief.\n\n### Parameters\n\n- `jobId: string`\n\n- `compareToJobId?: string`\n  Simulation run plan job to compare this run against, e.g. the last run on your main branch. Defaults to the plan's previous settled run. Any run in the project works, including another plan's: checks are matched by metric, and a check only one run graded reads null on the other side.\n\n### Returns\n\n- `{ data: { attemptSummary: { attemptCount: number; retryCount: number; silentAttemptCount: number; stillSilentTestCaseCount: number; testCaseCount: number; }; breakdowns: { byAgent: object[]; byPersona: object[]; }; calls: { agentName: string; attemptNumber: number; callId: string; checks: object[]; counted: boolean; durationMs: number; passed: boolean; personaName: string; retryOfSimulationJobId: string; simulationJobId: string; status: string; values: object[]; }[]; comparison: { baselineCallPassRate: number; baselineRun: object; baselineScore: number; baselineSource: 'PREVIOUS_RUN' | 'REQUESTED'; callPassRateDelta: number; checks: object[]; currentCallPassRate: number; currentScore: number; scoreDelta: number; }; debrief: { completedAt: string; createdAt: string; debriefId: string; errorMessage: string; report: object; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; metrics: { check: object; distribution: object[]; evaluatedCalls: number; isCheck: boolean; metricDefinitionId: string; metricId: string; name: string; numeric: object; outputType: 'COUNT' | 'NUMERIC' | 'BOOLEAN' | 'SCALE' | 'TEXT' | 'CLASSIFICATION' | 'OFFSET'; sampleSize: number; unitSymbol: string; }[]; run: { createdAt: string; durationMs: number; endedAt: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; simulationRunPlanName: string; startedAt: string; status: string; triggeredBy: 'SCHEDULED' | 'USER_TRIGGERED_FROM_UI' | 'RE_RUN' | 'TRIGGERED_FROM_API' | 'SYSTEM'; }; summary: { callPassRate: number; checkPassRate: number; completedCalls: number; countedCalls: number; evaluatedCalls: number; failedCalls: number; passedCalls: number; score: number; totalCalls: number; }; sweepAttribution: { caveats: string[]; checks: object[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; neverSpokeValues: object[]; testableValueCount: number; testedComparisonCount: number; values: object[]; }; verdict: { checks: object[]; failures: object[]; passed: boolean; score: number; }; }; }`\n\n  - `data: { attemptSummary: { attemptCount: number; retryCount: number; silentAttemptCount: number; stillSilentTestCaseCount: number; testCaseCount: number; }; breakdowns: { byAgent: { callPassRate: number; calls: number; evaluatedCalls: number; key: string; label: string; passedCalls: number; score: number; }[]; byPersona: { callPassRate: number; calls: number; evaluatedCalls: number; key: string; label: string; passedCalls: number; score: number; }[]; }; calls: { agentName: string; attemptNumber: number; callId: string; checks: { metricDefinitionId: string; metricName: string; passed: boolean; }[]; counted: boolean; durationMs: number; passed: boolean; personaName: string; retryOfSimulationJobId: string; simulationJobId: string; status: string; values: { metricDefinitionId: string; metricName: string; outputType: 'COUNT' | 'NUMERIC' | 'BOOLEAN' | 'SCALE' | 'TEXT' | 'CLASSIFICATION' | 'OFFSET'; participantRole: 'AGENT' | 'CUSTOMER' | 'SIMULATED_CUSTOMER' | 'BACKGROUND_SPEAKER'; reasoning: string; value: number | boolean | string; }[]; }[]; comparison: { baselineCallPassRate: number; baselineRun: { endedAt: string; runNumber: number; simulationRunPlanJobId: string; status: string; }; baselineScore: number; baselineSource: 'PREVIOUS_RUN' | 'REQUESTED'; callPassRateDelta: number; checks: { baselinePassRate: number; currentPassRate: number; delta: number; metricDefinitionId: string; metricName: string; }[]; currentCallPassRate: number; currentScore: number; scoreDelta: number; }; debrief: { completedAt: string; createdAt: string; debriefId: string; errorMessage: string; report: { executiveSummary: object; generatedAt: string; keyFindings: object[]; recommendations: object[]; themes: object[]; trend: object; verdict: 'PASSED' | 'THRESHOLD_FAILED'; verdictSummary: string; wentWell: object[]; }; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; metrics: { check: { evaluatedCalls: number; failedCalls: number; passRate: number; passedCalls: number; }; distribution: { count: number; value: string; }[]; evaluatedCalls: number; isCheck: boolean; metricDefinitionId: string; metricId: string; name: string; numeric: { average: number; max: number; median: number; min: number; p95: number; }; outputType: 'COUNT' | 'NUMERIC' | 'BOOLEAN' | 'SCALE' | 'TEXT' | 'CLASSIFICATION' | 'OFFSET'; sampleSize: number; unitSymbol: string; }[]; run: { createdAt: string; durationMs: number; endedAt: string; runNumber: number; simulationRunPlanId: string; simulationRunPlanJobId: string; simulationRunPlanName: string; startedAt: string; status: string; triggeredBy: 'SCHEDULED' | 'USER_TRIGGERED_FROM_UI' | 'RE_RUN' | 'TRIGGERED_FROM_API' | 'SYSTEM'; }; summary: { callPassRate: number; checkPassRate: number; completedCalls: number; countedCalls: number; evaluatedCalls: number; failedCalls: number; passedCalls: number; score: number; totalCalls: number; }; sweepAttribution: { caveats: string[]; checks: { attribution: 'PROPERTY_ATTRIBUTABLE' | 'FOUND_UNATTRIBUTED' | 'WITHIN_NOISE'; evaluated: number; failed: number; failureRate: number; metricDefinitionId: string; metricName: string; worseValues: object[]; }[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; neverSpokeValues: { adjustedPValue: number; attempted: number; key: string; label: string; restAttempted: number; restSilentAttempts: number; retries: number; silentAttempts: number; value: string; }[]; testableValueCount: number; testedComparisonCount: number; values: { attempted: number; counted: number; isBaseline: boolean; key: string; label: string; retries: number; score: number; silentAttempts: number; testable: boolean; value: string; }[]; }; verdict: { checks: { evaluatedSims: number; inherited: boolean; metricDefinitionId: string; minPassRate: number; passRate: number; passed: boolean; passedSims: number; metricName?: string; }[]; failures: { status: string; type: 'RUN_NOT_COMPLETED'; } | { evaluatedCalls: number; expectedCalls: number; type: 'INCOMPLETE_COVERAGE'; } | { maxShare: number; neverSpokeCalls: number; totalCalls: number; type: 'AGENT_NEVER_SPOKE'; agentName?: string; silentAttempts?: number; } | { metricDefinitionId: string; type: 'METRIC_NOT_EVALUATED'; metricName?: string; } | { inherited: boolean; metricDefinitionId: string; minPassRate: number; passRate: number; type: 'METRIC_BELOW_MIN_PASS_RATE'; metricName?: string; }[]; passed: boolean; score: number; }; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationRunPlanJob.getResults('jobId');\n\nconsole.log(response);\n```",
+    perLanguage: {
+      typescript: {
+        method: 'client.simulationRunPlanJob.getResults',
+        example:
+          "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlanJob.getResults('jobId');\n\nconsole.log(response.data);",
+      },
+      python: {
+        method: 'simulation_run_plan_job.get_results',
+        example:
+          'import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan_job.get_results(\n    job_id="jobId",\n)\nprint(response.data)',
+      },
+      http: {
+        example:
+          'curl https://api.roark.ai/v1/simulation/plan/job/$JOB_ID/results \\\n    -H "Authorization: Bearer $ROARK_API_BEARER_TOKEN"',
+      },
+    },
+  },
+  {
+    name: 'createDebrief',
+    endpoint: '/v1/simulation/plan/job/{jobId}/debrief',
+    httpMethod: 'post',
+    summary: 'Generate simulation run debrief',
+    description:
+      'Request the written debrief for a settled run: executive summary, failure themes and recommendations.\nRuns with graded calls get one automatically, so this is for regenerating one (`regenerate: true`)\nor retrying one that failed.\n\nReturns immediately. Generation takes a few minutes: poll GET\n/v1/simulation/plan/job/{jobId}/results until `debrief.status` is READY or FAILED.\nWithout `regenerate`, a debrief that is ready or already being written is returned as-is.',
+    stainlessPath: '(resource) simulationRunPlanJob > (method) createDebrief',
+    qualified: 'client.simulationRunPlanJob.createDebrief',
+    params: ['jobId: string;', 'regenerate?: boolean;'],
+    response:
+      "{ data: { completedAt: string; createdAt: string; debriefId: string; errorMessage: string; report: { executiveSummary: object; generatedAt: string; keyFindings: object[]; recommendations: object[]; themes: object[]; trend: object; verdict: 'PASSED' | 'THRESHOLD_FAILED'; verdictSummary: string; wentWell: object[]; }; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; }",
+    markdown:
+      "## createDebrief\n\n`client.simulationRunPlanJob.createDebrief(jobId: string, regenerate?: boolean): { data: object; }`\n\n**post** `/v1/simulation/plan/job/{jobId}/debrief`\n\nRequest the written debrief for a settled run: executive summary, failure themes and recommendations.\nRuns with graded calls get one automatically, so this is for regenerating one (`regenerate: true`)\nor retrying one that failed.\n\nReturns immediately. Generation takes a few minutes: poll GET\n/v1/simulation/plan/job/{jobId}/results until `debrief.status` is READY or FAILED.\nWithout `regenerate`, a debrief that is ready or already being written is returned as-is.\n\n### Parameters\n\n- `jobId: string`\n\n- `regenerate?: boolean`\n  Generate a new debrief even when a ready one exists. Without it, an existing ready or in-progress debrief is returned as-is.\n\n### Returns\n\n- `{ data: { completedAt: string; createdAt: string; debriefId: string; errorMessage: string; report: { executiveSummary: object; generatedAt: string; keyFindings: object[]; recommendations: object[]; themes: object[]; trend: object; verdict: 'PASSED' | 'THRESHOLD_FAILED'; verdictSummary: string; wentWell: object[]; }; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }; }`\n\n  - `data: { completedAt: string; createdAt: string; debriefId: string; errorMessage: string; report: { executiveSummary: { paragraphs: string[]; sections: object[]; }; generatedAt: string; keyFindings: { body: string; callIds: string[]; title: string; }[]; recommendations: { body: string; channel: 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL'; currentText: string; order: number; severity: 'HIGH' | 'MEDIUM' | 'LOW'; suggestedText: string; themeSlugs: string[]; title: string; }[]; themes: { affectedCallCount: number; analysis: string; callIds: string[]; checkNames: string[]; impact: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW'; lifecycle: 'NEW' | 'PERSISTENT' | 'IMPROVING' | 'FIXED'; prevalence: 'WIDESPREAD' | 'RECURRING' | 'ISOLATED'; rootCauseChannel: 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL'; severity: 'HIGH' | 'MEDIUM' | 'LOW'; slug: string; title: string; totalCallCount: number; }[]; trend: { baselineRunNumber: number; baselineRunPlanJobId: string; rows: object[]; }; verdict: 'PASSED' | 'THRESHOLD_FAILED'; verdictSummary: string; wentWell: { body: string; callIds: string[]; title: string; }[]; }; status: 'PENDING' | 'GENERATING' | 'READY' | 'FAILED'; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationRunPlanJob.createDebrief(\n  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(response);\n```",
+    perLanguage: {
+      typescript: {
+        method: 'client.simulationRunPlanJob.createDebrief',
+        example:
+          "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlanJob.createDebrief(\n  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(response.data);",
+      },
+      python: {
+        method: 'simulation_run_plan_job.create_debrief',
+        example:
+          'import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan_job.create_debrief(\n    job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",\n)\nprint(response.data)',
+      },
+      http: {
+        example:
+          'curl https://api.roark.ai/v1/simulation/plan/job/$JOB_ID/debrief \\\n    -H "Authorization: Bearer $ROARK_API_BEARER_TOKEN"',
+      },
+    },
+  },
   {
     name: 'list',
     endpoint: '/v1/persona',

package/src/methods.ts

@@ -238,6 +238,36 @@ export const sdkMethods: SdkMethod[] = [
     httpMethod: 'delete',
     httpPath: '/v1/simulation/tool-fixture/{fixtureId}',
   },
+  {
+    clientCallName: 'client.simulationRunGroup.create',
+    fullyQualifiedName: 'simulationRunGroup.create',
+    httpMethod: 'post',
+    httpPath: '/v1/simulation/run-group',
+  },
+  {
+    clientCallName: 'client.simulationRunGroup.list',
+    fullyQualifiedName: 'simulationRunGroup.list',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/run-group',
+  },
+  {
+    clientCallName: 'client.simulationRunGroup.delete',
+    fullyQualifiedName: 'simulationRunGroup.delete',
+    httpMethod: 'delete',
+    httpPath: '/v1/simulation/run-group/{groupId}',
+  },
+  {
+    clientCallName: 'client.simulationRunGroup.getByID',
+    fullyQualifiedName: 'simulationRunGroup.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/run-group/{groupId}',
+  },
+  {
+    clientCallName: 'client.simulationRunGroup.regenerateReport',
+    fullyQualifiedName: 'simulationRunGroup.regenerateReport',
+    httpMethod: 'post',
+    httpPath: '/v1/simulation/run-group/{groupId}/report',
+  },
   {
     clientCallName: 'client.simulationRunPlan.create',
     fullyQualifiedName: 'simulationRunPlan.create',
@@ -280,12 +310,24 @@ export const sdkMethods: SdkMethod[] = [
     httpMethod: 'post',
     httpPath: '/v1/simulation/plan/job/{jobId}/cancel',
   },
+  {
+    clientCallName: 'client.simulationRunPlanJob.createDebrief',
+    fullyQualifiedName: 'simulationRunPlanJob.createDebrief',
+    httpMethod: 'post',
+    httpPath: '/v1/simulation/plan/job/{jobId}/debrief',
+  },
   {
     clientCallName: 'client.simulationRunPlanJob.getByID',
     fullyQualifiedName: 'simulationRunPlanJob.getByID',
     httpMethod: 'get',
     httpPath: '/v1/simulation/plan/job/{jobId}',
   },
+  {
+    clientCallName: 'client.simulationRunPlanJob.getResults',
+    fullyQualifiedName: 'simulationRunPlanJob.getResults',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/plan/job/{jobId}/results',
+  },
   {
     clientCallName: 'client.simulationRunPlanJob.start',
     fullyQualifiedName: 'simulationRunPlanJob.start',

package/src/server.ts

@@ -28,7 +28,7 @@ export const newMcpServer = async ({
   new McpServer(
     {
       name: 'roarkanalytics_sdk_api',
-      version: '4.20.0', // x-release-please-version
+      version: '4.22.1', // x-release-please-version
     },
     {
       instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }),