@ishlabs/cli 0.20.0 → 0.22.0

package/dist/lib/study-results-projections.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Pure projection builders for `ish study results --group-by <kind>`.
+ *
+ * Each `buildStudyResultsPer<Kind>` consumes a `FilteredResults` (the output
+ * of `applyResultsFilters` in `study-results-filters.ts`) and returns a
+ * bare array of slice objects. The surface (`commands/study.ts`) wraps the
+ * array uniformly in a `SliceResponse` envelope alongside `totals_unfiltered`,
+ * `modality_warnings`, `study_id`, and `modality` before handing it off to
+ * `formatStudyResultsGroupBy` for JSON or human rendering.
+ *
+ * Conventions mirror `buildStudyResultsEnvelope` (`output.ts:1081`) and
+ * `buildStudyResultsSummary` (`output.ts:1292`):
+ *   - deterministic field order (object literals are emitted in source order)
+ *   - stable empties: empty arrays, never `null` for "no rows yet"
+ *   - sample_comments capped at 5 per group, truncated to 200 chars
+ *   - sentiment histograms are { label → count } records
+ *   - participant_aliases capped at 10 per group
+ *
+ * Has no IO and no console side-effects.
+ */
+import type { FilteredResults } from "./study-results-filters.js";
+import type { StudyResultsGroupByKind } from "./output.js";
+export type { FilteredResults } from "./study-results-filters.js";
+/**
+ * Uniform envelope emitted for every `ish study results --group-by <axis>`
+ * call, mirroring the MCP backend's `SliceResponse[T]`. Six top-level keys,
+ * stable across all six axes — `rows` carries the bare slice array returned
+ * by the matching `buildStudyResultsPer<Kind>` builder.
+ */
+export interface SliceResponse<T> {
+    axis: StudyResultsGroupByKind;
+    rows: T[];
+    totals_unfiltered: {
+        participant_count: number;
+        interaction_count: number;
+    };
+    modality_warnings: string[];
+    study_id: string;
+    modality: string;
+}
+/**
+ * Wrap a bare projection array in the uniform `SliceResponse` envelope.
+ * The surface calls this once after dispatching to one of the six
+ * `buildStudyResultsPer<Kind>` builders, then hands the envelope to
+ * `formatStudyResultsGroupBy`.
+ */
+export declare function wrapSliceProjection<T>(filtered: FilteredResults, axis: StudyResultsGroupByKind, rows: T[], studyId: string, modality: string): SliceResponse<T>;
+interface IterationSlice {
+    iteration_id: string;
+    iteration_label: string | null;
+    participant_count: number;
+    interaction_count: number;
+    sentiment: Record<string, number>;
+    sample_comments: string[];
+    top_actions: Array<{
+        action_type: string;
+        count: number;
+    }>;
+}
+/**
+ * `--group-by iteration` — one slice per declared iteration, in the same
+ * order as `ish study get`. Iterations with zero surviving participants
+ * still appear with `participant_count: 0` so the consumer sees the full
+ * matrix at stable size. Returns a bare array; the surface wraps it in
+ * the uniform `SliceResponse` envelope.
+ */
+export declare function buildStudyResultsPerIteration(filtered: FilteredResults): IterationSlice[];
+interface FrameSlice {
+    frame_id: string;
+    frame_label: string | null;
+    interaction_count: number;
+    sentiment_histogram: Record<string, number>;
+    sample_comments: string[];
+    participant_aliases: string[];
+}
+/**
+ * `--group-by frame` — one slice per Frame that had a surviving interaction.
+ * Interactive only — the surface (T5) errors before reaching here when the
+ * study isn't interactive. Includes a synthetic `_unmatched` bucket when
+ * `--include-unmatched` was set and null-frame_version_id rows survived.
+ *
+ * Returns a bare array (no wrapper) — callers attach totals_unfiltered.
+ */
+export declare function buildStudyResultsPerFrame(filtered: FilteredResults): FrameSlice[];
+interface SegmentSlice {
+    segment_index: number | null;
+    segment_label: string | null;
+    interaction_count: number;
+    sentiment_histogram: Record<string, number>;
+    engagement_histogram: Record<string, number>;
+    sample_comments: string[];
+}
+/**
+ * `--group-by segment` — media studies (video / audio / text / document).
+ * Groups by `actions[0].data.segment_index`, falling back to `segment_label`
+ * when the index isn't present.
+ */
+export declare function buildStudyResultsPerSegment(filtered: FilteredResults): SegmentSlice[];
+interface TurnSlice {
+    turn_index: number;
+    interaction_count: number;
+    sentiment_histogram: Record<string, number>;
+    sample_replies: string[];
+    failures: number;
+}
+/**
+ * `--group-by turn` — chat studies. Groups by `actions[0].data.turn_index`
+ * and surfaces both a count of bot-failure stubs (`bot_reply.failure`
+ * populated) and up to 5 sample bot replies per turn.
+ */
+export declare function buildStudyResultsPerTurn(filtered: FilteredResults): TurnSlice[];
+interface AssignmentSlice {
+    assignment_id: string;
+    assignment_name: string | null;
+    interaction_count: number;
+    sentiment_histogram: Record<string, number>;
+    step_completion: unknown[];
+}
+/**
+ * `--group-by assignment` — one slice per study assignment, with each
+ * assignment's `step_completion[]` (from the study payload) attached so the
+ * caller can see pass / inconclusive / fail rollups inline.
+ */
+export declare function buildStudyResultsPerAssignment(filtered: FilteredResults): AssignmentSlice[];
+interface StepVerdict {
+    participant_alias: string | null;
+    verdict: string | null;
+    reason: string | null;
+    evidence_interaction_ids: string[];
+}
+interface StepSlice {
+    assignment_id: string;
+    assignment_name: string | null;
+    step_id: string;
+    step_name: string | null;
+    total: number;
+    passed: number;
+    inconclusive: number;
+    failed: number;
+    rate: number;
+    participant_verdicts: StepVerdict[];
+}
+/**
+ * `--group-by step` — one slice per `(assignment, step_id)` pair with verdict
+ * totals (re-derived from surviving participants, NOT the pre-computed
+ * step_completion) and per-participant verdict rows inline.
+ *
+ * Re-deriving totals matters when filters are applied: e.g. a caller asking
+ * for `--iteration B --group-by step` wants verdict counts for iteration B
+ * only, not the study-wide rollup.
+ */
+export declare function buildStudyResultsPerStep(filtered: FilteredResults): StepSlice[];