mirror of
https://github.com/BerriAI/litellm.git
synced 2026-11-18 09:45:23 +00:00
3.6 KiB
3.6 KiB
- Target invariants, not completion claims
- Keep this crate the Python runtime adapter for
litellm-callbacks-v1and nothing else: the subscriber snapshot and onePythonLifecyclethat delivers the core contract- Envelopes, sequencing, routing, the interceptor fold, redaction, handler selection and wire patch validation belong to
litellm-callbacks-v1; this adapter drives itsCallSessionand adds only projection (Python arguments, response and exception into facts) and execution (calling handlers,Await/resume, cancellation, GC traversal) - The snapshot splits each subscriber into the contract's
Subscriptionand this crate'sHandlers, kept at the same index litellm/rust_bridge/callbacks_v1.pyis the only Python module Rust imports;python_contract.jsonpins its functions on both sides- The typed authoring surface (callback protocols, envelope and patch types, the registry) is
litellm/callbacks_v1/__init__.py; the bridge module re-exportssnapshotfrom it and otherwise holds only marshalling
- Envelopes, sequencing, routing, the interceptor fold, redaction, handler selection and wire patch validation belong to
- Terms (contract terms are in
callbacks-v1/AGENTS.md, lifecycle terms inhost-python/AGENTS.md)- Registry: the process-wide subscriber list; it lives in Python (
register/unregister), never in Rust - Snapshot: that list read once per call, with one observer and one interceptor handler already selected per subscriber for the call's mode (
subscribers.rs) - Projection: the public response turned into JSON by
project_response; a failed projection becomesresponse_error, never a failed call - Report: logging an observer's swallowed error through
report - Continuation: what a step returns to the driver once every observer of its envelope has run
- "Callback" in the Python module (
Callbackprotocol) is the user's object; once registered it is a subscriber
- Registry: the process-wide subscriber list; it lives in Python (
- No Python object of the call reaches a callback; a callback influences a call only through a patch Rust validates
beginreturns the dict it was given by identity;after_successanddeliveredstay the trait's pass-through defaults- Every callback gets a freshly built envelope per event; never cache or share a converted one
- Contract values cross into Python only through a fresh conversion per callback
- Schema v1 is owned by
litellm-callbacks-v1; this crate only marshals it- Everything rejectable is rejected at
register, never during a call; the snapshot only parses and the lifecycle never re-validates a subscriber
- Everything rejectable is rejected at
- Observers cannot affect a call: ordinary exceptions are reported and swallowed at every event, awaited or not; an interceptor failure fails the call
- A cancellation is returned at once, with no further dispatch and no report
- Exactly one terminal envelope, last; none after a cancellation
- In a sync call no step suspends: handler selection happens once, at snapshot, from what registration recorded
- Every suspension is awaited inline in the caller's task; never
into_future, never spawn
- Every suspension is awaited inline in the caller's task; never
- The subscriber snapshot is taken once per call before the driver starts; later registrations do not reach that call
V1PythonLifecycle::subscribedis the only constructor callers get; it returnsNonefor an empty snapshot, so an unobserved call builds no envelope and projects no response- This lifecycle may run after another one in a
LifecycleChain; it observes the arguments and the wire as that one left them and never assumes it is alone
closeis idempotent;traversevisits every retained Python edge and calls no Python- This crate has none of
callbacks-legacy-python's obligations and must not grow them; shared behaviour belongs toPythonLifecycle, not to either adapter