https://github.com/ronierisonmaciel/hub-ia
HuB‑IA é uma aplicação interativa desenvolvida com Streamlit e LangChain, capaz de transformar perguntas em linguagem natural em consultas SQL eficientes e interpretá-las com naturalidade. Os dados vêm de uma base SQLite contendo informações econômicas como IPCA, PMS, PMC e transações com cartões.
https://github.com/ronierisonmaciel/hub-ia
ai ollama python3 streamlit
Last synced: about 1 year ago
JSON representation
HuB‑IA é uma aplicação interativa desenvolvida com Streamlit e LangChain, capaz de transformar perguntas em linguagem natural em consultas SQL eficientes e interpretá-las com naturalidade. Os dados vêm de uma base SQLite contendo informações econômicas como IPCA, PMS, PMC e transações com cartões.
- Host: GitHub
- URL: https://github.com/ronierisonmaciel/hub-ia
- Owner: RonierisonMaciel
- Created: 2025-02-18T19:32:37.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-02T18:40:23.000Z (about 1 year ago)
- Last Synced: 2025-06-03T06:45:34.789Z (about 1 year ago)
- Topics: ai, ollama, python3, streamlit
- Language: Python
- Homepage:
- Size: 961 KB
- Stars: 0
- Watchers: 1
- Forks: 10
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# HuB‑IA – Assistente Inteligente para Dados Públicos da Fecomércio
**HuB‑IA** é uma aplicação interativa desenvolvida com **Streamlit** e **LangChain**, capaz de transformar perguntas em linguagem natural em **consultas SQL** eficientes e interpretá-las com naturalidade. Os dados vêm de uma base SQLite contendo informações econômicas como IPCA, PMS, PMC e transações com cartões.
---
## Demonstração
> Pergunte algo como:
> “Qual a inflação acumulada em Recife?”
---
## Funcionalidades
- Interpretação de perguntas com modelo LLM local (`phi4-mini`)
- Geração de queries SQL automáticas (somente leitura)
- Interpretação amigável e responsiva dos resultados
- Correção automática de colunas inválidas via fuzzy match
- Interface natural com efeito de digitação
- Sugestões contextuais baseadas na pergunta
---
## Estrutura do projeto
```plaintext
hub-ia/
│
├── core/ # Lógica de negócio
│ ├── database.py # Conexão e execução SQL
│ ├── engine.py # Orquestra LLM + SQL + validações
│ ├── llm_agent.py # Interação com o modelo LLM
│ ├── prompts.py # Geração de system prompts
│ └── utils.py # Funções auxiliares gerais
│
├── ui/ # Interface e efeitos visuais
│ ├── layout.py # Estilo visual da página
│ └── typing_effect.py # Efeito de digitação da resposta
│
├── config/
│ └── table_aliases.yaml # Descrições das tabelas
│
├── services/ # Serviços auxiliares para execução e logging
│
├── models/ # Modelos de dados ou persistência
│
├── app.py # Interface principal com Streamlit
├── docker-compose.yml # Ambiente dockerizado
└── requirements.txt # Dependências Python
```
---
## Requisitos
* Python 3.10+
* [Ollama](https://ollama.com/) instalado localmente com o modelo `phi4-mini`
* [Streamlit](https://streamlit.io/)
* SQLite
---
## Instalação
```bash
# Clone o projeto
git clone https://github.com/ronierisonmaciel/hub-ia.git
cd hub-ia
# Crie e ative o ambiente virtual
python -m venv .venv
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
# Instale as dependências
pip install -r requirements.txt
```
---
## Executando
```bash
streamlit run app.py
```
---
## Exemplos de perguntas
- Qual foi o IPCA em Recife?
- Qual a bandeira de cartão com mais emissão?
- Qual o volume de serviços no RN?
- Quantas transações foram feitas com crédito?
---
## Base de dados
O banco `fecomdb.db` é composto por múltiplas tabelas extraídas de dados estatísticos públicos.
As descrições legíveis das tabelas estão no arquivo [`config/table_aliases.yaml`](config/table_aliases.yaml).
---
## Segurança
* Todas as queries são somente leitura (proibido `INSERT`, `UPDATE`, `DELETE`).
* A identificação de colunas é validada contra `PRAGMA table_info`.
* SQL Injection é prevenido com checagem de nomes e validação regex.
---
## LLM e prompting
O sistema utiliza o modelo `matilde` via Ollama, com prompts personalizados para:
- Geração de SQL (usando descrições e nomes das tabelas)
- Interpretação humanizada dos resultados
- Adição de contexto semântico à pergunta (ex: IPCA localização)
---
## Histórico e Memória
- O sistema usa cache em memória RAM com `ConversationBufferMemory`
- O histórico não é persistido; ao reiniciar, ele é limpo
---
## Contribuindo
Leia o [CONTRIBUTING.md](CONTRIBUTING.md) antes de começar. Resumo:
1. Fork este repositório
2. Crie sua branch (`git checkout -b feature/minha-funcionalidade`)
3. Commit suas mudanças (`git commit -am 'feat: adiciona nova feature'`)
4. Push para a branch (`git push origin feature/minha-funcionalidade`)
5. Crie um Pull Request
---
## Licença
Este projeto é licenciado sob os termos da [MIT License](LICENSE).
---
## Responsável
- Ronierison Maciel