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

# Knowledge Management

> Insert content, track processing jobs, and explore the knowledge graph

## insert()

Insert text content into the knowledge base. Vrin chunks the text, extracts facts (entities + relationships), and indexes everything for retrieval.

```python theme={null}
result = client.insert(
    "ACME Corp reported $50M revenue in Q4 2025, up 23% YoY.",
    title="ACME Q4 Earnings"
)
```

By default, `insert()` waits for processing to complete. Pass `wait=False` to get a job ID and poll later.

### Parameters

<ParamField body="content" type="string" required>
  Text content to insert into the knowledge base.
</ParamField>

<ParamField body="title" type="string" default="Untitled">
  Document title. Used in search results and source attribution.
</ParamField>

<ParamField body="tags" type="List[str]">
  Optional tags for categorization and filtering.
</ParamField>

<ParamField body="metadata" type="Dict[str, Any]">
  Optional metadata dict attached to the document.
</ParamField>

<ParamField body="wait" type="bool" default="True">
  If `True`, poll until processing completes and return the result dict.
  If `False`, return the job ID string immediately.
</ParamField>

<ParamField body="poll_interval" type="float" default="2.0">
  Seconds between status polls when `wait=True`.
</ParamField>

<ParamField body="max_wait" type="float" default="300.0">
  Maximum seconds to wait when `wait=True`. Raises `TimeoutError` if exceeded.
</ParamField>

### Synchronous (default)

```python theme={null}
result = client.insert(
    "ACME Corp reported $50M revenue in Q4 2025.",
    title="ACME Financials",
    tags=["earnings", "2025"]
)
# result contains facts_extracted, chunk_id, etc.
```

### Asynchronous

```python theme={null}
job_id = client.insert(
    "Long document content...",
    title="Annual Report",
    wait=False
)
print(f"Job started: {job_id}")

# Check status manually
status = client.get_job_status(job_id)
print(status["status"])  # "pending" | "chunking" | "extracting" | "completed"

# Or wait for completion later
result = client.wait_for_job(job_id)
```

## get\_job\_status()

Check the status of an async insertion job.

```python theme={null}
status = client.get_job_status("job_abc123")
```

### Parameters

<ParamField body="job_id" type="string" required>
  The job ID returned by `insert(wait=False)`.
</ParamField>

### Returns

```json theme={null}
{
  "job_id": "job_abc123",
  "status": "extracting",
  "progress": 0.65,
  "message": "Extracting facts from chunks..."
}
```

Job statuses progress through: `pending` -> `chunking` -> `extracting` -> `storing` -> `completed`.

## wait\_for\_job()

Poll a job until completion or timeout. Logs progress as the job moves through stages.

```python theme={null}
result = client.wait_for_job("job_abc123", poll_interval=3.0, max_wait=120.0)
```

### Parameters

<ParamField body="job_id" type="string" required>
  The job ID to wait on.
</ParamField>

<ParamField body="poll_interval" type="float" default="2.0">
  Seconds between status polls.
</ParamField>

<ParamField body="max_wait" type="float" default="300.0">
  Maximum seconds to wait. Raises `TimeoutError` if exceeded.
</ParamField>

### Exceptions

* **`JobFailedError`** -- The job failed during processing.
* **`TimeoutError`** -- The job did not complete within `max_wait` seconds. Use `get_job_status()` to check current state.

## get\_knowledge\_graph()

Get knowledge graph visualization data showing entities and their relationships.

```python theme={null}
graph = client.get_knowledge_graph(limit=50)
# Returns nodes (entities) and edges (relationships)
```

### Parameters

<ParamField body="limit" type="int" default="100">
  Maximum number of graph elements to return.
</ParamField>

## What happens during insertion

When you call `insert()`, Vrin:

1. **Chunks** the text into overlapping segments optimized for retrieval
2. **Extracts facts** -- entities, relationships, and attributes using an LLM
3. **Stores facts** in the knowledge graph (Neptune) with `{model, timestamp, confidence}` metadata
4. **Indexes chunks** in the vector store (OpenSearch) with BM25 + kNN embeddings
5. Returns a summary with fact counts and chunk IDs