HSN Code Assistant

Overview

The HSN Code Assistant is designed to help users find and understand HSN codes through natural language queries. It leverages ADK's agent architecture and tool system to provide intelligent responses about HSN codes and their classifications.

Features

• Find and understand HSN codes through natural language queries
• Exact HSN code matching
• Prefix matching for category exploration
• Hierarchical code understanding
• Description search with multi-term matching
• Partial word matching
• Category-based search
• Relevance-based ordering of results
• Duplicate removal in results
• Results limited to the top 5 matches for readability
• Responses include HSN codes with descriptions
• Category hierarchies included when relevant
• Suggestions for refined searches
• Error messages with helpful alternatives
• Input validation for empty queries and invalid code formats
• Missing data handling
• HSN data loaded from CSV once at startup, with column name normalization and type conversion
• Session management for user isolation via ADK's InMemorySessionService

ADK components used

• Agent — uses ADK's Agent class for the main interaction logic, configured with a Gemini model for natural language understanding and custom instructions for HSN code interpretation and response formatting.
• FunctionTool — implements HSN lookup as an ADK tool, handling both code-based and description-based searches, and returning structured responses with matches and metadata.
• Runner & session management — uses ADK's Runner for agent execution and InMemorySessionService for session handling, with proper event processing for responses.
• Message handling — uses ADK's content types for structured messaging, with role-based interactions and event-based response processing.

Data handling strategy

• Data loading — HSN data is loaded from a CSV file once at startup, with column name normalization and type conversion for HSN codes.
• Search implementation — numeric queries use direct HSN code prefix matching, text queries use multi-term search across descriptions, and results are limited to the top 5 matches for readability.
• Validation logic — input validation for empty queries, type checking for HSN codes, error handling with helpful suggestions, and duplicate prevention in results.

Implementation steps

• Project setup — pip install -r requirements.txt, then set up .env with GOOGLE_API_KEY.
• ADK configuration — configure genai with the API key and create the agent with custom instructions: Agent(name="hsn_assistant", model="gemini-2.0-flash", instruction=..., tools=[hsn_tool]).
• Tool implementation — wrap the search in an ADK tool: hsn_tool = FunctionTool(func=lookup_hsn), where lookup_hsn(query: str) returns the HSN code search results.
• Session management — set up InMemorySessionService, create a session, and configure Runner(agent=hsn_agent, app_name="hsn_assistant", session_service=session_service).

Usage examples

• "What is HSN code 0101?" — returns that HSN code 0101 refers to live horses, asses, mules, and hinnies.
• "Tell me about HSN codes for live animals" — returns that HSN code 01 covers all live animals.
• "Find HSN codes for fish" — returns the relevant fish-related HSN codes and descriptions.

Environment setup

• Required environment variable: GOOGLE_API_KEY
• Dependencies: google-adk, python-dotenv, pandas, google-generativeai

Security notes & best practices

• The API key is stored in a .env file, kept out of version control.
• Session management keeps users isolated from one another.
• Input validation guards against injection.
• Code organization — modular tool implementation, clear separation of concerns, and consistent error handling.
• ADK usage — proper event handling, type-safe message passing, and session state management.
• Data management — efficient data loading, memory-conscious search, and result limiting for performance.

Future improvements

• Enhanced search — fuzzy matching, synonym support, and multi-language support.
• Performance — data indexing, cache implementation, and batch processing.
• Features — history tracking, export functionality, and custom categorizations.