sidecar

Documentation

Overview

Package sidecar manages the v1 LiteLLM proxy subprocess that serves the Anthropic-wire translator until v2's native Go translator replaces it (see the architecture plan, §5.4).

Index

• Variables
• func RenderConfig(p profile.Profile, apiKey, masterKey string) ([]byte, error)
• type State
• type Supervisor
  • func (s *Supervisor) LogPath() string
  • func (s *Supervisor) Start(ctx context.Context, configPath string, port int) error
  • func (s *Supervisor) State() State
  • func (s *Supervisor) Stop(timeout time.Duration) error

Variables

var ErrBinaryNotFound = errors.New(`sidecar: litellm not found on PATH; install it with "pipx install litellm" or see https://docs.litellm.ai/docs/proxy/quick_start`)

ErrBinaryNotFound is returned by Start when the configured binary (default "litellm") is not on PATH. This is the v1 hybrid-engine trade-off: LiteLLM is a Python tool we shell out to until v2's native Anthropic translator removes the dependency.

Functions

func RenderConfig

func RenderConfig(p profile.Profile, apiKey, masterKey string) ([]byte, error)

RenderConfig builds the LiteLLM proxy YAML config for p's tier->model mappings. Every model entry uses apiKey (the user's OPENROUTER_API_KEY) as its credential. masterKey becomes LiteLLM's own required bearer token, so only the AgentRoute gateway (which is the only holder of masterKey) can reach the sidecar directly.

Model names in the rendered config are AgentRoute aliases (see profile.Alias), matching exactly what the gateway's ModelRouter resolves requests to before proxying here — so the sidecar receives a model name it already has a model_list entry for.

Types

type State

type State string

State is the lifecycle state of a supervised sidecar process.

const (
	StateStopped  State = "stopped"
	StateStarting State = "starting"
	StateRunning  State = "running"
	StateCrashed  State = "crashed"
)

The lifecycle states a Supervisor reports via State().

type Supervisor

type Supervisor struct {
	// Binary is the executable to run. Defaults to "litellm" if empty.
	Binary string
	// ExtraEnv is appended to the subprocess's environment in addition to
	// the current process's environment. Tests use this to re-exec the
	// test binary as a fake LiteLLM server instead of requiring a real
	// litellm install.
	ExtraEnv []string
	// HealthTimeout bounds how long Start waits for the sidecar to report
	// healthy before giving up. Defaults to 20s if zero.
	HealthTimeout time.Duration
	// contains filtered or unexported fields
}

Supervisor starts, health-checks, and stops a single LiteLLM proxy subprocess. It is safe for concurrent use.

func (*Supervisor) LogPath

func (s *Supervisor) LogPath() string

LogPath returns the path of the sidecar's combined stdout/stderr log from the most recent Start call, or "" if Start has never been called.

func (*Supervisor) Start

func (s *Supervisor) Start(ctx context.Context, configPath string, port int) error

Start launches the sidecar with configPath, listening on port, and blocks until it reports healthy or ctx/HealthTimeout expires. If health never arrives, the process is killed and the last lines of its log are included in the returned error.

func (*Supervisor) State

func (s *Supervisor) State() State

State reports the supervisor's current view of the sidecar's lifecycle.

func (*Supervisor) Stop

func (s *Supervisor) Stop(timeout time.Duration) error

Stop terminates the sidecar's whole process tree (a Python LiteLLM process commonly spawns worker subprocesses; killing only the immediate pid leaves orphans and the port held). It waits up to timeout for a graceful exit before force-killing. Stop on a never-started or already-stopped Supervisor is a no-op.