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