Skip to content

api-reference.md

Latest commit

 

History

History
484 lines (405 loc) · 15.5 KB

api-reference.md

File metadata and controls

484 lines (405 loc) · 15.5 KB
Raw

API Reference 📚

Complete reference for all configuration options, environment variables, and output fields in Lipsync Investigation.

Table of Contents

Configuration Schema

Complete config.json Structure

{
  "github": {
    "searchQueries": ["string"],
    "maxRepositories": "number",
    "rateLimitDelay": "number"
  },
  "llm": {
    "provider": "string",
    "model": "string",
    "maxTokens": "number",
    "temperature": "number",
    "contextLimit": "number",
    "fields": {
      "license": "boolean",
      "docker_support": "boolean",
      "video_input_support": "boolean",
      "is_lipsync_model": "boolean",
      "code_quality_score": "boolean",
      "documentation_quality": "boolean",
      "maintenance_status": "boolean",
      "has_pretrained_models": "boolean",
      "issue_response_quality": "boolean",
      "model_architecture_type": "boolean",
      "training_framework": "boolean",
      "inference_ready": "boolean",
      "dataset_requirements": "boolean",
      "gpu_requirements": "boolean",
      "paper_associated": "boolean",
      "demo_available": "boolean",
      "commercial_viability": "boolean",
      "research_novelty_score": "boolean",
      "audio_processing_support": "boolean",
      "real_time_capable": "boolean",
      "inference_speed_estimate": "boolean",
      "model_size_category": "boolean",
      "multi_speaker_support": "boolean",
      "emotion_control": "boolean",
      "3d_awareness": "boolean",
      "training_data_scale": "boolean",
      "reproducibility_score": "boolean",
      "community_activity_score": "boolean"
    }
  },
  "output": {
    "csvFilename": "string",
    "includeColumns": ["string"]
  },
  "analysis": {
    "enableLLMAnalysis": "boolean",
    "enableHeuristicAnalysis": "boolean",
    "maxConcurrentRequests": "number",
    "requestTimeout": "number"
  },
  "performance": {
    "mode": "string",
    "enableContextEnrichment": "boolean",
    "enableMultiPassAnalysis": "boolean",
    "enableValidation": "boolean",
    "enableCaching": "boolean",
    "maxFileFetches": "number",
    "skipMissingFiles": "boolean",
    "parallelFileFetches": "boolean"
  }
}

GitHub Configuration

Field Type Required Default Description
searchQueries string[] Yes - Array of GitHub search queries
maxRepositories number No 2000 Maximum repositories to analyze
rateLimitDelay number No 1000 Delay between API calls (ms)

Example:

{
  "github": {
    "searchQueries": [
      "\"lip sync\" OR \"talk face\" stars:>=100",
      "\"facial animation\" created:>=2024-01-01 stars:>=50"
    ],
    "maxRepositories": 500,
    "rateLimitDelay": 1500
  }
}

LLM Configuration

Field Type Required Default Description
provider string Yes - LLM provider ("openai" or "openrouter")
model string Yes - Model identifier
maxTokens number No 2000 Maximum tokens per request
temperature number No 0.0 Response randomness (0.0-2.0)
contextLimit number No 1000000 Maximum context size
fields object No - Analysis field configuration

Example:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "maxTokens": 2000,
    "temperature": 0.0,
    "contextLimit": 1000000,
    "fields": {
      "license": true,
      "docker_support": true,
      "is_lipsync_model": true,
      "code_quality_score": true
    }
  }
}

Output Configuration

Field Type Required Default Description
csvFilename string Yes - Output CSV filename
includeColumns string[] Yes - Columns to include in output

Example:

{
  "output": {
    "csvFilename": "lipsync_analysis.csv",
    "includeColumns": [
      "model_name",
      "github_url",
      "github_stars",
      "is_lipsync_model",
      "code_quality_score",
      "confidence"
    ]
  }
}

Analysis Configuration

Field Type Required Default Description
enableLLMAnalysis boolean No true Enable AI-powered analysis
enableHeuristicAnalysis boolean No true Enable rule-based analysis
maxConcurrentRequests number No 3 Parallel repository analyses
requestTimeout number No 60000 Request timeout (ms)

Example:

{
  "analysis": {
    "enableLLMAnalysis": true,
    "enableHeuristicAnalysis": true,
    "maxConcurrentRequests": 2,
    "requestTimeout": 120000
  }
}

Performance Configuration

Field Type Required Default Description
mode string No "fast" Performance mode ("fast", "balanced", "accurate")
enableContextEnrichment boolean No false Fetch additional repository context
enableMultiPassAnalysis boolean No false Use multiple LLM passes
enableValidation boolean No true Validate LLM responses
enableCaching boolean No true Enable response caching
maxFileFetches number No 3 Maximum files to fetch per repo
skipMissingFiles boolean No true Skip 404 errors for missing files
parallelFileFetches boolean No true Fetch files in parallel

Example:

{
  "performance": {
    "mode": "balanced",
    "enableContextEnrichment": true,
    "enableMultiPassAnalysis": false,
    "enableValidation": true,
    "enableCaching": true,
    "maxFileFetches": 5,
    "skipMissingFiles": false,
    "parallelFileFetches": true
  }
}

Environment Variables

Required Variables

Variable Description Example
GITHUB_TOKEN GitHub Personal Access Token ghp_xxxxxxxxxxxxxxxxxxxx

LLM Provider Variables (Choose One)

Variable Description Example
OPENAI_API_KEY OpenAI API Key sk-xxxxxxxxxxxxxxxxxxxx
OPENROUTER_API_KEY OpenRouter API Key sk-or-xxxxxxxxxxxxxxxxxxxx

Optional Variables

Variable Description Default Example
LOG_LEVEL Logging level info debug, info, warn, error

Environment File Example

# 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
LOG_LEVEL=info

Output Fields

Core Fields

Field Type Description Example
model_name string Repository full name "owner/repo-name"
published_month string Creation date (YYYY-MM) "2024-01"
license string License identifier "MIT", "Apache-2.0", "N/A"
github_url string Repository URL "https://github.com/owner/repo"
github_stars number Star count 150
confidence number Analysis confidence (0-1) 0.85
reasoning string Analysis reasoning "Strong evidence of..."

Capability Fields

Field Type Values Description
docker_support string "yes", "no", "N/A" Docker containerization support
video_input_support string "yes", "no", "N/A" Video file processing capability
is_lipsync_model string "yes", "no", "N/A" Contains runnable lip-sync model
has_pretrained_models string "yes", "no", "N/A" Has downloadable models
inference_ready string "yes", "no", "N/A" Production-ready inference
audio_processing_support string "yes", "no", "N/A" Audio processing capability
real_time_capable string "yes", "no", "uncertain", "N/A" Real-time performance
multi_speaker_support string "yes", "no", "N/A" Multiple speaker support
emotion_control string "yes", "no", "N/A" Emotion/expression control
3d_awareness string "yes", "no", "N/A" 3D-aware processing

Quality Fields

Field Type Values Description
code_quality_score number 0-10 Code quality rating
documentation_quality string "poor", "fair", "good", "excellent", "N/A" Documentation quality
maintenance_status string "active", "maintained", "stale", "abandoned", "N/A" Project maintenance
issue_response_quality string "poor", "fair", "good", "excellent", "N/A" Issue response quality
reproducibility_score number 0-10 Reproducibility rating
community_activity_score number 0-10 Community activity rating

Technical Fields

Field Type Values Description
model_architecture_type string Architecture name "GAN", "Diffusion", "Transformer", "N/A"
training_framework string Framework name "PyTorch", "TensorFlow", "JAX", "N/A"
dataset_requirements string Dataset info "VoxCeleb", "custom", "N/A"
gpu_requirements string "low", "medium", "high", "N/A" GPU resource needs
inference_speed_estimate string "slow", "medium", "fast", "N/A" Inference speed
model_size_category string "small", "medium", "large", "xlarge", "N/A" Model size
training_data_scale string "small", "medium", "large", "N/A" Training data size

Research Fields

Field Type Values Description
paper_associated string "yes", "no", "N/A" Has research paper
demo_available string "yes", "no", "N/A" Has live demo
commercial_viability string "yes", "no", "uncertain", "N/A" Commercial viability
research_novelty_score number 0-10 Research novelty rating

Metadata Fields

Field Type Description Example
open_issues_count number Number of open issues 25

Analysis Fields

Field Categories

Core Analysis Fields

  • license - Repository license detection
  • docker_support - Containerization support
  • video_input_support - Video processing capability
  • is_lipsync_model - Primary classification

Quality Assessment Fields

  • code_quality_score - Code quality rating (0-10)
  • documentation_quality - Documentation assessment
  • maintenance_status - Project maintenance status
  • issue_response_quality - Community responsiveness

Technical Analysis Fields

  • model_architecture_type - ML architecture identification
  • training_framework - Framework detection
  • inference_ready - Production readiness
  • gpu_requirements - Resource requirements

Research Evaluation Fields

  • paper_associated - Research publication link
  • demo_available - Live demonstration availability
  • commercial_viability - Commercial use assessment
  • research_novelty_score - Innovation rating (0-10)

Extended Analysis Fields

  • audio_processing_support - Audio processing capability
  • real_time_capable - Real-time performance
  • inference_speed_estimate - Performance estimation
  • model_size_category - Model size classification
  • multi_speaker_support - Multi-speaker capability
  • emotion_control - Expression control
  • 3d_awareness - 3D processing capability
  • training_data_scale - Training data size
  • reproducibility_score - Reproducibility rating (0-10)
  • community_activity_score - Community engagement (0-10)

Field Configuration

Enable/disable specific analysis fields in config.json:

{
  "llm": {
    "fields": {
      "license": true,
      "docker_support": true,
      "video_input_support": true,
      "is_lipsync_model": true,
      "code_quality_score": true,
      "documentation_quality": false,
      "maintenance_status": false,
      "model_architecture_type": true,
      "training_framework": false
    }
  }
}

GitHub Search Syntax

Basic Search Operators

Operator Description Example
"exact phrase" Exact phrase match "lip sync"
OR Logical OR "lip sync" OR "talk face"
AND Logical AND "pytorch" AND "lip sync"
NOT Logical NOT "lip sync" NOT "demo"

Search Qualifiers

Qualifier Description Example
in:name Search in repository name "lip sync" in:name
in:description Search in description "facial animation" in:description
in:readme Search in README "installation" in:readme
in:name,description,readme Search in multiple fields "lip sync" in:name,description,readme

Filter Qualifiers

Qualifier Description Example
stars:>=N Minimum star count stars:>=100
stars:<=N Maximum star count stars:<=1000
created:>=YYYY-MM-DD Created after date created:>=2024-01-01
created:<=YYYY-MM-DD Created before date created:<=2024-12-31
language:LANG Programming language language:python
license:LICENSE License type license:mit

Advanced Search Examples

{
  "searchQueries": [
    // Recent high-quality lip-sync repositories
    "\"lip sync\" OR \"talk face\" created:>=2024-01-01 stars:>=100 in:name,description,readme",
    
    // Python-based facial animation tools
    "\"facial animation\" language:python stars:>=50",
    
    // PyTorch lip-sync models
    "\"pytorch\" AND (\"lip sync\" OR \"talk face\") stars:>=200",
    
    // Research repositories with papers
    "\"lip sync\" AND \"paper\" stars:>=50",
    
    // Commercial-friendly licenses
    "(\"lip sync\" OR \"talk face\") license:mit stars:>=100"
  ]
}

LLM Models

OpenAI Models

Model Best For Cost Speed Accuracy
gpt-4o High accuracy analysis High Medium Very High
gpt-4o-mini Balanced performance Medium Fast High
gpt-4-turbo Complex analysis High Medium Very High
gpt-4 Legacy high accuracy High Slow Very High

OpenRouter Models

Model Best For Cost Speed Accuracy
openai/gpt-oss-120b High accuracy Medium Medium Very High
anthropic/claude-3-5-sonnet-20241022 Complex reasoning Medium Medium Very High
anthropic/claude-3-5-haiku-20241022 Fast analysis Low Fast High
google/gemini-1.5-pro Balanced performance Medium Medium High

Model Selection Guide

For Cost-Effective Analysis:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  }
}

For High Accuracy:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o"
  }
}

For Balanced Performance:

{
  "llm": {
    "provider": "openrouter",
    "model": "openai/gpt-oss-120b"
  }
}

Configuration Examples: See the Examples guide for complete working configurations.