# NSCT — Neutral Search Crawler Tool

**NSCT** ist ein vollständig lokal betreibbares, containerisiertes Recherche- und
Analyse-System. Es durchsucht Webquellen, extrahiert Inhalte, vergleicht
Behauptungen (Claims) aus verschiedenen Quellen und erzeugt einen neutralen,
quellengestützten Bericht.

**NSCT steht für:** Neutral Search Crawler Tool.

---

## Architektur-Übersicht

```
┌─────────────┐    ┌──────────────────────────┐    ┌───────────────┐
│  User / CLI  │───▶│  NSCT REST API (FastAPI) │───▶│  uvicorn      │
│              │    │  (async, background pip.)│    │  :8080        │
└─────────────┘    └──────────┬───────────────┘    └───────────────┘
                              │
              ┌───────────────┼─────────────────┐
              ▼               ▼                 ▼
        ┌──────────────┐ ┌──────────┐  ┌──────────────┐
        │ Search       │ │ Content  │  │  Crawler     │
        │  Providers   │ │ Fetcher  │  │  (SSRF-Prot) │
        │ (DDG, Multi) │ │ (HTTP/   │  │  (HTML,PDF,  │
        └──────┬───────┘ │  Playwright)│  │   PDF, ...) │
               │         └──────┬─────┘  └──────────────┘
               ▼                ▼
        ┌─────────────────────────────────────────────┐
        │   Evidence Pipeline (Orchestrator)          │
        │   Search → Fetch → Extract → Claim →       │
        │   Compare → Score → Synthesis → Report     │
        └──────────────────────────┬─────────────────┘
                                   │
                                   ▼
                    ┌────────────────────────┐
                    │  PostgreSQL (asyncpg)   │
                    │  Evidence Store         │
                    └────────────────────────┘
                                   ▲
                                   │
                    ┌──────────────┴──────────────┐
                    │  LLM (Qwen3.6-35B)          │
                    │  Vision (Qwen2.5-VL-3B)      │
                    │  Audio (STT)                 │
                    └──────────────────────────────┘
```

## Quick Start

### Docker Compose

```bash
# 1. Kopiere die Beispiel-Env
cp .env.example .env

# 2. Trage deine Endpunkte ein (LLM, Vision, Audio, PostgreSQL)

# 3. Starte alles
docker compose up --build

# 4. Prüfe den Health-Check
curl http://localhost:8080/health
```

Die API ist danach unter `http://localhost:8080` erreichbar.
`/docs` zeigt die auto-generierte Swagger-Dokumentation (nur bei `NSCT_DEBUG=true`).

### Frontend auf einem separaten Rechner

Das Backend kann unabhängig vom Frontend betrieben werden. Das Frontend leitet
seine Same-Origin-Anfragen an `/api/*` per Caddy an diese API weiter. Auf dem
Frontend-Rechner wird dazu im Frontend-Repository gesetzt:

```env
NSCT_API_UPSTREAM=backend.example.com:8080
```

Der Backend-Rechner muss Port 8080 ausschließlich für die IP bzw. das Netz des
Frontend-Rechners freigeben. Für öffentliche oder nicht vertrauenswürdige Netze
soll die Verbindung zwischen den Rechnern über TLS, VPN oder einen abgesicherten
Reverse Proxy erfolgen.

## Projektstruktur

```
nsct/
├── src/nsct/
│   ├── api/          # FastAPI-Routen (health, research, search, etc.)
│   ├── agents/       # Research Planner & Validator
│   ├── crawler/      # Content Fetcher, Extraction, Normalization
│   ├── models/       # Pydantic v2 Schemas
│   ├── orchestration/# State Machine, Budget, Gap Analysis
│   ├── provenance.py # Vollständige Provenance Tracking
│   ├── providers/    # LLM, Vision, Audio, Search, Multi, Priority
│   ├── security/     # SSRF-Schutz, URL-Validierung
│   ├── stages/       # Pipeline-Stages (5-13: claim, evidence, synthesis)
│   ├── storage/      # SQLAlchemy 2.0 Models + Engine
│   ├── cli.py        # Kommandozeileninterface
│   ├── config.py     # Pydantic BaseSettings Konfiguration
│   ├── logging_config.py  # Strukturiertes JSON-Logging
│   ├── metrics.py    # Prometheus Metriken
│   └── main.py       # FastAPI Application Factory
├── tests/            # pytest-Tests (Unit + Integration)
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
├── .env.example
├── README.md
├── ARCHITECTURE.md
├── SECURITY.md
├── METHODOLOGY.md
├── API.md
├── DEPLOYMENT.md
└── CHANGELOG.md
```

## Schnellstart-Beispiel (CLI)

```bash
nsct research "Welche wesentlichen Entwicklungen gab es im letzten Jahr bei Kernfusion?" \
  --depth normal \
  --language de
```

## Schnellstart-Beispiel (API)

```bash
curl -X POST http://localhost:8080/v1/research \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Welche Entwicklungen gab es bei Kernfusion?",
    "language": "de",
    "depth": "normal"
  }'
```

Antwort:
```json
{
  "research_id": "uuid-...",
  "status": "pending",
  "query": "Welche Entwicklungen gab es bei Kernfusion?",
  "depth": "normal",
  "state": "created"
}
```

Den Status und das Ergebnis abrufen:
```bash
# Status
curl http://localhost:8080/v1/research/<research_id>/status

# Bericht
curl http://localhost:8080/v1/research/<research_id>/report

# Quellen
curl http://localhost:8080/v1/research/<research_id>/sources

# Claims
curl http://localhost:8080/v1/research/<research_id>/claims

# Evidence-Scores
curl http://localhost:8080/v1/research/<research_id>/evidence
```

## Status

**Stage 22** — Abschluss & Production Readiness.

Alle 22 Stages sind abgeschlossen. NSCT ist production-ready:

- **Pipeline:** Search → Fetch → Extract → Claim → Compare → Score → Synthesize → Report
- **State Machine:** 12 Zustände (CREATED → ... → COMPLETED/FAILED/CANCELLED)
- **Budget Limits:** Hard limits für Queries, Sources, LLM-Requests, Duration
- **Iterative Research:** Gap Analysis mit max 3 Runden
- **REST API:** Vollständiger Research Lifecycle (POST/GET/DELETE)
- **CLI:** Kommandozeileninterface mit depth, language, format Optionen
- **Observability:** Strukturiertes Logging + Prometheus Metriken
- **Docker Hardening:** Non-Root, Read-Only FS, Dropped Capabilities, Resource Limits
- **Reproduzierbarkeit:** Vollständige Provenance + research_run_hash
- **Neutralitäts-Tests:** Syndication, politische Aussagen, Dissens, Prompt Injection, fehlende Evidenz
- **E2E-Tests:** 9 Integrationstests für den vollständigen Pipeline-Durchlauf

## Lizenz

MIT