SDK Guarantees

​

Delivery Guarantees

• 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

• 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

• 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

• 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

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

​

Invalid Requests

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

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

​

Manual Flush

# Flush all buffered events immediately
value.flush()

​

Graceful Shutdown

# Flush remaining events and close
value.close()

with ValueClient(api_key="sk_live_abc123xyz") as value:
    value.send_action(...)
    # Automatically flushes and closes

​

Performance

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

​

Monitoring

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