e9410be941
- Pyproject.toml mit FastAPI, Pydantic v2, SQLAlchemy, httpx, asyncio, BeautifulSoup4, selectolax, trafilatura, uvicorn, pytest-asyncio - Multi-stage Dockerfile (Python 3.12-slim, Non-Root-User nsct) - docker-compose.yml (nsct-api + postgres + optional searxng) - .env.example mit allen Config-Parametern - Config-System: AppSettings mit LLMConfig, VisionConfig, AudioConfig, DatabaseConfig — komplett aus Environment, keine Hardcodes - Strukturiertes Logging mit research_id/llm_request_id Tracking - Pydantic v2 Schemas: SearchQuery, Source, Claim, EvidenceRelation, CitationEdge, ResearchReport - SQLAlchemy 2.0 Declarative Models + async Engine Factory - SSRF-Schutz: URL-Validation, IP-Blocklist (RFC1918, Cloud Metadata, file://, ftp://) - Provider-Interfaces: LLMProvider, VisionProvider, AudioProvider, SearchProvider, ContentFetcher als ABCs - Health-Endpoints: /health, /ready (LLM-Connect-Test), /providers - FastAPI App mit CORS, lifespan (LLM Pre-Flight) - CLI-Stub mit Entry-Points: nsct, nsct-core, nsct-api - 6 Test-Cases: /health, /ready, /providers + No-Secrets-Test - Vollständige Dokumentation: README, ARCHITECTURE, SECURITY, METHODOLOGY, API, DEPLOYMENT - .gitignore (Python, Docker, IDE, .env)
157 lines
2.4 KiB
Markdown
157 lines
2.4 KiB
Markdown
# 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.
|
|
|
|
## 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):**
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{
|
|
"status": "ready",
|
|
"llm": "ok",
|
|
"database": "unknown",
|
|
"llm_model": "Qwen3.6-6-35B"
|
|
}
|
|
```
|
|
|
|
Wenn nicht bereit:
|
|
```json
|
|
{
|
|
"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
|
|
|
|
**Mögliche `llm`-Werte:**
|
|
- `ok` — LLM-Provider ist erreichbar
|
|
- `error:<detail>` — Fehlerbeschreibung (HTTP-Statuscode oder Exception-Typ)
|
|
|
|
---
|
|
|
|
### GET /providers
|
|
|
|
**Beschreibung:** Listet die konfigurierten Provider ohne Secrets.
|
|
|
|
**Request:**
|
|
```
|
|
GET /providers
|
|
```
|
|
|
|
**Response (200 OK):**
|
|
```json
|
|
{
|
|
"llm": {
|
|
"available": true,
|
|
"model": "Qwen3.6-6-35B",
|
|
"max_concurrency": 3
|
|
},
|
|
"vision": {
|
|
"available": true,
|
|
"model": "Qwen2-VL-3B"
|
|
},
|
|
"audio": {
|
|
"available": true,
|
|
"model": "default"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Falls kein Provider konfiguriert:**
|
|
```json
|
|
{
|
|
"llm": { "available": false },
|
|
"vision": { "available": false },
|
|
"audio": { "available": false }
|
|
}
|
|
```
|
|
|
|
**Wichtig:** Dieser Endpoint gibt **keinerlei** Secrets, API-Keys
|
|
oder senssible Konfigurationswerte zurück.
|
|
|
|
---
|
|
|
|
## Entwicklung (nur mit NSCT_DEBUG=true)
|
|
|
|
### GET /docs
|
|
|
|
Swagger UI mit interaktiver API-Documentation.
|
|
|
|
```bash
|
|
curl http://localhost:8080/docs
|
|
```
|
|
|
|
### GET /redoc
|
|
|
|
ReDoc-Generierung.
|
|
|
|
```bash
|
|
curl http://localhost:8080/redoc
|
|
```
|
|
|
|
---
|
|
|
|
## Error Response Format
|
|
|
|
Alle Fehler folgen einem konsistenten Format:
|
|
|
|
```json
|
|
{
|
|
"detail": "Fehlerbeschreibung"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Authentifizierung
|
|
|
|
Stage 0: Keine Authentifizierung. Dies wird in späteren Stages
|
|
hinzugefügt (API-Key, OAuth, etc.). |