rdsm/arxiv_audio_summary
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More readable readme

Browse source
This commit is contained in:
Regis David Souza Mesquita 2025-03-02 04:02:26 +00:00
parent 5bd4cf40a4
commit 281fd03aa8
1 changed files with 87 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

141
README.md
View file

@ -1,83 +1,116 @@
# vibe: Article Summarization & TTS Pipeline
# vibe: Your Personal AI Research Summarizer 🎧
vibe is a Python-based pipeline that automatically fetches the latest Computer Science research articles from arXiv, filters them for relevance using a language model (LLM), converts article PDFs to Markdown with Docling, generates narrative summaries, and synthesizes the summaries into an MP3 audio file using a text-to-speech (TTS) system.
**vibe** is a smart assistant that fetches the latest Computer Science research articles from arXiv, identifies the most relevant ones based on your interests, summarizes them into engaging narratives, and even reads them aloud by generating an MP3 audio summary. Perfect for staying informed effortlessly!
This repository has been refactored into a modular structure for improved maintainability.
---
## Project Structure
## 🎯 What Can vibe Do for You?
- **vibe/** - Main package containing all modules:
- `config.py` - Configuration, constants, and cache setup.
- `fetcher.py` - Module to fetch articles from arXiv.
- `filter.py` - Module for relevance filtering using an LLM.
- `rerank.py` - Module to rerank articles.
- `converter.py` - Module to convert PDFs to Markdown.
- `summarizer.py` - Module to generate article summaries.
- `tts.py` - Module for text-to-speech conversion.
- `orchestrator.py` - Orchestrates the complete pipeline.
- `server.py` - Flask server exposing a REST API.
- `main.py` - CLI entry point.
- **tests/** - Contains unit tests.
- **requirements.txt** - Python package requirements.
- **Makefile** - Makefile to run common tasks.
- Automatically fetch the newest CS research from arXiv.
- Filter and rank articles tailored to your specific interests.
- Summarize articles into a smooth, narrative-friendly format.
- Generate an MP3 audio summary to listen on-the-go.
- Provide real-time progress updates while generating your summaries.
## Installation
---
1. **Prerequisites:**
- Python 3.x
- Install dependencies:
```bash
pip install -r requirements.txt
```
## 🚀 Quick Start Guide
2. **Clone the repository:**
```bash
git clone <repository_url>
cd <repository_directory>
### ✅ Step 1: Installation
Running the Application
Make sure you have Python (3.x) installed, then run:
CLI Mode
```bash
pip install -r requirements.txt
```
To generate a summary MP3 using the CLI:
### ✅ Step 2: Clone vibe to Your Machine
python vibe/main.py --generate --prompt "Your interests and context here" --max-articles 5 --output summary.mp3
```bash
git clone <repository_url>
cd vibe
```
Server Mode
### 🛠 Running vibe
To run the Flask server:
You can use vibe in two ways: via a command-line interface (CLI) or through a friendly web interface with real-time updates.
#### 1️⃣ CLI Mode
To quickly generate an audio summary directly from your terminal:
```bash
python vibe/main.py --generate --prompt "Your interests here" --max-articles 5 --output summary.mp3
```
Your audio summary will be saved as `summary.mp3`. Just play and enjoy!
#### 2️⃣ Server Mode (Recommended 🎉)
We’ve built a simple, intuitive web landing page that lets you interact easily with vibe:
First, launch the Flask server by running:
```bash
python vibe/main.py --serve
```
Then, you can make a POST request to http://127.0.0.1:5000/process with a JSON payload:
Then open your web browser and go to:
curl -X POST http://127.0.0.1:5000/process \
-H "Content-Type: application/json" \
-d '{"user_info": "Your interests here", "max_articles": 5, "new_only": false}'
```
http://127.0.0.1:5000
```
Running Tests
#### ✨ How It Works:
The project includes basic tests to verify that modules are working as expected. To run the tests, execute:
- Enter your interests directly on the landing page.
- Click “Submit” and relax while vibe fetches and summarizes the best articles for you.
- Watch live status updates appear on-screen, letting you know exactly what’s happening behind the scenes.
- Once complete, an audio summary (`summary.mp3`) will automatically download. It’s that easy!
---
## 🧪 Running Tests
Ensure vibe stays reliable with the built-in test suite. Just run:
```bash
make test
```
or
Or manually:
```bash
python -m unittest discover -s tests
```
Makefile Commands
• make test - Run the unit tests.
• make run - Run the application in CLI mode (you can modify the command inside the Makefile).
• make serve - Run the Flask server.
• make clean - Clean up temporary files (e.g., remove the cache directory).
---
Environment Variables
## ⚙️ Makefile Commands
The following environment variables can be set to customize the behavior:
• ARXIV_URL
• LLM_URL
• MODEL_NAME
We’ve made common tasks simpler:
License
- `make test` – Runs unit tests.
- `make run` – Runs vibe in CLI mode (you can customize this command inside the Makefile).
- `make serve` – Starts the Flask server with the web interface.
- `make clean` – Cleans temporary files (cache, temporary directories).
This project is licensed under the MIT License.
---
## 🌎 Environment Variables
Customize vibe with these optional environment variables:
- `ARXIV_URL` – URL for fetching articles from arXiv.
- `LLM_URL` – URL of your preferred language model endpoint.
- `MODEL_NAME` – Name of the language model to use.
---
## 📜 License
vibe is open source under the MIT License. Use it, modify it, enjoy it!
---
✨ Enjoy exploring the latest research effortlessly with vibe! ✨