plures 1.15.0 → 1.18.0

package/dist/index.d.ts

@@ -4,6 +4,93 @@ type Option = {
 };
 /** "verifiers" asks ID verified people first; "team" goes straight to your own people ($0.05 per internal vote live). */
 type Route = "verifiers" | "team";
+type DriftDiagnosis = {
+    summary: string;
+    confidence: "high" | "medium" | "low";
+    causes: {
+        title: string;
+        detail: string;
+        files: {
+            file: string;
+            line?: number | null;
+        }[];
+    }[];
+    changes: {
+        file: string;
+        why: string;
+    }[];
+    evals_added: number;
+};
+type DriftCase = {
+    object: "drift_case";
+    id: string;
+    app: string;
+    mode: "live" | "test";
+    source: "rubric" | "answers";
+    key: string;
+    label: string;
+    status: "open" | "diagnosing" | "diagnosed" | "fix_open" | "verifying" | "recovered" | "dismissed" | "failed";
+    baseline: number | null;
+    at_open: number | null;
+    current: number | null;
+    points: number;
+    version_before: string | null;
+    version_after: string | null;
+    diagnosis: DriftDiagnosis | null;
+    pr_url: string | null;
+    merged_at: string | null;
+    post_n: number;
+    recovered_at: string | null;
+    opened_at: string;
+};
+type TurnParams = {
+    /** Which version of your assistant answered, like "prompt v15", so a drop can be traced to a change. */ version?: string;
+    /** What the user said or typed. */ question: string;
+    /** What the assistant replied ("" if it said nothing). */ answer: string;
+    /** Where your router sent it. */ intent?: string;
+    /** If the model corrected the router. */ rerouted_to?: string | null;
+    /** How it retrieved, like "full", "rerank" or "agentic". */ retrieval?: string;
+    /** What it used. [] means it answered with none. */ sources?: {
+        id?: string;
+        title?: string;
+        snippet?: string;
+        score?: number;
+    }[];
+    /** It said it didn't know. Plures guesses from the answer if you leave it out. */ refused?: boolean;
+    /** A conversation or call id, so Plures can tell when the user asks again. */ session?: string;
+    channel?: "voice" | "text";
+    /** A recording people can play, for voice. */ audio_url?: string;
+    /** Every intent your router can pick, so graders can choose the right one. */ intents?: string[];
+    /** Send this one for review whatever the sample says. */ review?: boolean;
+    app?: string;
+    metadata?: Record<string, unknown>;
+};
+type CheckOverrides = {
+    question?: string;
+    options?: string[];
+    instructions?: string;
+    verifiers?: number;
+    team?: string;
+    route?: "verifiers" | "team";
+    /** Check this one even if the sample or a condition would skip it. */ always?: boolean;
+    /** Share of calls people check, 0 to 1, for this call. */ sample?: number;
+    /** Seconds people have to answer. */ timeout?: number;
+    metadata?: Record<string, unknown>;
+    webhook_url?: string;
+};
+type CheckExtra = {
+    check: string;
+    on_timeout: "proceed" | "hold";
+    kept_private?: string[];
+    skipped_because?: string;
+};
+type CheckResult = Task & Omit<CheckExtra, "kept_private" | "skipped_because"> & {
+    /** The option to act on, by label. */ answer: string | null;
+    /** false when the check wasn't needed this time (a sample or a condition). */ checked: boolean;
+    timed_out: boolean;
+    kept_private: string[];
+    skipped_because: string | null;
+};
 type TaskStatus = "pending" | "completed" | "expired" | "canceled" | "skipped";
 type Result = {
     answer: string | null;
@@ -253,6 +340,30 @@ type MapKey = {
     created_at: string;
     last_used_at: string | null;
 };
+type MapChanges = {
+    since: number | null;
+    added: {
+        id: string;
+        label: string;
+        score: number | null;
+        checked: boolean;
+    }[];
+    removed: {
+        id: string;
+        label: string;
+    }[];
+    renamed: {
+        from: string;
+        to: string;
+        label: string;
+    }[];
+    risky: {
+        id: string;
+        label: string;
+        score: number;
+        why: string[];
+    }[];
+};
 type StoredAgentMap = AgentMap & {
     object: "agent_map";
     app: string;
@@ -260,6 +371,23 @@ type StoredAgentMap = AgentMap & {
     created_at?: string;
     via?: string;
     url?: string;
+    /** Set for a branch map: the branch, the main map version it's compared with, and its pull request. */
+    branch?: string;
+    main_version?: number | null;
+    pull_request?: string | null;
+    changes?: MapChanges;
+    engine?: {
+        version: string;
+        actions: Record<string, {
+            score: number;
+            factors: string[];
+            oversight: {
+                mode: string;
+                rate: number | null;
+                verifiers: number;
+            };
+        }>;
+    };
 };
 type Rubric = {
     object: "rubric";
@@ -352,7 +480,7 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.15.0";
+declare const VERSION = "1.18.0";
 type GitHubLink = {
     object: "github_link";
     app: string;
@@ -469,7 +597,10 @@ declare class Plures {
         guide: () => Promise<string>;
         retrieve: (app: string) => Promise<StoredAgentMap>;
         /** Uploads a new version. Checks you already added or dismissed keep that. */
-        upload: (app: string, map: AgentMap) => Promise<StoredAgentMap>;
+        /** A branch other than the main one gets its own map, compared with main, and noted on its pull request. */
+        upload: (app: string, map: AgentMap, opts?: {
+            branch?: string;
+        }) => Promise<StoredAgentMap>;
         setCheckpoint: (app: string, id: string, status: "added" | "dismissed" | "suggested") => Promise<StoredAgentMap>;
         /** A key that can only read and upload this app's map, for CI. The key is in the response once. */
         createKey: (app: string, opts?: {
@@ -525,6 +656,17 @@ declare class Plures {
             phase: string;
             received: number;
         }>;
+        /** After npx plures check add pushed a branch with the check in it: Plures opens the pull request. Pass error instead if adding it failed. */
+        checkPr: (app: string, id: string, p: {
+            branch: string;
+        } | {
+            error: string;
+        }) => Promise<{
+            object: "check_pr";
+            check: string;
+            opened: boolean;
+            pull_request?: string;
+        }>;
         /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
         workflow: (app: string, branch?: string) => Promise<string>;
     };
@@ -652,8 +794,97 @@ declare class Plures {
             metadata: Record<string, unknown>;
         }[]>;
     };
+    /**
+     * Answer reviews: send each turn your assistant answers, with where it routed and what it
+     * retrieved. Plures picks the ones worth a look (rerouted, refused, empty, no sources, asked
+     * again, plus a few at random) and your team grades them. Free, and nothing waits on it: call
+     * it after the reply and don't await it in the user's path.
+     */
+    turns: {
+        log: (t: TurnParams) => Promise<{
+            object: "turn";
+            id: string;
+            app: string;
+            picked: boolean;
+            reason: string | null;
+            signals: string[];
+            asked_again_of?: string;
+        }>;
+        /** Grade a turn from your own tools. */
+        grade: (id: string, g: {
+            intent_ok?: boolean;
+            right_intent?: string;
+            grounded?: "yes" | "partly" | "no" | "should_refuse" | "should_answer";
+            complete?: boolean;
+            missed?: string;
+            fact?: string;
+            doc?: string;
+            note?: string;
+            email?: string;
+        }) => Promise<{
+            object: "turn_grade";
+            turn: string;
+        }>;
+        /** What the grades say: per intent, misroutes, retrieval misses and missed asks. */
+        insights: (app: string, opts?: {
+            days?: number;
+        }) => Promise<Record<string, unknown>>;
+        /** Graded turns as eval data: routes (routing examples), retrieval ({ query, doc, must_contain }), qa ({ question, fact } or { question, unanswerable }), missed. */
+        export: (app: string, kind: "routes" | "retrieval" | "qa" | "missed", opts?: {
+            since?: string;
+        }) => Promise<Record<string, unknown>[]>;
+    };
+    /**
+     * Drift: when a rubric's grades or an answer intent's grades fall, Plures opens a case, the repo's
+     * runner reads the code with the examples that got worse and opens a fix, and Plures checks the
+     * fix brings quality back. npx plures drift fix does the reading in your repo.
+     */
+    drift: {
+        list: (app: string) => Promise<{
+            object: "list";
+            data: DriftCase[];
+        }>;
+        /** Runs the fix on GitHub through the repo's Plures workflow. */
+        fix: (app: string, id: string) => Promise<{
+            object: "drift_fix";
+            case: string;
+            status: string;
+            session: string;
+        }>;
+        /** What got worse: graded examples, the change that started it, and the steps on the map. */
+        packet: (app: string, id: string) => Promise<Record<string, unknown> & {
+            case: string;
+            label: string;
+            session: string | null;
+            kind: "rubric" | "answers";
+        }>;
+        /** After reading the code: the diagnosis, and the branch with the fix if there is one. Plures opens the pull request. */
+        report: (app: string, id: string, p: {
+            diagnosis: DriftDiagnosis;
+            branch?: string | null;
+        } | {
+            error: string;
+        }) => Promise<{
+            object: "drift_fix";
+            case: string;
+            status: string;
+            pull_request?: string;
+        }>;
+    };
     /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
     balance: () => Promise<Balance>;
+    /**
+     * Runs a check from your app's map and waits for the decision. Send the data by name; the check
+     * saved on Plures supplies the question, options, guidance, which fields people see (the rest
+     * never leave Plures), who decides, how often and what happens on a timeout. Any of those can be
+     * overridden for this call. `answer` is the option to act on: what people chose, the first option
+     * when the check wasn't needed (a sample or a condition) or timed out set to go ahead, and null
+     * when it timed out set to hold.
+     */
+    check(id: string, data?: Record<string, unknown>, overrides?: CheckOverrides, opts?: {
+        timeoutMs?: number;
+        idempotencyKey?: string;
+    }): Promise<CheckResult>;
     /** Creates a task and waits for people to answer it. */
     verify(params: CreateTask, opts?: {
         timeoutMs?: number;
@@ -667,4 +898,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type GitHubLink, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };
+export { type AgentMap, type App, type Balance, type CheckOverrides, type CheckResult, type Consensus, type CreateTask, type DriftCase, type DriftDiagnosis, type Escalation, type GitHubLink, type MapChanges, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, type TurnParams, VERSION, type WebhookEvent, Plures as default };

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   PluresError,
   VERSION,
   index_default
-} from "./chunk-JSR4MDEK.js";
+} from "./chunk-RKIJTDS3.js";
 export {
   Plures,
   PluresError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plures",
-  "version": "1.15.0",
+  "version": "1.18.0",
   "description": "Human judgment as an API for AI agents. Send a decision to ID verified people and get their consensus back.",
   "keywords": [
     "human-in-the-loop",