Metadata-Version: 2.4
Name: vectornest-sdk
Version: 0.1.0
Summary: Python SDK for the Vectornest / RAG Studio API
Project-URL: Homepage, https://vectornestai.com
Project-URL: Repository, https://github.com/allcognix/vectornest-python
Project-URL: Bug Tracker, https://github.com/allcognix/vectornest-python/issues
Author: AllCognix AI
License: MIT
Keywords: embeddings,haystack,llm,rag,sdk,vectornest
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# vectornest

Official Python SDK for the [Vectornest](https://vectornestai.com) / RAG Studio API.

## Installation

```bash
pip install vectornest-sdk
```

## Quickstart

```python
from vectornest import Vectornest

client = Vectornest(api_key="vn_your_key_here")

# Create and activate a collection
client.collections.create("research-docs")
client.collections.activate("research-docs")

# Upload documents and wait for ingestion
task = client.documents.upload(["report.pdf", "data.csv"])
task.wait(timeout=120)  # blocks; raises TaskFailedError on failure

# Query
resp = client.chat.query("summarize the key findings", session_id="session-1")
print(resp.answer)
for source in resp.sources:
    print(f"  [{source.score:.2f}] {source.filename}")
```

## Async Usage

```python
import asyncio
from vectornest import AsyncVectornest

async def main():
    async with AsyncVectornest(api_key="vn_your_key_here") as client:
        await client.collections.activate("research-docs")
        task = await client.documents.upload(["report.pdf"])
        await task.wait_async(timeout=120)
        resp = await client.chat.query("what are the conclusions?")
        print(resp.answer)

asyncio.run(main())
```

## Error Handling

```python
from vectornest.exceptions import BudgetExceededError, AuthenticationError, TaskFailedError

try:
    task = client.documents.upload(["big_file.pdf"])
    task.wait()
except AuthenticationError:
    print("Invalid API key")
except BudgetExceededError:
    print("Usage limit reached — upgrade your plan")
except TaskFailedError as e:
    print(f"Ingestion failed: {e.message}")
```

## API Reference

### `Vectornest(api_key, base_url, timeout)`
| Namespace | Methods |
|---|---|
| `client.collections` | `create()`, `list()`, `active()`, `activate()`, `delete()` |
| `client.documents` | `upload()`, `list()`, `delete()` |
| `client.chat` | `query()` |

### `UploadTask`
| Method | Description |
|---|---|
| `.wait(timeout=300, poll_interval=3)` | Block until ingestion completes |
| `.wait_async(timeout=300, poll_interval=3)` | Async variant |

### `QueryResponse`
| Field | Type | Description |
|---|---|---|
| `answer` | `str` | Generated LLM answer |
| `sources` | `list[SourceChunk]` | Retrieved context chunks |
| `llm_metrics` | `LLMMetrics` | Token counts, latency |
| `fallback_used` | `bool` | Whether fallback model was used |

## License

MIT