Skip to content

Feature request: support extra_headers in config.toml #32

Description

@lionhylra

Problem

Some litellm providers and local proxies require custom HTTP headers on every
request — for example:

  • Anthropic extended features: anthropic-beta: interleaved-thinking-2025-05-14
  • LiteLLM proxy authentication: x-litellm-api-key: <token>
  • Observability / tracing: x-trace-id: my-service

There is currently no way to pass these headers through OpenChronicle's config.
Users who need them must fork the code or intercept at the network layer.

Proposal

Add an optional extra_headers table to any [models.*] section. Headers are
forwarded verbatim to every litellm.completion() call for that stage, and
inherited from [models.default] like all other model fields.

[models.default]
model = "claude-opus-4-5"
api_key_env = "ANTHROPIC_API_KEY"

[models.default.extra_headers]
anthropic-beta = "interleaved-thinking-2025-05-14"
x-trace-id     = "openchronicle"

[models.classifier]
model = "claude-opus-4-5"
# inherits extra_headers from default; override per-stage if needed

Behaviour

  • extra_headers defaults to {} — no change for existing configs.
  • Stage sections inherit the default's headers unless they define their own
    extra_headers table, which fully replaces (not merges) the default for
    that stage.
  • Values must be strings; non-string TOML values (e.g. integers) are rejected
    at the litellm call site.

Implementation notes

Changes required in two files:

  1. src/openchronicle/config.py — add extra_headers: dict[str, str]
    field to ModelConfig; copy the dict in _build_models when inheriting
    from default so each stage owns an independent dict.
  2. src/openchronicle/writer/llm.py — pass extra_headers to
    litellm.completion() in both call_llm and ping_stage (a shallow copy
    prevents litellm from mutating config state).

PR

Implementation + tests available at
main...lionhylra:OpenChronicle:support-extra-headers

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions