Metadata-Version: 2.4
Name: seo-pilot
Version: 0.1.0
Summary: Self-improving SEO agent. Measures, acts, learns.
Author: Palicz91
License: MIT
License-File: LICENSE
Keywords: agent,automation,google-search-console,self-improving,seo
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: google-api-python-client>=2.0
Requires-Dist: google-auth>=2.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: sqlmodel>=0.0.14
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# seo-pilot

Self-improving SEO agent. Measures, acts, learns.

seo-pilot syncs your Google Search Console data, identifies what needs fixing, suggests concrete changes, and measures whether they worked. It's the closed feedback loop most SEO workflows are missing.

## What it does

1. **Syncs** GSC data daily (queries, pages, impressions, clicks, position)
2. **Analyzes** on a weekly and monthly schedule:
   - **Low hanging fruit**: pages with high impressions but low CTR for their position
   - **Content gaps**: queries where Google shows your site but you have no dedicated page
   - **Rising queries**: search terms growing >30% week-over-week
   - **Position drops**: pages losing ground (>2 positions)
3. **Suggests** concrete title/meta rewrites via LLM (Claude, OpenAI, Gemini, or Ollama)
4. **Tracks** every action in a queue with priority scoring
5. **Measures** the impact of your changes automatically and writes changelog entries
6. **Audits** internal links: finds orphan pages, broken links, missing product links

## What makes it different

Most SEO tools tell you what happened. seo-pilot tells you what to **do** and then checks if it **worked**.

- **Closed feedback loop**: change title → measure CTR after 14d → auto-log result
- **Action queue**: every finding becomes a trackable action with priority
- **Auto-changelog**: records before/after for every change with baseline metrics
- **Scoring engine**: prioritizes pages by impression volume, position, and CTR gap
- **Expert guidelines**: built-in 2026 SEO best practices (customizable)

## Quick start

```bash
# Install
pip install seo-pilot

# Interactive setup
seo-pilot init

# Check everything works
seo-pilot doctor

# Sync last 90 days of GSC data
seo-pilot sync --backfill

# Run your first review
seo-pilot review
```

## Requirements

- Python 3.10+
- Google Search Console access (service account)
- Optional: LLM API key (for title suggestions)
- Optional: Telegram/Slack (for notifications)

## Setup

### 1. Google Search Console credentials

Create a Google Cloud service account with Search Console API access:

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project (or use existing)
3. Enable "Google Search Console API"
4. Create a service account → download JSON key
5. Add the service account email as a user in your GSC property

Save the JSON key as `credentials.json` in your project root.

### 2. Configuration

```bash
seo-pilot init
```

This creates `config.yaml` with your settings. Or copy `config.example.yaml` and edit manually.

### 3. First sync

```bash
# Backfill 90 days of historical data
seo-pilot sync --backfill

# Run first analysis
seo-pilot review
```

## Commands

| Command | What it does |
|---------|-------------|
| `seo-pilot init` | Interactive setup, generates config.yaml |
| `seo-pilot doctor` | Checks config, GSC auth, DB, notifications |
| `seo-pilot sync` | Sync yesterday's GSC data |
| `seo-pilot sync --backfill` | Load last 90 days |
| `seo-pilot review` | Weekly review (28d vs prev 28d) |
| `seo-pilot review --monthly` | Monthly review (90d trend) |
| `seo-pilot audit links` | Internal linking audit via HTTP crawl |
| `seo-pilot actions list` | Show open actions |
| `seo-pilot actions resolve <id>` | Mark action as resolved |

## Review schedule

| Frequency | Window | What it covers |
|-----------|--------|---------------|
| Weekly | 28 days vs previous 28 days | LHF, content gaps, rising queries, drops, title suggestions |
| Monthly (1st week) | 90 days, month-by-month | Trend analysis, position movers, action queue summary, stale action escalation |

## How scoring works

Every low-hanging-fruit page gets a composite score (0-100):

| Factor | Weight | Example |
|--------|--------|---------|
| Impression volume | 30% | 200 imp = 30/30 |
| Position (5-15 sweet spot) | 25% | pos 8 = 25/25 |
| CTR gap vs expected | 25% | pos 3 + 0% CTR (expected 11%) = 25/25 |
| Title quality | 10% | question format + year = 10/10 |
| Content freshness | 10% | current year = 10/10 |

Score 85+ = urgent (fix today). Score 70+ = action this week.

Expected CTR benchmarks (2026):
- Position 1: 28%, Position 3: 11%, Position 5: 7%, Position 10: 3%

## LLM providers

seo-pilot uses an LLM to generate title/meta suggestions. Supported providers:

| Provider | Config value | Model examples |
|----------|-------------|----------------|
| Google Gemini | `gemini` | gemini-2.0-flash |
| Anthropic Claude | `claude` | claude-sonnet-4-6 |
| OpenAI | `openai` | gpt-4o |
| Ollama (local) | `ollama` | llama3, mistral |

Title suggestions are optional. The analysis runs without an LLM.

## Internal linking audit

```bash
seo-pilot audit links
```

Crawls your site via HTTP (no headless browser needed), maps all internal links, and identifies:
- **Orphan pages**: pages with zero inbound internal links
- **Broken links**: internal links pointing to 404s
- **Missing product links**: blog posts without a link to pricing/conversion pages
- **Cluster mapping**: groups pages into topic clusters

Output: `linking-map.md` in your project root.

## Docker

```bash
# Build
docker build -t seo-pilot .

# Run a review
docker run -v ./config.yaml:/app/config.yaml \
           -v ./credentials.json:/app/credentials.json \
           -e TELEGRAM_BOT_TOKEN=xxx \
           -e GEMINI_API_KEY=xxx \
           seo-pilot review
```

Or with docker-compose:

```bash
docker-compose run seo-pilot review
```

## Guidelines

seo-pilot includes default SEO guidelines at `guidelines/default.md`. These encode 2026 best practices for title tags, meta descriptions, content scoring, and internal linking.

Customize by editing the file or pointing to your own:

```yaml
guidelines:
  path: "./my-guidelines.md"
```

Guidelines should be refreshed quarterly. The scoring engine reads thresholds from the guidelines.

## File structure

```
seo-pilot/
├── config.yaml              # Your config (gitignored)
├── config.example.yaml      # Template
├── credentials.json          # GSC service account (gitignored)
├── seo-pilot.db             # SQLite database (gitignored)
├── guidelines/
│   └── default.md           # SEO best practices
├── templates/
│   ├── weekly_report.j2     # Weekly report template
│   └── monthly_report.j2    # Monthly report template
├── seo_pilot/
│   ├── cli.py               # CLI commands
│   ├── config.py            # Config loader
│   ├── gsc_client.py        # Google Search Console API
│   ├── storage.py           # SQLite/Postgres storage
│   ├── analyzer.py          # Analysis engine
│   ├── changelog.py         # Auto-changelog
│   ├── linking_audit.py     # Internal link crawler
│   ├── notifier.py          # Telegram/Slack/webhook
│   ├── llm.py               # LLM title suggestions
│   └── reporter.py          # Report generator
└── docs/
    └── architecture.md      # System design
```

## Roadmap

- [x] v0.1 — Core: GSC sync, analysis, action queue, changelog, CLI
- [ ] v0.2 — MCP server mode (use from Claude Code directly)
- [ ] v0.2 — Web dashboard (lightweight, static HTML)
- [ ] v0.2 — OAuth support (not just service account)
- [ ] v0.2 — Slack + Discord notifications
- [ ] v0.3 — Competitor watch plugin
- [ ] v0.3 — WordPress/CMS content discovery

## Contributing

Contributions welcome. Please open an issue first to discuss what you'd like to change.

```bash
# Development setup
git clone https://github.com/Palicz91/seo-pilot.git
cd seo-pilot
pip install -e ".[dev]"
pytest
```

## License

MIT
