Metadata-Version: 2.4
Name: dodil
Version: 0.0.3
Summary: DODIL Python SDK
Author: DODIL
Author-email: support@dodil.io
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: grpcio (>=1.76.0,<2.0.0)
Requires-Dist: grpcio-tools (>=1.76.0,<2.0.0)
Requires-Dist: httpx (>=0.27.0,<0.28.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pydantic-settings (>=2.12.0,<3.0.0)
Requires-Dist: pymilvus (>=2.6.6,<3.0.0)
Description-Content-Type: text/markdown

# DODIL Python SDK

The **DODIL Python SDK** lets you interact with DODIL services from Python.

Today the SDK includes:

- **VNG**: ingestion / processing service (primarily **gRPC**, async-first)
- **VBase**: vector database service (Milvus-backed).

---

## Installation

Using Poetry:

```bash
poetry add dodil
```

Using pip:

```bash
pip install dodil
```

---

## Quick start

### 1) Create a client (service account)

Set your credentials as environment variables (recommended):

```bash
export DODIL_SERVICE_ACCOUNT_ID="..."
export DODIL_SERVICE_ACCOUNT_SECRET="..."
```


Then in Python:

```python
from dodil import Client

client = Client(
    service_account_id="...",
    service_account_secret="...",
)
```
- Service Account ID and Secret are found in console IAM page.

### 2) Use VNG

VNG is designed to be async-first.

```python
import asyncio
from dodil import Client

async def main():
    c = Client(
        profile="staging",
        service_account_id="...",
        service_account_secret="...",
    )

    # Create a bound VNG client (gRPC)
    vng = c.vng.connect()
    await vng.close()
    c.close()
```

**What VNG does** (typical use cases):
- Submit ingestion / processing jobs
- Track job status via polling
- Fetch outputs and manifests


### 3) Use VBase

VBase uses a Milvus-compatible endpoint. Your platform might show **host + port** (address and port) or a full URI; the SDK supports both.

#### A) Connect using host + port

```python
from dodil import Client, VBaseConfig

c = Client(
    service_account_id="...",
    service_account_secret="...",
)

vbase = c.vbase.connect(
    VBaseConfig(
        host="vbase-db-<id>.dodil.cloud",
        port=443,
        scheme="https",
        db_name="db_12934",
    )
)

print(vbase.list_collections())

vbase.close()
c.close()
```

**What VBase does** (typical use cases):
- Create collections (schemas)
- Insert / upsert embeddings
- Search vectors and query metadata
- Manage indexes

### 4) Schema definitions (FieldSchema, CollectionSchema, DataType)

If you want to build Milvus-style schemas, you can import definitions from `dodil.vbase`.

```python
from dodil.vbase import FieldSchema, CollectionSchema, DataType

# Example schema objects (usage depends on your backend / PyMilvus version)
fields = [
    FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=False),
    FieldSchema(name="vec", dtype=DataType.FLOAT_VECTOR, dim=768),
]

schema = CollectionSchema(fields=fields, description="example")
```
---

## Configuration

### Profiles

- `profile="staging"` (default): uses staging identity + API endpoints.
- `profile="prod"`: uses production endpoints.

### Timeouts

You can pass `timeout_s` to the root `Client` and service configs (where supported).

```python
from dodil import Client

c = Client(
    profile="staging",
    service_account_id="...",
    service_account_secret="...",
    timeout_s=60.0,
)
```

---

## Testing

Install dev dependencies then run tests:

```bash
poetry install
pytest
```

### Integration tests

Integration tests hit real external services and are marked with `integration`.

```bash
pytest -m integration -s
```

You may need to set environment variables for endpoints and credentials depending on your setup.

---

## Contributing

- Keep public APIs stable (prefer additive changes).
- Prefer service handles (`client.vng`, `client.vbase`) that create bound clients via `.connect(...)`.

---
