stage22: Abschluss & Production Readiness — E2E-Tests, CHANGELOG, Dokumentation
This commit is contained in:
NSCT Agent
301
API.md
301
API.md
@@ -1,8 +1,6 @@
|
||||
# NSCT — API-Referenz
|
||||
|
||||
> **Hinweis:** Diese API-Referenz beschreibt nur die Endpunkte
|
||||
> von Stage 0. Die eigentliche Evidence-Pipeline (Suche,
|
||||
> Analyse, Report) wird in späteren Stages implementiert.
|
||||
> **Hinweis:** Diese API-Referenz beschreibt den aktuellen Stand (Stage 22).
|
||||
|
||||
## Server-Adresse
|
||||
|
||||
@@ -54,7 +52,7 @@ Wenn bereit:
|
||||
"status": "ready",
|
||||
"llm": "ok",
|
||||
"database": "unknown",
|
||||
"llm_model": "Qwen3.6-6-35B"
|
||||
"llm_model": "Qwen3.6-35B"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -71,10 +69,6 @@ Wenn nicht bereit:
|
||||
- `ready` — Alle geprüften Services sind erreichbar
|
||||
- `not_ready` — Mindestens ein Service ist nicht erreichbar
|
||||
|
||||
**Mögliche `llm`-Werte:**
|
||||
- `ok` — LLM-Provider ist erreichbar
|
||||
- `error:<detail>` — Fehlerbeschreibung (HTTP-Statuscode oder Exception-Typ)
|
||||
|
||||
---
|
||||
|
||||
### GET /providers
|
||||
@@ -91,12 +85,12 @@ GET /providers
|
||||
{
|
||||
"llm": {
|
||||
"available": true,
|
||||
"model": "Qwen3.6-6-35B",
|
||||
"model": "Qwen3.6-35B",
|
||||
"max_concurrency": 3
|
||||
},
|
||||
"vision": {
|
||||
"available": true,
|
||||
"model": "Qwen2-VL-3B"
|
||||
"model": "Qwen2.5-VL-3B"
|
||||
},
|
||||
"audio": {
|
||||
"available": true,
|
||||
@@ -115,28 +109,291 @@ GET /providers
|
||||
```
|
||||
|
||||
**Wichtig:** Dieser Endpoint gibt **keinerlei** Secrets, API-Keys
|
||||
oder senssible Konfigurationswerte zurück.
|
||||
oder sensible Konfigurationswerte zurück.
|
||||
|
||||
---
|
||||
|
||||
## Entwicklung (nur mit NSCT_DEBUG=true)
|
||||
## Research API (Stage 14+)
|
||||
|
||||
### GET /docs
|
||||
Alle Research-Endpoints haben das Präfix `/v1/research`.
|
||||
|
||||
Swagger UI mit interaktiver API-Documentation.
|
||||
---
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/docs
|
||||
### 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:**
|
||||
```json
|
||||
{
|
||||
"query": "Welche wesentlichen Fortschritte gab es im letzten Jahr bei Kernfusion?",
|
||||
"language": "de",
|
||||
"depth": "normal",
|
||||
"extra_queries": ["Fusion breakthroughs 2025", "commercial fusion progress"]
|
||||
}
|
||||
```
|
||||
|
||||
### GET /redoc
|
||||
**Parameter:**
|
||||
|
||||
ReDoc-Generierung.
|
||||
| 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 |
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/redoc
|
||||
**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):**
|
||||
```json
|
||||
{
|
||||
"research_id": "uuid-...",
|
||||
"status": "pending",
|
||||
"query": "Welche Fortschritte bei Kernfusion?",
|
||||
"depth": "normal",
|
||||
"state": "created"
|
||||
}
|
||||
```
|
||||
|
||||
**Error (400):**
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```json
|
||||
{
|
||||
"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
|
||||
@@ -153,5 +410,5 @@ Alle Fehler folgen einem konsistenten Format:
|
||||
|
||||
## Authentifizierung
|
||||
|
||||
Stage 0: Keine Authentifizierung. Dies wird in späteren Stages
|
||||
hinzugefügt (API-Key, OAuth, etc.).
|
||||
Stage 22: Keine Authentifizierung. Dies kann in späteren Stages
|
||||
hinzugefügt werden (API-Key, OAuth, etc.).
|
||||
Reference in New Issue
Block a user