Custom endpoints & auth

A model that is an HTTP endpoint is one you configure here. (It need not be — if your model runs in-process, keep the same client and swap the transport; base_url and headers are then just values your own callable receives and can ignore.) Auth is a header template: you write "Bearer ${OPENAI_API_KEY}", and the ${ENV_VAR} is expanded from the process environment at the moment the request is sent — never before. The secret’s value never lives on a client object, in a config, in a repr, or in a log. Only the ${NAME} placeholder is ever held.

First-class auth on any model client

${ENV} header auth is the same mechanism in all three ports: the template is held on the client, and the HTTP layer expands it at the request boundary — Python HttpClient, Go models.HTTPClient.ResolveHeaders, JavaScript HttpClient.resolveHeaders. Same embedding endpoint, one tab per language:

Python

from citenexus import OpenAICompatibleEmbedding

embedder = OpenAICompatibleEmbedding(
    base_url="https://api.jina.ai/v1",
    model="jina-embeddings-v3",
    headers={
        "Authorization": "Bearer ${JINA_API_KEY}",   # expands at call time
        "X-Tenant": "legal",                          # arbitrary provider header
    },
)
vectors = embedder.embed_many(["hello"])

Go

import "github.com/muthuishere/citenexus/golang/models"

// A real net/http transport; timeout 0 means the 60s default.
http := models.NewHTTPClient(nil, 0)

embedder := models.NewOpenAIEmbedding(
    "https://api.jina.ai/v1", "jina-embeddings-v3",
    http.Transport(),
    models.WithHeaders(map[string]string{
        "Authorization": "Bearer ${JINA_API_KEY}", // expands at call time
        "X-Tenant":      "legal",
    }),
)
vectors, err := embedder.Embed([]string{"hello"})

JavaScript

import { HttpClient, OpenAIEmbedder } from "@muthuishere/citenexus";

const http = new HttpClient();

const embedder = new OpenAIEmbedder(
  {
    base_url: "https://api.jina.ai/v1",
    model: "jina-embeddings-v3",
    headers: {
      Authorization: "Bearer ${JINA_API_KEY}",   // expands at call time
      "X-Tenant": "legal",
    },
  },
  (url, body, headers) => http.send(url, body, headers),
);
const vectors = await embedder.embed(["hello"]);

The same option carries a bare token under whatever header name a provider wants — {"x-api-key": "${ACME_TOKEN}"} — so a non-Bearer scheme needs no special support.

Chat generation is the same shape in all three:

Python

from citenexus import OpenAICompatibleGenerator

generator = OpenAICompatibleGenerator(
    base_url="https://api.openai.com/v1",
    model="gpt-4o-mini",
    headers={"Authorization": "Bearer ${OPENAI_API_KEY}"},
)

Go

generator := models.NewOpenAIChatGenerator(
    "https://api.openai.com/v1", "gpt-4o-mini",
    0.0, nil, // temperature, max_tokens (nil → omitted from the request)
    http.Transport(),
    models.WithHeaders(map[string]string{"Authorization": "Bearer ${OPENAI_API_KEY}"}),
)

JavaScript

import { HttpClient, OpenAIChatGenerator } from "@muthuishere/citenexus";

const generator = new OpenAIChatGenerator(
  {
    base_url: "https://api.openai.com/v1",
    model: "gpt-4o-mini",
    headers: { Authorization: "Bearer ${OPENAI_API_KEY}" },
  },
  (url, body, headers) => new HttpClient().send(url, body, headers),
);

Which clients each port ships

Go and JavaScript publish an embedding client, an OpenAI-compatible chat generator, and a native Anthropic generator (models.NewAnthropicGenerator / AnthropicGenerator). The vision and reranker clients (OpenAICompatibleVision, OpenAICompatibleReranker) are Python-only — the ports publish no such contract, so there is no port tab to write for them.

# Python only — vision and reranking clients take the same headers= templates.
from citenexus import OpenAICompatibleVision

vision = OpenAICompatibleVision(
    base_url="https://api.internal.acme/v1",
    model="acme-vlm",
    headers={
        "x-api-key": "${ACME_TOKEN}",        # bare token, custom auth header
        "X-Tenant": "legal",                  # arbitrary provider header
    },
)

Why templates, not values

Passing api_key=os.environ["KEY"] pulls the secret value into your code and the client object, where it can end up in a stack trace, a debugger, a serialized config, or an LLM’s context. A ${ENV} template never does: the value is read from the environment only inside the HTTP client, only for that one request, and header values are never logged. Reference the key by name — expand it at the edge.

Typed provider endpoints — Python only

Everything from here down belongs to the Python facade: HttpEndpoint, the typed subclasses, and from_config are the config layer, and the ports have no config layer to wire them into. In Go and JavaScript you construct the client directly, exactly as the tabs above show.

For config-driven wiring, the typed HttpEndpoint subclasses carry the same ${ENV} headers (and reusable defaults like the right base URL and auth style):

from citenexus import (
    OpenAIHttpEndpoint, GeminiHttpEndpoint, AnthropicHttpEndpoint,
    OpenRouterHttpEndpoint, OllamaHttpEndpoint,
)

openai = OpenAIHttpEndpoint(headers={"Authorization": "Bearer ${OPENAI_API_KEY}"})
gemini = GeminiHttpEndpoint(headers={"Authorization": "Bearer ${GEMINI_API_KEY}"})
claude = AnthropicHttpEndpoint(headers={"x-api-key": "${ANTHROPIC_API_KEY}"})  # no Bearer
local  = OllamaHttpEndpoint(base_url="http://localhost:11434/v1")             # no key

A private gateway is just the general HttpEndpoint — URL, ${ENV} token in a header of your choosing, and arbitrary per-request headers:

from citenexus import HttpEndpoint

endpoint = HttpEndpoint(
    base_url="https://llm.internal.acme/v1",
    headers={
        "Authorization": "Bearer ${ACME_TOKEN}",
        "X-Tenant": "legal", "X-Env": "prod",
    },
    timeout_s=60,
)

Wiring endpoints into the client

Endpoints are applied through from_config — CiteNexus builds each model client with a transport that expands the ${ENV} headers at call time:

from citenexus import CiteNexus, GeminiHttpEndpoint, OpenAIHttpEndpoint
from citenexus.config.schema import (
    CiteNexusConfig, EmbeddingConfig, LLMConfig, RerankerConfig, StorageConfig,
)
from citenexus.config.signals import Signal

jina = OpenAIHttpEndpoint(
    base_url="https://api.jina.ai/v1",
    headers={"Authorization": "Bearer ${JINA_API_KEY}"},
)
config = CiteNexusConfig(
    storage=StorageConfig(bucket="./citenexus-data"),
    embedding=EmbeddingConfig(endpoint=jina, model="jina-embeddings-v3"),
    reranker=RerankerConfig(endpoint=jina, model="jina-reranker-v2-base-multilingual"),
    llm=LLMConfig(
        endpoint=GeminiHttpEndpoint(headers={"Authorization": "Bearer ${GEMINI_API_KEY}"}),
        model="gemini-2.5-flash",
    ),
    signals=(Signal.embedding, Signal.text),
)

rag = CiteNexus.from_config(config)   # each client resolves ${ENV} headers at the edge

Driving the HTTP layer yourself

If you would rather not use a shipped client, the HTTP layer is public on its own — the ${ENV} expansion lives there, not in the clients:

Python

from citenexus.http import HttpClient

client = HttpClient()                    # the client *is* the transport: __call__
raw = client(
    "https://api.jina.ai/v1/embeddings",
    b'{"model": "jina-embeddings-v3", "input": ["hello"]}',
    {"Authorization": "Bearer ${JINA_API_KEY}"},   # expanded inside the call
)

Go

client := models.NewHTTPClient(nil, 0)
raw, err := client.Do(
    "https://api.jina.ai/v1/embeddings",
    []byte(`{"model":"jina-embeddings-v3","input":["hello"]}`),
    map[string]string{"Authorization": "Bearer ${JINA_API_KEY}"},
)

JavaScript

const http = new HttpClient();
const raw = await http.send(
  "https://api.jina.ai/v1/embeddings",
  JSON.stringify({ model: "jina-embeddings-v3", input: ["hello"] }),
  { Authorization: "Bearer ${JINA_API_KEY}" },
);

In every port the merge order is the same — User-Agent < client defaults < per-call headers, auth wins — and the templates stay unexpanded until the one call that sends them (resolve_headers / ResolveHeaders / resolveHeaders).

Transport is (url, body, headers) => string | Promise<string>, so an async transport needs no cast — a consumer awaits either. HttpClient.send is async (Node fetch); resolveHeaders is the synchronous primitive underneath it, so a synchronous transport (the hermetic test fakes) stays valid.

Legacy: api_key on HttpEndpoint

HttpEndpoint(api_key=SecretStr(...), auth_header=..., auth_scheme=...) still works for backward compatibility and materializes the value into the endpoint object. Prefer an ${ENV} header — it keeps the value out of the object entirely. Non-Bearer providers are covered by a header key of your choice ("x-api-key": "${TOKEN}"), so auth_header/auth_scheme are rarely needed.

Writing a model that is not an HTTP endpoint at all — in-process, a local daemon, an adapter for a third library, a fixture? Keep these same clients and replace one callable: Bring your own model — swap the transport.