Create README.md
Browse files# How to Use NLU Seq2Seq Model
This guide shows you how to load and use the RC Car Command model from Hugging Face.
## What This Model Does
Converts natural language commands into robot action sequences (JSON format).
Example:
- Input: "drive forward for 5 seconds"
- Output: [{"name":"Forward","args":{"duration":5}},{"name":"Stop","args":{}}]
## Quick Start
### Step 1: Install Required Libraries
```bash
pip install huggingface-hub torch
```
### Step 2: Download and Load Model
```python
from huggingface_hub import hf_hub_download
import torch
import json
# Download model files
model_path = hf_hub_download(
repo_id="Nandhini3737/nlu-seq2seq",
filename="best_model.pt"
)
src_vocab_path = hf_hub_download(
repo_id="Nandhini3737/nlu-seq2seq",
filename="src_vocab.json"
)
tgt_vocab_path = hf_hub_download(
repo_id="Nandhini3737/nlu-seq2seq",
filename="tgt_vocab.json"
)
# Load files
model = torch.load(model_path, map_location='cpu')
with open(src_vocab_path) as f:
src_vocab = json.load(f)
with open(tgt_vocab_path) as f:
tgt_vocab = json.load(f)
print("Model loaded successfully!")
```
## Model Information
Name: NLU Seq2Seq RC Car Model
Type: Transformer Encoder-Decoder
Size: 20 MB
Parameters: 5.6M
Accuracy: 69%
Architecture Details:
- Hidden Dimension: 256
- Layers: 4 (Encoder + Decoder)
- Attention Heads: 8
- FFN Dimension: 512
Vocabularies:
- Source Tokens: 156
- Target Tokens: 28
## Supported Commands
Basic Commands:
- "drive forward"
- "drive backward"
- "turn left"
- "turn right"
- "stop"
Duration Specifications:
- "drive forward for 5 seconds"
- "go backwards for 10 seconds"
Complex Patterns:
- "drive in a square to the left"
- "make a circle going right"
- "do a zigzag starting left"
- "drive a figure eight"
## Using in Google Colab
Colab has PyTorch pre-installed. Just run:
```python
!pip install huggingface-hub --quiet
from huggingface_hub import hf_hub_download
import torch
import json
# Then follow the download steps above
```
## Loading from Cache
The first time you download, files are cached locally.
Next time, loading will be instant without downloading again.
Cache location: ./hf_models/ (or Colab cache)
## Model Output Format
The model generates JSON action sequences:
```json
[
{"name": "Forward", "args": {"duration": 5}},
{"name": "Turn_Left", "args": {}},
{"name": "Stop", "args": {}}
]
```
Available Actions:
- Forward: moves forward (duration in seconds)
- Backward: moves backward (duration in seconds)
- Turn_Left: turns left 90 degrees
- Turn_Right: turns right 90 degrees
- Stop: stops the robot
## Model Accuracy
Overall Test Accuracy: 69% (138/200 correct)
Performance by Command Type:
- Simple commands: 95%+ accuracy
- Single turns: 90%+ accuracy
- Complex patterns: 40-60% accuracy
- Long sequences: 50-70% accuracy
## Known Limitations
1. Struggles with forward/backward distinction
2. May generate incomplete JSON for very long sequences
3. Complex geometric patterns have lower accuracy
4. Works best with simple, common commands
5. English language only
## For Mobile Apps
The model can be quantized for Android/iOS apps:
- Quantized size: 5-6 MB (vs 20 MB original)
- Faster inference
- Use TFLite format for mobile
## File Structure
best_model.pt: Model weights (20 MB)
src_vocab.json: Input vocabulary
tgt_vocab.json: Output vocabulary
config.json: Model configuration
eval_report.json: Evaluation metrics
history.json: Training history
## License
MIT License - Free to use for personal and commercial projects
## Need Help?
Visit the model page: https://huggingface.co/Nandhini3737/nlu-seq2seq
## Example Usage
```python
from huggingface_hub import hf_hub_download
import torch
import json
# Setup (run once)
model = torch.load(
hf_hub_download(
repo_id="Nandhini3737/nlu-seq2seq",
filename="best_model.pt"
),
map_location='cpu'
)
with open(
hf_hub_download(
repo_id="Nandhini3737/nlu-seq2seq",
filename="src_vocab.json"
)
) as f:
src_vocab = json.load(f)
with open(
hf_hub_download(
repo_id="Nandhini3737/nlu-seq2seq",
filename="tgt_vocab.json"
)
) as f:
tgt_vocab = json.load(f)
print(f"Source vocabulary size: {len(src_vocab)}")
print(f"Target vocabulary size: {len(tgt_vocab)}")
print("Ready to use!")
# Your model is now ready for inference
```
## Next Steps
1. Load the model (steps above)
2. Prepare your input commands
3. Run inference through the model
4. Parse the output JSON
5. Execute the robot actions
For production use, add validation to handle invalid JSON output.
## Training Information
Dataset: RC Car Commands (0xAbhi/rc-car-commands)
Training Samples: 500
Test Samples: 200
Epochs: 50
Batch Size: 32
Training Time: 2-3 hours
Platform: Google Colab
## Questions?
Check the model card for more details: https://huggingface.co/Nandhini3737/nlu-seq2seq