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