@spendgraph/workflows 0.2.0

package/dist/noesis/usage.js

@@ -0,0 +1,56 @@
+export const NO_USAGE = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    citationTokens: 0,
+    reasoningTokens: 0,
+};
+/**
+ * Sums two costs without inventing one.
+ *
+ * Undefined on both sides stays undefined; a priced call landing beside an
+ * unpriced one gives the priced total, which is a floor rather than a fiction.
+ */
+const addCost = (a, b) => a === undefined && b === undefined ? undefined : (a ?? 0) + (b ?? 0);
+/** Every token field filled, so a caller never has to guard one. Cost stays absent when it is. */
+export const usageOf = (reported) => ({
+    inputTokens: reported.inputTokens ?? 0,
+    outputTokens: reported.outputTokens ?? 0,
+    cacheReadTokens: reported.cacheReadTokens ?? 0,
+    cacheWriteTokens: reported.cacheWriteTokens ?? 0,
+    citationTokens: reported.citationTokens ?? 0,
+    reasoningTokens: reported.reasoningTokens ?? 0,
+    ...(reported.costMicros === undefined ? {} : { costMicros: reported.costMicros }),
+});
+export const addUsage = (total, next) => ({
+    inputTokens: total.inputTokens + (next.inputTokens ?? 0),
+    outputTokens: total.outputTokens + (next.outputTokens ?? 0),
+    cacheReadTokens: total.cacheReadTokens + (next.cacheReadTokens ?? 0),
+    cacheWriteTokens: total.cacheWriteTokens + (next.cacheWriteTokens ?? 0),
+    citationTokens: total.citationTokens + (next.citationTokens ?? 0),
+    reasoningTokens: total.reasoningTokens + (next.reasoningTokens ?? 0),
+    ...(() => {
+        const cost = addCost(total.costMicros, next.costMicros);
+        return cost === undefined ? {} : { costMicros: cost };
+    })(),
+});
+/** Every token the call is billed for, however the provider split them. */
+export const billableTokens = (usage) => usage.inputTokens +
+    usage.outputTokens +
+    usage.cacheReadTokens +
+    usage.cacheWriteTokens +
+    usage.citationTokens +
+    usage.reasoningTokens;
+/** What the run is known to have cost, in micro-USD, or undefined where nothing priced it. */
+export const spend = (usage) => usage.costMicros;
+/**
+ * One price for several calls: undefined unless at least one of them was priced.
+ *
+ * The cascade in 6C runs a tier at a time, so a run can hold several prices
+ * still in flight. Summing them with `?? 0` alone would turn "nobody priced
+ * any of these" into a confident zero.
+ */
+export const totalCost = (costs) => costs.some((cost) => cost !== undefined)
+    ? costs.reduce((sum, cost) => sum + (cost ?? 0), 0)
+    : undefined;

package/dist/noesis/verify/index.d.ts

@@ -0,0 +1,2 @@
+export type { Checked, Verification } from "./types.js";
+export { blind, compare, render, SETTLED_WITHOUT_TOOLS } from "./verify.js";

package/dist/noesis/verify/index.js

@@ -0,0 +1 @@
+export { blind, compare, render, SETTLED_WITHOUT_TOOLS } from "./verify.js";

package/dist/noesis/verify/types.d.ts

@@ -0,0 +1,54 @@
+import type { CheckedBy } from "../producers/cove-answers/index.js";
+import type { ClaimType } from "../producers/cove-questions/index.js";
+/** One claim, the question that tested it, and what came back. */
+export interface Checked {
+    id: string;
+    claim: string;
+    claim_type: ClaimType;
+    question: string;
+    /** Empty where the check came back unknown. */
+    answer: string;
+    confidence: number;
+    unknown: boolean;
+    /**
+     * When the fact was true, as 5B dated it. Null where it is time-invariant,
+     * and null where the check found nothing — there is no date for a non-fact.
+     */
+    as_of?: string | null;
+    /** How the check was settled, as the run can actually support it. */
+    checked_by?: CheckedBy;
+    /** What 5B said, where `compare()` had to correct it. */
+    claimed_by?: CheckedBy;
+    /** False where the check could not settle the claim either way. */
+    settled: boolean;
+}
+/**
+ * The two halves of stage 5, put back together.
+ *
+ * Every list here is a count or a missing id — nothing judges whether an answer
+ * agrees with its claim, which is the reading 5C and 6A are for.
+ */
+export interface Verification {
+    checked: Checked[];
+    /** Questions 5A asked that 5B never answered. */
+    unanswered: string[];
+    /** Ids 5B answered that 5A never asked — the pairing has gone wrong. */
+    unasked: string[];
+    /** Claims no check settled: unknown, or below the floor. */
+    unsettled: string[];
+    /** Claims 5A said nothing could settle. */
+    unverifiable: string[];
+    /**
+     * Ids where 5B claimed a provenance the run could not have had.
+     *
+     * Not an error and not a dropped check: the answer still counts, the
+     * provenance on it has been corrected to `knowledge`, and the id is recorded
+     * here so a stage reading the verification can see that the record was
+     * repaired rather than believed.
+     *
+     * A reply that named no provenance is absent from this list. Saying nothing
+     * is not the same as claiming a tool, and a gate told otherwise would refuse
+     * over a correction nobody made.
+     */
+    overclaimed: string[];
+}

package/dist/noesis/verify/types.js

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

package/dist/noesis/verify/verify.d.ts

@@ -0,0 +1,36 @@
+import type { CheckedBy, CoveAnswers } from "../producers/cove-answers/index.js";
+import type { CoveQuestions } from "../producers/cove-questions/index.js";
+import type { Verification } from "./types.js";
+/**
+ * What a check can honestly have been settled by when 5B is given no tools.
+ *
+ * `coveAnswers` is called with a client, a model and a question — there is no
+ * `ToolBus` on that call, so parametric memory is the only thing the stage can
+ * have used. Every other value in the enum is reachable only by passing a wider
+ * set to `compare()`, which is the caller saying it wired the tools up.
+ */
+export declare const SETTLED_WITHOUT_TOOLS: ReadonlySet<CheckedBy>;
+/**
+ * The questions as 5B is allowed to see them: ids and questions, nothing else.
+ *
+ * `claim_it_tests` and `claim_type` are stripped here rather than trusted to a
+ * prompt. Answering blind is the whole reason 5A and 5B are two stages, and a
+ * stage that can read the claim will answer the claim.
+ */
+export declare function blind(questions: CoveQuestions): string;
+/**
+ * 5A and 5B paired back together by id.
+ *
+ * In code because it has to be: whatever does this sees both the claim and the
+ * answer that was written without it, and a model given both is no longer a
+ * blind check of anything.
+ *
+ * A reply that named no provenance at all is not overclaiming. `checked_by` is
+ * required by the schema and nothing checks a reply against it on the way back,
+ * so an absent one is the model being terse rather than the stage claiming a
+ * tool it never had — it settles to `knowledge`, which is the floor anyway, and
+ * is not reported as a correction nobody made.
+ */
+export declare function compare(questions: CoveQuestions, answers: CoveAnswers, floor?: number, settledBy?: ReadonlySet<CheckedBy>): Verification;
+/** The verification as a stage reads it. */
+export declare function render(verification: Verification): string;

package/dist/noesis/verify/verify.js

@@ -0,0 +1,94 @@
+const DEFAULT_FLOOR = 0.6;
+/**
+ * What a check can honestly have been settled by when 5B is given no tools.
+ *
+ * `coveAnswers` is called with a client, a model and a question — there is no
+ * `ToolBus` on that call, so parametric memory is the only thing the stage can
+ * have used. Every other value in the enum is reachable only by passing a wider
+ * set to `compare()`, which is the caller saying it wired the tools up.
+ */
+export const SETTLED_WITHOUT_TOOLS = new Set(["knowledge"]);
+/**
+ * The questions as 5B is allowed to see them: ids and questions, nothing else.
+ *
+ * `claim_it_tests` and `claim_type` are stripped here rather than trusted to a
+ * prompt. Answering blind is the whole reason 5A and 5B are two stages, and a
+ * stage that can read the claim will answer the claim.
+ */
+export function blind(questions) {
+    return questions.questions.map((q) => `${q.id}. ${q.question}`).join("\n");
+}
+/**
+ * 5A and 5B paired back together by id.
+ *
+ * In code because it has to be: whatever does this sees both the claim and the
+ * answer that was written without it, and a model given both is no longer a
+ * blind check of anything.
+ *
+ * A reply that named no provenance at all is not overclaiming. `checked_by` is
+ * required by the schema and nothing checks a reply against it on the way back,
+ * so an absent one is the model being terse rather than the stage claiming a
+ * tool it never had — it settles to `knowledge`, which is the floor anyway, and
+ * is not reported as a correction nobody made.
+ */
+export function compare(questions, answers, floor = DEFAULT_FLOOR, settledBy = SETTLED_WITHOUT_TOOLS) {
+    const replies = new Map(answers.answers.map((a) => [a.id, a]));
+    const asked = new Set(questions.questions.map((q) => q.id));
+    const checked = [];
+    const unanswered = [];
+    const overclaimed = [];
+    for (const question of questions.questions) {
+        const reply = replies.get(question.id);
+        if (!reply) {
+            unanswered.push(question.id);
+            continue;
+        }
+        const claimed = reply.checked_by;
+        const overclaiming = !!claimed && !settledBy.has(claimed);
+        if (overclaiming)
+            overclaimed.push(question.id);
+        checked.push({
+            id: question.id,
+            claim: question.claim_it_tests,
+            claim_type: question.claim_type,
+            question: question.question,
+            answer: reply.answer,
+            confidence: reply.confidence,
+            unknown: reply.unknown,
+            as_of: reply.unknown ? null : reply.as_of,
+            checked_by: overclaiming || !claimed ? "knowledge" : claimed,
+            ...(overclaiming ? { claimed_by: claimed } : {}),
+            settled: !reply.unknown && reply.confidence >= floor,
+        });
+    }
+    return {
+        checked,
+        unanswered,
+        unasked: answers.answers.filter((a) => !asked.has(a.id)).map((a) => a.id),
+        unsettled: checked.filter((c) => !c.settled).map((c) => c.claim),
+        unverifiable: questions.unverifiable_claims,
+        overclaimed,
+    };
+}
+const line = (c) => `${c.id}. ${c.claim}\n   asked: ${c.question}\n   found: ${c.unknown ? "nothing" : c.answer} (${c.settled ? "settled" : "unsettled"}, confidence ${c.confidence})${c.as_of ? `\n   as of: ${c.as_of}` : ""}`;
+/** The verification as a stage reads it. */
+export function render(verification) {
+    const parts = [
+        `<checks>\n${verification.checked.length
+            ? verification.checked.map(line).join("\n\n")
+            : "Nothing was checked."}\n</checks>`,
+    ];
+    if (verification.unsettled.length) {
+        parts.push(`<unsettled>\n${verification.unsettled.join("\n")}\n</unsettled>`);
+    }
+    if (verification.unverifiable.length) {
+        parts.push(`<unverifiable>\n${verification.unverifiable.join("\n")}\n</unverifiable>`);
+    }
+    if (verification.overclaimed.length) {
+        parts.push(`<overclaimed>\nrecorded as knowledge — the check had no tool to use: ${verification.overclaimed.join(", ")}\n</overclaimed>`);
+    }
+    if (verification.unanswered.length || verification.unasked.length) {
+        parts.push(`<mismatched>\nnever answered: ${verification.unanswered.join(", ") || "none"}\nnever asked: ${verification.unasked.join(", ") || "none"}\n</mismatched>`);
+    }
+    return parts.join("\n\n");
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@spendgraph/workflows",
+  "version": "0.2.0",
+  "description": "Ready-made workflows assembled from the spendgraph packages.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnLog0/spendgraph.git",
+    "directory": "packages/workflows"
+  },
+  "homepage": "https://github.com/fnLog0/spendgraph#readme",
+  "bugs": {
+    "url": "https://github.com/fnLog0/spendgraph/issues"
+  },
+  "keywords": [
+    "llm",
+    "agent",
+    "workflow",
+    "orchestration"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@spendgraph/harness": "^0.2.0",
+    "@spendgraph/llms": "^0.2.0",
+    "@spendgraph/prompt": "^0.2.0",
+    "@spendgraph/tools": "^0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prebuild": "npm run build --workspace @spendgraph/harness --workspace @spendgraph/llms --workspace @spendgraph/prompt --workspace @spendgraph/tools",
+    "test": "vitest run",
+    "eval": "vitest run --config evals/vitest.config.mts",
+    "eval:typecheck": "tsc -p evals/tsconfig.json"
+  },
+  "devDependencies": {
+    "@locusgraph/client": "^0.8.1",
+    "@spendgraph/evals": "^0.2.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}