Skip to content

Commit c7d62a3

Browse files
vikasswebdevvikasswebdev
committed
feat: initialize OpenSEO project structure with CLI commands, LLM-based analysis, and reporting utilities
0 parents  commit c7d62a3

91 files changed

Lines changed: 8061 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
build/
11+
develop-eggs/
12+
dist/
13+
downloads/
14+
eggs/
15+
.eggs/
16+
lib/
17+
lib64/
18+
parts/
19+
sdist/
20+
var/
21+
wheels/
22+
share/python-wheels/
23+
*.egg-info/
24+
.installed.cfg
25+
*.egg
26+
MANIFEST
27+
28+
# Pyinstaller
29+
# Usually these files are written by a python script from a template
30+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
31+
*.manifest
32+
*.spec
33+
34+
# Installer logs
35+
pip-log.txt
36+
pip-delete-this-directory.txt
37+
38+
# Unit test / Coverage reports
39+
htmlcov/
40+
.tox/
41+
.nosenv
42+
.gauge
43+
.coverage
44+
.coverage.*
45+
.cache
46+
nosetests.xml
47+
coverage.xml
48+
*.cover
49+
*.py,cover
50+
.hypothesis/
51+
.pytest_cache/
52+
cover/
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Sphinx documentation
65+
docs/_build/
66+
67+
# PyBuilder
68+
.pybuilder/
69+
target/
70+
71+
# Jupyter Notebook
72+
.ipynb_checkpoints
73+
74+
# IPython
75+
profile_default/
76+
ipython_config.py
77+
78+
# pyenv
79+
# For a library or app, you might want to share your .python-version if you're
80+
# using pyenv and local version file (.python-version).
81+
# .python-version
82+
83+
# pipenv
84+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
85+
# However, in case of collaboration, if delegates have different platforms, you should keep Pipfile.lock in gitignore.
86+
# Pipfile.lock
87+
88+
# poetry
89+
# Similar to Pipfile.lock, poetry.lock is generally recommended to be committed.
90+
# However, if you're building a library, you should ignore it:
91+
# poetry.lock
92+
93+
# pdm
94+
# Similar to Poetry and Pipenv, pdm.lock is generally recommended to be committed.
95+
# pdm.lock
96+
# pdm local configuration
97+
.pdm-python
98+
.pdm-db/
99+
100+
# PEP 582 project packages
101+
__pypackages__/
102+
103+
# Celery stuff
104+
celerybeat-schedule
105+
celerybeat.pid
106+
107+
# SageMath parsed files
108+
*.sage.py
109+
110+
# Environments
111+
.env
112+
.venv
113+
env/
114+
venv/
115+
ENV/
116+
env.bak/
117+
venv.bak/
118+
119+
# Spyder project settings
120+
.spyderproject
121+
.spyproject
122+
123+
# Rope project settings
124+
.ropeproject
125+
126+
# mkdocs documentation
127+
/site/
128+
129+
# mypy
130+
.mypy_cache/
131+
.dmypy.json
132+
dmypy.json
133+
134+
# Pyre type checker
135+
.pyre/
136+
137+
# pytype
138+
.pytype/
139+
140+
# Cython debug symbols
141+
cython_debug/
142+
143+
# OS-specific
144+
.DS_Store
145+
Thumbs.db
146+
147+
# OpenSEO local run leftovers
148+
.openseo/
149+
cache.db
150+
cache.db-journal
151+
logs/

‎CONTRIBUTING.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Contributing to OpenSEO
2+
3+
First off, thank you for taking the time to contribute! OpenSEO is built to be a community-driven tool, and your help is highly appreciated.
4+
5+
## Getting Started
6+
7+
1. **Clone the repository**:
8+
```bash
9+
git clone https://github.com/openseo/openseo.git
10+
cd openseo
11+
```
12+
13+
2. **Set up virtual environment & dependencies**:
14+
We recommend using `uv` for lightning-fast environment setup:
15+
```bash
16+
uv venv
17+
source .venv/bin/activate # On Windows: .venv\Scripts\activate
18+
uv pip install -e ".[all]"
19+
```
20+
21+
3. **Install Playwright**:
22+
```bash
23+
playwright install chromium
24+
```
25+
26+
## Development Workflow
27+
28+
### Coding Standards
29+
- **Typing**: 100% typed. All functions must have type hints. Run `mypy` to verify.
30+
- **Style**: We use `ruff` for linting and formatting.
31+
- **Composition**: Prefer composition over inheritance. Keep modules small and highly focused.
32+
- **No Monoliths**: Commands, analyzers, and outputs must be kept in their respective folders and follow the abstraction contracts.
33+
34+
### Verification and Quality Checks
35+
Before submitting a PR, make sure your code passes formatting, type checks, and tests:
36+
37+
```bash
38+
# Run Ruff linting and formatting
39+
ruff check src/ tests/
40+
ruff format src/ tests/
41+
42+
# Run type checker
43+
mypy src/
44+
45+
# Run tests
46+
pytest tests/
47+
```
48+
49+
## Adding a New CLI Command
50+
1. Create a new module in `src/openseo/commands/<command_name>.py`.
51+
2. Implement the command function using `typer`.
52+
3. Expose a `register(app: typer.Typer)` function to add it to the main Typer application.
53+
4. Import and call the registration in `src/openseo/app.py`.
54+
55+
## Adding a New Analyzer
56+
1. Add your analyzer function in `src/openseo/analyzers/`. It must accept a `Page` model and return a tuple of `(list[Issue], float)`.
57+
2. Expose it in `src/openseo/analyzers/__init__.py`.
58+
3. Call it in `src/openseo/commands/audit.py` to incorporate it into the main audit scoring.

‎LICENSE‎

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

‎README.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# OpenSEO 🔍
2+
3+
[![PyPI version](https://img.shields.io/pypi/v/openseo.svg)](https://pypi.org/project/openseo/)
4+
[![Supported Python Versions](https://img.shields.io/pypi/pyversions/openseo.svg)](https://pypi.org/project/openseo/)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
7+
OpenSEO is a production-quality, provider-agnostic, plugin-ready command-line tool built to help developers, marketers, and SEO professionals audit, analyze, and optimize search engine visibility using Large Language Models (LLMs).
8+
9+
Unlike other SEO auditing tools, OpenSEO **never** locks you into a single provider. With integration via LiteLLM, you can use OpenAI, Anthropic Claude, Google Gemini, Groq, Ollama, DeepSeek, Together AI, Fireworks, or any OpenAI-compatible endpoint with one unified interface.
10+
11+
---
12+
13+
## Key Features
14+
15+
- 🛠 **Full SEO Audit**: Combines rules-based HTML parsing with LLM-powered recommendations.
16+
- 💡 **AI Provider-Agnostic**: Change providers or models seamlessly via commands or configs.
17+
- 📂 **No Hardcoded Prompts**: Prompts are stored as dynamic Markdown templates, easy to edit and extend.
18+
- 🧩 **Plugin Architecture**: Write and load custom commands, providers, and logic easily.
19+
- ⚡ **SQLite Caching**: Zero-configuration, local caching with customizable TTL to avoid repeating API calls.
20+
- 💻 **Beautiful UI**: Highly polished terminal UI with tables, trees, scoring, and progress bars powered by Rich.
21+
- 🔒 **Privacy-First / local**: Supports local LLM endpoints like Ollama out-of-the-box.
22+
23+
---
24+
25+
## Installation
26+
27+
Install using `pip` or `uv`:
28+
29+
```bash
30+
# Core installation
31+
pip install openseo
32+
33+
# Install with all extras (includes Playwright for JavaScript rendering and developer tools)
34+
pip install "openseo[all]"
35+
playwright install chromium
36+
```
37+
38+
---
39+
40+
## Quick Start
41+
42+
1. **Initialize configuration**:
43+
```bash
44+
seo init
45+
```
46+
This interactive wizard will help you set up your default provider and configurations at `~/.openseo/config.json`.
47+
48+
2. **Configure your API keys**:
49+
```bash
50+
# Set key in config
51+
seo provider set-key openai sk-...
52+
53+
# Or set environment variables (recommended)
54+
export OPENAI_API_KEY="sk-..."
55+
```
56+
57+
3. **Verify installation**:
58+
```bash
59+
seo doctor
60+
```
61+
62+
4. **Run your first audit**:
63+
```bash
64+
seo audit https://example.com
65+
```
66+
67+
---
68+
69+
## Architecture Overview
70+
71+
OpenSEO is designed with clean architecture and modular SOLID principles:
72+
73+
```
74+
src/openseo/
75+
├── cli.py # Entry point
76+
├── app.py # App bootstrap
77+
├── commands/ # Isolated Typer command modules
78+
├── providers/ # Provider adapters (OpenAI, Claude, etc.)
79+
├── crawler/ # Page crawlers (Http, Playwright) & Extractor
80+
├── analyzers/ # Independent SEO checks (Title, Image, Links)
81+
├── prompts/ # PromptManager & Markdown Prompt templates
82+
├── outputs/ # Output renderers (Terminal, JSON, Markdown)
83+
├── cache/ # SQLite key-value cache
84+
└── services/ # Unified LLMService
85+
```
86+
87+
---
88+
89+
## Contributing
90+
91+
We welcome contributions of all forms! Check out [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
92+
93+
## License
94+
95+
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

‎ROADMAP.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# OpenSEO Release Roadmap
2+
3+
This roadmap outlines the milestones and release goals for the OpenSEO CLI tool.
4+
5+
---
6+
7+
## v0.1: Core CLI & Scaffolding (Current)
8+
- [x] Basic project scaffold and clean architecture design.
9+
- [x] Abstract provider system using LiteLLM.
10+
- [x] Prompts managed dynamically using Markdown templates.
11+
- [x] BeautifulSoup4 extraction and basic rules-based analyzers.
12+
- [x] Config manager supporting JSON settings and per-provider overrides.
13+
- [x] SQLite-backed local cache store.
14+
- [x] Typer command modules: `init`, `config`, `provider`, `audit`, `keywords`, `schema`, `content`, `doctor`, `sitemap`, `robots`.
15+
- [x] Beautiful rich-based terminal output renderers.
16+
17+
---
18+
19+
## v0.2: Content Strategy & Dynamic Optimization
20+
- [ ] Integration with advanced keyword gap tools.
21+
- [ ] Content optimization score adjustments based on SERP analysis.
22+
- [ ] Competitor site scanning and metadata comparison.
23+
- [ ] Bulk URL crawl/audit commands (crawling complete domain structures via sitemap index).
24+
25+
---
26+
27+
## v0.3: Plugin System & Third-Party Integrations
28+
- [ ] Stable plugin installation and verification commands (`seo plugin install xxx`).
29+
- [ ] Built-in plugins for:
30+
- **WordPress**: Generate metadata & posts directly to your WordPress site.
31+
- **Shopify**: Audit product page optimization directly via Shopify API.
32+
- **Vercel/NextJS**: Automated CI/CD checks for page-by-page metadata compliance.
33+
- [ ] Community plugins registry.
34+
35+
---
36+
37+
## v0.4: Advanced Technical SEO
38+
- [ ] Real User Monitoring / PageSpeed Insights API validation.
39+
- [ ] Crawl budget analyses.
40+
- [ ] Mixed HTTP/HTTPS resource and security auditing.
41+
- [ ] Deep internal link graphs and internal pagerank simulation.
42+
43+
---
44+
45+
## v1.0: Stable Release
46+
- [ ] 100% test coverage with automated unit and integration tests.
47+
- [ ] Complete documentation site hosted at `openseo.dev`.
48+
- [ ] Custom PDF/HTML reporting modules for agency handoffs.
49+
- [ ] Production-ready, stable, extensible API.

0 commit comments

Comments
 (0)