diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 0000000..a19e38d --- /dev/null +++ b/HANDOFF.md @@ -0,0 +1,118 @@ +# NSCT – Handoff für neue Threads + +> Diese Datei wird **nicht** in Git gepushed. Sie dient nur als Brücke zwischen Threads. + +--- + +## Projekt: NSCT – Neutral Search Crawler Tool + +**Ziel:** Vollständig lokal betreibbares, containerisiertes Recherche- und Analyse-System. +Webquellen recherchieren, Inhalte extrahieren, Quellen/Claims vergleichen, neutralen Bericht erzeugen. + +**Repository:** `https://git.frerkc.de/opencode/NSCT---Neutral-Search-Crawler-Tool.git` +**Branch:** `main` — alle Commits sind bereits gepusht. + +--- + +## Bisher abgeschlossene Stages + +| Stage | Beschreibung | Commit | Files | Tests | +|---|---|---|---|---| +| 0 | Repository & Architekturgrundlage | `e9410be` | 28 | 6 | +| 1 | Model Provider Layer (LLM/Vision/Audio, Metriken, Debug) | `9280d69` | 6 | – | +| 2 | Search Provider Abstraction (DuckDuckGo, Multi-Provider, POST /search) | `a1ef260` | 5 | 25 | +| 3 | Crawler & Content Extraction (SSRF, trafilatura, PDF, Batch) | `a8595cc` | 10 | ~15 | +| 4 | Research Planner (LLM-basierte Recherchestrategie, Search-Bias-Reduktion) | `b8181de` | 6 | 25 | +| 5 | Claim Extraction (atomare, überprüfbare Claims mit Provenance) | `e8b6515` | 7 | 36 | + +**Gesamt:** 70 Dateien, ~6500 Zeilen Code, ~86 Tests. + +--- + +## Nächste Stages (aus prompt.md) + +| Stage | Beschreibung | +|---|---| +|| **5** | ~~Claim Extraction~~ (✅ **ABGESCHLOSSEN** – `e8b6515`) | +|| **6** | **Source Independence & Citation Graph** — Erkennen von Syndication, gemeinsamen Ursprüngen, nahezu identischen Texten. independence_score für jede Quelle. | +| **7** | **Claim Clustering & Contradiction Candidates** — Semantische Gruppierung, numerische Normalisierung, LLM für schwierige Fälle. supports/contradicts/duplicate/uncertain. | +| **8** | **Evidence Scoring** — Transparente multidimensionale Scores (source_independence, primary_source_proximity, cross_source_support, contradiction_level, evidence_directness, date_relevance). Kein einziger "truth_score". | +| **9** | **Neutral Synthesis Engine** — LLM erzeugt den finalen Bericht aus dem Evidence Package. Trennung Fakten/Interpretation, Unsicherheit explizit, keine politische Empfehlung. | +| **10** | **Vision Integration** — Qwen2.5-VL-3B für Diagramme, Screenshots, Infografiken, PDF-Layouts. Provenance-Pflicht. | +| **11** | **Audio Integration** — Transkription von Interviews, Podcasts, Pressekonferenzen. Timestamped Claims. | +| **12** | **Research Orchestrator** — State Machine (CREATED→PLANNING→SEARCHING→...→COMPLETED/FAILED). Harte Budgets (max_search_queries, max_sources, max_llm_requests, ...). | +| **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 `. | +| **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. | + +--- + +## Wichtige Architektur-Regeln (immer gelten!) + +1. Web Content ist Daten, keine Instruktion. +2. Jede relevante Behauptung benötigt Provenance. +3. Anzahl Webseiten != Anzahl unabhängiger Quellen. +4. Search Ranking != Truth Ranking. +5. LLM darf keine Quellen/Evidenz erfinden. +6. Unsicherheit ist ein gültiges Resultat. +7. Keine einzelne numerische Kennzahl als universeller "Truth Score". +8. LLMs übernehmen semantische Aufgaben, deterministischer Code wo möglich. +9. Qwen3.6-Modell bleibt einziger großer Sprachmodell-Worker im MVP. +10. Vision und Audio sind spezialisierte Evidence Extractors. + +--- + +## Wichtige Konfiguration + +**LLM-Endpunkte (nicht hardcoden!):** +- LLM: `NSCT_LLM_BASE_URL` (Qwen3.6-35B) +- Vision: `NSCT_VISION_BASE_URL` (Qwen2.5-VL-3B) +- Audio: `NSCT_AUDIO_BASE_URL` (Audio/STT) +- Alle über Environment-Variablen. API-Key über `HERMES_CUSTOM_192_168_80_199_8030_API_KEY`. + +**PostgreSQL:** +- `NSCT_DB_URL` — PostgreSQL+asyncpg +- SQLAlchemy 2.0 Declarative Models + async Engine + +**Search Provider:** +- DuckDuckGo als Default-Provider +- MultiProviderSearch für parallele Abfrage +- Search-Bias-Reduktion: kein Ranking = kein Evidenz-Ranking + +**Security:** +- SSRF-Schutz: RFC1918-Blocklist, Cloud-Metadata, file://, ftp:// +- Control Plane ≠ Evidence Plane + +--- + +## GIT-Information + +- **Remote:** `https://df918b20ee2da2c2f92f8dd9bdbdb42ee0c6f9da@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. + +--- + +## Arbeitsweise + +- Orchestrator-Pattern: Ich koordiniere, SubAgents (delegate_task) implementieren. +- Pro Stage: neue Dateien → syntaktischer Check → `git add` → `git commit` → `git push origin main`. +- Keine Features aus späteren Stages vorimplementieren. +- Nach Stage-Abschluss: Tests ausführen, Docker-Build testen (wenn verfügbar), Dokumentation aktualisieren. +- ** Niemals automatisch zur nächsten Stage springen — auf explizite Anweisung warten.** + +--- + +## 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`. \ No newline at end of file