@michaelborck/honeyguide-core 0.6.0 → 0.7.0

package/README.md

@@ -8,3 +8,7 @@ Shared logic for Honeyguide: retrieval, verification, ranking and rationale.
   ([ADR-0002](../../docs/adr/0002-extend-cite-sight-core-for-verification.md)).
 - Every enrichment step degrades non-fatally
   ([ADR-0006](../../docs/adr/0006-non-fatal-degradation.md)).
+- Paper discovery is multi-source — OpenAlex, Semantic Scholar, Europe PMC and
+  arXiv, merged and deduplicated, with Crossref as the fallback. Web search
+  goes through a pluggable provider (SearXNG, Brave or Serper)
+  ([ADR-0013](../../docs/adr/0013-multi-source-paper-retrieval-and-search-providers.md)).

package/dist/align/outcomes.d.ts

@@ -0,0 +1,75 @@
+import type { Alignment, Outcome, Resource } from '../types.js';
+import type { PipelineConfig } from '../config.js';
+import { type EmbeddingProvider } from '../rank/embeddings.js';
+export declare const MAX_ALIGN_RESOURCES = 12;
+export declare const MAX_ALIGN_OUTCOMES = 8;
+/**
+ * Extract outcomes from a plain list or a pasted unit outline. When an
+ * "Outcomes" heading is present, only that section is used; otherwise every
+ * non-structural line is a candidate. List markers, numbering and outcome
+ * codes (LO1, CLO2…) are stripped.
+ */
+export declare function parseOutcomes(text: string): Outcome[];
+export interface AlignmentQuestion {
+    type: 'choice';
+    instructions: string;
+    criteria: Record<string, string>;
+}
+export interface AlignmentRequest {
+    model: string;
+    state: {
+        topic: string;
+        outcomes: Array<{
+            id: string;
+            text: string;
+        }>;
+        resources: Array<{
+            id: string;
+            title: string;
+            venue?: string;
+            description?: string;
+        }>;
+    };
+    questions: Record<string, AlignmentQuestion>;
+    keep_alive: string;
+}
+export interface BuiltAlignmentRequest {
+    request: AlignmentRequest;
+    resourceById: Map<string, Resource>;
+    outcomeById: Map<string, Outcome>;
+}
+/**
+ * Build one `/v1/systemone` request: a Choice per resource over the outcome
+ * list plus `none`. Choice probabilities let us keep near-ties instead of
+ * blindly trusting a `none` that won by a rounding error.
+ */
+export declare function buildAlignmentRequest(topic: string, resources: Resource[], outcomes: Outcome[], model: string): BuiltAlignmentRequest;
+export declare function parseAlignmentResponse(response: unknown, resourceById: Map<string, Resource>, outcomeById: Map<string, Outcome>): Map<Resource, Alignment>;
+export interface OutcomeAligner {
+    readonly name: 'decision' | 'embeddings';
+    align(topic: string, resources: Resource[], outcomes: Outcome[]): Promise<Map<Resource, Alignment>>;
+}
+/**
+ * Local System One alignment (ADR-0017): one Choice per resource. Preferred
+ * because it reasons about fit rather than surface similarity.
+ */
+export declare class OllamaOutcomeAligner implements OutcomeAligner {
+    private readonly baseUrl;
+    private readonly model;
+    private readonly apiKey?;
+    readonly name = "decision";
+    constructor(baseUrl: string, model?: string, apiKey?: string | undefined);
+    align(topic: string, resources: Resource[], outcomes: Outcome[]): Promise<Map<Resource, Alignment>>;
+}
+/**
+ * Embedding fallback: cosine similarity between each resource and outcome.
+ * Less precise than a Choice, but works anywhere embeddings do.
+ */
+export declare class EmbeddingOutcomeAligner implements OutcomeAligner {
+    private readonly provider;
+    readonly name = "embeddings";
+    constructor(provider: EmbeddingProvider);
+    align(_topic: string, resources: Resource[], outcomes: Outcome[]): Promise<Map<Resource, Alignment>>;
+}
+/** Pick the configured aligner: decision model first, embeddings second. */
+export declare function createOutcomeAligner(config: PipelineConfig): OutcomeAligner | null;

package/dist/align/outcomes.js

@@ -0,0 +1,266 @@
+import { createEmbeddingProvider } from '../rank/embeddings.js';
+import { cosineSimilarity } from '../rank/semantic.js';
+const TIMEOUT_MS = 30_000;
+export const MAX_ALIGN_RESOURCES = 12;
+export const MAX_ALIGN_OUTCOMES = 8;
+const MAX_TEXT_CHARS = 240;
+const EMBEDDING_MIN_SCORE = 0.35;
+const OUTCOMES_HEADING = /^(?:(?:learning|intended|course|unit|subject|module|program|programme|graduate)\s+)*outcomes?$|^(?:ilos?|clos?|ulos?|slos?)$/i;
+const OTHER_HEADING = /^(?:week|module|topic|unit|lecture|seminar|workshop|assessment|assessments|resources|readings?|activities|schedule|content|description|overview|introduction)\b/i;
+/**
+ * Extract outcomes from a plain list or a pasted unit outline. When an
+ * "Outcomes" heading is present, only that section is used; otherwise every
+ * non-structural line is a candidate. List markers, numbering and outcome
+ * codes (LO1, CLO2…) are stripped.
+ */
+export function parseOutcomes(text) {
+    const lines = text.split(/\r?\n/);
+    let start = 0;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (OUTCOMES_HEADING.test(heading(lines[i]))) {
+            start = i + 1;
+            break;
+        }
+    }
+    const hasOutcomesHeading = start > 0;
+    const seen = new Set();
+    const texts = [];
+    for (let i = start; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        const clean = heading(line);
+        if (OUTCOMES_HEADING.test(clean))
+            continue;
+        if (OTHER_HEADING.test(clean)) {
+            if (hasOutcomesHeading)
+                break;
+            continue;
+        }
+        const outcome = stripPrefix(line);
+        if (outcome.length < 8)
+            continue;
+        const key = outcome.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        texts.push(outcome);
+    }
+    return texts.map((outcomeText, index) => ({ id: `o${index}`, text: outcomeText }));
+}
+/** A line reduced to its section-heading text, or '' if it is not a heading. */
+function heading(line) {
+    return line
+        .replace(/^[#*\s]+/, '')
+        .replace(/[*\s]+$/, '')
+        .replace(/:$/, '')
+        .trim();
+}
+function stripPrefix(line) {
+    return line
+        .replace(/^\s*(?:[-*•·▪]|\d+(?:\.\d+)*[.)]?)\s*/, '')
+        .replace(/^(?:LO|ILO|CLO|ULO|SLO)\s*\d+\s*[:.)-]?\s*/i, '')
+        .replace(/^students?\s+(?:will|should)\s+be\s+able\s+to\s+/i, '')
+        .replace(/^students?\s+can\s+/i, '')
+        .replace(/^be\s+able\s+to\s+/i, '')
+        .trim();
+}
+/**
+ * Build one `/v1/systemone` request: a Choice per resource over the outcome
+ * list plus `none`. Choice probabilities let us keep near-ties instead of
+ * blindly trusting a `none` that won by a rounding error.
+ */
+export function buildAlignmentRequest(topic, resources, outcomes, model) {
+    const outcomeList = outcomes.slice(0, MAX_ALIGN_OUTCOMES);
+    const resourceList = resources.slice(0, MAX_ALIGN_RESOURCES);
+    const resourceById = new Map();
+    const outcomeById = new Map();
+    const criteria = {};
+    for (const outcome of outcomeList) {
+        outcomeById.set(outcome.id, outcome);
+        criteria[outcome.id] = outcome.text.slice(0, MAX_TEXT_CHARS);
+    }
+    criteria.none = 'None of the outcomes fit this resource.';
+    const questions = {};
+    const stateResources = [];
+    resourceList.forEach((resource, index) => {
+        const id = `r${index}`;
+        resourceById.set(id, resource);
+        stateResources.push({
+            id,
+            title: resource.title.slice(0, 180),
+            venue: resource.venue?.slice(0, 80),
+            description: resource.annotation.text?.slice(0, MAX_TEXT_CHARS),
+        });
+        questions[id] = {
+            type: 'choice',
+            instructions: `Which \`outcomes\` entry does \`resources[${index}]\` best help a ` +
+                `lecturer teach? Choose \`none\` if no outcome fits.`,
+            criteria,
+        };
+    });
+    return {
+        request: {
+            model,
+            state: {
+                topic: topic.slice(0, 300),
+                outcomes: outcomeList.map((outcome) => ({
+                    id: outcome.id,
+                    text: outcome.text.slice(0, MAX_TEXT_CHARS),
+                })),
+                resources: stateResources,
+            },
+            questions,
+            keep_alive: '5m',
+        },
+        resourceById,
+        outcomeById,
+    };
+}
+export function parseAlignmentResponse(response, resourceById, outcomeById) {
+    const answers = response?.answers ?? {};
+    const result = new Map();
+    for (const [resourceId, resource] of resourceById) {
+        const answer = answers[resourceId];
+        if (!answer || answer.type !== 'choice')
+            continue;
+        const probabilities = answer.probabilities ?? {};
+        const noneProbability = probabilities.none ?? 0;
+        let chosen = answer.choice ?? 'none';
+        let forcedLow = false;
+        if (chosen === 'none') {
+            const best = [...outcomeById.keys()]
+                .map((id) => ({ id, probability: probabilities[id] ?? 0 }))
+                .sort((a, b) => b.probability - a.probability)[0];
+            // The small decision model sometimes puts `none` a hair ahead of a
+            // genuinely close outcome. Keep it as a low-confidence proposal.
+            if (best && best.probability >= 0.35 && best.probability >= noneProbability * 0.8) {
+                chosen = best.id;
+                forcedLow = true;
+            }
+            else {
+                continue;
+            }
+        }
+        const outcome = outcomeById.get(chosen);
+        if (!outcome)
+            continue;
+        const score = probabilities[chosen] ?? answer.confidence ?? 0;
+        result.set(resource, {
+            outcomeId: outcome.id,
+            outcomeText: outcome.text,
+            score,
+            confidence: forcedLow ? 'low' : confidenceBand(score),
+            proposedBy: 'decision',
+            confirmed: false,
+        });
+    }
+    return result;
+}
+/**
+ * Local System One alignment (ADR-0017): one Choice per resource. Preferred
+ * because it reasons about fit rather than surface similarity.
+ */
+export class OllamaOutcomeAligner {
+    baseUrl;
+    model;
+    apiKey;
+    name = 'decision';
+    constructor(baseUrl, model = 'tev1:0.8b', apiKey) {
+        this.baseUrl = baseUrl;
+        this.model = model;
+        this.apiKey = apiKey;
+    }
+    async align(topic, resources, outcomes) {
+        const { request, resourceById, outcomeById } = buildAlignmentRequest(topic, resources, outcomes, this.model);
+        if (!Object.keys(request.questions).length)
+            return new Map();
+        const headers = { 'content-type': 'application/json' };
+        if (this.apiKey)
+            headers.authorization = `Bearer ${this.apiKey}`;
+        const res = await fetch(`${this.baseUrl.replace(/\/$/, '')}/v1/systemone`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`Ollama System One HTTP ${res.status}`);
+        return parseAlignmentResponse(await res.json(), resourceById, outcomeById);
+    }
+}
+/**
+ * Embedding fallback: cosine similarity between each resource and outcome.
+ * Less precise than a Choice, but works anywhere embeddings do.
+ */
+export class EmbeddingOutcomeAligner {
+    provider;
+    name = 'embeddings';
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async align(_topic, resources, outcomes) {
+        const outcomeList = outcomes.slice(0, MAX_ALIGN_OUTCOMES);
+        const resourceList = resources.slice(0, MAX_ALIGN_RESOURCES);
+        if (!outcomeList.length || !resourceList.length)
+            return new Map();
+        const texts = [
+            ...outcomeList.map((outcome) => outcome.text),
+            ...resourceList.map(resourceText),
+        ];
+        const vectors = await this.provider.embed(texts);
+        if (vectors.length !== texts.length) {
+            throw new Error('embedding count did not match the request');
+        }
+        const outcomeVectors = vectors.slice(0, outcomeList.length);
+        const resourceVectors = vectors.slice(outcomeList.length);
+        const result = new Map();
+        resourceList.forEach((resource, resourceIndex) => {
+            let bestOutcome = null;
+            let bestScore = -1;
+            for (let outcomeIndex = 0; outcomeIndex < outcomeList.length; outcomeIndex++) {
+                const score = cosineSimilarity(resourceVectors[resourceIndex], outcomeVectors[outcomeIndex]);
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestOutcome = outcomeList[outcomeIndex];
+                }
+            }
+            if (bestOutcome && bestScore >= EMBEDDING_MIN_SCORE) {
+                result.set(resource, {
+                    outcomeId: bestOutcome.id,
+                    outcomeText: bestOutcome.text,
+                    score: bestScore,
+                    confidence: confidenceBand(bestScore),
+                    proposedBy: 'embeddings',
+                    confirmed: false,
+                });
+            }
+        });
+        return result;
+    }
+}
+/** Pick the configured aligner: decision model first, embeddings second. */
+export function createOutcomeAligner(config) {
+    if (config.decisionUrl) {
+        return new OllamaOutcomeAligner(config.decisionUrl, config.decisionModel ?? 'tev1:0.8b', config.decisionApiKey);
+    }
+    if (config.embeddingUrl) {
+        const provider = createEmbeddingProvider(config);
+        return provider ? new EmbeddingOutcomeAligner(provider) : null;
+    }
+    return null;
+}
+function resourceText(resource) {
+    return [resource.title, resource.venue, resource.annotation.text]
+        .filter(Boolean)
+        .join('. ')
+        .slice(0, 400);
+}
+function confidenceBand(score) {
+    if (score >= 0.7)
+        return 'high';
+    if (score >= 0.45)
+        return 'medium';
+    return 'low';
+}
+//# sourceMappingURL=outcomes.js.map

package/dist/align/outcomes.js.map

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

package/dist/align/reasons.d.ts

@@ -0,0 +1,11 @@
+import type { Resource } from '../types.js';
+import type { PipelineConfig } from '../config.js';
+/** The prompt for a one-line "why this outcome" reason. */
+export declare function buildAlignmentReasonPrompt(topic: string, outcomeText: string, resource: Resource): string;
+export declare function generateAlignmentReason(topic: string, outcomeText: string, resource: Resource, config: PipelineConfig): Promise<string | undefined>;
+/**
+ * Fill in `alignment.reason` for up to a few resources with the local LLM.
+ * Optional and non-fatal: no LLM, a timeout or a bad response simply leaves
+ * the reason absent.
+ */
+export declare function addAlignmentReasons(resources: Resource[], topic: string, config: PipelineConfig): Promise<void>;

package/dist/align/reasons.js

@@ -0,0 +1,84 @@
+const TIMEOUT_MS = 12_000;
+// Alignment is capped at 12 resources; generating reasons for all of them
+// with a local LLM is slow, so only the first few proposals get prose.
+const MAX_REASONS = 6;
+const REASON_CONCURRENCY = 3;
+/** The prompt for a one-line "why this outcome" reason. */
+export function buildAlignmentReasonPrompt(topic, outcomeText, resource) {
+    const meta = [
+        resource.title,
+        resource.venue ? `Venue: ${resource.venue}` : null,
+        resource.year ? `Year: ${resource.year}` : null,
+        resource.annotation.text
+            ? `Description: ${resource.annotation.text.slice(0, 400)}`
+            : null,
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return (`A lecturer is teaching: "${topic.slice(0, 300)}"\n\n` +
+        `Unit outcome: "${outcomeText.slice(0, 300)}"\n\n` +
+        `Resource:\n${meta}\n\n` +
+        `In one short sentence, say specifically how this resource helps students ` +
+        `meet that outcome. Do not invent details not present above. ` +
+        `Reply with the sentence only.`);
+}
+export async function generateAlignmentReason(topic, outcomeText, resource, config) {
+    if (!config.ollamaUrl)
+        return undefined;
+    const res = await fetch(`${config.ollamaUrl.replace(/\/$/, '')}/api/generate`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            ...(config.ollamaApiKey
+                ? { authorization: `Bearer ${config.ollamaApiKey}` }
+                : {}),
+        },
+        body: JSON.stringify({
+            model: config.ollamaModel ?? 'llama3.1:8b',
+            prompt: buildAlignmentReasonPrompt(topic, outcomeText, resource),
+            stream: false,
+            think: false,
+            options: { num_predict: 80, temperature: 0.2 },
+        }),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!res.ok)
+        throw new Error(`Ollama HTTP ${res.status}`);
+    const data = (await res.json());
+    const line = data.response?.trim().split('\n')[0]?.trim();
+    return line ? line.slice(0, 240) : undefined;
+}
+/**
+ * Fill in `alignment.reason` for up to a few resources with the local LLM.
+ * Optional and non-fatal: no LLM, a timeout or a bad response simply leaves
+ * the reason absent.
+ */
+export async function addAlignmentReasons(resources, topic, config) {
+    if (!config.ollamaUrl || config.alignmentReasons === false)
+        return;
+    const targets = resources.filter((resource) => resource.alignment).slice(0, MAX_REASONS);
+    if (!targets.length)
+        return;
+    await mapLimit(targets, REASON_CONCURRENCY, async (resource) => {
+        const alignment = resource.alignment;
+        try {
+            const reason = await generateAlignmentReason(topic, alignment.outcomeText, resource, config);
+            if (reason)
+                alignment.reason = reason;
+        }
+        catch {
+            // reasons are a bonus, never a failure
+        }
+    });
+}
+async function mapLimit(items, limit, fn) {
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const i = next++;
+            await fn(items[i]);
+        }
+    });
+    await Promise.all(workers);
+}
+//# sourceMappingURL=reasons.js.map

package/dist/align/reasons.js.map

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

package/dist/annotate/ladder.d.ts

@@ -8,4 +8,4 @@ import type { PipelineConfig } from '../config.js';
  *   2. extractive description from retrieval/page metadata
  *   3. nothing — metadata-only result
  */
-export declare function annotate(topic: string, candidate: Candidate, config: PipelineConfig, llmWanted: boolean, stance?: 'supporting' | 'counterpoint'): Promise<Annotation>;
+export declare function annotate(topic: string, candidate: Candidate, config: PipelineConfig, llmWanted: boolean, stance?: 'supporting' | 'counterpoint', context?: string): Promise<Annotation>;

package/dist/annotate/ladder.js

@@ -6,12 +6,12 @@ import { generateRationale } from './ollama.js';
  *   2. extractive description from retrieval/page metadata
  *   3. nothing — metadata-only result
  */
-export async function annotate(topic, candidate, config, llmWanted, stance = 'supporting') {
+export async function annotate(topic, candidate, config, llmWanted, stance = 'supporting', context) {
     if (llmWanted && config.ollamaUrl) {
         try {
             return {
                 source: 'llm',
-                text: await generateRationale(topic, candidate, config, stance),
+                text: await generateRationale(topic, candidate, config, stance, context),
             };
         }
         catch {

package/dist/annotate/ladder.js.map

@@ -1 +1 @@
-{"version":3,"file":"ladder.js","sourceRoot":"","sources":["../../src/annotate/ladder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAa,EACb,SAAoB,EACpB,MAAsB,EACtB,SAAkB,EAClB,SAAwC,YAAY;IAEpD,IAAI,SAAS,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO;gBACL,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,MAAM,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;aAChE,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAChD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS,EAAE,GAAW;IACtC,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC;AACnE,CAAC"}
+{"version":3,"file":"ladder.js","sourceRoot":"","sources":["../../src/annotate/ladder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAa,EACb,SAAoB,EACpB,MAAsB,EACtB,SAAkB,EAClB,SAAwC,YAAY,EACpD,OAAgB;IAEhB,IAAI,SAAS,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO;gBACL,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,MAAM,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC;aACzE,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAChD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS,EAAE,GAAW;IACtC,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC;AACnE,CAAC"}

package/dist/annotate/ollama.d.ts

@@ -1,9 +1,11 @@
 import type { Candidate } from '../retrieval/candidates.js';
 import type { PipelineConfig } from '../config.js';
+/** The rationale prompt, including optional teaching context (ADR-0018). */
+export declare function buildRationalePrompt(topic: string, candidate: Candidate, stance?: 'supporting' | 'counterpoint', context?: string): string;
 /**
  * Generate a one-to-two sentence relational rationale (ADR-0011 rung 1).
  * Prompt is sized for 4B–8B models (spec §8): short, concrete, no format
  * tricks. The LLM only writes ABOUT a resource retrieval already found —
  * it can never introduce one.
  */
-export declare function generateRationale(topic: string, candidate: Candidate, config: PipelineConfig, stance?: 'supporting' | 'counterpoint'): Promise<string>;
+export declare function generateRationale(topic: string, candidate: Candidate, config: PipelineConfig, stance?: 'supporting' | 'counterpoint', context?: string): Promise<string>;

package/dist/annotate/ollama.js

@@ -1,14 +1,7 @@
 const GENERATE_TIMEOUT_MS = 30_000;
 const DEFAULT_MODEL = 'llama3.1:8b';
-/**
- * Generate a one-to-two sentence relational rationale (ADR-0011 rung 1).
- * Prompt is sized for 4B–8B models (spec §8): short, concrete, no format
- * tricks. The LLM only writes ABOUT a resource retrieval already found —
- * it can never introduce one.
- */
-export async function generateRationale(topic, candidate, config, stance = 'supporting') {
-    if (!config.ollamaUrl)
-        throw new Error('no Ollama configured');
+/** The rationale prompt, including optional teaching context (ADR-0018). */
+export function buildRationalePrompt(topic, candidate, stance = 'supporting', context) {
     const meta = [
         `Title: ${candidate.title}`,
         candidate.authors.length ? `By: ${candidate.authors.slice(0, 3).join(', ')}` : null,
@@ -24,11 +17,23 @@ export async function generateRationale(topic, candidate, config, stance = 'supp
             `and why showing students a counterpoint here could be valuable.`
         : `In one or two sentences, say why this resource could support that teaching, ` +
             `what it adds, and (if apparent) what it does not cover.`;
-    const prompt = `A lecturer is teaching: "${topic.slice(0, 300)}"\n\n` +
+    return ((context ? `Teaching context: ${context.slice(0, 400)}\n\n` : '') +
+        `A lecturer is teaching: "${topic.slice(0, 300)}"\n\n` +
         `Candidate ${stance === 'counterpoint' ? 'counterpoint' : 'supporting'} resource:\n${meta}\n\n` +
         `${ask} ` +
         `Be concrete and honest; do not invent details not present above. ` +
-        `Reply with the sentences only.`;
+        `Reply with the sentences only.`);
+}
+/**
+ * Generate a one-to-two sentence relational rationale (ADR-0011 rung 1).
+ * Prompt is sized for 4B–8B models (spec §8): short, concrete, no format
+ * tricks. The LLM only writes ABOUT a resource retrieval already found —
+ * it can never introduce one.
+ */
+export async function generateRationale(topic, candidate, config, stance = 'supporting', context) {
+    if (!config.ollamaUrl)
+        throw new Error('no Ollama configured');
+    const prompt = buildRationalePrompt(topic, candidate, stance, context);
     const res = await fetch(`${config.ollamaUrl.replace(/\/$/, '')}/api/generate`, {
         method: 'POST',
         headers: {
@@ -39,6 +44,7 @@ export async function generateRationale(topic, candidate, config, stance = 'supp
             model: config.ollamaModel ?? DEFAULT_MODEL,
             prompt,
             stream: false,
+            think: false,
             options: { num_predict: 120, temperature: 0.3 },
         }),
         signal: AbortSignal.timeout(GENERATE_TIMEOUT_MS),

package/dist/annotate/ollama.js.map

@@ -1 +1 @@
-{"version":3,"file":"ollama.js","sourceRoot":"","sources":["../../src/annotate/ollama.ts"],"names":[],"mappings":"AAGA,MAAM,mBAAmB,GAAG,MAAM,CAAC;AACnC,MAAM,aAAa,GAAG,aAAa,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAa,EACb,SAAoB,EACpB,MAAsB,EACtB,SAAwC,YAAY;IAEpD,IAAI,CAAC,MAAM,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG;QACX,UAAU,SAAS,CAAC,KAAK,EAAE;QAC3B,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;QACnF,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QACjD,SAAS,SAAS,CAAC,MAAM,EAAE;QAC3B,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,gBAAgB,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;KACrF;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,GAAG,GACP,MAAM,KAAK,cAAc;QACvB,CAAC,CAAC,6DAA6D;YAC7D,iEAAiE;YACjE,iEAAiE;QACnE,CAAC,CAAC,8EAA8E;YAC9E,yDAAyD,CAAC;IAChE,MAAM,MAAM,GACV,4BAA4B,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO;QACtD,aAAa,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,eAAe,IAAI,MAAM;QAC/F,GAAG,GAAG,GAAG;QACT,mEAAmE;QACnE,gCAAgC,CAAC;IAEnC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,EAAE;QAC7E,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnF;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,KAAK,EAAE,MAAM,CAAC,WAAW,IAAI,aAAa;YAC1C,MAAM;YACN,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE;SAChD,CAAC;QACF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,mBAAmB,CAAC;KACjD,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0B,CAAC;IACzD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACpD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"ollama.js","sourceRoot":"","sources":["../../src/annotate/ollama.ts"],"names":[],"mappings":"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"}

package/dist/brief.d.ts

@@ -0,0 +1,30 @@
+import type { SearchConstraints } from './types.js';
+import type { Candidate } from './retrieval/candidates.js';
+/** The four deterministic interview questions (ADR-0018). */
+export interface BriefAnswers {
+    stance: 'support' | 'challenge' | 'both';
+    priorKnowledge: 'none' | 'reading' | 'lecture' | 'notes';
+    /** Optional free-text clarification about prior knowledge. */
+    priorNote?: string;
+    timing: 'pre-class' | 'in-class' | 'post-class' | 'assessment';
+    openAccessOnly?: boolean;
+    noVideo?: boolean;
+    recentOnly?: boolean;
+}
+export interface CompiledBrief {
+    counterpoint: boolean;
+    constraints: SearchConstraints;
+    /** Teaching context passed to the annotator. Retrieval is unchanged. */
+    context: string;
+}
+/**
+ * Turn the interview answers into the fields the pipeline already understands:
+ * a counterpoint flag, search constraints and a teaching-context string.
+ */
+export declare function compileBrief(answers: BriefAnswers, currentYear?: number): CompiledBrief;
+/**
+ * Apply brief constraints to candidates before ranking. `openAccessOnly` is
+ * best-effort: only papers explicitly flagged as subscription are dropped;
+ * unknown access is kept (and labelled later).
+ */
+export declare function applyConstraints(candidates: Candidate[], constraints?: SearchConstraints): Candidate[];