Metadata-Version: 2.4
Name: nebula-sdk
Version: 1.6.1
Summary: Nebula Python SDK (autogenerated)
Project-URL: Homepage, https://github.com/zeroset-inc/nebula-python
Project-URL: Repository, https://github.com/zeroset-inc/nebula-python
Project-URL: Issues, https://github.com/zeroset-inc/nebula-python/issues
Author-email: Nebula <support@zeroset.com>
License: MIT
License-File: LICENSE
Keywords: ai,memory,nebula,openapi,sdk
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# nebula-sdk

Official Nebula API SDK for Python. Provides typed async access to the public
Nebula REST API: collections, memories, connectors, snapshots, and system
health.

## Install

```bash
# Stable
pip install nebula-sdk
# Preview (next iteration, RC versions)
pip install --pre nebula-sdk
```

> **Pre-launch:** The public surface is still being shaped. Plain
> semver releases (`1.6.0`, `1.7.0`, …) are stable. Iteration ships
> as PEP 440 pre-release versions (`1.6.0rc1`, `rc2`, …) which
> pip's default resolver excludes — `pip install nebula-sdk` gets
> stable; `--pre` opts in to the iteration channel. Version
> specifiers like `nebula-sdk>=1.6.0,<2.0.0` likewise exclude
> pre-releases unless the specifier itself names one.

## Quick start

```python
import asyncio
from nebula import Nebula, ClientOptions

async def main() -> None:
    async with Nebula(ClientOptions(api_key="...")) as client:
        memory_id = await client.store_memory(
            collection_id="01234567-...",
            raw_text="hello, world",
        )
        results = await client.memories.search(body={"query": "hello"})
        print(results)

asyncio.run(main())
```

This SDK is **async-first**. If you need to call it from a sync context, wrap
each call with `asyncio.run(...)`. A dedicated sync client is not currently
provided.

## Auth

Pass either `api_key` (for Nebula API keys) or `bearer_token` (for JWTs)
when constructing the client. If you pass an opaque-looking token via
`api_key` (one that isn't prefixed with `key_` or `neb_`), the DX layer
automatically routes it through the `Authorization: Bearer` header
instead — handy when your app exchanges a workspace token for the SDK
and doesn't want to think about which header to use.

```python
async with Nebula(ClientOptions(api_key="...")) as client:
    ...

async with Nebula(ClientOptions(bearer_token="...")) as client:
    ...
```

## Errors

All HTTP errors map to a typed exception hierarchy:

- `NebulaBadRequestError` (400)
- `NebulaUnauthorizedError` (401)
- `NebulaForbiddenError` (403)
- `NebulaNotFoundError` (404)
- `NebulaConflictError` (409)
- `NebulaValidationError` (422)
- `NebulaRateLimitError` (429) — carries `retry_after` when the server returns `Retry-After`
- `NebulaServerError` (5xx)
- `NebulaConnectionError` / `NebulaTimeoutError` — transport-level

## Docs

- API reference: https://docs.zeroset.com
- Migration notes: see `MIGRATION.md` in the source repo

## License

MIT
