Blame for README.md

---
license: other
license_name: gemma-terms-of-use
license_link: https://ai.google.dev/gemma/terms
base_model:
  - google/gemma-4-E2B-it
tags:
  - code
  - vision
  - multimodal
  - gemma4
  - software-engineering
  - react-native
  - android
  - typescript
  - python
  - unsloth
language:
  - pt
  - en
pipeline_tag: image-text-to-text
---

# 🚀 SpaceCode-E2B (Versão Oficial V12 — Merged 16-bit)

**SpaceCode-E2B** é um modelo compacto e multimodal de alta precisão especializado em **Engenharia de Software, Desenvolvimento Mobile/Web (React Native, TypeScript, Python 3.12, Android) e Tutoria Acadêmica**, construído sobre a arquitetura **Google Gemma 4 E2B (`google/gemma-4-E2B-it`)** pela **SpaceGhost**.

> **Versão Oficial Atual:** `V12` (Release Tag: `v12`)  
> **Formato de Distribuição:** Modelo completo fundido (*Merged 16-bit bfloat16 Safetensors*)  
> **Modelo-Base:** `google/gemma-4-E2B-it` (Gemma4ForConditionalGeneration)  
> **Adapter Homologado:** SpaceCode-E2B V12 Checkpoint 345 (`9e250264e93278b65c14d98e27c9631fe293734a04ed7e27140f417fb1396361`)  
> **Status de Homologação:** ✅ **APROVADO E HOMOLOGADO PELO SOFTWARE ARCHITECT**

---

## 📌 1. Visão Geral e Arquitetura

O SpaceCode-E2B V12 unifica as capacidades multimodais de visão e raciocínio técnico do Gemma 4 E2B com especialização rigorosa em código fortemente tipado, padrões arquiteturais modernos, tutoria socrática e mitigação sistemática de alucinações técnicas.

- **Arquitetura Base:** `Gemma4ForConditionalGeneration` (2.3B parâmetros de linguagem + Vision Tower SigLIP).
- **Precisão Numérica dos Pesos:** Bfloat16 (16-bit) completo, sem quantização destrutiva na exportação merged.
- **Tamanho Total em Disco:** 9,54 GiB (10.242.069.243 bytes distribuídos em 3 shards Safetensors).
- **Janela de Contexto Suportada:** 1.536 tokens nominais certificados no treinamento (expansível até 16.384 tokens pelo mecanismo de atenção nativo do Gemma 4).

---

## 🛠️ 2. Informações do Treinamento e Fine-Tuning

- **Corpus de Treinamento:** V12 Sequence Gate (1.379 amostras ativas selecionadas com mascaramento estrito de prompt de sistema e labels pedagógicos).
- **Estratégia de Adaptação:** QLoRA SFT de alta fidelidade via Unsloth.
  - Rank ($r$): 16
  - Alpha ($\alpha$): 16
  - Dropout: 0.05
  - Target Modules: Camadas de projeção de atenção e MLP do modelo de linguagem (`q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj`).
- **Duração do Treinamento:** Exatamente 1 época experimental (345 passos do otimizador AdamW, com gradiente acumulado em 4 micro-lotes e último passo normalizado estritamente por 3.0 amostras).
- **Curva de Taxa de Aprendizado:** Cosine schedule com 10 passos de warmup ($2 \times 10^{-4} \to 2 \times 10^{-5}$).
- **Progressão de Perda (Loss):** Redução de 1,0356 (Passo 1) para 0,3568 (Passo 345), correspondendo a -65,55% de otimização.

---

## 📊 3. Resultados da Avaliação Multimodal MMMU (TASK-0016)

Avaliação pareada e determinística (`temperature = 0.0`, `do_sample = False`) realizada sobre **100 questões oficiais do split de validação do benchmark MMMU (standard)**, distribuídas equitativamente entre 10 disciplinas acadêmicas (10 questões por disciplina):

| Disciplina Acadêmica | Grande Domínio | Gemma 4 E2B Original | SpaceCode-E2B V12 | Delta (p.p.) | Classificação |
| :--- | :--- | :---: | :---: | :---: | :--- |
| **Computer Science** | Tech & Engineering | 2/10 (20.0%) | **3/10 (30.0%)** | **+10.0%** | **SUPERIOR** |
| **Electronics** | Tech & Engineering | 0/10 (0.0%) | **3/10 (30.0%)** | **+30.0%** | **SUPERIOR** |
| **Mechanical Engineering** | Tech & Engineering | 0/10 (0.0%) | **1/10 (10.0%)** | **+10.0%** | **SUPERIOR** |
| **Math** | Science | 1/10 (10.0%) | **3/10 (30.0%)** | **+20.0%** | **SUPERIOR** |
| **Biology** | Science | 2/10 (20.0%) | **4/10 (40.0%)** | **+20.0%** | **SUPERIOR** |
| **Chemistry** | Science | 1/10 (10.0%) | **2/10 (20.0%)** | **+10.0%** | **SUPERIOR** |
| **Basic Medical Science** | Health & Medicine | 2/10 (20.0%) | **5/10 (50.0%)** | **+30.0%** | **SUPERIOR** |
| **Economics** | Business | 2/10 (20.0%) | **5/10 (50.0%)** | **+30.0%** | **SUPERIOR** |
| **Psychology** | Humanities & Social | 3/10 (30.0%) | 2/10 (20.0%) | -10.0% | Inferior |
| **Art Theory** | Art & Design | 7/10 (70.0%) | 5/10 (50.0%) | -20.0% | Inferior |
| **TOTAL GERAL (100 itens)** | **6 Áreas do Conhecimento** | **20/100 (20.0%)** | **33/100 (33.0%)** | **+13.0 p.p.** | **V12 SUPERIOR** |

> **Nota Metodológica Obrigatória:** A bateria acima constitui uma amostra experimental controlada de 100 questões do split de validação do MMMU padrão e **não equivale nem substitui a pontuação do benchmark completo ou do MMMU-Pro** (cujo valor oficial publicado pelo Google para o Gemma 4 E2B completo é de 44,2%).

### Análise Estatística e Qualitativa:
- **Teste de Contingência McNemar:** $\chi^2 = 5,7600$ ($p = 0,0164$, ganho estatisticamente significativo com $p < 0,05$).
- **Redução Drástica de Evasão:** O modelo original gerou **52 respostas não interpretáveis (UNPARSED)** por esgotamento de tokens em dissertações reflexivas, enquanto o SpaceCode V12 reduziu esse número para apenas **14 UNPARSED** (-73,08% de respostas inválidas), respondendo de forma concisa e estruturada.

---

## 🧪 4. Resultados da Avaliação Funcional Independente (TASK-0015)

O SpaceCode-E2B V12 demonstrou conformidade integral nos testes formais pós-treinamento:
1. **Engenharia de Software (Python 3.12 / Concorrência):** Geração idiomática com `asyncio.TaskGroup`, type hints completos e tratamento gracioso de cancelamento sob exceções.
2. **Conhecimento Conceitual (Teorema CAP):** Síntese precisa dos trade-offs de consistência, disponibilidade e particionamento em bancos de dados distribuídos.
3. **Tutoria Acadêmica (Escopo Léxico e Closure em JS):** Explicação didática clara estruturada em torno de um contador funcional sem jargões desnecessários.
4. **Extração e Formatação Estrita:** Extração precisa de logs em formato JSON puro (`status_code`, `endpoint`, `horario`) sem ruído antes ou depois.
5. **Anti-Alucinação Crítica (Sonda T04):** Recusa categórica e determinística a APIs inexistentes (rejeitando o hook fictício `useLifecycle()` no React Native e instruindo o usuário sobre métodos reais do ciclo de vida e `useEffect`).

---

## ⚠️ 5. Limitações Conhecidas

- **Execução em GPU de 8 GB de VRAM:** A viabilidade e a estabilidade de inferência em GPUs de consumo de 8 GB de VRAM **ainda não foi formalmente validada pela Arquitetura**. Embora a estimativa matemática aponte viabilidade sob quantização 4-bit, a homologação oficial para essa classe de hardware ocorrerá em etapa posterior.
- **Domínio Multimodal:** O modelo especializou predominantemente a geração de código, tutoria e interfaces móveis/web. Domínios visuais altamente abstratos (como Teoria da Arte pura) preservam as respostas herdadas da base ou podem apresentar variações estilísticas.

---

## 💻 6. Como Usar (Inferência com Hugging Face Transformers)

### Instalação das Dependências:
```bash
pip install -q transformers accelerate safetensors torch pillow torchvision
```

### Exemplo em Python (Texto e Visão Multimodal):
```python
import torch
from transformers import AutoProcessor, Gemma4ForConditionalGeneration
from PIL import Image

MODEL_ID = "SpaceGhost/SpaceCode-E2B"

# Carregar processador e modelo completo merged em bfloat16
processor = AutoProcessor.from_pretrained(MODEL_ID)
model = Gemma4ForConditionalGeneration.from_pretrained(
    MODEL_ID,
    torch_dtype=torch.bfloat16,
    device_map="auto"
)

# 1. Prompt de Código / Engenharia de Software:
prompt_code = [
    {
        "role": "user",
        "content": "Como implementar um hook customizado em React Native com TypeScript para gerenciar conexões WebSocket com reconexão automática e limpeza de memória?"
    }
]

inputs = processor(
    text=processor.apply_chat_template(prompt_code, tokenize=False, add_generation_prompt=True),
    return_tensors="pt"
).to("cuda")

with torch.no_grad():
    outputs = model.generate(**inputs, max_new_tokens=400, do_sample=False)

response = processor.tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(response)

# 2. Prompt Multimodal (com Imagem de Interface UI):
# img = Image.open("tela_aplicativo.png").convert("RGB")
# msgs = [
#     {
#         "role": "user",
#         "content": [
#             {"type": "image"},
#             {"type": "text", "text": "Analise esta tela móvel e forneça os componentes React Native correspondentes."}
#         ]
#     }
# ]
# inp_multi = processor(text=processor.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True), images=[img], return_tensors="pt").to("cuda")
# out_multi = model.generate(**inp_multi, max_new_tokens=300, do_sample=False)
# print(processor.tokenizer.decode(out_multi[0][inp_multi.input_ids.shape[1]:], skip_special_tokens=True))
```

### Execução Local com Ollama (GGUF):

O modelo conta com versões quantizadas oficiais GGUF disponibilizadas no diretório `gguf/`:
- `SpaceCode-E2B-V12-Q8_0.gguf` (4,61 GiB — Alta Precisão de Referência)
- `SpaceCode-E2B-V12-Q4_K_M.gguf` (3,18 GiB — Execução Otimizada para Recursos Limitados)

#### Como Criar e Rodar no Ollama:
```bash
# 1. Baixar o arquivo Modelfile e o binário GGUF Q4_K_M
huggingface-cli download SpaceGhost/SpaceCode-E2B Modelfile --local-dir .
huggingface-cli download SpaceGhost/SpaceCode-E2B gguf/SpaceCode-E2B-V12-Q4_K_M.gguf --local-dir .

# 2. Criar o modelo localmente no Ollama
ollama create spacecode-e2b -f Modelfile

# 3. Executar o modelo no terminal
ollama run spacecode-e2b
```

> **Nota sobre Multimodalidade no Ollama:** O suporte a imagens em GGUF no ecossistema Ollama/llama.cpp para a arquitetura Gemma 4 depende da integração completa do projetor visual `mtmd/gemma4v`. Para inferência multimodal integral com visão ativa (texto + imagem), utilize a biblioteca oficial `transformers` com os pesos Safetensors bfloat16 conforme demonstrado acima.

---

## 📜 7. Histórico de Versões e Governança

| Versão | Tag da Release | Formato | Status | Destaques |
| :---: | :---: | :---: | :---: | :--- |
| **V12** | `v12` | **Merged 16-bit Safetensors** | **Atual Oficial** | Merge integral da base Gemma 4 E2B com LoRA V12. +13 p.p. no MMMU, 1.536 tokens, anti-alucinação T04. |
| **V11** | `v11` | Adapter LoRA (`specialization-task-0011`) | Homologado Baseline | Baseline imutável preservada (SHA-256: `cb58fbb0...`). |
| **V2** | `v2` | Merged 16-bit / GGUF | Histórico | Release inicial baseada na ementa Android/React Native (88% acurácia). |

---

## ⚖️ 8. Licença e Atribuições

Este modelo baseia-se no **Google Gemma 4 E2B** e é disponibilizado em estrita conformidade com os termos da [Gemma Terms of Use](https://ai.google.dev/gemma/terms).

*Gemma is a trademark of Google LLC.*  
*Desenvolvido e mantido pela equipe de Engenharia de Machine Learning da **SpaceGhost**.*