Metadata-Version: 2.4
Name: vantage-litellm-callback
Version: 0.0.7
Summary: Durable Vantage lifecycle callback for LiteLLM
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: litellm
Requires-Dist: pydantic>=2

# Vantage LiteLLM Callback

## Required Vantage collector

The callback works with the Vantage LiteLLM collector. To set up the Vantage
LiteLLM integration, install both components:

1. Run the collector beside each LiteLLM proxy. The collector stores usage
   events and uploads compacted batches to Vantage.
2. Install this callback in the LiteLLM Python environment. The callback sends
   usage events to the local collector over its Unix socket.

The callback cannot upload usage to Vantage by itself. The collector cannot
collect LiteLLM usage without the callback. See the collector repository README
for deployment and configuration instructions.

## Install

Install a released version with:

```sh
pip install vantage-litellm-callback
```

To work from a source checkout, install this directory with `pip install .`.
Configure LiteLLM with:

```yaml
litellm_settings:
  callbacks:
    - vantage_callback.callback_instance
```

See the repository README for collector setup and lifecycle billing semantics.

The callback is fail-open: collector outages, acknowledgement failures, malformed
responses, queue pressure, and projection errors never block or fail a provider
request. Usage events are placed into a bounded in-process queue and delivered by
a background worker. When delivery is unhealthy, the worker opens a circuit,
aggregates bounded loss information, and periodically probes the collector with a
versioned `delivery_gap` control frame. Normal delivery resumes only after that
frame receives a durable acknowledgement.

Configuration:

- `VANTAGE_COLLECTOR_DELIVERY_QUEUE_SIZE` (default `1024`)
- `VANTAGE_COLLECTOR_RECOVERY_PROBE_SECONDS` (default `5`)
- `VANTAGE_COLLECTOR_GAP_EVENT_ID_SAMPLE_SIZE` (default `32`)
- `VANTAGE_COLLECTOR_GAP_SUMMARY_INTERVAL_SECONDS` (default `60`)
- `VANTAGE_COLLECTOR_SOCKET_PATH` (default
  `/var/run/vantage-collector/collector.sock`)
- `VANTAGE_COLLECTOR_ACK_TIMEOUT_SECONDS` (default `5`)
- `VANTAGE_COLLECTOR_CONNECTION_POOL_SIZE` (default `16`)

The queue and gap aggregate are intentionally process-local and bounded. A
process exit may therefore lose queued events; the gap frame reports losses
observed while the process remains alive.
