repo-seo 0.6.0

AI-powered GitHub repository SEO optimization using X Algorithm's recommendation pipeline

repo-seo

AI-powered tool to optimize GitHub repositories for better discoverability through improved descriptions, topics, and README content.

Architecture

Inspired by the X Algorithm's recommendation pipeline, repo-seo uses a composable pipeline architecture:

┌─────────────────────────────────────────────────────────────────────┐
│                      SEO OPTIMIZATION PIPELINE                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐   │
│   │ Sources  │────▶│Hydrators │────▶│ Filters  │────▶│ Scorers  │   │
│   │          │     │          │     │          │     │          │   │
│   │ Local    │     │ README   │     │ Quality  │     │ README   │   │
│   │ GitHub   │     │ Language │     │ Dedup    │     │ Topic    │   │
│   └──────────┘     │ Keywords │     │ Relevance│     │ SEO      │   │
│                    └──────────┘     └──────────┘     └──────────┘   │
│                                                             │        │
│                                                             ▼        │
│                                                      ┌──────────┐   │
│                                                      │ Selector │   │
│                                                      │  Top-K   │   │
│                                                      └──────────┘   │
│                                                             │        │
└─────────────────────────────────────────────────────────────│────────┘
                                                              ▼
                                                    Optimized Results

Features

• Auto-Apply SEO: Directly update GitHub topics & description with repo-seo suggest --apply
• Phoenix SEO: X Algorithm's Two-Tower + Multi-Action ranking for topic recommendations
• Pipeline Architecture: Composable sources, hydrators, filters, scorers, selectors
• Dynamic Trending Topics: Real-time GitHub trending keywords matching
• README Analysis: Section ordering suggestions, keyword optimization
• AI-Powered Analysis: OpenAI, Anthropic Claude, DeepSeek support
• Multi-Signal Scoring: README quality, topic relevance, trending score
• Rule-Based Fallback: Works without API keys

Installation

# Install from source
pip install -e .

# With AI provider support
pip install -e ".[all]"

Quick Start

Using the Pipeline (Recommended)

from repo_seo import (
    Pipeline, Query,
    LocalRepoSource,
    ReadmeHydrator,
    ReadmeScorer, TopicScorer,
    TopKSelector,
)
from repo_seo.pipeline import QualityFilter, DuplicateFilter

# Create optimization pipeline
pipeline = Pipeline(
    sources=[LocalRepoSource()],
    hydrators=[ReadmeHydrator()],
    pre_filters=[QualityFilter(), DuplicateFilter()],
    scorers=[ReadmeScorer(), TopicScorer()],
    selector=TopKSelector(k=10),
)

# Run optimization
query = Query(repo_path="./my-project", repo_name="my-project")
results = pipeline.run(query)

# Process results
for candidate in results:
    print(f"{candidate.type}: {candidate.id} (score: {candidate.final_score:.1f})")

Command Line

# SEO suggestions with README/topic analysis + auto-apply to GitHub
repo-seo suggest --top-k 10
repo-seo suggest --apply  # Actually update GitHub topics & description

# Phoenix SEO recommendations (X Algorithm style)
repo-seo phoenix --detailed

# Get trending topic suggestions
repo-seo trending --language python

# Analyze current repository
repo-seo analyze

# Optimize with AI
repo-seo optimize --repo-path . --provider openai

Auto-Apply SEO Changes

The suggest command analyzes your repo and can directly update GitHub:

# Preview suggestions
repo-seo suggest --top-k 8

# Apply changes to GitHub (updates topics + description)
repo-seo suggest --apply

Output:

📝 README Optimization Suggestions:
  1. Add [installation]: Include installation instructions
  2. Add status badges (build, coverage, version, license)

🏷️ Topic Keywords (Priority Order):
  🔥 1. api (score: 84 +20)        # +20 = content match boost
  🔥 2. machine-learning (score: 82 +20)
  📊 3. cli (score: 65)

📋 Description Optimization:
  Current:   My project...
  Suggested: AI-powered tool for X. Built with Python. Features api support.

🚀 Applying Changes to GitHub
  ✅ Topics updated successfully!
  ✅ Description updated successfully!

Simple API

from repo_seo import RepoAnalyzer

repo_info = {
    "name": "my-project",
    "description": "A sample project",
    "languages": ["Python"],
    "topics": ["python", "cli"],
    "readme": "# My Project\n\nDescription here.",
}

analyzer = RepoAnalyzer(repo_info)
results = analyzer.analyze()
print(f"SEO Score: {results['score']}/100")

Phoenix SEO (X Algorithm Style)

Topic recommendation using X Algorithm's Two-Tower architecture with Multi-Action User Behavior Prediction:

┌─────────────────────────────────────────────────────────────────┐
│                     PHOENIX SEO PIPELINE                        │
├─────────────────────────────────────────────────────────────────┤
│   ┌─────────────────┐              ┌─────────────────────────┐  │
│   │  REPO TOWER     │              │  TRENDING TOWER         │  │
│   │  (Your Repo)    │              │  (GitHub LIVE)          │  │
│   │  README         │   Dot        │  Trending Repos Topics  │  │
│   │  Description    │─ Product ───▶│  Featured Topics        │  │
│   │  Languages      │              │  (Real-time from API)   │  │
│   └─────────────────┘              └─────────────────────────┘  │
│            │                                    │               │
│            └────────────┬───────────────────────┘               │
│                         ▼                                       │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │         MULTI-ACTION USER BEHAVIOR PREDICTION            │   │
│   │  ┌────────────────────────┬────────────────────────────┐│   │
│   │  │ POSITIVE ACTIONS       │ NEGATIVE ACTIONS           ││   │
│   │  │ ⭐ P(star)             │ ⛔ P(ignore)               ││   │
│   │  │ 🍴 P(fork)             │ 🚫 P(report)               ││   │
│   │  │ 👆 P(click)            │                            ││   │
│   │  │ 👁️ P(watch)            │                            ││   │
│   │  │ 📥 P(clone)            │                            ││   │
│   │  │ 🤝 P(contribute)       │                            ││   │
│   │  └────────────────────────┴────────────────────────────┘│   │
│   │  Final Score = Σ(weight × P(positive)) - Σ(weight × P(negative))│
│   └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

from repo_seo.pipeline import PhoenixSEO, phoenix_recommend

# Quick recommendation with user behavior prediction
recommendations = phoenix_recommend(
    readme=open("README.md").read(),
    languages=["Python"],
)

for rec in recommendations:
    print(f"{rec['topic']}: Score={rec['final_score']}")
    actions = rec['action_scores']
    print(f"  ⭐ P(star)={actions['star']}  🍴 P(fork)={actions['fork']}")
    print(f"  👆 P(click)={actions['click']}  👁️ P(watch)={actions['watch']}")
    print(f"  ⛔ P(ignore)={actions['ignore']}")

CLI with detailed predictions:

repo-seo phoenix --detailed

Trending Topics

Dynamic matching with GitHub's trending keywords:

from repo_seo.pipeline import TrendingTopicSuggester, get_trending_topics

# Get trending topics for Python
topics = get_trending_topics("python", max_topics=10)
print(topics)  # ['machine-learning', 'fastapi', 'langchain', ...]

# Get personalized suggestions for your repo
suggester = TrendingTopicSuggester()
suggestions = suggester.suggest(
    repo_path="./my-project",
    current_topics=["python", "cli"],
    languages=["Python"],
    readme_content=open("README.md").read(),
)

for s in suggestions:
    print(f"{s['topic']}: {s['combined_score']:.1f}")

Pipeline Components

Component	Description
Source	Fetches candidates (LocalRepoSource, GitHubTrendingSource)
Hydrator	Enriches with features (ReadmeHydrator, TrendingHydrator)
Filter	Removes invalid items (QualityFilter, DuplicateFilter)
Scorer	Computes scores (ReadmeScorer, TopicScorer, TrendingScorer)
Selector	Picks top candidates (TopKSelector, DiversitySelector)

Configuration

# Set API keys
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

Development

pip install -e ".[dev]"
pytest
black repo_seo/
ruff check repo_seo/

License

MIT License - see LICENSE for details.