@opengeni/jev 4.2.1-canary.39593846423001 → 4.3.1

package/README.md

@@ -1,8 +1,8 @@
 # `@opengeni/jev`
 
-`@opengeni/jev` holds Opengeni's client for TypeSafe Jev, a fast judge model, and the Jev-ranked
-`code_search` engine behind the worker's `code_search` agent tool. The package has no runtime
-dependencies. It uses global `fetch`, runs under Node 18+ and Bun, and makes no filesystem or process
+`@opengeni/jev` holds Opengeni's client for TypeSafe Jev, its adapter to the shared
+`@opengeni/decisions` interface, and the provider-neutral `code_search` engine.
+Its only runtime dependency is that shared typed contract. It uses global `fetch`, runs under Node 18+ and Bun, and makes no filesystem or process
 calls of its own.
 
 ## Jev client
@@ -58,9 +58,23 @@ Retries and errors work like this:
 
 ## code_search
 
-`runCodeSearch({question, keywords, subQuestions?, paths?, workspace, jev, signal?, budgetTokens?})`
+`createJevDecisionModel(client)` adapts the existing client without replacing its
+transport policy. `JevError`, `JevUnavailableError` and `JevRequestError` remain
+exported aliases of the shared decision errors. The existing breaker accepts those
+same canonical errors for every provider, with unchanged thresholds and cooldowns.
+The direct client's numeric usage fields remain compatible; `inputTokensReported`
+distinguishes missing counts. The shared adapter reports null token/cost values
+when any successful chunk omitted a valid count, not a zero-cost estimate.
+
+`runCodeSearch({question, keywords, subQuestions?, paths?, workspace, decisionModel, signal?, budgetTokens?})`
 is scout-0.4. It keeps the recall, triage and verification defaults of the validated research tool
 scout-0.3.1, and adds the stages that let an agent read less irrelevant code without reading less relevant code.
+The legacy `jev: JevClient` input remains supported when `decisionModel` is absent.
+Stages now use the shared typed interface; the following Jev-based pipeline was
+the original validated configuration, not a performance claim for every backend.
+Usage is under `stats.decision` (nullable token/cost counts, model/provider and
+cost source); stage events are named `decision`. Refusals fail rather than turning
+into lexical scores. See [decision models](../../docs/decision-models.md).
 The pipeline:
 
 1. **Recall:** one ripgrep pass over the keyword variants, then IDF scoring per file.

package/dist/client.d.ts

@@ -63,6 +63,8 @@ export interface JevAskResult<Q extends Record<string, JevQuestion>> {
     model: string;
     usage: {
         inputTokens: number;
+        /** Whether every successful chunk reported a valid count; numeric field retains compatibility. */
+        inputTokensReported?: boolean;
     };
     /** HTTP requests (chunks) that made up this ask. */
     requests: number;
@@ -78,23 +80,8 @@ export declare function noul(instructions: JevInstructions, criteria?: {
     false?: JevInstructions;
 }): JevNoulQuestion;
 export declare function jevCostUsd(inputTokens: number): number;
-export declare class JevError extends Error {
-    /** HTTP status of the failed response, when there was one. */
-    readonly status: number | undefined;
-    /** Machine-readable reason when known (for example "max_tokens_exceeded" or "state_too_large"). */
-    readonly code: string | undefined;
-    constructor(message: string, options?: {
-        status?: number;
-        code?: string;
-        cause?: unknown;
-    });
-}
-/** Jev cannot be used right now: network, timeout, 5xx, 429 after retries, or 401/402/403 auth and billing. */
-export declare class JevUnavailableError extends JevError {
-}
-/** Jev rejected the request itself (other 4xx), or the request cannot fit the limits. Never retried. */
-export declare class JevRequestError extends JevError {
-}
+import { DecisionError as JevError, DecisionUnavailableError as JevUnavailableError, DecisionRequestError as JevRequestError } from "@opengeni/decisions";
+export { JevError, JevUnavailableError, JevRequestError };
 export interface JevLimits {
     /** Documented: state + longest question. */
     stateLongestMax: number;

package/dist/code-search/judge.d.ts

@@ -1,15 +1,15 @@
 /**
- * judge.ts - the only place where scores come from: Jev answers one probability per judged item.
+ * judge.ts - the only place where scores come from: a typed model returns a probability per item.
  *
- * All Jev wording lives in PROMPTS below (one place to review). Design rules followed:
- *  - one state + many narrow Nouls per request (fan-out); one Noul per candidate (multi-select)
+ * All judge wording lives in PROMPTS below (one place to review). Design rules followed:
+ *  - one state + many narrow predicates per request; one predicate per candidate
  *  - criteria text is explicit (in the state for 60-file triage batches, per question for passages)
  *  - the literal question text is inlined in every question (no `collections[i]`-style indirection)
  *  - state holds only the candidates being judged (filtered by code first)
- *  - no counting, math or dates asked of Jev; code combines answers
- * A Jev failure is not replaced by lexical scores: it propagates and the whole search fails.
+ *  - no counting, math or dates asked of the model; code combines answers
+ * A model failure or refusal is not replaced by lexical scores.
  */
-import { type JevClient, type JevNoulQuestion } from "../client.js";
+import { type DecisionModel, type DecisionPredicateQuestion, type DecisionUsage } from "@opengeni/decisions";
 import type { CodeSearchConfig } from "./config.js";
 export interface JudgeContext {
     question: string;
@@ -20,7 +20,7 @@ export interface FileItem {
     path: string;
     /** path + best hit lines, as shown to the judge */
     descriptor: string;
-    /** Normalized lexical score; used only if Jev returns no usable number for this item. */
+    /** Normalized lexical score retained for candidate ordering. */
     lex: number;
 }
 export interface PassageItem {
@@ -51,8 +51,8 @@ export interface StatusScore {
 }
 export interface StageStats {
     requests: number;
-    inputTokens: number;
-    costUsd: number;
+    inputTokens: number | null;
+    costUsd: number | null;
     ms: number;
 }
 export type JudgeEvent = (stage: string, data: Record<string, unknown>) => void;
@@ -113,7 +113,7 @@ export declare function buildFileRequest(items: FileItem[], ctx: JudgeContext, c
             [k: string]: string;
         };
     };
-    questions: Record<string, JevNoulQuestion>;
+    questions: Record<string, DecisionPredicateQuestion>;
 };
 export declare function buildPassageRequest(items: PassageItem[], ctx: JudgeContext, cfg: CodeSearchConfig): {
     state: {
@@ -128,7 +128,7 @@ export declare function buildPassageRequest(items: PassageItem[], ctx: JudgeCont
             };
         };
     };
-    questions: Record<string, JevNoulQuestion>;
+    questions: Record<string, DecisionPredicateQuestion>;
 };
 export declare function buildLeadRequest(items: LeadItem[], ctx: JudgeContext, cfg: CodeSearchConfig): {
     state: {
@@ -142,7 +142,7 @@ export declare function buildLeadRequest(items: LeadItem[], ctx: JudgeContext, c
             [k: string]: string;
         };
     };
-    questions: Record<string, JevNoulQuestion>;
+    questions: Record<string, DecisionPredicateQuestion>;
 };
 export declare function buildSymbolRequest(items: LeadItem[], ctx: JudgeContext, cfg: CodeSearchConfig): {
     state: {
@@ -156,7 +156,7 @@ export declare function buildSymbolRequest(items: LeadItem[], ctx: JudgeContext,
             [k: string]: string;
         };
     };
-    questions: Record<string, JevNoulQuestion>;
+    questions: Record<string, DecisionPredicateQuestion>;
 };
 export declare function buildChangeRequest(items: LeadItem[], ctx: JudgeContext, cfg: CodeSearchConfig): {
     state: {
@@ -170,7 +170,7 @@ export declare function buildChangeRequest(items: LeadItem[], ctx: JudgeContext,
             [k: string]: string;
         };
     };
-    questions: Record<string, JevNoulQuestion>;
+    questions: Record<string, DecisionPredicateQuestion>;
 };
 export declare function buildStatusRequest(evidence: string, ctx: JudgeContext, cfg: CodeSearchConfig): {
     state: {
@@ -178,24 +178,29 @@ export declare function buildStatusRequest(evidence: string, ctx: JudgeContext,
         question: string;
         evidence: string;
     };
-    questions: Record<string, JevNoulQuestion>;
+    questions: Record<string, DecisionPredicateQuestion>;
 };
 /** Group passages into requests: consecutive (same-file first) up to perRequest items and maxChars of text. */
 export declare function chunkPassages(items: PassageItem[], perRequest: number, maxChars: number): PassageItem[][];
 /** Split into the fewest groups of at most n items, as equal in size as possible (69 -> 35 + 34, not 60 + 9). */
 export declare function chunkEven<T>(xs: T[], n: number): T[][];
-export declare class JevJudge {
+export declare class CodeSearchJudge {
     private readonly o;
     private readonly stageStats;
-    private jevModel;
+    private decisionModelName;
+    private decisionProvider;
+    private readonly usageCostSources;
     constructor(o: {
-        client: JevClient;
+        client: DecisionModel;
         config: CodeSearchConfig;
         signal: AbortSignal;
         onEvent?: JudgeEvent | undefined;
+        onUsage?: ((usage: DecisionUsage) => void | Promise<void>) | undefined;
     });
     stats(): Record<string, StageStats>;
     model(): string | null;
+    provider(): string | null;
+    costSources(): ("estimate" | "provider-reported" | "unknown")[];
     private stat;
     /** One logical request (the client may split its questions into several HTTP requests). */
     private ask;

package/dist/code-search/search.d.ts

@@ -1,5 +1,5 @@
 /**
- * search.ts - the code_search pipeline (scout-0.3.1 with the Jev judge):
+ * search.ts - the code_search pipeline with a shared typed judge:
  *
  *  1. recall   (ripgrep)                        -> top maxCandidates files by distinct-keyword IDF
  *  2. wave 1   (file triage, 1 Noul per file)   -> up to maxFiles files (+ lexical guard)
@@ -7,11 +7,12 @@
  *  4. wave 3   (leads, exactly one round)       -> <= maxLeadsFollowed definitions, verified like wave 2
  *  5. pack     (bounded, verbatim, line-numbered) + status (1 request over the packed evidence)
  *
- * Every file and process access goes through the injected CodeSearchWorkspace. A Jev failure fails the
- * search (JevUnavailableError / JevRequestError propagate); only a failed final status check keeps the
- * fully Jev-scored pack and reports the status as unknown.
+ * Every file and process access goes through the injected CodeSearchWorkspace. A judge failure fails the
+ * search (DecisionUnavailableError / DecisionRequestError propagate); only a failed final status check keeps the
+ * fully scored pack and reports the status as unknown.
  */
-import { JevRequestError, JevUnavailableError, type JevClient } from "../client.js";
+import { DecisionRequestError, DecisionUnavailableError, type DecisionModel, type DecisionUsage } from "@opengeni/decisions";
+import type { JevClient } from "../client.js";
 import { type CodeSearchConfig } from "./config.js";
 import { type FileCandidate, type KeywordInfo, type RecallResult } from "./recall.js";
 import type { CodeSearchWorkspace } from "./workspace.js";
@@ -25,20 +26,24 @@ export interface CodeSearchInput {
     /** Workspace-relative path prefixes to search; default the whole workspace. */
     paths?: string[] | undefined;
     workspace: CodeSearchWorkspace;
-    jev: JevClient;
+    decisionModel?: DecisionModel;
+    /** Compatibility for public callers of the existing client API; adapted once at entry. */
+    jev?: JevClient;
     signal?: AbortSignal | undefined;
     /** Max pack size in tokens (default 12000). */
     budgetTokens?: number | undefined;
     /** Tuning and tests only; defaults to DEFAULT_CODE_SEARCH_CONFIG. */
     config?: CodeSearchConfig | undefined;
-    /** In-memory stage trace (recall, wave1, wave2, leads, pack, summary, and one "jev" event per Jev request). */
+    /** In-memory stage trace, including one "decision" event per typed judgment request. */
     onStage?: ((stage: string, data: Record<string, unknown>) => void) | undefined;
+    /** Received provider usage is observable even if a later stage or answer fails. */
+    onDecisionUsage?: ((usage: DecisionUsage) => void | Promise<void>) | undefined;
 }
 export interface CodeSearchStatus {
     label: "sufficient" | "partial" | "insufficient" | "unknown";
     overall: number | null;
     subs: Array<number | null>;
-    /** Set when the final Jev sufficiency check failed (the pack itself is fully Jev-scored). */
+    /** Set when the final evidence check failed (the pack itself is fully scored). */
     error?: string;
 }
 export interface CodeSearchStats {
@@ -53,11 +58,13 @@ export interface CodeSearchStats {
     workspaceCalls: number;
     /** A ripgrep call returned partial output (byte cap or time limit); the pack header says so. */
     ripgrepTruncated: boolean;
-    jev: {
+    decision: {
         requests: number;
-        inputTokens: number;
-        costUsd: number;
+        inputTokens: number | null;
+        costUsd: number | null;
         model: string | null;
+        provider: string | null;
+        costSources: Array<"provider-reported" | "estimate" | "unknown">;
     };
 }
 export interface CodeSearchResult {
@@ -67,7 +74,7 @@ export interface CodeSearchResult {
     status: CodeSearchStatus;
     stats: CodeSearchStats;
     /** The error of a failed final status check, for a circuit breaker (the search itself succeeded). */
-    statusCheckError?: JevUnavailableError | JevRequestError;
+    statusCheckError?: DecisionUnavailableError | DecisionRequestError;
 }
 /** Lexical passage relevance in [0,1]: keyword IDF mass present, question-term overlap, file prior. */
 export declare function lexicalPassageScore(text: string, kwPresent: number[], keywords: KeywordInfo[], qTerms: string[], fileNorm: number): number;

package/dist/decision-model.d.ts

@@ -0,0 +1,4 @@
+import { type DecisionModel } from "@opengeni/decisions";
+import { JevClient } from "./client.js";
+/** Adapt the existing typed client without duplicating its transport/chunking policy. */
+export declare function createJevDecisionModel(client: JevClient): DecisionModel;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { JEV_CHARS_PER_TOKEN, JEV_DEFAULT_BASE_URL, JEV_DEFAULT_LIMITS, JEV_DEFAULT_MODEL, JEV_PRICE_PER_MILLION_INPUT_TOKENS_USD, JevClient, JevError, JevLimiter, JevRequestError, JevUnavailableError, estimateJevTokens, jevCostUsd, noul, planChunks, type JevAnswer, type JevAnswerFor, type JevAskOptions, type JevAskResult, type JevChoiceAnswer, type JevChoiceQuestion, type JevClientOptions, type JevFetch, type JevInstructions, type JevLimits, type JevNoulAnswer, type JevNoulQuestion, type JevQuestion, type JevScoreAnswer, type JevScoreQuestion, } from "./client.js";
+export { createJevDecisionModel } from "./decision-model.js";
 export { JevCircuitBreaker, type JevCircuitBreakerOptions, type JevCircuitLease, type JevCircuitState, type JevCircuitStatus, } from "./circuit-breaker.js";
 export { CODE_SEARCH_DEFAULT_BUDGET_TOKENS, CODE_SEARCH_ENGINE_VERSION, runCodeSearch, type CodeSearchInput, type CodeSearchResult, type CodeSearchStats, type CodeSearchStatus, } from "./code-search/search.js";
 export { CODE_SEARCH_CREDENTIAL_DIRS, isCodeSearchCredentialPath } from "./code-search/recall.js";