Update README.md

README.md

@@ -51,4 +51,78 @@ Para rodar o formato GGUF localmente utilizando apenas o processador, recomendam
 
 ### Instalação
 ```bash
-pip install llama-cpp-python
+pip install llama-cpp-python
+```
+
+
+
+### Exemplo de Código (Python)
+
+```bash
+
+from llama_cpp import Llama
+
+def generate_spatial_query(prompt: str, model_path: str) -> str:
+    """
+    Gera uma consulta PostGIS a partir de linguagem natural utilizando o TerraModel.
+    
+    Args:
+        prompt (str): A pergunta em linguagem natural.
+        model_path (str): O caminho local para o arquivo .gguf.
+        
+    Returns:
+        str: A consulta SQL gerada pelo modelo.
+    """
+    # Instanciação do modelo otimizada para CPU
+    llm = Llama(
+        model_path=model_path,
+        n_ctx=2048,          # Janela de contexto
+        n_threads=8,         # Ajuste para a quantidade de núcleos físicos da sua CPU
+        verbose=False
+    )
+    
+    # System Prompt exato utilizado no fine-tuning do TerraModel
+    system_prompt = """Você é o TerraModel, um especialista em análise geoespacial e PostgreSQL/PostGIS.
+Sua tarefa é traduzir perguntas em linguagem natural para consultas SQL rigorosas e otimizadas.
+
+Você deve basear sua sintaxe ESTRITAMENTE no seguinte esquema de banco de dados:
+CREATE TABLE public.dados_deter (gid integer, fid varchar, classname varchar, quadrant varchar, path_row varchar, view_date date, sensor varchar, satellite varchar, areauckm numeric, uc varchar, areamunkm numeric, municipali varchar, geocodibge varchar, uf varchar, geom geometry);
+Nota: Use unaccent() para buscar textos."""
+
+    # Formatação ChatML requerida pela arquitetura Qwen2.5-Coder
+    formatted_prompt = f"<|im_start|>system\n{system_prompt}<|im_end|>\n<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant\n"
+    
+    # Inferência
+    response = llm(
+        formatted_prompt,
+        max_tokens=256,
+        stop=["<|im_end|>"],
+        temperature=0.1      # Temperatura baixa para garantir determinismo na sintaxe SQL
+    )
+    
+    return response['choices'][0]['text'].strip()
+
+# Exemplo de uso
+if __name__ == "__main__":
+    pergunta = "Calcule a área total em hectares dos polígonos que representam áreas de desmatamento e que estão dentro de um raio de 10 km de um ponto específico."
+    caminho_gguf = "./terramodel-7b-q4_k_m.gguf"
+    
+    sql_gerado = generate_spatial_query(pergunta, caminho_gguf)
+    print("Query Gerada:\n", sql_gerado)
+
+```
+
+
+
+## 📊 Avaliação e Desempenho
+
+O modelo foi submetido a um rigoroso benchmark empírico. A versão TerraModel 7B Q8 atingiu uma Acurácia de Execução de 82,00% no PostGIS, superando APIs comerciais como o GPT-4o-mini em cenários de inferência zero-shot focados no esquema do projeto.
+
+Para aprofundamento metodológico, métricas de taxa de transferência (throughput) e validação semântica sistêmica (RAGAS), consulte o artigo científico vinculado a este projeto.
+
+
+## 🔗 Conjunto de Dados e Reprodutibilidade
+
+O dataset sintético com as 3.000 amostras (pares NL-SQL) utilizadas para a injeção de conhecimento topológico e os scripts de benchmark estão disponíveis no repositório do GitHub:
+
+👉 [Acesse o Repositório](https://github.com/thiagonishimura/terramodel)