Copilot LLM Gateway

Gateway Python/FastAPI que expõe OpenAI Chat Completions e traduz pedidos para um provider HTTP customizado. Ele não contém lógica específica do GitHub Copilot nem executa ferramentas: apenas preserva o protocolo entre o cliente e o provider.

Arquitetura e fluxo

Copilot CLI -> POST /v1/chat/completions (SSE opcional) -> OpenAI compatibility -> CustomLLMProvider -> POST /generate.

O adapter normaliza a resposta do provider em eventos internos; a camada OpenAI converte-os em JSON ou SSE. Isso permite adicionar um provider sem mudar as rotas HTTP.

Requisitos e instalação

Python 3.12+ e um provider que implemente POST /generate. Instale com make install, copie .env.example para .env e ajuste CUSTOM_LLM_BASE_URL e as chaves.

Executar

make dev ou uvicorn app.main:app --host 0.0.0.0 --port 8080.

Configure o Copilot CLI:

export COPILOT_PROVIDER_TYPE=openai
export COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:8080/v1
export COPILOT_PROVIDER_API_KEY=local-copilot-key
export COPILOT_MODEL=custom-coder

copilot

Exemplo não streaming:

curl http://localhost:8080/v1/chat/completions \
  -H 'Authorization: Bearer local-copilot-key' -H 'Content-Type: application/json' \
  -d '{"model":"custom-coder","messages":[{"role":"user","content":"Hello"}],"stream":false}'

Para streaming use "stream":true; a resposta usa text/event-stream, chunks OpenAI e termina em data: [DONE].

Tool calling

Envie tools e tool_choice normalmente. O provider devolve tool_calls ou eventos tool_call_delta; o gateway preserva id, name, argumentos incrementais e índice. O cliente executa a ferramenta e reenvia o resultado como uma mensagem role=tool, incluindo tool_call_id.

Contrato do provider

CustomLLMProvider envia POST /generate com model, messages, tools, tool_choice, stream e generation. No modo normal recebe text, tool_calls, finish_reason e usage; no streaming aceita NDJSON ou SSE com text_delta, tool_call_delta, done e error.

Para criar outro provider implemente LLMProvider em app/providers/base.py, normalize-o nos modelos de app/providers/models.py e registre-o no factory de app/main.py.

Docker, testes e qualidade

docker build -t copilot-llm-gateway .
docker run -p 8080:8080 --env-file .env copilot-llm-gateway
make test
make lint
make typecheck

O Compose sobe somente o gateway: configure o URL do provider externo em .env.

Troubleshooting

• 401: confira PROXY_API_KEY e o Bearer enviado pelo cliente.
• 502/504: valide conectividade, URL e timeout do provider; credenciais upstream não aparecem nos logs.
• Streaming parado: o provider deve produzir linhas NDJSON ou data: <JSON> SSE e terminar com done ou [DONE].
• Modelo ausente: use o valor de CUSTOM_LLM_MODEL; /v1/models o expõe.