@wrenautomation/raven 0.7.0 → 0.8.0

package/README.md

@@ -12,10 +12,10 @@ Three calls, one record each:
 |---|---|---|
 | `plan` | an ask (text, kind, what is known, what the person says: `steer`, rendered first in every prompt), proposals from people or other models, yield rows from earlier runs | a `Plan`: typed queries, each with `why`, `from` (ai or human) and `by` (model id, plan file or person), the sources it may use, the budget, and a snapshot of what raven was given |
 | `triage` | hits as a source shows them for free (title, channel, length, date, snippet, which sources returned it) | read or skip per hit; the model writes a why on a read only (a skip's is fixed text); the read budget caps it |
-| `review` | what a round came to (counts, found lines, the extractor's verdict and gap per read, notes) | the edge: `stop`, `again` (a new round from plan) or `back` (rerun one step), with why |
+| `review` | what a round came to (counts, found lines with their dates, the extractor's verdict and gap per read, the steps' gaps, the sample check, notes) | the edge: `stop`, `again` (a new round from plan) or `back` (rerun one step), with why |
 
 Ask kinds: `web`, `video`, `channel`, `person`, `site`. Each has a default plan file
-(prompts, sources, budget). Copy one, tune it, keep it beside your ledger: that is where a run
+(prompts, sources, budget, and `age`: one sentence on how much a source's age counts). Copy one, tune it, keep it beside your ledger: that is where a run
 learns. Raven never loops; the runner takes the edge.
 
 ## CLI

package/dist/app/cli.js

@@ -60,6 +60,7 @@ withModel(program
         kind,
         known: o.known,
         steer: o.steer,
+        open: [],
         ...(o.site ? { site: o.site } : {}),
     };
     const proposals = o.propose.length

package/dist/plan.js

@@ -1,6 +1,6 @@
 import { fill } from "./model.js";
 import { defaultPlanFile } from "./plans/index.js";
-import { lines, renderSteer, renderYield } from "./render.js";
+import { lines, renderOpen, renderSteer, renderYield } from "./render.js";
 import { z, } from "./types.js";
 const ProposalAnswer = z.object({
     queries: z.array(z.object({ terms: z.string(), why: z.string(), site: z.string().optional() })),
@@ -12,6 +12,7 @@ export function proposePrompt(ask, planFile, yieldRows, now) {
         ask: ask.text,
         site: ask.site ?? "",
         steer: renderSteer(ask.steer),
+        open: renderOpen(ask.open),
         known: lines(ask.known),
         yield: renderYield(yieldRows),
     });

package/dist/plans/index.d.ts

@@ -5,4 +5,6 @@
 import { type AskKind, type PlanFile } from "../types.js";
 /** The default plan file for a kind, validated, as a fresh copy. */
 export declare function defaultPlanFile(kind: AskKind): PlanFile;
+/** The plan file's word on age; a stored file from before version 4 takes its kind's default. */
+export declare const ageOf: (planFile: PlanFile) => string | undefined;
 export declare const PLAN_KINDS: AskKind[];

package/dist/plans/index.js

@@ -11,14 +11,14 @@ const SHAPE_EDGE = `Return ONLY a JSON object, no prose, exactly this shape:
 {"next": "stop", "why": "..."}
 where "next" is "stop", "again" (a new round from plan) or "back" (rerun one step of this round, named in "to": "plan", "fetch", "triage", "read" or "extract").`;
 const CONTEXT = `Ask: {ask}
-{steer}Known already (look past these):
+{steer}{open}Known already (look past these):
 {known}
 What yielded before (hits, reads, proposed, kept):
 {yield}`;
 const TRIAGE_RULES = `- One entry per hit, with its url as given. Mark "read": true for at most {n}.
 - Read a hit when what it shows for free (title, snippet, channel, length, date) says it holds what the ask needs and is not known already.
 - A hit returned by more than one source is a good sign, not a duplicate.
-- "why" on a read only: one short line a person reads to agree or not. A skip has no "why".`;
+- "why" on a read only: one short line a person reads to agree or not. A skip has no "why".{age}`;
 const REVIEW = `You decide what happens after one round of research.
 
 ${SHAPE_EDGE}
@@ -28,20 +28,26 @@ Rules:
 - "again" when the ask is still open and new queries could find more. The gaps say what is missing; say what to look for next in "why".
 - "again" too when the reads were mostly "thin" or "off": the queries found the wrong pages, so plan different ones.
 - "back" when one step of this round failed for a reason a rerun fixes (a source was down, reads timed out). Name the step in "to".
-- "why" is one short line a person reads to agree or not.
+- The gaps are what a step or the person said this round lacks: a query with no new hits, a page no source could open. Weigh them like the verdicts.
+- A check that failed means a finding's quote does not back it, and the finding was dropped. Many failed checks mean the reads were poor: say so in "why".{age}
+- "why" is one short line a person reads to agree or not. On "again" it is what the next plan reads first.
 
 Ask: {ask}
 {steer}Round {round} of at most {rounds}. Hits {hits}, reads {reads}, findings proposed {proposed}, kept {kept}.
-Found:
+Found (the source's date in brackets when it gives one):
 {found}
 Read (quality: rich, thin, off or empty; then the gap, what the ask still lacks):
 {verdicts}
+Gaps (the step or the person, then what is missing):
+{gaps}
+Checked (a sample of the kept findings, each against its document):
+{checks}
 Notes:
 {notes}`;
 const web = {
     id: "raven/web",
     kind: "web",
-    version: 3,
+    version: 4,
     propose: `You plan web searches for one research ask.
 
 ${SHAPE_QUERIES}
@@ -67,12 +73,13 @@ Hits:
 {hits}`,
     review: REVIEW,
     sources: ["searxng", "exa", "google"],
-    budget: { queries: 3, reads: 6, rounds: 3 },
+    budget: { queries: 3, reads: 6, rounds: 3, checks: 3 },
+    age: "Prices, tools and numbers that move: prefer the last two years. A principle or a method can be old.",
 };
 const video = {
     id: "raven/video",
     kind: "video",
-    version: 3,
+    version: 4,
     propose: `You plan video searches for one research ask: talks, walkthroughs, interviews and reviews on YouTube and podcast feeds.
 
 ${SHAPE_QUERIES}
@@ -98,12 +105,13 @@ Hits:
 {hits}`,
     review: REVIEW,
     sources: ["youtube", "podcasts"],
-    budget: { queries: 3, reads: 4, rounds: 2 },
+    budget: { queries: 3, reads: 4, rounds: 2, checks: 3 },
+    age: "Tools and platforms: prefer the last two years. A talk on a principle can be old.",
 };
 const channel = {
     id: "raven/channel",
     kind: "channel",
-    version: 3,
+    version: 4,
     propose: `You plan searches that find the people and channels worth following for one research ask: creators, newsletters, podcasts, forums.
 
 ${SHAPE_QUERIES}
@@ -127,12 +135,13 @@ Hits:
 {hits}`,
     review: REVIEW,
     sources: ["searxng", "youtube", "exa"],
-    budget: { queries: 3, reads: 6, rounds: 2 },
+    budget: { queries: 3, reads: 6, rounds: 2, checks: 3 },
+    age: "A channel that has not posted in the last year counts for little.",
 };
 const person = {
     id: "raven/person",
     kind: "person",
-    version: 3,
+    version: 4,
     propose: `You plan searches about one person or company for one research ask: what they do, what they said, what others say about them.
 
 ${SHAPE_QUERIES}
@@ -158,12 +167,13 @@ Hits:
 {hits}`,
     review: REVIEW,
     sources: ["searxng", "exa", "linkedin", "google"],
-    budget: { queries: 4, reads: 6, rounds: 2 },
+    budget: { queries: 4, reads: 6, rounds: 2, checks: 3 },
+    age: "What they do now: prefer the latest pages. Their history can be old.",
 };
 const site = {
     id: "raven/site",
     kind: "site",
-    version: 3,
+    version: 4,
     propose: `You plan searches inside one website for one research ask. Every query runs on {site} only.
 
 ${SHAPE_QUERIES}
@@ -188,12 +198,15 @@ Hits:
 {hits}`,
     review: REVIEW,
     sources: ["sitemap", "searxng", "fetch"],
-    budget: { queries: 4, reads: 8, rounds: 2 },
+    budget: { queries: 4, reads: 8, rounds: 2, checks: 3 },
+    age: "When two pages of the site disagree, the later one counts.",
 };
 const DEFAULTS = { web, video, channel, person, site };
 /** The default plan file for a kind, validated, as a fresh copy. */
 export function defaultPlanFile(kind) {
     return PlanFileShape.parse(structuredClone(DEFAULTS[kind]));
 }
+/** The plan file's word on age; a stored file from before version 4 takes its kind's default. */
+export const ageOf = (planFile) => planFile.age ?? DEFAULTS[planFile.kind].age;
 export const PLAN_KINDS = Object.keys(DEFAULTS);
 //# sourceMappingURL=index.js.map

package/dist/render.d.ts

@@ -3,6 +3,10 @@ import type { HitView, YieldRow } from "./types.js";
 export declare const lines: (xs: readonly string[], none?: string) => string;
 /** "The person says:" and their lines, or nothing: a prompt pays for the heading only when there is one. */
 export declare const renderSteer: (steer: readonly string[] | undefined) => string;
+/** What the last round left open, under its heading, or nothing. */
+export declare const renderOpen: (open: readonly string[] | undefined) => string;
+/** The plan file's word on age as one more rule line, or nothing. */
+export declare const renderAge: (age: string | undefined) => string;
 /** One line per row, the keys it has first: `source=exa channel=... hits=12 reads=4 proposed=9 kept=3`. */
 export declare function renderYield(rows: readonly YieldRow[]): string;
 /** Numbered, one hit per line, only the fields it has. */

package/dist/render.js

@@ -1,6 +1,10 @@
 export const lines = (xs, none = "(nothing)") => xs.length ? xs.map((x) => `- ${x}`).join("\n") : none;
 /** "The person says:" and their lines, or nothing: a prompt pays for the heading only when there is one. */
 export const renderSteer = (steer) => steer?.length ? `The person says:\n${lines(steer)}\n` : "";
+/** What the last round left open, under its heading, or nothing. */
+export const renderOpen = (open) => open?.length ? `The last round left open (plan for these first):\n${lines(open)}\n` : "";
+/** The plan file's word on age as one more rule line, or nothing. */
+export const renderAge = (age) => (age ? `\n- Age: ${age}` : "");
 /** One line per row, the keys it has first: `source=exa channel=... hits=12 reads=4 proposed=9 kept=3`. */
 export function renderYield(rows) {
     if (!rows.length)

package/dist/review.js

@@ -1,6 +1,6 @@
 import { fill } from "./model.js";
-import { defaultPlanFile } from "./plans/index.js";
-import { lines, renderSteer } from "./render.js";
+import { ageOf, defaultPlanFile } from "./plans/index.js";
+import { lines, renderAge, renderSteer } from "./render.js";
 import { Step, z } from "./types.js";
 const EdgeAnswer = z.object({
     next: z.enum(["stop", "again", "back"]),
@@ -20,6 +20,9 @@ export function reviewPrompt(round, planFile) {
         kept: String(round.kept),
         found: lines(round.found),
         notes: lines(round.notes, "(none)"),
+        gaps: lines(round.gaps, "(none)"),
+        checks: lines(round.checks, "(none)"),
+        age: renderAge(ageOf(planFile)),
         verdicts: lines(round.verdicts.map(verdictLine), "(none)"),
     });
 }

package/dist/triage.js

@@ -1,6 +1,6 @@
 import { fill } from "./model.js";
-import { defaultPlanFile } from "./plans/index.js";
-import { lines, renderHits, renderSteer, renderYield } from "./render.js";
+import { ageOf, defaultPlanFile } from "./plans/index.js";
+import { lines, renderAge, renderHits, renderOpen, renderSteer, renderYield } from "./render.js";
 import { HitView, z, } from "./types.js";
 const TriageAnswer = z.object({
     hits: z.array(z.object({ url: z.string(), read: z.boolean(), why: z.string().nullable().optional() })),
@@ -33,6 +33,8 @@ export function triagePrompt(hits, plan, planFile, yieldRows) {
         ask: plan.ask.text,
         site: plan.ask.site ?? "",
         steer: renderSteer(plan.ask.steer),
+        open: renderOpen(plan.ask.open),
+        age: renderAge(ageOf(planFile)),
         known: lines(plan.ask.known),
         yield: renderYield(yieldRows),
         hits: renderHits(hits),

package/dist/types.d.ts

@@ -31,6 +31,7 @@ export declare const Ask: z.ZodObject<{
     }>;
     known: z.ZodDefault<z.ZodArray<z.ZodString>>;
     steer: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    open: z.ZodDefault<z.ZodArray<z.ZodString>>;
     site: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Ask = z.infer<typeof Ask>;
@@ -78,12 +79,14 @@ export declare const Budget: z.ZodObject<{
     queries: z.ZodNumber;
     reads: z.ZodNumber;
     rounds: z.ZodNumber;
+    checks: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type Budget = z.infer<typeof Budget>;
 /**
  * The recipe for one ask kind: the prompts, the sources it may use, the budget. Versioned and
  * tuned like an SOP, stored beside the ledger. `{name}` marks in a prompt are filled from the
- * ask: `{ask}`, `{known}`, `{yield}`, `{n}`, `{year}`, `{site}`.
+ * ask: `{ask}`, `{known}`, `{yield}`, `{n}`, `{year}`, `{site}`, `{open}`, `{age}`; the review's
+ * also `{gaps}` and `{checks}`.
  */
 export declare const PlanFile: z.ZodObject<{
     id: z.ZodString;
@@ -103,7 +106,9 @@ export declare const PlanFile: z.ZodObject<{
         queries: z.ZodNumber;
         reads: z.ZodNumber;
         rounds: z.ZodNumber;
+        checks: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>;
+    age: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PlanFile = z.infer<typeof PlanFile>;
 /** What a source, channel or proposer yielded before. Raven reads it; wren or the files ledger writes it. */
@@ -148,6 +153,7 @@ export declare const Plan: z.ZodObject<{
         }>;
         known: z.ZodDefault<z.ZodArray<z.ZodString>>;
         steer: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        open: z.ZodDefault<z.ZodArray<z.ZodString>>;
         site: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     round: z.ZodNumber;
@@ -173,6 +179,7 @@ export declare const Plan: z.ZodObject<{
         queries: z.ZodNumber;
         reads: z.ZodNumber;
         rounds: z.ZodNumber;
+        checks: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>;
     snapshot: z.ZodObject<{
         at: z.ZodString;
@@ -235,6 +242,7 @@ export declare const Round: z.ZodObject<{
         }>;
         known: z.ZodDefault<z.ZodArray<z.ZodString>>;
         steer: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        open: z.ZodDefault<z.ZodArray<z.ZodString>>;
         site: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     round: z.ZodNumber;
@@ -242,6 +250,7 @@ export declare const Round: z.ZodObject<{
         queries: z.ZodNumber;
         reads: z.ZodNumber;
         rounds: z.ZodNumber;
+        checks: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>;
     hits: z.ZodNumber;
     reads: z.ZodNumber;
@@ -259,6 +268,8 @@ export declare const Round: z.ZodObject<{
         }>;
         gap: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    gaps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type Round = z.infer<typeof Round>;
 export declare const Step: z.ZodEnum<{

package/dist/types.js

@@ -16,6 +16,8 @@ export const Ask = z.object({
     known: z.array(z.string()).default([]),
     /** What the person said along the way, one line each: every prompt renders it first. */
     steer: z.array(z.string()).default([]),
+    /** What the last round left open, one line each: its review's why, its gaps. The planner looks there first. */
+    open: z.array(z.string()).default([]),
     /** Only for kind `site`, or when a query must stay on one host. */
     site: z.string().optional(),
 });
@@ -43,11 +45,14 @@ export const Budget = z.object({
     reads: z.number().int().positive(),
     /** Rounds before `review` must stop. */
     rounds: z.number().int().positive(),
+    /** Kept findings per round that a model checks against their document: a sample spread across the documents. 0: none. */
+    checks: z.number().int().nonnegative().default(3),
 });
 /**
  * The recipe for one ask kind: the prompts, the sources it may use, the budget. Versioned and
  * tuned like an SOP, stored beside the ledger. `{name}` marks in a prompt are filled from the
- * ask: `{ask}`, `{known}`, `{yield}`, `{n}`, `{year}`, `{site}`.
+ * ask: `{ask}`, `{known}`, `{yield}`, `{n}`, `{year}`, `{site}`, `{open}`, `{age}`; the review's
+ * also `{gaps}` and `{checks}`.
  */
 export const PlanFile = z.object({
     id: z.string().min(1),
@@ -62,6 +67,8 @@ export const PlanFile = z.object({
     /** Source names a run may use, in order of preference. A run can narrow the list, never widen it. */
     sources: z.array(z.string()),
     budget: Budget,
+    /** How much a source's age counts for this kind, one sentence: filled as `{age}`. Never a cutoff. */
+    age: z.string().optional(),
 });
 /** What a source, channel or proposer yielded before. Raven reads it; wren or the files ledger writes it. */
 export const YieldRow = z.object({
@@ -131,6 +138,10 @@ export const Round = z.object({
     notes: z.array(z.string()).default([]),
     /** The extractor's verdict on each document read this round: the planner sees what the reads were worth. */
     verdicts: z.array(Verdict).default([]),
+    /** What a step or a person said the round lacks, one line each, the step or the person first. */
+    gaps: z.array(z.string()).default([]),
+    /** The sample check: whether each checked finding's quote backs it, one line each. */
+    checks: z.array(z.string()).default([]),
 });
 export const Step = z.enum(["plan", "fetch", "triage", "read", "extract"]);
 /** The edge out of a round. `again` is a new round from `plan`; `back` reruns one step of this round. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrenautomation/raven",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Ask in, plan out. The planner of Wren's research engine: typed queries with who proposed them and why, proposals merged into one plan under a plan file per ask kind, read-or-skip on hits, and the edge to take after a round. Pure functions and prompts; the model is injected.",
   "license": "PolyForm-Shield-1.0.0",
   "repository": {
@@ -32,7 +32,7 @@
   "dependencies": {
     "commander": "15.0.0",
     "zod": "4.6.5",
-    "@wrenautomation/models": "0.7.0"
+    "@wrenautomation/models": "0.8.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",