RAGcore-Public/docs/06_API/SDK_REQUIREMENTS.md

SDK Requirements

V1 levert handgeschreven Python (sdk/python, pakket ragcore-sdk) en TypeScript (sdk/typescript, pakket @ragcore/sdk) clients tegen de pinned OpenAPI-specificatie, elk scoped tot de drie echt geïmplementeerde retrieval-endpoints (search/context/answers) -- /v1/citations/{id} en /v1/jobs/{id} staan wel in docs/contracts/openapi.yaml, maar zijn nooit als echte route geïmplementeerd, dus geen van beide SDK's doet alsof ze bestaan.

Beide SDK's:

• accepteren het bearer token veilig zonder het ooit te loggen (Python: nooit buiten de request-headers; TypeScript: een echt privé class field #token, niet TypeScript's compile-time-only private, dus niet zichtbaar via console.log/spread/JSON.stringify);
• ondersteunen timeouts (beide) en cancellation via de standaard taal- mechanismen (Python: normale asyncio-cancellation; TypeScript: een interne AbortController per request) -- geen aparte cancellation-API bovenop wat de taal al biedt;
• exposen typed problem details (ProblemDetails/RAGCoreAPIError) voor elke non-2xx-response, die allemaal dezelfde RFC7807-vorm hebben;
• modelleren de search/context/answer-types volledig, inclusief citations;
• handelen de SSE-answerstream af (event: <type>\ndata: <json>\n\n, zoals answers/routes.py::_sse_body het echt verstuurt);
• retryen alleen de non-streaming requestpaden, en alleen bij een connectiefout of een 503 -- nooit een 4xx, nooit een al gestarte SSE-stream (zie beide SDK's eigen moduledocstring voor de redenering);
• sturen een eigen versie-identifier mee: Python zet een echte User-Agent: ragcore-sdk-python/<versie> header; TypeScript zet in plaats daarvan X-RAGCore-SDK-Version: <versie>, omdat browsers pogingen om User-Agent via fetch te zetten stilzwijgend negeren (Node accepteert het wel, wat een inconsistent gedrag tussen runtimes zou opleveren als User-Agent zelf gebruikt was).

Geen SDK exposet Qdrant- of databaseconcepten.

Bewust niet geleverd

Twee requirements uit een eerdere versie van dit document zijn bewust losgelaten, omdat ze niet passen bij wat er echt bestaat:

• Idempotency keys. search/context/answers zijn stateless, side-effect-vrije queries (geen enkele schrijft iets weg) -- een idempotency key is een mechanisme tegen dubbele schrijf-operaties bij een retry, en heeft dus geen functie hier. De retry-policy hierboven is om diezelfde reden al veilig zonder een key.
• Cursor-iterators. Geen van de drie endpoints heeft cursor-based paginering (search/context/answers geven een vast-begrensde resultatenset terug, geen paginated lijst); er is dus niets om te itereren.