@andrueandersoncs/lint-anything 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,11 @@
1
1
  import { Cause, Context, Effect, Layer, Redacted, Result, Runtime, Schema } from "effect";
2
+ import { type MediaKind } from "./media.ts";
2
3
  /**
3
4
  * One yes/no question: `instructions` is what the decision model judges, and `criteria` say what a yes
4
- * (`true`) and a no (`false`) mean. The model answers with the probability of yes.
5
+ * (`true`) and a no (`false`) mean. The model answers with the probability of yes. `media` lists image,
6
+ * audio, and video files the model is shown with it, by path from the current directory (types by
7
+ * extension, `media.ts`); a request shows its media for every question in it, so only questions with the
8
+ * same media share one.
5
9
  */
6
10
  export interface Question {
7
11
  readonly instructions: string;
@@ -9,6 +13,7 @@ export interface Question {
9
13
  readonly true: string;
10
14
  readonly false: string;
11
15
  };
16
+ readonly media?: ReadonlyArray<string>;
12
17
  }
13
18
  declare const DecisionModelError_base: Schema.Class<DecisionModelError, Schema.TaggedStruct<"DecisionModelError", {
14
19
  readonly message: Schema.String;
@@ -44,13 +49,18 @@ export declare const cacheMaxAgeMs: number;
44
49
  * - `system-one`: the System One API (`POST /v1/systemone`) that Jev introduced and Clef, LiteLLM, LLM
45
50
  * Gateway, Ollama, llama.cpp, SGLang, and most decision-model servers speak. A request has a `state` and
46
51
  * `noul` questions keyed by id; each answer is the probability of yes. Workers AI wraps the response in
47
- * `result`, which is read the same way.
52
+ * `result`, which is read the same way. Media go before the state as data URLs, in `images`, `audio`,
53
+ * and `videos`, as Clef, clef-omni, and LiteLLM take them.
48
54
  * - `decisions`: OpenAI's Decisions API (`POST /v1/decisions`). A request has an `input` and a list of
49
- * `predicate` questions; answers come back as a list, each a probability or a refusal.
55
+ * `predicate` questions; answers come back as a list, each a probability or a refusal. With images, the
56
+ * input is one user message: an `input_image` part per image, then the state as `input_text`. It takes
57
+ * no audio or video.
50
58
  * - `gemini`: Google's Decisions API for Gemini Decision (`POST /v1beta/decisions` on
51
59
  * `generativelanguage.googleapis.com`). A request has an `input` and `noul` questions keyed by id, whose
52
60
  * criteria are `true_description` and `false_description`; the key goes in `x-goog-api-key`. A request
53
- * its safety filters block is answered with HTTP 400 instead, which declines every question in it.
61
+ * its safety filters block is answered with HTTP 400 instead, which declines every question in it. With
62
+ * media, the input is a list of content blocks: an `image`, `audio`, or `video` block per file, in base64,
63
+ * then the state as `text`.
54
64
  */
55
65
  export type Format = "system-one" | "decisions" | "gemini";
56
66
  /** A response, read: each question's probability of yes, or `declined`, by id, and the input tokens it reports. */
@@ -79,6 +89,11 @@ export interface Model {
79
89
  readonly cacheKey: string;
80
90
  /** USD per input token, when known. */
81
91
  readonly inputTokenPrice: number | undefined;
92
+ /**
93
+ * The kinds of media it takes, when known; otherwise any its format can carry is sent, and the endpoint
94
+ * says whether it takes them.
95
+ */
96
+ readonly media?: ReadonlyArray<MediaKind> | undefined;
82
97
  }
83
98
  /**
84
99
  * A decision model and how to reach it: the endpoint requests are POSTed to, and the API key or token, if
@@ -123,9 +138,14 @@ export declare const configuredModel: Effect.Effect<Model, DecisionModelError>;
123
138
  * `CLOUDFLARE_AUTH_TOKEN`, and optionally `CLOUDFLARE_API_BASE_URL`.
124
139
  */
125
140
  export declare const configuredTarget: Effect.Effect<Target, DecisionModelError>;
126
- /** One request: its exact body and what each question id answers. */
141
+ /**
142
+ * One request: its exact body, the media its questions show (by path), and what each question id answers.
143
+ * The body of a request with media leaves them out; they are read, and put where its format takes them,
144
+ * when it is sent.
145
+ */
127
146
  export interface Planned<A> {
128
147
  readonly body: string;
148
+ readonly media: ReadonlyArray<string>;
129
149
  readonly questions: ReadonlyArray<{
130
150
  readonly id: string;
131
151
  readonly value: A;
@@ -133,7 +153,9 @@ export interface Planned<A> {
133
153
  }
134
154
  /**
135
155
  * Plans the requests that ask `questions` under `state`: the state once per request and as many questions
136
- * as fit, laid out for `model` (default: Clef). Planned questions answer by index into `questions`.
156
+ * as fit, laid out for `model` (default: Clef). A request shows its media for every question in it, so
157
+ * questions share one only with questions showing the same media; groups are planned in order of their
158
+ * first question. Planned questions answer by index into `questions`.
137
159
  */
138
160
  export declare const planRequests: (state: string, questions: ReadonlyArray<Question>, model?: Pick<Model, "format" | "model">) => {
139
161
  requests: Planned<number>[];
@@ -155,6 +177,15 @@ export interface Usage {
155
177
  }
156
178
  export declare const noUsage: Usage;
157
179
  export declare const sumUsage: (usages: Iterable<Usage>) => Usage;
180
+ /** Configuration for cascading two decision models: a fast primary and a secondary tiebreaker. */
181
+ export interface CascadeOptions {
182
+ /** Primary probabilities below `low` are accepted directly without calling `secondary` (default: 0.15). */
183
+ readonly low?: number;
184
+ /** Primary probabilities above `high` are accepted directly without calling `secondary` (default: 0.85). */
185
+ readonly high?: number;
186
+ /** Combines primary and secondary probabilities for items sent to both (default: arithmetic mean). */
187
+ readonly combine?: (primary: number, secondary: number) => number;
188
+ }
158
189
  declare const DecisionModel_base: Context.ServiceClass<DecisionModel, "lint-anything/DecisionModel", {
159
190
  /** The model asked, and where. */
160
191
  readonly target: Target;
@@ -175,5 +206,11 @@ export declare class DecisionModel extends DecisionModel_base {
175
206
  static readonly layer: (cacheDirectory?: string) => Layer.Layer<DecisionModel, DecisionModelError, never>;
176
207
  /** `target`, whatever the environment says; answers are cached as with `layer`. */
177
208
  static readonly layerFor: (target: Target, cacheDirectory?: string) => Layer.Layer<DecisionModel, DecisionModelError, never>;
209
+ /**
210
+ * Cross-family cascade: asks `primary` first, and asks `secondary` only for questions whose primary
211
+ * probability lands in `[low, high]`, combining both probabilities with `combine` (default: mean).
212
+ * Combines `stats` from both models.
213
+ */
214
+ static readonly cascadeLayer: (primary: Target, secondary: Target, cacheDirectory?: string, options?: CascadeOptions) => Layer.Layer<DecisionModel, DecisionModelError, never>;
178
215
  }
179
216
  export {};
@@ -4,10 +4,12 @@ declare const ItemFields: Schema.Struct<{
4
4
  readonly text: Schema.NonEmptyString;
5
5
  readonly path: Schema.optional<Schema.NonEmptyString>;
6
6
  readonly lines: Schema.optional<Schema.Tuple<readonly [Schema.Int, Schema.Int]>>;
7
+ readonly media: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
7
8
  }>;
8
9
  /**
9
10
  * One thing a selector picked out to judge. `text` is everything the decision model reads for it, context included; `id`
10
- * names it in findings; `path` and `lines` (1-based, inclusive) say where findings point.
11
+ * names it in findings; `path` and `lines` (1-based, inclusive) say where findings point. `media` lists the image, audio,
12
+ * and video files the model is shown with it, by path from where the selector ran.
11
13
  */
12
14
  export type Item = Schema.Schema.Type<typeof ItemFields>;
13
15
  /** Parses one JSONL line into an item; fails with a message saying what is wrong with it. */
@@ -16,5 +18,6 @@ export declare const parseItem: (line: string) => Effect.Effect<{
16
18
  readonly text: string;
17
19
  readonly path?: string | undefined;
18
20
  readonly lines?: readonly [number, number] | undefined;
21
+ readonly media?: readonly string[] | undefined;
19
22
  }, string, never>;
20
23
  export {};
@@ -18,7 +18,7 @@
18
18
  * with the metrics and bootstrap intervals the evals use; the skill's score script is built on it.
19
19
  */
20
20
  import { DecisionModel, DecisionModelError } from "./decision-model.ts";
21
- export { cacheMaxAgeMs, clef, clefInputTokenPrice, configuredModel, configuredTarget, Declined, declinesAll, decodeReply, DecisionModel, DecisionModelError, endpointTarget, type Format, keyHeader, type Model, noUsage, planRequests, type Planned, type Question, RequestTooLarge, sumUsage, type Target, type Unanswered, type Usage, workersAiTarget } from "./decision-model.ts";
21
+ export { cacheMaxAgeMs, type CascadeOptions, clef, clefInputTokenPrice, configuredModel, configuredTarget, Declined, declinesAll, decodeReply, DecisionModel, DecisionModelError, endpointTarget, type Format, keyHeader, type Model, noUsage, planRequests, type Planned, type Question, RequestTooLarge, sumUsage, type Target, type Unanswered, type Usage, workersAiTarget } from "./decision-model.ts";
22
22
  /** @deprecated Renamed `DecisionModel`: it asks whichever decision model is configured, Clef by default. */
23
23
  export declare const Clef: typeof DecisionModel;
24
24
  /** @deprecated Renamed `DecisionModel`. */
@@ -31,4 +31,4 @@ export { type Item, parseItem } from "./item.ts";
31
31
  export { decide, defaultThreshold, type Finding, itemQuestion, judge, lint, reviewFloor, select, type Verdict, verdictOf } from "./lint.ts";
32
32
  export { loadPolicies, parsePolicy, type Policy, PolicyError } from "./policy.ts";
33
33
  export { killRunningSelectors, runSelector, SelectorError, type SelectorRuns, selectorTimeoutMinutes } from "./select.ts";
34
- export { auroc, bootstrapInterval, brier, caught, cliThresholds, concordance, falseAlarms, itemLabel, itemsOf, type Label, LabelError, type LabelRecord, loadLabels, pairedInterval, parseLabels, type PolicyScore, type Quality, quality, type Range, reachedRanges, type Scored, scorePolicy, type ScoreVerdict, type Split, targetKey, targetScore, type Thresholds, tuneThresholds, verdict, verdictF1 } from "./score.ts";
34
+ export { auprc, auroc, bootstrapInterval, brier, caught, cliThresholds, concordance, falseAlarms, itemLabel, itemsOf, type Label, LabelError, labelFileItems, type LabelRecord, loadLabels, pairedInterval, parseLabels, type PolicyScore, type Quality, quality, type Range, reachedRanges, type Scored, scorePolicy, type ScoreVerdict, type Split, targetKey, targetScore, type Thresholds, tprAtFpr, tuneThresholds, verdict, verdictF1, violationPrecision } from "./score.ts";
@@ -29,6 +29,7 @@ export declare const select: (policy: Policy, cwd?: string | undefined, runs?: S
29
29
  readonly text: string;
30
30
  readonly path?: string | undefined;
31
31
  readonly lines?: readonly [number, number] | undefined;
32
+ readonly media?: readonly string[] | undefined;
32
33
  }[], import("./select.ts").SelectorError, never>;
33
34
  /**
34
35
  * Judge stage: asks the decision model whether each item violates `policy`, under the policy body. Results
@@ -40,6 +41,7 @@ export declare const judge: (policy: Policy, items: readonly {
40
41
  readonly text: string;
41
42
  readonly path?: string | undefined;
42
43
  readonly lines?: readonly [number, number] | undefined;
44
+ readonly media?: readonly string[] | undefined;
43
45
  }[]) => Effect.Effect<readonly Result.Result<number, Unanswered>[], import("./decision-model.ts").DecisionModelError, DecisionModel>;
44
46
  /**
45
47
  * Decide stage: one finding per item of `items`, given their `answers` (from `judge`, in the same order),
@@ -0,0 +1,30 @@
1
+ /** What a decision model can be shown besides text. */
2
+ export type MediaKind = "image" | "audio" | "video";
3
+ export declare const mediaKinds: ReadonlyArray<MediaKind>;
4
+ /** What a message calls several files of a kind. */
5
+ export declare const mediaNoun: Record<MediaKind, string>;
6
+ /** The extensions a media file may have, for messages. */
7
+ export declare const mediaExtensions: string[];
8
+ /** A media file's MIME type and kind, from its extension; `undefined` when it isn't one the models take. */
9
+ export declare const mediaTypeOf: (path: string) => {
10
+ readonly type: string;
11
+ readonly kind: MediaKind;
12
+ } | undefined;
13
+ /** Most files of each kind one item may show the model. */
14
+ export declare const maxMediaFiles: Record<MediaKind, number>;
15
+ /** Largest image an item may show the model. */
16
+ export declare const maxImageBytes: number;
17
+ /** Largest total of the media one item shows the model. */
18
+ export declare const maxMediaBytes: number;
19
+ /** A media file as read for a request: its type and kind, its size, and the SHA-256 of its contents. */
20
+ export interface Medium {
21
+ readonly path: string;
22
+ readonly type: string;
23
+ readonly kind: MediaKind;
24
+ readonly bytes: number;
25
+ readonly digest: string;
26
+ }
27
+ /** Reads the media file at `path` (which must have a media type) and fingerprints it; rejects if it can't. */
28
+ export declare const readMedium: (path: string) => Promise<Medium>;
29
+ /** A media file's contents in base64, read when its request is sent. */
30
+ export declare const mediaBase64: (medium: Medium) => Promise<string>;
@@ -56,6 +56,16 @@ export declare const itemLabel: (target: {
56
56
  readonly label: Label;
57
57
  readonly lines?: ReadonlyArray<Range>;
58
58
  }, item: Item) => Label;
59
+ /**
60
+ * Labels every item emitted for one target together, preventing nested-range artifacts: when a violating
61
+ * target emits both an enclosing unit and a smaller item strictly nested inside it (e.g. a clean helper
62
+ * closure inside a 100-line violating function), the nested item stays `complies` if every gold range it
63
+ * overlaps is covered < 50% by it and strictly better covered by an enclosing emitted item.
64
+ */
65
+ export declare const labelFileItems: (target: {
66
+ readonly label: Label;
67
+ readonly lines?: ReadonlyArray<Range>;
68
+ }, items: ReadonlyArray<Item>) => Array<Label>;
59
69
  /** How many of `ranges` some item covers; items without lines cover every range. */
60
70
  export declare const reachedRanges: (ranges: ReadonlyArray<Range>, items: ReadonlyArray<Item>) => number;
61
71
  /**
@@ -69,6 +79,7 @@ export declare const itemsOf: (record: LabelRecord, items: ReadonlyArray<Item>)
69
79
  readonly text: string;
70
80
  readonly path?: string | undefined;
71
81
  readonly lines?: readonly [number, number] | undefined;
82
+ readonly media?: readonly string[] | undefined;
72
83
  }[];
73
84
  /**
74
85
  * A labeled unit with a policy's violation probability (`null`: too large to send). `group` is the
@@ -91,6 +102,18 @@ export type ScoreVerdict = "pass" | "review" | "violation";
91
102
  export declare const verdict: (score: number, { floor, threshold }: Thresholds) => ScoreVerdict;
92
103
  /** Separation of clear violations from clean units (ambiguous units excluded). */
93
104
  export declare const auroc: (cases: ReadonlyArray<Scored<unknown>>) => number;
105
+ /**
106
+ * Area under the precision-recall curve (Average Precision) on clear cases (ambiguous excluded). Ties are
107
+ * handled by grouping equal scores so ordering within ties cannot inflate or deflate precision.
108
+ */
109
+ export declare const auprc: (cases: ReadonlyArray<Scored<unknown>>) => number;
110
+ /**
111
+ * True positive rate at a target false-positive rate `fpr` on clear cases: share of violations scored
112
+ * strictly above the `(1 - fpr)` clean quantile (with linear handling of boundary ties).
113
+ */
114
+ export declare const tprAtFpr: (cases: ReadonlyArray<Scored<unknown>>, fpr: number) => number;
115
+ /** Precision of `violation` findings (`score >= threshold`) on clear cases (ambiguous excluded). */
116
+ export declare const violationPrecision: (cases: ReadonlyArray<Scored<unknown>>, thresholds?: Thresholds) => number;
94
117
  /**
95
118
  * Ordinal concordance: over every pair of units with different targets (clean < ambiguous < violates),
96
119
  * the share where the higher target gets the higher score. Rewards placing ambiguous units between.
@@ -176,6 +199,7 @@ export declare const scorePolicy: (policy: Policy, labels: readonly {
176
199
  readonly text: string;
177
200
  readonly path?: string | undefined;
178
201
  readonly lines?: readonly [number, number] | undefined;
202
+ readonly media?: readonly string[] | undefined;
179
203
  };
180
204
  label: Label;
181
205
  group: string;
@@ -24,13 +24,14 @@ export declare const killRunningSelectors: () => void;
24
24
  /**
25
25
  * Runs `policy.select` with `sh -c` from `cwd`, with no arguments and an empty stdin: the selector finds
26
26
  * what it judges itself. Its stdout must be JSONL: one item per non-empty line. A non-zero exit, an invalid
27
- * line, or running longer than `selectorTimeoutMinutes` fails the run. With `runs`, a selector already run
28
- * with the same command and directory reuses that run's output.
27
+ * line (media that name no file included), or running longer than `selectorTimeoutMinutes` fails the run.
28
+ * With `runs`, a selector already run with the same command and directory reuses that run's output.
29
29
  */
30
30
  export declare const runSelector: (policy: Policy, cwd?: string | undefined, runs?: SelectorRuns | undefined) => Effect.Effect<{
31
31
  readonly id: string;
32
32
  readonly text: string;
33
33
  readonly path?: string | undefined;
34
34
  readonly lines?: readonly [number, number] | undefined;
35
+ readonly media?: readonly string[] | undefined;
35
36
  }[], SelectorError, never>;
36
37
  export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@andrueandersoncs/lint-anything",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
4
4
  "description": "Check anything against plain-English policies, judged by the decision model of your choice: any System One, OpenAI Decisions, or Gemini Decisions endpoint, or Workers AI",
5
5
  "license": "MIT",
6
6
  "author": "Andrue Anderson",
@@ -5,7 +5,7 @@ description: Run lint-anything, act on its findings, and write or tune its polic
5
5
 
6
6
  # lint-anything
7
7
 
8
- lint-anything checks a codebase against rules written in English. Each rule is a **policy**: a Markdown file whose shell **selector** cuts out the items to judge (functions, comments, commits, anything), and whose body and **criteria** tell a decision model what a violation is: whichever model the project configures. The model returns a violation probability for each item; the CLI turns it into a verdict.
8
+ lint-anything checks a codebase against rules written in English. Each rule is a **policy**: a Markdown file whose shell **selector** cuts out the items to judge (functions, comments, commits, screenshots, recordings, anything), and whose body and **criteria** tell a decision model what a violation is: whichever model the project configures. The model returns a violation probability for each item; the CLI turns it into a verdict.
9
9
 
10
10
  It is a guide more than a gate: semantic rules are judged probabilistically. On the project's eval corpus, well-written policies catch about 69% of real violations outright, surface about 85% (counting `review`), and raise false alarms on about 13% of clean cases. Read findings critically; don't assume every `violation` is real or every `pass` is clean.
11
11
 
@@ -24,7 +24,8 @@ If `lint-anything` isn't found, install it with `bun add -d @andrueandersoncs/li
24
24
  - **The working directory matters.** Policies are read from `./.lint-anything/rules`, and selectors run in the current directory. Run from a subdirectory and you get `error: cannot read policies in .lint-anything/rules`: there is no upward search.
25
25
  - **The decision model** is the project's choice, set in the environment or in `.env` / `.env.local` in the current directory. Don't change it to make findings go away. With `LINT_ANYTHING_ENDPOINT` (a full URL), the model named by `LINT_ANYTHING_MODEL` is asked there, and `LINT_ANYTHING_API_KEY` is its key if it needs one. An endpoint on `generativelanguage.googleapis.com` speaks Google's Decisions API (`gemini-decision-1`, keyed by a Gemini API key); any other whose path ends in `/decisions` speaks OpenAI's; any other speaks System One (`/v1/systemone`: Jev, LiteLLM, LLM Gateway, and most decision-model servers).
26
26
  - **Without an endpoint**, a Cloudflare model on Workers AI is asked: `clef`, or another that `LINT_ANYTHING_MODEL` names (`clef-flash`). `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AUTH_TOKEN` are then required on every run, even when every answer would come from the cache. `CLOUDFLARE_API_BASE_URL` is optional.
27
- - **Accuracy numbers in this skill were measured on Clef.** A project on another model should score it on its labels before trusting it.
27
+ - **What the model can see** besides text depends on it: Gemini Decision 1 and `clef-omni` take images, audio, and video; OpenAI Decisions, `clef`, and `clef-flash` take images only; another System One server takes what it takes. An item whose media the model can't take stops the run before anything is sent (`Clef takes text and images, not audio clips: …`).
28
+ - **Accuracy numbers in this skill were measured on Clef**, on text. A project on another model, or with media, should score its policies on its labels before trusting them.
28
29
  - **Add `.lint-anything/cache` to `.gitignore`.** The answer cache (`answers.sqlite` plus `-wal`/`-shm` files) is written there.
29
30
 
30
31
  ### Output
@@ -50,7 +51,7 @@ Columns: verdict, violation probability (`-` when none), location, policy name,
50
51
  | `pass` | probability ≤ 0.5 | 0 |
51
52
  | `review` | between 0.5 and 0.65: uncertain, often a case reasonable reviewers would disagree on | 0 |
52
53
  | `violation` | probability ≥ 0.65 | **1** |
53
- | `inconclusive` | the item wasn't judged: too large to send (`request is N bytes; Clef would truncate it`, or `…, over the 64000-byte request limit` on another model), or refused by the model (`<model> declined to answer`: an OpenAI Decisions refusal, or a request Gemini's safety filters blocked) | 0 |
54
+ | `inconclusive` | the item wasn't judged: too large to send (`request is N bytes; Clef would truncate it`, or `…, over the 64000-byte request limit` on another model; `image <path> is N bytes, over the 4194304-byte image limit`; `media are N bytes, over the 8388608-byte media limit`), or refused by the model (`<model> declined to answer`: an OpenAI Decisions refusal, or a request Gemini's safety filters blocked) | 0 |
54
55
 
55
56
  | Exit code | Meaning |
56
57
  | --- | --- |
@@ -123,8 +124,8 @@ Frontmatter keys are `select` and `criteria` (with both `true` and `false`), bot
123
124
 
124
125
  The model's "yes" is read as **"this item violates the rule"**:
125
126
 
126
- - `criteria.true` describes an item that **violates** the rule.
127
- - `criteria.false` describes an item that **follows** it, **or that the rule doesn't govern**. Selectors usually over-select, so say what the false answer covers.
127
+ - `criteria.true` describes an item that **violates** the rule — be rule-specific rather than generic ("The item contains a violation"). On the fresh 216-file holdout (H28/H34), replacing generic criteria with rule-specific `criteria.true` and exemption-explicit `criteria.false` plus targeted selector fixes raised Applicable File AUROC `+0.015`, Localized Caught `+6.5 pts`, and TPR@5% `+6.5 pts` outside noise at the same false-alarm rate.
128
+ - `criteria.false` describes an item that **follows** it, **its explicit exemptions**, **or items the rule doesn't govern**. Selectors usually over-select, and decision models read `criteria` immediately adjacent to every question.
128
129
 
129
130
  If you swap them, every verdict inverts. Nothing catches this but the evidence: before relying on a new policy, run it on at least one known violation and one known-clean item and check that the scores point the right way.
130
131
 
@@ -149,8 +150,20 @@ The selector is a shell command that finds what to judge and prints **JSONL**, o
149
150
  | `text` | yes | non-empty string: **everything the model reads for this item**, including its context |
150
151
  | `path` | no | file path, for the location |
151
152
  | `lines` | no | `[start, end]`, integers, **1-based**, inclusive, `1 ≤ start ≤ end` |
153
+ | `media` | no | array of file paths, from the project root: images, audio, and video the model is shown with the text |
152
154
 
153
- Any other field, a non-JSON line, or a wrong type stops the whole run with `selector output line N is not a valid item: …`. Blank lines are skipped.
155
+ Any other field, a non-JSON line, or a wrong type stops the whole run with `selector output line N is not a valid item: …`. Blank lines are skipped. So does a `media` file that doesn't exist, has a type the models don't take, or is one too many of its kind.
156
+
157
+ **Media items.** `media` files are typed by extension: `.png`, `.jpg`, `.jpeg`, `.webp`; `.wav`, `.mp3`, `.flac`, `.ogg`; `.mp4`, `.webm`. An item shows at most 4 images, 4 audio clips, and 2 videos, at most 4 MiB per image and 8 MiB in all (larger is `inconclusive`). Keep `text` short and say what the media is: it is the question asked about them.
158
+
159
+ ```yaml
160
+ select: |
161
+ for f in docs/screenshots/*.png; do
162
+ jq -cn --arg f "$f" '{id: $f, path: $f, text: "screenshot \($f)", media: [$f]}'
163
+ done
164
+ ```
165
+
166
+ Items share a request only with items showing the same files, so a policy over 200 screenshots sends 200 requests on its first run. Several questions about one file (a heading rule and a button rule, as separate items with the same `media`) do share one.
154
167
 
155
168
  How a selector runs:
156
169
 
@@ -256,7 +269,7 @@ The lint-anything repository has worked examples: 21 policies in `evals/corpus/p
256
269
 
257
270
  ## Cache and cost
258
271
 
259
- - Each answer is cached per question, keyed by model (and endpoint), policy body, item text, and criteria. Switching models never reuses another model's answers. Re-running with nothing changed sends no requests, and an edit re-asks only the items whose text changed. Editing a policy's body or criteria re-asks all of that policy's items.
272
+ - Each answer is cached per question, keyed by model (and endpoint), policy body, item text, criteria, and the contents of the item's media. Switching models never reuses another model's answers. Re-running with nothing changed sends no requests, and an edit re-asks only the items whose text or media changed. Editing a policy's body or criteria re-asks all of that policy's items.
260
273
  - Answers expire after 30 days, so everything is asked again about once a month, and verdicts can shift slightly if the model has been updated.
261
274
  - A machine without the cache (a fresh CI runner) pays for every item on every run, unless CI keeps `.lint-anything/cache` between runs.
262
275
  - Cost depends on the model. `--debug` prices only Clef ($0.24 per million input tokens; output is free); on another model its cost column is `-`, and the project's provider bills it. On the evals, with Clef, rule-specific selectors cost about $14–16 per 1,000 files across 17 rules. Nothing caps spending: a selector that emits every line of a large repository sends all of them, so check the item count by hand first.