<p align="center">
<img src="midia/Pymandua.png" alt="Pymandua Logo">
</p>
# Pymandua: Web Scraper para todos os websites
## Conversão de HTML para Markdown para pré-processamento de LLMs
Este projeto é uma biblioteca Python que realiza Web Scraping inteligente com lógica fuzzy e converte páginas HTML e conteúdos relacionados (como subpáginas e conteúdos renderizados com JS) em um Markdown simplificado, ideal para Large Language Models (LLMs) e análises posteriores.
---
## 🚀 Funcionalidades
- Web scraping automatizado com Selenium e suporte a páginas dinâmicas
- Conversão precisa de HTML para Markdown limpo com suporte a:
- Títulos, parágrafos, listas, links, tabelas, blocos de código, entre outros
- Lógica de busca fuzzy para identificar se o conteúdo da página e páginas ao seu redor está relacionado às palavras-chave desejadas
- Mecanismo de retorno automático de páginas visitadas
- Pode ser utilizado como biblioteca ou como script principal
---
## 🧠 Como Funciona
### 🔍 Web Scraping com Selenium
O módulo utiliza o `undetected-chromedriver` e `selenium-stealth` com o ``selenium`` para navegar por páginas web, extrair conteúdos e retroceder após a coleta. O conteúdo das páginas é tratado pelo `BeautifulSoup` e convertido em Markdown por um parser customizado.
### 🧪 Lógica Fuzzy
A comparação entre o conteúdo da página e as palavras-chave fornecidas é feita com `RapidFuzz`, utilizando similaridade textual (ex: token_sort_ratio). Isso permite validar se a página realmente trata do tema buscado, mesmo que o texto não seja exatamente igual, ou se existe alguns conteúdos ao seu redor (subpáginas e conteúdos criados a partir de reatividade com JavaScript) para capturar e consolidar em um único lugar.
---
## 🖼️ Fluxo do Processo
<p align="center">
<img src="midia/flowchart.png" alt="Fluxograma do Processo" style="background: white; padding: 8px; border-radius: 8px;">
</p>
### 🧪 Instalação
**Com pip**
```bash
pip install pymandua
```
**Ou alternativamente**
1. **Clone o repositório:**
```bash
git clone https://github.com/Mark-Campanella/pymandua.git
cd pymandua
```
2. **Crie um ambiente virtual e ative:**
```bash
python -m venv env
source env/bin/activate # Linux/macOS
env\Scripts\activate # Windows
```
3. **Instale as dependências:**
``` bash
pip install -r requirements.txt
```
### 🔧 Uso como script
```python
from pymandua import to_mkd
result = to_mkd(
urls="https://pt.wikipedia.org/wiki/Luís_XIV_de_França",
keywords=["Luís XIV", "França", "Rei Sol"],
output_path=r"projeto/output",
wait=2,
threshold=90
)
print(result)
```
**Uso como CLI**
```bash
to-mkd --urls "https://exemplo.com" --keywords "palavra1,palavra2" --output "saida.md" --wait 2 --threshold 95
```
### 🧩 Estrutura do Projeto
```
├── pymandua/ # Módulo principal
│ ├── interface.py # Interface principal do conversor
│ ├── converter.py # Conversor de HTML para Markdown
│ ├── gatherer.py # Web scraper e parser de conteúdo
│ ├── driver.py # Inicializador de driver para o selenium
│ ├── crawler.py # Web crawler e parser de conteúdo
│ ├── treater.py # Prepara para o cleaner
│ ├── aggregator.py # Agrega os diversos HTMLs resultantes em um para ser convertido
│ ├── cleaner.py # Parser e limpador de conteúdo não necessário
├── output/ # Arquivos .mkd gerados
├── requirements.txt # Dependências
├── main.py # Exemplo de uso
```
**📚 Referências**
- [Selenium Docs](https://selenium-python.readthedocs.io)
- [BeautifulSoup Docs](https://www.crummy.com/software/BeautifulSoup/bs4/doc/)
- [RapidFuzz Docs](maxbachmann.github.io/RapidFuzz/)
- [RapidFuzz Examples](https://github.com/rapidfuzz/RapidFuzz#examples)
----------
### 🧠 RAG Pipeline (Análise com IA)
Este projeto estende sua funcionalidade principal com um pipeline de Análise de Conteúdo usando `Retrieval-Augmented Generation (RAG)`. Ele permite que você use os arquivos Markdown gerados para consultas inteligentes, respondendo perguntas e gerando tabelas estruturadas sobre o conteúdo.
### 🚀 Funcionalidades Chave do RAG
- Modularidade "Plug & Play": Alterne facilmente entre diferentes provedores de LLM (``Ollama, OpenAI, Gemini``) e bancos de dados vetoriais (``ChromaDB, Pinecone``) com a simples alteração de um parâmetro.
- Interface Web (UI): Uma interface interativa e amigável, criada com ``Gradio``, que se abre automaticamente no navegador para uma experiência de uso otimizada.
- Geração de Tabelas: Peça ao LLM para extrair dados específicos e formatá-los em uma tabela Markdown com cabeçalhos personalizados, ideal para análise.
### 🔧 Uso do Pipeline RAG
O pipeline RAG é um processo separado da conversão de HTML para Markdown, permitindo que você use a biblioteca de forma modular.
#### Passo 1: Gerar os Arquivos Markdown
Primeiro, use a função ``to_mkd`` para gerar os arquivos Markdown no diretório de saída (configurado em ``config.yaml``). Seus arquivos .mkd servirão como a base de conhecimento para o sistema RAG.
```python
from pymandua import to_mkd
# This will generate the .mkd files in the 'output' directory
to_mkd(
urls=["https://pt.wikipedia.org/wiki/Luís_XIV_de_França"],
keywords=["Luís XIV"],
wait=2,
threshold=90
)
```
### Passo 2: Iniciar o Pipeline RAG
Em seguida, use a nova função ``start_rag_pipeline`` para processar os arquivos Markdown existentes e iniciar a interface de usuário. Você pode usar as configurações padrão do ``config.yaml`` ou sobrescrevê-las com parâmetros diretos para maior flexibilidade.
```python
from pymandua import start_rag_pipeline
# Example 1: Use default settings from config.yaml
start_rag_pipeline()
# Example 2: Override models and providers via code
start_rag_pipeline(
llm_model="llama3-chatqa:8b",
embedding_model="nomic-embed-text",
active_provider="ollama",
persist_directory="./my-rag-db"
)
```
### 🖼️ Fluxo de Processo Completo
O diagrama de fluxo do seu projeto agora é expandido para incluir o pipeline RAG, ilustrando o processo completo da web até a análise com IA.
```mermaid
graph TD
subgraph Web Scraping & Conversion
User[User] --> to_mkd(to_mkd);
to_mkd --> Output[output/];
end
subgraph RAG Pipeline
Output --> start_rag_pipeline(start_rag_pipeline);
start_rag_pipeline --> Ingest(Ingestion: Embeddings & Storage);
Ingest --> VectorDB[Vector Database ] ;
VectorDB --> Gradio[Gradio UI];
Gradio --> LLM(LLM);
Gradio --> VectorDB;
end
LLM --> Answers[Answers & Tables];
```
Raw data
{
"_id": null,
"home_page": "https://github.com/seuusuario/web-scraper-with-ai",
"name": "pymandua",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "scraping, fuzzy logic, HTML to Markdown, JavaScript reactivity, LLM, web scraping, RAG, retrieval-augmented generation",
"author": "Marcos Henrique Maimoni Campanella",
"author_email": "\"Marcos H. M. Campanella\" <mhmcamp@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/39/d4/d18bbcf9a91a9104b9f6db9b2fbcaa72ab2e637bc3460ba59e738977da8f/pymandua-0.1.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\r\n <img src=\"midia/Pymandua.png\" alt=\"Pymandua Logo\">\r\n</p>\r\n\r\n# Pymandua: Web Scraper para todos os websites \r\n## Convers\u00e3o de HTML para Markdown para pr\u00e9-processamento de LLMs\r\n\r\nEste projeto \u00e9 uma biblioteca Python que realiza Web Scraping inteligente com l\u00f3gica fuzzy e converte p\u00e1ginas HTML e conte\u00fados relacionados (como subp\u00e1ginas e conte\u00fados renderizados com JS) em um Markdown simplificado, ideal para Large Language Models (LLMs) e an\u00e1lises posteriores.\r\n\r\n---\r\n\r\n## \ud83d\ude80 Funcionalidades\r\n\r\n- Web scraping automatizado com Selenium e suporte a p\u00e1ginas din\u00e2micas\r\n- Convers\u00e3o precisa de HTML para Markdown limpo com suporte a:\r\n - T\u00edtulos, par\u00e1grafos, listas, links, tabelas, blocos de c\u00f3digo, entre outros\r\n- L\u00f3gica de busca fuzzy para identificar se o conte\u00fado da p\u00e1gina e p\u00e1ginas ao seu redor est\u00e1 relacionado \u00e0s palavras-chave desejadas\r\n- Mecanismo de retorno autom\u00e1tico de p\u00e1ginas visitadas\r\n- Pode ser utilizado como biblioteca ou como script principal\r\n\r\n---\r\n\r\n## \ud83e\udde0 Como Funciona\r\n\r\n### \ud83d\udd0d Web Scraping com Selenium\r\n\r\nO m\u00f3dulo utiliza o `undetected-chromedriver` e `selenium-stealth` com o ``selenium`` para navegar por p\u00e1ginas web, extrair conte\u00fados e retroceder ap\u00f3s a coleta. O conte\u00fado das p\u00e1ginas \u00e9 tratado pelo `BeautifulSoup` e convertido em Markdown por um parser customizado.\r\n\r\n### \ud83e\uddea L\u00f3gica Fuzzy\r\n\r\nA compara\u00e7\u00e3o entre o conte\u00fado da p\u00e1gina e as palavras-chave fornecidas \u00e9 feita com `RapidFuzz`, utilizando similaridade textual (ex: token_sort_ratio). Isso permite validar se a p\u00e1gina realmente trata do tema buscado, mesmo que o texto n\u00e3o seja exatamente igual, ou se existe alguns conte\u00fados ao seu redor (subp\u00e1ginas e conte\u00fados criados a partir de reatividade com JavaScript) para capturar e consolidar em um \u00fanico lugar.\r\n\r\n---\r\n\r\n## \ud83d\uddbc\ufe0f Fluxo do Processo\r\n\r\n\r\n<p align=\"center\">\r\n <img src=\"midia/flowchart.png\" alt=\"Fluxograma do Processo\" style=\"background: white; padding: 8px; border-radius: 8px;\">\r\n</p>\r\n\r\n\r\n### \ud83e\uddea Instala\u00e7\u00e3o\r\n\r\n**Com pip**\r\n```bash\r\npip install pymandua\r\n```\r\n\r\n\r\n**Ou alternativamente**\r\n1. **Clone o reposit\u00f3rio:**\r\n```bash\r\ngit clone https://github.com/Mark-Campanella/pymandua.git\r\ncd pymandua\r\n```\r\n\r\n2. **Crie um ambiente virtual e ative:**\r\n```bash\r\npython -m venv env\r\nsource env/bin/activate # Linux/macOS\r\nenv\\Scripts\\activate # Windows\r\n```\r\n\r\n3. **Instale as depend\u00eancias:**\r\n``` bash\r\npip install -r requirements.txt\r\n```\r\n\r\n\r\n### \ud83d\udd27 Uso como script\r\n```python\r\nfrom pymandua import to_mkd\r\n\r\nresult = to_mkd(\r\n urls=\"https://pt.wikipedia.org/wiki/Lu\u00eds_XIV_de_Fran\u00e7a\",\r\n keywords=[\"Lu\u00eds XIV\", \"Fran\u00e7a\", \"Rei Sol\"],\r\n output_path=r\"projeto/output\",\r\n wait=2,\r\n threshold=90\r\n)\r\nprint(result)\r\n\r\n```\r\n\r\n**Uso como CLI**\r\n```bash\r\nto-mkd --urls \"https://exemplo.com\" --keywords \"palavra1,palavra2\" --output \"saida.md\" --wait 2 --threshold 95\r\n```\r\n\r\n### \ud83e\udde9 Estrutura do Projeto\r\n```\r\n\u251c\u2500\u2500 pymandua/ # M\u00f3dulo principal\r\n\u2502 \u251c\u2500\u2500 interface.py # Interface principal do conversor\r\n\u2502 \u251c\u2500\u2500 converter.py # Conversor de HTML para Markdown\r\n\u2502 \u251c\u2500\u2500 gatherer.py # Web scraper e parser de conte\u00fado\r\n\u2502 \u251c\u2500\u2500 driver.py # Inicializador de driver para o selenium\r\n\u2502 \u251c\u2500\u2500 crawler.py # Web crawler e parser de conte\u00fado\r\n\u2502 \u251c\u2500\u2500 treater.py # Prepara para o cleaner\r\n\u2502 \u251c\u2500\u2500 aggregator.py # Agrega os diversos HTMLs resultantes em um para ser convertido\r\n\u2502 \u251c\u2500\u2500 cleaner.py # Parser e limpador de conte\u00fado n\u00e3o necess\u00e1rio\r\n\u251c\u2500\u2500 output/ # Arquivos .mkd gerados\r\n\u251c\u2500\u2500 requirements.txt # Depend\u00eancias\r\n\u251c\u2500\u2500 main.py # Exemplo de uso\r\n```\r\n\r\n**\ud83d\udcda Refer\u00eancias**\r\n- [Selenium Docs](https://selenium-python.readthedocs.io)\r\n- [BeautifulSoup Docs](https://www.crummy.com/software/BeautifulSoup/bs4/doc/)\r\n- [RapidFuzz Docs](maxbachmann.github.io/RapidFuzz/)\r\n- [RapidFuzz Examples](https://github.com/rapidfuzz/RapidFuzz#examples)\r\n\r\n----------\r\n\r\n### \ud83e\udde0 RAG Pipeline (An\u00e1lise com IA)\r\nEste projeto estende sua funcionalidade principal com um pipeline de An\u00e1lise de Conte\u00fado usando `Retrieval-Augmented Generation (RAG)`. Ele permite que voc\u00ea use os arquivos Markdown gerados para consultas inteligentes, respondendo perguntas e gerando tabelas estruturadas sobre o conte\u00fado.\r\n\r\n### \ud83d\ude80 Funcionalidades Chave do RAG\r\n- Modularidade \"Plug & Play\": Alterne facilmente entre diferentes provedores de LLM (``Ollama, OpenAI, Gemini``) e bancos de dados vetoriais (``ChromaDB, Pinecone``) com a simples altera\u00e7\u00e3o de um par\u00e2metro.\r\n\r\n- Interface Web (UI): Uma interface interativa e amig\u00e1vel, criada com ``Gradio``, que se abre automaticamente no navegador para uma experi\u00eancia de uso otimizada.\r\n\r\n- Gera\u00e7\u00e3o de Tabelas: Pe\u00e7a ao LLM para extrair dados espec\u00edficos e format\u00e1-los em uma tabela Markdown com cabe\u00e7alhos personalizados, ideal para an\u00e1lise.\r\n\r\n### \ud83d\udd27 Uso do Pipeline RAG\r\nO pipeline RAG \u00e9 um processo separado da convers\u00e3o de HTML para Markdown, permitindo que voc\u00ea use a biblioteca de forma modular.\r\n\r\n#### Passo 1: Gerar os Arquivos Markdown\r\n\r\nPrimeiro, use a fun\u00e7\u00e3o ``to_mkd`` para gerar os arquivos Markdown no diret\u00f3rio de sa\u00edda (configurado em ``config.yaml``). Seus arquivos .mkd servir\u00e3o como a base de conhecimento para o sistema RAG.\r\n\r\n```python\r\nfrom pymandua import to_mkd\r\n\r\n# This will generate the .mkd files in the 'output' directory\r\nto_mkd(\r\n urls=[\"https://pt.wikipedia.org/wiki/Lu\u00eds_XIV_de_Fran\u00e7a\"],\r\n keywords=[\"Lu\u00eds XIV\"],\r\n wait=2,\r\n threshold=90\r\n)\r\n```\r\n### Passo 2: Iniciar o Pipeline RAG\r\n\r\nEm seguida, use a nova fun\u00e7\u00e3o ``start_rag_pipeline`` para processar os arquivos Markdown existentes e iniciar a interface de usu\u00e1rio. Voc\u00ea pode usar as configura\u00e7\u00f5es padr\u00e3o do ``config.yaml`` ou sobrescrev\u00ea-las com par\u00e2metros diretos para maior flexibilidade.\r\n\r\n```python\r\nfrom pymandua import start_rag_pipeline\r\n\r\n# Example 1: Use default settings from config.yaml\r\nstart_rag_pipeline()\r\n\r\n\r\n# Example 2: Override models and providers via code\r\nstart_rag_pipeline(\r\n llm_model=\"llama3-chatqa:8b\",\r\n embedding_model=\"nomic-embed-text\",\r\n active_provider=\"ollama\",\r\n persist_directory=\"./my-rag-db\"\r\n)\r\n\r\n```\r\n\r\n### \ud83d\uddbc\ufe0f Fluxo de Processo Completo\r\nO diagrama de fluxo do seu projeto agora \u00e9 expandido para incluir o pipeline RAG, ilustrando o processo completo da web at\u00e9 a an\u00e1lise com IA.\r\n\r\n```mermaid\r\ngraph TD\r\n subgraph Web Scraping & Conversion\r\n User[User] --> to_mkd(to_mkd);\r\n to_mkd --> Output[output/];\r\n end\r\n\r\n subgraph RAG Pipeline\r\n Output --> start_rag_pipeline(start_rag_pipeline);\r\n start_rag_pipeline --> Ingest(Ingestion: Embeddings & Storage);\r\n Ingest --> VectorDB[Vector Database ] ;\r\n VectorDB --> Gradio[Gradio UI];\r\n Gradio --> LLM(LLM);\r\n Gradio --> VectorDB;\r\n end\r\n\r\n LLM --> Answers[Answers & Tables];\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Uma biblioteca para scraping com l\u00f3gica fuzzy e convers\u00e3o de HTML e conte\u00fados ao seu redor, lidando com reatividade do javascript para Markdown focado em LLMs. Adicionado com um pipeline RAG.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/seuusuario/web-scraper-with-ai",
"homepage": "https://github.com/Mark-Campanella/pymandua",
"repository": "https://github.com/Mark-Campanella/pymandua"
},
"split_keywords": [
"scraping",
" fuzzy logic",
" html to markdown",
" javascript reactivity",
" llm",
" web scraping",
" rag",
" retrieval-augmented generation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e58a97ab706517c3454db9d744e53fd62b0ef45d9e5fb24888aca140d5bc8814",
"md5": "811f5bb5da29f3cf0c06858e2ae78784",
"sha256": "235df00056a7a2f9dbed783edde57b3a754253cc170cc36477cb89ca95a95f9d"
},
"downloads": -1,
"filename": "pymandua-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "811f5bb5da29f3cf0c06858e2ae78784",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27478,
"upload_time": "2025-10-06T23:51:57",
"upload_time_iso_8601": "2025-10-06T23:51:57.731457Z",
"url": "https://files.pythonhosted.org/packages/e5/8a/97ab706517c3454db9d744e53fd62b0ef45d9e5fb24888aca140d5bc8814/pymandua-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "39d4d18bbcf9a91a9104b9f6db9b2fbcaa72ab2e637bc3460ba59e738977da8f",
"md5": "719ae2c36d047137a400b4184b6852e0",
"sha256": "f36fd971b83ab99f52b19e781907cedfe0d63ef0ff743ee73ddb40594f396144"
},
"downloads": -1,
"filename": "pymandua-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "719ae2c36d047137a400b4184b6852e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27129,
"upload_time": "2025-10-06T23:51:58",
"upload_time_iso_8601": "2025-10-06T23:51:58.920907Z",
"url": "https://files.pythonhosted.org/packages/39/d4/d18bbcf9a91a9104b9f6db9b2fbcaa72ab2e637bc3460ba59e738977da8f/pymandua-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 23:51:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "seuusuario",
"github_project": "web-scraper-with-ai",
"github_not_found": true,
"lcname": "pymandua"
}
JSON
