@spendgraph/workflows 0.2.0

package/dist/noesis/producers/plan-candidates/prompt.js

@@ -0,0 +1,46 @@
+/** Stage 3A. Pulled by slug, so an edit needs no release here. */
+export const PLAN_SLUG = "ctr-3a-plan-candidates-898095";
+/** What the reply must be, as the prompt itself specifies it. */
+export const PLAN_SCHEMA = {
+    type: "object",
+    properties: {
+        candidates: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    approach: { type: "string" },
+                    strongest_reason: { type: "string" },
+                    fatal_risk: { type: "string" },
+                    cost: { type: "string" },
+                },
+                required: ["id", "approach", "strongest_reason", "fatal_risk", "cost"],
+            },
+        },
+        chosen: { type: "string" },
+        rationale: { type: "string" },
+        switch_trigger: {
+            type: "object",
+            properties: {
+                observation: { type: "string" },
+                switch_to: { type: "string" },
+            },
+            required: ["observation", "switch_to"],
+        },
+        steps: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    n: { type: "number" },
+                    action: { type: "string" },
+                    predicted_outcome: { type: "string" },
+                    tolerance: { type: "string" },
+                },
+                required: ["n", "action", "predicted_outcome", "tolerance"],
+            },
+        },
+    },
+    required: ["candidates", "chosen", "rationale", "switch_trigger", "steps"],
+};

package/dist/noesis/producers/plan-candidates/types.d.ts

@@ -0,0 +1,32 @@
+import type { Asked } from "../../context.js";
+import type { StageOptions, StageOutcome } from "../../stage.js";
+/** One way the question could be approached. */
+export interface PlanCandidate {
+    id: string;
+    approach: string;
+    strongest_reason: string;
+    fatal_risk: string;
+    cost: string;
+}
+/** What would make the chosen approach the wrong one, and what to move to. */
+export interface SwitchTrigger {
+    observation: string;
+    switch_to: string;
+}
+export interface PlanStep {
+    n: number;
+    action: string;
+    predicted_outcome: string;
+    /** How far the actual result may differ before the loop must re-plan. */
+    tolerance: string;
+}
+export interface PlanCandidates {
+    candidates: PlanCandidate[];
+    chosen: string;
+    rationale: string;
+    switch_trigger: SwitchTrigger;
+    steps: PlanStep[];
+}
+export type PlanCandidatesInput = Asked;
+export type PlanCandidatesOptions = StageOptions;
+export type PlanCandidatesResult = StageOutcome<PlanCandidates>;

package/dist/noesis/producers/plan-candidates/types.js

@@ -0,0 +1 @@
+export {};

package/dist/noesis/producers/qn-brief/index.d.ts

@@ -0,0 +1,3 @@
+export { invoke } from "./invoke.js";
+export { BRIEF_SCHEMA, BRIEF_SLUG } from "./prompt.js";
+export type { BriefInput, BriefOptions, BriefResult, KeyConcept, QuestionBrief, Viewpoint, } from "./types.js";

package/dist/noesis/producers/qn-brief/index.js

@@ -0,0 +1,2 @@
+export { invoke } from "./invoke.js";
+export { BRIEF_SCHEMA, BRIEF_SLUG } from "./prompt.js";

package/dist/noesis/producers/qn-brief/invoke.d.ts

@@ -0,0 +1,5 @@
+import type { Llm } from "@spendgraph/llms";
+import type { PromptClient } from "@spendgraph/prompt";
+import type { BriefInput, BriefOptions, BriefResult } from "./types.js";
+/** Stage 1. Interrogates the question and hands back the brief, never an answer. */
+export declare function invoke(client: PromptClient, llm: Llm, input: BriefInput, opts?: BriefOptions): Promise<BriefResult>;

package/dist/noesis/producers/qn-brief/invoke.js

@@ -0,0 +1,6 @@
+import { runStage } from "../../stage.js";
+import { BRIEF_SCHEMA, BRIEF_SLUG } from "./prompt.js";
+/** Stage 1. Interrogates the question and hands back the brief, never an answer. */
+export function invoke(client, llm, input, opts = {}) {
+    return runStage(client, llm, BRIEF_SLUG, BRIEF_SCHEMA, input, opts);
+}

package/dist/noesis/producers/qn-brief/prompt.d.ts

@@ -0,0 +1,12 @@
+import type { JsonSchema } from "@spendgraph/llms";
+/** The stored question-brief prompt. Pulled by slug, so an edit needs no release here. */
+export declare const BRIEF_SLUG = "ctr-1-question-brief-f2w9fd";
+/**
+ * What the reply must be, as the prompt itself specifies it.
+ *
+ * Every key is required, including the two that are usually null: the prompt
+ * returns `better_question` and `interpretation` as null rather than omitting
+ * them, and a missing key would read downstream as "nothing was ambiguous"
+ * instead of "the stage did not say".
+ */
+export declare const BRIEF_SCHEMA: JsonSchema;

package/dist/noesis/producers/qn-brief/prompt.js

@@ -0,0 +1,65 @@
+/** The stored question-brief prompt. Pulled by slug, so an edit needs no release here. */
+export const BRIEF_SLUG = "ctr-1-question-brief-f2w9fd";
+const STRINGS = { type: "array", items: { type: "string" } };
+const NULLABLE_STRING = { type: ["string", "null"] };
+/**
+ * What the reply must be, as the prompt itself specifies it.
+ *
+ * Every key is required, including the two that are usually null: the prompt
+ * returns `better_question` and `interpretation` as null rather than omitting
+ * them, and a missing key would read downstream as "nothing was ambiguous"
+ * instead of "the stage did not say".
+ */
+export const BRIEF_SCHEMA = {
+    type: "object",
+    properties: {
+        purpose: { type: "string" },
+        restated_question: { type: "string" },
+        restatement_differs: { type: "boolean" },
+        information_given: STRINGS,
+        information_needed: STRINGS,
+        key_concepts: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    term: { type: "string" },
+                    definition: { type: "string" },
+                },
+                required: ["term", "definition"],
+            },
+        },
+        assumptions: STRINGS,
+        viewpoints: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    stakeholder: { type: "string" },
+                    position: { type: "string" },
+                },
+                required: ["stakeholder", "position"],
+            },
+        },
+        implications_if_wrong: { type: "string" },
+        is_right_question: { type: "boolean" },
+        better_question: NULLABLE_STRING,
+        interpretation: NULLABLE_STRING,
+        ruled_out: STRINGS,
+    },
+    required: [
+        "purpose",
+        "restated_question",
+        "restatement_differs",
+        "information_given",
+        "information_needed",
+        "key_concepts",
+        "assumptions",
+        "viewpoints",
+        "implications_if_wrong",
+        "is_right_question",
+        "better_question",
+        "interpretation",
+        "ruled_out",
+    ],
+};

package/dist/noesis/producers/qn-brief/types.d.ts

@@ -0,0 +1,42 @@
+import type { Asked } from "../../context.js";
+import type { StageOptions, StageOutcome } from "../../stage.js";
+/** A term whose definition changes the answer. */
+export interface KeyConcept {
+    term: string;
+    definition: string;
+}
+/** Whose interests the answer touches, and where they pull against each other. */
+export interface Viewpoint {
+    stakeholder: string;
+    position: string;
+}
+/**
+ * The brief every later stage reads before it works.
+ *
+ * Every slot is filled or the stage has failed: the prompt is told an empty slot
+ * is a finding rather than a blank, so `information_needed` naming a gap is the
+ * answer, not the absence of one.
+ */
+export interface QuestionBrief {
+    purpose: string;
+    restated_question: string;
+    /** True where the restatement changed the meaning, not merely the wording. */
+    restatement_differs: boolean;
+    information_given: string[];
+    /** Each item is a research subtask for the stages downstream. */
+    information_needed: string[];
+    key_concepts: KeyConcept[];
+    assumptions: string[];
+    viewpoints: Viewpoint[];
+    implications_if_wrong: string;
+    /** False where a different question would serve the purpose better. */
+    is_right_question: boolean;
+    /** The replacement question. Null while `is_right_question` holds. */
+    better_question: string | null;
+    /** The one reading being proceeded under. Null where nothing was ambiguous. */
+    interpretation: string | null;
+    ruled_out: string[];
+}
+export type BriefInput = Asked;
+export type BriefOptions = StageOptions;
+export type BriefResult = StageOutcome<QuestionBrief>;

package/dist/noesis/producers/qn-brief/types.js

@@ -0,0 +1 @@
+export {};

package/dist/noesis/producers/toulmin/answer.d.ts

@@ -0,0 +1,18 @@
+import type { Llm } from "@spendgraph/llms";
+import type { PromptClient } from "@spendgraph/prompt";
+import type { AnswerOptions, AnswerResult, Artifacts } from "./types.js";
+/** Every tier fell over, so there is no answer to render. */
+export declare class NoAnswerError extends Error {
+    readonly escalated: string[];
+    constructor(escalated: string[]);
+}
+/**
+ * Stage 6C, cheapest model first.
+ *
+ * A tier is accepted when it committed to a claim and its own calibrated
+ * confidence clears the bar; an abstention escalates whatever the bar is,
+ * because a stage that could not answer has not answered. Nothing is rewritten
+ * on the way up — each rung answers from the artifacts again, so an escalation
+ * is a second opinion rather than a polish of the first.
+ */
+export declare function answer(client: PromptClient, llm: Llm, artifacts: Artifacts, opts?: AnswerOptions): Promise<AnswerResult>;

package/dist/noesis/producers/toulmin/answer.js

@@ -0,0 +1,87 @@
+import { cascade } from "@spendgraph/harness";
+import { addUsage, totalCost, NO_USAGE } from "../../usage.js";
+import { invoke } from "./invoke.js";
+import { render } from "./render.js";
+const DEFAULT_MIN_CONFIDENCE = 0.6;
+/**
+ * The tiers to run, when the caller named none.
+ *
+ * One tier, and it is the model the `Llm` was built with. A default list of
+ * model ids chosen here would answer on a model the caller never picked, and on
+ * a provider that has never heard of those ids it fails outright — at the last
+ * stage, after every earlier one has been paid for.
+ *
+ * So a cascade is something you ask for. Naming two tiers is what buys the
+ * second opinion; naming none gets the model already configured, once.
+ */
+const tiersFor = (llm, named) => named?.length ? named : [{ model: llm.model }];
+/** Every tier fell over, so there is no answer to render. */
+export class NoAnswerError extends Error {
+    escalated;
+    constructor(escalated) {
+        super(`No tier produced an answer (tried ${escalated.join(", ") || "none"}).`);
+        this.escalated = escalated;
+        this.name = "NoAnswerError";
+    }
+}
+/**
+ * Stage 6C, cheapest model first.
+ *
+ * A tier is accepted when it committed to a claim and its own calibrated
+ * confidence clears the bar; an abstention escalates whatever the bar is,
+ * because a stage that could not answer has not answered. Nothing is rewritten
+ * on the way up — each rung answers from the artifacts again, so an escalation
+ * is a second opinion rather than a polish of the first.
+ */
+export async function answer(client, llm, artifacts, opts = {}) {
+    const tiers = tiersFor(llm, opts.tiers);
+    const floor = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+    const rolloutIds = [];
+    const pricings = [];
+    let usage = NO_USAGE;
+    const result = await cascade({}, {
+        maxTokens: opts.maxTokens,
+        tiers: tiers.map((tier) => ({
+            name: tier.model,
+            run: async () => {
+                const reply = await invoke(client, llm, artifacts, {
+                    model: tier.model,
+                    params: tier.params,
+                    emit: opts.emit,
+                    attempts: opts.attempts,
+                });
+                rolloutIds.push(reply.rolloutId);
+                usage = addUsage(usage, reply);
+                if (reply.pricing)
+                    pricings.push(reply.pricing);
+                return {
+                    output: JSON.stringify(reply.answer),
+                    model: reply.model,
+                    inputTokens: reply.inputTokens,
+                    outputTokens: reply.outputTokens,
+                    data: reply.answer,
+                };
+            },
+        })),
+        accept: (produced) => {
+            const toulmin = produced.data;
+            if (!toulmin || toulmin.abstained)
+                return false;
+            return (toulmin.qualifier?.confidence ?? 0) >= floor;
+        },
+    });
+    const toulmin = result.data;
+    if (!toulmin)
+        throw new NoAnswerError(result.escalated);
+    return {
+        ...usage,
+        ...(pricings.length ? { pricing: Promise.all(pricings).then(totalCost) } : {}),
+        text: render(toulmin, opts),
+        answer: toulmin,
+        model: result.tier ?? "unknown",
+        accepted: result.accepted,
+        escalated: result.escalated,
+        rolloutIds,
+        latencyMs: result.latencyMs,
+    };
+}

package/dist/noesis/producers/toulmin/index.d.ts

@@ -0,0 +1,5 @@
+export { answer, NoAnswerError } from "./answer.js";
+export { invoke, ToulminReplyError } from "./invoke.js";
+export { TOULMIN_SCHEMA, TOULMIN_SLUG } from "./prompt.js";
+export { render } from "./render.js";
+export type { AnswerOptions, AnswerResult, AnswerTier, Artifacts, Ground, Qualifier, Rebuttal, ToulminAnswer, ToulminOptions, ToulminResult, } from "./types.js";

package/dist/noesis/producers/toulmin/index.js

@@ -0,0 +1,4 @@
+export { answer, NoAnswerError } from "./answer.js";
+export { invoke, ToulminReplyError } from "./invoke.js";
+export { TOULMIN_SCHEMA, TOULMIN_SLUG } from "./prompt.js";
+export { render } from "./render.js";

package/dist/noesis/producers/toulmin/invoke.d.ts

@@ -0,0 +1,18 @@
+import type { Llm } from "@spendgraph/llms";
+import type { PromptClient } from "@spendgraph/prompt";
+import type { Artifacts, ToulminOptions, ToulminResult } from "./types.js";
+/** The reply came back, but not as the object the stage is supposed to return. */
+export declare class ToulminReplyError extends Error {
+    readonly raw: string;
+    constructor(raw: string);
+}
+/**
+ * Stage 6C. Compiles the artifacts into the final answer and its qualifier.
+ *
+ * The artifacts are the request, so they go through `{question}` like every
+ * other stage's. They used to arrive as a history turn instead, which worked
+ * only while the prompt's question box was empty: `renderMessages` puts history
+ * between the system turn and the question, so anything saved in that box would
+ * have been the last thing the model read.
+ */
+export declare function invoke(client: PromptClient, llm: Llm, artifacts: Artifacts, opts?: ToulminOptions): Promise<ToulminResult>;

package/dist/noesis/producers/toulmin/invoke.js

@@ -0,0 +1,53 @@
+import { askThrough, QUESTION_FIELD } from "../../question.js";
+import { attempting } from "../../retry.js";
+import { announce, failed } from "../../started.js";
+import { usageOf } from "../../usage.js";
+import { TOULMIN_SCHEMA, TOULMIN_SLUG } from "./prompt.js";
+/** The reply came back, but not as the object the stage is supposed to return. */
+export class ToulminReplyError extends Error {
+    raw;
+    constructor(raw) {
+        super("Toulmin answer returned no object matching its schema.");
+        this.raw = raw;
+        this.name = "ToulminReplyError";
+    }
+}
+function asText(artifacts) {
+    return typeof artifacts === "string" ? artifacts : JSON.stringify(artifacts, null, 2);
+}
+/**
+ * Stage 6C. Compiles the artifacts into the final answer and its qualifier.
+ *
+ * The artifacts are the request, so they go through `{question}` like every
+ * other stage's. They used to arrive as a history turn instead, which worked
+ * only while the prompt's question box was empty: `renderMessages` puts history
+ * between the system turn and the question, so anything saved in that box would
+ * have been the last thing the model read.
+ */
+export async function invoke(client, llm, artifacts, opts = {}) {
+    announce(opts.emit, TOULMIN_SLUG, opts.model);
+    return attempting(async () => {
+        const prompt = await client.pull(TOULMIN_SLUG);
+        let reply;
+        const question = asText(artifacts);
+        const outcome = await prompt.call({ [QUESTION_FIELD]: question }, async ({ messages }) => {
+            reply = await llm.call(askThrough(messages, question, TOULMIN_SLUG), {
+                model: opts.model,
+                schema: TOULMIN_SCHEMA,
+                trace: false,
+                params: opts.params,
+            });
+            return reply;
+        });
+        if (reply?.data === undefined)
+            throw new ToulminReplyError(outcome.output);
+        return {
+            ...usageOf(outcome),
+            ...(outcome.pricing ? { pricing: outcome.pricing } : {}),
+            answer: reply.data,
+            rolloutId: outcome.rolloutId,
+            model: outcome.model,
+            latencyMs: reply.latencyMs ?? 0,
+        };
+    }, { attempts: opts.attempts, onFailure: (err) => failed(opts.emit, TOULMIN_SLUG, err) });
+}

package/dist/noesis/producers/toulmin/prompt.d.ts

@@ -0,0 +1,12 @@
+import type { JsonSchema } from "@spendgraph/llms";
+/** The stored answer-assembly prompt. Pulled by slug, so an edit needs no release here. */
+export declare const TOULMIN_SLUG = "ctr-6c-toulmin-answer-d28bb8";
+/**
+ * What the reply must be, as the prompt itself specifies it.
+ *
+ * `rebuttals` and `would_change_my_mind` are required rather than optional on
+ * purpose: an empty list is a claim the stage may make, but a missing key would
+ * let a surviving objection be dropped silently, which is what this stage
+ * exists to prevent.
+ */
+export declare const TOULMIN_SCHEMA: JsonSchema;

package/dist/noesis/producers/toulmin/prompt.js

@@ -0,0 +1,60 @@
+/** The stored answer-assembly prompt. Pulled by slug, so an edit needs no release here. */
+export const TOULMIN_SLUG = "ctr-6c-toulmin-answer-d28bb8";
+const UNIT = { type: "number", minimum: 0, maximum: 1 };
+/**
+ * What the reply must be, as the prompt itself specifies it.
+ *
+ * `rebuttals` and `would_change_my_mind` are required rather than optional on
+ * purpose: an empty list is a claim the stage may make, but a missing key would
+ * let a surviving objection be dropped silently, which is what this stage
+ * exists to prevent.
+ */
+export const TOULMIN_SCHEMA = {
+    type: "object",
+    properties: {
+        claim: { type: "string" },
+        grounds: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    evidence: { type: "string" },
+                    source_stage: { type: "string" },
+                },
+                required: ["evidence", "source_stage"],
+            },
+        },
+        warrant: { type: "string" },
+        qualifier: {
+            type: "object",
+            properties: {
+                confidence: UNIT,
+                holds_when: { type: "string" },
+                does_not_apply_to: { type: "string" },
+            },
+            required: ["confidence", "holds_when", "does_not_apply_to"],
+        },
+        rebuttals: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    objection: { type: "string" },
+                    defeats_claim_when: { type: "string" },
+                },
+                required: ["objection", "defeats_claim_when"],
+            },
+        },
+        would_change_my_mind: { type: "string" },
+        abstained: { type: "boolean" },
+    },
+    required: [
+        "claim",
+        "grounds",
+        "warrant",
+        "qualifier",
+        "rebuttals",
+        "would_change_my_mind",
+        "abstained",
+    ],
+};

package/dist/noesis/producers/toulmin/render.d.ts

@@ -0,0 +1,14 @@
+import type { AnswerOptions, ToulminAnswer } from "./types.js";
+/**
+ * The answer as a person reads it.
+ *
+ * Pure, and deliberately not a seventh prompt. Every part of a `ToulminAnswer`
+ * is something the stage was forbidden to soften — a surviving objection, a
+ * calibrated number, an abstention — and handing the object to a model to write
+ * up returns each of those chances on the last call before anyone sees it.
+ *
+ * Objections are never dropped. Where something has to give, grounds go first,
+ * which is why they are off by default: they are the audit trail, and the
+ * rollout already has them.
+ */
+export declare function render(answer: ToulminAnswer, opts?: AnswerOptions): string;

package/dist/noesis/producers/toulmin/render.js

@@ -0,0 +1,82 @@
+function confidencePhrase(confidence) {
+    if (confidence >= 0.9)
+        return "very high";
+    if (confidence >= 0.75)
+        return "high";
+    if (confidence >= 0.5)
+        return "moderate";
+    if (confidence >= 0.25)
+        return "low";
+    return "very low";
+}
+/**
+ * Whether the model actually said this.
+ *
+ * Takes `string | undefined` although `ToulminAnswer` types every field as a
+ * string, because nothing enforces that: the schema's `required` list is sent
+ * to the provider and never checked on the way back, so a field the model
+ * omitted arrives as `undefined` and reads here as unsaid.
+ */
+function said(value) {
+    return !!value && value.trim().length > 0;
+}
+/**
+ * The model writes these as sentences, and the label already supplies the
+ * conjunction — without this they read "holds when when the trace shows".
+ */
+function clause(text) {
+    return text.trim().replace(/^(when|if)\s+/i, "");
+}
+function qualifierLine(answer) {
+    const { confidence, holds_when, does_not_apply_to } = answer.qualifier ?? {};
+    const parts = typeof confidence === "number"
+        ? [`Confidence: ${confidencePhrase(confidence)} (${confidence.toFixed(2)}).`]
+        : [];
+    if (said(holds_when))
+        parts.push(`Holds when ${clause(holds_when)}.`);
+    if (said(does_not_apply_to))
+        parts.push(`Does not apply to ${clause(does_not_apply_to)}.`);
+    return parts.join(" ");
+}
+function rebuttalLines(rebuttals) {
+    const lines = (rebuttals ?? [])
+        .filter((r) => said(r.objection))
+        .map((r) => said(r.defeats_claim_when)
+        ? `- ${r.objection} — defeats this when ${clause(r.defeats_claim_when)}`
+        : `- ${r.objection}`);
+    return lines.length > 0 ? `Objections that stand:\n${lines.join("\n")}` : "";
+}
+function groundLines(answer) {
+    const lines = (answer.grounds ?? [])
+        .filter((g) => said(g.evidence))
+        .map((g) => (said(g.source_stage) ? `- ${g.evidence} (${g.source_stage})` : `- ${g.evidence}`));
+    const grounds = lines.length > 0 ? `Grounds:\n${lines.join("\n")}` : "";
+    const warrant = said(answer.warrant) ? `Warrant: ${answer.warrant}` : "";
+    return [grounds, warrant].filter(said).join("\n\n");
+}
+/**
+ * The answer as a person reads it.
+ *
+ * Pure, and deliberately not a seventh prompt. Every part of a `ToulminAnswer`
+ * is something the stage was forbidden to soften — a surviving objection, a
+ * calibrated number, an abstention — and handing the object to a model to write
+ * up returns each of those chances on the last call before anyone sees it.
+ *
+ * Objections are never dropped. Where something has to give, grounds go first,
+ * which is why they are off by default: they are the audit trail, and the
+ * rollout already has them.
+ */
+export function render(answer, opts = {}) {
+    const rebuttals = rebuttalLines(answer.rebuttals);
+    const changes = said(answer.would_change_my_mind)
+        ? `What would change this: ${answer.would_change_my_mind}`
+        : "";
+    if (answer.abstained) {
+        return ["Not enough to answer.", answer.claim, rebuttals, changes].filter(said).join("\n\n");
+    }
+    const sections = [answer.claim, qualifierLine(answer), rebuttals];
+    if (opts.showGrounds)
+        sections.push(groundLines(answer));
+    sections.push(changes);
+    return sections.filter(said).join("\n\n");
+}