https://github.com/chenxingqiang/repo-seo

🚀 AI-powered GitHub SEO: Boost repo discoverability with X Algorithm's Two-Tower recommendation. Topics, README optimization & user behavior prediction.
https://github.com/chenxingqiang/repo-seo
ai api automation bash cli developer-tools development discoverability github-seo langchain library markdown openai optimization python recommendation-system repo seo tool
Last synced: 2 days ago
JSON representation
🚀 AI-powered GitHub SEO: Boost repo discoverability with X Algorithm's Two-Tower recommendation. Topics, README optimization & user behavior prediction.
Host: GitHub
URL: https://github.com/chenxingqiang/repo-seo
Owner: chenxingqiang
License: mit
Created: 2025-01-09T08:48:38.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2026-01-27T17:54:07.000Z (6 months ago)
Last Synced: 2026-01-28T03:41:46.718Z (6 months ago)
Topics: ai, api, automation, bash, cli, developer-tools, development, discoverability, github-seo, langchain, library, markdown, openai, optimization, python, recommendation-system, repo, seo, tool
Language: Python
Homepage:
Size: 1.32 MB
Stars: 2
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

          # repo-seo

[![PyPI version](https://badge.fury.io/py/repo-seo.svg)](https://pypi.org/project/repo-seo/)

[![Downloads](https://static.pepy.tech/badge/repo-seo)](https://pepy.tech/project/repo-seo)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)

[![GitHub stars](https://img.shields.io/github/stars/chenxingqiang/repo-seo?style=social)](https://github.com/chenxingqiang/repo-seo)

🚀 **AI-powered GitHub SEO** - Boost your repository's discoverability using **X Algorithm's Two-Tower recommendation system**. Optimize topics, README, and descriptions with user behavior prediction.

## 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

```bash

# Using uv (recommended - fastest)

uv pip install repo-seo

# Or run directly without installing

uvx repo-seo suggest

# Using pip

pip install repo-seo

# Install from source (for development)

git clone https://github.com/chenxingqiang/repo-seo.git

cd repo-seo

uv pip install -e ".[dev]"  # or: pip install -e ".[dev]"

```

## Quick Start

### Using the Pipeline (Recommended)

```python

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

```bash

# 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:

```bash

# 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

```python

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))│

│   └─────────────────────────────────────────────────────────┘   │

└─────────────────────────────────────────────────────────────────┘

```

```python

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:**

```bash

repo-seo phoenix --detailed

```

## Trending Topics

Dynamic matching with GitHub's trending keywords:

```python

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) |

## Find Similar Excellent Repos

Learn from top GitHub repos (5000+ stars) to optimize your topics:

```bash

# Find repos similar to yours and get topic recommendations

repo-seo similar --top-k 10

```

```

Similar repos:

  1. donnemartin/system-design-primer  333,552⭐  ████████████████████ 0.5148

  2. huggingface/transformers          155,819⭐  ███████████████████░ 0.4866

Recommended topics from similar repos:

  1. awesome (used by HelloGitHub, awesome-python)

  2. deep-learning (used by transformers, tensorflow)

```

## Real-time Monitoring

Run a background daemon to track stars, forks, and downloads:

```bash

# Start background monitor (checks every 5 min)

repo-seo monitor --start --interval 300

# Check current metrics

repo-seo monitor

# Check monitor status

repo-seo monitor --status

# View history

repo-seo monitor --history

# Stop monitor

repo-seo monitor --stop

```

## CLI Commands

| Command | Description |

|---------|-------------|

| `repo-seo suggest --apply` | Analyze & auto-apply SEO to GitHub |

| `repo-seo phoenix --detailed` | User behavior prediction (star/fork/click) |

| `repo-seo monitor --start` | Start background monitoring daemon |

| `repo-seo mcp-server` | Start MCP server for AI assistants |

| `repo-seo retrieval` | Two-Tower retrieval visualization |

| `repo-seo similar` | Find similar excellent repos |

| `repo-seo trending` | Get trending topic suggestions |

| `repo-seo corpus` | Build repo embedding corpus |

## MCP Server (AI Assistant Integration)

Use repo-seo as an MCP server for AI assistants like Claude in Cursor:

**1. Add to Cursor MCP config (`~/.cursor/mcp.json`):**

```json

{

  "mcpServers": {

    "repo-seo": {

      "command": "repo-seo",

      "args": ["mcp-server"]

    }

  }

}

```

**2. Available MCP Tools:**

| Tool | Description |

|------|-------------|

| `repo_seo_suggest` | Get SEO optimization suggestions |

| `repo_seo_phoenix` | Run Two-Tower + behavior prediction |

| `repo_seo_trending` | Get trending topics |

| `repo_seo_similar` | Find similar excellent repos |

| `repo_seo_monitor` | Check metrics and monitoring |

| `repo_seo_analyze` | Analyze README quality |

| `repo_seo_set_api_key` | Set API key (OPENAI, ANTHROPIC, etc.) |

| `repo_seo_get_config` | View current configuration |

| `repo_seo_list_providers` | List LLM providers and status |

| `repo_seo_delete_api_key` | Remove a stored API key |

| `repo_seo_github_auth` | Check/set GitHub authentication |

**3. Or run standalone:**

```bash

repo-seo mcp-server

# or

repo-seo-mcp

```

## Configuration

```bash

# Set API keys (optional - works without them)

export OPENAI_API_KEY=sk-...

export ANTHROPIC_API_KEY=sk-ant-...

```

## Development

```bash

pip install -e ".[dev]"

pytest

ruff check repo_seo/

```

## Contributing

Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

## License

MIT License - see [LICENSE](LICENSE) for details.

---



  ⭐ Star this repo if it helps you!


  https://github.com/chenxingqiang/repo-seo
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/chenxingqiang/repo-seo

Awesome Lists containing this project

README
