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

NSCT — API-Referenz

Hinweis: Diese API-Referenz beschreibt den aktuellen Stand (Stage 22).

Server-Adresse

http://localhost:8080

Nach docker compose up.

---

System-Endpunkte

GET /health

Beschreibung: Basic health check — gibt den Status und die Version zurück. Wird von Docker Healthchecks und Load Balancern verwendet.

Request:

GET /health

Response (200 OK):

{
  "status": "ok",
  "version": "0.1.0"
}

---

GET /ready

Beschreibung: Readiness check — prüft die Erreichbarkeit von Downstream-Services (LLM-Provider, ggf. Datenbank).

Request:

GET /ready

Response (200 OK):

Wenn bereit:

{
  "status": "ready",
  "llm": "ok",
  "database": "unknown",
  "llm_model": "Qwen3.6-35B"
}

Wenn nicht bereit:

{
  "status": "not_ready",
  "llm": "error:Connection refused",
  "database": "unknown"
}

Mögliche status-Werte:

• ready — Alle geprüften Services sind erreichbar
• not_ready — Mindestens ein Service ist nicht erreichbar

---

GET /providers

Beschreibung: Listet die konfigurierten Provider ohne Secrets.

Request:

GET /providers

Response (200 OK):

{
  "llm": {
    "available": true,
    "model": "Qwen3.6-35B",
    "max_concurrency": 3
  },
  "vision": {
    "available": true,
    "model": "Qwen2.5-VL-3B"
  },
  "audio": {
    "available": true,
    "model": "default"
  }
}

Falls kein Provider konfiguriert:

{
  "llm": { "available": false },
  "vision": { "available": false },
  "audio": { "available": false }
}

Wichtig: Dieser Endpoint gibt keinerlei Secrets, API-Keys oder sensible Konfigurationswerte zurück.

---

Research API (Stage 14+)

Alle Research-Endpoints haben das Präfix /v1/research.

---

POST /v1/research

Beschreibung: Startet eine neue Recherche asynchron (Background-Pipeline). Die Antwort kommt sofort — das eigentliche Ergebnis ist über GET /v1/research/{id}/report abrufbar.

Request:

{
  "query": "Welche wesentlichen Fortschritte gab es im letzten Jahr bei Kernfusion?",
  "language": "de",
  "depth": "normal",
  "extra_queries": ["Fusion breakthroughs 2025", "commercial fusion progress"]
}

Parameter:

Field	Type	Required	Default	Description
query	string	yes	—	Forschungsfrage (1–2000 Zeichen)
language	string	no	"de"	Sprachcode (z.B. "de", "en")
depth	string	no	"normal"	Suchtiefe: "quick", "normal", "deep"
extra_queries	string[]	no	null	Optionale zusätzliche Suchanfragen

Depth-Konfiguration:

Tiefe	max_search_queries	max_sources	max_llm_requests	max_duration	max_context
quick	10	15	15	120s	16k
normal	20	30	30	300s	24k
deep	40	60	60	600s	32k

Response (200 OK):

{
  "research_id": "uuid-...",
  "status": "pending",
  "query": "Welche Fortschritte bei Kernfusion?",
  "depth": "normal",
  "state": "created"
}

Error (400):

{
  "detail": "Ungültige Tiefe 'ultra'. Gültig: 'quick', 'normal', 'deep'."
}

---

GET /v1/research

Beschreibung: Liste aller Research-Runs (paginiert).

Query-Parameter:

Parameter	Type	Default	Description
limit	int	10	Max Anzahl Ergebnisse
offset	int	0	Offset für Pagination

Response (200 OK):

{
  "total": 5,
  "limit": 10,
  "offset": 0,
  "items": [
    {
      "research_id": "uuid-...",
      "query": "Kernfusion",
      "depth": "normal",
      "state": "completed",
      "created_at": "2025-01-01T00:00:00+00:00",
      "source_count": 5,
      "claim_count": 12
    }
  ]
}

---

GET /v1/research/{id}

Beschreibung: Metadaten eines Research-Runs.

Path-Parameter:

Parameter	Type	Description
id	string	UUID des Research-Runs

Response (200 OK):

{
  "research_id": "uuid-...",
  "query": "Kernfusion 2025",
  "depth": "normal",
  "state": "completed",
  "created_at": "2025-01-01T00:00:00+00:00",
  "updated_at": "2025-01-01T00:05:00+00:00",
  "search_count": 20,
  "source_count": 5,
  "claim_count": 12,
  "is_completed": true,
  "is_running": false
}

---

GET /v1/research/{id}/status

Beschreibung: State-Machine Status eines Research-Runs.

Identisch zu GET /v1/research/{id} — gleicher Response.

---

GET /v1/research/{id}/sources

Beschreibung: Quellen für einen Research-Run.

Response (200 OK):

{
  "research_id": "uuid-...",
  "sources": [
    {
      "id": "s1",
      "url": "https://example.com/1",
      "title": "Beispiel Quelle",
      "domain": "example.com",
      "source_type": "primary",
      "retrieved_at": "2025-01-01T00:01:00+00:00"
    }
  ],
  "total": 1
}

---

GET /v1/research/{id}/claims

Beschreibung: Claims (Behauptungen) für einen Research-Run.

Response (200 OK):

{
  "research_id": "uuid-...",
  "claims": [
    {
      "id": "c1",
      "research_run_id": "uuid-...",
      "source_id": "s1",
      "claim_text": "Behauptung A",
      "evidence_span": "Quelle 1, Abschnitt 2",
      "claim_type": "factual",
      "confidence": 0.85
    }
  ],
  "total": 1
}

---

GET /v1/research/{id}/evidence

Beschreibung: Evidence-Scores (6-dimensional) für einen Research-Run.

Response (200 OK):

{
  "research_id": "uuid-...",
  "evidence": [
    {
      "claim_id": "c1",
      "research_run_id": "uuid-...",
      "evidence_type": "primary_report",
      "source_independence_score": 0.9,
      "primary_source_proximity": 0.95,
      "cross_source_support": 0.7,
      "contradiction_level": 0.2,
      "evidence_directness": 0.88,
      "date_relevance_score": 0.95
    }
  ],
  "total": 1
}

---

GET /v1/research/{id}/report

Beschreibung: Synthese-Bericht (finaler Research Report).

Response (200 OK):

{
  "research_id": "uuid-...",
  "query": "Kernfusion 2025",
  "summary": "Zusammenfassung der Recherche...",
  "findings": [
    {
      "text": "Fundamentale Erkenntnis A",
      "confidence": 0.85,
      "source_ids": ["s1", "s2"]
    }
  ],
  "disagreements": [
    {
      "claim": "Behauptung X",
      "positions": [
        {"source": "Quelle 1", "view": "Für X"},
        {"source": "Quelle 2", "view": "Gegen X"}
      ]
    }
  ],
  "uncertainties": ["Nicht ausreichend belegte Behauptung Y"],
  "source_statistics": {
    "total_sources": 5,
    "primary_sources": 2,
    "secondary_sources": 3
  },
  "methodology": "NSCT Evidence Pipeline — Search, Extract, Claim, Compare, Synthesize",
  "generated_at": "2025-01-01T00:00:00+00:00"
}

---

DELETE /v1/research/{id}

Beschreibung: Löscht einen Research-Run (nur wenn nicht completed).

Response (200 OK):

{
  "status": "deleted",
  "research_id": "uuid-..."
}

Error (400): Completed runs sind immutable.

---

Prometheus Metrics

GET /metrics

Response: Prometheus Text Format mit allen Metriken:

• search_queries_total
• sources_discovered_total
• sources_fetched_total
• sources_rejected_total
• claims_extracted_total
• duplicate_sources_total
• contradictions_detected_total
• llm_requests_total
• llm_tokens_input_total
• llm_tokens_output_total
• research_duration_seconds
• research_completed_total
• research_failed_total
• active_research_runs

---

Error Response Format

Alle Fehler folgen einem konsistenten Format:

{
  "detail": "Fehlerbeschreibung"
}

---

Authentifizierung

Stage 22: Keine Authentifizierung. Dies kann in späteren Stages hinzugefügt werden (API-Key, OAuth, etc.).