uni9ja-intent 0.1.4
A lightweight Nigerian-focused intent classifier using SpaCy and PyTorch
Requires Python: >=3.8

# Uni9ja Intent Classifier

A lightweight, high-performance Intent Classification library built on **PyTorch** and **SpaCy**. This library allows you to identify user intentions in text using word embeddings.

## 🛠 Features

- **Three-Mode Logic**: Use our pretrained model, fine-tune it with your data, or train a new one from scratch.
- **SpaCy Integration**: Uses `en_core_web_md` for high-quality semantic vectors.
- **Auto-Adaptive Architecture**: Automatically rebuilds the model head if you add new intent categories during fine-tuning.
- **Production Ready**: Includes Early Stopping, Learning Rate Scheduling, and Dropout for regularization.

---

## Installation

1. Clone the repository:

```bash
git clone https://github.com/Perfect-Aimers-Enterprise/uni9ja_nlp.git
cd uni9ja_intent

```

2. Install the library:

```bash
pip install uni9ja-intent

```

3. Download the language model:

```bash
python -m spacy download en_core_web_md

```

---

## Usage Guide

### 1. Using the Pretrained Model (Inference)

If you just want to use the model out of the box to predict intents:

```python
from uni9ja_intent import IntentModel

# Initialize and load weights
model = IntentModel()
model.load_model("pretrained/uni9ja_intent.pth")

# Predict
intent, confidence = model.predict("How do I sign up for the project?")
print(f"Intent: {intent} ({confidence:.2%})")

```

### 2. Fine-tuning with New Data

Use this when you want the model to keep its old knowledge but learn a few new phrases or categories.

```python
new_data = [
    {"text": "I want to hire a freelancer", "label": "hire_request"},
    {"text": "Is there a discount for students?", "label": "pricing_query"}
]

model.finetune(new_data, epochs=20, save_path="pretrained/uni9ja_intent_v2.pth")

```

### 3. Training from Scratch (Custom Logic)

Use this if you have a completely different dataset and want to build a brand new brain.

```python
my_custom_data = [
    {"text": "What is the weather?", "label": "weather"},
    {"text": "Play some music", "label": "media_control"},
    # ... more data
]

# Passing data to __init__ triggers the training setup
model = IntentModel(data=my_custom_data, hidden_dims=[256, 128], dropout=0.4)
model.train(epochs=100)
model.save_model("my_custom_model.pth")

```

---

## Project Structure

```text
.
├── pretrained/           # Saved .pth model checkpoints
├── uni9ja_intent/        # Core Library Source
│   ├── __init__.py       # Package entry point
│   ├── model.py          # PyTorch Neural Network Architecture
│   ├── trainer.py        # IntentModel Manager Class
│   └── spacy_loader.py   # Vectorization logic
├── setup.py              # Pip installation script
└── requirements.txt      # Dependencies

```

---

## Configuration Parameters

| Parameter     | Default     | Description                                             |
| ------------- | ----------- | ------------------------------------------------------- |
| `hidden_dims` | `[128, 64]` | The size of the hidden layers in the MLP.               |
| `dropout`     | `0.3`       | Probability of dropping neurons (prevents overfitting). |
| `threshold`   | `0.6`       | Minimum confidence score to return a label.             |

---

### Pro-Tip for Terminal Users

To see your folder structure like the one in this documentation, remember to use the command we set up earlier:
`tree -I '__pycache__|.git'`

**Would you like me to create a `test.py` script for you that automatically verifies if all these features are working correctly?**

# Loading Data in Code

You can now load your files directly using the built-in utility:

Python
from uni9ja_intent import IntentModel, load_data

# 1. Load data from file

training_data = load_data("path/to/your_data.json")

# 2. Feed it to the model

model = IntentModel(data=training_data)
model.train(epochs=50)