Instalar o nrgrd
nrgrd é o cliente de terminal da NeuroGrid: um agente de código que trabalha
no seu repositório pelo shell. Ele se conecta a qualquer endpoint compatível
com OpenAI, incluindo um deployment da NeuroGrid, e está publicado no PyPI
como nrgrd.
Roda em macOS, Linux e Windows, e precisa do Python 3.11 ou mais recente.
Essa é a ferramenta para usar inferência. Se você quer alugar uma GPU, o que você quer é o agente, que vem como uma imagem Docker.
Instalação
Com uv (recomendado)
O uv instala o nrgrd no próprio ambiente dele, coloca o comando nrgrd no
seu PATH, e baixa um Python adequado se você não tiver um.
uv tool install nrgrd
Ainda não tem o uv? Instale primeiro, depois rode o comando acima em um terminal novo.
# macOS e Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Com pipx
Precisa do Python 3.11 ou mais recente já instalado.
pipx install nrgrd
Com pip
Instale em um ambiente virtual, não no Python do sistema. O nrgrd fica então disponível sempre que esse ambiente estiver ativo.
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install nrgrd
Confira se funcionou
nrgrd --version
Isso imprime a versão instalada, por exemplo nrgrd 0.1.0.
Primeira execução
Abra um terminal no projeto com o qual você quer trabalhar e inicie o nrgrd:
cd meu-projeto
nrgrd # interativo
nrgrd "explique este repositório" # um único prompt, depois sai
Na primeira vez, ele pede a URL do endpoint e a API key do seu deployment, as duas da sua consola da NeuroGrid. Depois ele pergunta ao endpoint quais modelos ele serve, e se houver só um, ele escolhe por você.
A API key fica guardada no armazenamento de credenciais do seu sistema operacional — Keychain, Windows Credential Manager, ou Secret Service no Linux — não em um arquivo de configuração.
Mude a conexão depois com /config edit. Digite /help para ver todos os
comandos.
Atualizar e desinstalar
| uv | pipx | pip | |
|---|---|---|---|
| Atualizar | uv tool upgrade nrgrd | pipx upgrade nrgrd | pip install -U nrgrd |
| Desinstalar | uv tool uninstall nrgrd | pipx uninstall nrgrd | pip uninstall nrgrd |
Solução de problemas
Windows: "incompatible hardlinks" (os error 396)
Sintoma. uv tool install nrgrd falha com
The cloud operation cannot be performed on a file with incompatible hardlinks. (os error 396).
Causa. O uv instala criando hardlinks de arquivos a partir do cache dele. O OneDrive, comum em notebooks de trabalho, não permite hardlinks nas pastas que ele gerencia.
Correção. Diga ao uv para copiar os arquivos em vez de linká-los:
uv tool uninstall nrgrd
uv tool install nrgrd --link-mode=copy
Para tornar a cópia o padrão em toda instalação do uv, rode isso uma vez e abra um terminal novo:
[Environment]::SetEnvironmentVariable("UV_LINK_MODE", "copy", "User")
O comando nrgrd não é reconhecido
Causa. A pasta onde o uv ou o pipx colocam comandos ainda não está no seu PATH.
Correção. Rode uv tool update-shell (ou pipx ensurepath), depois
abra um terminal novo.
error: externally-managed-environment
Causa. No macOS e Linux recentes, o pip se recusa a instalar no Python do sistema, para proteger os pacotes próprios do sistema operacional.
Correção. Use uv ou pipx, ou pip dentro de um ambiente virtual como mostrado acima.
O pacote 'nrgrd' exige um Python diferente
Causa. pip ou pipx estão rodando em Python 3.10 ou mais antigo.
Correção. Instale com uv, que baixa um Python adequado sozinho, ou instale o Python 3.11 ou mais recente.
pipx: "pipx needs uv>=…"
Causa. Versões recentes do pipx usam o uv quando encontram ele na sua máquina, e seu uv é mais antigo do que ele exige.
Correção. Atualize o uv (uv self update se você o instalou com o
instalador independente), ou pule isso com
pipx install --backend pip nrgrd.