> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vrin.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Guide

> Migrating from v0.8.x to v1.0.0

v1.0.0 is **backward-compatible**. Your existing code continues to work without changes. This guide covers what changed and how to adopt the new APIs.

## What changed

### Module consolidation

| v0.8.x                       | v1.0.0                  | Notes                              |
| ---------------------------- | ----------------------- | ---------------------------------- |
| `client.py` + `client_v2.py` | `client.py`             | Single unified client              |
| `enterprise_client.py`       | `enterprise.py`         | No network calls on init           |
| `conversation.py`            | Folded into `client.py` | Conversation methods on VRINClient |
| `config.py`                  | `_endpoints.py`         | URL constants only                 |
| `network.py`                 | Removed                 | `requests` used directly           |
| `providers/`                 | Removed                 | Server-side only                   |
| `validation.py`              | Removed                 | Validation in client methods       |

Old modules are archived in `vrin/_legacy/` and are not imported.

### URL fixes

| Endpoint      | v0.8.x               | v1.0.0                 |
| ------------- | -------------------- | ---------------------- |
| Login         | `/login`             | `/api/auth/login`      |
| Register      | `/register`          | `/api/auth/signup`     |
| Conversations | `/dev/conversations` | `/Stage/conversations` |

These fixes resolve 404 errors that occurred with the old URLs.

### Enterprise client

The v0.8.x `EnterpriseClient` made network calls during `__init__` (fetching config, validating connectivity). The v1.0.0 `VRINEnterpriseClient` is a thin subclass that only validates the key prefix.

```python theme={null}
# v0.8.x -- made network calls on init
from vrin import EnterpriseClient
client = EnterpriseClient(api_key="vrin_ent_lv_abc123def456ghi789jkl012mno345")  # slow, could fail

# v1.0.0 -- instant, no network calls
from vrin import VRINEnterpriseClient
client = VRINEnterpriseClient(api_key="vrin_ent_lv_abc123def456ghi789jkl012mno345")  # instant
```

## Backward-compatible aliases

These aliases map old method names to new ones. They work in v1.0.0 but are not documented in the primary SDK reference.

```python theme={null}
# All of these still work in v1.0.0
client.insert_text("content")           # -> insert()
client.insert_and_wait("content")       # -> insert(wait=True)
client.query_text("query")              # -> query()
client.get_raw_results("query")         # -> query_facts()
client.get_facts("query")              # -> query_facts()
client.get_raw_facts_only("query")     # -> query_facts()
client.get_current_session_id()        # -> current_session_id property
client.get_conversation_history_ids()  # -> conversation_history_ids property
```

## Recommended changes

While not required, these changes adopt the v1.0.0 API style:

### 1. Use `insert()` instead of `insert_text()` / `insert_and_wait()`

```python theme={null}
# Before
client.insert_text("content")
client.insert_and_wait("content", timeout=120)

# After
client.insert("content")                      # waits by default
client.insert("content", wait=False)           # returns job_id
client.insert("content", max_wait=120.0)       # custom timeout
```

### 2. Use `query_facts()` instead of `get_raw_facts_only()`

```python theme={null}
# Before
facts = client.get_raw_facts_only("ACME revenue")

# After
facts = client.query_facts("ACME revenue")
```

### 3. Use properties instead of getter methods

```python theme={null}
# Before
session_id = client.get_current_session_id()

# After
session_id = client.current_session_id
```

### 4. Use streaming with metadata access

```python theme={null}
# Before (v0.8.x had no streaming)
result = client.query("question")

# After (v1.0.0 streaming)
resp = client.query("question", stream=True)
for token in resp:
    print(token, end="", flush=True)
print(f"\nFacts: {resp.total_facts}, Chunks: {resp.total_chunks}")
```

### 5. Use context manager

```python theme={null}
# Before
client = VRINClient(api_key="vrin_live_abc123def456ghi789jkl012mno345pq")
# ... use client ...
# (session never closed)

# After
with VRINClient(api_key="vrin_live_abc123def456ghi789jkl012mno345pq") as client:
    result = client.query("question")
# session closed automatically
```