Metadata-Version: 2.4
Name: repo-seo
Version: 0.6.0
Summary: AI-powered GitHub repository SEO optimization using X Algorithm's recommendation pipeline
Project-URL: Homepage, https://github.com/chenxingqiang/repo-seo
Project-URL: Documentation, https://github.com/chenxingqiang/repo-seo#readme
Project-URL: Repository, https://github.com/chenxingqiang/repo-seo
Project-URL: Issues, https://github.com/chenxingqiang/repo-seo/issues
Author-email: Chen Xingqiang <chenxingqiang@turingai.cc>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,automation,git,github,llm,optimization,phoenix,recommendation-system,repository,seo,topics,trending,two-tower,x-algorithm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.5.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.5.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

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

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

```bash
# Install from source
pip install -e .

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

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

## Configuration

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

## Development

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

## License

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