README.md

---
license: apache-2.0
datasets:
- custom
- chatgpt
new_version: v1.1
language:
- en
tags:
- token-classification
- ner
- travel
- trip-planning
- bert
- transformers
- fine-tuned
- bio-tagging
- custom-dataset
- pytorch
- english
- tripplan
- lightweight
- nlp
metrics:
- accuracy
- f1
- precision
- recall
base_model:
- boltuix/bert-mini
pipeline_tag: token-classification
library_name: transformers
model_size: ~15MB
---

![Banner](https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhDKgyzoi0qzMMC61gfMkXQIDabui00AESMZZqoR5SMaOiIOQpyIk5goCfROnNhhRNy69qi5r8SbvmAMuiK2i8M6-iiSxTjd7guIG3FRji2NG1ASZBPOh-bRxrmbFOZJfSNbe51XqKOymeiW-axm7WcY2B05LFarh87iFvmmPmno5WgvncdyKDkJV93Aqo/s2938/route-bert.jpg)

# 🗺️ RouteNER: Trip Planning Entity Recognition 🚉✈️🚗

## 🚀 Overview
`RouteNER` is a lightweight (~15MB) BERT-based model meticulously fine-tuned for **Trip Planning Entity Recognition (NER)** 🧭. Designed to extract critical entities such as **"From"** (origin), **"To"** (destination), and **"Mode"** (transportation method) from natural language travel queries, `RouteNER` empowers travel assistants 🤖, chatbots 💬, navigation systems 🗺️, and more. Its compact size and high accuracy make it ideal for deployment in resource-constrained environments, delivering robust performance without sacrificing speed.

### 🎯 Example
- **Input:** *"I want to travel from New York to Chicago by train."*
- **Output:**
  - 📍 "New York" → `From`
  - 📍 "Chicago" → `To`
  - 🚆 "train" → `Mode`

---

## 🌟 What is Natural Language Processing (NLP)?
Natural Language Processing (NLP) is a field of artificial intelligence that enables machines to understand, interpret, and generate human language. By combining linguistics, computer science, and machine learning, NLP powers applications like chatbots, translation services, and sentiment analysis. `RouteNER` leverages NLP to process travel-related queries, transforming unstructured text into structured, actionable data.

## 🔍 What is Named Entity Recognition (NER)?
Named Entity Recognition (NER) is a subtask of NLP that identifies and classifies key entities in text, such as names, locations, or organizations. In the context of `RouteNER`, NER is used to extract travel-specific entities (`From`, `To`, `Mode`) with high precision, enabling seamless integration into travel planning workflows.

## 🎯 Purpose of RouteNER
`RouteNER` is purpose-built to streamline trip planning by accurately extracting essential travel details from user queries. Whether you're building a virtual travel agent, a navigation app, or a customer service chatbot, `RouteNER` provides a reliable, lightweight solution for understanding user intent and delivering relevant responses. Its focus on travel-specific entities makes it a specialized tool for the tourism and transportation industries.

---

## 🌟 Key Features

| ✨ Feature                | 📌 Description                                                                |
|--------------------------|------------------------------------------------------------------------------|
| **🎯 Task**              | Named Entity Recognition (NER) for trip planning queries.                    |
| **🔍 Entities**          | `From` (origin), `To` (destination), `Mode` (transportation method).         |
| **🤖 Model**             | Fine-tuned BERT-mini (`boltuix/bert-mini`) for token classification.         |
| **🌐 Language**          | English.                                                                     |
| **⚖️ Model Size**        | ~15MB, optimized for low-resource environments like mobile devices.          |
| **📚 Library**           | Hugging Face Transformers.                                                   |
| **🔧 Framework**         | PyTorch.                                                                     |
| **🚀 Deployment**        | Lightweight design ensures fast inference, even on edge devices.             |

---

## 🧠 About the Base Model: bert-mini
`RouteNER` is built upon `boltuix/bert-mini`, a compact variant of the BERT (Bidirectional Encoder Representations from Transformers) architecture. Unlike traditional NLP models that process text unidirectionally, BERT's bidirectional approach captures contextual relationships by analyzing both preceding and following words in a sentence. This enables `RouteNER` to understand nuanced travel queries with high accuracy.

### Why bert-mini?
- **Lightweight Design**: With only ~15MB in size, `bert-mini` is significantly smaller than larger BERT models (e.g., BERT-base at ~440MB), making it ideal for resource-constrained environments like mobile apps or IoT devices.
- **Bidirectional Contextual Understanding**: The model excels at interpreting complex sentence structures, ensuring accurate tagging of entities like locations and transportation modes.
- **Efficient Training**: During fine-tuning, `bert-mini` allowed rapid experimentation with part-of-speech tagging and BIO (Beginning, Inside, Outside) schemes, resulting in a robust and precise NER model.
- **Scalability**: Its small footprint enables seamless scaling across various platforms, from cloud servers to edge devices, without compromising performance.

By leveraging `bert-mini`, `RouteNER` achieves a balance of accuracy, speed, and efficiency, making it a go-to solution for travel-related NLP tasks.

---

## 🛠️ Installation
Get started with `RouteNER` by installing the required dependencies:

```bash
pip install transformers torch
```

---

## 🚀 Usage

### ✅ Basic Example
Use the Hugging Face `pipeline` for quick and easy inference.

```python
from transformers import pipeline

# 🤖 Load the model
ner_pipeline = pipeline("token-classification", model="boltuix/RouteNER", aggregation_strategy="simple")

# 📝 Input travel query
query = "I want to travel from New York to Chicago by train."

# 🧠 Perform NER
results = ner_pipeline(query)

# 📤 Display extracted entities
print(results)
```

🔎 **Sample Output**
```json
[
  {"entity_group": "from_loc", "word": "New York", "score": 0.999},
  {"entity_group": "to_loc", "word": "Chicago", "score": 0.998},
  {"entity_group": "transport_mode", "word": "train", "score": 0.997}
]
```

### 💡 Structured Trip Planning Example
Extract entities into a structured JSON format for integration into travel applications.

```python
from transformers import pipeline
import json

# 🚀 Load the NER model
ner_pipeline = pipeline("token-classification", model="boltuix/RouteNER", aggregation_strategy="simple")

# 🧾 Input query
query = "Plan a trip to New York from San Francisco by flight."

# 🧠 Perform NER
results = ner_pipeline(query)

# 📦 Initialize output dictionary
output = {
    "from": "",
    "to": "",
    "mode": ""
}

# 🧹 Extract entities
for item in results:
    entity = item["entity_group"]
    word = item["word"].strip(".").strip()
    if entity == "from_loc":
        output["from"] = word
    elif entity == "to_loc":
        output["to"] = word
    elif entity == "transport_mode":
        output["mode"] = word

# 🖨️ Print structured output
print(json.dumps(output, indent=2))
```

🔎 **Sample Output**
```json
{
  "from": "San Francisco",
  "to": "New York",
  "mode": "flight"
}
```

---

## 📊 Test Cases
Below are diverse test cases showcasing `RouteNER`'s ability to handle a wide range of travel queries, including complex and unconventional inputs.

✅ **Test Case 1**  
**Sentence:** Take a flight from San Francisco to Los Angeles.  
**Output:**  
- From: San Francisco  
- To: Los Angeles  
- Mode: flight  

✅ **Test Case 2**  
**Sentence:** I need a bus ticket from Houston to Austin.  
**Output:**  
- From: Houston  
- To: Austin  
- Mode: bus  

✅ **Test Case 3**  
**Sentence:** Navigate me from Thompsonburgh - Port MH to Clark LLC HQ 163 5756 Salazar Rapids Suite 176 East Patrickfurt NC 56993 Cook Islands using FlixBus ride.  
**Output:**  
- From: Thompsonburgh - Port MH  
- To: Clark LLC HQ 163 5756 Salazar Rapids Suite 176 East Patrickfurt NC 56993 Cook Islands  
- Mode: FlixBus ride  

✅ **Test Case 4**  
**Sentence:** Guide me from New Jacqueline Region MA to Port Christine AR via horse-drawn carriage ride.  
**Output:**  
- From: New Jacqueline Region MA  
- To: Port Christine AR  
- Mode: horse-drawn carriage ride  

✅ **Test Case 5**  
**Sentence:** Take me from Franklinfurt Downtown MH to Government Stephanieburgh MN 05480 with Canadian VIA Rail.  
**Output:**  
- From: Franklinfurt Downtown MH  
- To: Government Stephanieburgh MN 05480  
- Mode: Canadian VIA Rail  

✅ **Test Case 6**  
**Sentence:** Book a ferry from Miami to the Bahamas.  
**Output:**  
- From: Miami  
- To: Bahamas  
- Mode: ferry  

✅ **Test Case 7**  
**Sentence:** Plan a road trip from Seattle to Yellowstone National Park by car.  
**Output:**  
- From: Seattle  
- To: Yellowstone National Park  
- Mode: car  

---

## 💼 Use Cases
`RouteNER` is versatile and can be applied across various domains. Here are some exciting use cases:

1. **🧳 Travel Assistants**: Power virtual travel agents that extract trip details to recommend flights, trains, or buses.
2. **📱 Navigation Apps**: Enhance GPS apps by parsing user queries to provide tailored route suggestions.
3. **💬 Customer Service Chatbots**: Automate responses for travel agencies by identifying key trip details from customer inquiries.
4. **📅 Event Planning**: Extract travel logistics from event invites or schedules to assist with group travel coordination.
5. **🌍 Tourism Platforms**: Enable seamless trip planning by integrating `RouteNER` into websites or apps for destination exploration.
6. **🚀 IoT Devices**: Deploy on smart devices (e.g., in-car systems) for voice-activated travel planning with minimal computational overhead.
7. **📊 Data Analytics**: Process large volumes of travel-related user queries to identify trends in transportation preferences or popular destinations.

---

## 📈 Model Performance
Evaluated on a custom dataset, `RouteNER` delivers impressive results:

| Metric     | Score  |
|------------|--------|
| Accuracy   | 0.95   |
| Precision  | 0.94   |
| Recall     | 0.93   |
| F1-Score   | 0.94   |

These metrics reflect the model's ability to accurately identify and classify travel entities, even in complex or ambiguous queries.

---

## 🗂️ Dataset
`RouteNER` was fine-tuned on a robust dataset comprising:  
- **Custom Dataset**: Carefully curated travel queries with annotated entities (`From`, `To`, `Mode`) to ensure high-quality training data.  
- **ChatGPT-Generated Data**: Synthetic travel queries to enhance dataset diversity, covering a wide range of transportation modes and location formats.  

The dataset includes both simple queries (e.g., "Fly from Boston to Miami") and complex ones (e.g., addresses with detailed location descriptions), ensuring `RouteNER` generalizes well across real-world scenarios.

---

## ⚙️ Training Details
- **Base Model**: `boltuix/bert-mini`  
- **Fine-Tuning**: Conducted using PyTorch and Hugging Face Transformers.  
- **Tagging Scheme**: BIO (Beginning, Inside, Outside) for precise token classification.  
- **Hyperparameters**:  
  - Learning Rate: 2e-5  
  - Epochs: 3  
  - Batch Size: 16  
- **Training Focus**: Optimized for bidirectional contextual understanding, leveraging `bert-mini`'s architecture to capture part-of-speech relationships and entity boundaries.

---

## 🌐 Integration Options
Unlock the full potential of `RouteNER` with these integration ideas:  
- **Live Demo**: Contact us to explore a hosted demo showcasing real-time NER capabilities.  
- **API Integration**: Deploy via Hugging Face Inference API or your own server for scalable applications.  
- **UI Wrapper**: Build interactive interfaces with Gradio or Streamlit for user-friendly trip planning tools.  
- **Edge Deployment**: Leverage the model's lightweight nature for on-device inference in mobile or IoT applications.  
- **Custom Fine-Tuning**: Reach out to tailor `RouteNER` for specific domains or additional entities.  

---

## 📜 License
This model is licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).

---

## 🙌 Acknowledgments
- Built on the foundation of `boltuix/bert-mini`.  
- Gratitude to the Hugging Face team for the Transformers library and ecosystem.  
- Special thanks to contributors who provided custom annotations and synthetic data via ChatGPT.  

---

## 📬 Contact
We’d love to hear from you! For questions, feedback, or collaboration opportunities:  
- 📧 Email: [email protected]  
- 🌐 Website: [boltuix.com](https://boltuix.com)  
- 🐦 X: [@BoltUIX](https://x.com/BoltUIX)  

Plan your next adventure with `RouteNER`! 🌍✈️🚄🧳