veridex 0.2.0

A modular, probabilistic, and research-grounded AI content detection library.

Veridex

A modular, probabilistic, and research-grounded AI content detection library.

Veridex is a production-ready library for detecting AI-generated content across multiple modalities: text, image, and audio. Unlike binary classifiers, Veridex provides probabilistic detection with confidence estimates and interpretable signals.

---

📑 Quick Navigation

Section	Description
✨ Features	Key capabilities of Veridex
🚀 Quick Start	Installation and basic usage
📦 Available Detectors	Complete detector comparison
🏗️ Architecture	System design and philosophy
📚 Documentation	Guides, tutorials, and API reference
🧪 Testing	Running tests and coverage
🤝 Contributing	How to contribute
🔬 Research	Academic papers and citations
⚠️ Limitations	Important usage constraints

---

✨ Features

• 🎯 Multi-Modal Detection: Text, Image, and Audio deepfake detection
• 📊 Probabilistic Outputs: Returns probabilities and confidence scores, not just binary labels
• 🔍 Interpretable Signals: Exposes individual detection features for transparency
• 🧩 Modular Architecture: Easy to extend with new detection methods
• 🚀 Production-Ready: Robust error handling, graceful degradation
• 📖 Research-Grounded: Based on state-of-the-art papers and benchmarks

💡 Use Cases

• 🛡️ Content Moderation: Automatically flag AI-generated spam, fake profiles, and synthetic media.
• 🎓 Academic Integrity: Verify the authenticity of student essays and research papers.
• 📰 Journalism & Media: Validate sources and detect deepfake imagery in news gathering.
• 🎨 Copyright Protection: Distinguish between human-created art and generative AI outputs.

🚀 Quick Start

Installation

# Install core library
pip install veridex

# Install with specific modality support
pip install veridex[text]      # Text detection
pip install veridex[audio]     # Audio detection
pip install veridex[image]     # Image detection
pip install veridex[video]     # Video detection

# Install everything
pip install veridex[text,image,audio,video]

# Development installation
pip install -e ".[dev]"

Usage Examples

Text Detection

from veridex.text import PerplexitySignal, BinocularsSignal

# Quick detection with perplexity
detector = PerplexitySignal()
result = detector.run("This text seems suspiciously perfect...")

print(f"AI Probability: {result.score:.2f}")
print(f"Confidence: {result.confidence:.2f}")
print(f"Perplexity: {result.metadata['mean_perplexity']:.2f}")

Audio Detection

from veridex.audio import SpectralSignal

# Lightweight frequency analysis
detector = SpectralSignal()
result = detector.run("audio_sample.wav")

print(f"AI Probability: {result.score:.2f}")
print(f"Spectral Features: {result.metadata}")

Image Detection

from veridex.image import FrequencySignal

# Analyze spectral anomalies
detector = FrequencySignal()
result = detector.run("suspicious_image.png")

print(f"AI Probability: {result.score:.2f}")

Video Detection

from veridex.video import VideoEnsemble

# Combine multiple video signals (recommended)
ensemble = VideoEnsemble()
result = ensemble.run("video.mp4")

print(f"AI Probability: {result.score:.2f}")
print(f"Confidence: {result.confidence:.2f}")

# View individual signal contributions
for sig, res in result.metadata['individual_results'].items():
    print(f"{sig}: {res['score']:.2f}")

👉 See more examples in the examples/ directory

---

📦 Available Detectors

Text Detectors

Detector	Method	Speed	Accuracy	GPU Required	Use Case
ZlibEntropySignal	Compression-based	⚡ Fast	⭐ Low	❌ No	Quick first-pass screening
PerplexitySignal	Statistical (LLM-based)	🔄 Medium	⭐⭐ Medium	🔶 Optional	General-purpose detection
BinocularsSignal	Contrastive Perplexity	🔄 Medium	⭐⭐⭐ High	🔶 Optional	High-accuracy text analysis
StylometricSignal	Linguistic Analysis	⚡ Fast	⭐ Low	❌ No	Style pattern detection

Audio Detectors

Detector	Method	Speed	Accuracy	GPU Required	Use Case
SpectralSignal	Frequency Domain	⚡ Fast	⭐⭐ Medium	❌ No	Lightweight audio screening
AASISTSignal	Spectro-Temporal	🔄 Medium	⭐⭐⭐ High	❌ No	Anti-spoofing detection
Wav2VecSignal	Foundation Model	🐌 Slow	⭐⭐⭐⭐ Very High	✅ Recommended	Production-grade detection
SilenceSignal	Pause Analysis	⚡ Fast	⭐ Low	❌ No	Synthetic speech patterns

Image Detectors

Detector	Method	Speed	Accuracy	GPU Required	Use Case
FrequencySignal	Spectral Analysis	⚡ Fast	⭐⭐ Medium	❌ No	Quick image screening
DIRESignal	Diffusion Reconstruction	🐌 Slow	⭐⭐⭐ High	✅ Yes	High-accuracy AI image detection
ELASignal	Error Level Analysis	⚡ Fast	⭐⭐ Medium	❌ No	Image manipulation detection

Video Detectors

Detector	Method	Speed	Accuracy	GPU Required	Use Case
RPPGSignal	Biological (Heartbeat)	🔄 Medium	⭐⭐⭐ High	❌ No	Face-swap deepfakes
I3DSignal	Spatiotemporal Motion	🔄 Medium	⭐⭐⭐ High	🔶 Recommended	General video deepfakes
LipSyncSignal	Audio-Visual Sync	🔄 Medium	⭐⭐⭐ High	❌ No	Dubbing/voice cloning
VideoEnsemble	Combines All Three	🔄 Medium	⭐⭐⭐⭐ Very High	🔶 Recommended	Production use

📺 Recommended: Use VideoEnsemble for robust detection. Combines RPPG, I3D, and LipSync with confidence-weighted fusion.

📖 Video Detection Guide - Comprehensive documentation

💡 See Choosing the Right Detector for guidance

---

🏗️ Architecture

Veridex follows a signal-based architecture:

Input → Signal Extractors → Normalization → Fusion → Output
                ↓
    (Independent, Inspectable Signals)

Each detector:

• Inherits from BaseSignal
• Returns standardized DetectionResult
• Operates independently
• Declares its limitations explicitly

Learn more: Architecture Documentation

---

📚 Documentation

📖 Guides & Tutorials

• Getting Started Guide - Installation and first steps
• Text Detection Tutorial - Step-by-step text analysis
• Image Detection Tutorial - Image deepfake detection
• Audio Detection Tutorial - Voice deepfake detection
• Examples Directory - Comprehensive examples

🔍 Concepts

• Core Concepts - Signal-based architecture
• Text Signals - Understanding text detection
• Image Signals - Understanding image detection
• Audio Signals - Understanding audio detection

📘 API Reference

• Core API - BaseSignal, DetectionResult
• Text API - Text detectors
• Image API - Image detectors
• Audio API - Audio detectors

🔬 Technical Documentation

• Design Philosophy - System design and architecture
• Research Document - Comprehensive technical analysis
• Testing Guide - How to test all metrics
• Contributing Guide - Development guidelines

---

🧪 Testing

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install with development dependencies
pip install -e ".[dev,text,audio,image]"

# Run all tests
pytest tests/ -v

# Run specific module tests
pytest tests/audio/ -v

# With coverage
pytest tests/ --cov=veridex --cov-report=html

See TESTING.md for detailed testing guide.

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/ADITYAMAHAKALI/veridex.git
cd veridex

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in editable mode with all dependencies
pip install -e ".[dev,text,image,audio]"

# Run tests
pytest tests/

# Format code
black veridex/ tests/
flake8 veridex/

---

📄 License

Apache License 2.0 - See LICENSE for details.

---

🔬 Research & Citations

Veridex is based on cutting-edge research in AI-generated content detection. Key methods include:

• Binoculars: Spotting LLMs With Binoculars (arXiv:2401.12070)
• AASIST: Audio Anti-Spoofing Integrated Spectro-Temporal Graph Attention
• DIRE: Diffusion Reconstruction Error for deepfake images
• Wav2Vec 2.0: Self-supervised foundation models for audio

See Research Documentation for full references.

---

⚠️ Limitations

Veridex is a probabilistic detection tool, not a definitive proof system:

• ❌ Not suitable as sole evidence for legal/forensic purposes
• ❌ Cannot detect all AI-generated content with 100% accuracy
• ❌ Vulnerable to adversarial attacks and post-processing
• ⚠️ Requires regular updates as generative models improve

Always use multiple signals and human judgment for critical decisions.

---

🗺️ Roadmap

• Text detection (Perplexity, Binoculars)
• Image detection (Frequency, DIRE)
• Audio detection (Spectral, AASIST, Wav2Vec)
• Video detection (rPPG, I3D, LipSync)
• C2PA provenance integration
• Ensemble fusion models
• Real-time streaming detection
• Model calibration on benchmarks

---

📧 Contact

For questions, issues, or contributions:

• Email: [e-mail]
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Contributing: CONTRIBUTING.md

---

🌟 Star History

If you find Veridex useful, please consider giving it a ⭐ on GitHub!

---

Built with ❤️ for transparency in the age of generative AI