pdf-brain 1.3.0 → 2.0.0

package/src/types.test.ts

@@ -28,12 +28,16 @@ describe("Unified Search Types", () => {
   describe("DocumentSearchResult", () => {
     test("should create valid document search result", () => {
       const result = new DocumentSearchResult({
+        chunkId: "doc-123-0",
         docId: "doc-123",
         title: "Test Document",
         page: 1,
         chunkIndex: 0,
         content: "Test content",
         score: 0.95,
+        rawScore: 0.95,
+        scoreType: "cosine_similarity",
+        vectorScore: 0.95,
         matchType: "vector",
         entityType: "document",
       });
@@ -45,12 +49,16 @@ describe("Unified Search Types", () => {
 
     test("should support optional expanded content", () => {
       const result = new DocumentSearchResult({
+        chunkId: "doc-123-0",
         docId: "doc-123",
         title: "Test Document",
         page: 1,
         chunkIndex: 0,
         content: "Test content",
         score: 0.95,
+        rawScore: 0.95,
+        scoreType: "cosine_similarity",
+        vectorScore: 0.95,
         matchType: "vector",
         entityType: "document",
         expandedContent: "Expanded test content",
@@ -69,6 +77,8 @@ describe("Unified Search Types", () => {
         prefLabel: "Machine Learning",
         definition: "A subset of artificial intelligence...",
         score: 0.88,
+        rawScore: 0.88,
+        scoreType: "cosine_similarity",
         entityType: "concept",
       });
 
@@ -82,12 +92,16 @@ describe("Unified Search Types", () => {
   describe("UnifiedSearchResult", () => {
     test("should accept DocumentSearchResult", () => {
       const docResult: UnifiedSearchResult = new DocumentSearchResult({
+        chunkId: "doc-123-0",
         docId: "doc-123",
         title: "Test Document",
         page: 1,
         chunkIndex: 0,
         content: "Test content",
         score: 0.95,
+        rawScore: 0.95,
+        scoreType: "cosine_similarity",
+        vectorScore: 0.95,
         matchType: "vector",
         entityType: "document",
       });
@@ -101,6 +115,8 @@ describe("Unified Search Types", () => {
         prefLabel: "Machine Learning",
         definition: "A subset of artificial intelligence...",
         score: 0.88,
+        rawScore: 0.88,
+        scoreType: "cosine_similarity",
         entityType: "concept",
       });
 
@@ -110,12 +126,16 @@ describe("Unified Search Types", () => {
     test("should discriminate by entityType", () => {
       const results: UnifiedSearchResult[] = [
         new DocumentSearchResult({
+          chunkId: "doc-123-0",
           docId: "doc-123",
           title: "Test Document",
           page: 1,
           chunkIndex: 0,
           content: "Test content",
           score: 0.95,
+          rawScore: 0.95,
+          scoreType: "cosine_similarity",
+          vectorScore: 0.95,
           matchType: "vector",
           entityType: "document",
         }),
@@ -124,6 +144,8 @@ describe("Unified Search Types", () => {
           prefLabel: "Machine Learning",
           definition: "A subset of artificial intelligence...",
           score: 0.88,
+          rawScore: 0.88,
+          scoreType: "cosine_similarity",
           entityType: "concept",
         }),
       ];

package/src/types.ts

@@ -52,12 +52,22 @@ export type EntityType = "document" | "concept";
  * @deprecated Use DocumentSearchResult for unified search. Kept for backwards compatibility.
  */
 export class SearchResult extends Schema.Class<SearchResult>("SearchResult")({
+  chunkId: Schema.String,
   docId: Schema.String,
   title: Schema.String,
   page: Schema.Number,
   chunkIndex: Schema.Number,
   content: Schema.String,
+  /** Normalized score in 0..1 for ranking across match types */
   score: Schema.Number,
+  /** Raw score from the underlying engine (e.g. cosine similarity, FTS rank) */
+  rawScore: Schema.Number,
+  /** What rawScore represents (do not assume one score meaning across engines) */
+  scoreType: Schema.Literal("cosine_similarity", "fts_rank", "hybrid"),
+  /** Optional component score for vector results */
+  vectorScore: Schema.optional(Schema.Number),
+  /** Optional component score for FTS results (raw FTS rank; often negative, more negative = better) */
+  ftsRank: Schema.optional(Schema.Number),
   matchType: Schema.Literal("vector", "fts", "hybrid"),
   /** Expanded context around the match (only populated when expandChars > 0) */
   expandedContent: Schema.optional(Schema.String),
@@ -65,7 +75,47 @@ export class SearchResult extends Schema.Class<SearchResult>("SearchResult")({
   expandedRange: Schema.optional(
     Schema.Struct({ start: Schema.Number, end: Schema.Number })
   ),
-}) {}
+}) {
+  /**
+   * Backwards-compatible constructor:
+   * Older callers used `SearchResult` without chunkId/rawScore/scoreType.
+   *
+   * This type is deprecated in favor of `DocumentSearchResult`, but we keep
+   * legacy input working so downstream code doesn't explode.
+   */
+  constructor(props: any) {
+    const docId = props?.docId;
+    const page = props?.page;
+    const chunkIndex = props?.chunkIndex;
+
+    const matchType: "vector" | "fts" | "hybrid" = props?.matchType;
+    const score: number = props?.score;
+
+    const chunkId =
+      props?.chunkId ?? `legacy:${String(docId)}:${String(page)}:${String(chunkIndex)}`;
+
+    const rawScore = props?.rawScore ?? score;
+
+    const scoreType =
+      props?.scoreType ??
+      (matchType === "fts"
+        ? "fts_rank"
+        : matchType === "hybrid"
+          ? "hybrid"
+          : "cosine_similarity");
+
+    const vectorScore =
+      props?.vectorScore ?? (matchType === "vector" ? score : undefined);
+
+    super({
+      ...props,
+      chunkId,
+      rawScore,
+      scoreType,
+      vectorScore,
+    });
+  }
+}
 
 /**
  * Document search result with entity type discriminator
@@ -73,12 +123,22 @@ export class SearchResult extends Schema.Class<SearchResult>("SearchResult")({
 export class DocumentSearchResult extends Schema.Class<DocumentSearchResult>(
   "DocumentSearchResult"
 )({
+  chunkId: Schema.String,
   docId: Schema.String,
   title: Schema.String,
   page: Schema.Number,
   chunkIndex: Schema.Number,
   content: Schema.String,
+  /** Normalized score in 0..1 for ranking across match types */
   score: Schema.Number,
+  /** Raw score from the underlying engine (e.g. cosine similarity, FTS rank) */
+  rawScore: Schema.Number,
+  /** What rawScore represents (do not assume one score meaning across engines) */
+  scoreType: Schema.Literal("cosine_similarity", "fts_rank", "hybrid"),
+  /** Optional component score for vector results */
+  vectorScore: Schema.optional(Schema.Number),
+  /** Optional component score for FTS results (raw FTS rank; often negative, more negative = better) */
+  ftsRank: Schema.optional(Schema.Number),
   matchType: Schema.Literal("vector", "fts", "hybrid"),
   entityType: Schema.Literal("document"),
   /** Expanded context around the match (only populated when expandChars > 0) */
@@ -98,7 +158,11 @@ export class ConceptSearchResult extends Schema.Class<ConceptSearchResult>(
   conceptId: Schema.String,
   prefLabel: Schema.String,
   definition: Schema.String,
+  /** Normalized score in 0..1 */
   score: Schema.Number,
+  /** Raw score from the underlying engine (cosine similarity) */
+  rawScore: Schema.Number,
+  scoreType: Schema.Literal("cosine_similarity"),
   entityType: Schema.Literal("concept"),
 }) {}
 
@@ -166,6 +230,9 @@ export class Config extends Schema.Class<Config>("Config")({
     host: Schema.String,
     autoInstall: Schema.Boolean,
   }),
+  gateway: Schema.optionalWith(Schema.Struct({
+    apiKey: Schema.optional(Schema.String),
+  }), { default: () => ({}) }),
 }) {
   /**
    * Default configuration: Ollama for all providers
@@ -187,7 +254,15 @@ export class Config extends Schema.Class<Config>("Config")({
       host: "http://localhost:11434",
       autoInstall: true,
     },
+    gateway: {},
   });
+
+  /**
+   * Resolve the gateway API key: config takes precedence over env var.
+   */
+  get gatewayApiKey(): string | undefined {
+    return this.gateway.apiKey ?? process.env.AI_GATEWAY_API_KEY;
+  }
 }
 
 // ============================================================================
@@ -224,7 +299,7 @@ export function loadConfig(): Config {
 
 /**
  * Save config to $PDF_LIBRARY_PATH/config.json.
- * API keys are never stored - they come from env vars (AI_GATEWAY_API_KEY).
+ * API keys can be stored in config or read from env var AI_GATEWAY_API_KEY.
  */
 export function saveConfig(config: Config): void {
   const libraryPath =
@@ -268,6 +343,11 @@ export class AddOptions extends Schema.Class<AddOptions>("AddOptions")({
   metadata: Schema.optional(
     Schema.Record({ key: Schema.String, value: Schema.Unknown })
   ),
+  /**
+   * Internal/advanced: preserve original `addedAt` on re-add/rechunk workflows.
+   * CLI does not expose this directly.
+   */
+  addedAt: Schema.optional(Schema.Date),
 }) {}
 
 // ============================================================================

package/src/updater.ts

@@ -9,8 +9,9 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, chmodSync } from "fs";
 import { join } from "path";
+import { logInfo } from "./logger.js";
 
-const REPO = "joelhooks/pdf-library";
+const REPO = "joelhooks/pdf-brain";
 const STATE_DIR = join(process.env.HOME || "~", ".pdf-brain");
 const STATE_FILE = join(STATE_DIR, "update-check.json");
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 1 day
@@ -112,6 +113,10 @@ async function downloadAndReplace(version: string): Promise<boolean> {
  * Current invocation keeps running the old code — new version takes effect next run.
  */
 export function backgroundUpdateCheck(currentVersion: string): void {
+  // Agent-first default: disable background updates unless explicitly enabled.
+  // Background network calls + non-deterministic stderr output are a footgun for tool callers.
+  if (process.env.PDF_BRAIN_BACKGROUND_UPDATE !== "1") return;
+
   // Don't auto-update in dev mode
   if (currentVersion.includes("compiled") || currentVersion === "0.0.0") return;
 
@@ -135,8 +140,8 @@ export function backgroundUpdateCheck(currentVersion: string): void {
       if (ok) {
         newState.lastAutoUpdate = now;
         newState.latestVersion = latest;
-        // Brief note so they know why behavior might change
-        console.error(`\x1b[2mUpdated pdf-brain v${currentVersion} → v${latest}\x1b[0m`);
+        // Brief note so they know why behavior might change (stderr only).
+        logInfo(`Updated pdf-brain v${currentVersion} -> v${latest}`);
       }
     }