Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/06_API/SDK_REQUIREMENTS.md

@@ -0,0 +1,51 @@
+# 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.