Upload folder using huggingface_hub

.env.example

@@ -0,0 +1,5 @@
+# QueryIntent-Entity-NER
+DATA_PATH=data/query_intent.csv
+MODEL_DIR=models
+HF_MODEL=bert-base-uncased
+RANDOM_STATE=42

README.md

@@ -0,0 +1,69 @@
+# QueryIntent-Entity-NER: Query Intent and Entity Extraction for SEO
+
+**Type:** Academic | **Domain:** SEO, NLP  
+**Hugging Face:** [syeedalireza/query-intent-entity-ner](https://huggingface.co/syeedalireza/query-intent-entity-ner)
+
+Multi-task: query intent classification and named-entity extraction for search content planning.
+
+## 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 intent (informational, navigational, transactional) and key entities in queries improves content and keyword strategy.
+
+## Approach
+
+- **Intent:** Multi-class (e.g. informational / navigational / transactional / commercial).
+- **Entities:** NER (ORG, PRODUCT, LOC, etc.) from query text.
+- **Models:** Hugging Face transformer (e.g. BERT) for sequence classification + token classification, or pipeline with spaCy/transformers.
+
+## Tech Stack
+
+| Category | Tools |
+|----------|------|
+| NLP | Hugging Face Transformers, tokenizers |
+| NER | spaCy (optional), transformers NER head |
+| ML | PyTorch, scikit-learn |
+| Data | pandas, NumPy |
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+```bash
+python train.py
+python inference.py --query "best running shoes for flat feet"
+```
+
+## Project structure
+
+```
+03_query-intent-entity-ner/
+├── config.py
+├── train.py           # BERT (or HF) sequence classification
+├── inference.py       # Single query or batch CSV; CPU/GPU auto
+├── requirements.txt
+├── .env.example
+├── data/
+│   └── query_intent.csv   # Sample: query, intent
+└── models/
+```
+
+## Data
+
+- **Sample data (included):** `data/query_intent.csv` — columns: `query`, `intent`.
+- **Intent labels:** `informational`, `navigational`, `transactional`, `commercial`.
+- Set `DATA_PATH` in `.env` if using another file.
+
+## License
+
+MIT.

config.py

@@ -0,0 +1,16 @@
+"""
+Configuration for QueryIntent-Entity-NER.
+"""
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent
+DATA_PATH = os.getenv("DATA_PATH", str(BASE_DIR / "data" / "query_intent.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"))
+
+INTENT_LABELS = ["informational", "navigational", "transactional", "commercial"]
+QUERY_COLUMN = "query"
+INTENT_COLUMN = "intent"
+MODEL_DIR.mkdir(parents=True, exist_ok=True)

data/query_intent.csv

@@ -0,0 +1,20 @@
+query,intent
+what is seo,informational
+how to rank on google,informational
+nike official store,navigational
+buy wireless headphones,transactional
+best CRM software comparison,commercial
+python documentation,navigational
+why is the sky blue,informational
+cheap flight tickets,transactional
+difference between http and https,informational
+amazon login,navigational
+best project management tools,commercial
+how to install docker,informational
+shop running shoes,transactional
+linkedin homepage,navigational
+what is tensorflow,informational
+best antivirus 2024,commercial
+how to make pasta,informational
+netflix sign in,navigational
+buy domain name,transactional

inference.py

@@ -0,0 +1,55 @@
+"""
+Predict query intent for one or more queries.
+"""
+import argparse
+from pathlib import Path
+
+import pandas as pd
+import torch
+from transformers import AutoTokenizer, AutoModelForSequenceClassification
+
+from config import MODEL_DIR, INTENT_LABELS
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--query", type=str, help="Single query")
+    parser.add_argument("--input", type=str, help="CSV with 'query' column")
+    parser.add_argument("--output", type=str, default="predictions.csv")
+    args = parser.parse_args()
+
+    if not (MODEL_DIR / "config.json").exists():
+        raise FileNotFoundError(f"Train first. No model in {MODEL_DIR}")
+
+    tokenizer = AutoTokenizer.from_pretrained(str(MODEL_DIR))
+    model = AutoModelForSequenceClassification.from_pretrained(str(MODEL_DIR))
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model = model.to(device)
+
+    def predict(queries: list[str]):
+        inp = tokenizer(queries, truncation=True, max_length=128, padding=True, return_tensors="pt")
+        inp = {k: v.to(device) for k, v in inp.items()}
+        with torch.no_grad():
+            out = model(**inp)
+        return out.logits.argmax(dim=1).tolist()
+
+    if args.query:
+        idx = predict([args.query])[0]
+        print({"query": args.query, "intent": INTENT_LABELS[idx]})
+        return
+
+    if args.input and Path(args.input).exists():
+        df = pd.read_csv(args.input)
+        if "query" not in df.columns:
+            raise ValueError("CSV must have 'query' column")
+        indices = predict(df["query"].astype(str).tolist())
+        df["intent"] = [INTENT_LABELS[i] for i in indices]
+        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 @@
+# QueryIntent-Entity-NER
+# Python 3.9+
+
+torch>=1.12.0
+transformers>=4.20.0
+tokenizers>=0.12.0
+datasets>=2.0.0
+scikit-learn>=1.0.0
+pandas>=1.3.0
+numpy>=1.21.0

train.py

@@ -0,0 +1,101 @@
+"""
+Train query intent classifier.
+Uses Hugging Face transformer for sequence classification.
+"""
+import json
+from pathlib import Path
+
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from sklearn.metrics import classification_report, f1_score
+from transformers import (
+    AutoTokenizer,
+    AutoModelForSequenceClassification,
+    TrainingArguments,
+    Trainer,
+)
+from datasets import Dataset
+
+from config import (
+    DATA_PATH,
+    MODEL_DIR,
+    RANDOM_STATE,
+    HF_MODEL,
+    QUERY_COLUMN,
+    INTENT_COLUMN,
+    INTENT_LABELS,
+)
+
+
+def load_data(path: str) -> pd.DataFrame:
+    df = pd.read_csv(path)
+    if QUERY_COLUMN not in df.columns or INTENT_COLUMN not in df.columns:
+        raise ValueError(f"Need columns: {QUERY_COLUMN}, {INTENT_COLUMN}")
+    return df
+
+
+def main():
+    if not Path(DATA_PATH).exists():
+        print(f"Data not found at {DATA_PATH}. Create data/query_intent.csv with query, intent.")
+        return
+
+    df = load_data(DATA_PATH)
+    df[INTENT_COLUMN] = pd.Categorical(df[INTENT_COLUMN], categories=INTENT_LABELS)
+    df["label"] = df[INTENT_COLUMN].cat.codes
+
+    train_df, val_df = train_test_split(df, test_size=0.2, random_state=RANDOM_STATE, stratify=df["label"])
+
+    tokenizer = AutoTokenizer.from_pretrained(HF_MODEL)
+    model = AutoModelForSequenceClassification.from_pretrained(HF_MODEL, num_labels=len(INTENT_LABELS))
+
+    def tokenize(examples):
+        return tokenizer(examples[QUERY_COLUMN], truncation=True, max_length=128, padding="max_length")
+
+    train_ds = Dataset.from_pandas(train_df[["query", "label"]].rename(columns={"query": QUERY_COLUMN}))
+    val_ds = Dataset.from_pandas(val_df[["query", "label"]].rename(columns={"query": QUERY_COLUMN}))
+    train_ds = train_ds.map(tokenize, batched=True, remove_columns=[QUERY_COLUMN])
+    val_ds = val_ds.map(tokenize, batched=True, remove_columns=[QUERY_COLUMN])
+    train_ds.set_format("torch")
+    val_ds.set_format("torch")
+
+    args = TrainingArguments(
+        output_dir=str(MODEL_DIR),
+        num_train_epochs=3,
+        per_device_train_batch_size=16,
+        per_device_eval_batch_size=32,
+        evaluation_strategy="epoch",
+        save_strategy="epoch",
+        load_best_model_at_end=True,
+        metric_for_best_model="f1",
+        greater_is_better=True,
+    )
+
+    def compute_metrics(eval_pred):
+        preds = eval_pred.predictions.argmax(axis=1)
+        return {"f1": float(f1_score(eval_pred.label_ids, preds, average="macro"))}
+
+    trainer = Trainer(
+        model=model,
+        args=args,
+        train_dataset=train_ds,
+        eval_dataset=val_ds,
+        compute_metrics=compute_metrics,
+    )
+    trainer.train()
+    trainer.save_model(str(MODEL_DIR))
+    tokenizer.save_pretrained(str(MODEL_DIR))
+
+    pred = trainer.predict(val_ds)
+    report = classification_report(
+        val_df["label"].values,
+        pred.predictions.argmax(axis=1),
+        target_names=INTENT_LABELS,
+        output_dict=True,
+    )
+    with open(MODEL_DIR / "metrics.json", "w") as f:
+        json.dump({"classification_report": report}, f, indent=2)
+    print(classification_report(val_df["label"].values, pred.predictions.argmax(axis=1), target_names=INTENT_LABELS))
+
+
+if __name__ == "__main__":
+    main()