Add application file

.gitignore

@@ -0,0 +1,4 @@
+*.gguf
+models/*
+__pycache__/
+.env

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.9
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,60 @@
 ---
-title: Llm Agent Api
-emoji: 🌍
+title: LLM Agent API
+emoji: 🧠
 colorFrom: blue
-colorTo: gray
+colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
 license: mit
+hardware: cpu-upgrade
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧠 LLM Agent API
+
+API REST com modelo Llama 2 7B rodando localmente usando llama-cpp-python.
+
+## Endpoints
+
+### POST /chat
+Envia mensagem para o agente LLM.
+
+**Request:**
+```json
+{
+  "message": "Olá, como você está?",
+  "max_tokens": 100,
+  "temperature": 0.7
+}
+```
+
+**Response:**
+```json
+{
+  "response": "Olá! Estou bem, obrigado por perguntar. Como posso ajudá-lo hoje?"
+}
+```
+
+### GET /health
+Verifica status da API.
+
+**Response:**
+```json
+{
+  "status": "healthy"
+}
+```
+
+## Como usar
+
+```bash
+curl -X POST "http://localhost:7860/chat" \
+     -H "Content-Type: application/json" \
+     -d '{"message": "Olá!"}'
+```
+
+## Tecnologias
+
+- FastAPI
+- llama-cpp-python
+- Uvicorn

app.py

@@ -0,0 +1,74 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+from llama_cpp import Llama
+from huggingface_hub import hf_hub_download
+import os
+
+app = FastAPI(title="LLM Agent API", version="1.0.0")
+
+class ChatRequest(BaseModel):
+    message: str
+    max_tokens: int = 100
+    temperature: float = 0.7
+
+class ChatResponse(BaseModel):
+    response: str
+
+class LocalLLMAgent:
+    def __init__(self):
+        # Download do modelo se não existir
+        model_path = "./llama-2-7b-chat.Q4_K_M.gguf"
+        
+        if not os.path.exists(model_path):
+            print("Baixando modelo...")
+            model_path = hf_hub_download(
+                repo_id="TheBloke/Llama-2-7B-Chat-GGUF",
+                filename="llama-2-7b-chat.Q4_K_M.gguf",
+                local_dir="./"
+            )
+            print("Modelo baixado com sucesso!")
+        
+        self.llm = Llama(
+            model_path=model_path,
+            chat_format="llama-2",
+            n_ctx=2048,
+            verbose=False
+        )
+        self.messages = [
+            {"role": "system", "content": "Responda sempre em português brasileiro de forma natural e conversacional."}
+        ]
+    
+    def chat(self, message: str, max_tokens: int = 100, temperature: float = 0.7) -> str:
+        self.messages.append({"role": "user", "content": message})
+        
+        response = self.llm.create_chat_completion(
+            messages=self.messages,
+            max_tokens=max_tokens,
+            temperature=temperature
+        )
+        
+        assistant_message = response['choices'][0]['message']['content']
+        self.messages.append({"role": "assistant", "content": assistant_message})
+        
+        return assistant_message
+
+# Inicializa o agente globalmente
+agent = None
+
+@app.on_event("startup")
+async def startup_event():
+    global agent
+    agent = LocalLLMAgent()
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat_endpoint(request: ChatRequest):
+    if agent is None:
+        return ChatResponse(response="Modelo ainda carregando, tente novamente.")
+    response = agent.chat(request.message, request.max_tokens, request.temperature)
+    return ChatResponse(response=response)
+
+@app.get("/health")
+async def health_check():
+    return {"status": "healthy"}
+
+# Removido - uvicorn será executado pelo Dockerfile

docs/application.md

@@ -0,0 +1,78 @@
+# 🧠 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
+
+---

docs/oficial_docs.txt

@@ -0,0 +1,3 @@
+llama-cpp-python: https://github.com/abetlen/llama-cpp-python
+Modelo TinyLlama GGUF (TheBloke): https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF
+Integração LangChain com LlamaCpp: https://python.langchain.com/docs/integrations/llms/llamacpp/

main.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Aplicação Local para LLMs voltados para Agentes
+Roda modelos GGUF localmente usando llama-cpp-python
+"""
+
+from llama_cpp import Llama
+import os
+import sys
+
+# Força encoding UTF-8
+if sys.stdout.encoding != 'utf-8':
+    sys.stdout.reconfigure(encoding='utf-8')
+if sys.stdin.encoding != 'utf-8':
+    sys.stdin.reconfigure(encoding='utf-8')
+
+class LocalLLMAgent:
+    def __init__(self, n_ctx: int = 2048):
+        """
+        Inicializa o agente LLM local
+        
+        Args:
+            n_ctx: Tamanho do contexto (tokens)
+        """
+        #llama-2-7b.Q2_K.gguf
+        model_path = "./models/llama-2-7b-chat.Q4_K_M.gguf"
+        print(f"Carregando modelo: {model_path}")
+        self.llm = Llama(
+            model_path=model_path,
+            chat_format="llama-2",
+            verbose=False
+        )
+        print("Modelo carregado com sucesso!")
+        # Inicializa com prompt do sistema em português
+        self.messages = [
+            {"role": "system", "content": "Responda sempre em português brasileiro de forma natural e conversacional."}
+        ]
+    
+    def chat(self, user_message: str, max_tokens: int = 100, temperature: float = 0.7) -> str:
+        """
+        Gera resposta usando o formato de chat nativo
+        
+        Args:
+            user_message: Mensagem do usuário
+            max_tokens: Máximo de tokens na resposta
+            temperature: Controle de criatividade (0.0 a 1.0)
+            
+        Returns:
+            Resposta do modelo
+        """
+        # Adiciona mensagem do usuário
+        self.messages.append({"role": "user", "content": user_message})
+        
+        # Gera resposta usando create_chat_completion conforme documentação
+        response = self.llm.create_chat_completion(
+            messages=self.messages,
+            max_tokens=max_tokens,
+            temperature=0.75
+        )
+        
+        assistant_message = response['choices'][0]['message']['content']
+        
+        # Adiciona resposta do assistente ao histórico
+        self.messages.append({"role": "assistant", "content": assistant_message})
+        
+        return assistant_message
+
+def main():
+    """Função principal - interface de terminal"""
+    
+    print("🧠 Aplicação Local para LLMs Agentes")
+    print("=" * 40)
+    
+    try:
+        agent = LocalLLMAgent()
+        
+        print("\n🧠 Agente LLM Local iniciado!")
+        print("Digite 'sair' para encerrar\n")
+        
+        while True:
+            try:
+                user_input = input("Você: ").strip()
+            except UnicodeDecodeError:
+                user_input = input("Voce: ").strip()
+            
+            if user_input.lower() in ['sair', 'exit', 'quit']:
+                print("Encerrando...")
+                break
+            
+            if not user_input:
+                continue
+            
+            print("Agente: ", end="", flush=True)
+            response = agent.chat(user_input)
+            print(response)
+            print()
+            
+    except Exception as e:
+        import traceback
+        print(f"Erro: {e}")
+        print("Detalhes do erro:")
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,5 @@
+llama-cpp-python
+huggingface-hub
+fastapi
+uvicorn
+pydantic