Skip to content

getting-started.md

Latest commit

 

History

History
249 lines (183 loc) · 6.3 KB

getting-started.md

File metadata and controls

249 lines (183 loc) · 6.3 KB
Raw

Getting Started 🚀

This guide will help you set up and run your first analysis with Lipsync Investigation.

Table of Contents

Prerequisites

Before you begin, ensure you have the following:

System Requirements

  • Node.js: Version 22.0.0 or higher 
    node --version  # Should show v22.0.0 or higher
  • Docker: Version 20.10 or higher (recommended) 
    docker --version  # Should show 20.10 or higher
docker compose --version  # Should show 2.0 or higher

API Keys Required

You'll need API keys for the services you want to use:

GitHub Personal Access Token (Required)

  1. Go to GitHub Settings > Developer settings > Personal access tokens
  2. Click "Generate new token (classic)"
  3. Select scopes:
    • repo:read (for private repositories)
    • public_repo (for public repositories)
  4. Copy the generated token (starts with ghp_)

LLM API Key (Required for AI Analysis)

Choose one of the following:

Option A: OpenAI API Key

  1. Go to OpenAI API Keys
  2. Create a new secret key
  3. Copy the key (starts with sk-)

Option B: OpenRouter API Key

  1. Go to OpenRouter Dashboard
  2. Create a new API key
  3. Copy the key (starts with sk-or-)

Installation

Method 1: Docker Installation (Recommended)

Docker provides the easiest and most reliable setup:

  1. Clone the repository

    git clone https://github.com/428lab/lipsync-investigation.git
cd lipsync-investigation

  2. Verify Docker is running

    docker --version
docker compose --version

  3. You're ready! Skip to Environment Configuration

Method 2: Local Installation

If you prefer to run locally without Docker:

  1. Clone the repository

    git clone https://github.com/428lab/lipsync-investigation.git
cd lipsync-investigation

  2. Install dependencies

    npm install

  3. Build the project

    npm run build

  4. Verify installation

    npm start --help  # Should show usage information

Environment Configuration

Create and configure your environment file:

  1. Copy the example environment file

    cp env.example .env

  2. Edit the .env file with your API keys:

    # Required: GitHub Personal Access Token
GITHUB_TOKEN=ghp_your_github_token_here

# Required: Choose one LLM provider
OPENAI_API_KEY=sk-your_openai_key_here
# OR
OPENROUTER_API_KEY=sk-or-your_openrouter_key_here

# Optional: Logging level (error|warn|info|debug)
LOG_LEVEL=info

  3. Verify your configuration

    # Check that your .env file is properly formatted
cat .env

First Run

Using Docker (Recommended)

  1. Start the analysis

    docker compose up

  2. Monitor progress

    # In another terminal, watch the logs
docker compose logs -f

  3. Check results

    # Wait for completion, then check output
ls output/
head output/lipsync_models_analysis.csv

Using Local Installation

  1. Start the analysis

    npm start

  2. Monitor progress

    # Watch the log file in another terminal
tail -f output/lipsync-investigation.log

  3. Check results

    # Wait for completion, then check output
ls output/
head output/lipsync_models_analysis.csv

Verifying Setup

Check API Connectivity

The tool will automatically verify your API keys when it starts. Look for these messages in the logs:

✅ GitHub API connection successful
✅ LLM API connection successful

Verify Output Generation

After a successful run, you should see:

  1. CSV file created

    ls -la output/lipsync_models_analysis.csv
# Should show a file with recent timestamp

  2. Log file generated

    ls -la output/lipsync-investigation.log
# Should show a file with execution logs

  3. Sample data in CSV

    head -5 output/lipsync_models_analysis.csv
# Should show header row and some data rows

Expected First Run Behavior

Your first run will:

  1. Search GitHub for lip-sync repositories (takes 1-2 minutes)
  2. Analyze repositories using AI and heuristics (takes 5-15 minutes depending on repository count)
  3. Generate CSV output with analysis results
  4. Create log file with detailed execution information

Typical first run time: 10-20 minutes for 50-100 repositories

Next Steps

Now that you have Lipsync Investigation running, explore these resources:

📖 Documentation

  • Configuration Guide - Customize search queries and analysis settings
  • Usage Guide - Learn about different workflows and output interpretation
  • Examples - See practical examples and use cases

🎯 Common Next Steps

  1. Customize your search - Edit config.json to focus on specific types of repositories
  2. Adjust analysis fields - Enable/disable specific analysis metrics
  3. Set performance mode - Choose between Fast, Balanced, or Accurate analysis
  4. Explore results - Import CSV into Excel, Google Sheets, or data analysis tools

🔧 Troubleshooting

If you encounter issues:

  1. Check the logs - Look at output/lipsync-investigation.log for error messages
  2. Verify API keys - Ensure your tokens are valid and have proper permissions
  3. Check network - Ensure you have internet connectivity
  4. See Troubleshooting Guide - Common issues and solutions

💡 Tips for Success

  • Start small - Use the default configuration for your first run
  • Monitor progress - Watch the logs to understand what's happening
  • Be patient - Analysis can take time, especially with many repositories
  • Check results - Review the CSV output to understand the analysis quality

Ready to dive deeper? Check out the Configuration Guide to customize your analysis!