Skip to main content

​
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

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

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: 
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: 
# Flush all buffered events immediately
value.flush()

​
Graceful Shutdown

Close the client gracefully: 
# Flush remaining events and close
value.close()
Or use context manager: 
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