plures 1.4.0 → 1.7.0

package/dist/index.cjs

@@ -26,7 +26,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.4.0";
+var VERSION = "1.7.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -39,17 +39,22 @@ var PluresError = class extends Error {
 var Plures = class {
   base;
   apiKey;
+  /** The app tasks go to when they don't name one. From opts.app or PLURES_APP. */
+  app;
+  ua;
   constructor(apiKey, opts = {}) {
     const key = apiKey ?? (typeof process !== "undefined" ? process.env?.PLURES_API_KEY : void 0);
     if (!key) throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
     this.apiKey = key;
+    this.ua = opts.userAgent ?? `plures-js/${VERSION}`;
+    this.app = opts.app ?? (typeof process !== "undefined" ? process.env?.PLURES_APP : void 0) ?? null;
     this.base = (opts.baseUrl ?? (typeof process !== "undefined" ? process.env?.PLURES_BASE_URL : void 0) ?? "https://plures.si").replace(/\/$/, "");
   }
   async req(method, path, body, headers = {}) {
     for (let attempt = 0; ; attempt++) {
       const r = await fetch(this.base + path, {
         method,
-        headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": `plures-js/${VERSION}`, ...body ? { "content-type": "application/json" } : {}, ...headers },
+        headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua, ...body ? { "content-type": "application/json" } : {}, ...this.app ? { "plures-app": this.app } : {}, ...headers },
         body: body ? JSON.stringify(body) : void 0
       });
       if (r.status >= 500 && attempt < 2) {
@@ -92,6 +97,69 @@ var Plures = class {
     set: (mix) => this.req("PUT", "/api/v1/test_mix", { mix }),
     clear: () => this.req("DELETE", "/api/v1/test_mix")
   };
+  /**
+   * Where tasks go. set() replaces what you send (team, groups or rules) and keeps the rest.
+   * For example { groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }.
+   */
+  routing = {
+    get: () => this.req("GET", "/api/v1/routing"),
+    set: (update) => this.req("PUT", "/api/v1/routing", update)
+  };
+  /** Your apps. Each agent you run can be its own app, with its own tasks, ledger view and map. */
+  apps = {
+    list: () => this.req("GET", "/api/v1/apps"),
+    /** { name: "Support agent" }, with an optional id like "support-agent". */
+    create: (params) => this.req("POST", "/api/v1/apps", params),
+    retrieve: (id) => this.req("GET", `/api/v1/apps/${encodeURIComponent(id)}`),
+    /** Rename it, change its id (its tasks move with it), or make it the default. */
+    update: (id, params) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(id)}`, params),
+    /** Only an app with no tasks can be deleted. */
+    del: (id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(id)}`)
+  };
+  /**
+   * Agent maps: where each app's agent needs a person. Your coding agent reads your code and
+   * writes the map; Plures gets only the map. guide() returns the steps it follows.
+   */
+  maps = {
+    guide: async () => {
+      const r = await fetch(`${this.base}/api/v1/map_guide`);
+      return r.text();
+    },
+    retrieve: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map`),
+    /** Uploads a new version. Checks you already added or dismissed keep that. */
+    upload: (app, map) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app)}/map`, map),
+    setCheckpoint: (app, id, status) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(app)}/map/checkpoints/${encodeURIComponent(id)}`, { status })
+  };
+  /**
+   * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
+   * early, and compare two versions blind before you ship. Personal details are taken out first.
+   */
+  quality = {
+    /** Send every output; the rubric's sample rate decides which ones people grade. */
+    sample: (p) => this.req("POST", "/api/v1/samples", p),
+    /** A blind release check: a is the current version's output, b the new one's, for the same input. */
+    compare: (p) => this.req("POST", "/api/v1/comparisons", p),
+    /** How often people preferred the new version, with a 95% range and a verdict. */
+    release: (name, opts = {}) => this.req("GET", `/api/v1/releases/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+    rubrics: {
+      list: (opts = {}) => this.req("GET", `/api/v1/rubrics${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      /** { name: "reply_quality", question: "Is this reply correct and kind?", options: ["Good", "Okay", "Bad"], sample_rate: 0.05 } */
+      create: (p) => this.req("POST", "/api/v1/rubrics", p),
+      retrieve: (name, opts = {}) => this.req("GET", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      update: (name, p) => this.req("PATCH", `/api/v1/rubrics/${encodeURIComponent(name)}${p.app ? `?app=${encodeURIComponent(p.app)}` : ""}`, p),
+      del: (name, opts = {}) => this.req("DELETE", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`)
+    },
+    /** Graded samples as JSON lines (input, output, grade, score, agreement), for fine tuning or an eval set. */
+    export: async (rubric, opts = {}) => {
+      const q = new URLSearchParams(Object.entries({ app: opts.app ?? this.app ?? void 0, since: opts.since }).filter(([, v]) => v));
+      const r = await fetch(`${this.base}/api/v1/rubrics/${encodeURIComponent(rubric)}/export${q.size ? `?${q}` : ""}`, { headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua } });
+      if (!r.ok) {
+        const d = await r.json().catch(() => ({}));
+        throw new PluresError(d?.error?.message ?? `HTTP ${r.status}`, r.status, d?.error?.type ?? "api_error");
+      }
+      return (await r.text()).split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    }
+  };
   /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
   balance = () => this.req("GET", "/api/v1/balance");
   /** Creates a task and waits for people to answer it. */

package/dist/index.d.cts

@@ -2,6 +2,8 @@ type Option = {
     id: string;
     label: string;
 };
+/** "verifiers" asks ID verified people first; "team" goes straight to your own people ($0.05 per internal vote live). */
+type Route = "verifiers" | "team";
 type TaskStatus = "pending" | "completed" | "expired" | "canceled";
 type Result = {
     answer: string | null;
@@ -15,17 +17,44 @@ type Result = {
     /** The team member who decided, when decided_by is "team". */
     reviewer?: string;
     note?: string;
+    /** How your team voted, when your team decided. */
+    team?: TeamTally;
 };
-/** Set when verifiers didn't all agree and the decision went to your team. */
+type TeamVote = {
+    reviewer: string;
+    answer: string;
+    note: string | null;
+    confirmed: boolean;
+    lead: boolean;
+};
+type TeamTally = {
+    votes: Record<string, number>;
+    agreement: number;
+    required: number;
+    unanimous: boolean;
+    voters: TeamVote[];
+    decided_by_lead: boolean;
+    agreed: boolean;
+};
+/** How your team decides: how many vote, whether they must all agree, a lead for splits, passkey confirmation. */
+type Consensus = {
+    votes: number;
+    unanimous: boolean;
+    lead: string | null;
+    passkey: boolean;
+};
+/** Set when the decision went to your team: straight there (team_only), or because verifiers didn't all agree or answer in time. */
 type Escalation = {
-    reason: "split" | "tie" | "no_answer";
+    reason: "split" | "tie" | "no_answer" | "team_only";
     escalated_at: string;
     verifiers: Result | null;
     team_deadline?: string;
+    lead_called_at?: string;
 };
 type Task = {
     id: string;
     object: "task";
+    app?: string | null;
     mode: "live" | "test";
     status: TaskStatus;
     question: string;
@@ -42,11 +71,23 @@ type Task = {
     result: Result | null;
     escalation?: Escalation | null;
     metadata: Record<string, unknown>;
-    /** Live tasks only: price per answer and what answers have cost so far, in US cents. */
+    /** Where it went: verified people first, or straight to your team. */
+    route?: Route;
+    category?: string | null;
+    /** The named team that decides, or null for your main team. */
+    team?: string | null;
+    team_consensus?: {
+        votes: number;
+        unanimous: boolean;
+        lead: boolean;
+        passkey: boolean;
+    };
+    /** Live tasks only: price per answer and what answers have cost so far, in US cents. A task sent straight to your team is billed per internal vote, billed_as "internal_votes". */
     cost?: {
         per_answer_cents: number;
         answers_billed: number;
         total_cents: number;
+        billed_as?: "answers" | "internal_votes";
     } | null;
     /** Where this decision sits on the Plures ledger, once recorded. */
     ledger?: {
@@ -83,10 +124,59 @@ type CreateTask = {
     escalate?: boolean;
     /** Agreement below which this task goes to your team, 0 to 1. Default from your dashboard. */
     escalate_below?: number;
+    /** "team" skips verified people and sends it straight to your team. Default "verifiers". */
+    route?: Route;
+    /** A label your routing rules match on, like "refunds". */
+    category?: string;
+    /** The name of one of your teams, like "Finance", instead of your main team. */
+    team?: string;
+    /** How many people on the team vote; the majority decides. Default from the team. */
+    team_votes?: number;
+    /** Everyone who votes must agree, or it goes to the team's lead. */
+    team_unanimous?: boolean;
+    /** Which of your apps this task belongs to, like "support-agent". Defaults to the client's app, then your default app. */
+    app?: string;
+};
+/** Your main team, named teams and rules by category. */
+type RoutingRule = {
+    category: string;
+    route: Route;
+    group: string | null;
+    escalate_below: number | null;
+};
+type Routing = {
+    object: "routing";
+    team: {
+        emails: string[];
+        escalate_below: number;
+    } & Consensus;
+    groups: ({
+        name: string;
+        emails: string[];
+    } & Consensus)[];
+    rules: RoutingRule[];
+    internal_vote_cents: number;
+};
+type RoutingUpdate = {
+    team?: {
+        emails?: string[];
+        escalate_below?: number;
+    } & Partial<Consensus>;
+    groups?: ({
+        name: string;
+        emails: string[];
+    } & Partial<Consensus>)[];
+    rules?: {
+        category: string;
+        route?: Route;
+        group?: string | null;
+        escalate_below?: number | null;
+    }[];
 };
 /** Whole number shares of test task outcomes that add up to 100. */
 type Mix = {
     unanimous?: number;
+    most?: number;
     split?: number;
     tie?: number;
     expired?: number;
@@ -97,6 +187,140 @@ type TestMix = {
     to_team_percent: number;
 };
 /** Prepaid credit for live tasks, in US cents. */
+type MapNode = {
+    id: string;
+    label: string;
+    kind: "input" | "model" | "tool" | "action" | "data" | "output" | "human";
+    file?: string | null;
+    line?: number | null;
+    risk?: "low" | "medium" | "high" | null;
+    note?: string | null;
+};
+type MapDraft = {
+    question: string;
+    options: string[];
+    show?: string[];
+    hide?: string[];
+    instructions?: string | null;
+    route?: "verifiers" | "team";
+    team?: string | null;
+    verifiers?: number;
+    escalate_below?: number | null;
+    example?: string | null;
+};
+type MapCheckpoint = {
+    id?: string;
+    at: string;
+    why: string;
+    category?: string;
+    when?: string | null;
+    status?: "suggested" | "added" | "dismissed";
+    draft?: MapDraft | null;
+    stats?: {
+        tasks: number;
+        done: number;
+        agreement: number | null;
+        to_team: number;
+        internal: number;
+        med_ms: number | null;
+    };
+};
+/** An agent map: the steps of one app's agent and where people check. Written by your coding agent; no source code. */
+type AgentMap = {
+    name?: string | null;
+    summary?: string | null;
+    source?: {
+        repo?: string | null;
+        commit?: string | null;
+        tool?: string | null;
+    };
+    nodes: MapNode[];
+    edges: {
+        from: string;
+        to: string;
+        label?: string | null;
+    }[];
+    checkpoints: MapCheckpoint[];
+};
+type StoredAgentMap = AgentMap & {
+    object: "agent_map";
+    app: string;
+    version: number;
+    created_at?: string;
+    via?: string;
+    url?: string;
+};
+type Rubric = {
+    object: "rubric";
+    name: string;
+    app: string;
+    question: string;
+    options: string[];
+    instructions: string | null;
+    sample_rate: number;
+    verifiers: number;
+    drift_points: number;
+    webhook_url: string | null;
+    seen: number;
+    sampled: number;
+    created_at: string;
+    quality?: {
+        score: number | null;
+        this_week: number | null;
+        baseline: number | null;
+        drift: boolean;
+        graded_this_week: number;
+        grades_this_week: Record<string, number>;
+        days: {
+            day: string;
+            score: number | null;
+            n: number;
+        }[];
+    };
+};
+type RubricParams = {
+    name?: string;
+    question?: string;
+    options?: string[];
+    instructions?: string | null;
+    sample_rate?: number;
+    verifiers?: 1 | 3 | 5;
+    drift_points?: number;
+    webhook_url?: string | null;
+    app?: string;
+};
+type Sample = {
+    object: "sample";
+    rubric: string;
+    sampled: boolean;
+    sample_rate: number;
+    redacted: Record<string, number>;
+    task: Task | null;
+};
+type Release = {
+    object: "release";
+    release: string;
+    app: string;
+    compared: number;
+    b_wins: number;
+    a_wins: number;
+    ties: number;
+    win_rate: number | null;
+    low: number | null;
+    high: number | null;
+    verdict: string;
+};
+/** One agent or product on your account. Tasks, the ledger view and the map are kept per app. */
+type App = {
+    object: "app";
+    id: string;
+    name: string;
+    default: boolean;
+    created_at: string;
+    tasks_30d?: number;
+    waiting?: number;
+    last_task_at?: string | null;
+};
 type Balance = {
     object: "balance";
     currency: "usd";
@@ -117,7 +341,7 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.4.0";
+declare const VERSION = "1.7.0";
 declare class PluresError extends Error {
     readonly status: number;
     readonly type: string;
@@ -126,8 +350,13 @@ declare class PluresError extends Error {
 declare class Plures {
     private base;
     private apiKey;
+    /** The app tasks go to when they don't name one. From opts.app or PLURES_APP. */
+    readonly app: string | null;
+    private ua;
     constructor(apiKey?: string, opts?: {
         baseUrl?: string;
+        app?: string;
+        userAgent?: string;
     });
     private req;
     tasks: {
@@ -140,6 +369,7 @@ declare class Plures {
             status?: TaskStatus;
             limit?: number;
             starting_after?: string;
+            app?: string;
         }) => Promise<{
             object: "list";
             data: Task[];
@@ -163,6 +393,126 @@ declare class Plures {
         set: (mix: Mix | null) => Promise<TestMix>;
         clear: () => Promise<TestMix>;
     };
+    /**
+     * Where tasks go. set() replaces what you send (team, groups or rules) and keeps the rest.
+     * For example { groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }.
+     */
+    routing: {
+        get: () => Promise<Routing>;
+        set: (update: RoutingUpdate) => Promise<Routing>;
+    };
+    /** Your apps. Each agent you run can be its own app, with its own tasks, ledger view and map. */
+    apps: {
+        list: () => Promise<{
+            object: "list";
+            data: App[];
+            has_more: boolean;
+        }>;
+        /** { name: "Support agent" }, with an optional id like "support-agent". */
+        create: (params: {
+            name: string;
+            id?: string;
+        }) => Promise<App>;
+        retrieve: (id: string) => Promise<App>;
+        /** Rename it, change its id (its tasks move with it), or make it the default. */
+        update: (id: string, params: {
+            name?: string;
+            id?: string;
+            default?: true;
+        }) => Promise<App>;
+        /** Only an app with no tasks can be deleted. */
+        del: (id: string) => Promise<{
+            object: "app";
+            id: string;
+            deleted: true;
+        }>;
+    };
+    /**
+     * Agent maps: where each app's agent needs a person. Your coding agent reads your code and
+     * writes the map; Plures gets only the map. guide() returns the steps it follows.
+     */
+    maps: {
+        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>;
+        setCheckpoint: (app: string, id: string, status: "added" | "dismissed" | "suggested") => Promise<StoredAgentMap>;
+    };
+    /**
+     * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
+     * early, and compare two versions blind before you ship. Personal details are taken out first.
+     */
+    quality: {
+        /** Send every output; the rubric's sample rate decides which ones people grade. */
+        sample: (p: {
+            rubric: string;
+            output: string;
+            input?: string;
+            app?: string;
+            metadata?: Record<string, unknown>;
+            force?: boolean;
+        }) => Promise<Sample>;
+        /** A blind release check: a is the current version's output, b the new one's, for the same input. */
+        compare: (p: {
+            release: string;
+            a: string;
+            b: string;
+            input?: string;
+            question?: string;
+            instructions?: string;
+            verifiers?: 1 | 3 | 5;
+            app?: string;
+            metadata?: Record<string, unknown>;
+        }) => Promise<{
+            object: "comparison";
+            release: string;
+            task: Task;
+        }>;
+        /** How often people preferred the new version, with a 95% range and a verdict. */
+        release: (name: string, opts?: {
+            app?: string;
+        }) => Promise<Release>;
+        rubrics: {
+            list: (opts?: {
+                app?: string;
+            }) => Promise<{
+                object: "list";
+                data: Rubric[];
+                has_more: boolean;
+            }>;
+            /** { name: "reply_quality", question: "Is this reply correct and kind?", options: ["Good", "Okay", "Bad"], sample_rate: 0.05 } */
+            create: (p: RubricParams & {
+                name: string;
+                question: string;
+                options: string[];
+            }) => Promise<Rubric>;
+            retrieve: (name: string, opts?: {
+                app?: string;
+            }) => Promise<Rubric>;
+            update: (name: string, p: RubricParams) => Promise<Rubric>;
+            del: (name: string, opts?: {
+                app?: string;
+            }) => Promise<{
+                deleted: true;
+            }>;
+        };
+        /** Graded samples as JSON lines (input, output, grade, score, agreement), for fine tuning or an eval set. */
+        export: (rubric: string, opts?: {
+            app?: string;
+            since?: string;
+        }) => Promise<{
+            task_id: string;
+            rubric: string;
+            input: string | null;
+            output: string;
+            grade: string | null;
+            score: number | null;
+            agreement: number | null;
+            graders: number;
+            graded_at: string;
+            metadata: Record<string, unknown>;
+        }[]>;
+    };
     /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
     balance: () => Promise<Balance>;
     /** Creates a task and waits for people to answer it. */
@@ -178,4 +528,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type Balance, type CreateTask, type Escalation, type Mix, type Option, Plures, PluresError, type Result, type Task, type TaskStatus, type TestMix, VERSION, type WebhookEvent, Plures as default };
+export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type MapCheckpoint, type MapDraft, 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 };