Push streamlit app to hugging face

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,16 @@
+# virtual environments
+venv/
+.venv/
+
+# python cache
+__pycache__/
+
+# log info and local stuff 
+*.log
+.DS_Store
+.idea/
+.vscode/
+
+# Environment & secrets
+.env
+env/

README.md

@@ -17,3 +17,93 @@ Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :hear
 
 If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
 forums](https://discuss.streamlit.io).
+
+
+# Car Dealership VIN Lookup App
+
+![alt text](logo_image.png)
+
+## 📌 Overview
+This is a simple app for a car dealership that allows users to look up vehicle information (year, make, and model) by entering a VIN number.  
+
+Additionally, the app keeps track of search frequency and lets users view the **Top 3 most looked-up vehicle makes**.  
+
+All vehicle data is retrieved from the [NHTSA (National Highway Traffic Safety Administration) VIN decoding API](https://vpic.nhtsa.dot.gov/api/), accessed via the helper module [`nhtsa_api_call.py`](./nhtsa_api_call.py).
+
+---
+
+## ⚙️ Features
+- 🔍 Lookup vehicle details (year, make, model) by VIN number 
+- 📊 View the **Top 3 most searched vehicle makes**  
+- 🌐 Fetches real-time data from the **NHTSA VIN API**  
+- 🖥️ Simple and interactive command-line interface  
+
+---
+## 📦 Python Version
+
+Tested on: Python 3.10
+
+---
+## 🚀 Getting Started
+
+**How to run locally**
+
+1. Clone the Repository
+git clone https://github.com/averyestopinal/AIPI503PROJECT
+cd AIPI503PROJECT
+
+2. Create a virtual environment (optional but recommended):
+python -m venv .venv
+source .venv/bin/activate        # macOS/Linux
+.venv\Scripts\activate           # Windows
+
+3. Install Dependencies
+This app uses only standard Python libraries (no external dependencies).However, make sure you are running Python 3.7+.
+pip install -r requirements.txt
+
+4. Run the Streamlit app:
+streamlit run streamlit_app.py
+
+**How to Run cli_demo.py**
+This is a simple command-line version of the VIN decoder. Make sure your terminal is in the same directory as cli_demo.py.
+
+python cli_demo.py
+
+**Link to the Hugging Faces Space**
+
+
+---
+
+🧩 Project Structure
+.
+├── streamlit_app.py                # Entry point for the Streamlit application
+├── cli_demo.py                     # Command-line interface version of the VIN decoder
+├── nhtsa_api_call.py               # Helper module for API requests
+├── car_image.png                   # Image file used in the Streamlit application
+├── logo_image.py                   # Logo image file used in the Streamlit application
+├── README.md                       # Project documentation
+├── requirements.txt                # Python Dependencies 
+
+---
+📡 API Reference
+The app uses the NHTSA VIN Decoder API which provides vehicle details when supplied with a VIN number.
+
+Example request: https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/<VIN>?format=json
+
+---
+🙌 Credits
+NHTSA Vehicle API
+Streamlit
+Hugging Face Spaces
+
+---
+👨‍💻 Author
+Developed as part of a learning project by
+1. Avery Estopinal
+2. Sharmil K
+3. Eugenia Tate
+4. Jaideep Aher
+---
+
+Contributions are welcome!
+Feel free to fork and submit a pull request 🚀

cli_demo.py

@@ -0,0 +1,121 @@
+"""
+cli_demo.py
+
+Author: Eugenia Tate
+Date: August 24, 2025
+
+A simple command-line application for a car dealership that allows users 
+to look up vehicle information (year, make, and model) by VIN number. 
+The app also lets a user view top 3 looked up vehicle makes.
+The data is retrieved from the NHTSA (National Highway Traffic Safety 
+Administration) VIN decoding API via the helper module `nhtsa_api_call.py`.
+
+Usage:
+    python cli_demo.py
+"""
+import nhtsa_api_call, re, csv, os
+import pandas as pd
+
+TOP3 = 3
+
+def is_valid_vin (vin):
+    """
+    Check whether vin is valid.
+    A valid VIN is a VIN of 17 alphanumeric characters long and can not 
+    include I, O, Q. 
+    """
+    vin = vin.upper()
+    if len(vin) != 17:
+        return False 
+    if not re.match(r'^[A-HJ-NPR-Z0-9]{17}$', vin):
+        return False
+    return True
+
+def save_vehicle(year, make, model, filename = "vin_lookup_history.csv"):
+    """Append VIN lookup result to a CSV file."""
+    file_exists = os.path.isfile(filename)
+    with open(filename, "a", newline="") as f:
+        writer = csv.writer(f)
+        if not file_exists:
+            # add first row
+            writer.writerow(["year", "make", "model"])  
+        writer.writerow([year, make, model])
+
+def display_top3(filename = "vin_lookup_history.csv"):
+    """Show top 3 car makes by lookup frequency"""
+    # if file does not exist then there is no history yet
+    if not os.path.isfile(filename):
+        print("\nNo VIN lookup history found. Please look up some VINs first.\n")
+        return
+    # create a dataframe using file data 
+    df = pd.read_csv(filename)
+    # save number each make appears in the log as a series
+    counts = df['make'].value_counts()
+    # file exists but no data has been added yet
+    if len(counts) == 0:
+        print("\n No data in the log yet.\n")
+        return
+    # if there are  fewer than 3 data entries in the log then the program will 
+    # at least display 1 or 2 most looked up makes
+    if len(counts) < TOP3:
+        print(f"\nNot enough data for displaying top 3. Showing top {len(counts)} instead:\n")
+        top_makes = counts.head(len(counts))
+    else:
+        print(f"\n Top {TOP3} Car Makes from Lookups:\n")
+        top_makes = counts.head(TOP3)
+
+    for make, count in top_makes.items():
+        print(f"   {make}: {count} lookups")
+    # an empty line print to space out CLI prompts
+    print()  
+
+def main():
+    """
+    Run the command-line VIN lookup loop.
+
+    Prompts the user for a VIN number, calls the NHTSA API,
+    and prints out the vehicle information if found.
+    Enter '0' to exit.
+    """
+    print("🚗 Welcome to the Car Dealership VIN Lookup!\n")
+   
+    while True:
+        print("Choose an option from the menu:")
+        print("1. Lookup a VIN")
+        print("2. Show Top 3 Most Looked-up Makes")
+        print("0. Exit")
+        choice = input("Enter your choice: ").strip()
+        
+        # exit condition gets checked first
+        if choice == "0":
+            print("👋 You chose to exit VIN lookup. Goodbye!")
+            break
+        # user selected to add a VIN
+        elif choice == "1": 
+            vin = input("Please enter a valid VIN or 0 (zero) to exit: \n").strip()
+            if vin == "0":
+                continue
+            # check if vin is valid, and if not print error message
+            if not is_valid_vin(vin): 
+                print("Invalid VIN format. Must be 17 letters/numbers (no I, O, Q). Try again.\n")
+                continue
+            # vin is valid, perform VIN lookup
+            else:
+                year, make, model = nhtsa_api_call.get_vehicle_info(vin)
+                if year and make and model:
+                    print(f"✅ VIN {vin}")
+                    print(f"   Year: {year}")
+                    print(f"   Make: {make}")
+                    print(f"   Model: {model}")
+                    save_vehicle(year, make, model)     #save the data in the lookup history file
+                else:
+                    print(f"❌ VIN {vin} not found in database. Try again.")
+        # user selected to view top3 vehicle makes 
+        elif choice == "2":
+            display_top3()
+        # user entered something other than 1,2 or 0
+        else:
+            print("Invalid option. Please choose 1, 2, or 0.\n")
+
+if __name__ == "__main__":
+    main()

nhtsa_api_call.py

@@ -0,0 +1,22 @@
+import requests
+
+def get_vehicle_info(vin):
+    """
+    This function takes the parameter "vin" and uses the NHTSA Decode VIN API to retrive year, make, and model
+    The API returns a JSON file which is not a dictionary so the file must be searched with a for loop by "Variable"
+    For more API information visit https://vpic.nhtsa.dot.gov/api/
+    """
+    url = f'https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVin/{vin}?format=json'
+    response = requests.get(url);
+    data = response.json()
+
+    for item in data["Results"]:
+        if item["Variable"] in ["Model Year"]:
+            year = item["Value"]
+        if item["Variable"] in ["Make"]:
+            make = item["Value"]
+        if item["Variable"] in ["Model"]:
+            model = item["Value"]
+    
+    return year, make, model	
+		

requirements.txt

@@ -1,3 +1,42 @@
-altair
-pandas
-streamlit
+altair==5.5.0
+attrs==25.3.0
+blinker==1.9.0
+cachetools==6.2.0
+certifi==2025.8.3
+charset-normalizer==3.4.3
+click==8.2.1
+contourpy==1.3.2
+cycler==0.12.1
+fonttools==4.59.1
+gitdb==4.0.12
+GitPython==3.1.45
+idna==3.10
+Jinja2==3.1.6
+jsonschema==4.25.1
+jsonschema-specifications==2025.4.1
+kiwisolver==1.4.9
+MarkupSafe==3.0.2
+matplotlib==3.10.5
+narwhals==2.2.0
+numpy==2.2.6
+packaging==25.0
+pandas==2.3.2
+pillow==11.3.0
+protobuf==6.32.0
+pyarrow==21.0.0
+pydeck==0.9.1
+pyparsing==3.2.3
+python-dateutil==2.9.0.post0
+pytz==2025.2
+referencing==0.36.2
+requests==2.32.5
+rpds-py==0.27.0
+six==1.17.0
+smmap==5.0.2
+streamlit==1.49.0
+tenacity==9.1.2
+toml==0.10.2
+tornado==6.5.2
+typing_extensions==4.15.0
+tzdata==2025.2
+urllib3==2.5.0

streamlit_app.py

@@ -0,0 +1,204 @@
+"""
+VIN Decoder Streamlit App
+
+This app allows users to input a Vehicle Identification Number (VIN) and fetch vehicle
+information (year, make, model). The data is retrieved from the NHTSA (National Highway Traffic Safety 
+Administration) VIN decoding API via the helper module `nhtsa_api_call.py`.
+Useful for car dealerships who need quick VIN lookups.
+
+Usage:
+    streamlit run streamlit_vin_decoder.py
+
+Author: Sharmil Nanjappa
+Date: August 25, 2025
+"""
+
+import streamlit as st  # Import the Streamlit library for creating the web app
+import nhtsa_api_call  # Import the API call function from external file
+import os
+import re
+import pandas as pd
+import matplotlib.pyplot as plt
+from collections import Counter
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))       # Gets the current directory
+logo_img_file = os.path.join(BASE_DIR, "logo_image.png")
+car_img_file = os.path.join(BASE_DIR, "car_image.png")
+TOP3 = 3                                                    # Define top N makes to display
+
+# Check if the 'make_history' key is already in Streamlit's session state
+if "make_history" not in st.session_state:
+    # If not, initialize it as an empty list to store searched vehicle makes
+    st.session_state.make_history = []
+
+# Define a function to track the vehicle make each time a VIN is decoded
+def track_make(make):
+    """
+    Store the searched make in session state for pie chart stats.
+    """
+    # Proceed only if a valid make value is provided
+    if make:
+        # Capitalize and append the make to the session history list
+        st.session_state.make_history.append(make.title())
+        # Optional: Display the current list of searched makes in the sidebar for debugging
+        #st.sidebar.write("Debug – History:", st.session_state.make_history)
+
+
+def show_top_3_makes():
+    """
+Display a pie chart of the top 3 most searched vehicle makes.
+
+    if not st.session_state.make_history:
+            st.warning("No vehicle makes have been searched yet.")
+            return
+"""
+
+
+
+    if not st.session_state.make_history:
+        st.warning("No vehicle makes have been searched yet.")
+        return
+    
+    # Count how many times each make was searched
+    counts = Counter(st.session_state.make_history)
+    
+    if len(counts) < TOP3:
+        st.warning(f"Not enough data to display Top 3. Showing Top {len(counts)} instead.")
+
+    # Get the top N (3 or fewer)
+    top_n = counts.most_common(min(len(counts), TOP3))
+
+    labels = [item[0].upper() for item in top_n]        # Label for the vehicle make, displayed in upper case for each slice of the pie chart
+    sizes = [item[1] for item in top_n]                 # Count of each make in the Top3. Used to determine how large each slice of the pie chart is.
+    colors = ['#4682B4', '#1E3F66', '#0B1F3A'][:len(labels)]   #[colors of pie chart slices][match slice count]
+    with st.container():
+        
+        st.markdown("""
+                <div style="
+                    max-width: 700px;
+                    margin: 0 auto;
+                    padding: 12px 24px;
+                    border: 1px solid #ccc;
+                    border-radius: 10px;
+                    background-color: #f9f9f9;
+                    text-align: center;
+                    font-size: 16px;
+                    font-weight: 500;
+                ">
+                    Pie chart displaying the Top 3 Vehicles<br>
+                    searched based on their Make
+                </div>
+            """, unsafe_allow_html=True)
+
+    fig, ax = plt.subplots(figsize=(3,3), dpi=150)
+    
+    # Draw pie chart with borders and percentage labels
+    wedges, texts, autotexts = ax.pie(
+        sizes,
+        labels=labels,
+        colors=colors,
+        autopct='%1.1f%%',
+        startangle=90,          # autopct shows % and startangle starts the first slice from the top
+         wedgeprops={'edgecolor': 'white', 'linewidth': 1}
+        )
+              
+    ax.axis('equal')                                                    # Forces the chart to be a perfect circle
+
+    # Style text and labels
+    for text in texts:                                                  #The labels of each pie slice
+        text.set_fontsize(5)
+        text.set_color('#000')                                          # text color: Black
+        text.set_fontweight('semibold')
+
+    for autotext in autotexts:                                          #The percentages shown on each slice
+        autotext.set_fontsize(5)
+        autotext.set_color('#fff')                                       # text color: White
+    
+    st.pyplot(fig)
+    st.markdown("</div>", unsafe_allow_html=True)
+
+def get_vin(vin):
+    """ 
+    Decodes the VIN and displays model,make, model year.
+    Validates VIN format and displays vehicle details or error message.
+    """
+    status_area = st.empty()
+    col1, col2 = st.columns([1, 1])
+
+    if len(vin) != 17:
+        status_area.error(f"VIN must be exactly 17 characters long.")
+        return
+    elif not re.match(r'^[A-HJ-NPR-Z0-9]{17}$', vin):
+        status_area.error(f"VIN must be alpha-numeric and cannot include letters I, O, Q.")
+        return
+    else:
+        status_area.info("Decoding VIN...")
+
+    try: 
+        year, make, model = nhtsa_api_call.get_vehicle_info(vin)
+
+        if not all([year, make, model]) or any([v is None for v in [year, make, model]]):
+            status_area.warning(f"Incomplete vehicle data returned. Please verify the VIN and try again.")
+        else:
+            status_area.success("VIN decoded successfully!")
+            
+            track_make(make)
+            with col1:     
+                st.image(car_img_file, use_container_width=True)
+
+            with col2:
+                st.write(f"Below are the vehicle details :")
+                st.write("🔍 Vehicle Information")
+                st.write(f"**Make:** {make}")
+                st.write(f"**Model:** {model}")
+                st.write(f"**Model Year:** {year}")
+
+    except Exception as e:
+        status_area.error(f"An error occurred while decoding the VIN: {e}")
+
+def main():
+    """
+    Sets Streamlitcomponents for the page layout, handles user input, and calls get_vin function.
+    """
+
+    col1, col2 = st.columns([1, 2])
+    with col1:
+        st.image(logo_img_file, width=180)
+    with col2:
+            st.markdown("""
+                <div style='text-align: left; margin-top: 30px;'>
+                    <h1 style='font-size: 38px;'>Vehicle VIN Decoder</h1>
+                </div>
+            """, unsafe_allow_html=True)
+    st.write("*" * 50)
+
+    st.markdown("<h5 style='text-align: center;'>Welcome to the Car Dealership VIN Lookup!</h5>", unsafe_allow_html=True)
+    
+    
+    with st.expander("ℹ️ About this app"):
+        st.write("This app is designed to help car dealerships and automotive professionals effortlessly decode Vehicle Identification Numbers (VINs) to retrieve key vehicle details such as model,make and model year. By simply entering a 17-character VIN, users can access verified vehicle information. The data is fetched in real-time from the National Highway Traffic Safety Administration (NHTSA). Whether you're validating trade-ins, checking vehicle specs, or streamlining inventory intake, this tool delivers quick and reliable insights.")
+
+ 
+    
+    st.markdown("Enter a **17-character VIN** below to decode the vehicle info.")
+
+    vin = st.text_input("Enter VIN:", max_chars=17).strip().upper()
+    if st.button("Decode VIN", use_container_width=True):
+        if vin:
+            get_vin(vin)
+        else:
+            st.error(f"❌ Please enter a VIN before fetching the vehicle information.")
+    
+     # Show top 3 searched makes
+    st.markdown("---")
+    if st.button("Top 3 Makes Searched", use_container_width=True):
+        show_top_3_makes()
+    
+    st.markdown("___")
+    st.markdown("<p style='text-align: center; font-size: 14px;'>© 2025 Car Dealership VIN Lookup", unsafe_allow_html=True) #Footer for the webpage
+
+   
+
+
+if __name__ == "__main__":
+    main()