Documenta como usar o querido-diario para alimentar bases de dados do querido-diario-data-processing

.gitignore

@@ -2,3 +2,4 @@ __pycache__
 .coverage
 envvars
 contrib/data
+.venv

Makefile

@@ -253,4 +253,4 @@ wait-elasticsearch:
 .PHONY: publish-tag
 publish-tag:
 	podman tag $(IMAGE_NAMESPACE)/$(IMAGE_NAME):${IMAGE_TAG} $(IMAGE_NAMESPACE)/$(IMAGE_NAME):$(shell git describe --tags)
-	podman push $(IMAGE_NAMESPACE)/$(IMAGE_NAME):$(shell git describe --tags)
+	podman push $(IMAGE_NAMESPACE)/$(IMAGE_NAME):$(shell git describe --tags)

README.md

@@ -1,40 +1,30 @@
-# querido-diario-data-processing
-
-## Setup
-
-- [Install podman](https://podman.io/getting-started/installation)
-- execute build stage (only the first time):
-```console
-make build
-```
-- execute setup stage:
-```console
-make setup
-```
-
-## Populate data
-Populate data [following this instructions](https://github.com/okfn-brasil/querido-diario#run-inside-a-container).
-
-- you can see created data inside [storage](http://localhost:9000/minio/queridodiariobucket) using [local credentials](contrib/sample.env#L3)
-- you can see gazettes not processed yet connecting on database
-- open database console in a new terminal
-```console
-make shell-database
-```
-- and run a query to see gazettes not processed
-```sql
-select processed, count(1) from gazettes g group by processed;
-```
-
-## Run
-- execute processing stage:
-```console
-make re-run
-```
-- and see gazettes processed running the query above
-- you can search using ElasticSearch
-```console
-curl 'http://localhost:9200/querido-diario/_search' \
-  -H 'Content-Type: application/json' \
-  --data-raw '{"query":{"query_string":{"query":"*"}},"size":2}'
-```
+PT/BR [Tutorial geral](https://github.com/Luisa-Coelho/qd-data-processing/blob/readme_update/tutorial.md) | [Configurando os diferentes ambientes](https://github.com/Luisa-Coelho/qd-data-processing/blob/readme_update/configurando_ambientes.md) | [Conectando ao querido-diario](https://github.com/Luisa-Coelho/qd-data-processing/blob/readme_update/conectando_qd.md)
+
+EN/US
+
+## O processamento de dados
+
+O repositório [querido-diario-data-processing](https://github.com/okfn-brasil/querido-diario-data-processing) tem como objetivo gerar buscas mais assertivas para o usuário por meio do uso de técnicas de processamento de linguagem natural. O processo desse repositório pode ser referenciado a partir da imagem da Infraestrutura do Querido Diário na Figura abaixo.
+![image](https://github.com/Luisa-Coelho/qd-data-processing/assets/87907716/cd6b5589-f4e7-45a0-86a9-5cbb0bf14cb7)
+
+As partes referentes à indexação e extração do texto são responsabilidade desse repositório em específico. Afinal, para ter os documentos em formato de texto (.txt) disponíveis na [plataforma](https://queridodiario.ok.org.br/) é necessário que seja feito um processamento desse conteúdo (os PDFs coletados previamente pelo repositório [querido-diario](https://github.com/okfn-brasil/querido-diario)).
+
+Veja a estrutura completa do projeto [aqui](https://docs.queridodiario.ok.org.br/pt/latest/).
+
+### Entendendo a estrutura do querido-diario-data-processing
+
+1. Montando o ambiente de trabalho
+
+A pasta "scripts" são responsáveis pelo ambiente de trabalho.
+
+2. Extração do texto
+
+"data_extraction"
+
+3. Processamento do texto
+
+A pasta "tasks" 
+
+4. Armazenamento
+
+"database" e "storage"

conectando_qd.md

@@ -0,0 +1,82 @@
+PT/BR [Tutorial geral](tutorial.md) | [Configurando os diferentes ambientes](configurando_ambientes.md) | [Conectando ao querido-diario](conectando_qd.md)
+
+EN/US
+
+## Configurando as credenciais para a comunicação dos dois projetos
+
+Para configurar as credenciais é necessário vincular os dois projetos como um só. Para isso é necessário **criar um arquivo .env** na raíz do repositório [querido-diario]() e inserir parâmetros coincidentes com o processamento do repositório [queridod-diario-data-processing](). Depois de ter realizado o fork do querido-diario, abra este repositório na sua máquina e insira um arquivo .env com as seguintes informações.
+
+~~~.env
+AWS_ACCESS_KEY_ID=minio-access-key
+AWS_SECRET_ACCESS_KEY=minio-secret-key
+AWS_ENDPOINT_URL=http://127.0.0.1:9000/
+AWS_REGION_NAME=us-east-1
+FILES_STORE=s3://queridodiariobucket/
+FILES_STORE_S3_ACL=public-read
+QUERIDODIARIO_DATABASE_URL=postgresql+psycopg2://queridodiario:[email protected]:5432/queridodiariodb
+~~~
+
+A variável .env já está como ignorada no projeto do querido-diario, portanto não é necessário mudar mais nada. Para executar a requisição abra 2 terminais (1 com o repositório do [querido-diario-data-processing]() e outro com o [querido-diario](), ambos forked). Realize o **make setup** no repositório de processamento de dados e faça a busca scrapy crawl no repositório do querido-diario. Após isso, é possível...
+
+Acesse os diários baixados através desse link: **http://localhost:9000/minio/queridodiariobucket**.
+
+Essa etapa tem que dar certo para qualquer tipo de sistema operacional, utilizando Linux ou WSL no Windows.
+
+## Configurando o ambiente do querido-diario
+
+É importante seguir as instruções gerais no repositório no repositório [querido-diario](). Iniciar um ambiente virtual, instalar o arquivo de _requirements_ bem como o pre-commit. Caso sinta dificuldades ao configurar o ambiente, é possível consultar o material de "lidando com erros" preparado.
+
+### Lidando com erros na Configuração
+
+#### Linux
+Os erros em Linux são menos comuns mas podem ocorrer devido a novas atualizações. É provável que você encontre essas soluções nas seções de WSL, Windows e Mac.
+
+Não se preocupe, como as atualizações são constantes logo o erro será resolvido e para isso você pode informá-lo em uma nova issue, pull request ou entrando em contato com os mantenedores pelo [Discord da Open Knowledge Brasil]().
+
+#### Windows
+
+##### Usando WSL
+
+Abra um novo terminal do Ubuntu e faça o clone do repositório forked do [querido-diario](https://github.com/okfn-brasil/querido-diario). Se tiver dúvidas, acesse o [tutorial de instalação do WSL no Windows](https://github.com/Luisa-Coelho/qd-data-processing/blob/readme_update/wsl_windows.md).
+
+Para fazer a conexão você precisará ter baixado e instalado tudo que for necessário no repositório [querido-diario](https://github.com/okfn-brasil/querido-diario) em outro lugar na sua máquina WSL. Deixe as pastas próximas uma da outra para facilitar seu trabalho. Abra uma outra máquina Ubuntu para iniciar o repositório querido-diario.
+
+Caso haja um erro com cython_sources, assim como na imagem:
+
+![image](https://github.com/Luisa-Coelho/qd-data-processing/assets/87907716/57afdb93-26cd-4ddc-be43-53cd4fd60365)
+
+Faça esse procedimento e instale os requirements-dev novamente:
+~~~Linux
+pip3 install wheel -v
+pip3 install "cython<3.0.0" pyyaml==5.4.1 --no-build-isolation -v
+~~~
+
+Caso haja um erro com legacy-install
+
+![image](https://github.com/Luisa-Coelho/qd-data-processing/assets/87907716/2040db6a-0d47-404f-aa98-2d2204a6ff4c)
+
+Então faça o upgrade do pip e instale algumas bibliotecas essenciais do Linux:
+~~~Linux
+python3 -m pip install --upgrade pip
+sudo apt-get install build-essential libssl-dev libffi-dev python3-dev
+~~~
+
+##### Usando o terminal do Windows
+
+Lembre-se que para conectar o Banco de Dados é necessário vincular o terminal Windows com o Linux. Caso você não queira baixar os diários diretamente na sua máquina utilizando o Windows, é possível seguir as configurações no tutorial geral do [querido-diario]() levando em conta os possível erros que podem aparecer.
+
+É necessário que as configurações C++ estejam instaladas. Baixe o Visual Studio Comunidade [aqui](https://visualstudio.microsoft.com/pt-br/downloads/) . Seguindo os passos [aqui](https://github.com/okfn-brasil/querido-diario/blob/main/docs/CONTRIBUTING.md#em-linux), você deverá baixar o Visual Studio e baixar as configurações … 
+
+Em **Componentes Individuais** selecione "SDK do Windows 10" ou '11 e Ferramentas de build do MSVC v143 - VS 2022 C++ x64/x86 (v14.32-17.4)". Ou conteúdo similares. Note que muitas vezes as versões Windows 10 SDK e MSVC v142 - VS 2019 C++ x64/x86 build tools serão atualizadas, portanto procure por itens similares em Componentes individuais para realizar a instalação (ou seja, mais novos)
+
+Em **Cargas de Trabalho**, selecione “Desenvolvimento para desktop com C++”. Instale e siga o resto do tutorial de configuração.
+
+Caso haja um erro com "pinned with == "  na hora de instalar os requerimentos, utilize o pip3 install junto com o comando --no-deps, dessa forma:
+
+~~~Windows
+pip3 install -r data_collection/requirements-dev.txt --no-deps
+~~~ 
+
+#### Mac
+
+...

configurando_ambientes.md

@@ -0,0 +1,55 @@
+PT/BR [Tutorial geral](tutorial.md) | [Configurando os diferentes ambientes](configurando_ambientes.md) | [Conectando ao querido-diario](conectando_qd.md)
+
+EN/US
+
+## Como os Projetos se relacionam
+
+O repositório [querido-diario-data-processing](https://github.com/okfn-brasil/querido-diario-data-processing) tem como objetivo gerar buscas mais assertivas para o usuário por meio do uso de técnicas de processamento de linguagem natural. O processo desse repositório pode ser referenciado a partir da imagem da Infraestrutura do Querido Diário no [[fluxograma_1.png]]. As partes referentes à indexação e extração do texto são responsabilidade desse repositório em específico. Afinal, para ter os documentos em formato de texto (.txt) disponíveis na [plataforma](https://queridodiario.ok.org.br/) é necessário que seja feito um processamento desse conteúdo (os PDFs coletados previamente pelo repositório [querido-diario](https://github.com/okfn-brasil/querido-diario)).
+
+Esse é o objetivo principal mas não é o único, já que além da possibilidade da colaboração por meio do desenvolvimento, é também possível aplicar as técnicas de PLN em um _dataset_ específico.
+
+## Configurando seu ambiente de Desenvolvimento
+
+Sempre fique ligado(a) ao documento de [Contribuição](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#ecossistema), nele é possível verificar as exigências básicas como formatação _black_, configuração de ambiente seguro, detalhamento nas _[[issues e pull requests]]_. Lembre-se também que as **issues e pull requests são uma parte da documentação do projeto**!  
+
+Sabendo desses pontos, é necessário configurar o ambiente de trabalho. Existem três diferentes sistemas operacionais que são compatíveis com o ambiente desenvolvido: Linux (o padrão e raíz), Windows e Mac. Vamos explorar cada um deles.
+
+### Linux
+
+Se você já trabalha com Linux seguir as orientações de instalação contidas no [repositório](https://github.com/okfn-brasil/querido-diario-data-processing) serão suficientes para instalar o ambiente.
+
+Alguns possíveis problemas que talvez precisem de um cuidado é relacionado à conexão do ecossistema com o [[querido-diario]]. Veja em [[conectar ao querido-diario]].
+
+### Windows
+##### Utilizando WSL
+
+Para utlizar essa etapa é necessário instalar o WSL na sua máquina Windows e instalar um sistema operacional. Veja esse tutorial de [[Instalando WSL]] caso tenha dúvidas.
+
+Dentro da sua máquina Linux já é possível seguir as instruções de instalação do ambiente contidas no repositório em [Setup](). Instale o Podman e inicie o ambiente virtual. Um comando de cada vez.
+
+~~~Linux
+ sudo apt-get update
+ ## sudo apt update && sudo apt upgrade  ##testar
+ sudo apt-get -y install podman
+
+ sudo apt install python3.10-venv
+ python3 -m venv .venv
+ source .venv/Scripts/activate  ### Ativando o ambiente virtual
+
+ sudo apt install make          ### Caso apresente erro de instalação
+ make build                     ### Somente a 1° vez
+ make setup
+ ~~~
+
+Teste para ver se o seu ambiente funciona:
+~~~Linux
+make shell-database
+~~~
+
+![[Pasted image 20231005100446.png]]
+![[Pasted image 20231005100534.png]]
+
+Após essa etapa é necessário **[[conectar ao querido-diario]]** ao banco de dados gerados pelo repositório [[querido-diario]] o qual é responsável por extrair os diários oficiais. Se a conexão não for feita, esse repositório não possui documentos para processar. Faça o fork do repositório [[querido-diario]] e [[querido-diario-data-processing]] na sua conta do Github e a partir daí faça o clone para a sua máquina Linux desses repositórios.
+### Mac
+
+...

contrib/import-env.py

@@ -0,0 +1,7 @@
+import os
+from dotenv import load_dotenv
+
+try:
+    load_dotenv()  # Load environment variables from a .env file
+except Exception as e:
+    print(f"Error loading .env file: {e}")

scripts/Dockerfile

@@ -20,4 +20,4 @@ COPY . $WORKDIR
 WORKDIR $WORKDIR
 USER $USER
 
-RUN python -c "import sentence_transformers; sentence_transformers.SentenceTransformer('neuralmind/bert-base-portuguese-cased').save('"$USER_HOME"/models/bert-base-portuguese-cased')"
+RUN python -c "import sentence_transformers; sentence_transformers.SentenceTransformer('neuralmind/bert-base-portuguese-cased').save('"$USER_HOME"/models/bert-base-portuguese-cased')"

scripts/requirements.txt

@@ -0,0 +1,11 @@
+black==19.10b0
+coverage==5.2.1
+python-magic==0.4.18
+boto3==1.22.6
+psycopg2==2.8.6
+botocore==1.25.6
+elasticsearch==7.17.3
+requests==2.25.0
+scikit-learn==1.0.2 
+sentence-transformers==2.2.0
+huggingface-hub==0.10.1  # fix: https://github.com/UKPLab/sentence-transformers/issues/1762

tutorial.md

@@ -0,0 +1,44 @@
+PT/BR [Tutorial geral](tutorial.md) | [Configurando os diferentes ambientes](configurando_ambientes.md) | [Conectando ao querido-diario](conectando_qd.md)
+
+EN/US
+
+# querido-diario-data-processing
+
+## Setup
+
+- [Install podman](https://podman.io/getting-started/installation)
+- execute build stage (only the first time):
+```console
+make build
+```
+- execute setup stage:
+```console
+make setup
+```
+
+## Populate data
+Populate data [following this instructions](https://github.com/okfn-brasil/querido-diario#run-inside-a-container).
+
+- you can see created data inside [storage](http://localhost:9000/minio/queridodiariobucket) using [local credentials](contrib/sample.env#L3)
+- you can see gazettes not processed yet connecting on database
+- open database console in a new terminal
+```console
+make shell-database
+```
+- and run a query to see gazettes not processed
+```sql
+select processed, count(1) from gazettes g group by processed;
+```
+
+## Run
+- execute processing stage:
+```console
+make re-run
+```
+- and see gazettes processed running the query above
+- you can search using ElasticSearch
+```console
+curl 'http://localhost:9200/querido-diario/_search' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"query":{"query_string":{"query":"*"}},"size":2}'
+```

wsl_windows.md

@@ -0,0 +1,48 @@
+O WSL é uma sigla para Subsistema de Windows para Linux, tradução de _Windows Subsystem for Linux_, 
+
+O sistema do Querido Diário foi totalmente desenvolvido para Linux e por isso algumas configurações não funcionam para Windows, sabendo disso uma das maneiras menos trabalhosas é configurar um subsistema para Linux, através do WSL. 
+
+Primeiramente é necessário executar o **Windows Power Shell** como administrador. No terminal digite:
+
+~~~ Windows PowerShell (admin)
+wsl --install     ### Instalando o WSL
+~~~
+
+Atenção: Recursos mais atuais do WSL exigem um sistema operacional Windows mais recentes (a partir do Windows 10).
+
+Após isso, será possível configurar um nome de usuário e senha para que você possa logar na sua nova máquina. Feito isso é necessário configurar o ambiente para o Querido Diário. É necessário ter Python, Git, Podman e o próprio repositório na sua nova máquina.
+Nas máquinas Linux normalmente já está instalado o Python, verifique a partir desse comando:
+~~~Linux
+python --version
+~~~
+
+A partir disso é possível atualizar ou dar continuidade com a instalação do ambiente de trabalho. Para instalar o Podman (para trabalhar com dockers) siga o [tutorial](https://podman.io/docs/installation) de instalação e vá até "Installing on Linux". Somente com a instalação já é possível iniciar o ambiente (utilizando o Makefile).
+
+
+~~~Linux
+sudo apt install python3-venv -y
+sudo apt install python3.10-venv
+python3 -m venv .venv
+source .venv/bin/activate
+~~~
+
+Ao iniciar uma nova máquina, já é possível acessá-la no menu iniciar do Windows. Por exemplo, caso tenha instalado o Ubuntu, pesquise assim:
+![image](https://github.com/Luisa-Coelho/qd-data-processing/assets/87907716/233e1427-2557-4c7e-ae35-40a2b7fccbf9)
+
+Caso ao iniciar seu terminal Linux apareça o erro **"Error: 0x80370114 Não foi possível iniciar a operação porque um recurso necessário não foi instalado"** ,tente habilitar os recursos Hyper-V. Para isso, digite "hyper-V" em Pesquisar e aparecerá uma opção de "Ativar ou desativar recursos do Windows".
+
+![image](https://github.com/Luisa-Coelho/qd-data-processing/assets/87907716/c82bba62-5225-40bb-8e55-ad5b39b3b5c4)
+
+Selecione Plataforma do Hipervisor do Windows e clique em Ok. Após esse procedimento, reinicie a sua máquina. 
+
+ A partir daí já será possível realizar o git clone de um repositório forked do [querido-diario-data-processing](https://github.com/okfn-brasil/querido-diario-data-processing) e então criar e iniciar um ambiente virtual:
+~~~Linux
+git clone repositorio_forked_querido-diario
+git clone repositorio_forked_querido-diario-data-processing
+~~~
+
+Caso nesta etapa tenha dado algum erro de conexão ao host do github, tente reiniciar o terminal Linux pelo comando:
+
+~~~Linux
+sudo shutdown -h now
+~~~