docs/application.md

# 🧠 Projeto: Aplicação Local para Rodar LLMs voltados para Agentes (CPU-Friendly)

## 🎯 Objetivo

Desenvolver uma aplicação **simples, leve e de fácil entendimento**, capaz de rodar **modelos LLM localmente em CPU**, utilizando tecnologias como [`llama.cpp`](https://github.com/ggml-org/llama.cpp) e formatos como `GGUF`.

A aplicação será usada com **modelos ajustados para criação de agentes**, ou seja, com suporte a:

- Diálogo multi-turno
- Seguir instruções
- Raciocínio estruturado
- Suporte futuro ao uso de ferramentas (LangChain tools)

O foco inicial é **testar o modelo localmente**, sem deploy ainda.

---

## ✅ Requisitos

- Rodar **100% em CPU**, compatível com Hugging Face Spaces (Free Tier)
- Usar **modelos em formato GGUF**, leves, voltados para agentes
- Usar **llama-cpp-python** (binding oficial Python para llama.cpp)
- Código em Python, com estrutura clara, comentado e expansível
- Interface simples via terminal ou função Python

---

## 🧠 Modelos recomendados (GGUF)

Modelos ajustados para **conversação com agentes**:

| Modelo                | Tamanho | Destaques                     |
| --------------------- | ------- | ----------------------------- |
| OpenHermes 2.5 GGUF   | 7B      | Muito bom com LangChain       |
| Nous Hermes 2 Mistral | 7B      | Fortemente instruído          |
| TinyLlama Chat GGUF   | 1.1B    | Super leve, roda fácil em CPU |
| Zephyr 7B Beta GGUF   | 7B      | Instrução + estilo de chat    |
| OpenChat 3.5 GGUF     | 7B      | Excelente para agentes        |

---

## 🔧 Tecnologias a utilizar

- [llama.cpp](https://github.com/ggml-org/llama.cpp)
- [llama-cpp-python](https://github.com/abetlen/llama-cpp-python)
- Python 3.10+
- Modelo `.gguf` (baixado localmente)

---

## 🛑 Fora do escopo neste momento

- Deploy na nuvem (ex: Hugging Face Spaces)
- API REST / Chat API
- Integração com LangChain

Essas partes virão nas próximas fases do projeto.

---

## ✅ Output esperado nesta fase

- Aplicação local funcional
- Capaz de carregar e rodar um modelo `.gguf` leve
- Permitir conversas básicas (ex: terminal)
- Código simples, modular e pronto para expansão

---

## 📦 Próximo passo sugerido

Criar:

- `main.py` com execução local do modelo
- `requirements.txt`
- Documentação explicando como rodar

---