Skip to content
/ velocity-search Public

A high-performance search engine built from scratch with inverted index, TF-IDF ranking, and advanced NLP preprocessing. Features fast indexing, boolean queries, and sub-100ms search responses.

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

codeGeekPro/velocity-search

BranchesTags

Repository files navigation

Velocity Search Engine

Velocity Search Engine

Moteur de recherche textuel avancé, optimisé pour la performance, la compression et l’intégration Python/C++.

GitHub stars Documentation

Sommaire

🚀 Fonctionnalités

Voir les détails
  • Index inversé performant (Python & C++/pybind11)
  • Calcul TF-IDF, intersection/union de requêtes
  • CLI, API web Flask, visualisations
  • Compression des posting lists (variable byte, delta encoding)
  • Dictionnaire de termes compact (Trie)
  • Benchmarking et profiling (latence, mémoire, CPU)

⚡ Installation

# Dépendances Python
pip install -r requirements.txt

# Compilation extension C++ (optionnelle)
cd cpp_ext && mkdir -p build && cd build
cmake .. && make

🏁 Démarrage rapide

Indexation

from src.indexer.inverted_index import InvertedIndex
index = InvertedIndex()
index.add_document("1", ["python", "search", "engine"])

Recherche

results = index.search(["python", "engine"])
print(results)  # doc_id → score

Compression

pl = index.get_postings("python")
compressed = pl.get_doc_ids_compressed()
doc_ids = pl.decompress_doc_ids(compressed)

Benchmark

python benchmarks/benchmark_indexing.py
python benchmarks/benchmark_query.py
python benchmarks/benchmark_compression.py

🧩 API principale

InvertedIndex

  • add_document(doc_id, terms) : Ajoute un document à l’index
  • search(query_terms) : Recherche les documents pertinents
  • get_postings(term) : Récupère la posting list d’un terme
  • calculate_tf_idf(term, doc_id) : Calcule le score TF-IDF
  • get_document_vector(doc_id) : Vecteur TF-IDF du document

📊 Benchmarks

Scripts pour mesurer la performance :

  • Indexation : python benchmarks/benchmark_indexing.py
  • Recherche : python benchmarks/benchmark_query.py
  • Compression : python benchmarks/benchmark_compression.py

Voir docs/source/benchmarks.rst pour les métriques détaillées.

📚 Documentation

🏗️ Architecture

Diagramme Mermaid 
flowchart TD
        A[DocumentLoader] --> B[TextPreprocessor]
        B --> C[InvertedIndex]
        C --> D[Compression]
        C --> E[DocumentManager]
        E --> F[QueryProcessor]
        F --> G[Ranker]
        G --> H[Results]
        subgraph API
                I[Flask Web]
                J[CLI]
        end
        H --> I
        H --> J
Loading

📖 Guides

💡 Contribuer

Les contributions sont les bienvenues ! Voir docs/development/contributing.md.

Velocity Search Engine © 2025 - Velocity Team
- `get_vocabulary()` : Liste des termes - `save_to_disk(filepath, format)` / `load_from_disk(filepath, format)` : Sauvegarde/chargement - `get_term_dict_size()` / `get_trie_compressed_dict_size()` : Taille du dictionnaire brut/compressé

PostingList

  • add_posting(doc_id, term_frequency, positions) : Ajoute un posting
  • get_doc_ids_compressed() : Compression des IDs (variable byte + delta)
  • decompress_doc_ids(data) : Décompression des IDs

API Web

  • /search : Recherche par requête (GET/POST)
  • /index : Ajout de document (POST)
  • /stats : Statistiques de l’index

Visualisations

  • src/visualizations/charts.py : Génération de graphiques (matplotlib, wordcloud)

CLI

  • src/cli.py : Interface en ligne de commande pour indexer, rechercher, exporter

Extension C++

  • cpp_ext/src/inverted_index.cpp : Index inversé haute performance (pybind11)
  • benchmark_cpp_vs_python.py : Comparatif Python vs C++

Licence

MIT

Pour plus de détails, consultez la documentation des modules et les exemples dans le dossier benchmarks/.

Velocity Search Engine 🚀

Python 3.9+ License: MIT Tests Benchmarks Documentation

Un moteur de recherche haute performance conçu pour indexer et rechercher efficacement dans de grandes collections de documents avec un classement par pertinence avancé.

🎯 Démarrage Rapide

# Installation
git clone https://github.com/codeGeekPro/velocity-search.git
cd velocity-search
make install

# Premier test
python -c "
from src.core import VelocitySearch
engine = VelocitySearch()
engine.add_document('doc1', 'Python est un langage de programmation')
print(engine.search('Python'))
"

📖 Guide de Démarrage Complet →

✨ Fonctionnalités

  • 🚀 Indexation rapide : 10 000 documents en < 30 secondes
  • ⚡ Recherche ultra-rapide : Réponses en < 100ms
  • 🧠 Classement intelligent : TF-IDF et BM25
  • 💬 Autocomplétion : Suggestions en temps réel
  • 🔍 Recherche avancée : Requêtes booléennes, recherche floue
  • 🌐 API REST : Interface moderne avec FastAPI
  • 📊 Benchmarks complets : Monitoring des performances
  • 🔧 Scalable : Architecture préparée pour le clustering

📊 Performances Validées

Composant Métrique Performance
Préprocesseur Petit texte 74,959 ops/sec
Préprocesseur Texte moyen (2.5KB) 2,461 ops/sec
Préprocesseur Gros texte (50KB) 30 ops/sec
Tokenisation Vitesse pure 63,061 ops/sec
Stemming 5000 tokens 165 ops/sec
Mots vides Filtrage 935,700 ops/sec

📈 Voir tous les benchmarks →

🏗️ Architecture

velocity-search/
├── 📁 src/                    # Code source principal
│   ├── 🔍 indexer/           # Construction et gestion des index
│   ├── 🧹 preprocessor/      # Nettoyage et tokenisation  
│   ├── ❓ query_processor/   # Traitement des requêtes
│   ├── 🏆 ranker/           # Algorithmes de classement
│   └── 🛠️ utils/            # Utilitaires communs
├── 🧪 tests/                 # Tests (29 passed) + Benchmarks (12 tests)
├── 📊 data/                  # Documents et index
├── ⚙️ config/               # Configuration
├── 📚 docs/                 # Documentation complète
└── 📖 README.md

🏛️ Architecture détaillée →

� Composants du Préprocesseur

Le module de préprocessing fournit des outils avancés pour charger, nettoyer et préparer les documents avant l'indexation.

📄 DocumentLoader - Chargement Multi-Format

Classe spécialisée pour charger des documents dans différents formats avec extraction automatique de métadonnées :

Formats supportés :

  • Texte : .txt, .md (UTF-8 avec détection automatique)
  • PDF : .pdf (extraction de texte avec PyMuPDF)
  • Office : .docx (avec python-docx)
  • Web : .html, .htm (parsing avec BeautifulSoup)
  • Données : .xml, .json (traitement structuré)

Fonctionnalités :

  • ✅ Chargement parallèle avec barre de progression
  • ✅ Détection d'encodage automatique (chardet)
  • ✅ Extraction de métadonnées (titre, auteur, date, langue)
  • ✅ Gestion d'erreurs robuste (récupération gracieuse)
  • ✅ Validation de taille de fichiers
  • ✅ Détection de langue automatique

Exemple d'utilisation :

from src.preprocessor import DocumentLoader

# Créer un chargeur de documents
loader = DocumentLoader()

# Charger un document unique
document = loader.load_document("article.pdf")

# Charger plusieurs documents en parallèle
documents = loader.load_documents_batch([
    "doc1.txt", "doc2.pdf", "doc3.docx"
], max_workers=4)

# Charger tout un répertoire
documents = loader.load_directory("./data/docs/", recursive=True)

# Accéder aux métadonnées
print(f"Titre: {document.title}")
print(f"Auteur: {document.metadata.author}")
print(f"Langue: {document.metadata.language}")
print(f"Mots: {document.metadata.word_count}")

🧹 TextPreprocessor - Nettoyage de Texte

Nettoie et normalise le texte brut pour l'indexation :

  • Normalisation Unicode (décomposition, normalisation)
  • Suppression de la ponctuation et caractères spéciaux
  • Normalisation des espaces et retours à la ligne
  • Filtrage des mots vides (stop words)
  • Conversion en minuscules

🔤 Tokenizer - Tokenisation Avancée

Divise le texte en unités linguistiques significatives :

  • Tokenisation intelligente avec préservation des entités
  • Gestion des contractions (ex: "l'intelligence" → ["l", "intelligence"])
  • Détection d'entités nommées (noms, dates, organisations)
  • Types de tokens : mots, nombres, ponctuation, symboles

🌍 Stemmer - Réduction Morphologique

Réduit les mots à leur racine pour améliorer la recherche :

  • Support multi-langue : Français, Anglais, Espagnol
  • Algorithmes spécialisés par langue
  • Règles morphologiques avancées
  • Performance optimisée avec cache

�🚀 Installation

Prérequis

  • Python 3.9+ (Recommandé: Python 3.11+)
  • Git
  • 4GB RAM minimum (8GB recommandé pour de gros corpus)

Options d'Installation

📦 Installation Complète (Recommandée)

# Cloner le projet
git clone https://github.com/codeGeekPro/velocity-search.git
cd velocity-search

# Créer un environnement virtuel
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou venv\Scripts\activate  # Windows

# Installation complète avec toutes les fonctionnalités
pip install -r requirements.txt

🪶 Installation Minimale (Légère)

# Pour une installation légère (fonctionnalités de base uniquement)
pip install -r requirements-minimal.txt

🛠️ Installation Développement

# Pour contribuer au projet (outils de dev inclus)
pip install -r requirements-dev.txt

📋 Comparaison des Installations

Fonctionnalité Minimale Complète Développement
Moteur de recherche core ✅ ✅ ✅
Interface CLI ✅ ✅ ✅
Algorithmes TF-IDF/BM25 ✅ ✅ ✅
API REST FastAPI ❌ ✅ ✅
NLP avancé (spaCy) ❌ ✅ ✅
Cache Redis ❌ ✅ ✅
Interface riche (Rich) ❌ ✅ ✅
ML/Clustering ❌ ✅ ✅
Outils de test Basique Complet Avancé
Profilage & Debug ❌ ❌ ✅
Documentation ❌ ❌ ✅

⚙️ Configuration Post-Installation

Installer le package en mode développement

pip install -e .


## 🎯 Utilisation

### Interface en ligne de commande
```bash
# Indexer des documents
velocity-search index --path ./data/documents/

# Rechercher
velocity-search search "machine learning python"

# Démarrer l'API
velocity-search serve --port 8000

API REST

# Démarrer le serveur
uvicorn src.api.main:app --reload

# Requête de recherche
curl -X POST "http://localhost:8000/search" \
     -H "Content-Type: application/json" \
     -d '{"query": "python machine learning", "limit": 10}'

Code Python

from velocity_search import VelocitySearch

# Initialiser le moteur
engine = VelocitySearch()

# Indexer des documents
engine.index_directory("./data/documents/")

# Rechercher
results = engine.search("machine learning", limit=10)
for result in results:
    print(f"{result.title}: {result.score:.3f}")

📊 Performance

Métrique Cible Résultat
Indexation 10K docs/30s ✅ 12K docs/30s
Requête simple < 100ms ✅ 45ms moyenne
Autocomplétion < 20ms ✅ 8ms moyenne
Mémoire < 1GB/100K docs ✅ 850MB/100K docs

🧪 Tests

# Tous les tests
pytest

# Tests avec couverture
pytest --cov=src --cov-report=html

# Tests de performance
pytest tests/benchmarks/ -v

📚 Documentation

🛠️ Développement

Structure du code

# Exemple d'utilisation des composants
from src.indexer import InvertedIndex
from src.preprocessor import TextPreprocessor
from src.ranker import TFIDFRanker

# Pipeline d'indexation
preprocessor = TextPreprocessor()
indexer = InvertedIndex()
ranker = TFIDFRanker()

Roadmap

  • Phase 1 : Core MVP avec index inversé
  • Phase 2 : Algorithmes de ranking avancés
  • Phase 3 : Interface web et autocomplétion
  • Phase 4 : Scalabilité et distribution

🤝 Contribution

  1. Fork le projet
  2. Créer une branche feature (git checkout -b feature/amazing-feature)
  3. Commit les changements (git commit -m 'Add amazing feature')
  4. Push vers la branche (git push origin feature/amazing-feature)
  5. Ouvrir une Pull Request

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🔗 Liens Utiles

Développé avec ❤️ par l'équipe Velocity Search

About

A high-performance search engine built from scratch with inverted index, TF-IDF ranking, and advanced NLP preprocessing. Features fast indexing, boolean queries, and sub-100ms search responses.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages