diff --git a/README.MD b/README.MD deleted file mode 100644 index ce203f6..0000000 --- a/README.MD +++ /dev/null @@ -1,98 +0,0 @@ -# ForgeLM - -ForgeLM e um workspace Rust para inferencia local de LLMs com tres superficies principais: - -- uma API HTTP local compativel com partes da API de chat da OpenAI -- uma CLI (`localllm`) para operacao, diagnostico e automacao -- um app desktop Tauri para runtime management e chat persistente - -O projeto hoje e organizado para rodar localmente, com foco em modelos `.gguf`, operacao local-first e uma ponte entre backend Rust, CLI e interface desktop. - -## O que existe hoje - -- `crates/inference-server`: servidor HTTP com `GET /health`, `GET /v1/models` e `POST /v1/chat/completions` -- `crates/localllm-cli`: CLI para status, modelos, auth, config, benchmark, logs e doctor -- `tauri-app`: app desktop com runtime manager, chat UI, armazenamento local e integracao com o backend -- `crates/api-contracts`: contratos de request/response compartilhados -- `crates/inference-core`: engine, perfis de runtime e pipeline de inferencia - -## Inicio rapido - -### 1. Subir a API local - -Defina pelo menos o caminho do modelo e execute o servidor: - -```bash -set LOCALLLM_MODEL=D:\caminho\modelo.gguf -cargo run -p inference-server -``` - -Validacoes basicas: - -```bash -curl http://127.0.0.1:8080/health -curl http://127.0.0.1:8080/v1/models -``` - -### 2. Usar a CLI - -```bash -cargo run -p localllm-cli -- status -cargo run -p localllm-cli -- models list -``` - -### 3. Abrir o app desktop - -```bash -cd tauri-app -npm install -npm run tauri dev -``` - -No app, abra o Runtime Manager, configure modo local ou remoto e depois use o chat. - -## Requisitos - -- Rust toolchain atual para o workspace -- Node.js/NPM para o app Tauri -- um modelo `.gguf` local para o runtime -- GPU NVIDIA e opcional; o projeto tambem possui perfil CPU fallback - -## Estrutura do repositorio - -- `crates/api-contracts/` - contratos HTTP e tipos compartilhados -- `crates/inference-core/` - engine, sessoes, sampler e perfis de runtime -- `crates/inference-server/` - servidor HTTP local -- `crates/localllm-cli/` - CLI de operacao -- `crates/metrics/` - contadores e medicao de throughput -- `crates/llama-sys/` - bindings/integracao de baixo nivel -- `tauri-app/` - app desktop Tauri + frontend React -- `docs/` - documentacao detalhada - -## Documentacao - -- `docs/README.md` - indice da documentacao -- `docs/api/overview.md` - visao geral do backend e da API -- `docs/api/endpoints.md` - referencia HTTP -- `docs/api/configuration.md` - variaveis de ambiente e configuracao do servidor -- `docs/cli/overview.md` - visao geral da CLI -- `docs/cli/commands.md` - referencia de comandos e exemplos -- `docs/app/overview.md` - visao geral do app desktop -- `docs/app/user-guide.md` - guia de uso do app -- `docs/app/backend-commands.md` - comandos Tauri expostos pelo backend do app -- `docs/developer/architecture.md` - arquitetura do workspace e fluxos entre modulos - -## Estado atual e limitacoes - -- A API atual expoe apenas tres endpoints publicos: `GET /health`, `GET /v1/models` e `POST /v1/chat/completions`. -- A compatibilidade com OpenAI e parcial: o projeto foca no fluxo de chat, nao em toda a superficie da plataforma. -- A CLI possui uma superficie ampla, mas a execucao ao vivo hoje esta mais consolidada em `status`, `models list` e `bench throughput`. -- O app desktop controla o runtime local no modo `local` e pode consumir uma API ja existente no modo `remote`. -- O armazenamento do chat no frontend usa `sql.js` carregado por CDN e persistencia em `localStorage`. - -## Leitura recomendada - -- Quer entender a API? Comece em `docs/api/overview.md`. -- Quer operar o sistema por terminal? Va para `docs/cli/overview.md`. -- Quer usar o app desktop? Leia `docs/app/user-guide.md`. -- Quer contribuir no codigo? Comece em `docs/developer/architecture.md`. diff --git a/README.md b/README.md new file mode 100644 index 0000000..732c126 --- /dev/null +++ b/README.md @@ -0,0 +1,162 @@ +
+ +# ForgeLM + +**Inferência local de LLMs `.gguf` em Rust: API HTTP no estilo OpenAI, CLI e app +desktop Tauri com chat persistente e gerenciador de modelos — tudo rodando na sua máquina.** + +![Linguagem](https://img.shields.io/badge/Rust-edition_2021-informational) +![Desktop](https://img.shields.io/badge/Tauri-v2-informational) +![Licença](https://img.shields.io/badge/licen%C3%A7a-MIT-informational) + +[Início rápido](#in%C3%ADcio-r%C3%A1pido) · [Recursos](#o-que-existe-hoje) · [Como funciona](#como-funciona) · [Limitações](#limita%C3%A7%C3%B5es-conhecidas) · [Documentação](#documenta%C3%A7%C3%A3o) + +
+ +> [!NOTE] +> **Estado do projeto:** em desenvolvimento (último commit em abril/2026). Segundo +> [`.planning/ROADMAP.md`](.planning/ROADMAP.md), as fases 1–4 (estado de rascunho do +> runtime, segurança dos comandos de ciclo de vida, workspace unificado e download de +> modelos do Hugging Face) estão concluídas e a fase 5 (validação de fontes de modelo) +> segue aberta. O histórico também registra os planos 06-01 a 06-03 (redesign do chat +> e da página de Configurações). + +> [!IMPORTANT] +> **A API sobe aberta por padrão.** Sem `LOCALLLM_API_KEY` não há autenticação, o +> bind default é `0.0.0.0:8080` e o CORS libera `*`. Para uso fora de uma máquina +> confiável, defina a chave e restrinja `LOCALLLM_ADDR` e `LOCALLLM_CORS_ORIGINS` +> (veja [`docs/api/configuration.md`](docs/api/configuration.md)). + +## O que existe hoje + +| Superfície | Onde | O que entrega | +|---|---|---| +| **API HTTP local** | [`crates/inference-server`](crates/inference-server) | `GET /health`, `GET /v1/models` e `POST /v1/chat/completions` (com streaming SSE e `stream_options.include_usage`) | +| **CLI `localllm`** | [`crates/localllm-cli`](crates/localllm-cli) | Comandos `status`, `models`, `auth`, `config`, `bench`, `logs` e `doctor`; flags globais `--server`, `--api-key`, `--models-dir`, `--format text\|json` e `--dry-run` | +| **App desktop** | [`tauri-app`](tauri-app) | Runtime manager (modo `local` ou `remote`), chat persistente e página de Configurações com gerenciador de modelos | +| **Perfis de runtime** | [`crates/inference-core`](crates/inference-core) | `Turbo4B` (default), `balanced_9b` e `cpu_fallback`, ajustáveis por `LOCALLLM_GPU_LAYERS`, `LOCALLLM_CTX`, `LOCALLLM_BATCH`, etc. | +| **Runtime llama.cpp gerenciado** | [`crates/runtime-deps`](crates/runtime-deps) | Baixa o llama.cpp `b8358` (variantes CPU e CUDA 12.4), valida SHA-256 e guarda em cache local | + +No app desktop: + +- **Runtime manager** com estados `stopped`, `starting`, `ready`, `degraded`, `stopping` e `error`; o modo local inicia/para o processo e usa `GET /health` para saber se está pronto. +- **Gerenciador de modelos:** escaneia/importa `.gguf`, busca modelos no Hugging Face, baixa em streaming com progresso e cancelamento (token do Hugging Face opcional), troca o modelo carregado com um clique (*hot-swap*: para, grava o novo `model_path` e reinicia), apaga arquivos e abre a pasta no explorador. +- **Chat:** streaming, memória opcional de até 20 mensagens recentes, separação visual do raciocínio (`…`) da resposta final, contagem de tokens (por mensagem e por chat) e tokens/s, edição, reenvio e exclusão de mensagens. + +## Início rápido + +> [!WARNING] +> **Na primeira execução o servidor baixa o runtime do llama.cpp.** Se o runtime não +> for encontrado (`LLAMA_DLL_PATH`, ao lado do binário ou vendor legado), o `runtime-deps` baixa o +> pacote de `github.com/ggml-org/llama.cpp` (`b8358`). A variante CUDA 12.4 são dois +> zips (≈ 227 MB + ≈ 391 MB conforme o manifesto); a CPU, um zip de ≈ 37 MB. O +> servidor escolhe CUDA quando as camadas em GPU são `> 0` e cai para CPU caso não +> exista variante de GPU para o alvo. + +**1. Subir a API local** (Windows `cmd`; em bash use `export`): + +```bash +set LOCALLLM_MODEL=D:\caminho\modelo.gguf +cargo run -p inference-server + +curl http://127.0.0.1:8080/health +curl http://127.0.0.1:8080/v1/models +``` + +**2. Usar a CLI:** + +```bash +cargo run -p localllm-cli -- status +cargo run -p localllm-cli -- models list +``` + +**3. Abrir o app desktop:** + +```bash +cd tauri-app +npm install +npm run tauri dev +``` + +No app, abra o Runtime Manager, escolha modo `local` ou `remote` e depois use o chat. + +**Requisitos:** toolchain Rust atual, Node.js/NPM (app Tauri) e um modelo `.gguf` local. +GPU NVIDIA é opcional — existe o perfil `cpu_fallback`. + +## Como funciona + +```mermaid +flowchart LR + UI["App Tauri
React + Rust"] -->|"HTTP /v1/chat/completions"| S + UI -->|"inicia / para / health"| S["inference-server
Axum · binário localllm"] + CLI["localllm-cli"] -->|HTTP| S + S --> C["inference-core
engine · sessão · sampler · perfis"] + C --> L["llama-sys
carga dinâmica (libloading)"] + L --> R["llama.dll
llama.cpp b8358"] + D["runtime-deps
download + SHA-256"] --> R + S --> D + UI -->|"busca e download"| HF["Hugging Face"] + S -.-> M["metrics
tokens e throughput"] +``` + +
+Crates e módulos + +| Módulo | Responsabilidade | +|---|---| +| `crates/api-contracts` | Tipos compartilhados: chat completions, lista de modelos, health e erros | +| `crates/inference-core` | Engine de inferência local: carga do modelo, sessão, sampler e perfis de runtime | +| `crates/inference-server` | Camada HTTP em Axum: variáveis de ambiente, auth, CORS e aliases de modelo | +| `crates/localllm-cli` | CLI de operação e automação (clap) | +| `crates/metrics` | Contadores de uso de tokens e throughput | +| `crates/llama-sys` | Integração de baixo nível: carrega `llama.dll` dinamicamente via `libloading` | +| `crates/runtime-deps` | Resolve o runtime (override por env, binário adjacente, vendor legado ou cache gerenciado) e instala a partir de [`vendor/llama-runtime/manifest.json`](vendor/llama-runtime/manifest.json) | +| `tauri-app/` | App desktop: frontend React 18 + Vite + Tailwind, backend Tauri 2 em Rust | + +Variáveis de ambiente do servidor (principais): `LOCALLLM_MODEL`, `LOCALLLM_ADDR`, +`LOCALLLM_MODEL_ALIASES`, `LOCALLLM_PROFILE`, `LOCALLLM_API_KEY`, +`LOCALLLM_AUTH_HEADER`, `LOCALLLM_AUTH_SCHEME`, `LOCALLLM_CORS_ORIGINS`, +`LOCALLLM_SYSTEM_PROMPT` e `LOCALLLM_ENABLE_TOOL_CALLS`. Detalhes em +[`docs/api/configuration.md`](docs/api/configuration.md). + +
+ +## Limitações conhecidas + +- A API expõe só três endpoints; a compatibilidade com a OpenAI é parcial e focada no fluxo de chat (`n` precisa ser `1`, `parallel_tool_calls` não é tratado como recurso suportado, `content` em partes vira texto consolidado). +- O raciocínio não aparece como campo separado na API; quem separa `…` é o frontend do app. +- Na CLI, a execução ao vivo está mais consolidada em `status`, `models list` e `bench throughput`; o restante da superfície é mais avançado no parser do que nas capacidades HTTP públicas. +- O chat usa `sql.js` carregado por CDN e persiste o banco exportado em `localStorage` — não é um banco nativo do sistema. +- No modo local o app precisa encontrar o binário `localllm`; o runtime manager faz polling periódico do snapshot (sem fluxo de eventos push). +- O manifesto do runtime ([`vendor/llama-runtime/manifest.json`](vendor/llama-runtime/manifest.json)) só lista variantes `windows-x64` (CPU e CUDA 12.4). Em outros alvos o servidor só sobe com um runtime já presente (binário adjacente ou `LLAMA_DLL_PATH`). +- Os scripts [`scripts/build-dev.sh`](scripts/build-dev.sh) e [`scripts/build-prod.sh`](scripts/build-prod.sh) compilam `vendor/llama.cpp` e exigem esse submódulo, que não está declarado no repositório (não há `.gitmodules`). +- `inference-server` e `localllm-cli` declaram ambos um binário chamado `localllm`; use `cargo run -p ` para escolher qual executar. + +## Execução local + +```bash +cargo run -p inference-server # API em 0.0.0.0:8080 (precisa de LOCALLLM_MODEL) +cargo run -p localllm-cli -- status # CLI + +cd tauri-app +npm install +npm run dev # só o frontend (Vite, porta 1420) +npm run tauri dev # app desktop completo +npm run build # tsc + vite build +npm test # vitest run +``` + +## Documentação + +| Documento | Conteúdo | +|---|---| +| [`docs/README.md`](docs/README.md) | Índice da documentação | +| [`docs/api/overview.md`](docs/api/overview.md) · [`endpoints.md`](docs/api/endpoints.md) · [`configuration.md`](docs/api/configuration.md) | API: visão geral, referência HTTP e configuração | +| [`docs/cli/overview.md`](docs/cli/overview.md) · [`commands.md`](docs/cli/commands.md) | CLI: visão geral e referência de comandos | +| [`docs/app/overview.md`](docs/app/overview.md) · [`user-guide.md`](docs/app/user-guide.md) · [`backend-commands.md`](docs/app/backend-commands.md) | App desktop: visão geral, guia de uso e comandos Tauri | +| [`docs/developer/architecture.md`](docs/developer/architecture.md) | Arquitetura do workspace e fluxos entre módulos | + +## Avisos + +- Os binários de inferência vêm do [llama.cpp](https://github.com/ggml-org/llama.cpp) (releases oficiais baixadas e verificadas por SHA-256); modelos são buscados no [Hugging Face](https://huggingface.co) e seguem a licença de cada autor. +- Licença do workspace: MIT (declarada em [`Cargo.toml`](Cargo.toml); o repositório não inclui arquivo `LICENSE`).