🔬 Deep-Inspection Generator: Multi-Iteration Intelligence Report Architecture

scripts/deep-inspection/index.ts

@@ -0,0 +1,83 @@
+/**
+ * @module deep-inspection
+ * @description DeepInspectionPipeline — thin programmatic entrypoint wrapper
+ * around `generateDeepInspection()`.
+ *
+ * The underlying generator performs collection, analysis, synthesis, and
+ * rendering internally. This class intentionally does not re-implement those
+ * phases; it only delegates execution and returns enriched run metadata.
+ *
+ * @example
+ * ```typescript
+ * const pipeline = new DeepInspectionPipeline();
+ * const result = await pipeline.run();
+ * ```
+ *
+ * @author Hack23 AB
+ * @license Apache-2.0
+ */
+
+import { generateDeepInspection } from '../generate-news-enhanced/generators.js';
+import { analysisDepth, focusTopic } from '../generate-news-enhanced/config.js';
+import type { GenerationResult } from '../types/article.js';
+
+/**
+ * Result produced by a pipeline run.
+ * Extends GenerationResult with optional depth and topic metadata.
+ */
+export interface DeepInspectionResult extends GenerationResult {
+  /** Effective analysis depth used. */
+  depth: 1 | 2 | 3 | 4;
+  /** Focus topic if provided. */
+  topic?: string;
+}
+
+/**
+ * DeepInspectionPipeline delegates execution to
+ * `generateDeepInspection()` in generators.ts, which
+ * reads targeting parameters and `analysisDepth` from CLI config. When used
+ * programmatically via this class, those CLI values are already set at module
+ * load time — so `run()` simply invokes the generator and enriches the result.
+ *
+ * All targeting (document IDs, URLs) and analysis depth are controlled via CLI
+ * arguments parsed by `config.ts` at module load time. This class provides a
+ * clean programmatic entrypoint without duplicating CLI parameter handling.
+ */
+export class DeepInspectionPipeline {
+  /**
+   * Phase labels for logging purposes.
+   * @internal
+   */
+  private phaseLabel(depth: 1 | 2 | 3 | 4): string {
+    const labels: Record<1 | 2 | 3 | 4, string> = {
+      1: 'Surface analysis — events & actors',
+      2: 'Predictive + historical context',
+      3: 'Full report with executive summary & methodology',
+      4: 'Full multi-iteration intelligence report',
+    };
+    return labels[depth];
+  }
+
+  /**
+   * Run deep-inspection generation via the underlying generator wrapper.
+   *
+   * @returns DeepInspectionResult with success status, file count, and slug
+   */
+  async run(): Promise<DeepInspectionResult> {
+    const depth = analysisDepth;
+    const topic = focusTopic || undefined;
+
+    console.log(`🔬 DeepInspectionPipeline starting — depth ${depth}: ${this.phaseLabel(depth)}`);
+    if (topic) console.log(`   Topic: ${topic}`);
+
+    const result = await generateDeepInspection();
+
+    return {
+      ...result,
+      depth,
+      topic,
+    };
+  }
+}
+
+export default DeepInspectionPipeline;

scripts/generate-news-enhanced/config.ts

@@ -45,10 +45,11 @@ export const skipExistingArg: boolean = args.includes('--skip-existing');
 export const batchSize: number = batchSizeArg ? parseInt(parseArgValue(batchSizeArg) || '0', 10) : 0;
 const qualityThresholdArg: string | undefined = args.find(arg => arg.startsWith('--quality-threshold='));
 
-// Deep-inspection arguments: document IDs, URLs, and focus topic for targeted analysis
+// Deep-inspection arguments: document IDs, URLs, focus topic, and analysis depth
 const documentIdsArg: string | undefined = args.find(arg => arg.startsWith('--document-ids='));
 const documentUrlsArg: string | undefined = args.find(arg => arg.startsWith('--document-urls='));
 const focusTopicArg: string | undefined = args.find(arg => arg.startsWith('--focus-topic='));
+const depthArg: string | undefined = args.find(arg => arg.startsWith('--depth='));
 
 /** Comma-separated Riksdag document IDs for deep-inspection (e.g. H901FiU1,H901JuU25) */
 const rawDocumentIds: string = parseArgValue(documentIdsArg);
@@ -65,6 +66,26 @@ export const documentUrls: string[] = rawDocumentUrls
 /** Specific policy topic to focus deep-inspection analysis on */
 export const focusTopic: string = parseArgValue(focusTopicArg);
 
+/**
+ * Analysis depth for deep-inspection (1–4).
+ *  1 — surface analysis (what happened) — default, fastest
+ *  2 — adds predictive assessment and historical context
+ *  3 — adds executive intelligence summary and methodology (3 iterations)
+ *  4 — full report: adds quality-review iteration in methodology (4 iterations)
+ */
+const rawDepth: string = parseArgValue(depthArg);
+const depthArgProvided: boolean = !!depthArg;
+const parsedDepthNum: number = rawDepth ? Number(rawDepth) : NaN;
+const depthIsValid: boolean = Number.isInteger(parsedDepthNum) && parsedDepthNum >= 1 && parsedDepthNum <= 4;
+if (depthArgProvided && !depthIsValid) {
+  console.warn(`Invalid --depth value "${rawDepth}" (expected integer 1–4), falling back to default 1.`);
+}
+const safeDepth: number = depthIsValid ? parsedDepthNum : 1;
+export const analysisDepth: 1 | 2 | 3 | 4 =
+  safeDepth === 4 ? 4 :
+  safeDepth === 3 ? 3 :
+  safeDepth === 2 ? 2 :
+  1;
 // --iterations=N: number of AI analysis iterations for deep-inspection (default: 3)
 const iterationsArg: string | undefined = args.find(arg => arg.startsWith('--iterations='));
 const DEFAULT_ITERATIONS = 3;
@@ -93,8 +114,8 @@ export const analysisIterations: number = parsedIterations;
  * - `standard` — 2 passes (initial + SWOT refinement; default)
  * - `deep`     — 3 passes (initial + refinement + stakeholder validation)
  */
-const analysisDepthArg: string | undefined = args.find(arg => arg.startsWith('--analysis-depth='));
-const rawAnalysisDepth: string = parseArgValue(analysisDepthArg ?? '').toLowerCase();
+const analysisModeArg: string | undefined = args.find(arg => arg.startsWith('--analysis-depth='));
+const rawAnalysisMode: string = parseArgValue(analysisModeArg ?? '').toLowerCase();
 const VALID_ANALYSIS_DEPTHS: readonly AnalysisDepth[] = ['quick', 'standard', 'deep'];
 
 function parseAnalysisDepth(raw: string): AnalysisDepth {
@@ -107,7 +128,7 @@ function parseAnalysisDepth(raw: string): AnalysisDepth {
   return 'standard';
 }
 
-export const analysisDepth: AnalysisDepth = parseAnalysisDepth(rawAnalysisDepth);
+export const analysisMode: AnalysisDepth = parseAnalysisDepth(rawAnalysisMode);
 
 const DEFAULT_QUALITY_THRESHOLD = 40;
 let parsedQualityThreshold: number = DEFAULT_QUALITY_THRESHOLD;