feat: add semantic bias option and update metrics documentation

Why:
The analyzer previously used only keyword bias cues. Users now need an
opt-in mode for transformer-based semantic bias checks. The metrics doc
and README also required updates to explain the new behavior.

What:
- Add --semantic-bias flag to analyse command
- Add semanticBias field through tools, workflow, and analyzer options
- Load semantic bias detector lazily to avoid extra startup cost
- Update metrics doc with keyword vs semantic bias note
- Update README with usage examples for semantic bias mode
- Update structured-report tests for new similarity fields and
  analysis_window section

Author: doguabaris

README.md

@@ -150,10 +150,23 @@ catalog or discover new ones using the lookup command.
 
 1. Run the analyzer:
 
+   ```bash
+   gwaln analyse --topic moon
+   ```
+
+   To bypass cached results and regenerate even if inputs are unchanged:
+
    ```bash
    gwaln analyse --topic moon --force
    ```
 
+   By default, bias cues are keyword-only. Enable transformer-based
+   semantic bias detection (slower, downloads a model) when you need it:
+
+   ```bash
+   gwaln analyse --topic moon --force --semantic-bias
+   ```
+
 2. Review the terminal summary:
 
    ```bash

docs/html-report-metrics.md

@@ -129,6 +129,10 @@ the articles **diverge**. A score near 0.0 means “near-identical /
 likely copied,” and a score near 1.0 means “independent or divergent
 content.” Very high similarity will naturally push the score down.
 
+> Note: Bias cues in the default CLI run come from the keyword detector.
+> Semantic transformer-based bias checks are opt-in (`--semantic-bias`)
+> and take longer because they load a model.
+
 ### How the score is calculated (current behavior)
 
 The score starts at `1 - sentence_similarity`, then applies boosts or

src/commands/analyse.ts

@@ -21,6 +21,7 @@ interface AnalyseCliOptions extends BiasVerifierOptionInput, GeminiSummaryOption
   force?: boolean;
   geminiSummary?: boolean;
   verifyCitations?: boolean;
+  semanticBias?: boolean;
 }
 
 const createCliHooks = (): AnalyzeWorkflowHooks => {
@@ -62,6 +63,10 @@ const analyseCommand = new Command('analyse')
     '--verify-citations',
     'Fetch Grokipedia citations and confirm extra sentences are supported',
   )
+  .option(
+    '--semantic-bias',
+    'Enable transformer-based semantic bias detection (otherwise keyword-only cues are used)',
+  )
   .action(async (options: AnalyseCliOptions) => {
     const verifier = resolveBiasVerifierOptions(options);
     const summary = options.geminiSummary ? resolveGeminiSummaryOptions(options) : null;
@@ -71,6 +76,7 @@ const analyseCommand = new Command('analyse')
       biasVerifier: verifier,
       summary,
       verifyCitations: options.verifyCitations,
+      semanticBias: options.semanticBias,
       hooks: createCliHooks(),
     });
   });

src/lib/analyzer.ts

@@ -31,7 +31,6 @@ import {
   type EntityDiscrepancy,
   type NumericDiscrepancy,
 } from './discrepancies';
-import { detectSemanticBiasBatch } from './semantic-bias-detector';
 import type {
   StructuredArticle,
   StructuredClaim,
@@ -106,6 +105,7 @@ export interface AnalysisMeta {
 
 interface AnalyzerOptions {
   contentHash?: string;
+  semanticBias?: boolean;
 }
 
 export interface GeminiSummary {
@@ -458,6 +458,7 @@ const detectBiasEventsHybrid = async (
   }
 
   const keywordEvents = detectBiasEventsKeywordOnly(extraSentences, wikiText);
+  const { detectSemanticBiasBatch } = await import('./semantic-bias-detector');
 
   const flaggedSentences = new Set(keywordEvents.map((e) => e.evidence.grokipedia!));
   const sampleSize = Math.min(50, Math.ceil(extraSentences.length * 0.1));
@@ -530,7 +531,11 @@ const detectBiasEventsHybrid = async (
 const detectBiasEvents = async (
   extraSentences: string[],
   wikiText: string,
+  enableSemantic: boolean,
 ): Promise<DiscrepancyRecord[]> => {
+  if (!enableSemantic) {
+    return detectBiasEventsKeywordOnly(extraSentences, wikiText);
+  }
   try {
     return await detectBiasEventsHybrid(extraSentences, wikiText);
   } catch (error) {
@@ -1046,7 +1051,8 @@ export const analyzeContent = async (
   const numericDiscrepancies = detectNumericDiscrepancies(claimAlignment);
   const entityDiscrepancies = detectEntityDiscrepancies(claimAlignment);
 
-  const biasEvents = await detectBiasEvents(extra, wikiText);
+  const semanticBiasEnabled = options.semanticBias === true;
+  const biasEvents = await detectBiasEvents(extra, wikiText, semanticBiasEnabled);
   const hallucinationEvents = detectHallucinationEvents(extra, wiki.content.claims);
   const factualErrors = detectFactualErrors(
     claimAlignment,

src/tools/analyze.ts

@@ -19,6 +19,7 @@ export const AnalyzeInputSchema = z.object({
   geminiModel: z.string().optional(),
   geminiSummary: z.boolean().optional(),
   verifyCitations: z.boolean().optional(),
+  semanticBias: z.boolean().optional(),
 });
 
 export const analyzeTool = {
@@ -52,6 +53,7 @@ export const analyzeHandler = async (
     biasVerifier: verifier,
     summary,
     verifyCitations: input.verifyCitations,
+    semanticBias: input.semanticBias,
     logger,
   });
   return {

src/workflows/analyze-workflow.ts

@@ -57,6 +57,7 @@ export interface AnalyzeWorkflowOptions {
   verifyCitations?: boolean;
   logger?: Pick<Console, 'log' | 'warn' | 'error'>;
   hooks?: AnalyzeWorkflowHooks;
+  semanticBias?: boolean;
 }
 
 type WorkflowLogger = Pick<Console, 'log' | 'warn' | 'error'>;
@@ -103,6 +104,7 @@ const buildTopicContext = (topic: Topic): TopicContext => {
 const analyzeTopicSync = async (
   topic: Topic,
   force: boolean | undefined,
+  semanticBias: boolean | undefined,
   context: TopicContext,
   logger: WorkflowLogger,
 ): Promise<AnalysisPayload | null> => {
@@ -123,19 +125,21 @@ const analyzeTopicSync = async (
 
   return await analyzeContent(topic, context.wikiSource, context.grokSource, {
     contentHash: context.contentHash,
+    semanticBias,
   });
 };
 
 const analyzeTopicAsync = (
   topic: Topic,
   force: boolean | undefined,
+  semanticBias: boolean | undefined,
   context: TopicContext,
   logger: WorkflowLogger,
 ): Promise<AnalysisPayload | null> =>
   new Promise((resolve, reject) => {
     setImmediate(async () => {
       try {
-        resolve(await analyzeTopicSync(topic, force, context, logger));
+        resolve(await analyzeTopicSync(topic, force, semanticBias, context, logger));
       } catch (error) {
         reject(error);
       }
@@ -150,6 +154,7 @@ export const runAnalyzeWorkflow = async ({
   verifyCitations,
   logger,
   hooks,
+  semanticBias,
 }: AnalyzeWorkflowOptions): Promise<AnalyzeTopicResult[]> => {
   const topics = loadTopics();
   const selection = selectTopics(topics, topicId);
@@ -177,7 +182,7 @@ export const runAnalyzeWorkflow = async ({
     }
 
     try {
-      const analysis = await analyzeTopicAsync(topic, force, context, activeLogger);
+      const analysis = await analyzeTopicAsync(topic, force, semanticBias, context, activeLogger);
       if (!analysis) {
         const result: AnalyzeTopicResult = {
           topicId: topic.id,