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ão3.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 dollm, 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:
GET {endpoint}/models, comAuthorization: Bearer ...;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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.