@indigoai-us/cq 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * CQ Public API — top-level configuration and instance types.
+ */
+import type { ConfidenceConfig } from "./confidence/index.js";
+import type { BudgetConfig } from "./budget/index.js";
+import type { TokenTracker } from "./budget/token-tracker.js";
+import type { SearchProvider, ModelProvider } from "./providers/types.js";
+import type { OrchestratorResult } from "./orchestrator/types.js";
+import type Database from "better-sqlite3";
+/** Configuration for initialising the CQ system. */
+export interface CQConfig {
+    /** Root directory for the knowledge tree (markdown files). */
+    dataDir: string;
+    /** Optional budget configuration overrides. */
+    budget?: Partial<BudgetConfig>;
+    /** Optional confidence configuration overrides. */
+    confidence?: Partial<ConfidenceConfig>;
+    /** Optional provider overrides. Defaults to OpenAI search + Claude model. */
+    providers?: {
+        search?: SearchProvider;
+        model?: ModelProvider;
+    };
+    /** Optional scheduler configuration. If provided, the scheduler starts automatically. */
+    scheduler?: {
+        /** Cron expression: "minute hour dayOfMonth". Default "0 3 *". */
+        cron?: string;
+        /** Called when a scheduled run completes. */
+        onComplete?: (result: OrchestratorResult) => void;
+        /** Called when a scheduled run fails. */
+        onError?: (error: Error) => void;
+    };
+}
+/** A fully initialised CQ system instance. */
+export interface CQInstance {
+    /** Knowledge tree operations (write, read, list, remove entries). */
+    knowledge: {
+        initKnowledgeTree: (dataDir: string) => Promise<void>;
+        writeEntry: typeof import("./knowledge-tree/index.js").writeEntry;
+        readEntry: typeof import("./knowledge-tree/index.js").readEntry;
+        listEntries: typeof import("./knowledge-tree/index.js").listEntries;
+        listCategories: typeof import("./knowledge-tree/index.js").listCategories;
+        removeEntry: typeof import("./knowledge-tree/index.js").removeEntry;
+        createCategory: typeof import("./knowledge-tree/index.js").createCategory;
+        generateIndex: typeof import("./knowledge-tree/index.js").generateIndex;
+        generateIndexRecursive: typeof import("./knowledge-tree/index.js").generateIndexRecursive;
+    };
+    /** Metadata store operations (index, search, query metadata). */
+    metadata: {
+        indexEntry: typeof import("./metadata/index.js").indexEntry;
+        removeFromIndex: typeof import("./metadata/index.js").removeFromIndex;
+        getMetadata: typeof import("./metadata/index.js").getMetadata;
+        getStaleEntries: typeof import("./metadata/index.js").getStaleEntries;
+        search: typeof import("./metadata/search.js").search;
+        rebuildIndex: typeof import("./metadata/search.js").rebuildIndex;
+    };
+    /** Confidence system operations. */
+    confidence: {
+        setConfidenceConfig: typeof import("./confidence/index.js").setConfidenceConfig;
+        getConfidenceConfig: typeof import("./confidence/index.js").getConfidenceConfig;
+        getConfidence: typeof import("./confidence/index.js").getConfidence;
+        recordVerification: typeof import("./confidence/index.js").recordVerification;
+        recordContradiction: typeof import("./confidence/index.js").recordContradiction;
+        getRefreshCandidates: typeof import("./confidence/index.js").getRefreshCandidates;
+    };
+    /** Curiosity queue operations. */
+    curiosity: {
+        addCuriosity: typeof import("./curiosity/index.js").addCuriosity;
+        fetchPending: typeof import("./curiosity/index.js").fetchPending;
+        getItem: typeof import("./curiosity/index.js").getItem;
+        markInProgress: typeof import("./curiosity/index.js").markInProgress;
+        markCompleted: typeof import("./curiosity/index.js").markCompleted;
+        markFailed: typeof import("./curiosity/index.js").markFailed;
+        dismiss: typeof import("./curiosity/index.js").dismiss;
+        countByStatus: typeof import("./curiosity/index.js").countByStatus;
+    };
+    /** Research pipeline. */
+    pipeline: {
+        runPipeline: typeof import("./pipeline/index.js").runPipeline;
+    };
+    /** Resource vetter. */
+    vetter: {
+        vetResource: typeof import("./vetter/index.js").vetResource;
+        trackResourceUsage: typeof import("./vetter/index.js").trackResourceUsage;
+        isOverRelied: typeof import("./vetter/index.js").isOverRelied;
+        getDomainUsage: typeof import("./vetter/index.js").getDomainUsage;
+        getUnderexploredDomains: typeof import("./vetter/index.js").getUnderexploredDomains;
+        getResourceUsage: typeof import("./vetter/index.js").getResourceUsage;
+    };
+    /** Budget tracking. */
+    budget: {
+        setBudgetConfig: typeof import("./budget/index.js").setBudgetConfig;
+        getBudgetConfig: typeof import("./budget/index.js").getBudgetConfig;
+        charge: typeof import("./budget/index.js").charge;
+        checkBudget: typeof import("./budget/index.js").checkBudget;
+        getDailyBudgetStatus: typeof import("./budget/index.js").getDailyBudgetStatus;
+        getTotalBudgetStatus: typeof import("./budget/index.js").getTotalBudgetStatus;
+    };
+    /** Token tracker for context window management. */
+    tokenTracker: TokenTracker;
+    /** Research orchestrator. */
+    orchestrator: {
+        runOrchestrator: typeof import("./orchestrator/index.js").runOrchestrator;
+        getRecentRuns: typeof import("./orchestrator/index.js").getRecentRuns;
+    };
+    /** Scheduler control. */
+    scheduler: {
+        startScheduler: typeof import("./orchestrator/scheduler.js").startScheduler;
+        stopScheduler: typeof import("./orchestrator/scheduler.js").stopScheduler;
+        isSchedulerRunning: typeof import("./orchestrator/scheduler.js").isSchedulerRunning;
+    };
+    /** The underlying better-sqlite3 database instance. */
+    db: Database.Database;
+    /** The data directory path. */
+    dataDir: string;
+    /** The search provider in use. */
+    searchProvider: SearchProvider;
+    /** The model provider in use. */
+    modelProvider: ModelProvider;
+    /** Cleanly shut down all SQLite connections and stop the scheduler. */
+    close: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * CQ Public API — top-level configuration and instance types.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/vetter/__tests__/vetter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vetter.test.d.ts.map

package/dist/vetter/__tests__/vetter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vetter.test.d.ts","sourceRoot":"","sources":["../../../src/vetter/__tests__/vetter.test.ts"],"names":[],"mappings":""}

package/dist/vetter/__tests__/vetter.test.js

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { vetResource } from "../index.js";
+import { initResourceTracker, trackResourceUsage, isOverRelied, getDomainUsage, getUnderexploredDomains, getResourceUsage, } from "../resource-tracker.js";
+import { closeResourceTracker } from "../resource-tracker.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeResource(overrides = {}) {
+    return {
+        title: "Understanding Modern Web Architecture",
+        url: "https://developer.mozilla.org/en-US/docs/Web/Architecture",
+        snippet: "Modern web architecture has evolved significantly, specifically because of advancements in distributed systems and cloud computing platforms.",
+        content: "# Modern Web Architecture\n\nModern web architecture has evolved significantly.\n\n## Key Concepts\n\n- Microservices\n- Serverless\n- Edge computing\n\n```javascript\nconst app = express();\n```\n\nThis guide covers the fundamentals of building scalable web applications.\n\n" +
+            "Additional content ".repeat(100),
+        ...overrides,
+    };
+}
+function makeMinimalResource(overrides = {}) {
+    return {
+        title: "Hi",
+        url: "http://example.com",
+        snippet: "Short",
+        ...overrides,
+    };
+}
+// ===========================================================================
+// Quality Vetting
+// ===========================================================================
+describe("vetResource", () => {
+    it("scores a high-quality resource above accept threshold", async () => {
+        const result = await vetResource(makeResource());
+        expect(result.qualityScore).toBeGreaterThanOrEqual(0.75);
+        expect(result.recommendation).toBe("accept");
+        expect(result.url).toBe("https://developer.mozilla.org/en-US/docs/Web/Architecture");
+        expect(result.signals.length).toBeGreaterThan(0);
+    });
+    it("scores a minimal resource below quality threshold", async () => {
+        const result = await vetResource(makeMinimalResource());
+        expect(result.qualityScore).toBeLessThan(0.5);
+        expect(result.recommendation).toBe("reject");
+        expect(result.reason).toContain("below threshold");
+    });
+    it("returns 'review' for borderline resources", async () => {
+        const resource = makeResource({
+            content: "Some content with moderate length to pass basic checks.",
+            snippet: "A decent snippet that provides some context about the topic.",
+            url: "https://example.com/article",
+            title: "Decent Article Title About Things",
+        });
+        const result = await vetResource(resource, undefined, {
+            qualityThreshold: 0.4,
+            acceptThreshold: 0.8,
+        });
+        // With this config the score should land between 0.4 and 0.8
+        if (result.qualityScore >= 0.4 && result.qualityScore < 0.8) {
+            expect(result.recommendation).toBe("review");
+        }
+    });
+    it("respects custom quality thresholds", async () => {
+        const config = { qualityThreshold: 0.9, acceptThreshold: 0.95 };
+        const result = await vetResource(makeResource(), undefined, config);
+        // Even a good resource should be "review" or "reject" with very high thresholds
+        expect(["review", "reject"]).toContain(result.recommendation);
+    });
+    it("returns signals array with expected fields", async () => {
+        const result = await vetResource(makeResource());
+        for (const signal of result.signals) {
+            expect(signal).toHaveProperty("signal");
+            expect(signal).toHaveProperty("score");
+            expect(signal).toHaveProperty("weight");
+            expect(signal.score).toBeGreaterThanOrEqual(0);
+            expect(signal.score).toBeLessThanOrEqual(1);
+            expect(signal.weight).toBeGreaterThan(0);
+        }
+    });
+    it("detects content length signal", async () => {
+        const result = await vetResource(makeResource());
+        const lengthSignal = result.signals.find((s) => s.signal === "content_length");
+        expect(lengthSignal).toBeDefined();
+        expect(lengthSignal.score).toBeGreaterThanOrEqual(0.7);
+    });
+    it("detects structure signal", async () => {
+        const result = await vetResource(makeResource());
+        const structSignal = result.signals.find((s) => s.signal === "structure");
+        expect(structSignal).toBeDefined();
+        expect(structSignal.score).toBeGreaterThan(0);
+    });
+    it("penalises low-quality URL patterns", async () => {
+        const resource = makeResource({
+            url: "https://www.pinterest.com/pin/12345",
+        });
+        const result = await vetResource(resource);
+        const urlSignal = result.signals.find((s) => s.signal === "url_quality");
+        expect(urlSignal).toBeDefined();
+        expect(urlSignal.score).toBeLessThan(0.5);
+    });
+    it("boosts trusted domain scores", async () => {
+        const resource = makeResource({
+            url: "https://github.com/some/repo",
+        });
+        const result = await vetResource(resource);
+        const urlSignal = result.signals.find((s) => s.signal === "url_quality");
+        expect(urlSignal).toBeDefined();
+        expect(urlSignal.score).toBeGreaterThanOrEqual(0.9);
+    });
+    it("rounds quality score to 3 decimal places", async () => {
+        const result = await vetResource(makeResource());
+        const decimalPlaces = result.qualityScore.toString().split(".")[1]?.length ?? 0;
+        expect(decimalPlaces).toBeLessThanOrEqual(3);
+    });
+});
+// ===========================================================================
+// Resource Usage Tracking
+// ===========================================================================
+describe("resource-tracker", () => {
+    beforeEach(() => {
+        initResourceTracker(":memory:");
+    });
+    afterEach(() => {
+        closeResourceTracker();
+    });
+    describe("trackResourceUsage", () => {
+        it("creates a new usage record", () => {
+            trackResourceUsage("https://example.com/article", 0.8);
+            const usage = getResourceUsage("https://example.com/article");
+            expect(usage).toBeDefined();
+            expect(usage.url).toBe("https://example.com/article");
+            expect(usage.domain).toBe("example.com");
+            expect(usage.use_count).toBe(1);
+            expect(usage.quality_scores).toEqual([0.8]);
+        });
+        it("increments use_count on repeat usage", () => {
+            trackResourceUsage("https://example.com/article", 0.8);
+            trackResourceUsage("https://example.com/article", 0.9);
+            trackResourceUsage("https://example.com/article", 0.7);
+            const usage = getResourceUsage("https://example.com/article");
+            expect(usage.use_count).toBe(3);
+            expect(usage.quality_scores).toEqual([0.8, 0.9, 0.7]);
+        });
+        it("strips www. from domain", () => {
+            trackResourceUsage("https://www.example.com/page", 0.5);
+            const usage = getResourceUsage("https://www.example.com/page");
+            expect(usage.domain).toBe("example.com");
+        });
+        it("sets timestamps on creation", () => {
+            trackResourceUsage("https://example.com/a", 0.5);
+            const usage = getResourceUsage("https://example.com/a");
+            expect(usage.first_used_at).toBeTruthy();
+            expect(usage.last_used_at).toBeTruthy();
+        });
+    });
+    describe("isOverRelied", () => {
+        it("returns false for unknown URLs", () => {
+            expect(isOverRelied("https://unknown.com")).toBe(false);
+        });
+        it("returns false when use_count is at or below threshold", () => {
+            for (let i = 0; i < 5; i++) {
+                trackResourceUsage("https://example.com/doc", 0.8);
+            }
+            expect(isOverRelied("https://example.com/doc", 5)).toBe(false);
+        });
+        it("returns true when use_count exceeds threshold", () => {
+            for (let i = 0; i < 6; i++) {
+                trackResourceUsage("https://example.com/doc", 0.8);
+            }
+            expect(isOverRelied("https://example.com/doc", 5)).toBe(true);
+        });
+        it("uses default maxUses of 5", () => {
+            for (let i = 0; i < 6; i++) {
+                trackResourceUsage("https://example.com/doc", 0.8);
+            }
+            expect(isOverRelied("https://example.com/doc")).toBe(true);
+        });
+    });
+    describe("getDomainUsage", () => {
+        it("returns undefined for unknown domain", () => {
+            expect(getDomainUsage("unknown.com")).toBeUndefined();
+        });
+        it("aggregates stats across URLs for same domain", () => {
+            trackResourceUsage("https://example.com/a", 0.8);
+            trackResourceUsage("https://example.com/b", 0.6);
+            trackResourceUsage("https://example.com/a", 0.9);
+            const stats = getDomainUsage("example.com");
+            expect(stats).toBeDefined();
+            expect(stats.domain).toBe("example.com");
+            expect(stats.total_uses).toBe(3);
+            expect(stats.unique_urls).toBe(2);
+            expect(stats.avg_quality).toBeCloseTo(0.767, 2);
+        });
+        it("computes correct avg_quality", () => {
+            trackResourceUsage("https://test.org/x", 1.0);
+            trackResourceUsage("https://test.org/y", 0.5);
+            const stats = getDomainUsage("test.org");
+            expect(stats.avg_quality).toBeCloseTo(0.75, 2);
+        });
+    });
+    describe("getUnderexploredDomains", () => {
+        it("returns unused domains first", () => {
+            trackResourceUsage("https://used.com/page", 0.8);
+            const result = getUnderexploredDomains(["used.com", "unused1.com", "unused2.com"], 3);
+            expect(result[0]).not.toBe("used.com");
+            expect(result).toContain("unused1.com");
+            expect(result).toContain("unused2.com");
+        });
+        it("sorts by usage count ascending", () => {
+            trackResourceUsage("https://heavy.com/a", 0.8);
+            trackResourceUsage("https://heavy.com/a", 0.8);
+            trackResourceUsage("https://heavy.com/a", 0.8);
+            trackResourceUsage("https://light.com/b", 0.8);
+            const result = getUnderexploredDomains(["heavy.com", "light.com", "zero.com"], 3);
+            expect(result[0]).toBe("zero.com");
+            expect(result[1]).toBe("light.com");
+            expect(result[2]).toBe("heavy.com");
+        });
+        it("respects limit parameter", () => {
+            const result = getUnderexploredDomains(["a.com", "b.com", "c.com", "d.com"], 2);
+            expect(result).toHaveLength(2);
+        });
+        it("returns empty array for empty input", () => {
+            expect(getUnderexploredDomains([])).toEqual([]);
+        });
+    });
+});
+//# sourceMappingURL=vetter.test.js.map

package/dist/vetter/__tests__/vetter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vetter.test.js","sourceRoot":"","sources":["../../../src/vetter/__tests__/vetter.test.ts"],"names":[],"mappings":"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"}

package/dist/vetter/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resource Vetter — heuristic quality scoring for web search results.
+ *
+ * Scores resources on a 0–1 scale using content-based signals (length,
+ * structure, snippet quality, URL quality). The optional modelProvider
+ * parameter is reserved for future LLM-enhanced vetting.
+ */
+import type { WebSearchResult } from "../providers/types.js";
+import type { ModelProvider } from "../providers/types.js";
+import type { VetResult, VetConfig } from "./types.js";
+export type { VetResult, VetConfig, QualitySignal, VetRecommendation } from "./types.js";
+export type { ResourceUsage, DomainStats } from "./types.js";
+export { initResourceTracker, trackResourceUsage, isOverRelied, getDomainUsage, getUnderexploredDomains, getResourceUsage, } from "./resource-tracker.js";
+/**
+ * Vet a resource for quality using content-based heuristics.
+ *
+ * @param resource - A web search result to evaluate.
+ * @param _modelProvider - Reserved for future LLM-enhanced vetting (unused).
+ * @param config - Optional thresholds for accept/reject.
+ * @returns A VetResult with the quality score, signals, and recommendation.
+ */
+export declare function vetResource(resource: WebSearchResult, _modelProvider?: ModelProvider, config?: VetConfig): Promise<VetResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/vetter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vetter/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAoC,MAAM,YAAY,CAAC;AAEzF,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACzF,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAsI/B;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,eAAe,EACzB,cAAc,CAAC,EAAE,aAAa,EAC9B,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,SAAS,CAAC,CAwCpB"}

package/dist/vetter/index.js

@@ -0,0 +1,177 @@
+/**
+ * Resource Vetter — heuristic quality scoring for web search results.
+ *
+ * Scores resources on a 0–1 scale using content-based signals (length,
+ * structure, snippet quality, URL quality). The optional modelProvider
+ * parameter is reserved for future LLM-enhanced vetting.
+ */
+export { initResourceTracker, trackResourceUsage, isOverRelied, getDomainUsage, getUnderexploredDomains, getResourceUsage, } from "./resource-tracker.js";
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_QUALITY_THRESHOLD = 0.5;
+const DEFAULT_ACCEPT_THRESHOLD = 0.75;
+// ---------------------------------------------------------------------------
+// Signal detectors
+// ---------------------------------------------------------------------------
+/** Domains known to be high-quality reference sources. */
+const TRUSTED_DOMAINS = new Set([
+    "github.com",
+    "stackoverflow.com",
+    "developer.mozilla.org",
+    "docs.python.org",
+    "en.wikipedia.org",
+    "arxiv.org",
+    "nature.com",
+    "science.org",
+    "nytimes.com",
+    "reuters.com",
+]);
+/** URL patterns that suggest low-quality or aggregator content. */
+const LOW_QUALITY_PATTERNS = [
+    /slideshare\.net/,
+    /pinterest\.com/,
+    /quora\.com/,
+    /listicle/i,
+    /top-\d+/i,
+];
+function extractDomain(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return "";
+    }
+}
+/** Score based on content length (longer = more substance). */
+function scoreContentLength(resource) {
+    const content = resource.content ?? resource.snippet ?? "";
+    const len = content.length;
+    let score;
+    if (len >= 2000)
+        score = 1.0;
+    else if (len >= 500)
+        score = 0.7;
+    else if (len >= 100)
+        score = 0.4;
+    else
+        score = 0.1;
+    return { signal: "content_length", score, weight: 0.25 };
+}
+/** Score based on structural elements (headings, lists, code blocks). */
+function scoreStructure(resource) {
+    const content = resource.content ?? resource.snippet ?? "";
+    let hits = 0;
+    if (/^#{1,6}\s/m.test(content))
+        hits++;
+    if (/^[-*]\s/m.test(content))
+        hits++;
+    if (/```/.test(content))
+        hits++;
+    if (/\n\n/.test(content))
+        hits++;
+    if (/\d+\.\s/.test(content))
+        hits++;
+    const score = Math.min(hits / 3, 1.0);
+    return { signal: "structure", score, weight: 0.2 };
+}
+/** Score based on snippet quality (length, informativeness). */
+function scoreSnippet(resource) {
+    const snippet = resource.snippet ?? "";
+    const len = snippet.length;
+    let score;
+    if (len >= 150)
+        score = 1.0;
+    else if (len >= 80)
+        score = 0.7;
+    else if (len >= 30)
+        score = 0.4;
+    else
+        score = 0.1;
+    // Bonus for snippets that read like informative prose
+    if (/\b(because|therefore|however|specifically|according)\b/i.test(snippet)) {
+        score = Math.min(score + 0.15, 1.0);
+    }
+    return { signal: "snippet_quality", score, weight: 0.2 };
+}
+/** Score based on URL quality signals (trusted domain, protocol, path depth). */
+function scoreUrlQuality(resource) {
+    const domain = extractDomain(resource.url);
+    let score = 0.5; // neutral baseline
+    if (TRUSTED_DOMAINS.has(domain)) {
+        score = 0.9;
+    }
+    // HTTPS bonus (applied before penalty so penalty dominates)
+    if (resource.url.startsWith("https://")) {
+        score = Math.min(score + 0.05, 1.0);
+    }
+    if (LOW_QUALITY_PATTERNS.some((p) => p.test(resource.url))) {
+        score = Math.max(score - 0.4, 0);
+    }
+    return { signal: "url_quality", score, weight: 0.2 };
+}
+/** Score based on title quality. */
+function scoreTitleQuality(resource) {
+    const title = resource.title ?? "";
+    let score = 0.5;
+    if (title.length >= 20 && title.length <= 120)
+        score = 0.8;
+    else if (title.length >= 10)
+        score = 0.6;
+    else
+        score = 0.2;
+    // Penalise clickbait patterns
+    if (/you won't believe|shocking|😱|🔥/i.test(title)) {
+        score = Math.max(score - 0.3, 0);
+    }
+    return { signal: "title_quality", score, weight: 0.15 };
+}
+// ---------------------------------------------------------------------------
+// Main vetter
+// ---------------------------------------------------------------------------
+/**
+ * Vet a resource for quality using content-based heuristics.
+ *
+ * @param resource - A web search result to evaluate.
+ * @param _modelProvider - Reserved for future LLM-enhanced vetting (unused).
+ * @param config - Optional thresholds for accept/reject.
+ * @returns A VetResult with the quality score, signals, and recommendation.
+ */
+export async function vetResource(resource, _modelProvider, config) {
+    const qualityThreshold = config?.qualityThreshold ?? DEFAULT_QUALITY_THRESHOLD;
+    const acceptThreshold = config?.acceptThreshold ?? DEFAULT_ACCEPT_THRESHOLD;
+    const signals = [
+        scoreContentLength(resource),
+        scoreStructure(resource),
+        scoreSnippet(resource),
+        scoreUrlQuality(resource),
+        scoreTitleQuality(resource),
+    ];
+    // Weighted average
+    const totalWeight = signals.reduce((sum, s) => sum + s.weight, 0);
+    const qualityScore = totalWeight > 0
+        ? signals.reduce((sum, s) => sum + s.score * s.weight, 0) / totalWeight
+        : 0;
+    let recommendation;
+    let reason;
+    if (qualityScore >= acceptThreshold) {
+        recommendation = "accept";
+        reason = "Resource meets quality standards";
+    }
+    else if (qualityScore >= qualityThreshold) {
+        recommendation = "review";
+        reason = "Resource quality is borderline — manual review recommended";
+    }
+    else {
+        recommendation = "reject";
+        reason = "Resource quality below threshold";
+    }
+    return {
+        url: resource.url,
+        qualityScore: Math.round(qualityScore * 1000) / 1000,
+        signals,
+        recommendation,
+        reason,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/vetter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vetter/index.ts"],"names":[],"mappings":"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"}