README.md

---

title: Minecraft Friends AI ZeroGPU
emoji: 🧠
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.27.0
python_version: '3.12'
app_file: app.py
pinned: false
---


# Programa — Naldo autônomo + endpoint CPU

O controlador padrão do `Naldo_Bot` é o **AltoClef 0.19** (comando `@gamer`,
speedrun survival real: equipamento, stronghold, dragão) com supervisão de
alto nível via **OpenCode Muse** (`muse-spark-1.3-contributor-free`). Mundo
**Survival / Normal**, mapa atual inalterado; o inventário existente do Naldo
é mantido (run assistida, sem itens dados nem teleporte). Status ao vivo em
`GET /opencode-bot/status` e log em `GET /opencode-bot/log`. O Voyager antigo
continua disponível apenas como alternativa manual (`VOYAGER_AUTOSTART=0` por
padrão); as seções Voyager abaixo são o legado manual.

## Endpoint local de compatibilidade (Granite)

O endpoint OpenAI-compatible público continua disponível para clientes antigos e
para os componentes locais auxiliares. Ele não é mais o cérebro generativo do
`Naldo_Bot`; o Naldo usa OpenCode conforme a seção seguinte.

- GGUF oficial: `ibm-granite/granite-4.0-h-tiny-GGUF`
- Arquivo: `granite-4.0-h-tiny-Q4_K_M.gguf`
- Revisão fixada: `08d5a8a9741dd5c1a95d2d39e25253226aa1464e`
- Quantização: `Q4_K_M`
- Arquitetura: Granite 4.0 H-Tiny MoE/Mamba2, 7B totais e ~1B parâmetros ativos
- Contexto operacional do Voyager: 8.192 tokens
- Saída padrão: 384 tokens
- Saída máxima: 512 tokens
- Alias principal: `granite-4.0-h-tiny`
- CPU: 16 threads de decode e 16 threads de prefill/batch

Os aliases antigos permanecem aceitos apenas para compatibilidade de clientes e
continuam roteando para o Granite local. O Voyager do Naldo não usa esses aliases
para geração.

## Cérebro do Naldo_Bot: OpenCode Muse + AltoClef (legado manual Voyager abaixo)



O Naldo ativo é o AltoClef 0.19 (`@gamer`) supervisionado pelo OpenCode Muse;

o restante desta seção descreve o legado manual do Voyager (alternativa

manual, `VOYAGER_AUTOSTART=0` por padrão).

Action, Curriculum, Critic e Skill Manager do `Naldo_Bot` usam uma ponte
OpenAI-compatible local em `127.0.0.1:7864`, que traduz as chamadas do Voyager
para um servidor `opencode serve` preso ao loopback em `127.0.0.1:7865`.

- OpenCode pinado: `opencode-ai@1.18.33`, instalado localmente no runtime sem `npm -g`.
- Provider: `opencode`.
- Modelo principal: `muse-spark-1.3-contributor-free`.
- Fallbacks: `fledge-alpha-free` e `nemotron-3-ultra-free`, somente do provider OpenCode gratuito.
- Nenhuma credencial do usuário é copiada; o processo recebe HOME/XDG próprios no runtime.
- As mensagens de inferência enviam `tools: {}`. No OpenCode 1.18.33 isso foi validado
  sem execução de bash/arquivos; permissões customizadas de sessão não são usadas porque
  o Zen gratuito as rejeita com `FreeTierError`.
- O bridge não inventa suporte a `temperature`/`max_tokens`: registra os valores pedidos
  e preserva a resposta integral, evitando cortar JavaScript do Action Agent.
- Embeddings continuam locais em `127.0.0.1:7860/v1/embeddings`.
- Se OpenCode ou bridge morrerem, o supervisor interrompe o Naldo e recupera o cérebro
  antes de religar o bot; não existe fallback generativo para Granite ou Gemini.

O Curriculum em Creative continua usando o estado real e os checkpoints persistentes.
A conclusão da tarefa continua exigindo verificação independente do mundo.

Referência do modelo:
https://huggingface.co/ibm-granite/granite-4.0-h-tiny-GGUF

## Embeddings

O Voyager original usa embeddings no SkillManager e no cache de QA do CurriculumAgent.

- Modelo oficial: `Qwen/Qwen3-Embedding-0.6B-GGUF`
- Arquivo: `Qwen3-Embedding-0.6B-Q8_0.gguf`
- Revisão fixada: `370f27d7550e0def9b39c1f16d3fbaa13aa67728`
- Pooling: LAST, conforme documentação do Qwen3 Embedding para llama.cpp
- Vetores normalizados
- Alias OpenAI-compatible: `text-embedding-ada-002`

Referência:
https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF

## Inferência local somente em CPU

A inferência Granite e os embeddings locais não usam GPU:

- `CUDA_VISIBLE_DEVICES=""`
- `HIP_VISIBLE_DEVICES=""`
- `ROCR_VISIBLE_DEVICES=""`
- `GGML_VK_VISIBLE_DEVICES=""`
- `n_gpu_layers=0`
- `offload_kqv=False`
- `op_offload=False`
- wheel CPU do `llama-cpp-python==0.3.35`
- threads detectadas por affinity/cgroup
- mmap ativado
- chamadas de geração serializadas para evitar disputa de CPU

O decorador `@spaces.GPU` existente é somente a sentinela exigida pelo host ZeroGPU;
a função não é chamada pela API.

## Compatibilidade Voyager (legado manual)

Por padrão o Voyager não inicia sozinho. `PLAYER_MODE=0`. O servidor não injeta o antigo prompt Bedrock.
Os dois Voyagers jogam em Creative: mineração, colocação, equipamento e inventário
são verificados a partir da observação real. O `placeBlocks` recebe o ID exato
da tarefa canônica; o agente não pode substituir `bricks` por `brick`.

O endpoint aceita temperatura 0.0, que coincide com os defaults do Voyager para
ActionAgent, CurriculumAgent, CriticAgent e SkillManager.

O endpoint mantém a compatibilidade HTTP de chat e embeddings para os clientes.

## API

- `GET /`
- `GET /health`
- `GET /status`
- `GET /v1/models`
- `POST /v1/chat/completions`
- `POST /v1/embeddings`
- `GET /minecraft/status`
- `GET /opencode-bot/status` (Naldo ativo — AltoClef)
- `GET /opencode-bot/log`
- `GET /voyager/status` (alternativa manual)
- `GET /gemini-bot/status`

## Segundo jogador: Gemini_Bot



`Gemini_Bot` executa uma segunda instância completa do Voyager no mesmo servidor
Java 1.19, com processo Mineflayer e checkpoint próprios. Curriculum, Action,
Critic e Skill Manager consultam o Gemini CLI por um proxy local exclusivo;
somente os embeddings usam o modelo local. O `Naldo_Bot` ativo é o AltoClef,
supervisionado pelo OpenCode Muse; o bridge OpenCode descrito acima serve
apenas à supervisão. Ambos validam tarefas Creative pela
mudança real no mundo ou pelo inventário.

O Curriculum permanece no modo automático do Voyager: cada IA observa o estado
atual, consulta seu checkpoint e decide o próximo objetivo. Não existe sequência
fixa nem fallback circular. Objetivos e projetos já concluídos ou falhados são
rejeitados semanticamente; a IA recebe o motivo e precisa escolher algo novo.
Se o provedor não produzir uma decisão válida, o bot permanece conectado e
aguarda com backoff, sem construir estruturas por roteiro.

Projetos suportados continuam verificáveis (`wall`, `bridge`, `room`, `tower`,
`road`, `arch`, `monument`, `shelter`, `courtyard` e `gate`). Quando a IA escolhe
um deles, a geometria é executada por `buildProject`, que usa `placeItem` e
registra todas as coordenadas físicas para o Critic. Um projeto concluído não
pode ser escolhido novamente. Naldo_Bot e Gemini_Bot tomam decisões separadas e
mantêm checkpoints independentes.

O adaptador `/pause` não envia o comando global do mod: os dois bots e os
jogadores Xbox compartilham um mundo que continua rodando durante a inferência.
`placeBlocks` prioriza destinos com linha de visão e usa a face encontrada por
`GoalPlaceBlock`, mantendo a confirmação do bloco no mundo. A física está fixada
em `prismarine-physics@1.6.0`, que inclui a correção oficial de água no Minecraft
1.19; os quatro pins do protocolo permanecem inalterados.
Os logs `[llm_metric]` registram bot, papel, latência e tokens reais por chamada
de Curriculum, Action, Critic e Skill Manager. No Gemini CLI, a temperatura zero
é aplicada por `modelConfigs.customOverrides`, além do cliente Voyager.

Se as construções cercarem o bot, o helper procura uma área de superfície já
carregada e livre, a 8–12 blocos por eixo. O voo Creative de recuperação verifica
o volume do jogador em toda a rota, usa segmentos de até 0,4 bloco, sobe no máximo
4 blocos para ultrapassar a construção e pousa em solo confirmado. Não destrói
blocos, não teleporta e não altera a exploração horizontal do Curriculum.

- CLI fixado em `@google/gemini-cli@0.61.0`, modelo efetivo `gemini-3.5-flash-lite`.
- Segredos privados do Space: `GEMINI_BOT_KEY_1` a `GEMINI_BOT_KEY_6`.
- Nenhuma chave deve ser salva no Git, no checkpoint ou nas saídas de status.
- Status: `/gemini-bot/status` (conexão, tarefas, métricas e falhas por posição
  da chave; nunca revela valores de chaves).
- Controle de inicialização: `GEMINI_BOT_AUTOSTART=0` desativa somente o
  segundo bot. O Naldo_Bot e o mundo persistente seguem independentes.



API pública de compatibilidade:



`https://erinaldordso-minecraft-friends-ai-zerogpu.hf.space/v1`



Modelo de chat público (não é o cérebro do Naldo):



`granite-4.0-h-tiny`



Cérebro interno do Naldo:



`opencode/muse-spark-1.3-contributor-free` via `127.0.0.1:7864/v1`



Modelo de embeddings:



`text-embedding-ada-002`



## Upstream Voyager



Os dois processos instanciam as classes de currículo, Action, Critic, Skill

Manager e o loop `Voyager.learn()` do mesmo checkout MineDojo/Voyager fixado em

`55e45a880755d0c8c66ca7fb5fe7962ac8974f89`. Cada runner verifica o HEAD

do checkout e a origem das cinco classes antes de aprender; os endpoints de

status expõem `engine_runtime` apenas para o PID validado. Os adaptadores
Creative e os parsers necessários aos modelos não são código byte a byte igual
ao upstream. Checkpoints e mundo ficam em `/persist` e não são substituídos
pela atualização do código.

Projeto original:
https://github.com/MineDojo/Voyager

Este Space executa o Voyager fixado em `55e45a880755d0c8c66ca7fb5fe7962ac8974f89`
com correções de reconexão, observações nulas e exploração horizontal limitada.
O `mineBlock` só aceita blocos até dois níveis abaixo dos pés, para o bot cavar
um poço de onde consegue sair, e o pathfinder mantém a escavação do upstream
justamente por isso.

## Instalação conforme a página oficial

O `README.md`, `installation/minecraft_instance_install.md` e
`installation/fabric_mods_install.md` do upstream são o contrato de instalação.
`tests/test_installation_conformance.py` trava o que é possível automatizar.

| Passo oficial | Onde está neste Space |
| --- | --- |
| Python >= 3.9 | `voyager_stack.MIN_PYTHON`, verificado no boot |
| Node.js >= 16.13.0 | `voyager_stack.MIN_NODE`, verificado no boot |
| `git clone` | `VoyagerStack._ensure_source`, no commit fixado |
| `pip install -e .` | `VoyagerStack._ensure_python_package`, com verificação posterior |
| `npm install` + `npx tsc` em `mineflayer-collectblock`, depois `npm install` em `voyager/env/mineflayer` | `VoyagerStack._ensure_node` |
| Dependências de `requirements.txt` | `requirements.txt` deste repositório |
| `Voyager(ckpt_dir=..., resume=True)` para retomar | `voyager_runner.py` deriva `resume` dos arquivos do checkpoint e o passa ao construtor |
| Mundo em Creative + Peaceful | `server.properties` |
| `fabric-loader-0.14.18-1.19` | instalador Fabric pinado em `minecraft_stack.py` |

Desvios, todos deliberados:

- **`mc_port` em vez de `azure_login`.** O README aceita os dois ("You can also
  use mc_port instead of azure_login"). Este Space sobe um servidor Bedrock
  dedicado em `127.0.0.1:25565` com Geyser/ViaProxy para os amigos Xbox, então
  não existe `MinecraftInstance` local para o `azure_login` abrir. A
  reconexão automática do upstream é substituída pela supervisor do Space e
  pelos patches de recuperação não destrutivos.
- **Subconjunto de mods do Fabric.** A lista de 5 mods da página é para um
  *cliente* (o próprio README diz para abrir o mundo em LAN). Um servidor
  dedicado recebe o subconjunto de servidor: Fabric API 0.58.0+1.19,
  Complete Config 2.0.0 e Multiplayer Server Pause 1.1.0. **Mod Menu** é
  exclusivamente de cliente e **Better Respawn** crasha o servidor ao salvar um
  jogador Creative recém-conectado (mixin dereferenciando `respawnDimension`
  não inicializado), então o jar é removido em `_ensure_voyager_mods`.
- **`pip install -e . --no-deps`.** A distribuição é instalada e verificada, mas
  a resolução de dependências fica por conta de `requirements.txt` deste Space:
  deixar o pip re-resolver em boot moveria a pilha de inferência de um Space já
  em execução.
- **Versões pinadas.** `chromadb==0.4.22` (o upstream fixa 0.3.29, anterior ao
  `langchain==0.0.350`) e `langchain-community==0.0.2` (exigido pelo
  `ChatOpenAI` usado pelo upstream). `cchardet` fica de fora de propósito: é um
  acelerador opcional do `chromadb` e compilá-lo no build do Space quebraria a
  build inteira.
- **Modelo local.** `granite-4.0-h-tiny` no lugar do GPT-4, servido por
  `app.py` como endpoint OpenAI-compatible em `127.0.0.1:7860`.
- **`learn(reset_env=False)`.** O reset do upstream é um hard reset do ambiente

  do Mineflayer; sem `azure_login` ele derrubaria a conexão a cada tarefa. O

  `Voyager.learn()` do upstream continua sendo o loop, só sem o reset.



## Mapa



O mundo é um superflat de farm, com superfície em Y=64 (fixa em

`minecraft_stack.WORLD_SURFACE_Y` e validada por `tests/test_world_map.py`): grama

no topo, três camadas de terra, cascalho e uma faixa de minério de carvão até

esmeralda entre 6 e 24 blocos abaixo da superfície, repetida na banda de

deepslate no fundo da coluna. Sem lagos, sem features e sem estruturas, para a

superfície continuar previsível para o pathfinder e para quem constrói.



O mapa vive em `/persist/minecraft-friends/world-20260928-ores-y64-v1`. Como

`generator-settings` só é lido quando o mundo é criado, trocar o mapa exige um

diretório novo; os saves dos jogadores humanos são carregados para o mundo novo

(`_carry_player_saves`) e o save do bot não é, para o Curriculum oficial sair do

seu ramo de inventário cheio. O token OAuth da Xbox fica em

`/persist/minecraft-friends/relay` e não é tocado pela troca de mapa.



Os checkpoints continuam em

`/persist/minecraft-friends/voyager/ckpt-20260927-flat-y64-v1` e

`/persist/minecraft-friends/gemini-voyager/ckpt-20260927-flat-y64-v1`, porque a

superfície continua plana em Y=64 e as skills aprendidas foram preservadas.



Validação offline, sem iniciar modelos ou servidor de jogo:

`python -m pytest tests -q --ignore=tests/test_player_save_diagnostics.py`



O contrato do runtime (decisões upstream, adaptação declarada do retry do

curriculum e patch aplicado sobre a árvore oficial) é verificado por

`tests/test_voyager_official_contract.py` e `tests/test_voyager_patch_application.py`.



## Mapa normal 20261003 (Naldo)



- Mundo novo de terreno normal: `/persist/minecraft-friends/world-20261003-normal-v1`

  (`minecraft:normal` com estruturas; sem camadas flat). Todos entram no spawn

  natural do mapa novo: nenhuma playerdata antiga e importada na troca

  flat->normal (posicao antiga enterraria o jogador na montanha, longe do Naldo).

- Checkpoint novo e vazio: `/persist/minecraft-friends/voyager/ckpt-20261003-normal-v1`

  (resume=False; sem herdar skills, tasks ou posicoes do mapa antigo).

- Antigos mantidos, nunca apagados: `world-20260928-ores-y64-v1`,

  `world-20260927-flat-y64-v1`, checkpoints `ckpt-20260927-flat-y64-v1` e o

  `relay/token.json` da Xbox (sem novo login).