Upload folder using huggingface_hub

.env.example

@@ -0,0 +1,5 @@
+# SERP-Feature-Classifier
+DATA_PATH=data/serp_labels.csv
+MODEL_DIR=models
+HF_MODEL=bert-base-uncased
+RANDOM_STATE=42

README.md

@@ -0,0 +1,67 @@
+# SERP-Feature-Classifier: SERP Feature Type Prediction
+
+**Type:** Academic | **Domain:** SEO, Search  
+**Hugging Face:** [syeedalireza/serp-feature-classifier](https://huggingface.co/syeedalireza/serp-feature-classifier)
+
+Multi-label classification of SERP feature types (featured snippet, PAA, local pack, etc.) from query and context.
+
+## Author
+
+**Alireza Aminzadeh**  
+- Hugging Face: [syeedalireza](https://huggingface.co/syeedalireza)  
+- LinkedIn: [alirezaaminzadeh](https://www.linkedin.com/in/alirezaaminzadeh)  
+- Email: alireza.aminzadeh@hotmail.com
+
+## Problem
+
+Understanding which SERP features appear for a query helps content and technical SEO strategy (e.g. snippet optimization, local SEO).
+
+## Approach
+
+- **Input:** Query text, optional context (device, locale).
+- **Output:** Multi-label (featured_snippet, paa, local_pack, knowledge_panel, etc.).
+- **Models:** Transformer-based text classifier (e.g. BERT mini) or sentence-transformers + linear head; optional XGBoost on query features.
+
+## Tech Stack
+
+| Category | Tools |
+|----------|------|
+| NLP / DL | Hugging Face Transformers, sentence-transformers |
+| ML | scikit-learn, PyTorch |
+| Data | pandas, NumPy |
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+```bash
+python train.py
+python inference.py --query "best coffee shops near me"
+```
+
+## Project structure
+
+```
+02_serp-feature-classifier/
+├── config.py
+├── train.py           # Sentence-transformers + MultiOutputClassifier
+├── inference.py       # Single query or batch CSV
+├── requirements.txt
+├── .env.example
+├── data/
+│   └── serp_labels.csv   # Sample: query + binary labels per SERP feature
+└── models/
+```
+
+## Data
+
+- **Sample data (included):** `data/serp_labels.csv` — columns: `query`, `featured_snippet`, `paa`, `local_pack`, `knowledge_panel`, `images` (0/1).
+- Set `DATA_PATH` in `.env` if using another file.
+
+## License
+
+MIT.

config.py

@@ -0,0 +1,21 @@
+"""
+Configuration for SERP-Feature-Classifier.
+"""
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent
+DATA_PATH = os.getenv("DATA_PATH", str(BASE_DIR / "data" / "serp_labels.csv"))
+MODEL_DIR = Path(os.getenv("MODEL_DIR", str(BASE_DIR / "models")))
+HF_MODEL = os.getenv("HF_MODEL", "bert-base-uncased")
+RANDOM_STATE = int(os.getenv("RANDOM_STATE", "42"))
+
+SERP_LABELS = [
+    "featured_snippet",
+    "paa",
+    "local_pack",
+    "knowledge_panel",
+    "images",
+]
+QUERY_COLUMN = "query"
+MODEL_DIR.mkdir(parents=True, exist_ok=True)

data/serp_labels.csv

@@ -0,0 +1,21 @@
+query,featured_snippet,paa,local_pack,knowledge_panel,images
+best coffee shops near me,0,1,1,0,1
+what is machine learning,1,1,0,1,0
+buy running shoes online,0,1,0,0,1
+how to fix 404 error,1,1,0,0,0
+weather in new york today,0,0,0,1,0
+python tutorial for beginners,1,1,0,0,0
+restaurants open now,0,1,1,0,1
+seo best practices 2024,1,1,0,0,0
+apple store locations,0,0,1,1,0
+how does photosynthesis work,1,1,0,1,0
+cheap hotels near airport,0,1,1,0,1
+what is deep learning,1,1,0,1,0
+pizza delivery near me,0,1,1,0,1
+how to learn python,1,1,0,0,0
+best laptops 2024,0,1,0,0,1
+who invented the telephone,1,1,0,1,0
+plumbers near me,0,1,1,0,0
+docker vs kubernetes,1,1,0,0,0
+nearest gas station,0,0,1,0,0
+how to tie a tie,1,1,0,0,1

inference.py

@@ -0,0 +1,54 @@
+"""
+Predict SERP feature labels for queries.
+"""
+import argparse
+import joblib
+from pathlib import Path
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+from config import MODEL_DIR, SERP_LABELS
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--query", type=str, help="Single query to predict")
+    parser.add_argument("--input", type=str, help="CSV with 'query' column for batch")
+    parser.add_argument("--output", type=str, default="predictions.csv")
+    args = parser.parse_args()
+
+    model_path = MODEL_DIR / "serp_classifier.joblib"
+    label_path = MODEL_DIR / "label_columns.joblib"
+    if not model_path.exists():
+        raise FileNotFoundError(f"Train first: {model_path} not found")
+
+    clf = joblib.load(model_path)
+    labels = joblib.load(label_path) if label_path.exists() else SERP_LABELS
+    encoder = SentenceTransformer("all-MiniLM-L6-v2")
+
+    if args.query:
+        X = encoder.encode([args.query])
+        pred = np.array([est.predict(X) for est in clf.estimators_]).T
+        out = dict(zip(labels, pred[0].tolist()))
+        print(out)
+        return
+
+    if args.input and Path(args.input).exists():
+        import pandas as pd
+        df = pd.read_csv(args.input)
+        if "query" not in df.columns:
+            raise ValueError("CSV must have 'query' column")
+        X = encoder.encode(df["query"].astype(str).tolist())
+        pred = np.array([est.predict(X) for est in clf.estimators_]).T
+        for i, col in enumerate(labels):
+            df[f"pred_{col}"] = pred[:, i]
+        df.to_csv(args.output, index=False)
+        print(f"Saved to {args.output}")
+        return
+
+    print("Use --query 'text' or --input file.csv")
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,10 @@
+# SERP-Feature-Classifier
+# Python 3.9+
+
+torch>=1.12.0
+transformers>=4.20.0
+sentence-transformers>=2.2.0
+scikit-learn>=1.0.0
+joblib>=1.1.0
+pandas>=1.3.0
+numpy>=1.21.0

train.py

@@ -0,0 +1,64 @@
+"""
+Train SERP feature multi-label classifier.
+Uses sentence-transformers embeddings + sklearn multi-output classifier.
+"""
+import json
+from pathlib import Path
+
+import pandas as pd
+import numpy as np
+from sklearn.model_selection import train_test_split
+from sklearn.multioutput import MultiOutputClassifier
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.metrics import f1_score, accuracy_score
+from sentence_transformers import SentenceTransformer
+
+from config import (
+    DATA_PATH,
+    MODEL_DIR,
+    RANDOM_STATE,
+    SERP_LABELS,
+    QUERY_COLUMN,
+)
+
+
+def load_data(path: str) -> tuple[pd.DataFrame, list[str]]:
+    df = pd.read_csv(path)
+    if QUERY_COLUMN not in df.columns:
+        raise ValueError(f"Missing column: {QUERY_COLUMN}")
+    labels = [c for c in SERP_LABELS if c in df.columns]
+    return df, labels
+
+
+def main():
+    if not Path(DATA_PATH).exists():
+        print(f"Data not found at {DATA_PATH}. Create data/serp_labels.csv with columns: {QUERY_COLUMN}, {SERP_LABELS}")
+        return
+
+    df, labels = load_data(DATA_PATH)
+    encoder = SentenceTransformer("all-MiniLM-L6-v2")
+    X = encoder.encode(df[QUERY_COLUMN].astype(str).tolist())
+    y = df[labels].values
+
+    X_train, X_val, y_train, y_val = train_test_split(
+        X, y, test_size=0.2, random_state=RANDOM_STATE
+    )
+
+    clf = MultiOutputClassifier(RandomForestClassifier(n_estimators=100, random_state=RANDOM_STATE))
+    clf.fit(X_train, y_train)
+    pred = np.array([est.predict(X_val) for est in clf.estimators_]).T
+
+    metrics = {
+        "macro_f1": float(f1_score(y_val, pred, average="macro", zero_division=0)),
+        "micro_f1": float(f1_score(y_val, pred, average="micro", zero_division=0)),
+    }
+    import joblib
+    joblib.dump(clf, MODEL_DIR / "serp_classifier.joblib")
+    joblib.dump(labels, MODEL_DIR / "label_columns.joblib")
+    with open(MODEL_DIR / "metrics.json", "w") as f:
+        json.dump(metrics, f, indent=2)
+    print("Metrics:", metrics)
+
+
+if __name__ == "__main__":
+    main()