litellm/litellm-rust/crates/callbacks-legacy-python/AGENTS.md

• Target invariants, not completion claims
• This crate is the legacy @client wrapper as the native call sees it, and nothing else: the Logging contract (function_setup, the deployment hooks, pre_call/post_call, the sync and async success and failure fan-out, the deferred proxy release, the argument sharing those callbacks rely on)
  • Smell test: if a future callback host (callbacks-v1-python, WASM, in-process Rust) could share a piece of this crate, it does not belong here
  • SDK request policy (credential inheritance, the budget and retry-count limits) is the driver's preflight, supplied by python-bridge; this crate only adopts the keyword view it produces
  • The driver in litellm-host-python, the routes and core see one PythonCallHooks; they never learn which Python objects consume a call
• Every litellm Python internal Rust still borrows is a variant of LegacyPython, grouped by subsystem, with its signature pinned in python_contract.json
  • The enum only shrinks: when Rust owns a subsystem, delete its group rather than adding a Rust path beside it
  • Calling a user's own callback directly is permanent Python surface and gets its own type outside LegacyPython
• PublicCall is the caller's call as Logging sees it: the positional arguments, the keyword view as the call rewrites it (setup, deployment hook, preflight) and the bound request object backing omitted keywords; routes hand it over through run_legacy_call and keep no copy
• setup reuses a Logging passed as litellm_logging_obj (the proxy and Router) and otherwise builds one through function_setup; which callbacks run is Logging's decision, never this crate's
• Callbacks receive the caller's own objects and may mutate them; this crate alone carries that obligation
  • Retain complete boundary arguments, opaque values, aliases, omitted/default distinctions and deliberate copies; preserve the deployment-hook kwargs view
  • Before pre_call, re-alias every body key whose value equals the caller's argument to the caller's own object, resolved through litellm_host_python::lookup
  • Retain body/header roots from pre_call to post_call; in-place mutation reaches the wire, envelope field replacement is visible to later callbacks only
• Success and failure handlers receive the exact selected public response or exception
  • A failure-handler error cannot suppress the other eligible family or replace the mapped provider error; a cancellation ends the call with no further dispatch
  • Dispatch errors never replay provider work or trigger the opposite outcome; the proxy releases deferred success at most once
  • Delivery follows the registry, not the callable's type: direct, awaited, executor-submitted, logging-worker and deferred paths stay distinct
• Traverse every retained Python edge; close is idempotent and restores the correlation context once