Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

sdk/python/README.md

@@ -0,0 +1,47 @@
+# ragcore-sdk
+
+Typed Python client for RAGCore's `/v1/search`, `/v1/context`, and
+`/v1/answers` endpoints.
+
+```python
+from ragcore_sdk import RAGCoreClient
+
+with RAGCoreClient(base_url="https://ragcore.example.internal", token="...") as client:
+    response = client.search(query="What is the refund policy?")
+    for result in response.results:
+        print(result.rank, result.citation.source_uri)
+```
+
+Streaming answers:
+
+```python
+import asyncio
+from ragcore_sdk import AsyncRAGCoreClient
+
+async def main() -> None:
+    async with AsyncRAGCoreClient(base_url="https://ragcore.example.internal", token="...") as client:
+        async for event in client.answer_stream(query="What is the refund policy?"):
+            print(event.type, event.data)
+
+asyncio.run(main())
+```
+
+## Scope
+
+This SDK covers exactly the endpoints RAGCore actually implements:
+`search`, `context`, and `answers` (sync and SSE-streaming). It does not
+expose `get_citation`/`get_job` methods — those paths exist only in the
+aspirational OpenAPI contract, not as real routes in this codebase, so
+the SDK does not fabricate a client surface for them.
+
+## Errors
+
+Every non-2xx response RAGCore returns is an RFC7807 Problem Details body.
+The SDK raises `RAGCoreAPIError` (carrying the parsed `ProblemDetails`) for
+those, and `RAGCoreConnectionError` for network-level failures that
+persist after retries are exhausted. Retries only ever apply to this
+SDK's own read-only, side-effect-free requests (search/context/answers are
+GET-equivalent queries) on connection failures and `503` responses --
+never on `4xx` client errors.
+
+The bearer token is never logged or included in exception messages.