@wrenautomation/raven 0.9.0 → 0.11.0

package/README.md

@@ -12,11 +12,18 @@ 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 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. On the last round of the budget the edge is `stop` whatever the model says; its why says what the ask still lacks |
+| `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. The budget is shown, never enforced here: the runner parks past it |
 
 Ask kinds: `web`, `video`, `channel`, `person`, `site`. Each has a default plan file
-(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.
+(prompts, sources, budget, `age`: one sentence on how much a source's age counts, and `tree`: the
+facets a round's query tree covers and `thin`, the new hits under which a try falls through to the
+next). Copy one,
+tune it, keep it beside your ledger (`weaver learn`): that is where a run learns. Raven never
+loops; the runner takes the edge.
+
+Raven is the runner's planner. An agent that drives weaver's commands (`skills/birdwatch`) does
+raven's three decisions itself and uses raven for its types (`Ask`, `Plan`, `PlanFile`, the
+records), the merge of proposals, and the renderers.
 
 ## CLI
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { fill } from "./model.js";
 export { mergeProposals, type PlanInput, plan, propose, proposePrompt } from "./plan.js";
-export { defaultPlanFile, PLAN_KINDS } from "./plans/index.js";
+export { ageOf, defaultPlanFile, PLAN_KINDS, TREE, treeOf } from "./plans/index.js";
 export { renderHits, renderYield } from "./render.js";
 export { review, reviewPrompt } from "./review.js";
 export { dedupeHits, triage, triagePrompt } from "./triage.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { fill } from "./model.js";
 export { mergeProposals, plan, propose, proposePrompt } from "./plan.js";
-export { defaultPlanFile, PLAN_KINDS } from "./plans/index.js";
+export { ageOf, defaultPlanFile, PLAN_KINDS, TREE, treeOf } from "./plans/index.js";
 export { renderHits, renderYield } from "./render.js";
 export { review, reviewPrompt } from "./review.js";
 export { dedupeHits, triage, triagePrompt } from "./triage.js";

package/dist/plans/index.d.ts

@@ -2,9 +2,16 @@
  * The default plan file per ask kind. A copy of one, tuned and stored beside a ledger, is how
  * a run learns: the recipe changes, raven does not. `raven plans <kind>` prints one to start from.
  */
-import { type AskKind, type PlanFile } from "../types.js";
+import { type AskKind, type PlanFile, type TreeGuide } from "../types.js";
+/**
+ * The five sides a researcher covers before the reads start. One tree per round; the agent
+ * fills each facet with tries, in order of what it expects to work.
+ */
+export declare const TREE: TreeGuide;
 /** 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. */
+/** The plan file's word on age; a stored file from before version 4 takes its kind's default. Version 5: the review no longer says "at most". Version 6: `tree`, the query tree's guide. */
 export declare const ageOf: (planFile: PlanFile) => string | undefined;
+/** The plan file's guide for a query tree; a stored file from before version 6 takes its kind's default. */
+export declare const treeOf: (planFile: PlanFile) => TreeGuide;
 export declare const PLAN_KINDS: AskKind[];

package/dist/plans/index.js

@@ -2,7 +2,7 @@
  * The default plan file per ask kind. A copy of one, tuned and stored beside a ledger, is how
  * a run learns: the recipe changes, raven does not. `raven plans <kind>` prints one to start from.
  */
-import { PlanFile as PlanFileShape } from "../types.js";
+import { PlanFile as PlanFileShape, } from "../types.js";
 const SHAPE_QUERIES = `Return ONLY a JSON object, no prose, exactly this shape:
 {"queries": [{"terms": "...", "why": "..."}]}`;
 const SHAPE_HITS = `Return ONLY a JSON object, no prose, exactly this shape:
@@ -33,7 +33,7 @@ Rules:
 - "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}.
+{steer}Round {round}; the budget is {rounds} rounds, a guard rail (past it the runner parks and a person decides), not a stop rule. Hits {hits}, reads {reads}, findings proposed {proposed}, kept {kept}.
 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):
@@ -44,10 +44,27 @@ Checked (a sample of the kept findings, each against its document):
 {checks}
 Notes:
 {notes}`;
+/**
+ * The five sides a researcher covers before the reads start. One tree per round; the agent
+ * fills each facet with tries, in order of what it expects to work.
+ */
+export const TREE = {
+    facets: [
+        { name: "number", why: "a figure: a rate, a price, a count, a date" },
+        { name: "how", why: "how it is done: a method, a step list, a tool" },
+        { name: "who", why: "who does it or buys it, in their own words" },
+        { name: "counter", why: "the case against: what fails, who says no" },
+        {
+            name: "primary",
+            why: "the source itself: a study, a filing, a transcript, the maker's own page",
+        },
+    ],
+    thin: 3,
+};
 const web = {
     id: "raven/web",
     kind: "web",
-    version: 4,
+    version: 6,
     propose: `You plan web searches for one research ask.
 
 ${SHAPE_QUERIES}
@@ -74,12 +91,13 @@ Hits:
     review: REVIEW,
     sources: ["searxng", "exa", "google"],
     budget: { queries: 3, reads: 6, rounds: 3, checks: 3 },
+    tree: TREE,
     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: 4,
+    version: 6,
     propose: `You plan video searches for one research ask: talks, walkthroughs, interviews and reviews on YouTube and podcast feeds.
 
 ${SHAPE_QUERIES}
@@ -106,12 +124,13 @@ Hits:
     review: REVIEW,
     sources: ["youtube", "podcasts"],
     budget: { queries: 3, reads: 4, rounds: 2, checks: 3 },
+    tree: TREE,
     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: 4,
+    version: 6,
     propose: `You plan searches that find the people and channels worth following for one research ask: creators, newsletters, podcasts, forums.
 
 ${SHAPE_QUERIES}
@@ -136,12 +155,13 @@ Hits:
     review: REVIEW,
     sources: ["searxng", "youtube", "exa"],
     budget: { queries: 3, reads: 6, rounds: 2, checks: 3 },
+    tree: TREE,
     age: "A channel that has not posted in the last year counts for little.",
 };
 const person = {
     id: "raven/person",
     kind: "person",
-    version: 4,
+    version: 6,
     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}
@@ -168,12 +188,13 @@ Hits:
     review: REVIEW,
     sources: ["searxng", "exa", "linkedin", "google"],
     budget: { queries: 4, reads: 6, rounds: 2, checks: 3 },
+    tree: TREE,
     age: "What they do now: prefer the latest pages. Their history can be old.",
 };
 const site = {
     id: "raven/site",
     kind: "site",
-    version: 4,
+    version: 6,
     propose: `You plan searches inside one website for one research ask. Every query runs on {site} only.
 
 ${SHAPE_QUERIES}
@@ -199,6 +220,7 @@ Hits:
     review: REVIEW,
     sources: ["sitemap", "searxng", "fetch"],
     budget: { queries: 4, reads: 8, rounds: 2, checks: 3 },
+    tree: TREE,
     age: "When two pages of the site disagree, the later one counts.",
 };
 const DEFAULTS = { web, video, channel, person, site };
@@ -206,7 +228,9 @@ const DEFAULTS = { web, video, channel, person, site };
 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. */
+/** The plan file's word on age; a stored file from before version 4 takes its kind's default. Version 5: the review no longer says "at most". Version 6: `tree`, the query tree's guide. */
 export const ageOf = (planFile) => planFile.age ?? DEFAULTS[planFile.kind].age;
+/** The plan file's guide for a query tree; a stored file from before version 6 takes its kind's default. */
+export const treeOf = (planFile) => planFile.tree ?? DEFAULTS[planFile.kind].tree;
 export const PLAN_KINDS = Object.keys(DEFAULTS);
 //# sourceMappingURL=index.js.map

package/dist/review.d.ts

@@ -1,8 +1,7 @@
 /**
- * After a round: stop, go again from plan, or back to one step. The round budget is a guard
- * rail, not a stop rule: before it is spent the model decides and says why. On the last round
- * the model still reads the round, so its why says what the ask still lacks, but the edge is
- * stop whatever it answers. The runner takes the edge; raven never loops.
+ * After a round: stop, go again from plan, or back to one step. The model decides and says why;
+ * the round budget is a guard rail it sees (`{round}` of `{rounds}`), never a stop rule. The
+ * runner takes the edge and parks past the budget; raven never loops.
  */
 import type { Model } from "@wrenautomation/models";
 import { type Edge, type PlanFile, type Round } from "./types.js";

package/dist/review.js

@@ -26,20 +26,9 @@ export function reviewPrompt(round, planFile) {
         verdicts: lines(round.verdicts.map(verdictLine), "(none)"),
     });
 }
-/** Told to the model on the last round: its answer cannot be again or back. */
-const LAST = "This is the last round: the run stops whatever you answer. Answer stop, and in why say what the ask still lacks, or that it is answered.";
 export async function review(round, model, options = {}) {
     const planFile = options.planFile ?? defaultPlanFile(round.ask.kind);
-    const last = round.round >= round.budget.rounds;
-    const shown = last ? { ...round, notes: [...round.notes, LAST] } : round;
-    const { value: out } = await model.ask(reviewPrompt(shown, planFile), EdgeAnswer);
-    if (last)
-        return {
-            next: "stop",
-            why: `round budget spent (${round.round} of ${round.budget.rounds}): ${out.why}`,
-            from: "ai",
-            by: model.id,
-        };
+    const { value: out } = await model.ask(reviewPrompt(round, planFile), EdgeAnswer);
     const edge = { next: out.next, why: out.why, from: "ai", by: model.id };
     if (out.next === "back")
         edge.to = out.to ?? "fetch";

package/dist/types.d.ts

@@ -47,6 +47,8 @@ export declare const Query: z.ZodObject<{
     terms: z.ZodString;
     site: z.ZodOptional<z.ZodString>;
     why: z.ZodString;
+    facet: z.ZodOptional<z.ZodString>;
+    tier: z.ZodOptional<z.ZodNumber>;
     from: z.ZodEnum<{
         ai: "ai";
         human: "human";
@@ -72,9 +74,55 @@ export declare const Proposal: z.ZodObject<{
         }>;
         terms: z.ZodString;
         why: z.ZodString;
+        facet: z.ZodOptional<z.ZodString>;
+        tier: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Proposal = z.infer<typeof Proposal>;
+/** One query as a leaf of the tree: what a person would type, and why. */
+export declare const Leaf: z.ZodObject<{
+    terms: z.ZodString;
+    why: z.ZodString;
+    site: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Leaf = z.infer<typeof Leaf>;
+/**
+ * One side of the ask a researcher covers: a number, a how, a who, a counter-view, a primary
+ * source. `tries` are its alternatives in order: the first runs; the next runs only when the
+ * one before it yielded thin (fewer new hits than the guide's `thin`), or when the agent asks.
+ */
+export declare const Facet: z.ZodObject<{
+    name: z.ZodString;
+    why: z.ZodString;
+    tries: z.ZodArray<z.ZodArray<z.ZodObject<{
+        terms: z.ZodString;
+        why: z.ZodString;
+        site: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Facet = z.infer<typeof Facet>;
+/** The fan-out for one round: the facets, each with its tries. The agent writes it; weaver runs it. */
+export declare const QueryTree: z.ZodObject<{
+    facets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        why: z.ZodString;
+        tries: z.ZodArray<z.ZodArray<z.ZodObject<{
+            terms: z.ZodString;
+            why: z.ZodString;
+            site: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type QueryTree = z.infer<typeof QueryTree>;
+/** The plan file's guide for a tree: the facets a tree of this kind covers, and what thin means. A guide, not a cap: a tree may add facets; one it leaves out is a warning. */
+export declare const TreeGuide: z.ZodObject<{
+    facets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        why: z.ZodString;
+    }, z.core.$strip>>;
+    thin: z.ZodNumber;
+}, z.core.$strip>;
+export type TreeGuide = z.infer<typeof TreeGuide>;
 export declare const Budget: z.ZodObject<{
     queries: z.ZodNumber;
     reads: z.ZodNumber;
@@ -109,6 +157,13 @@ export declare const PlanFile: z.ZodObject<{
         checks: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>;
     age: z.ZodOptional<z.ZodString>;
+    tree: z.ZodOptional<z.ZodObject<{
+        facets: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            why: z.ZodString;
+        }, z.core.$strip>>;
+        thin: z.ZodNumber;
+    }, z.core.$strip>>;
 }, 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. */
@@ -168,6 +223,8 @@ export declare const Plan: z.ZodObject<{
         terms: z.ZodString;
         site: z.ZodOptional<z.ZodString>;
         why: z.ZodString;
+        facet: z.ZodOptional<z.ZodString>;
+        tier: z.ZodOptional<z.ZodNumber>;
         from: z.ZodEnum<{
             ai: "ai";
             human: "human";
@@ -221,8 +278,8 @@ export type Triage = z.infer<typeof Triage>;
 export declare const Verdict: z.ZodObject<{
     url: z.ZodString;
     quality: z.ZodEnum<{
-        rich: "rich";
         thin: "thin";
+        rich: "rich";
         off: "off";
         empty: "empty";
     }>;
@@ -261,8 +318,8 @@ export declare const Round: z.ZodObject<{
     verdicts: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         quality: z.ZodEnum<{
-            rich: "rich";
             thin: "thin";
+            rich: "rich";
             off: "off";
             empty: "empty";
         }>;

package/dist/types.js

@@ -28,6 +28,9 @@ export const Query = z.object({
     site: z.string().optional(),
     /** Why this query serves the ask: the line a reviewer reads first. */
     why: z.string(),
+    /** The tree's facet it serves, and which try (1 = the first). Absent on a flat query. */
+    facet: z.string().optional(),
+    tier: z.number().int().positive().optional(),
     from: From,
     /** Model id, plan file id or a person's name. */
     by: z.string(),
@@ -38,6 +41,31 @@ export const Proposal = z.object({
     by: z.string(),
     queries: z.array(Query.omit({ from: true, by: true })),
 });
+/** One query as a leaf of the tree: what a person would type, and why. */
+export const Leaf = z.object({
+    terms: z.string().min(1),
+    why: z.string(),
+    site: z.string().optional(),
+});
+/**
+ * One side of the ask a researcher covers: a number, a how, a who, a counter-view, a primary
+ * source. `tries` are its alternatives in order: the first runs; the next runs only when the
+ * one before it yielded thin (fewer new hits than the guide's `thin`), or when the agent asks.
+ */
+export const Facet = z.object({
+    name: z.string().min(1),
+    /** What this facet would prove. */
+    why: z.string(),
+    tries: z.array(z.array(Leaf).min(1)).min(1),
+});
+/** The fan-out for one round: the facets, each with its tries. The agent writes it; weaver runs it. */
+export const QueryTree = z.object({ facets: z.array(Facet).min(1) });
+/** The plan file's guide for a tree: the facets a tree of this kind covers, and what thin means. A guide, not a cap: a tree may add facets; one it leaves out is a warning. */
+export const TreeGuide = z.object({
+    facets: z.array(z.object({ name: z.string().min(1), why: z.string() })),
+    /** New hits under which a try counts as thin, so the next try runs. */
+    thin: z.number().int().nonnegative(),
+});
 export const Budget = z.object({
     /** Queries per round after the merge. Human queries never count against it. */
     queries: z.number().int().positive(),
@@ -69,6 +97,8 @@ export const PlanFile = z.object({
     budget: Budget,
     /** How much a source's age counts for this kind, one sentence: filled as `{age}`. Never a cutoff. */
     age: z.string().optional(),
+    /** The facets a query tree of this kind covers. Absent on a file from before version 6: the kind's default. */
+    tree: TreeGuide.optional(),
 });
 /** What a source, channel or proposer yielded before. Raven reads it; wren or the files ledger writes it. */
 export const YieldRow = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrenautomation/raven",
-  "version": "0.9.0",
+  "version": "0.11.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-Strict-1.0.0",
   "repository": {
@@ -32,7 +32,7 @@
   "dependencies": {
     "commander": "15.0.0",
     "zod": "4.6.5",
-    "@wrenautomation/models": "0.9.0"
+    "@wrenautomation/models": "0.11.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",