{"id":48690527,"url":"https://github.com/xbrasil/myaiplayground","last_synced_at":"2026-06-13T22:01:30.341Z","repository":{"id":350534592,"uuid":"1205308225","full_name":"xBrasil/myAIplayground","owner":"xBrasil","description":"An open-source local application for chatting with Gemma 4 AI models running on your machine in a modern web UI.","archived":false,"fork":false,"pushed_at":"2026-06-13T16:47:52.000Z","size":946,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-13T17:06:11.236Z","etag":null,"topics":["ai","fastapi","gemma","gemma4","llama-cpp","llamacpp","llm","local-ai","multimodal","multimodal-ai","open-source","privacy","python","react","typescript","whisper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xBrasil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-08T20:56:06.000Z","updated_at":"2026-04-18T17:24:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"2d24bf6f-853b-4ddf-8723-93fed4fec019","html_url":"https://github.com/xBrasil/myAIplayground","commit_stats":null,"previous_names":["xbrasil/myaiplayground"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/xBrasil/myAIplayground","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xBrasil%2FmyAIplayground","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xBrasil%2FmyAIplayground/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xBrasil%2FmyAIplayground/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xBrasil%2FmyAIplayground/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xBrasil","download_url":"https://codeload.github.com/xBrasil/myAIplayground/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xBrasil%2FmyAIplayground/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34301732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","fastapi","gemma","gemma4","llama-cpp","llamacpp","llm","local-ai","multimodal","multimodal-ai","open-source","privacy","python","react","typescript","whisper"],"created_at":"2026-04-11T05:16:17.475Z","updated_at":"2026-06-13T22:01:30.334Z","avatar_url":"https://github.com/xBrasil.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"frontend/public/original_logo.png\" alt=\"My AI Playground\" width=\"180\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMy AI Playground\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Aplicação desktop-local para conversas com modelos \u003ca href=\"https://ai.google.dev/gemma/docs/core/model_card_4\"\u003eGemma 4\u003c/a\u003e rodando inteiramente na sua máquina.\u003cbr/\u003e\n  Interface web moderna, entrada multimodal (texto, imagens, áudio, arquivos) e histórico salvo apenas localmente.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\n![Stack](https://img.shields.io/badge/React_19-282c34?logo=react) ![Stack](https://img.shields.io/badge/FastAPI-009688?logo=fastapi\u0026logoColor=white) ![Stack](https://img.shields.io/badge/llama.cpp-GGUF-blue) ![Stack](https://img.shields.io/badge/SQLite-003B57?logo=sqlite\u0026logoColor=white)\n\n\u003c/p\u003e\n\n---\n\n## Funcionalidades\n\n| Categoria                             | Descrição                                                                                                                                                                  |\n| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Chat multimodal**             | Texto, imagens, áudio e arquivos em uma única conversa — envio simultâneo de múltiplos arquivos; arquivos de áudio enviados manualmente entram como anexos de contexto, com extração automática da faixa em contêineres como MP4; imagens em PNG, JPEG, WebP, GIF, SVG, HEIC/HEIF, AVIF, BMP, ICO e TIFF |\n| **Modelos Gemma 4**             | E2B, E4B, 12B Unified e 26B-A4B via GGUF — troque de modelo a qualquer momento pela interface                                                                                |\n| **Arquivos de texto**           | 60+ extensões de código e dados (`.py`, `.ts`, `.json`, `.csv`, `.xml`, `.yaml`, `.sql`, `.rs`, `.go`…) lidos como texto                                |\n| **Documentos**                  | PDF, Word (`.docx`), Excel (`.xlsx`) e PowerPoint (`.pptx`) — extração de texto automática                                                                         |\n| **Pesquisa na web**             | Busca via DuckDuckGo e leitura de páginas — o modelo cita fontes com referências numeradas `[1]`, `[2]`…                                                             |\n| **Acesso a arquivos locais**    | O modelo pode listar e ler arquivos de pastas permitidas pelo usuário (somente leitura)                                                                                     |\n| **Visão de imagens locais**    | Em modelos com visão (todos os modelos Gemma 4 disponíveis), o modelo pode ver e descrever imagens de pastas permitidas                                                     |\n| **Tool calling**                | O modelo pode chamar ferramentas (web, filesystem, visão) automaticamente; chamadas ficam salvas no histórico e são exibidas de forma auditável                          |\n| **Instruções personalizadas** | System prompt customizável pelo usuário nos Ajustes — aplicado a todas as conversas                                                                                       |\n| **Inferência local**           | llama.cpp server com aceleração GPU (NVIDIA CUDA, AMD HIP/ROCm, Apple Metal) ou CPU, flash attention, contexto por modelo (128K–256K tokens)                              |\n| **Streaming**                   | Respostas exibidas token a token em tempo real                                                                                                                               |\n| **Auto-continuação**          | Respostas longas continuam automaticamente quando o limite de tokens é atingido (até 5 rodadas)                                                                            |\n| **Gravação de voz**           | Gravar, pausar, retomar e parar antes de enviar; áudio convertido para WAV 16 kHz; timer com contagem regressiva                                                            |\n| **Transcrição**               | Whisper (faster-whisper) converte áudio em texto localmente quando o modelo ativo não oferece áudio nativo ou quando o engine não suporta essa entrada                      |\n| **Leitura de respostas**        | Text-to-Speech via Web Speech API com preferência para vozes Microsoft                                                                                                      |\n| **Markdown rico**               | Renderização com GFM, blocos de código com syntax highlight, matemática KaTeX                                                                                            |\n| **Edição de mensagens**       | Editar mensagens enviadas e regenerar respostas                                                                                                                              |\n| **Pesquisa de mensagens**       | Busque conversas por título ou conteúdo — destaque automático dos termos encontrados                                                                                     |\n| **Localização**               | Compartilhamento opcional de geolocalização para respostas mais contextualizadas (desativado por padrão)                                                                  |\n| **Avaliação de risco**        | Instruções personalizadas são avaliadas automaticamente pelo LLM; alerta exibido apenas quando o risco é significativo                                                   |\n| **i18n**                        | Português (BR), English (US), Español e Français — detecta automaticamente o idioma do navegador                                                                         |\n| **Tema escuro**                 | UI minimalista e responsiva com design dark-mode                                                                                                                             |\n| **Janela deslizante**           | Gestão automática de contexto: truncamento de conteúdo longo, descarte de mensagens antigas e retry em estouro                                                            |\n| **Privacidade total**           | Conversas e arquivos ficam em `data/user/` no seu disco. Nada é enviado para a nuvem.                                                                                     |\n| **Ícone na bandeja**           | Em vez de uma janela de console, a aplicação roda como ícone na bandeja do sistema (system tray) com menu para abrir, reiniciar, ver logs e encerrar                      |\n\n---\n\n## Interface\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/chat-dark-mode.jpeg\" alt=\"Chat em tema escuro\" width=\"720\" /\u003e\u003cbr/\u003e\n  \u003cem\u003eInterface principal com tema escuro — conversa com o modelo Gemma 4 E4B\u003c/em\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/multimodal-image.jpeg\" alt=\"Entrada multimodal com imagem\" width=\"720\" /\u003e\u003cbr/\u003e\n  \u003cem\u003eEnvio de imagem com análise visual pelo modelo\u003c/em\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/streaming-response.jpeg\" alt=\"Resposta em streaming\" width=\"720\" /\u003e\u003cbr/\u003e\n  \u003cem\u003eResposta em tempo real — tokens aparecem conforme são gerados\u003c/em\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/model-selector.jpeg\" alt=\"Seletor de modelos\" width=\"720\" /\u003e\u003cbr/\u003e\n  \u003cem\u003eSeletor de modelos com descrições de capacidade e limitações\u003c/em\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/settings-panel.jpeg\" alt=\"Painel de ajustes\" width=\"720\" /\u003e\u003cbr/\u003e\n  \u003cem\u003ePainel de ajustes — idioma, voz, instruções personalizadas, acesso web, arquivos locais\u003c/em\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/web-search.jpeg\" alt=\"Pesquisa na web\" width=\"720\" /\u003e\u003cbr/\u003e\n  \u003cem\u003ePesquisa na web com citação de fontes numeradas\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## Requisitos de Sistema\n\nO My AI Playground roda modelos de IA localmente no seu hardware. Os requisitos variam conforme o modelo escolhido.\n\n### Mínimos (modelo Gemma 4 E2B — 2B parâmetros)\n\n| Componente           | Requisito                                                   |\n| -------------------- | ----------------------------------------------------------- |\n| **SO**         | Windows 10/11 (64 bits)                                     |\n| **RAM**        | 8 GB                                                        |\n| **VRAM (GPU)** | 4 GB (NVIDIA CUDA, AMD HIP/ROCm ou Apple Metal) ou modo CPU |\n| **Disco**      | ~10 GB para o modelo + 2 GB para dependências              |\n| **CPU**        | Qualquer x86-64 com suporte AVX2 (ou Apple Silicon arm64)   |\n\n### Intermediário (modelo padrão Gemma 4 E4B — 4B parâmetros)\n\n| Componente           | Requisito                                       |\n| -------------------- | ----------------------------------------------- |\n| **RAM**        | 16 GB                                           |\n| **VRAM (GPU)** | 7 GB (NVIDIA CUDA, AMD HIP/ROCm ou Apple Metal) |\n| **Disco**      | ~10 GB para o modelo + 2 GB para dependências  |\n\n### Recomendados (modelo Gemma 4 12B Unified — 12B parâmetros)\n\n| Componente           | Requisito                                        |\n| -------------------- | ------------------------------------------------ |\n| **RAM**        | 24 GB                                            |\n| **VRAM (GPU)** | 12 GB (NVIDIA CUDA, AMD HIP/ROCm ou Apple Metal) |\n| **Disco**      | ~10 GB para o modelo + 2 GB para dependências     |\n\n### Para o modelo maior (Gemma 4 26B-A4B — 26B parâmetros, MoE)\n\n| Componente           | Requisito                                         |\n| -------------------- | ------------------------------------------------- |\n| **RAM**        | 32 GB                                             |\n| **VRAM (GPU)** | 16 GB+ (NVIDIA CUDA, AMD HIP/ROCm ou Apple Metal) |\n| **Disco**      | ~26 GB para o modelo + 2 GB para dependências    |\n\n\u003e **Nota:** sem VRAM suficiente, o llama.cpp fará offloading para a RAM do sistema (modo CPU/parcial), resultando em inferência significativamente mais lenta. Se você receber erros de **Out of Memory (OOM)**, experimente um modelo menor ou reduza `N_CTX` no arquivo `data/system/.env`.\n\n---\n\n## Início rápido (Windows)\n\n### Opção A — Instalador gráfico\n\nNa [página de releases](https://github.com/xBrasil/myAIplayground/releases) está disponível um instalador `.exe` para Windows (criado com [Inno Setup](https://jrsoftware.org/isinfo.php)). O assistente de instalação copia os arquivos, cria atalhos no Menu Iniciar e na Área de Trabalho, e opcionalmente executa a configuração de dependências ao final.\n\n### Opção B — Via scripts\n\n#### Pré-requisitos\n\n- **Windows 10/11** (64 bits)\n- **Python 3.11+**\n- **Node.js 20+**\n- **GPU** com drivers atualizados — NVIDIA (CUDA), AMD (HIP no Windows, ROCm no Linux) ou Apple Silicon (Metal) — recomendado; funciona sem GPU em modo CPU\n\n#### Instalação\n\n```powershell\ninstall.cmd\n```\n\nO instalador:\n\n- Detecta e instala Python e Node.js automaticamente via `winget` (solicitando elevação UAC se necessário)\n- Cria o ambiente virtual `.venv` e instala dependências do backend\n- Instala dependências npm do frontend\n- Baixa o binário mais recente do `llama-server` (CUDA, HIP, ROCm, Metal ou CPU, conforme sua GPU)\n- Cria `data/system/.env` a partir de `backend/.env.example`\n\n#### Execução\n\n```powershell\ntray.cmd\n```\n\nO launcher:\n\n- Inicia backend (FastAPI na porta 8000) e frontend (Vite na porta 5173) em segundo plano\n- Exibe um ícone na bandeja do sistema (system tray) com menu: **Abrir no Navegador**, **Ver Logs**, **Reiniciar**, **Sair**\n- Aguarda os serviços ficarem prontos e abre a interface no navegador automaticamente\n- Logs salvos em `data/system/logs/backend.log` e `data/system/logs/frontend.log`\n\n\u003e **Modo diagnóstico:** para ver o log completo no console (útil para depuração), use `run.cmd` em vez de `tray.cmd`.\n\n\u003e **Dica:** o primeiro uso de cada modelo envolve download do GGUF do Hugging Face. Modelos ficam em cache em `data/system/model-cache/`.\n\n---\n\n## Início rápido (Linux / macOS)\n\n### Pré-requisitos\n\n- **Python 3.11+** com `venv` (`python3-venv` no Ubuntu/Debian)\n- **Node.js 20+**\n- **GPU** com drivers atualizados — NVIDIA (CUDA), AMD (ROCm) ou Apple Silicon (Metal) — recomendado; funciona sem GPU em modo CPU\n- `curl`, `unzip` e `tar` instalados\n\n### Instalação\n\n```bash\nchmod +x install.sh\n./install.sh\n```\n\nO instalador faz as mesmas etapas da versão Windows: cria `.venv`, instala dependências, baixa `llama-server` e prepara `.env`.\n\n### Execução\n\n```bash\n./tray.sh\n```\n\nInicia os serviços em segundo plano e exibe um ícone na bandeja do sistema com menu de controle. O navegador é aberto automaticamente quando os serviços ficam prontos.\n\n\u003e **Modo diagnóstico:** para ver o log no terminal, use `./run.sh` em vez de `./tray.sh`. Use `Ctrl+C` para encerrar.\n\n\u003e **Nota:** o script detecta automaticamente macOS (arm64/x64) e Linux para baixar o binário correto do llama-server.\n\n---\n\n## Modelos disponíveis\n\n| Modelo                    | Arquivo GGUF                          | Quantização | Contexto | Uso típico                              |\n| ------------------------- | ------------------------------------- | ------------- | -------- | ---------------------------------------- |\n| **Gemma 4 E2B**     | `gemma-4-E2B-it-Q8_0.gguf`          | Q8_0          | 128K     | Rápido, ideal para testes               |\n| **Gemma 4 E4B**     | `gemma-4-E4B-it-Q4_K_M.gguf`        | Q4_K_M        | 128K     | Equilíbrio entre qualidade e velocidade |\n| **Gemma 4 12B Unified** | `gemma-4-12b-it-qat-q4_0.gguf`  | QAT Q4_0      | 256K     | Alta capacidade, áudio nativo           |\n| **Gemma 4 26B-A4B** | `gemma-4-26B-A4B-it-UD-IQ4_XS.gguf` | IQ4_XS        | 256K     | Maior qualidade, requer mais VRAM        |\n\nO modelo E2B é selecionado por padrão caso o usuário não disponha de uma GPU, e o E4B caso disponha. E2B, E4B e 12B Unified processam áudio nativamente; no GGUF do 12B, o llama.cpp habilita mídia com o `mmproj-gemma-4-12b-it-qat-q4_0.gguf`. O 26B-A4B não tem áudio nativo e usa fallback por transcrição Whisper. Todos são executados pelo llama.cpp via GGUF, sem PyTorch em runtime.\n\n\u003e **Nota:** o `mmproj` do 12B Unified usa o projector `gemma4uv`, suportado pelo `llama-server` b9616 ou mais recente. Execute `install.cmd`/`install.sh` novamente se o app tiver sido instalado com uma build anterior.\n\n---\n\n## Stack técnica\n\n### Frontend\n\n- **React 19** + **TypeScript** + **Vite**\n- `react-markdown` + `remark-gfm` + `remark-math` + `rehype-katex`\n- Web Speech API (TTS)\n- MediaRecorder API (gravação de áudio)\n\n### Backend\n\n- **FastAPI** + **Uvicorn**\n- **SQLAlchemy** (SQLite)\n- **faster-whisper** (transcrição de áudio)\n- **huggingface_hub** (download de modelos)\n- **httpx** (comunicação com llama-server)\n- **duckduckgo-search** (pesquisa web via DuckDuckGo)\n- **beautifulsoup4** (extração de conteúdo de páginas web)\n- **PyMuPDF** / **python-docx** / **openpyxl** / **python-pptx** (extração de texto de documentos)\n- **pillow-heif** (suporte a HEIC e AVIF no Pillow)\n- **svglib** + **reportlab** (renderização de SVG para análise visual)\n- **pystray** (ícone na bandeja do sistema — system tray)\n\n### Inferência\n\n- **llama.cpp server** (binário pré-compilado — NVIDIA CUDA, AMD HIP/ROCm, Apple Metal ou CPU)\n- Detecção automática de GPU (NVIDIA, AMD, Apple Silicon) com fallback para CPU\n- Gerenciado automaticamente pelo backend — download, inicialização e fallback\n\n---\n\n## Estrutura do projeto\n\n```\nmyAIplayground/\n├── frontend/          # React + Vite (interface web)\n│   └── src/\n│       ├── components/   # Sidebar, ChatLayout, Composer, MessageList...\n│       ├── lib/          # API client, preferências, speech, i18n\n│       └── locales/      # pt-BR.json, en-US.json, es-ES.json, fr-FR.json\n├── backend/           # FastAPI (API + serviços)\n│   └── app/\n│       ├── api/routes/   # chat, conversations, health, legal, models, settings\n│       ├── core/         # config (pydantic-settings)\n│       └── services/     # chat, model, storage, input_adapter, document, web, filesystem, whisper\n├── data/              # Dados locais (ignorados pelo git)\n│   ├── user/             # Dados do usuário (preservados na desinstalação)\n│   │   ├── app.db           # SQLite com conversas e mensagens\n│   │   └── uploads/         # Arquivos enviados nas conversas\n│   └── system/           # Dados do sistema (removidos na desinstalação)\n│       ├── model-cache/     # GGUF e mmproj baixados do HF\n│       ├── llama-server/    # Binário do llama-server\n│       └── logs/            # Logs da aplicação\n├── docs/              # Documentação adicional\n├── scripts/           # Scripts utilitários (install, run, tray, release, i18n, test)\n├── install.cmd        # Instalação automatizada (Windows)\n├── tray.cmd           # Launcher com ícone na bandeja (Windows)\n├── run.cmd            # Launcher modo diagnóstico (Windows)\n├── install.sh         # Instalação automatizada (Linux / macOS)\n├── tray.sh            # Launcher com ícone na bandeja (Linux / macOS)\n├── run.sh             # Launcher modo diagnóstico (Linux / macOS)\n└── README.md\n```\n\n---\n\n## Privacidade\n\n- As conversas são salvas apenas em `data/user/app.db` (local).\n- Arquivos enviados ficam em `data/user/uploads/` (local).\n- Os ajustes do aplicativo (idioma, voz, instruções personalizadas, pastas permitidas etc.) ficam em `data/user/settings.json` (local).\n- O download inicial dos modelos vem do Hugging Face. Após isso, tudo roda offline.\n- **Pesquisa web**: quando ativada nos Ajustes, o modelo pode fazer buscas no DuckDuckGo e acessar páginas web. Essas requisições saem da sua máquina. Desative nos Ajustes para modo totalmente offline.\n- **Acesso a arquivos locais**: quando ativado nos Ajustes, o modelo pode ler arquivos **somente** das pastas que você permitiu explicitamente. Acesso é READ-ONLY e protegido contra travessia de diretório.\n- A funcionalidade de Text-to-Speech usa a API `speechSynthesis` do navegador. O comportamento (local vs. online) depende da voz selecionada e da configuração do sistema.\n\n---\n\n## Modelos de IA (Gemma 4)\n\n\u003e **Aviso:** Este projeto **não é afiliado, patrocinado nem endossado pelo Google ou pela Alphabet Inc.** \"Gemma 4\" é uma marca do Google. Os modelos Gemma 4 são utilizados sob os termos de licenciamento disponibilizados pelo Google.\n\nOs modelos de IA utilizados por esta aplicação (família **Google Gemma 4**) **não são distribuídos** com este repositório. Eles são baixados diretamente do [Hugging Face](https://huggingface.co/) mediante solicitação do usuário e estão sujeitos aos [Termos de Uso do Gemma 4 - Apache 2.0](https://ai.google.dev/gemma/apache_2) do Google.\n\nAo baixar e usar esses modelos, você concorda em cumprir os termos do Google, que incluem restrições à geração de conteúdo prejudicial, ilegal ou enganoso.\n\n---\n\n## Licença\n\nEste projeto é licenciado sob a [Apache License 2.0](LICENSE).\n\n```\nCopyright 2026 Rodolfo Motta Saraiva\n```\n\nCriado por [Rodolfo Motta Saraiva](https://rmsaraiva.com/) como projeto pessoal de código aberto.\n\n### Componentes de terceiros\n\n| Componente                                                                                              | Licença                                                               |\n| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |\n| [llama.cpp](https://github.com/ggml-org/llama.cpp)                                                         | MIT                                                                    |\n| [FastAPI](https://github.com/tiangolo/fastapi)                                                             | MIT                                                                    |\n| [Uvicorn](https://github.com/encode/uvicorn)                                                               | BSD-3-Clause                                                           |\n| [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy)                                                     | MIT                                                                    |\n| [Pydantic](https://github.com/pydantic/pydantic)                                                           | MIT                                                                    |\n| [React](https://github.com/facebook/react)                                                                 | MIT                                                                    |\n| [Vite](https://github.com/vitejs/vite)                                                                     | MIT                                                                    |\n| [react-markdown](https://github.com/remarkjs/react-markdown)                                               | MIT                                                                    |\n| [KaTeX](https://github.com/KaTeX/KaTeX) (via rehype-katex)                                                 | MIT                                                                    |\n| [Hugging Face Hub](https://github.com/huggingface/huggingface_hub)                                         | Apache 2.0                                                             |\n| [faster-whisper](https://github.com/SYSTRAN/faster-whisper)                                                | MIT                                                                    |\n| [Pillow](https://github.com/python-pillow/Pillow)                                                          | HPND                                                                   |\n| [pillow-heif](https://github.com/bigcat88/pillow_heif)                                                     | BSD-3-Clause                                                           |\n| [PyMuPDF](https://github.com/pymupdf/PyMuPDF)                                                              | AGPL-3.0                                                               |\n| [python-docx](https://github.com/python-openxml/python-docx)                                               | MIT                                                                    |\n| [openpyxl](https://foss.heptapod.net/openpyxl/openpyxl)                                                    | MIT                                                                    |\n| [python-pptx](https://github.com/scanny/python-pptx)                                                       | MIT                                                                    |\n| [duckduckgo-search](https://github.com/deedy5/duckduckgo_search)                                           | MIT                                                                    |\n| [beautifulsoup4](https://www.crummy.com/software/BeautifulSoup/)                                           | MIT                                                                    |\n| [svglib](https://github.com/deeplook/svglib)                                                               | LGPL-3.0                                                               |\n| [reportlab](https://www.reportlab.com/dev/opensource/)                                                     | BSD-3-Clause                                                           |\n| [pystray](https://github.com/moses-palmer/pystray)                                                         | LGPL-3.0                                                               |\n| [Inno Setup](https://jrsoftware.org/isinfo.php) (instalador Windows)                                       | [Inno Setup License](https://jrsoftware.org/files/is/license.txt)         |\n| [Google Gemma 4](https://ai.google.dev/gemma/docs/core/model_card_4) (modelos de IA — não distribuídos) | [Gemma 4 Terms of Use - Apache 2.0](https://ai.google.dev/gemma/apache_2) |\n\n---\n\n## English Summary\n\n**My AI Playground** is an open-source, desktop-local application for chatting with [Google Gemma 4](https://ai.google.dev/gemma/docs/core/model_card_4) AI models running entirely on your machine. It features a modern web UI, multimodal input (text, images, audio, files), and conversation history stored only locally.\n\n\u003e **Disclaimer:** This project is **not affiliated with, sponsored by, or endorsed by Google or Alphabet Inc.** \"Gemma 4\" is a trademark of Google. The Gemma 4 models are used under the licensing terms provided by Google [Gemma 4 Terms of Use - Apache 2.0](https://ai.google.dev/gemma/apache_2).\n\n### Features\n\n- **Multimodal chat** — text, images, audio and files in a single conversation; multiple attachments per message. Uploaded audio files are treated as conversation attachments, with automatic audio-track extraction from containers such as MP4. Image formats: PNG, JPEG, WebP, GIF, SVG, HEIC/HEIF, AVIF, BMP, ICO, TIFF.\n- **Gemma models** — Gemma 4 E2B, E4B, 12B Unified and 26B-A4B via GGUF; switch models at any time from the UI.\n- **Text files** — 60+ code and data extensions (`.py`, `.ts`, `.json`, `.csv`, `.xml`, `.yaml`, `.sql`, `.rs`, `.go`…) read as plain text.\n- **Documents** — PDF, Word (`.docx`), Excel (`.xlsx`) and PowerPoint (`.pptx`) with automatic text extraction.\n- **Web search** — DuckDuckGo search and page reading; the model cites sources with numbered references (`[1]`, `[2]`…).\n- **Local filesystem access** — the model can list and read files from folders you explicitly allow (read-only, directory-traversal protected).\n- **Local image vision** — on vision-capable models (all available Gemma 4 models), the model can see and describe images from allowed folders.\n- **Tool calling** — the model calls tools (web, filesystem, vision) automatically; calls are persisted and rendered auditably in the history.\n- **Custom instructions** — user-defined system prompt applied to all conversations.\n- **Local inference** — llama.cpp server with CUDA, flash attention, per-model context (128K–256K tokens).\n- **Streaming** — responses rendered token by token in real time.\n- **Auto-continuation** — long responses continue automatically when the token limit is reached (up to 5 rounds).\n- **Voice recording** — record, pause, resume and stop before sending; audio converted to 16 kHz WAV with a countdown timer.\n- **Transcription** — Whisper (faster-whisper) converts audio to text locally when the active model or engine cannot process native audio.\n- **Text-to-Speech** — Web Speech API with preference for Microsoft voices.\n- **Rich Markdown** — GFM rendering, syntax-highlighted code blocks, KaTeX math.\n- **Message editing** — edit sent messages and regenerate responses.\n- **Message search** — search conversations by title or content with term highlighting.\n- **Location** — optional geolocation sharing for more context-aware answers (off by default).\n- **Risk evaluation** — custom instructions are evaluated automatically by the LLM; alerts shown only when risk is significant.\n- **i18n** — Portuguese (BR), English (US), Spanish and French; auto-detects browser language.\n- **Dark theme** — minimalist responsive UI.\n- **Sliding window** — automatic context management: long-content truncation, old-message eviction and retry on overflow.\n\n### System Requirements\n\n| Model                     | RAM   | VRAM (GPU)                                                     | Disk   |\n| ------------------------- | ----- | -------------------------------------------------------------- | ------ |\n| Gemma 4 E2B (2B)          | 8 GB  | 4 GB (NVIDIA CUDA, AMD HIP/ROCm or Apple Metal — or CPU-only) | ~3 GB  |\n| Gemma 4 E4B (4B)          | 16 GB | 7 GB                                                           | ~5 GB  |\n| Gemma 4 12B Unified (12B) | 24 GB | 10 GB                                                          | ~8 GB  |\n| Gemma 4 26B-A4B (26B MoE) | 32 GB | 16 GB+                                                         | ~15 GB |\n\n\u003e Without sufficient VRAM, llama.cpp will offload layers to system RAM (CPU mode), resulting in significantly slower inference. If you encounter **OOM errors**, try a smaller model or reduce `N_CTX` in `data/system/.env`.\n\n### Installation\n\n#### Prerequisites\n\n- **Python 3.11+** (on Linux/macOS, the `venv` module — `python3-venv` on Ubuntu/Debian)\n- **Node.js 20+**\n- **GPU** with up-to-date drivers — NVIDIA (CUDA), AMD (HIP on Windows, ROCm on Linux) or Apple Silicon (Metal) — recommended; runs on CPU otherwise\n- **Windows 10/11 (64-bit)**, modern Linux, or macOS (arm64/x64)\n- On Linux/macOS: `curl`, `unzip` and `tar`\n\n#### Windows — graphical installer\n\nA signed `.exe` installer (built with [Inno Setup](https://jrsoftware.org/isinfo.php)) is available on the [releases page](https://github.com/xBrasil/myAIplayground/releases). The wizard copies files, creates Start Menu and Desktop shortcuts, and optionally runs the dependency setup at the end.\n\n\u003e **Note:** Python 3.11+ and Node.js 20+ are installed automatically via `winget` when missing. If you chose the per-user install (without running as Administrator), a UAC prompt will appear at that moment to elevate just that step — the rest of the setup keeps running under your user account. Requires `winget` (App Installer) available on Windows; otherwise install Python/Node manually beforehand.\n\n#### Windows — via scripts\n\n```powershell\ninstall.cmd\n```\n\nThe installer:\n\n- Detects and installs Python and Node.js automatically via `winget` (prompting for UAC elevation if needed)\n- Creates the `.venv` virtual environment and installs backend dependencies\n- Installs frontend npm dependencies\n- Downloads the latest `llama-server` binary (CUDA or CPU, according to your GPU)\n- Creates `data/system/.env` from `backend/.env.example`\n\nLaunch with:\n\n```powershell\nrun.cmd\n```\n\n#### Linux / macOS\n\n```bash\nchmod +x install.sh run.sh\n./install.sh\n./run.sh\n```\n\nThe installer performs the same steps as the Windows version: creates `.venv`, installs dependencies, downloads `llama-server` and prepares `.env`. The script auto-detects macOS (arm64/x64) and Linux to pick the correct `llama-server` binary. Press `Ctrl+C` to stop.\n\n#### What the launcher does\n\n- Starts backend (FastAPI on port 8000) and frontend (Vite on port 5173)\n- Waits for both to be ready and opens the UI in your browser\n- Reuses already-running services — safe to run more than once\n- Logs saved to `data/system/logs/backend.log` and `data/system/logs/frontend.log`\n\n\u003e **Tip:** the first use of each model triggers a GGUF download from Hugging Face. Models are cached in `data/system/model-cache/`.\n\n### Privacy\n\n- Conversations are stored in a local SQLite database (`data/user/app.db`).\n- Uploaded files stay in `data/user/uploads/`.\n- App settings (language, voice, custom instructions, allowed folders, etc.) are stored in `data/user/settings.json`.\n- Initial model downloads come from Hugging Face. After that, everything runs offline.\n- **Web search**: when enabled in Settings, the model can query DuckDuckGo and fetch pages. Those requests leave your machine — disable it for fully offline mode.\n- **Local filesystem access**: when enabled, the model can read files **only** from folders you explicitly allowed. Access is read-only and protected against directory traversal.\n- Text-to-Speech uses the browser's `speechSynthesis` API; local vs. online behavior depends on the selected voice and system settings.\n- No analytics or telemetry.\n\n### Key points\n\n- **100% local inference** — all AI processing runs on your hardware via [llama.cpp](https://github.com/ggml-org/llama.cpp) (GGUF format). No data is sent to cloud services during normal chat use.\n- **Gemma 4 models are not included** — they are downloaded from [Hugging Face](https://huggingface.co/) at the user's request and are subject to [Gemma 4 Terms of Use - Apache 2.0](https://ai.google.dev/gemma/apache_2).\n- **Stack**: React 19 + TypeScript + Vite (frontend), FastAPI + SQLAlchemy (backend), llama.cpp server (inference), faster-whisper (speech-to-text).\n- **License**: [Apache License 2.0](LICENSE) — Copyright 2026 Rodolfo Motta Saraiva.\n\n### Third-party components\n\n| Component                                                                 | License                                                                |\n| ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |\n| [llama.cpp](https://github.com/ggml-org/llama.cpp)                           | MIT                                                                    |\n| [FastAPI](https://github.com/tiangolo/fastapi)                               | MIT                                                                    |\n| [Uvicorn](https://github.com/encode/uvicorn)                                 | BSD-3-Clause                                                           |\n| [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy)                       | MIT                                                                    |\n| [Pydantic](https://github.com/pydantic/pydantic)                             | MIT                                                                    |\n| [React](https://github.com/facebook/react)                                   | MIT                                                                    |\n| [Vite](https://github.com/vitejs/vite)                                       | MIT                                                                    |\n| [react-markdown](https://github.com/remarkjs/react-markdown)                 | MIT                                                                    |\n| [KaTeX](https://github.com/KaTeX/KaTeX) (via rehype-katex)                   | MIT                                                                    |\n| [Hugging Face Hub](https://github.com/huggingface/huggingface_hub)           | Apache 2.0                                                             |\n| [faster-whisper](https://github.com/SYSTRAN/faster-whisper)                  | MIT                                                                    |\n| [Pillow](https://github.com/python-pillow/Pillow)                            | HPND                                                                   |\n| [pillow-heif](https://github.com/bigcat88/pillow_heif)                       | BSD-3-Clause                                                           |\n| [PyMuPDF](https://github.com/pymupdf/PyMuPDF)                                | AGPL-3.0                                                               |\n| [python-docx](https://github.com/python-openxml/python-docx)                 | MIT                                                                    |\n| [openpyxl](https://foss.heptapod.net/openpyxl/openpyxl)                      | MIT                                                                    |\n| [python-pptx](https://github.com/scanny/python-pptx)                         | MIT                                                                    |\n| [duckduckgo-search](https://github.com/deedy5/duckduckgo_search)             | MIT                                                                    |\n| [beautifulsoup4](https://www.crummy.com/software/BeautifulSoup/)             | MIT                                                                    |\n| [svglib](https://github.com/deeplook/svglib)                                 | LGPL-3.0                                                               |\n| [reportlab](https://www.reportlab.com/dev/opensource/)                       | BSD-3-Clause                                                           |\n| [pystray](https://github.com/moses-palmer/pystray)                           | LGPL-3.0                                                               |\n| [Inno Setup](https://jrsoftware.org/isinfo.php) (Windows installer)          | [Inno Setup License](https://jrsoftware.org/files/is/license.txt)         |\n| [Google Gemma 4](https://ai.google.dev/gemma) (AI models — not distributed) | [Gemma 4 Terms of Use - Apache 2.0](https://ai.google.dev/gemma/apache_2) |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxbrasil%2Fmyaiplayground","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxbrasil%2Fmyaiplayground","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxbrasil%2Fmyaiplayground/lists"}