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

# SDK Guarantees

> Delivery guarantees, buffering, and error handling

## Delivery Guarantees

The Valmi Value SDK provides **at-least-once delivery**:

* Events are guaranteed to be delivered at least once
* Events may be delivered multiple times (deduplication handled server-side)
* Events are never lost (buffered locally if API unavailable)

## Offline Buffering

Events are automatically buffered locally when:

* Network is unavailable
* API is temporarily down
* Rate limits are hit

### Buffer Behavior

* **Automatic Buffering**: Events are stored locally
* **Automatic Retry**: SDK retries sending buffered events
* **Buffer Size**: Configurable buffer size (default: 100 events)
* **Flush Interval**: Automatic flush every N seconds (default: 5)

### Buffer Configuration

```python theme={null}
value = ValueClient(
    api_key="sk_live_abc123xyz",
    buffer_size=1000,  # Buffer up to 1000 events
    flush_interval=10,  # Flush every 10 seconds
)
```

## Retry Logic

The SDK automatically retries failed requests:

* **Max Retries**: Configurable (default: 3)
* **Exponential Backoff**: Retries with increasing delays
* **Retryable Errors**: Network errors, 5xx status codes
* **Non-Retryable Errors**: 4xx errors (except rate limits)

### Retry Configuration

```python theme={null}
value = ValueClient(
    api_key="sk_live_abc123xyz",
    max_retries=5,  # Retry up to 5 times
    retry_delay=1,  # Initial retry delay in seconds
)
```

## Deduplication

Server-side deduplication prevents duplicate events:

* **Event IDs**: Each event gets a unique ID
* **Deduplication Window**: 24-hour deduplication window
* **Automatic Handling**: No action required from you

## Error Handling

### Network Errors

Network errors are handled automatically:

* Events are buffered locally
* SDK retries when connection is restored
* No data loss

### Invalid Requests

Invalid requests return errors:

```python theme={null}
try:
    value.send_action(
        agent_key="invalid_key",
        action_type="llm_call",
        metadata={...}
    )
except ValueError as e:
    # Invalid agent key or parameters
    print(f"Error: {e}")
```

### Rate Limiting

Rate limits are handled gracefully:

* Events are buffered when rate limited
* SDK automatically retries with backoff
* No data loss

## Manual Flush

Manually flush buffered events:

```python theme={null}
# Flush all buffered events immediately
value.flush()
```

## Graceful Shutdown

Close the client gracefully:

```python theme={null}
# Flush remaining events and close
value.close()
```

Or use context manager:

```python theme={null}
with ValueClient(api_key="sk_live_abc123xyz") as value:
    value.send_action(...)
    # Automatically flushes and closes
```

## Performance

The SDK is designed for performance:

* **Non-Blocking**: Sends events asynchronously
* **Batch Support**: Efficient batch sending
* **Minimal Overhead**: Low performance impact
* **Connection Pooling**: Reuses connections

## Monitoring

Monitor SDK health:

* **Event Count**: Track events sent
* **Error Rate**: Monitor error rates
* **Buffer Size**: Monitor buffer usage
* **Retry Count**: Track retry attempts