ForgeLM/docs/app/user-guide.md

Guia de uso do app desktop

Este guia cobre o fluxo de uso do app Tauri no estado atual do projeto.

1. Abrir o app

Em desenvolvimento:

cd tauri-app
npm install
npm run tauri dev

2. Entender os modos de conexao

O Runtime Manager suporta dois modos.

Local API

Use quando o app deve subir e controlar o backend local.

Voce configura:

• pasta de modelos
• modelo selecionado
• endereco de bind (addr)
• numero de GPU layers
• contexto (ctx_size)
• politica de auto-start

Remote API

Use quando a API ja esta rodando em outro lugar.

Voce configura:

• server_url
• api_key opcional

Nesse modo o app nao tenta iniciar/parar o backend local.

3. Configurar o runtime local

Na sidebar, abra Manage ou o icone de configuracao.

Fluxo recomendado:

1. deixe Connection mode em Local API
2. escolha a pasta de modelos com Browse, ou adicione arquivos individuais com Add files
3. selecione o modelo desejado
4. ajuste Listen address, GPU layers e Context size se necessario
5. use Save settings ou Save and start local API

Observacoes:

• o app tenta descobrir o binario do backend automaticamente
• se uma revarredura da pasta vier vazia, o app preserva o model_path salvo em vez de limpar a selecao imediatamente
• o start local so fica disponivel quando existe binario e modelo selecionado

4. Configurar API remota

1. abra o Runtime Manager
2. mude para Remote API
3. preencha Remote server URL
4. opcionalmente, preencha API key
5. salve a configuracao

Depois disso, o app passa a usar essa URL para GET /v1/models e POST /v1/chat/completions.

5. Selecionar modelos no app

Quando a API estiver acessivel:

• o seletor de modelo na sidebar sera preenchido por GET /v1/models
• o app tenta manter a selecao atual quando possivel
• se o modelo sumir da API, o app troca para o primeiro disponivel

6. Conversar no chat

O fluxo principal fica em ChatView.

Recursos de uso:

• streaming on/off
• memory on/off
• historico persistente por conversa
• edicao e reenvio de mensagens do usuario
• edicao de resposta do assistente
• copia de conteudo/markdown/codigo

7. Thinking e tokens

Quando a resposta inclui blocos <think>...</think>:

• o app separa esse conteudo como Thinking
• o painel de thinking pode ser expandido/recolhido
• a resposta final aparece separadamente do thinking

Metricas visiveis:

• tokens enviados (Sent)
• tokens gerados (Generated)
• total por mensagem e por chat
• tok/s quando informado pela API

8. Troubleshooting rapido

"Configure a local or remote API before sending messages"

O app esta sem endpoint valido. Abra o Runtime Manager e configure modo local ou remoto.

Nenhum modelo aparece

• confirme que a API esta acessivel
• use o botao de refresh da sidebar
• no modo local, confirme que o modelo salvo foi iniciado corretamente

O start local esta desabilitado

Verifique:

• se o binario do backend foi encontrado
• se um modelo esta salvo/selecionado
• se voce nao esta em modo remoto

O runtime sobe mas nunca fica pronto

O app usa readiness por GET /health. Se a API local nao passar nesse check dentro do timeout, o runtime manager marca erro.

9. Persistencia e cuidado com dados

• chats e mensagens ficam no armazenamento local do app/frontend
• o app nao implementa sincronizacao remota de conversas
• apagar dados do navegador/webview pode remover o historico local