dcaacbe407
- API: POST /v1/default/banks/{bank_id}/operations/{operation_id}/retry
resets status to pending so the worker re-executes the task
- UI: Retry button on failed operations in the operations view
- Control plane proxy route + ControlPlaneClient.retryOperation()
- Updated OpenAPI spec, all generated clients, and operations docs
121 lines
3.2 KiB
Markdown
121 lines
3.2 KiB
Markdown
---
|
|
sidebar_position: 9
|
|
---
|
|
|
|
# Operations
|
|
|
|
Background tasks that Hindsight executes asynchronously.
|
|
|
|
:::tip Prerequisites
|
|
Make sure you've completed the [Quick Start](./quickstart) and understand [how retain works](./retain).
|
|
:::
|
|
|
|
## How Operations Work
|
|
|
|
Hindsight processes several types of tasks in the background to maintain memory quality and consistency. These operations run automatically—you don't need to trigger them manually.
|
|
|
|
By default, all background operations are executed in-process within the API service.
|
|
|
|
:::note Kafka Integration
|
|
Support for external streaming platforms like Kafka for scale-out processing is planned but **not available out of the box** in the current release.
|
|
:::
|
|
|
|
## Operation Types
|
|
|
|
| Operation | Trigger | Description |
|
|
|-----------|---------|-------------|
|
|
| **batch_retain** | `retain_batch` with `async=True` | Processes large content batches in the background |
|
|
| **consolidate** | After `retain` | Consolidates new facts into observations |
|
|
|
|
## Async Retain Example
|
|
|
|
When retaining large batches of memories, use `async=true` to process in the background. The response includes an `operation_id` that you can use to poll for completion.
|
|
|
|
### 1. Submit async retain request
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/v1/default/banks/my-bank/memories" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"items": [
|
|
{"content": "Alice joined Google in 2023"},
|
|
{"content": "Bob prefers Python over JavaScript"}
|
|
],
|
|
"async": true
|
|
}'
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"bank_id": "my-bank",
|
|
"items_count": 2,
|
|
"async": true,
|
|
"operation_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
```
|
|
|
|
### 2. Poll for operation status
|
|
|
|
```bash
|
|
curl "http://localhost:8000/v1/default/banks/my-bank/operations"
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"bank_id": "my-bank",
|
|
"operations": [
|
|
{
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"task_type": "retain",
|
|
"items_count": 2,
|
|
"document_id": null,
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"status": "completed",
|
|
"error_message": null
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Operation Status Values
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| `pending` | Operation is queued and waiting to be processed |
|
|
| `completed` | Operation finished successfully |
|
|
| `failed` | Operation failed (check `error_message` for details) |
|
|
|
|
## Managing Operations
|
|
|
|
### Cancel a pending operation
|
|
|
|
```bash
|
|
curl -X DELETE "http://localhost:8000/v1/default/banks/my-bank/operations/550e8400-e29b-41d4-a716-446655440000"
|
|
```
|
|
|
|
### Retry a failed operation
|
|
|
|
If an operation fails, you can manually re-queue it for execution:
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/v1/default/banks/my-bank/operations/550e8400-e29b-41d4-a716-446655440000/retry"
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Operation 550e8400-e29b-41d4-a716-446655440000 queued for retry",
|
|
"operation_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
```
|
|
|
|
The operation status resets to `pending` and the worker picks it up again. Returns `409` if the operation is not in `failed` state.
|
|
|
|
## Next Steps
|
|
|
|
- [**Documents**](./documents) — Track document sources
|
|
- [**Memory Banks**](./memory-banks) — Configure bank settings
|