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)
2.4 KiB
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):
{
"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-6-35B"
}
Wenn nicht bereit:
{
"status": "not_ready",
"llm": "error:Connection refused",
"database": "unknown"
}
Mögliche status-Werte:
ready— Alle geprüften Services sind erreichbarnot_ready— Mindestens ein Service ist nicht erreichbar
Mögliche llm-Werte:
ok— LLM-Provider ist erreichbarerror:<detail>— Fehlerbeschreibung (HTTP-Statuscode oder Exception-Typ)
GET /providers
Beschreibung: Listet die konfigurierten Provider ohne Secrets.
Request:
GET /providers
Response (200 OK):
{
"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:
{
"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.
curl http://localhost:8080/docs
GET /redoc
ReDoc-Generierung.
curl http://localhost:8080/redoc
Error Response Format
Alle Fehler folgen einem konsistenten Format:
{
"detail": "Fehlerbeschreibung"
}
Authentifizierung
Stage 0: Keine Authentifizierung. Dies wird in späteren Stages hinzugefügt (API-Key, OAuth, etc.).