NSCT---Neutral-Search-Crawler-Tool/ARCHITECTURE.md

NSCT — Architekturdokumentation

1. Überblick

NSCT (Neutral Search Crawler Tool) ist ein modulares, containerisiertes Recherchesystem. Es durchsucht Webquellen, extrahiert Inhalte, analysiert Behauptungen (Claims) und erzeugt einen neutralen, quellengestützten Bericht.

Kernprinzip: Webcontent ist DATA, keine INSTRUCTION. Der LLM verarbeitet nur strukturierte Daten, niemals rohen Webcontent direkt als Prompt.

2. Architektur-Diagramm

┌─────────────────────────────────────────────────────────────────────┐
│                            Control Plane                             │
│  ┌──────────┐  ┌───────────┐  ┌────────────┐  ┌─────────────────┐ │
│  │  CLI     │  │  REST API │  │  WebSocket │  │  Event Bus      │ │
│  └────┬─────┘  └─────┬─────┘  └─────┬──────┘  └────────┬────────┘ │
│       │              │             │                   │         │
│       └──────────────┴─────────────┴───────────────────┘         │
│                                                                    │
│  ┌───────────────────────Evidence Pipeline───────────────────────┐ │
│  │                                                               │ │
│  │  ┌─────────┐   ┌──────────┐   ┌───────────┐   ┌───────────┐ │ │
│  │  │  Search │──▶│  Fetch   │──▶│  Extract  │──▶│  Classify │ │ │
│  │  │  (SearX │   │ (HTTP/  │   │(Trafilat │   │(LLM/Rule)│ │ │
│  │  │   NG)   │   │ Playwright)│  │ura/BS4)  │   │          │ │ │
│  │  └─────────┘   └──────────┘   └───────────┘   └─────┬─────┘ │ │
│  │                                                     │       │ │
│  │  ┌─────────┐   ┌───────────┐   ┌────────────┐   ┌───┴─────┐ │ │
│  │  │  Index  │◀──│  Compare  │◀──│  Normalise │◀──│  Claim  │ │ │
│  │  │ & Store │   │ (LLM)     │   │  & Parse   │   │  Ext.   │ │ │
│  │  └─────────┘   └─────┬─────┘   └────────────┘   └─────────┘ │ │
│  │                        │                                      │ │
│  │                        ▼                                      │ │
│  │               ┌──────────────┐                               │ │
│  │               │  Report Gen. │                               │ │
│  │               │  (LLM)       │                               │ │
│  │               └──────┬───────┘                               │ │
│  │                      ▼                                       │ │
│  │               ┌──────────────┐                               │ │
│  │               │  Evidence DB │                               │ │
│  │               └──────────────┘                               │ │
│  └──────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

3. Datenfluss

Query ──▶ SearchProvider.search() ──▶ List[SearchResult]
         │
         │  (for each result)
         │
         ▼
     ContentFetcher.fetch(url) ──▶ Source document (parsed)
         │
         │  (LLM: extract claims from source)
         │
         ▼
     Claim[] ──▶ Normalization ──▶ NormalizedClaim[]
         │
         │  (LLM: compare claims pairwise)
         │
         ▼
     EvidenceRelation[] ──▶ Agreement matrix
         │
         │  (LLM: synthesize report)
         │
         ▼
     ResearchReport (Summary + Findings + Disagreements + Uncertainties)

4. Module

4.1 src/nsct/api/ — REST API

• main.py: FastAPI application factory, CORS, lifespan hooks
• health.py: /health, /ready, /providers endpunkte
• Pattern: Each router is a separate file; mounted in main.py

4.2 src/nsct/models/ — Pydantic v2 Schemas

• schemas.py: Data transfer objects (SearchQuery, Source, Claim, etc.)
• Pure Pydantic — no database or API coupling

4.3 src/nsct/storage/ — Database Layer

• models.py: SQLAlchemy 2.0 declarative models
• engine.py: Async engine factory with pool management
• Uses asyncpg for PostgreSQL

4.4 src/nsct/providers/ — Provider Interfaces

• Abstract base classes (LLMProvider, VisionProvider, SearchProvider, ContentFetcher, AudioProvider)
• No concrete implementations in Stage 0 — just protocols
• All providers accept structured data, never raw web content

4.5 src/nsct/security/ — Security

• policy.py: SSRF protection, URL validation, IP blocklisting
• Called before every outbound HTTP request

4.6 src/nsct/config.py — Configuration

• Pydantic BaseSettings — all values from environment
• Zero hard-coded secrets or URLs
• AppSettings.from_env() creates the root configuration

4.7 src/nsct/logging_config.py — Structured Logging

• JSON-formatted log output
• Per-request context tracking (research_id, llm_request_id)
• Global context dict merged into every log record

5. Interfaces / Protocols

# src/nsct/providers/__init__.py

class LLMProvider(ABC):
    async def generate(prompt, system_prompt=None, ...) -> LLMResponse: ...

class VisionProvider(ABC):
    async def analyze_image(image_bytes, prompt) -> VisionResponse: ...

class AudioProvider(ABC):
    async def transcribe(audio_bytes) -> AudioResponse: ...

class SearchProvider(ABC):
    async def search(query, language, limit) -> list[SearchResult]: ...

class ContentFetcher(ABC):
    async def fetch(url, **kwargs) -> dict: ...

Alle konkreten Implementationen (SearXNG, OpenAI, Trafilatura, etc.) müssen diese Interfaces implementieren — das ermöglicht den Wechsel von Providern ohne Codeänderung im Core.

6. Sicherheitsarchitektur

• Control Plane vs. Evidence Plane: Der LLM verarbeitet nur strukturierte Daten (Claims, NormalizedClaims, EvidenceRelations), niemals rohen Webcontent.
• SSRF-Schutz: Jede outbound-URL wird vor dem Request durch validate_url() geprüft.
• Prompt-Isolation: Webcontent wird niemals direkt als Prompt text eingebettet. Stattdessen wird er in strukturierte JSON-Objekte serialisiert.
• Non-Root-Docker: Der Container läuft als nicht-root User nsct.
• Read-Only-Filesystem: Wo möglich (read_only: true + tmpfs).

7. Datenmodell

Core Tables

Table	Beschreibung
search_queries	Research-Aufträge mit Query, Purpose, Language
sources	Extrahierte Webquellen mit Metadaten
claims	Behauptungen aus Quellen mit Typ, Konfidenz, Evidence
evidence_relations	Vergleichsergebnisse zwischen Claims
citation_edges	Quelle-zu-Quelle Referenzen
research_reports	Aggregierte Forschungsberichte

8. Nicht-funktionale Anforderungen

Kriterium	Anforderung
Concurrency	Async I/O konsequent (async/await everywhere)
Database	PostgreSQL 16+, asyncpg, SQLAlchemy 2.0
Logging	Strukturiert (JSON), jede Anfrage tracebar
Config	Environment-only, keine Config-Dateien
Testing	pytest-asyncio, FastAPI TestClient
Deployment	Docker Compose, reproduzierbar