iMiranda/kuro-phi3.5-gguf

Kuro — Phi-3.5-mini GGUF (Q4_K_M)

Kuro é um assistente de engenharia local que roda em terminal puro (TTY), otimizado para hardware de consumo sem GPU dedicada. É o modelo microsoft/Phi-3.5-mini-instruct (3.8 B parâmetros, licença MIT) quantizado para GGUF Q4_K_M (~2.3 GiB), com uma persona customizada aplicada via system prompt — sem fine-tuning de pesos.

O objetivo é rodar offline, em CPU, com resposta usável para chat interativo (~7–11 tokens/s em i7-1355U).

Créditos

Este repo é um repack do modelo microsoft/Phi-3.5-mini-instruct (Apache/MIT). Nenhum peso foi treinado do zero — apenas quantizado para GGUF e empacotado com um system prompt. O mérito do modelo base é inteiramente da Microsoft.

• Modelo base: https://huggingface.co/microsoft/Phi-3.5-mini-instruct
• Licença base: MIT (Microsoft Corporation)
• Quantização: llama.cpp (llama-quantize) — MIT

Como funciona a persona "Kuro"

A persona não está nos pesos — está num system prompt aplicado em runtime. Isso significa que o .gguf aqui é o Phi-3.5-mini padrão; o estilo "Kuro" vem de injetar o prompt abaixo via flag --system-prompt (ou --sys) do llama-cli.

Conteúdo do system prompt (coloque em data/system_prompt.md se quiser versionar à parte):

Você é **Kuro**, engenheiro sênior de software e machine learning, assistente pessoal local rodando em terminal puro (TTY) na máquina do operador.

Princípios de comunicação:
- **Direto e técnico.** Sem saudações, sem preâmbulos, sem "Claro, posso ajudar" — vá ao ponto na primeira frase.
- **Concisão máxima.** Se a resposta cabe em uma linha, escreva uma linha. Não repita a pergunta.
- **Honestidade brutal sobre limites.** Se não sabe, diga "não sei". Se algo é instável ou arriscado, avise antes de fazer.
- **Foco em código funcional.** Entregue código que roda, não pseudocódigo. Sempre prefira o caminho que funciona no hardware real, não o teórico.
- **Sem enrolação.** Sem ", não hesite em perguntar", sem "espero que isso ajude", sem recapitulação final.
- **Português por padrão.** Mantenha termos técnicos em inglês quando for convenção (ex: thread, batch, token, prompt).
- **Identidade curta.** Se perguntarem quem é você: "Kuro. Assistente local. Rodando em TTY."

Quando o operador pede uma ação, você executa e relata o resultado mínimo. Quando pede análise, você entrega apenas a conclusão técnica e o caminho de execução.

Especificações técnicas

Campo	Valor
Modelo base	microsoft/Phi-3.5-mini-instruct
Parâmetros	3.8 B
Arquitetura	Phi-3.5 (decoder-only transformer)
Quantização	Q4_K_M (4-bit primary + 6-bit K/V)
BPW médio	~5.02
Arquivo	kuro-Q4_K_M.gguf (~2.3 GiB)
Context length	até 131072 (recomendado: 4096)
Runtime testado	llama.cpp (llama-cli) CPU-only
Chat template	Jinja2 embedded no GGUF (Phi-3.5)

Como usar

Via llama.cpp (CLI direto)

# One-shot
llama-cli \
    -m kuro-Q4_K_M.gguf \
    --threads 8 \
    -c 4096 \
    --temp 0.3 --top-p 0.9 --repeat-penalty 1.05 \
    --system-prompt "$(cat data/system_prompt.md)" \
    --single-turn \
    -p "Escreva uma função Python que retorne únicos de uma lista." \
    -n 256 --no-display-prompt

# Modo interativo (chat multi-turno)
llama-cli \
    -m kuro-Q4_K_M.gguf \
    --threads 8 -c 4096 \
    --temp 0.3 --top-p 0.9 --repeat-penalty 1.05 \
    --system-prompt "$(cat data/system_prompt.md)" \
    -cnv --color on -mli

Via Ollama (recomendado — config pronta)

Baixe os 3 arquivos diretamente (sem git clone — o repo é GGUF/LFS e clone via git exige git-lfs/xet, que não são necessários):

mkdir kuro && cd kuro
curl -fLO https://huggingface.co/iMiranda/kuro-phi3.5-gguf/resolve/main/kuro-Q4_K_M.gguf
curl -fLO https://huggingface.co/iMiranda/kuro-phi3.5-gguf/resolve/main/Modelfile.kuro
curl -fLO https://huggingface.co/iMiranda/kuro-phi3.5-gguf/resolve/main/system_prompt.md

# Cria o modelo com persona + contexto + params já configurados
ollama create kuro -f Modelfile.kuro

# Testa
ollama run kuro "Quem é você?"

O .gguf tem ~2.4 GiB. Alternativa sem terminal: baixe cada arquivo pelo botão "Download file" na página do repo.

Limitação conhecida: o kuro (Phi-3.5-mini) não tem suporte a tools (function calling) — só chat. Ele não funciona como agente no Claude Code/OpenCode (does not support tools). Para uso como agente, use o kuro-small, que tem tools (Qwen2.5).

Via LM Studio / Jan

O arquivo GGUF aqui é padrão Q4_K_M com chat template Phi-3.5 embutido, então é compatível com qualquer ferramenta que consuma GGUF:

• LM Studio: arraste kuro-Q4_K_M.gguf para ~/.lmstudio/models/ e selecione no app.
• Jan: coloque o .gguf em ~/jan/models/ e selecione nos settings.

Importante: para que a persona Kuro apareça em LM Studio/Ollama/Jan, configure o system prompt manualmente nessa ferramenta (system_prompt.md no repositório) — o file GGUF não carrega o prompt automaticamente, só o chat template.

Performance conhecida

Medido em runtime real no hardware abaixo (não estimado). Os números variam conforme a máquina de quem roda.

Ambiente	Valor
CPU	Intel i7-1355U (10 cores físicos, 12 threads)
RAM total	16 GiB
GPU	Nenhuma usada (Intel Iris Xe integrada ignorada)
RAM usada (RSS)	4.7 GiB durante inferência
Swap	0.5 GiB (zram, estável — sem swap thrashing)
Prompt processing	38.8–50.9 tok/s
Generation	6.1–10.7 tok/s
Throughput médio	~9.5 tok/s (8 threads)
Tempo de carregamento	~2 s (mmap)
Context length testado	4096 tokens

Testado com 5 prompts variados (saudação, código Python, pedido de apagar /etc/passwd — recusou corretamente, identidade, leitura JSON). Sistema permaneceu responsivo (KDE + navegador + editores) durante toda a inferência. Exit code 0 em todos os testes.

Limitações conhecidas

• Tonalidade: sem fine-tuning na persona, o Phi-3.5 mantém a cordialidade padrão da família Phi ("Oi!", "Desculpe, mas não posso ajudar"). O system prompt corta muita enrolação mas não instala o tom minimalista total da persona Kuro ideal. Para evoluir, seria necessário fine-tune QLoRA em hardware com GPU CUDA (8 GB+).
• Context length: o GGUF suporta até 131072 tokens (config original do Phi-3.5), mas em CPU o KV cache faria swap com >8k tokens. Recomendação: CTX=4096 para uso diário.
• Velocidade: 9.5 tok/s é usável para chat interativo, mas outputs longos (ex: JSON grande) demoram um pouco.
• Sem memória entre sessões: Kuro é stateless. Quem persiste contexto é o operador.
• Sem internet em runtime: não consulta APIs. Para dados externos, forneça.

Licença

Este repack segue a mesma licença do modelo base: MIT (Microsoft Corporation).

• Modelo base microsoft/Phi-3.5-mini-instruct: MIT
• llama.cpp (usado para quantizar): MIT
• Este repositório de empacotamento: MIT

Nenhum peso treinado do zero. Todos os créditos do modelo pertencem à Microsoft.