Update README.md

README.md

@@ -1,128 +1,489 @@
+
+<div align="center">
+
+
+![image](https://cdn-uploads.huggingface.co/production/uploads/644afe169279988e0cbcd2d9/jCFCVTpFLOvaCUOF90b9o.png)
+
+<br>
+
+# LEVUM
+
+### Local · Código · Software
+
+**Um modelo local baseado em Qwen 3.5 9B, direcionado para desenvolvimento de software.**
+
+Escrever. Entender. Corrigir. Refatorar. Construir.
+
+**Menos cerimônia. Mais código rodando.**
+
+</div>
+
+---
+
+## Sobre
+
+**LEVUM** é um modelo de **9 bilhões de parâmetros**, baseado em **Qwen 3.5 9B** e direcionado para tarefas de desenvolvimento de software.
+
+O objetivo é simples: trabalhar perto do projeto e transformar instruções em código útil.
+
+O modelo foi pensado para tarefas como:
+
+* geração de código;
+* implementação de features;
+* debugging;
+* refatoração;
+* explicação e leitura de código;
+* criação de protótipos;
+* estruturação de projetos;
+* geração de aplicações completas;
+* assistência durante desenvolvimento local.
+
+LEVUM segue uma filosofia **local-first**: o modelo pode rodar próximo da IDE, dos arquivos e do contexto real do projeto, dependendo do runtime e da quantização escolhidos.
+
+> **Software primeiro. Local por padrão.**
+
+---
+
+## Especificações
+
+|                   |                                              |
+| ----------------- | -------------------------------------------- |
+| **Modelo**        | LEVUM                                        |
+| **Base**          | Qwen 3.5 9B                                  |
+| **Parâmetros**    | 9B                                           |
+| **Foco**          | Código / Software                            |
+| **Uso principal** | Desenvolvimento de software                  |
+| **Execução**      | Local                                        |
+| **Idioma**        | Português + capacidades multilíngues da base |
+| **Origem**        | 🇧🇷 Brasil                                  |
+
+---
+
+# Quantizações
+
+LEVUM é disponibilizado em diferentes níveis de quantização para permitir execução em uma variedade maior de hardware.
+
+A escolha ideal depende principalmente de:
+
+**RAM / VRAM → velocidade → fidelidade**
+
+### Q8 — Fidelidade
+
+Para máquinas com memória suficiente e usuários que querem preservar o máximo possível da qualidade do modelo.
+
+`Q8_0`
+
+---
+
+### Q4 / IQ4 — Equilíbrio
+
+O ponto recomendado para muitos sistemas locais.
+
+Boa relação entre tamanho, consumo de memória e qualidade.
+
+`Q4_K_M` · `Q4_K_S` · `IQ4_XS` · `IQ4_NL` · `Q4_1` · `Q4_0`
+
+---
+
+### Q3 / IQ3 — Compacto
+
+Para hardware mais limitado ou situações onde reduzir RAM/VRAM é prioridade.
+
+`Q3_K_L` · `Q3_K_M` · `Q3_K_S` · `IQ3_M` · `IQ3_S` · `IQ3_XS` · `IQ3_XXS`
+
+---
+
+### Q2 / IQ2 — Ultracompacto
+
+Compressão agressiva para ambientes onde versões maiores simplesmente não cabem.
+
+`Q2_K` · `Q2_K_S` · `IQ2_M` · `IQ2_S` · `IQ2_XS` · `IQ2_XXS` · `Q2_0` · `TQ2_0`
+
+---
+
+### IQ1 — Mínimo
+
+A opção extrema.
+
+`IQ1_M`
+
+Indicada apenas quando economia de memória é mais importante do que preservar a fidelidade máxima do modelo.
+
 ---
-base_model: ornith-ai/Ornith-1.5-9B
-datasets:
-- guell00/fds
-library_name: gguf
-pipeline_tag: text-generation
-license: mit
-tags:
-- gguf
-- llama.cpp
-- code
-- coding
-- imatrix
-- qwen3.5
-- ornith
-- lora
----
-
-# VELUM-Coder
-
-**VELUM-Coder** is a coding-focused fine-tune derived from
-[`ornith-ai/Ornith-1.5-9B`](https://huggingface.co/ornith-ai/Ornith-1.5-9B).
-
-This repository contains GGUF quantizations generated from the completed recovery adapter.
-
-- Source adapter: `ornith_fds_recovered_ckpt250`
-- Dataset: `guell00/fds`
-- llama.cpp commit: `f280b26983ad0fdb705a0d9ebf0503e76f2899b0`
-- Generated: 2026-08-25 02:06 UTC
-
-## Quantization policy
-
-- `Q8_0` is intentionally generated **without** an importance matrix.
-- Every Q4, Q3, Q2 and IQ1 build is invoked with the same domain-specific **imatrix**.
-- No Q5 or Q6 files are produced.
-- The extreme `IQ1_M` build keeps the token embedding and output tensors at `Q8_0` while the body is quantized as `IQ1_M`.
-- The imatrix is generated from code/conversation samples from `guell00/fds`.
-- `<think>...</think>` blocks are removed from assistant calibration text so calibration emphasizes direct answers and code.
-
-## Recommended files
-
-**Best default:** `VELUM-Coder-Q4_K_M.gguf`
-
-**Higher quality:** `VELUM-Coder-Q8_0.gguf`
-
-**Lower memory:** try `VELUM-Coder-IQ3_M.gguf` or `VELUM-Coder-IQ2_M.gguf`.
-
-**Extreme experiment:** `VELUM-Coder-IQ1_M.gguf`. This is not expected to preserve Q4-level quality. Embedding/output protection exists only to reduce catastrophic collapse.
-
-## Files
-
-| Status | File | Quant | Imatrix | Protection | Notes |
-|---|---|---|---|---|---|
-| ✅ | `VELUM-Coder-Q8_0.gguf` | `Q8_0` | No | Normal | Highest-quality quantized build; intentionally no imatrix. |
-| ✅ | `VELUM-Coder-Q4_K_M.gguf` | `Q4_K_M` | Yes | Normal | Recommended default Q4. |
-| ✅ | `VELUM-Coder-Q4_K_S.gguf` | `Q4_K_S` | Yes | Normal | Smaller Q4 K-quant. |
-| ✅ | `VELUM-Coder-IQ4_XS.gguf` | `IQ4_XS` | Yes | Normal | Compact 4-bit I-Quant. |
-| ✅ | `VELUM-Coder-IQ4_NL.gguf` | `IQ4_NL` | Yes | Normal | Non-linear 4-bit I-Quant. |
-| ✅ | `VELUM-Coder-Q4_1.gguf` | `Q4_1` | Yes | Normal | Legacy Q4 variant. |
-| ✅ | `VELUM-Coder-Q4_0.gguf` | `Q4_0` | Yes | Normal | Legacy compact Q4. |
-| ✅ | `VELUM-Coder-Q3_K_L.gguf` | `Q3_K_L` | Yes | Normal | Largest Q3 K-quant. |
-| ✅ | `VELUM-Coder-Q3_K_M.gguf` | `Q3_K_M` | Yes | Normal | Balanced Q3 K-quant. |
-| ✅ | `VELUM-Coder-Q3_K_S.gguf` | `Q3_K_S` | Yes | Normal | Smaller Q3 K-quant. |
-| ✅ | `VELUM-Coder-IQ3_M.gguf` | `IQ3_M` | Yes | Normal | Medium 3-bit I-Quant. |
-| ✅ | `VELUM-Coder-IQ3_S.gguf` | `IQ3_S` | Yes | Normal | Small 3-bit I-Quant. |
-| ✅ | `VELUM-Coder-IQ3_XS.gguf` | `IQ3_XS` | Yes | Normal | Extra-small 3-bit I-Quant. |
-| ✅ | `VELUM-Coder-IQ3_XXS.gguf` | `IQ3_XXS` | Yes | Normal | Extremely compact 3-bit I-Quant. |
-| ✅ | `VELUM-Coder-Q2_K.gguf` | `Q2_K` | Yes | Normal | Aggressive Q2 K-quant. |
-| ✅ | `VELUM-Coder-Q2_K_S.gguf` | `Q2_K_S` | Yes | Normal | Small Q2 K-quant. |
-| ✅ | `VELUM-Coder-IQ2_M.gguf` | `IQ2_M` | Yes | Normal | Higher-quality 2-bit I-Quant. |
-| ✅ | `VELUM-Coder-IQ2_S.gguf` | `IQ2_S` | Yes | Normal | 2-bit I-Quant. |
-| ✅ | `VELUM-Coder-IQ2_XS.gguf` | `IQ2_XS` | Yes | Normal | Extra-small 2-bit I-Quant. |
-| ✅ | `VELUM-Coder-IQ2_XXS.gguf` | `IQ2_XXS` | Yes | Normal | Extremely compact 2-bit I-Quant. |
-| ✅ | `VELUM-Coder-Q2_0.gguf` | `Q2_0` | Yes | Normal | 2.25 bpw Q2_0. |
-| ✅ | `VELUM-Coder-TQ2_0.gguf` | `TQ2_0` | Yes | Normal | Experimental ternary ~2-bit build. |
-| ✅ | `VELUM-Coder-IQ1_M.gguf` | `IQ1_M` | Yes | Q8_0 embed/output | Extreme build. IQ1_M body + Q8_0 embedding/output protection. |
-
-## Importance matrix
-
-The generated importance matrix is uploaded as:
-
-`imatrix/VELUM-Coder-imatrix.gguf`
-
-The calibration text itself is not uploaded; it is only an intermediate generated from `guell00/fds`.
+
+> **Regra prática:** comece com `Q4_K_M`.
+> Se houver memória sobrando, experimente `Q8_0`.
+> Se faltar memória, desça para Q3, Q2 ou IQ1.
+
+---
+
+# Executando localmente
 
 ## llama.cpp
 
-Example:
+Baixe uma das versões GGUF do LEVUM e execute com um runtime compatível com GGUF.
+
+```bash
+llama-cli \
+  -m ./LEVUM-Q4_K_M.gguf \
+  -p "Crie uma API REST em Python usando FastAPI."
+```
+
+Para iniciar um servidor local:
+
+```bash
+llama-server \
+  -m ./LEVUM-Q4_K_M.gguf \
+  -c 8192
+```
+
+Depois disso, o modelo pode ser integrado a ferramentas locais que suportem endpoints compatíveis.
+
+---
+
+## Ollama
+
+Crie um `Modelfile` apontando para o GGUF:
+
+```dockerfile
+FROM ./LEVUM-Q4_K_M.gguf
 
-~~~bash
-llama-cli -hf guell00/VELUM-Coder:Q4_K_M -c 16384
-~~~
+PARAMETER temperature 0.6
+PARAMETER top_p 0.9
+```
 
-Server:
+Depois:
 
-~~~bash
-llama-server -hf guell00/VELUM-Coder:Q4_K_M -c 16384
-~~~
+```bash
+ollama create levum -f Modelfile
+ollama run levum
+```
 
-Manual download:
+Exemplo:
+
+```text
+>>> Crie uma API em FastAPI para gerenciar projetos e tarefas.
+```
+
+---
+
+## LM Studio
+
+1. Baixe uma quantização GGUF do LEVUM.
+2. Importe o arquivo no LM Studio.
+3. Carregue o modelo.
+4. Ajuste o contexto de acordo com a memória disponível.
+5. Inicie uma conversa ou o servidor local.
+
+Nenhuma infraestrutura remota é necessária para a inferência quando o modelo está sendo executado localmente.
+
+---
+
+# Prompts
+
+LEVUM funciona melhor quando a tarefa, o contexto e o formato esperado são explícitos.
+
+## Gerar um projeto
+
+```text
+Crie um dashboard financeiro interativo em um único arquivo HTML.
+
+Requisitos:
+- HTML, CSS e JavaScript no mesmo arquivo
+- gráficos interativos
+- responsivo
+- dados de exemplo
+- sem dependências externas obrigatórias
+
+Retorne somente o HTML completo.
+```
+
+---
+
+## Implementar uma feature
+
+```text
+Analise o código abaixo e implemente autenticação JWT.
+
+Requisitos:
+- preserve a arquitetura atual
+- valide tokens expirados
+- adicione middleware de autenticação
+- não altere endpoints públicos
+- explique apenas decisões importantes
+
+Código:
+[cole o código aqui]
+```
+
+---
+
+## Debug
+
+```text
+Encontre a causa do bug no código abaixo.
+
+Comportamento esperado:
+[descreva]
+
+Comportamento atual:
+[descreva]
+
+Erro:
+[cole o erro]
+
+Código:
+[cole o código]
+
+Identifique a causa e retorne a correção completa.
+```
+
+---
+
+## Refatoração
+
+```text
+Refatore este código.
+
+Objetivos:
+- reduzir duplicação
+- melhorar legibilidade
+- manter comportamento atual
+- preservar a API pública
+- evitar abstrações desnecessárias
+
+Retorne primeiro o código refatorado e depois um resumo curto das mudanças.
+```
+
+---
+
+# Formato de prompt
+
+Para tarefas maiores, uma estrutura simples costuma produzir resultados mais previsíveis:
+
+```text
+OBJETIVO
+O que precisa ser construído.
+
+CONTEXTO
+Stack, arquivos existentes e arquitetura.
+
+REQUISITOS
+Comportamentos obrigatórios.
+
+RESTRIÇÕES
+O que não deve ser alterado.
+
+SAÍDA
+Formato exato esperado.
+```
+
+Por exemplo:
+
+```text
+OBJETIVO
+Criar uma página de analytics.
+
+CONTEXTO
+Projeto React + TypeScript + Tailwind.
+
+REQUISITOS
+- gráfico de receita
+- filtros por período
+- cards de métricas
+- tabela de transações
+
+RESTRIÇÕES
+- não adicionar novas dependências
+- reutilizar componentes existentes
+
+SAÍDA
+Retorne os arquivos completos que precisam ser criados ou alterados.
+```
+
+---
+
+# Code-first
+
+LEVUM foi pensado para trabalhar dentro do ciclo normal de desenvolvimento:
+
+```text
+PROMPT / CÓDIGO
+      ↓
+    LEVUM
+      ↓
+   ENTENDER
+      ↓
+    GERAR
+      ↓
+    DEBUG
+      ↓
+  REFATORAR
+      ↓
+SOFTWARE RODANDO
+```
+
+### Geração
+
+Projetos, componentes, APIs, scripts e features.
+
+### Debug
+
+Análise de erros, comportamento inesperado e correções.
+
+### Refatoração
+
+Estrutura, legibilidade e manutenção de código existente.
+
+### Prototipagem
+
+Transformar uma ideia em algo executável rapidamente.
+
+---
+
+# Exemplo
+
+**Prompt**
+
+```text
+Crie um jogo estilo Flappy Bird em um único HTML.
+
+Use apenas HTML, CSS e JavaScript.
+
+Inclua:
+- física
+- obstáculos
+- colisão
+- pontuação
+- reinício
+- controles por teclado e clique
+
+Retorne somente o HTML completo.
+```
+
+**Resultado esperado**
+
+```text
+prompt
+  ↓
+LEVUM
+  ↓
+HTML + CSS + JavaScript
+  ↓
+browser
+  ↓
+software rodando
+```
+
+---
+
+# Hardware
+
+O consumo real depende de vários fatores, incluindo:
+
+* quantização;
+* tamanho do contexto;
+* runtime;
+* KV cache;
+* CPU;
+* GPU;
+* quantidade de camadas descarregadas para GPU;
+* configuração de inferência.
+
+Por isso, os números de memória podem variar significativamente entre sistemas.
+
+Como regra geral:
+
+```text
+mais bits
+   ↑
+mais fidelidade
+   ↑
+mais memória
+
+menos bits
+   ↓
+menos memória
+   ↓
+maior compressão
+```
+
+Escolha a quantização com base no hardware disponível e na qualidade necessária para a tarefa.
+
+---
+
+# Limitações
+
+LEVUM continua sendo um modelo de linguagem.
+
+Isso significa que ele pode:
+
+* gerar código incorreto;
+* inventar APIs ou bibliotecas;
+* produzir soluções inseguras;
+* interpretar requisitos de forma errada;
+* introduzir regressões;
+* sugerir dependências inexistentes;
+* gerar código que parece correto sem realmente funcionar.
+
+Para software importante, revise, teste e valide o código antes de colocá-lo em produção.
+
+Código gerado por IA não ganha poderes mágicos só porque compilou uma vez.
+
+---
+
+# Uso responsável
+
+Antes de executar código gerado pelo modelo:
+
+1. revise as alterações;
+2. verifique dependências;
+3. execute testes;
+4. valide entradas externas;
+5. revise operações de filesystem, rede e banco de dados;
+6. não exponha segredos ou credenciais desnecessariamente;
+7. use ambientes isolados quando estiver testando código desconhecido.
+
+Para aplicações críticas, o modelo deve funcionar como ferramenta de assistência, não como única camada de revisão.
+
+---
+
+# Modelo base
+
+LEVUM é baseado em:
+
+**Qwen 3.5 9B**
+
+O modelo base fornece a capacidade geral sobre a qual o LEVUM é construído.
+
+Consulte também o model card e a licença do modelo base antes de distribuir ou utilizar derivados.
+
+---
+
+# Licença
+
+O uso do LEVUM está sujeito à licença publicada neste repositório e, quando aplicável, aos termos e condições associados ao modelo base.
+
+Consulte o arquivo `LICENSE` antes de uso comercial, redistribuição ou criação de derivados.
+
+---
 
-~~~bash
-hf download guell00/VELUM-Coder VELUM-Coder-Q4_K_M.gguf --local-dir .
-~~~
+# Brasil
 
-Then:
+<div align="center">
 
-~~~bash
-llama-cli -m VELUM-Coder-Q4_K_M.gguf -c 16384
-~~~
+### 🇧🇷 FEITO NO BRASIL
 
-## Adapter
+**Inteligência que fica por perto.**
 
-The final recovery LoRA adapter is also uploaded under `adapter/` when adapter upload is enabled.
+Local-first · Code-first · Software-first
 
-## Notes
+<br>
 
-Low-bit quantization is destructive. Q2 and especially IQ1_M are experimental options for constrained hardware, not substitutes for Q4/Q8 quality.
+`BUILD` · `DEBUG` · `REFACTOR` · `SHIP`
 
-GGUFs are produced directly by `llama-quantize` and uploaded after successful quantization. No conversational inference is run by this pipeline.
+<br>
 
-## Credits
+**LEVUM © 2026**
 
-- Ornith authors
-- llama.cpp / ggml contributors
-- Hugging Face
-- Unsloth
-- `guell00/fds`
+</div>