README.md

metadata

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).