🔢 Text to Vector Converter v1

A simple educational app that shows students how computers convert text into numbers. Perfect for teaching the basics of how AI and computers understand human language!

📚 Educational Resources

🎯 Want to understand what's happening behind the scenes?

• 📖 Understanding Text-to-Vector Conversion - Deep dive into how computers turn words into numbers
• 📊 Visual Flowcharts - Step-by-step diagrams showing the conversion process
• 🚀 Quick Start Guide - Get the app running (below)

For Teachers: These resources explain the concepts without focusing on technical implementation - perfect for classroom use!

🎯 What This App Does

🔧 Simple Features

• Two Methods: See how TF-IDF and AI models work differently
• Visual Results: Watch your text become points on a graph
• Instant Conversion: Type text and see numbers immediately
• Student-Friendly: Simple explanations for beginners
• Example Texts: Ready-to-use examples to get started

🎨 Easy to Use

• Clean Design: No confusing buttons or options
• Two-Panel Layout: Text on left, results on right
• Works Everywhere: Runs in any web browser
• Sample Texts: Click and try immediately

📊 What You Get

• Visual Map: See your text as points that move closer when similar
• Number Tables: See the exact coordinates for each sentence
• Save Results: Download your results as a file
• Fun Facts: Learn cool things about how it works

🚀 Quick Start

Using Docker (Recommended)

1. Clone or download the project
2. Clean up any existing containers and images:

   docker container prune -f
   docker image prune -a -f

3. Build and run with Docker:

   cd text-embeddings-app
   docker build -t text-embeddings-app .
   docker run -p 8501:8501 text-embeddings-app

4. Open your browser and go to http://localhost:8501

🎓 Educational Value

What Students Learn

• How AI really works - Not just magic, but mathematical processes
• Why computers need numbers - Text must be converted for processing
• Pattern recognition - Similar meanings create similar numbers
• Real-world applications - How Google, Netflix, and ChatGPT work

Classroom Activities

1. Compare Methods - Try TF-IDF vs AI and see the differences
2. Test Hypotheses - Will "happy" and "joyful" be close together?
3. Explore Relationships - How do opposites like "love" vs "hate" appear?
4. Create Experiments - Use song lyrics, movie descriptions, or book quotes

📖 Read the full educational guide →

📖 How to Use (Super Easy!)

1. Pick a Method

• TF-IDF: Counts important words (traditional way)
• AI Model: Uses artificial intelligence (modern way)

2. Add Your Text

• Use the example sentences, or
• Type your own sentences (one per line)

3. Convert and See Magic!

• Click "Convert Text to Numbers!"
• Watch your text become points on a graph
• See the actual numbers for each sentence

4. Learn and Experiment

• Try different sentences and see what happens
• Notice how similar sentences get similar numbers
• Save your results to show friends!

🧠 What Students Will Learn

Simple Concepts Made Clear

Why Computers Need Numbers:

• Computers only understand numbers, not words
• We need to convert text to numbers for AI to work
• Similar meanings should get similar numbers

Two Different Ways:

• Word Counting (TF-IDF): Like highlighting important words
• AI Understanding: Like having a smart robot read and understand

Real-World Connections:

• How Google Search finds relevant websites
• How Netflix knows what movies you might like
• How language translation works

Perfect For:

• 🎓 Students (middle school and up) learning about AI
• 👨‍🏫 Teachers explaining how computers understand language
• 👨‍👩‍👧‍👦 Parents showing kids how technology works
• 🤔 Anyone curious about how AI really works

📊 See visual flowcharts of the process →

🛠️ Technical Details (For Teachers/Parents)

What's Inside

text-embeddings-app/
├── app.py                 # Main application
├── embeddings/            # The smart modules
│   ├── tfidf_embedder.py     # Word counting method
│   └── transformer_embedder.py  # AI method
├── requirements.txt       # What software we need
├── Dockerfile            # Instructions for Docker
└── README.md             # This guide

Technology Used

• Streamlit: Makes the web interface
• scikit-learn: Does the math for word counting
• sentence-transformers: Provides the AI models
• plotly: Creates the interactive graphs
• pandas/numpy: Handles data and numbers
• nltk: Helps process text

AI Model (Simplified for v1)

• all-MiniLM-L6-v2: Fast, efficient AI model perfect for learning

🐳 Docker Setup (Easy!)

What Docker Does

Docker packages everything needed to run the app in one container - like a lunch box with everything inside!

Simple Commands

# Clean up old stuff first
docker container prune -f
docker image prune -a -f

# Build the app
docker build -t text-embeddings-app .

# Run the app
docker run -p 8501:8501 text-embeddings-app

# Run in background (optional)
docker run -d -p 8501:8501 --name text-converter text-embeddings-app

🔧 For Advanced Users

Settings You Can Change

• Port number (default: 8501)
• Server address (default: 0.0.0.0)

Making It Your Own

• Colors and design are in the load_css() function in app.py
• Add more example texts in the get_sample_texts() function
• The app is designed to be simple - perfect for v1!

🐛 If Something Goes Wrong

Common Issues

App Won't Start:

• Make sure Docker is running
• Check if port 8501 is already being used
• Try the cleanup commands first

Slow Performance:

• The AI model downloads the first time (be patient!)
• Try using fewer sentences
• TF-IDF method is faster than AI method

Can't See Results:

• Make sure you have at least 2 sentences
• Check that your text isn't too short
• Try the example texts first

Getting Help

1. Look at the error messages in the app
2. Try the example texts to make sure everything works
3. Restart Docker if needed

📊 Tips for Best Results

For Speed:

• Use the example texts for quick testing
• Try TF-IDF method first (it's faster)
• Use 3-8 sentences for best visualization

For Learning:

• Try sentences that are similar and different
• Compare how the two methods work differently
• Save your results and compare them later

🤝 Want to Help Make It Better?

This is a learning project! Teachers and students can:

• Suggest better example sentences
• Request simpler explanations
• Report bugs or confusing parts
• Share how you used it in class

📄 Free to Use

This app is free for everyone to use, especially for education and learning!

🙏 Thank You

• Sentence Transformers - for the AI models
• Streamlit - for making web apps easy
• scikit-learn - for the math tools
• Plotly - for the cool interactive graphs

---