# 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.