Lokasi ngalangkungan proxy:   [ UP ]  
[Ngawartoskeun bug]   [Panyetelan cookie]                
Skip to content

mpraes/exegese360

BranchesTags

Repository files navigation

Exegese360 - Sistema de Exegese Bíblica

Um sistema de IA baseado em LangGraph para análise bíblica gramatical-histórica usando a tradição hermenêutica Reformada.

Funcionalidades

  • Método Gramatical-Histórico: Guiado pela hermenêutica Reformada com questionamento socrático
  • Workflow LangGraph: Workflow cíclico de IA com progressão baseada em fases
  • Integração Groq: Alimentado pelo Llama-3 70B para diálogo teológico
  • Pesquisa Tavily: Pesquisa externa com filtragem de domínios
  • Concordância de Strong: Análise lexical integrada
  • Persistência Redis: Gerenciamento de estado de sessão com checkpointing

Arquitetura

┌─────────────────────────────────────────────────────────┐
│                    Sistema Exegese360                    │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Fase 1: Diálogo Socrático (Estudo Interno)             │
│  ├─ SocraticAgent (Groq/Llama-3)                       │
│  ├─ Loop Reflexivo (Verificação de Consistência Temática)│
│  └─ Desenvolvimento de Rascunho do Usuário               │
│                                                          │
│  Fases 2 & 3: Pesquisa Externa                           │
│  ├─ ResearchAgent (Busca Tavily)                        │
│  ├─ Análise Lexical (DB Strong)                         │
│  └─ Detecção de Conflitos                                 │
│                                                          │
│  Fases Futuras:                                          │
│  ├─ Síntese de Comentários                              │
│  ├─ Teologia Sistemática                                │
│  └─ Alinhamento Confessional                            │
│                                                          │
└─────────────────────────────────────────────────────────┘

Início Rápido

Pré-requisitos

Instalar uv (se ainda não estiver instalado)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Verificar instalação
uv --version

1. Clonar e Configurar

git clone <url-do-repositorio>
cd exegese360

# Copiar arquivo de ambiente
cp .env.example .env

# Editar .env com suas chaves de API
nano .env

2. Iniciar Infraestrutura

# Iniciar PostgreSQL e Redis
make docker-up

# Ou manualmente:
docker-compose up -d postgres redis

# Aguardar 5 segundos para os serviços iniciarem
sleep 5

# Inicializar banco de dados
make init-db

# Ou manualmente:
uv run alembic upgrade head

3. Instalar Dependências (Desenvolvimento Local)

Usando uv (recomendado - 10-100x mais rápido que pip):

# Usando make (recomendado)
make install

# Ou manualmente:
uv sync

Alternativa usando pip:

python -m venv .venv
source .venv/bin/activate  # No Windows: .venv\Scripts\activate
pip install -e ".[dev]"

4. Popular com Dados da Bíblia

# Usando make (recomendado)
make seed

# Ou manualmente para versões específicas
uv run python scripts/seed_verses.py
uv run python scripts/seed_lexicon.py

# Para dados em português (requer clonar data/biblia_pt/)
make seed-pt

5. Iniciar Sessão de Estudo

# CLI em português (principal)
uv run python -m src.cli.main_pt session

# Ou consulta direta
uv run python -m src.cli.main_pt consultar "João 3:16"

# CLI em inglês (alternativa)
uv run python -m src.cli study "John 3:16"

Comandos CLI

# Usando uv run (recomendado - auto-detecta venv)

# Inicializar banco de dados
uv run python -m src.cli.main_pt init

# Consultar versículo
uv run python -m src.cli.main_pt consultar "João 3:16"

# Consultar com contexto
uv run python -m src.cli.main_pt consultar "João 3:16" --contexto 3

# Comparar traduções
uv run python -m src.cli.main_pt consultar "João 3:16" --comparar

# Com insights de IA (requer GROQ_API_KEY)
uv run python -m src.cli.main_pt consultar "João 3:16" --comparar --insights

# Buscar termos
uv run python -m src.cli.main_pt buscar "graça" --livro João --limite 10

# Estatísticas
uv run python -m src.cli.main_pt stats

# Sessão interativa
uv run python -m src.cli.main_pt session

# Ou ativar venv primeiro
source .venv/bin/activate
python -m src.cli.main_pt consultar "João 3:16"

Comandos Make Disponíveis

# Desenvolvimento
make install          # Instalar dependências com uv
make docker-up        # Iniciar PostgreSQL e Redis
make docker-down      # Parar containers
make init-db          # Executar migrações do banco
make seed             # Popular com dados da Bíblia
make seed-pt          # Popular com Bíblia em português

# CLI
make pt-consultar     # Consulta interativa de versículos
make pt-session       # Sessão de estudo interativa

# Qualidade de Código
make lint             # Executar ruff (mypy desabilitado)
make format           # Formatar com black e ruff
make fix-permissions  # Corrigir permissões do .venv

# Testes
make test             # Executar todos os testes
make test-unit        # Testes unitários (exclui integração)
make test-integration # Testes de integração

# Status
make status           # Ver status dos containers Docker

Estrutura do Projeto

exegese360/
├── docker-compose.yml          # Configuração de infraestrutura
├── Dockerfile.dev              # Container Python de desenvolvimento
├── pyproject.toml              # Dependências Python (PEP 621)
├── uv.lock                     # Lock file do uv
├── .env.example                # Template de ambiente
├── init.sql                    # Inicialização do PostgreSQL
├── Makefile                    # Comandos úteis
├── alembic/                    # Migrações do banco de dados
├── alembic.ini                 # Configuração do Alembic
├── data/                       # Dados bíblicos
├── scripts/                    # Scripts auxiliares
├── src/
│   ├── __init__.py
│   ├── __main__.py             # Ponto de entrada do módulo
│   ├── models/
│   │   ├── database.py         # Configuração SQLAlchemy
│   │   ├── verse.py            # Modelo de Versículo
│   │   ├── verse_pt.py         # Modelo de Versículo PT
│   │   └── lexicon.py          # Modelo de Léxico
│   ├── agents/
│   │   ├── state.py            # Estado do LangGraph
│   │   ├── boundary_analyzer.py # Analisador de delimitação
│   │   ├── boundary_formatter.py # Formatador de análise
│   │   ├── socratic_agent.py   # Agente da Fase 1
│   │   └── research_agent.py   # Agente das Fases 2 & 3
│   ├── etl/
│   │   ├── base.py             # Classe base ETL
│   │   ├── hebrew_etl.py       # ETL Bíblia Hebraica
│   │   ├── greek_etl.py        # ETL NT Grego
│   │   └── stepbible_etl.py    # ETL Step Bible
│   ├── core/
│   │   ├── query_engine.py     # Motor de consulta bíblica
│   │   ├── state_manager.py    # Gerenciador de estado Redis
│   │   └── translation_analyzer.py # Analisador de traduções
│   ├── cli/
│   │   ├── main.py             # CLI em inglês
│   │   ├── main_pt.py          # CLI em português (principal)
│   │   └── study_session.py    # UI interativa
│   └── utils/
│       └── parsers.py          # Parsing de referências
└── tests/                      # Testes automatizados

Analisador de Delimitação de Passagens

Sistema que executa antes da análise LLM de traduções para verificar a hermenêutica da delimitação:

  • Score 1-5: Avalia se a passagem respeita unidades literárias
  • Identifica problemas: Corta unidade, contexto insuficiente, quebra paralelismos
  • Sugere melhorias: Propor nova referência quando necessário
  • Gatekeeper: Bloqueia análise se delimitação for inadequada (score < 3)

Uso automático quando --insights é usado com --comparar:

# Executa análise de delimitação (Etapa 1) antes da análise LLM (Etapa 2)
uv run python -m src.cli.main_pt consultar "João 3:16-18" --comparar --insights

Roadmap de Desenvolvimento

Sprint 1: Infraestrutura & Ingestão de Dados ✅

  • Docker Compose com PostgreSQL (pgvector), Redis, container Python dev
  • Modelos SQLAlchemy para Versículos e Léxico
  • Scripts ETL para Grego NT e Hebraico OT
  • Ponto de entrada CLI para consultas de versículos

Sprint 2: Agente Socrático & Gerenciamento de Estado ✅

  • Estado LangGraph com persistência Redis
  • SocraticAgent com Groq (Llama-3)
  • Loop Reflexivo para consistência temática
  • UI de Terminal com rich formatting

Sprint 3: Integração de Pesquisa Externa ✅

  • Ferramenta de Busca Tavily com filtragem de domínios
  • ResearchAgent para notas de estudo e léxico
  • Lógica de Detecção de Conflitos
  • Enriquecimento Lexical do DB local

Sprint 4: Comentários Avançados & Teologia Sistemática (Planejado)

  • Nó TheologicalAnalyst
  • Nó SystematicDialogue
  • Pontos de aprovação human-in-the-loop

Sprint 5: API Backend & Frontend (Planejado)

  • Backend FastAPI com WebSocket
  • Dashboard Streamlit
  • Exportação Markdown
  • Cache Redis para Tavily

Princípios da Hermenêutica Reformada

Este sistema segue o método hermenêutico clássico Reformado:

  1. Sola Scriptura: Escritura como autoridade suprema
  2. Princípio Gramatical: Atenção cuidadosa às palavras e gramática
  3. Princípio Histórico: Entendimento contextual
  4. Princípio Cristocêntrico: As Escrituras apontam para Cristo
  5. Analogia Scripturae: A Escritura interpreta a Escritura

Variáveis de Ambiente

Variável Descrição Obrigatória
GROQ_API_KEY Chave de API Groq para LLM Sim
TAVILY_API_KEY Chave de API Tavily para busca Sim
DATABASE_URL String de conexão PostgreSQL Não (padrão fornecido)
REDIS_URL String de conexão Redis Não (padrão fornecido)
RESEARCH_DOMAINS Lista de domínios separados por vírgula Não
LANGGRAPH_CHECKPOINT_REDIS Usar Redis para checkpointing Não

Fontes de Dados

  • Hebraico AT: Open Scriptures Hebrew Bible (OSHB)
  • Grego NT: Society of Biblical Literature Greek New Testament (SBLGNT)
  • Concordância de Strong: Integrada para análise lexical
  • Português: Bíblia em português (necessário clonar separadamente)

Contribuindo

Contribuições são bem-vindas! Por favor, siga o estilo de código existente e adicione testes para novas funcionalidades.

Execute os testes antes de commitar:

make test

Licença

Licença MIT - Veja o arquivo LICENSE para detalhes.

Agradecimentos

  • LangGraph para orquestração de workflow
  • Groq para inferência LLM
  • Tavily para pesquisa externa
  • OSHB e SBLGNT para textos bíblicos

Por que uv?

Este projeto usa uv (pronunciado "you-vee") para gerenciamento de dependências porque:

  • Velocidade: 10-100x mais rápido que pip
  • Unificado: Substitui pip, pip-tools, pipx, poetry, pyenv e virtualenv
  • Confiável: Resolução determinística com lock files
  • Compatível com padrões: Usa pyproject.toml (PEP 621)
  • Moderno: Construído em Rust para performance

Comandos rápidos do uv:

# Instalar pacote
uv pip install <pacote>

# Instalar em modo editável
uv pip install -e ".[dev]"

# Executar com venv (auto-detectado)
uv run python -m src.cli.main_pt consultar "João 3:16"

# Sincronizar dependências
uv sync

# Atualizar lock file
uv lock

Para mais informações: https://docs.astral.sh/uv/

Nota de Segurança: Nunca commitar o arquivo .env com chaves de API reais. O arquivo .env já está no .gitignore. Sempre use .env.example como template.

About

Programa para Exegese/estudo bíblico com consulta de versículos e estudos de palavras em pc local.

Topics

terminal-based bible-study bible-search bible-database

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages