repo-seo 0.7.4
AI-powered GitHub repository SEO optimization using X Algorithm's recommendation pipeline
Requires Python: >=3.9
Keywords: ai, automation, git, github, llm, optimization, phoenix, recommendation-system, repository, seo, topics, trending, two-tower, x-algorithm

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

---

<p align="center">
  <b>⭐ Star this repo if it helps you!</b><br>
  <a href="https://github.com/chenxingqiang/repo-seo">https://github.com/chenxingqiang/repo-seo</a>
</p>