text-to-insight 0.1.0__tar.gz

text_to_insight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026  Caio Petroncini and TextToInsight contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

text_to_insight-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: text-to-insight
+Version: 0.1.0
+Summary: Agentes LangGraph que transformam perguntas em linguagem natural em consultas SQL seguras, executadas no seu banco, com resposta em linguagem natural
+Author: Caio Petroncini, Julio Cesar Fuganti, Luiz Correia dos Santos, Antonio Carvalho, Bernardo Rubio, Jonas Honorato
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gruporaia/TextToInsight
+Project-URL: Documentation, https://github.com/gruporaia/TextToInsight#readme
+Project-URL: Repository, https://github.com/gruporaia/TextToInsight.git
+Project-URL: Bug Tracker, https://github.com/gruporaia/TextToInsight/issues
+Keywords: text-to-sql,nl2sql,llm,langgraph,rag,sql,agentes
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langgraph>=1.1
+Requires-Dist: langchain>=1.2
+Requires-Dist: langchain-core>=1.2
+Requires-Dist: langchain-google-genai>=4.2
+Requires-Dist: langchain-openai>=1.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: matplotlib>=3.9.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: chromadb>=1.5.9
+Requires-Dist: tabulate>=0.10.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: platformdirs>=3.0
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1.0; extra == "mysql"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-recording>=0.13.0; extra == "dev"
+Requires-Dist: aiohttp<3.10.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=5.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
+Dynamic: license-file
+
+# Text-to-Insight
+
+Biblioteca Python que transforma perguntas em linguagem natural em consultas SQL seguras, executadas no seu banco, com resposta final em linguagem natural (e gráfico, quando fizer sentido).
+
+O fluxo é um grafo de agentes em [LangGraph](https://github.com/langchain-ai/langgraph): lê o schema do banco, seleciona as tabelas relevantes (GraphRAG), calcula estatísticas das colunas, gera a SQL, executa em modo somente leitura, corrige a si mesmo em caso de erro e responde. Opcionalmente pausa para pedir esclarecimentos ao usuário (human-in-the-loop).
+
+## Instalação
+
+```bash
+pip install text-to-insight
+```
+
+SQLite funciona sem nada extra. Para PostgreSQL ou MySQL, instale o driver junto:
+
+```bash
+pip install "text-to-insight[postgres]"   # psycopg2
+pip install "text-to-insight[mysql]"      # pymysql
+```
+
+Modelos suportados: Gemini (`GOOGLE_API_KEY`) e OpenAI (`OPENAI_API_KEY`).
+
+## Uso como biblioteca
+
+A biblioteca **não abre conexões com o banco**. Você cria uma [Engine do SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/engines.html), passa para a `InsightEngine` e continua sendo dono dela (pool, credenciais, `dispose()`). A engine nunca entra no estado do grafo, então nada sobre a conexão vai para o checkpoint do LangGraph.
+
+```python
+from sqlalchemy import create_engine
+from text_to_insight import InsightEngine
+
+# SQLite em modo somente leitura
+db = create_engine("sqlite:///file:dados/loja.db?mode=ro&uri=true")
+# PostgreSQL: create_engine("postgresql+psycopg2://usuario:senha@host:5432/banco")
+
+engine = InsightEngine(
+    api_key="...",
+    model="gemini-2.5-flash",      # ou "gpt-5-mini", "openai/gpt-4o", ...
+    db_engine=db,
+    hitl=True,
+)
+
+resultado = engine.run(thread_id="sessao_1", query="Quantos pedidos existem no banco?")
+
+if resultado.get("status") == "AWAITING_USER":
+    print(resultado["message"])  # pergunta do agente para o usuário
+    resultado = engine.resume(thread_id="sessao_1", user_response="Considere só pedidos entregues.")
+
+print(resultado["sql_gerada"])
+print(resultado["resposta_natural"])
+
+db.dispose()
+```
+
+Toda SQL gerada passa por uma validação (apenas `SELECT`/`WITH`, uma única instrução, sem comandos de escrita ou de leitura de arquivos) e roda com timeout. Mesmo assim, use um usuário de banco com permissão só de leitura.
+
+### Opções da `InsightEngine`
+
+| Parâmetro | Padrão | O que faz |
+|---|---|---|
+| `db_engine` | obrigatório | Engine do SQLAlchemy do banco a consultar. |
+| `hitl` | `False` | Permite que o agente pause e peça esclarecimentos (`AWAITING_USER`). |
+| `use_rag` | `True` | Seleciona só as tabelas relevantes quando o schema é grande (GraphRAG). |
+| `enrich_rag` | `False` | Gera, com o LLM, descrições curtas das colunas antes do RAG. O resultado fica em cache. |
+| `use_data_exploration` | `True` | Inclui estatísticas das colunas no prompt (SQLite e PostgreSQL; outros bancos pulam esta etapa). |
+| `use_exploration_selector` | `"off"` | Escolhe quais colunas explorar: `"off"`, `"llm"` ou `"rag"`. |
+| `use_cot` | `True` | Pede raciocínio passo a passo antes da SQL. |
+| `inferir_fks_virtuais` | `False` | Infere chaves estrangeiras por nome (`*_id`) quando o banco não as declara. |
+| `enable_graphs` | `True` | Gera um gráfico (matplotlib) quando a visualização for útil. |
+| `model_kwargs` | `None` | Parâmetros do LLM, ex.: `{"temperature": 0}`. |
+| `cache_dir` | pasta de cache do usuário | Onde ficam o schema enriquecido e o índice do ChromaDB. |
+
+Por padrão o cache fica em `~/.cache/text-to-insight` (Linux), `~/Library/Caches/text-to-insight` (macOS) ou `%LOCALAPPDATA%\text-to-insight\Cache` (Windows). O schema enriquecido é indexado pelo conteúdo do schema: se o banco mudar, ele é gerado de novo.
+
+### Resultado
+
+`run` e `resume` devolvem o estado final do grafo. Os campos mais úteis:
+
+- `status`: `"aprovado"`, `"exec_erro"`, `"AWAITING_USER"` ou `"bloqueado_hitl"`;
+- `sql_gerada`, `linhas_resultado_completo`, `total_linhas_resultado`;
+- `resposta_natural`: resposta em linguagem natural;
+- `caminho_csv_resultado`, `caminho_grafico`: caminhos do CSV com o resultado completo e do gráfico, quando gerado;
+- `tokens_input`, `tokens_output`, `tokens_total`, `tokens_by_node`: uso de tokens.
+
+API pública: `text_to_insight.InsightEngine`, `text_to_insight.Graph`, `text_to_insight.EstadoTextToInsight`.
+
+## Uso via linha de comando
+
+```bash
+export GOOGLE_API_KEY=...
+
+# arquivo SQLite (aberto somente leitura)
+text-to-insight --db-path dados/loja.db --model gemini-2.5-flash --api-key-env GOOGLE_API_KEY \
+    "Quais categorias vendem mais?"
+
+# qualquer banco via URL (também lida de DATABASE_URL)
+text-to-insight --db-url postgresql://usuario:senha@host:5432/banco --hitl off \
+    "Qual o ticket médio por estado?"
+```
+
+`text-to-insight --help` lista as demais opções (`--hitl`, `--enrich-rag`, `--infer-fks`, `--cot`, `--data-exploration`, `--exploration-selector`, `--temperature`, `--max-tokens`).
+
+## Desenvolvimento
+
+- [Guia de desenvolvimento e testes](https://github.com/gruporaia/TextToInsight/blob/main/docs/DESENVOLVIMENTO.md)
+- [Arquitetura](https://github.com/gruporaia/TextToInsight/blob/main/docs/ARQUITETURA.md)
+- Benchmarks: [BIRD](https://github.com/gruporaia/TextToInsight/blob/main/docs/BENCHMARK_BIRD.md), [Spider 1.0 e 2.0](https://github.com/gruporaia/TextToInsight/blob/main/docs/BENCHMARK_SPIDER.md)
+
+Desenvolvido pelo grupo RAIA (USP). Licença MIT.

text_to_insight-0.1.0/README.md

@@ -0,0 +1,107 @@
+# Text-to-Insight
+
+Biblioteca Python que transforma perguntas em linguagem natural em consultas SQL seguras, executadas no seu banco, com resposta final em linguagem natural (e gráfico, quando fizer sentido).
+
+O fluxo é um grafo de agentes em [LangGraph](https://github.com/langchain-ai/langgraph): lê o schema do banco, seleciona as tabelas relevantes (GraphRAG), calcula estatísticas das colunas, gera a SQL, executa em modo somente leitura, corrige a si mesmo em caso de erro e responde. Opcionalmente pausa para pedir esclarecimentos ao usuário (human-in-the-loop).
+
+## Instalação
+
+```bash
+pip install text-to-insight
+```
+
+SQLite funciona sem nada extra. Para PostgreSQL ou MySQL, instale o driver junto:
+
+```bash
+pip install "text-to-insight[postgres]"   # psycopg2
+pip install "text-to-insight[mysql]"      # pymysql
+```
+
+Modelos suportados: Gemini (`GOOGLE_API_KEY`) e OpenAI (`OPENAI_API_KEY`).
+
+## Uso como biblioteca
+
+A biblioteca **não abre conexões com o banco**. Você cria uma [Engine do SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/engines.html), passa para a `InsightEngine` e continua sendo dono dela (pool, credenciais, `dispose()`). A engine nunca entra no estado do grafo, então nada sobre a conexão vai para o checkpoint do LangGraph.
+
+```python
+from sqlalchemy import create_engine
+from text_to_insight import InsightEngine
+
+# SQLite em modo somente leitura
+db = create_engine("sqlite:///file:dados/loja.db?mode=ro&uri=true")
+# PostgreSQL: create_engine("postgresql+psycopg2://usuario:senha@host:5432/banco")
+
+engine = InsightEngine(
+    api_key="...",
+    model="gemini-2.5-flash",      # ou "gpt-5-mini", "openai/gpt-4o", ...
+    db_engine=db,
+    hitl=True,
+)
+
+resultado = engine.run(thread_id="sessao_1", query="Quantos pedidos existem no banco?")
+
+if resultado.get("status") == "AWAITING_USER":
+    print(resultado["message"])  # pergunta do agente para o usuário
+    resultado = engine.resume(thread_id="sessao_1", user_response="Considere só pedidos entregues.")
+
+print(resultado["sql_gerada"])
+print(resultado["resposta_natural"])
+
+db.dispose()
+```
+
+Toda SQL gerada passa por uma validação (apenas `SELECT`/`WITH`, uma única instrução, sem comandos de escrita ou de leitura de arquivos) e roda com timeout. Mesmo assim, use um usuário de banco com permissão só de leitura.
+
+### Opções da `InsightEngine`
+
+| Parâmetro | Padrão | O que faz |
+|---|---|---|
+| `db_engine` | obrigatório | Engine do SQLAlchemy do banco a consultar. |
+| `hitl` | `False` | Permite que o agente pause e peça esclarecimentos (`AWAITING_USER`). |
+| `use_rag` | `True` | Seleciona só as tabelas relevantes quando o schema é grande (GraphRAG). |
+| `enrich_rag` | `False` | Gera, com o LLM, descrições curtas das colunas antes do RAG. O resultado fica em cache. |
+| `use_data_exploration` | `True` | Inclui estatísticas das colunas no prompt (SQLite e PostgreSQL; outros bancos pulam esta etapa). |
+| `use_exploration_selector` | `"off"` | Escolhe quais colunas explorar: `"off"`, `"llm"` ou `"rag"`. |
+| `use_cot` | `True` | Pede raciocínio passo a passo antes da SQL. |
+| `inferir_fks_virtuais` | `False` | Infere chaves estrangeiras por nome (`*_id`) quando o banco não as declara. |
+| `enable_graphs` | `True` | Gera um gráfico (matplotlib) quando a visualização for útil. |
+| `model_kwargs` | `None` | Parâmetros do LLM, ex.: `{"temperature": 0}`. |
+| `cache_dir` | pasta de cache do usuário | Onde ficam o schema enriquecido e o índice do ChromaDB. |
+
+Por padrão o cache fica em `~/.cache/text-to-insight` (Linux), `~/Library/Caches/text-to-insight` (macOS) ou `%LOCALAPPDATA%\text-to-insight\Cache` (Windows). O schema enriquecido é indexado pelo conteúdo do schema: se o banco mudar, ele é gerado de novo.
+
+### Resultado
+
+`run` e `resume` devolvem o estado final do grafo. Os campos mais úteis:
+
+- `status`: `"aprovado"`, `"exec_erro"`, `"AWAITING_USER"` ou `"bloqueado_hitl"`;
+- `sql_gerada`, `linhas_resultado_completo`, `total_linhas_resultado`;
+- `resposta_natural`: resposta em linguagem natural;
+- `caminho_csv_resultado`, `caminho_grafico`: caminhos do CSV com o resultado completo e do gráfico, quando gerado;
+- `tokens_input`, `tokens_output`, `tokens_total`, `tokens_by_node`: uso de tokens.
+
+API pública: `text_to_insight.InsightEngine`, `text_to_insight.Graph`, `text_to_insight.EstadoTextToInsight`.
+
+## Uso via linha de comando
+
+```bash
+export GOOGLE_API_KEY=...
+
+# arquivo SQLite (aberto somente leitura)
+text-to-insight --db-path dados/loja.db --model gemini-2.5-flash --api-key-env GOOGLE_API_KEY \
+    "Quais categorias vendem mais?"
+
+# qualquer banco via URL (também lida de DATABASE_URL)
+text-to-insight --db-url postgresql://usuario:senha@host:5432/banco --hitl off \
+    "Qual o ticket médio por estado?"
+```
+
+`text-to-insight --help` lista as demais opções (`--hitl`, `--enrich-rag`, `--infer-fks`, `--cot`, `--data-exploration`, `--exploration-selector`, `--temperature`, `--max-tokens`).
+
+## Desenvolvimento
+
+- [Guia de desenvolvimento e testes](https://github.com/gruporaia/TextToInsight/blob/main/docs/DESENVOLVIMENTO.md)
+- [Arquitetura](https://github.com/gruporaia/TextToInsight/blob/main/docs/ARQUITETURA.md)
+- Benchmarks: [BIRD](https://github.com/gruporaia/TextToInsight/blob/main/docs/BENCHMARK_BIRD.md), [Spider 1.0 e 2.0](https://github.com/gruporaia/TextToInsight/blob/main/docs/BENCHMARK_SPIDER.md)
+
+Desenvolvido pelo grupo RAIA (USP). Licença MIT.

text_to_insight-0.1.0/pyproject.toml

@@ -0,0 +1,102 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "text-to-insight"
+version = "0.1.0"
+description = "Agentes LangGraph que transformam perguntas em linguagem natural em consultas SQL seguras, executadas no seu banco, com resposta em linguagem natural"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Caio Petroncini"},
+    {name = "Julio Cesar Fuganti"},
+    {name = "Luiz Correia dos Santos"},
+    {name = "Antonio Carvalho"},
+    {name = "Bernardo Rubio"},
+    {name = "Jonas Honorato"},
+]
+keywords = ["text-to-sql", "nl2sql", "llm", "langgraph", "rag", "sql", "agentes"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "langgraph>=1.1",
+    "langchain>=1.2",
+    "langchain-core>=1.2",
+    "langchain-google-genai>=4.2",
+    "langchain-openai>=1.1",
+    "pydantic>=2.0",
+    "python-dotenv>=1.0.0",
+    "pandas>=2.2.2",  # uso na geração de gráficos e análise de dados; 2.2.2 é a primeira compatível com numpy 2
+    "matplotlib>=3.9.0", # uso na geração de gráficos e visualizações; 3.9 é a primeira compatível com numpy 2
+    "networkx>=3.0",
+    "chromadb>=1.5.9",
+    "tabulate>=0.10.0",
+    "sqlalchemy>=2.0.0",
+    "platformdirs>=3.0",
+]
+
+[project.scripts]
+text-to-insight = "text_to_insight.cli:main"
+
+[project.optional-dependencies]
+# Drivers de banco: a biblioteca recebe uma Engine do SQLAlchemy pronta, então
+# só precisa do driver de quem for usar PostgreSQL/MySQL (SQLite já vem no Python).
+postgres = ["psycopg2-binary>=2.9.0"]
+mysql = ["pymysql>=1.1.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "pytest-recording>=0.13.0",
+    "aiohttp<3.10.0",
+    "pytest-timeout>=2.3.0",
+    "black>=23.0",
+    "isort>=5.12",
+    "flake8>=6.0",
+    "mypy>=1.0",
+]
+docs = [
+    "sphinx>=5.0",
+    "sphinx-rtd-theme>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/gruporaia/TextToInsight"
+Documentation = "https://github.com/gruporaia/TextToInsight#readme"
+Repository = "https://github.com/gruporaia/TextToInsight.git"
+"Bug Tracker" = "https://github.com/gruporaia/TextToInsight/issues"
+
+# Só a biblioteca vai para o PyPI; scripts/, src/ (benchmarks) e tests/ ficam fora do wheel.
+[tool.setuptools.packages.find]
+include = ["text_to_insight*"]
+
+[tool.black]
+line-length = 88
+target-version = ['py310', 'py311', 'py312']
+
+[tool.isort]
+profile = "black"
+line_length = 88
+skip_gitignore = true
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+markers = [
+    "real_api: testes que executam chamadas reais ao provedor/modelo LLM",
+]

text_to_insight-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+