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

# Models

> Typed dataclasses for structured responses

Vrin client methods return plain dicts by default. These dataclasses provide optional typed wrappers with convenience properties. All have a `from_dict()` classmethod.

## Document

Represents a document to be processed and indexed.

```python theme={null}
from vrin import Document

doc = Document(
    content="ACME Corp reported $50M revenue in Q4 2025.",
    title="ACME Financials",
    tags=["earnings", "2025"],
    source="sdk-upload",
    document_type="text",
)
```

### Fields

| Field           | Type                  | Default               | Description                  |
| --------------- | --------------------- | --------------------- | ---------------------------- |
| `content`       | `str`                 | required              | Text content of the document |
| `title`         | `Optional[str]`       | `"Untitled Document"` | Document title               |
| `tags`          | `Optional[List[str]]` | `[]`                  | Tags for categorization      |
| `source`        | `Optional[str]`       | `"vrin-sdk"`          | Source identifier            |
| `user_id`       | `Optional[str]`       | `"default"`           | Owner user ID                |
| `document_type` | `str`                 | `"text"`              | Document type                |

## QueryResult

Represents a single search result from the knowledge base.

```python theme={null}
from vrin import QueryResult

qr = QueryResult.from_dict(result_dict)
print(qr.content)
print(qr.score)
print(qr.title)      # from metadata
print(qr.tags)       # from metadata
```

### Fields

| Field           | Type             | Description                          |
| --------------- | ---------------- | ------------------------------------ |
| `content`       | `str`            | Retrieved text content               |
| `score`         | `float`          | Relevance score                      |
| `search_type`   | `str`            | `"graph"`, `"vector"`, or `"hybrid"` |
| `metadata`      | `Dict[str, Any]` | Document metadata                    |
| `chunk_id`      | `str`            | Unique chunk identifier              |
| `graph_context` | `Optional[Dict]` | Related graph data                   |

### Properties

* `title` -- Document title (from `metadata`)
* `tags` -- Document tags (from `metadata`)
* `source` -- Source identifier (from `metadata`)

## JobStatus

Represents the status of an async processing job (insertion or upload).

```python theme={null}
from vrin import JobStatus

status = JobStatus.from_dict(client.get_job_status("job_abc123"))
print(status.status)         # "extracting"
print(status.progress)       # 65
print(status.is_completed)   # False
print(status.is_processing)  # True
```

### Fields

| Field           | Type             | Description                                                           |
| --------------- | ---------------- | --------------------------------------------------------------------- |
| `job_id`        | `str`            | Unique job identifier                                                 |
| `status`        | `str`            | `pending`, `chunking`, `extracting`, `storing`, `completed`, `failed` |
| `message`       | `str`            | Human-readable status message                                         |
| `progress`      | `int`            | Progress percentage (0-100)                                           |
| `timestamp`     | `Optional[int]`  | Job creation timestamp                                                |
| `completed_at`  | `Optional[int]`  | Completion timestamp                                                  |
| `data`          | `Optional[Dict]` | Result data (when completed)                                          |
| `error_details` | `Optional[str]`  | Error message (when failed)                                           |

### Properties

* `is_completed` -- `True` when status is `"completed"`
* `is_failed` -- `True` when status is `"failed"`
* `is_processing` -- `True` when status is any active state
* `completion_time` -- `datetime` from `completed_at`
* `creation_time` -- `datetime` from `timestamp`

## InsertResult

Structured response from an insert operation.

```python theme={null}
from vrin import InsertResult

result = InsertResult.from_dict(raw_result)
print(result.facts_extracted)  # 12
print(result.job_id)
```

### Fields

| Field             | Type            | Default | Description                     |
| ----------------- | --------------- | ------- | ------------------------------- |
| `success`         | `bool`          | `False` | Whether the operation succeeded |
| `job_id`          | `Optional[str]` | `None`  | Async job ID                    |
| `facts_extracted` | `int`           | `0`     | Number of facts extracted       |
| `message`         | `str`           | `""`    | Status message                  |
| `chunk_id`        | `Optional[str]` | `None`  | Chunk identifier                |

## UploadResult

Structured response from a file upload.

```python theme={null}
from vrin import UploadResult

result = UploadResult.from_dict(raw_result)
print(result.upload_id)
print(result.status)
```

### Fields

| Field       | Type            | Default | Description                  |
| ----------- | --------------- | ------- | ---------------------------- |
| `success`   | `bool`          | `False` | Whether the upload succeeded |
| `upload_id` | `Optional[str]` | `None`  | Upload identifier            |
| `filename`  | `Optional[str]` | `None`  | Uploaded filename            |
| `status`    | `str`           | `""`    | Processing status            |
| `message`   | `str`           | `""`    | Status message               |

## UserLimits

User plan information and usage limits.

```python theme={null}
from vrin import UserLimits

limits = UserLimits.from_dict(client.get_limits())
print(f"Plan: {limits.plan}")
print(f"Queries left: {limits.queries_remaining}")
```

### Fields

| Field               | Type        | Default  | Description                         |
| ------------------- | ----------- | -------- | ----------------------------------- |
| `plan`              | `str`       | `"free"` | Current plan name                   |
| `queries_remaining` | `int`       | `0`      | Queries remaining in billing period |
| `inserts_remaining` | `int`       | `0`      | Inserts remaining                   |
| `allowed_models`    | `List[str]` | `[]`     | Models available on current plan    |
| `max_file_size_mb`  | `int`       | `10`     | Maximum upload file size            |

## Conversation

Summary of a conversation session.

```python theme={null}
from vrin import Conversation

for raw in client.list_conversations():
    conv = Conversation.from_dict(raw)
    print(f"{conv.session_id}: {conv.title} ({conv.turn_count} turns)")
```

### Fields

| Field          | Type            | Default  | Description                    |
| -------------- | --------------- | -------- | ------------------------------ |
| `session_id`   | `str`           | required | Unique session identifier      |
| `title`        | `str`           | `""`     | Conversation title             |
| `created_at`   | `Optional[str]` | `None`   | Creation timestamp             |
| `last_updated` | `Optional[str]` | `None`   | Last update timestamp          |
| `turn_count`   | `int`           | `0`      | Number of query-response turns |
| `preview`      | `str`           | `""`     | Preview of the conversation    |