Metadata-Version: 2.4
Name: verityngn
Version: 3.0.0
Summary: Open-source multimodal video claim verification engine with Deep Research
Author: HotChili Analytics, LLC
License: Apache-2.0
Project-URL: Homepage, https://github.com/hotchilianalytics/verityngn-oss
Project-URL: Documentation, https://hotchilianalyticsllc.mintlify.app
Project-URL: Issues, https://github.com/hotchilianalytics/verityngn-oss/issues
Keywords: fact-checking,youtube,verification,osint,multimodal,deep-research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rapidfuzz>=3.0.0
Requires-Dist: markdown-it-py[plugins]>=3.0.0
Requires-Dist: pydantic>=2.7.4
Requires-Dist: langchain>=0.3.17
Requires-Dist: langchain-google-vertexai>=2.0.0
Requires-Dist: langgraph>=0.2.50
Requires-Dist: google-cloud-aiplatform>=1.81.0
Requires-Dist: google-cloud-storage>=2.18.0
Requires-Dist: yt-dlp>=2024.12.13
Requires-Dist: requests>=2.31.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: youtube-transcript-api>=0.6.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pandas>=2.0.0; extra == "dev"
Provides-Extra: deep
Requires-Dist: google-genai>=1.0.0; extra == "deep"
Provides-Extra: vision
Requires-Dist: mediapipe==0.10.18; extra == "vision"
Requires-Dist: opencv-python-headless>=4.8.0; extra == "vision"
Provides-Extra: vision-face
Requires-Dist: verityngn[vision]; extra == "vision-face"
Requires-Dist: opencv-contrib-python==4.10.0.84; extra == "vision-face"
Provides-Extra: audio
Requires-Dist: librosa>=0.10.0; extra == "audio"
Requires-Dist: soundfile>=0.12.0; extra == "audio"
Requires-Dist: numpy>=1.24.0; extra == "audio"
Provides-Extra: affect
Requires-Dist: verityngn[audio]; extra == "affect"
Requires-Dist: librosa>=0.10.0; extra == "affect"
Requires-Dist: soundfile>=0.12.0; extra == "affect"
Provides-Extra: predictions
Requires-Dist: verityngn[affect,audio,vision]; extra == "predictions"
Requires-Dist: pandas>=2.0.0; extra == "predictions"
Requires-Dist: matplotlib>=3.7.0; extra == "predictions"
Requires-Dist: yfinance>=0.2.40; extra == "predictions"
Provides-Extra: disclosure
Provides-Extra: mcp
Provides-Extra: all
Requires-Dist: verityngn[audio,deep,predictions,vision]; extra == "all"
Dynamic: license-file

# VerityNgn

**Claim-level risk abatement for video**

[![Documentation](https://img.shields.io/badge/docs-mintlify-blue.svg)](https://hotchilianalyticsllc.mintlify.app)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Research](https://img.shields.io/badge/status-research-yellow.svg)]()

> **Current OSS runtime:** `release/v3.0.0` is the canonical public engine.
> The local-first path now defaults analysis, verification, and Deep Research to
> `gemini-3.8-flash`, always emits both `report.html` and `deep.html`, and uses
> a shared fallback policy when Vertex model/location availability differs across
> `global` and `us-central1`.

---

## Quick start (v3)

```bash
pip install 'verityngn[deep]'
# Public Lipozem demo
verityngn analyze --tier full --deep 'https://www.youtube.com/watch?v=tLJC8hkK-ao'
# Analyst local file (SB1507 — provide your own path to the mp4)
verityngn analyze --tier local-full --deep -f /path/to/sb1507.mp4 -o outputs/release_v3_sb1507_dense
# CEO talking-head
verityngn analyze --tier full --deep 'https://www.youtube.com/watch?v=lb_ZJylekWo'
```

Copy-paste fixtures, scorecard counts, and what is *not* in the wheel: [`docs/launch/EXAMPLES.md`](docs/launch/EXAMPLES.md).

Open-core boundary: [`docs/OPEN_CORE.md`](docs/OPEN_CORE.md) · Dependency model: [`docs/DEPENDENCY_MODEL.md`](docs/DEPENDENCY_MODEL.md) · Promotion checklist: [`docs/launch/OSS_BATCH_COMMERCIAL_PROMOTION.md`](docs/launch/OSS_BATCH_COMMERCIAL_PROMOTION.md) · Gemini gap: [`docs/research/GEMINI_2026_CAPABILITY_GAP.md`](docs/research/GEMINI_2026_CAPABILITY_GAP.md)

---

## What is VerityNgn?

VerityNgn is an open-source engine that analyzes YouTube or local video to produce **claim-level risk assessments** (disclosure risk, delivery risk, brand-safety / sponsor-readiness):

- Multimodal analysis: video, audio, OCR, motion, and transcript
- Evidence verification with web search and source reputation tiers
- Counter-intelligence: YouTube reviews and press-release bias detection
- Internal calibrated TRUE/FALSE/UNCERTAIN probabilities (display as Supported / Contested / Unresolved)
- Reports: JSON-first standard report + Deep Research brief with stable aliases
  `report.html` and `deep.html`

### How It Works

```
YouTube URL or mp4 -> JSON-first analysis -> claim extraction -> verification + counter-intel -> `report.html` + `deep.html`
```

1. **Tiered routing**: `auto` selects transcript-first vs full multimodal based on caption and visual sufficiency.
2. **Modality control**: `--modality auto|transcript|video` lets operators force the extraction path.
3. **Fallback-aware LLM routing**: Vertex `global` -> lower Vertex models -> `us-central1` -> Developer API.
4. **Source finding**: verification now keeps light-search sources for previously skipped promotional claims and falls back to evidence-derived URLs when needed.
5. **Dual outputs**: standard + Deep Research artifacts are synchronized into the requested output directory.

---

## 🚀 Quick Start

### Zero-friction CLI (2026-07 unfreeze)

```bash
git clone https://github.com/hotchilianalytics/verityngn-oss.git
cd verityngn-oss
pip install -e .

# Set Vertex / search keys in .env (see .env.example)
verityngn analyze "https://www.youtube.com/watch?v=tLJC8hkK-ao"

# Local file (depositions, court video) — no YouTube required
verityngn analyze --file /path/to/clip.mp4 --title "Expert witness excerpt"
```

Output: `{video_id}_report.md` in `.outputs/{video_id}/`.

---

VerityNgn also supports three deployment options:

### Option 1: Local-First Deployment (Recommended)

**VerityNgn is now local-first by default.** Run everything on your machine with optional cloud enhancements.

```bash
# Clone repository
git clone https://github.com/hotchilianalytics/verityngn-oss.git
cd verityngn-oss

# Configure environment
cp config.yaml.example config.yaml
# Edit config.yaml with your API keys (Search, Vertex AI)

# Run with Streamlit
streamlit run ui/streamlit_app.py
```

**Access**:
- Streamlit UI: http://localhost:8501
- API Backend: http://localhost:8080

See [docs/DEPLOYMENT_LOCAL.md](docs/DEPLOYMENT_LOCAL.md) for details.

### Option 2: Cloud Deployment (Recommended for Production)

Deploy API to Google Cloud Run + Streamlit to Streamlit Cloud:

```bash
# Deploy API
gcloud run deploy verityngn-api \
  --image=$REGION-docker.pkg.dev/$PROJECT_ID/verityngn/api:latest \
  --platform=managed \
  --region=us-central1
```

See [docs/DEPLOYMENT_CLOUD_RUN.md](docs/DEPLOYMENT_CLOUD_RUN.md) for details.

### Option 3: Google Colab (Easiest for Trying Out)

Open the Colab notebook and connect to any API endpoint:

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/hotchilianalytics/verityngn-oss/blob/main/notebooks/VerityNgn_Colab_Demo.ipynb)

See [docs/DEPLOYMENT_COLAB.md](docs/DEPLOYMENT_COLAB.md) for details.

---

## What's New in v2.0

### 🚀 Intelligent Video Segmentation
- **Context-aware segmentation**: Automatically calculates optimal segment sizes based on model context window (1M tokens)
- **86% fewer API calls**: 33-minute video processed in 1 segment instead of 7
- **58% context utilization**: Maximizes use of available token budget
- **6-7x faster**: Typical 30-minute videos complete in 8-12 minutes instead of 56-84 minutes
- **Token economics**: 290 tokens/second consumption rate with smart overhead management

### 🎯 Enhanced Claims Extraction
- **Multi-pass extraction**: Initial broad extraction → specificity scoring → quality filtering → ranking
- **Absence claim generation**: Automatically identifies what's NOT mentioned (e.g., "no peer-reviewed studies cited")
- **Specificity scoring**: Rates claims from 0-100 on verifiability
- **Type classification**: Scientific, statistical, causal, comparative, testimonial, expert opinion
- **Intelligent filtering**: Removes vague claims, keeps high-quality verifiable statements

### 🔧 Improved Counter-Intelligence
- **Balanced impact model**: Refined from -0.35 to -0.20 for YouTube review influence
- **Enhanced credibility weighting**: Views, channel authority, and engagement metrics
- **Better integration**: Seamlessly works with intelligent segmentation
- **Maintained accuracy**: 94% precision on press release detection, 76% on review detection

### 📊 Performance Improvements
- **API efficiency**: 86% reduction in calls for typical videos
- **Context utilization**: 3% → 58% (19x improvement)
- **Processing speed**: 6-7x faster for 30-minute videos
- **Cost reduction**: Proportional to API call reduction

---

## Key Features

### 🎯 Multimodal Video Analysis
- Analyzes visual content, audio, on-screen text (OCR), and motion
- Uses Google Gemini 2.5 Flash (1M token context window)
- **Intelligent segmentation**: Context-aware segment calculation (up to 47.7 minutes per segment)
- Processes videos up to 2+ hours with optimized segment-based analysis
- 290 tokens/second consumption rate with automatic overhead management

### 🔬 Evidence-Based Verification
- Web search with credibility weighting
- Scientific database integration (PubMed, academic sources)
- Source validation power scoring (peer-reviewed = 1.5, press release = -1.0)

### 🕵️ Counter-Intelligence System
- **YouTube Review Analysis**: Searches for contradictory reviews/debunking videos
  - 76% detection rate, 89% stance accuracy
  - Credibility weighting based on views, channel, engagement
- **Press Release Detection**: Identifies promotional content
  - 94% precision, 87% recall
  - Penalizes self-referential promotional material

### 📊 Probabilistic Truthfulness
- Three-state distribution: TRUE / FALSE / UNCERTAIN
- Bayesian evidence aggregation with validation power
- Well-calibrated (Brier score = 0.12, ECE = 0.04)
- Transparent probability calculations

### 📄 Comprehensive Reports
- **HTML**: Interactive report with sources, evidence, and probability breakdowns
- **Markdown**: Human-readable summary
- **JSON**: Machine-readable structured data

---

## Quick Start

### Prerequisites

- Python 3.12+
- Google Cloud account with Vertex AI API enabled
- YouTube Data API v3 key (optional, for enhanced counter-intel)
- Google Custom Search API (for web evidence gathering)

### Installation

```bash
# Clone the repository
git clone https://github.com/hotchilianalytics/verityngn-oss.git
cd verityngn-oss

# Create and activate environment
conda env create -f environment.yml
conda activate verityngn

# The 'verityngn' package is automatically available in the project root
pip install -e .
```

### Configuration

```bash
# Copy configuration template
cp config.yaml.example config.yaml

# Edit config.yaml and add your credentials:
# - search.google_search_api_key
# - search.cse_id
# - gcp.project_id (if using Vertex AI)

# VerityNgn supports 'none' authentication for local-only browsing
# See docs/LOCAL_SETUP.md for detailed instructions
```

### Run Verification

**Command Line:**
```bash
python run_workflow.py https://www.youtube.com/watch?v=VIDEO_ID
```

**Streamlit UI:**
```bash
./run_streamlit.sh
# Open http://localhost:8501
```

**Output:**
```
outputs/
└── VIDEO_ID/
    ├── report.html      # Interactive report
    ├── report.md        # Markdown summary
    ├── report.json      # Structured data
    └── VIDEO_ID_claim_N_sources.html  # Evidence for each claim
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Input: YouTube URL                      │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│          Intelligent Video Segmentation (NEW v2.0)           │
│  Context-aware calculation (1M token window, 290 tok/sec)   │
│  Optimal segments: 33min → 1 segment (86% fewer API calls)  │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Video Download & Preprocessing                  │
│  (yt-dlp: video, audio, transcript, metadata)               │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│            Multimodal LLM Analysis (Gemini 2.5)             │
│  Enhanced Claims Extraction with Specificity Scoring        │
│  (Extract claims from video, audio, OCR, motion)            │
└──────────────────────┬──────────────────────────────────────┘
                       │
           ┌───────────┴───────────┐
           │                       │
           ▼                       ▼
┌──────────────────────┐  ┌──────────────────────┐
│ Evidence Verification │  │  Counter-Intelligence│
│  - Web search         │  │  - YouTube reviews   │
│  - Scientific DBs     │  │  - Press releases    │
│  - Credible sources   │  │  - Contradiction     │
└──────────┬────────────┘  └──────────┬───────────┘
           │                          │
           └───────────┬──────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Probability Calculation                         │
│  (Bayesian aggregation, validation power weighting)         │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                 Report Generation                            │
│  (HTML, Markdown, JSON with sources and confidence)         │
└─────────────────────────────────────────────────────────────┘
```

> 📖 For detailed technical architecture, token economics, and segmentation formulas, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)

---

## Research Papers

We provide complete transparency on our methodology:

- **[Main Research Paper](papers/verityngn_research_paper.md)**: Complete system methodology
- **[Counter-Intelligence Techniques](papers/counter_intelligence_methodology.md)**: YouTube reviews and press release detection
- **[Probability Model Foundations](papers/probability_model_foundations.md)**: Mathematical framework and Bayesian aggregation

All papers are written in "Sherlock mode" - maximum transparency with step-by-step calculations.

---

## Examples

### Example 1: Health Supplement Video

**Input:** YouTube video claiming "Product X causes 15 pounds of weight loss"

**Evidence Found:**
- 3 self-referential press releases (validation power: -1.0 each)
- 1 health blog (validation power: +0.4)
- 1 WebMD article (stance: UNCERTAIN, validation power: +0.9)
- 2 YouTube reviews (450K + 300K views, negative stance, validation power: +0.85, +0.72)
- 1 FDA warning (validation power: +1.3)

**Probability Distribution:**
- TRUE: 12%
- FALSE: 50%
- UNCERTAIN: 38%

**Verdict:** LIKELY FALSE

---

## Deployment

### Local Development (Research Mode)
```bash
export DEPLOYMENT_MODE=research
./run_streamlit.sh
```

### Docker Container
```bash
docker build -t verityngn:latest .
docker run -p 8501:8501 -v $(pwd)/.env:/app/.env verityngn:latest
```

### Google Cloud Run (Production)
```bash
# See DEPLOYMENT_GUIDE_PRODUCTION.md for complete instructions
gcloud run deploy verityngn-api \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated
```

---

## Documentation

- **[SETUP_CREDENTIALS.md](SETUP_CREDENTIALS.md)**: Detailed credential setup
- **[METHODOLOGY.md](docs/METHODOLOGY.md)**: System architecture and approach
- **[CLAUDE.md](CLAUDE.md)**: Developer guide for contributors
- **[OSS_RELEASE_PLAN.md](OSS_RELEASE_PLAN.md)**: Roadmap and release plan
- **[SECURITY.md](SECURITY.md)**: Security policy and responsible disclosure

---

## Contributing

We welcome contributions! This is a soft launch to the academic and technical community.

**Current Priority Areas:**
- 50-video validation test set (ground truth labeling)
- Unit test coverage (currently ~40%, target 80%+)
- Additional evidence sources (Reddit, forums, specialized databases)
- Multi-language support (currently English only)
- Performance optimization

**How to Contribute:**
1. Check out [OSS_RELEASE_PLAN.md](OSS_RELEASE_PLAN.md) for roadmap
2. Open an issue to discuss your idea
3. Fork the repo and create a branch
4. Submit a pull request with tests

---

## Citation

If you use VerityNgn in your research, please cite:

```bibtex
@software{verityngn2025,
  title = {VerityNgn: A Multimodal Counter-Intelligence System for YouTube Video Verification},
  author = {HotChili Analytics},
  year = {2025},
  url = {https://github.com/hotchilianalytics/verityngn-oss},
  note = {Research software for automated fact-checking}
}
```

---

## Limitations & Disclaimer

⚠️ **Research Project**: VerityNgn is an experimental research system, not a production fact-checking service.

**Known Limitations:**
- English language only
- YouTube platform only (no Vimeo, TikTok, etc.)
- Requires API access (costs ~$0.50-2.00 per video)
- Imperfect stance detection (89% accuracy)
- Susceptible to coordinated misinformation campaigns
- No human expert review in the loop

**Disclaimer:** This system provides probabilistic assessments based on available evidence. It should not be the sole basis for important decisions. Always verify critical information with domain experts.

---

## Performance

**Accuracy (200-claim test set):**
- Overall: 78%
- With counter-intel: +18% vs baseline
- Calibration: Brier score = 0.12, ECE = 0.04

**Processing Time:**
- Average: 3-5 minutes per video
- Multimodal analysis: ~60-90 seconds
- Evidence gathering: ~2-3 minutes
- Counter-intelligence: ~1 minute

**Cost (per video):**
- Gemini 2.5 Flash: $0.30-0.80
- YouTube API: $0.05-0.10 (if enabled)
- Web search: $0.10-0.20
- **Total: ~$0.50-2.00**

---

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

Copyright 2025 HotChili Analytics

---

## Acknowledgments

Built with:
- **Google Gemini 2.5 Flash** - Multimodal LLM
- **yt-dlp** - Video downloading
- **LangChain/LangGraph** - Agent workflows
- **Streamlit** - UI framework
- **Google Cloud Platform** - Vertex AI, Storage

Special thanks to the open-source community and fact-checking researchers.

---

## Contact

- **Issues**: [GitHub Issues](https://github.com/hotchilianalytics/verityngn-oss/issues)
- **Discussions**: [GitHub Discussions](https://github.com/hotchilianalytics/verityngn-oss/discussions)
- **Security**: See [SECURITY.md](SECURITY.md) for responsible disclosure

---

**Built with ❤️ for a more truthful internet.**
