reheat 0.0.1__tar.gz

reheat-0.0.1/.gitignore

@@ -0,0 +1 @@
+__pycache__/

reheat-0.0.1/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: reheat
+Version: 0.0.1
+Summary: Python CLI for SEO analysis. Cluster search intent, surface content gaps.
+Home-page: https://www.bayis.co.uk/reheat
+Author: Edward Grundy
+Author-email: ed@bayis.co.uk
+License: MIT
+Project-URL: Source, https://github.com/bayinfosys/reheat
+Project-URL: PyPI, https://pypi.org/project/reheat
+Project-URL: Company, https://bayis.co.uk
+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
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: dynawrap
+Requires-Dist: requests
+Requires-Dist: fastembed
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: umap-learn
+Requires-Dist: google-auth
+Requires-Dist: google-auth-httplib2
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: tqdm
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: python-dotenv
+Provides-Extra: local
+Requires-Dist: sentence-transformers; extra == "local"
+Requires-Dist: torch; extra == "local"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == "anthropic"
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: setuptools-scm; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Provides-Extra: all
+Requires-Dist: sentence-transformers; extra == "all"
+Requires-Dist: torch; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: anthropic>=0.20; extra == "all"
+Requires-Dist: psycopg2-binary; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Reheat
+
+Python CLI for SEO analysis. Pulls search queries from Google Search Console,
+enriches them with related searches and People Also Ask data, clusters by
+semantic intent, and surfaces content gaps and opportunities.
+
+Built by [Edward Grundy](https://bayis.co.uk) at
+[Bay Information Systems](https://bayis.co.uk).
+
+- Install: `pip install reheat`
+- Docs: [bayinfosys.github.io/reheat](https://bayinfosys.github.io/reheat)
+- PyPI: [pypi.org/project/reheat](https://pypi.org/project/reheat)
+
+---
+
+## Getting started
+
+### Install
+
+```bash
+pip install reheat
+```
+
+Requires Python 3.10+. For the local web interface you also need a running
+postgres instance (or use the JSON file backend for local development
+without postgres).
+
+```bash
+docker run -d \
+  --name reheat-pg \
+  -e POSTGRES_USER=reheat \
+  -e POSTGRES_PASSWORD=reheat \
+  -e POSTGRES_DB=reheat \
+  -p 5432:5432 \
+  postgres:16
+
+export DATABASE_URL=postgresql://reheat:reheat@localhost:5432/reheat
+```
+
+### Configure a Google Search Console source
+
+Download OAuth2 credentials from Google Cloud Console (APIs and Services >
+Credentials > OAuth 2.0 Client IDs, Desktop app type) and save as
+`~/.reheat/google-search-console.json`. Then:
+
+```bash
+reheat sources create \
+  --source-type google_search_console \
+  --domain yourdomain.com \
+  --client-secrets-path ~/.reheat/google-search-console.json
+```
+
+### Authenticate
+
+```bash
+reheat sources auth
+```
+
+Opens a browser for the Google OAuth2 consent flow. The token is persisted
+to `~/.reheat/gsc_token.json` and refreshed automatically on subsequent runs.
+
+### Configure a SerpAPI source (optional)
+
+Required for PAA and related search enrichment. Get an API key at
+[serpapi.com](https://serpapi.com).
+
+```bash
+reheat sources create \
+  --source-type serp \
+  --api-key YOUR_SERP_API_KEY
+```
+
+### Run the pipeline
+
+```bash
+# Fetch queries from Search Console
+reheat runs create
+
+# Enrich and process
+reheat enrich tags
+reheat enrich embed
+reheat enrich cluster
+reheat enrich gap
+reheat analyse opportunities
+
+# Build report data
+reheat project create
+reheat report scatter create
+reheat report summary create
+reheat report coverage create
+
+# Start the web interface
+reheat serve
+```
+
+Open [http://localhost:8000](http://localhost:8000).
+
+---
+
+## Inference providers
+
+`reheat analyse summarise` labels intent clusters using an LLM. Configure
+one of the following.
+
+### OpenAI
+
+Set `OPENAI_API_KEY` in your environment or `.env` file, or:
+
+```bash
+reheat config set --key openai_api_key --value sk-...
+```
+
+### Anthropic
+
+Set `ANTHROPIC_API_KEY` in your environment or `.env` file, or:
+
+```bash
+reheat config set --key anthropic_api_key --value sk-ant-...
+```
+
+### Marigold
+
+[Marigold](https://marigold.run) is a private inference API built by
+Bay Information Systems. Set endpoint and key when available:
+
+```bash
+reheat config set --key marigold_endpoint --value https://api.marigold.run
+reheat config set --key marigold_api_key --value <key>
+```
+
+---
+
+## CLI reference
+
+```
+reheat config show / set
+reheat sources create / list / show / update / delete / auth
+reheat runs create / list / show / delete
+reheat enrichments list / show / delete
+reheat enrich tags / embed / cluster / gap
+reheat analyse summarise / opportunities
+reheat project create / read
+reheat report scatter / summary / coverage  create / read
+reheat serve
+```
+
+---
+
+## Architecture
+
+reheat has three layers.
+
+**Commands** in `reheat/commands/` are the single source of truth for the
+application surface. Each command is a Python function decorated with
+`@command`, registered in a central registry, and exposed automatically
+through both the CLI and the HTTP API.
+
+**Pipeline** functions in `reheat/pipeline/` are pure data transforms:
+embedding, clustering, gap analysis, report building. No persistence, no
+side effects.
+
+**Persistence** uses [dynawrap](https://github.com/bayinfosys/dynawrap),
+a lightweight key-value library with identical interfaces over PostgreSQL
+and DynamoDB. Tables are passed at call time; models are backend-agnostic.
+
+The web interface is a static SPA served by FastAPI. All pages share a
+single stylesheet and a common `api.js` module that is the single source
+of truth for API endpoint calls.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- PostgreSQL (or JSON file backend for local development)
+- Google Search Console OAuth2 credentials
+- SerpAPI key (optional, for PAA enrichment)
+- OpenAI, Anthropic, or Marigold key (optional, for cluster summarisation)
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+Built by [Edward Grundy](https://bayis.co.uk) -- 
+[Bay Information Systems](https://bayis.co.uk)

reheat-0.0.1/README.md

@@ -0,0 +1,189 @@
+# Reheat
+
+Python CLI for SEO analysis. Pulls search queries from Google Search Console,
+enriches them with related searches and People Also Ask data, clusters by
+semantic intent, and surfaces content gaps and opportunities.
+
+Built by [Edward Grundy](https://bayis.co.uk) at
+[Bay Information Systems](https://bayis.co.uk).
+
+- Install: `pip install reheat`
+- Docs: [bayinfosys.github.io/reheat](https://bayinfosys.github.io/reheat)
+- PyPI: [pypi.org/project/reheat](https://pypi.org/project/reheat)
+
+---
+
+## Getting started
+
+### Install
+
+```bash
+pip install reheat
+```
+
+Requires Python 3.10+. For the local web interface you also need a running
+postgres instance (or use the JSON file backend for local development
+without postgres).
+
+```bash
+docker run -d \
+  --name reheat-pg \
+  -e POSTGRES_USER=reheat \
+  -e POSTGRES_PASSWORD=reheat \
+  -e POSTGRES_DB=reheat \
+  -p 5432:5432 \
+  postgres:16
+
+export DATABASE_URL=postgresql://reheat:reheat@localhost:5432/reheat
+```
+
+### Configure a Google Search Console source
+
+Download OAuth2 credentials from Google Cloud Console (APIs and Services >
+Credentials > OAuth 2.0 Client IDs, Desktop app type) and save as
+`~/.reheat/google-search-console.json`. Then:
+
+```bash
+reheat sources create \
+  --source-type google_search_console \
+  --domain yourdomain.com \
+  --client-secrets-path ~/.reheat/google-search-console.json
+```
+
+### Authenticate
+
+```bash
+reheat sources auth
+```
+
+Opens a browser for the Google OAuth2 consent flow. The token is persisted
+to `~/.reheat/gsc_token.json` and refreshed automatically on subsequent runs.
+
+### Configure a SerpAPI source (optional)
+
+Required for PAA and related search enrichment. Get an API key at
+[serpapi.com](https://serpapi.com).
+
+```bash
+reheat sources create \
+  --source-type serp \
+  --api-key YOUR_SERP_API_KEY
+```
+
+### Run the pipeline
+
+```bash
+# Fetch queries from Search Console
+reheat runs create
+
+# Enrich and process
+reheat enrich tags
+reheat enrich embed
+reheat enrich cluster
+reheat enrich gap
+reheat analyse opportunities
+
+# Build report data
+reheat project create
+reheat report scatter create
+reheat report summary create
+reheat report coverage create
+
+# Start the web interface
+reheat serve
+```
+
+Open [http://localhost:8000](http://localhost:8000).
+
+---
+
+## Inference providers
+
+`reheat analyse summarise` labels intent clusters using an LLM. Configure
+one of the following.
+
+### OpenAI
+
+Set `OPENAI_API_KEY` in your environment or `.env` file, or:
+
+```bash
+reheat config set --key openai_api_key --value sk-...
+```
+
+### Anthropic
+
+Set `ANTHROPIC_API_KEY` in your environment or `.env` file, or:
+
+```bash
+reheat config set --key anthropic_api_key --value sk-ant-...
+```
+
+### Marigold
+
+[Marigold](https://marigold.run) is a private inference API built by
+Bay Information Systems. Set endpoint and key when available:
+
+```bash
+reheat config set --key marigold_endpoint --value https://api.marigold.run
+reheat config set --key marigold_api_key --value <key>
+```
+
+---
+
+## CLI reference
+
+```
+reheat config show / set
+reheat sources create / list / show / update / delete / auth
+reheat runs create / list / show / delete
+reheat enrichments list / show / delete
+reheat enrich tags / embed / cluster / gap
+reheat analyse summarise / opportunities
+reheat project create / read
+reheat report scatter / summary / coverage  create / read
+reheat serve
+```
+
+---
+
+## Architecture
+
+reheat has three layers.
+
+**Commands** in `reheat/commands/` are the single source of truth for the
+application surface. Each command is a Python function decorated with
+`@command`, registered in a central registry, and exposed automatically
+through both the CLI and the HTTP API.
+
+**Pipeline** functions in `reheat/pipeline/` are pure data transforms:
+embedding, clustering, gap analysis, report building. No persistence, no
+side effects.
+
+**Persistence** uses [dynawrap](https://github.com/bayinfosys/dynawrap),
+a lightweight key-value library with identical interfaces over PostgreSQL
+and DynamoDB. Tables are passed at call time; models are backend-agnostic.
+
+The web interface is a static SPA served by FastAPI. All pages share a
+single stylesheet and a common `api.js` module that is the single source
+of truth for API endpoint calls.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- PostgreSQL (or JSON file backend for local development)
+- Google Search Console OAuth2 credentials
+- SerpAPI key (optional, for PAA enrichment)
+- OpenAI, Anthropic, or Marigold key (optional, for cluster summarisation)
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+Built by [Edward Grundy](https://bayis.co.uk) -- 
+[Bay Information Systems](https://bayis.co.uk)

reheat-0.0.1/docs/_config.yml

@@ -0,0 +1,10 @@
+title: reheat
+description: >
+  Open source Python CLI for SEO analysis. Pull Google Search Console queries,
+  cluster by semantic intent, and surface content gaps and opportunities.
+url: https://bayinfosys.github.io
+baseurl: /reheat
+theme: minima
+author:
+  name: Edward Grundy
+  url: https://bayis.co.uk

reheat-0.0.1/docs/index.md

@@ -0,0 +1,74 @@
+---
+layout: default
+title: reheat
+description: >
+  reheat is an open source Python CLI for SEO analysis. Pull queries from
+  Google Search Console, cluster by intent, and surface content gaps.
+---
+
+# reheat
+
+Open source Python CLI for SEO analysis. Pull your Google Search Console
+queries, enrich them with related searches and People Also Ask data, cluster
+by semantic intent, and surface content gaps and opportunities.
+
+Built by [Edward Grundy](https://bayis.co.uk) at
+[Bay Information Systems](https://bayis.co.uk).
+
+---
+
+## Install
+
+```bash
+pip install reheat
+```
+
+Requires Python 3.10+.
+
+---
+
+## Quick start
+
+```bash
+# Configure your Search Console source
+reheat sources create \
+  --source-type google_search_console \
+  --domain yourdomain.com \
+  --client-secrets-path ~/.reheat/google-search-console.json
+
+# Authenticate
+reheat sources auth
+
+# Run the pipeline
+reheat runs create
+reheat enrich tags
+reheat enrich embed
+reheat enrich cluster
+reheat enrich gap
+reheat analyse opportunities
+reheat project create
+reheat report scatter create
+reheat report summary create
+reheat report coverage create
+
+# Open the web interface
+reheat serve
+```
+
+---
+
+## Inference providers
+
+Cluster summarisation (`reheat analyse summarise`) works with
+[OpenAI](https://openai.com), [Anthropic](https://anthropic.com), or
+[Marigold](https://marigold.run). Set the relevant API key in your
+environment or `.env` file and reheat will pick it up automatically.
+
+---
+
+## Links
+
+- [GitHub repository](https://github.com/bayinfosys/reheat)
+- [PyPI](https://pypi.org/project/reheat)
+- [Bay Information Systems](https://bayis.co.uk)
+- [dynawrap](https://github.com/bayinfosys/dynawrap) -- persistence layer

reheat-0.0.1/reheat/__main__.py

@@ -0,0 +1,46 @@
+import logging
+import sys
+
+from reheat.state import init_backend
+
+import reheat.commands.config
+import reheat.commands.sources
+import reheat.commands.runs
+import reheat.commands.enrichments
+import reheat.commands.enrich
+import reheat.commands.analyse
+import reheat.commands.project
+import reheat.commands.report
+import reheat.commands.serve
+
+from reheat.adapters.argparse_adapter import build_parser, dispatch
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        format="%(asctime)s %(levelname)-8s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+        level=logging.DEBUG if getattr(args, "verbose", False) else logging.INFO,
+    )
+
+    try:
+        backend = init_backend(getattr(args, "config", None))
+    except Exception as e:
+        print(f"error: failed to initialise backend: {e}")
+        sys.exit(1)
+
+    try:
+        dispatch(args, backend)
+    except KeyboardInterrupt:
+        print("\ninterrupted")
+        sys.exit(130)
+    except Exception:
+        logging.getLogger(__name__).exception("command failed")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

reheat-0.0.1/reheat/registry.py

@@ -0,0 +1,34 @@
+from typing import TypeVar, Generic, Callable, Dict, Optional
+
+T = TypeVar("T")
+
+
+class Resource(Generic[T]):
+    """Parameter is a resource identifier. Maps to a URL path segment."""
+    pass
+
+
+class Payload(Generic[T]):
+    """Parameter is request payload. Maps to a POST body field."""
+    pass
+
+
+_registry: Dict[str, Callable] = {}
+
+
+def command(help: str = "", interactive_only: bool = False):
+    def decorator(fn: Callable) -> Callable:
+        parts = fn.__name__.split("_")
+
+        if parts[0] != "cmd":
+            raise ValueError(f"command functions must start with cmd_, got {fn.__name__}")
+
+        path = ".".join(parts[1:])
+        _registry[path] = fn
+        fn._cli_path = path
+        fn._cli_help = help
+        fn._interactive_only = interactive_only
+
+        return fn
+
+    return decorator

reheat-0.0.1/reheat/sources/__init__.py

@@ -0,0 +1,24 @@
+from reheat.state.execution import SourceConfig
+from reheat.sources.base import SourceProvider, SourceError
+
+
+def get_source_provider(config: SourceConfig) -> SourceProvider:
+    """
+    Factory: construct the correct SourceProvider for a SourceConfig.
+    Importing here keeps the registry central and avoids circular imports.
+    """
+    from reheat.sources.google_search_console import GoogleSearchConsoleProvider
+    from reheat.sources.serp import SerpAPIProvider
+
+    providers = {
+        "google_search_console": GoogleSearchConsoleProvider,
+        "serp": SerpAPIProvider,
+    }
+
+    cls = providers.get(config.source_type)
+    if cls is None:
+        raise SourceError(
+            f"unknown source type {config.source_type!r}. "
+            f"Available: {', '.join(providers)}"
+        )
+    return cls(config)

reheat-0.0.1/reheat/sources/base.py

@@ -0,0 +1,51 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+from reheat.state.execution import QueryRecord, SourceConfig
+
+
+class SourceProvider(ABC):
+    """
+    Base class for data source providers.
+
+    Each provider knows how to:
+    - validate its configuration
+    - execute a fetch and return QueryRecords
+    """
+
+    source_type: str = ""
+
+    def __init__(self, config: SourceConfig) -> None:
+        self.config = config
+        self.validate()
+
+    def validate(self) -> None:
+        """
+        Raise ValueError if the SourceConfig is missing required credentials
+        or settings. Called at construction time.
+        """
+        pass
+
+    @abstractmethod
+    def fetch(self) -> List[QueryRecord]:
+        """
+        Pull data from the source and return QueryRecords.
+        Raises SourceError on failure.
+        """
+        ...
+
+    def _credential(self, key: str) -> str:
+        """Return a credential value, raising ValueError if absent."""
+        value = self.config.credentials.get(key, "")
+        if not value:
+            raise ValueError(
+                f"source {self.config.source_id!r} missing credential {key!r}"
+            )
+        return value
+
+    def _setting(self, key: str, default: Any = None) -> Any:
+        """Return a setting value with optional default."""
+        return self.config.settings.get(key, default)
+
+
+class SourceError(Exception):
+    """Raised when a source provider fails to fetch data."""