seo-pilot 0.1.0__tar.gz

seo_pilot-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Config and secrets
+config.yaml
+credentials.json
+*.db
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Data
+data/
+*.json
+!config.example.yaml
+!guidelines/*.md
+!templates/*.j2

seo_pilot-0.1.0/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml .
+RUN pip install --no-cache-dir .
+
+COPY . .
+
+ENTRYPOINT ["seo-pilot"]
+CMD ["--help"]

seo_pilot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Palicz91
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seo_pilot-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+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

seo_pilot-0.1.0/README.md

@@ -0,0 +1,238 @@
+# 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

seo_pilot-0.1.0/config.example.yaml

@@ -0,0 +1,59 @@
+# seo-pilot configuration
+# Copy to config.yaml and fill in your values
+# Or run: seo-pilot init
+
+site:
+  domain: "example.com"
+  gsc_property: "sc-domain:example.com"  # or "https://example.com/"
+  sitemap: "https://example.com/sitemap.xml"  # optional, auto-detected from robots.txt
+
+auth:
+  gsc_credentials: "./credentials.json"  # Google service account JSON
+
+storage:
+  type: "sqlite"  # sqlite | postgres
+  # SQLite (default, zero config):
+  path: "./seo-pilot.db"
+  # Postgres (optional):
+  # url: "postgresql://user:pass@localhost:5432/seo_pilot"
+
+notifications:
+  - type: telegram
+    token_env: "TELEGRAM_BOT_TOKEN"  # reads from env var
+    chat_id: "123456789"
+  # - type: slack
+  #   webhook_env: "SLACK_WEBHOOK_URL"
+  # - type: webhook
+  #   url: "https://your-endpoint.com/seo-events"
+
+llm:
+  provider: "gemini"  # claude | openai | gemini | ollama
+  model: "gemini-2.0-flash"  # model name for the provider
+  api_key_env: "GEMINI_API_KEY"  # reads from env var
+  # For Ollama:
+  # provider: "ollama"
+  # model: "llama3"
+  # base_url: "http://localhost:11434"
+
+schedule:
+  weekly_review: "monday 05:30"  # day + time (local timezone)
+  monthly_review: "first_monday"  # runs on first Monday of each month
+
+content:
+  # How to discover your pages (tried in order):
+  # 1. sitemap.xml (if configured above)
+  # 2. GSC data (pages with impressions)
+  # 3. Manual list below
+  blog_url_pattern: "/blog/"  # URL prefix that identifies blog posts
+  # manual_urls:
+  #   - "/blog/my-first-post"
+  #   - "/blog/my-second-post"
+
+guidelines:
+  path: "./guidelines/default.md"  # SEO rules, customize or use default
+
+baseline:
+  # Set after first run, or manually:
+  # weekly_impressions: 1000
+  # weekly_clicks: 50
+  # avg_position: 15.0

seo_pilot-0.1.0/docker-compose.yaml

@@ -0,0 +1,11 @@
+services:
+  seo-pilot:
+    build: .
+    volumes:
+      - ./config.yaml:/app/config.yaml:ro
+      - ./credentials.json:/app/credentials.json:ro
+      - ./data:/app/data
+    environment:
+      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+    command: ["review"]