Skip to content

Getting Started - Overview

Welcome to Vows Social AI! This guide will help you understand the project and get up and running.

What You'll Learn

This section covers everything you need to start working with Vows Social:

  1. How It Works - Beautiful visual explanation of the system ⭐ Start here!
  2. Quick Start - Get the project running locally
  3. Architecture - High-level system design
  4. Free Tier Setup - Deploy on free services

For Non-Technical Users 👰🤵

Goal: Understand what the product does and why it's special

  1. Read How It Works - Plain English with visuals
  2. Skim the index page - Product overview
  3. Check Implementation Progress - What's built

For Developers 👨‍💻

Goal: Understand the architecture and start contributing

  1. Read How It Works - Understand the system flow
  2. Read Architecture - Technical design decisions
  3. Follow Quick Start - Run locally
  4. Check Development Guides - Git workflow, testing
  5. Review Backlog - What we're building

For ML Engineers 🧠

Goal: Understand the AI/ML components

  1. Read How It Works - System overview
  2. Deep dive: Architecture - ML architecture
  3. Review components:
  4. Foundation Model
  5. Thompson Sampling
  6. Multi-Agent System
  7. Check Modal Setup Guide - ML platform
  8. Read ADR-0005 - Why Modal

For Product Managers 📊

Goal: Understand product strategy and roadmap

  1. Read the PRD - Complete product requirements
  2. Read How It Works - User experience flow
  3. Review Implementation Roadmap - Phase plan
  4. Check RFC-0002 - Architecture decisions
  5. Review Backlog - Priorities

Documentation

Key Decisions

Development

Project Status

✅ Phase 0: Foundation (Complete)

  • Architecture designed
  • Platform chosen (Modal for ML/AI)
  • Admin console built (console.vows.social)
  • Comprehensive documentation
  • Legacy cleanup

🚧 Phase 1a: Core Implementation (In Progress)

  • Modal platform setup
  • GPU embedding pipeline (SigLIP 2)
  • Thompson Sampling orchestrator
  • Two-Tower model training
  • Qdrant integration

⏳ Phase 1b: Validation (Next)

  • User testing
  • Metrics collection
  • A/B testing framework
  • Performance optimization

🔮 Phase 2: Multi-Agent (Future)

  • Six specialized agents
  • Ray RLlib Multi-Agent PPO
  • LangSmith observability
  • Agent coordination

See Implementation Progress for detailed status.

Key Concepts

Core Technologies

Technology Purpose Why We Chose It
Modal ML platform Unified Python, GPU access, serverless
Two-Tower Model User/content understanding Industry-proven (Pinterest, YouTube)
Thompson Sampling Ranking algorithm Exploration/exploitation balance
SigLIP 2 Multimodal embeddings State-of-the-art 2025 model
Ray RLlib Multi-Agent RL OpenAI/DeepMind proven
LangSmith Observability Full agent tracing
Qdrant Vector database Semantic search
Supabase PostgreSQL User data & interactions

Key Principles

  1. 🧠 AI-First - Foundation model as source of truth
  2. 🤖 Multi-Agent - Specialized intelligence (Phase 2)
  3. 🎯 Thompson Sampling - Core ranking algorithm (KEPT)
  4. 🐍 Unified Stack - Python for all ML/AI
  5. 🔬 Observability - Full visibility (LangSmith)
  6. 💰 Free Tier - Validate before scaling
  7. 📊 Data-Driven - Learn from behavior
  8. 📚 Visual Docs - Plain English + diagrams

Common Questions

"Why Modal instead of Cloudflare Workers?"

Short answer: Modal is Python-native with GPU access. Perfect for ML/AI.

Detailed: See ADR-0005

  • Cloudflare Workers are JavaScript (our ML is Python)
  • Modal provides GPU for embeddings (A10G $0.30/hour)
  • Serverless like Workers but Python-first
  • Single platform vs CF Workers + Fly.io split

"What is Thompson Sampling?"

Short answer: A ranking algorithm that balances showing proven winners vs discovering new favorites.

Detailed: See Thompson Sampling Guide or How It Works

  • Used by Instagram, Pinterest, TikTok
  • Beta-Bernoulli bandit algorithm
  • Self-learning (no manual tuning)
  • Core algorithm (NOT removed)

"Do we need multi-agent complexity?"

Status: Open question in RFC-0002

TL;DR: Pinterest and YouTube don't use multi-agent crews. We're considering starting simple (Two-Tower + Thompson Sampling) and adding agents in Phase 2+ if data proves benefit.

"What's the free tier strategy?"

All services have generous free tiers:

Service Free Tier Cost After
Modal $30/month credits GPU usage ($0.30/hour A10G)
Qdrant 1GB free $25/month (4GB)
Supabase 500MB DB, 2GB bandwidth $25/month (8GB DB)
Vercel 100GB bandwidth $20/month (1TB)
LangSmith 5K traces/month $39/month (50K traces)

Total: $0/month until we hit limits, then ~$140/month

See Free Tier Setup for details.

Next Steps

1. Understand the System

👉 Read How It Works - Beautiful visual guide (recommended!)

2. Run Locally

👉 Follow Quick Start - Get code running

3. Explore Architecture

👉 Read Architecture - System design decisions

4. Start Contributing

👉 Check Backlog - Find a task 👉 Read Git Workflow - How we work

Ready? Let's dive into How It Works to see the magic! 🎨✨