More readable readme
This commit is contained in:
Regis David Souza Mesquita
parent
5bd4cf40a4
commit
281fd03aa8
1 changed files with 87 additions and 54 deletions
131
README.md
131
README.md
|
|
@ -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
|
||||
---
|
||||
|
||||
## 🚀 Quick Start Guide
|
||||
|
||||
### ✅ Step 1: Installation
|
||||
|
||||
Make sure you have Python (3.x) installed, then run:
|
||||
|
||||
1. **Prerequisites:**
|
||||
- Python 3.x
|
||||
- Install dependencies:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
2. **Clone the repository:**
|
||||
### ✅ Step 2: Clone vibe to Your Machine
|
||||
|
||||
```bash
|
||||
git clone <repository_url>
|
||||
cd <repository_directory>
|
||||
cd vibe
|
||||
```
|
||||
|
||||
Running the Application
|
||||
### 🛠 Running vibe
|
||||
|
||||
CLI Mode
|
||||
You can use vibe in two ways: via a command-line interface (CLI) or through a friendly web interface with real-time updates.
|
||||
|
||||
To generate a summary MP3 using the CLI:
|
||||
#### 1️⃣ CLI Mode
|
||||
|
||||
python vibe/main.py --generate --prompt "Your interests and context here" --max-articles 5 --output summary.mp3
|
||||
To quickly generate an audio summary directly from your terminal:
|
||||
|
||||
Server Mode
|
||||
```bash
|
||||
python vibe/main.py --generate --prompt "Your interests here" --max-articles 5 --output summary.mp3
|
||||
```
|
||||
|
||||
To run the Flask server:
|
||||
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! ✨
|
||||
Loading…
Add table
Reference in a new issue