feat(stage12): implement Research Orchestrator

2026-08-26 10:29:57 +00:00
parent 825aedb057
commit 2ef7b67002
6 changed files with 1392 additions and 35 deletions
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -27,24 +27,57 @@ Webquellen recherchieren, Inhalte extrahieren, Quellen/Claims vergleichen, neutr
 | 6 | Source Independence & Citation Graph (Syndication-Erkennung, similarity) | `a60cf21` | 4 | 43 |
 | 7 | Claim Clustering & Contradiction Candidates (LLM-Clustering, numerische Normalisierung) | `d1e6bb6` | 6 | 79 |
 | 8 | Evidence Scoring (6-dimensionale Scores, evidence_type, raw_scores_json) | `719e218` | 6 | ~60 |
+| 9 | Neutral Synthesis Engine | `d87e2b4` | 1 | 25 |
+| 10 | Vision Integration — Qwen2.5-VL-3B für Diagramme, Screenshots, Infografiken, PDF-Layouts | `3ab875d` | 6 | ~25 |
+| 11 | Audio Integration — STT-Transkription mit timestamped Claims | `10a083a` | 8 | ~20 |
+| **12** | **Research Orchestrator — State Machine + Budget Limits + Pipeline-Steuerung** | **`<NEXT>`** | **4** | **0** |

-**Gesamt:** 86 Dateien, ~12000 Zeilen Code, ~268 Tests.
+**Gesamt:** ~100 Dateien, ~15000 Zeilen Code, ~300 Tests.

 ---

-## Stage 8 – Evidence Scoring (abgeschlossen, commit `719e218`)
+## Stage 12 – Research Orchestrator (abgeschlossen)

- **EvidenceScoreModel** mit 6 Score-Dimensionen:
-  - `source_independence_score` – 0.0-1.0, aus Stage 6 gelesen
-  - `primary_source_proximity` – enum: DIRECT(1.0), SYNDICATED(0.6), DERIVED(0.3), UNKNOWN(0.0)
-  - `cross_source_support` – wie viele Quellen unterstützen denselben Claim
-  - `contradiction_level` – wie stark widersprechen Quellen (1.0 = alle unterstützen, 0.0 = starker Dissens)
-  - `evidence_directness` – 1.0 = direkter Befund, 0.0 = Spekulation
-  - `date_relevance_score` – age_days / 365, max 1 Jahr
-  - `evidence_type` – DIRECT_OBSERVATION, SECONDARY_REPORT, ANALYSIS, OPINION, SPECULATION
- **EvidenceScoreRelationModel** – Relationen zwischen Scores und Claims
- **raw_scores_json** – alle Rohdaten für Auditability
- Kein einziger "truth_score" – transparente multidimensionale Scores
+Implementiert die zentrale Orchestrator-Klasse, die alle Stages (1–11) verbindet.
+
+### Kernkomponenten
+
+**`src/nsct/orchestration/state.py`** — State Machine
+- `ResearchRunState` Enum: CREATED, PLANNING, SEARCHING, FETCHING, EXTRACTING, ANALYZING, EXPANDING, COMPARING, SYNTHESIZING, COMPLETED, FAILED, CANCELLED
+- Transition Matrix mit validierten Übergängen
+- FAILED/CANCELLED/COMPLETED sind Terminal-States (keine ausgehenden Transitionen)
+- StateMachine.transition(new_state) mit Logging und Validierung
+
+**`src/nsct/orchestration/budget.py`** — Hard Budget Limits
+- `HardBudgetConfig` (Pydantic, frozen=True): 7 Limits (max_search_queries, max_sources, max_pages_per_domain, max_total_download_bytes, max_llm_requests, max_research_duration_seconds, max_context_per_llm_call)
+- `BudgetTracker`: Counter für alle Limits mit increment_*() Methoden
+- `BudgetExhaustedError`: Exception bei Limit-Überschreitung
+- check_budget(), get_usage(), is_exhausted()
+
+**`src/nsct/orchestration/models.py`** — ResearchRun Pydantic Model
+- 13 Felder: id, research_id, query, state, budget_config_json, created_at, updated_at, metadata, research_plan, plan_error, search_count, source_count, claim_count
+- frozen=True, immutable
+
+**`src/nsct/orchestration/orchestrator.py`** — ResearchOrchestrator
+- `async start() -> ResearchRun` — Erstellt Run, setzt State CREATED
+- `async run() -> dict` — Führt volle Pipeline durch (8 Schritte)
+- `async run_step(step_name) -> dict` — Einzelner Schritt
+- Budget-Check vor jedem Schritt
+- Fallback: MockPlanner bei LLM-Ausfall, leere Quellen bei Crawler-Fehler, fallback report bei Synthese-Fehler
+- Properties: is_completed(), is_running(), state, run_id, budget_tracker
+
+### Pipeline-Flow
+```
+CREATED → PLANNING → SEARCHING → FETCHING → EXTRACTING → ANALYZING → COMPARING → SYNTHESIZING → COMPLETED
+                                                                                           ↘ FAILED
+                                                                                           ↘ CANCELLED
+```
+
+### Architekturregeln
+- Budget darf das LLM nie selbst erhöhen
+- Jeder Schritt validiert State-Transition
+- Pro-Stage Error-Handling (kein Single-Point-of-Failure)
+- Keine Features aus Stage 13+ vorimplementiert

 ---

@@ -52,7 +85,7 @@ Webquellen recherchieren, Inhalte extrahieren, Quellen/Claims vergleichen, neutr

 Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit der Arbeit beginnen. Der neue Thread liest prompt.md (liegt im Repo als `/home/faligam/nsct/prompt.md`) für die volle Spezifikation und setzt bei der nächsten offenen Stage fort.

-**Stage 10 ist die nächste offene Stage.**
+**Stage 13 ist die nächste offene Stage.**

 ---

@@ -60,24 +93,17 @@ Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit de

 | Stage | Beschreibung |
 |---|---|
-| 5 | ~~Claim Extraction~~ (✅ **ABGESCHLOSSEN** – `e8b6515`) |
-| 6 | ~~Source Independence & Citation Graph~~ (✅ **ABGESCHLOSSEN** – `a60cf21`) |
-|| 7 | ~~Claim Clustering & Contradiction Candidates~~ (✅ **ABGESCHLOSSEN** – `d1e6bb6`) ||
-|| 8 | ~~Evidence Scoring~~ (✅ **ABGESCHLOSSEN** – `719e218`) |
-|| 9 | ~~Neutral Synthesis Engine~~ (✅ **ABGESCHLOSSEN** – `d87e2b4`) ||
-|| **10** | **Vision Integration** — Qwen2.5-VL-3B für Diagramme, Screenshots, Infografiken, PDF-Layouts. Provenance-Pflicht. (**ABGESCHLOSSEN** – `3ab875d`) ||
-|| **11** | **Audio Integration** — STT-Transkription von Interviews, Podcasts, Pressekonferenzen. Timestamped Claims. (**ABGESCHLOSSEN** – `10a083a`) ||
-| **12** | **Research Orchestrator** — State Machine (CREATED→PLANNING→SEARCHING→...→COMPLETED/FAILED). Harte Budgets (max_search_queries, max_sources, max_llm_requests, ...). |
+| 12 | ~~Research Orchestrator~~ (✅ **ABGESCHLOSSEN** — `state.py` + `budget.py` + `models.py` + `orchestrator.py`) |
 | **13** | **Iterative Research / Gap Analysis** — Max 3 Research-Rounds. Lückenerkennung: welche Claims nur eine Quelle? Wo fehlen Primärquellen? |
-| **14** | **REST API** — POST/GET/DELETE für research, status, sources, claims, evidence, report. Depth: quick/normal/deep. |
-| **15** | **CLI** — `nsct research "..."`, `nsct status/report/sources/claims <id>`. |
-| **16** | **Observability** — Structured Logging, Metriken (search_queries_total, claims_extracted, contradictions_detected, ...). |
-| **17** | **Tests für Neutralitätsmethodik** — Syndication-Test, politische Aussagen, wissenschaftlicher Dissens, Prompt-Injection-Test, fehlende Evidenz-Test. |
-| **18** | **Docker Hardening** — Non-Root, Read-Only Root FS, no Docker Socket, Resource Limits. |
-| **19** | **Performanceoptimierung** — LLM Concurrency Semaphore(3), Priorisierung (HIGH/NORMAL/LOW), Batching. |
-| **20** | **Context Budgeting** — Pro Stage Kontext-Limits (Planner 8-16k, Claim 8-24k, Contradiction 16-32k, Synthesis 32-64k). |
-| **21** | **Reproduzierbarkeit** — research_run_hash, vollständige Provenance aller Schritte. |
-| **22** | **Abschluss & Production Readiness** — README, ARCHITECTURE, SECURITY, METHODOLOGY, API, DEPLOYMENT. End-to-End-Test. |
+| 14 | REST API — POST/GET/DELETE für research, status, sources, claims, evidence, report. Depth: quick/normal/deep. |
+| 15 | CLI — `nsct research "..."`, `nsct status/report/sources/claims <id>`. |
+| 16 | Observability — Structured Logging, Metriken (search_queries_total, claims_extracted, contradictions_detected, ...). |
+| 17 | Tests für Neutralitätsmethodik — Syndication-Test, politische Aussagen, wissenschaftlicher Dissens, Prompt-Injection-Test, fehlende Evidenz-Test. |
+| 18 | Docker Hardening — Non-Root, Read-Only Root FS, no Docker Socket, Resource Limits. |
+| 19 | Performanceoptimierung — LLM Concurrency Semaphore(3), Priorisierung (HIGH/NORMAL/LOW), Batching. |
+| 20 | Context Budgeting — Pro Stage Kontext-Limits (Planner 8-16k, Claim 8-24k, Contradiction 16-32k, Synthesis 32-64k). |
+| 21 | Reproduzierbarkeit — research_run_hash, vollständige Provenance aller Schritte. |
+| 22 | Abschluss & Production Readiness — README, ARCHITECTURE, SECURITY, METHODOLOGY, API, DEPLOYMENT. End-to-End-Test. |

 ---

@@ -121,7 +147,7 @@ Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit de

 ## GIT-Information

- **Remote:** `https://df918b20ee2da2c2f92f8dd9bdbdb42ee0c6f9da@git.frerkc.de/opencode/NSCT---Neutral-Search-Crawler-Tool.git`
+- **Remote:** `https://df918b...f9da@git.frerkc.de/opencode/NSCT---Neutral-Search-Crawler-Tool.git`
 - **Branch:** `main`
 - **Credentials:** `user.email="nsct@frerkc.de"`, `user.name="NSCT Agent"`
 - **Regel:** Jede Stage wird committed → gepusht → Fortschritt dokumentiert.
@@ -140,6 +166,4 @@ Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit de

 ## Start-Command für neuen Thread

-Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit der Arbeit beginnen. Der neue Thread liest prompt.md (liegt im Repo als `/home/faligam/nsct/prompt.md`) für die volle Spezifikation und setzt bei der nächsten offenen Stage fort.
-
-Der aktuelle Stand ist commit `b8181de` auf `origin/main`.
+Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit der Arbeit beginnen. Der neue Thread liest prompt.md (liegt im Repo als `/home/faligam/nsct/prompt.md`) für die volle Spezifikation und setzt bei der nächsten offenen Stage fort.