Skip to main content

llm-exp-gateway

Plugin para o CLI llm de Simon Willison que descobre modelos publicados por um gateway LiteLLM compatível com a API OpenAI. Apesar do nome do diretório de trabalho, este projeto é um plugin para o CLI llm, não uma aplicação web nem um plugin Datasette.

A inferência, o streaming, as ferramentas e os clientes síncrono e assíncrono são fornecidos pelas classes nativas Chat e AsyncChat do próprio llm. Os IDs locais recebem o prefixo exp/, enquanto a requisição upstream conserva o ID original. Assim, exp/Kimi-K3 chama o modelo Kimi-K3 no gateway.

Instalação

No ambiente em que o llm está instalado:

llm install llm-exp-gateway

Para uma cópia local em desenvolvimento:

llm install -e /caminho/para/datasette-llm

O pacote registra o entry point llm durante a instalação; não é necessário editar configuração do llm para habilitá-lo.

Configuração interativa

Não há endpoint padrão nem configuração de endpoint por variável de ambiente. Execute:

llm exp configure

O comando solicita o token, com entrada oculta, e o endpoint do gateway, que é obrigatório. O token é salvo com o nome exp pelo mesmo mecanismo usado por llm keys set exp; ele não é argumento de shell e, portanto, não entra no histórico de comandos nem é exibido pelo plugin. O endpoint pode ser informado com ou sem /v1 e com ou sem barra final, e é persistido normalizado para /v1. O arquivo de configuração contém somente esse metadado público, nunca o token.

Sem um endpoint salvo, o plugin não faz descoberta HTTP e orienta a executar llm exp configure, sem interromper os demais comandos do llm.

Também é possível usar as variáveis de ambiente:

  • EXP_API_KEY: token, como alternativa ao armazenamento nativo de chaves;
  • EXP_DISCOVERY_TIMEOUT: timeout em segundos de cada consulta HTTP (padrão 3.0; valores inválidos ou não positivos voltam ao padrão).

A configuração e o catálogo ficam no diretório global retornado por llm.user_dir():

  • exp-gateway.json: somente versão e endpoint efetivo normalizado;
  • exp-gateway-models.json: último catálogo válido, sem token ou cabeçalhos;
  • keys.json: credencial administrada exclusivamente pelo mecanismo nativo do llm, não pelo arquivo de configuração deste plugin.

llm exp configure não faz descoberta e funciona ainda que não exista uma configuração anterior.

Uso

Atualize e liste os modelos:

llm models
llm models --tools

Execute um prompt pontual:

llm -m exp/Kimi-K3 "Explique testes de contrato em três tópicos"

Ou inicie uma conversa contínua:

llm chat -m exp/Kimi-K3

Há suporte nativo a streaming e a ferramentas para todo ID anunciado por /models. Modelos com supports_vision: true em /model/info também aceitam anexos compatíveis, por exemplo:

llm -m exp/Kimi-K3 "Descreva esta imagem" -a imagem.png

Descoberta, metadados e fallback

A cada invocação do hook de modelos em um processo, o plugin consulta:

  1. GET {endpoint}/models, com Authorization: Bearer ...;
  2. GET {endpoint}/model/info, opcionalmente, para enriquecer os metadados.

A lista de /models é autoritativa. Um modelo presente somente em /model/info nunca é registrado. Falha, timeout ou JSON inválido no segundo endpoint não impede o uso da lista principal. Respostas HTTP 401 e 403 da lista principal produzem orientação explícita para revisar a autenticação; o corpo da resposta e o token não são expostos em mensagens.

max_input_tokens aceita número ou string. Quando disponível, max_output_tokens é usado como limite padrão de saída do Chat nativo. Não há limite inventado na ausência do metadado. Visão depende exclusivamente de supports_vision: true; não se infere reasoning nem visão pelo nome do modelo. Respostas continuam sendo processadas pelas implementações nativas do llm, inclusive os metadados que elas já preservam.

O catálogo válido substitui integralmente o cache por escrita temporária e rename atômico, evitando IDs obsoletos ou duplicados. O isolamento por endpoint impede reutilizar o catálogo de outro gateway. Se a renovação falhar, o último catálogo válido do mesmo endpoint é usado temporariamente e uma mensagem clara é emitida no stderr. Na primeira falha, sem cache, o plugin não interrompe os demais comandos do llm. Sem endpoint salvo, nenhuma requisição é feita. Com endpoint salvo, mas sem token no mecanismo nativo de chaves ou em EXP_API_KEY, também não há requisição e só pode haver fallback ao cache público do mesmo endpoint.

Desenvolvimento e testes

A partir da raiz deste repositório, usando o virtualenv .venv da raiz:

uv venv .venv
uv pip install --python .venv/bin/python -e './datasette-llm[dev]'
.venv/bin/python -m pytest datasette-llm/tests -p no:cacheprovider

O plugin não carrega arquivos .env nem consulta EXPLLM_KEY em runtime. Essa variável é reservada exclusivamente para validação manual de desenvolvimento; não é uma alternativa ao mecanismo nativo de chaves ou a EXP_API_KEY.

Os testes usam httpx.MockTransport, mocks e diretórios temporários isolados para llm.user_dir()/LLM_USER_PATH. Eles não acessam o gateway real, não leem a configuração pessoal e não deixam tokens de teste fora dos diretórios temporários. A distribuição também foi validada com uv build e, em LLM_USER_PATH isolado, com o gateway real: descoberta dos 9 modelos, inferências síncrona e assíncrona e execução de uma ferramenta pelo modelo.

Na versão atual do gateway, o campo não padrão metadata das respostas pode ser uma lista, enquanto o SDK OpenAI espera outro formato. Algumas versões do SDK/Pydantic emitem um UserWarning ao serializá-lo para os logs do llm. Esse aviso é originado pela conversão nativa do SDK, não contém o token e não impediu as respostas ou as ferramentas na validação real.

Metadata

Release files for llm-exp-gateway 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for llm-exp-gateway 1.0.0
File Size Uploaded Provenance Actions
llm_exp_gateway-1.0.0.tar.gz 16.3 kB With provenance Details for llm_exp_gateway-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for llm-exp-gateway 1.0.0
File Interpreter ABI Platform Actions
llm_exp_gateway-1.0.0-py3-none-any.whl Python 3 none any Details for llm_exp_gateway-1.0.0-py3-none-any.whl

Total release size: 26.7 kB

Release files / llm_exp_gateway-1.0.0.tar.gz

Download URL llm_exp_gateway-1.0.0.tar.gz
Size 16.3 kB
Tags Source
SHA-256 checksum
How to use checksums
611c0fd24995ff1813be7b7c4afb7bb83a3ae8b9c154e40519c224cfcd9ce282
BLAKE2b-256 checksum
How to use checksums
e2e98d050c29b6522ff598ac8429559cf136e48553d54ba9e6193264a1c184a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / llm_exp_gateway-1.0.0-py3-none-any.whl

Download URL llm_exp_gateway-1.0.0-py3-none-any.whl
Size 10.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7ef74cdfa9d7e63fd4f47f356b7a470084701bc382efd2aeed3844ed9b239252
BLAKE2b-256 checksum
How to use checksums
edb09207ed73c06c7d9c24e7a980bc1aa5ece3507807673d975a52d2cbbea833
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for llm-exp-gateway 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for llm_exp_gateway-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page