🔭 SpaceExplainer AI

AI-powered space image education tool that identifies celestial objects using GPT-4 Vision and NASA data

Live Demo • Features • Quick Start • Documentation

---

📋 Table of Contents

• About
• Features
• Live Demo
• Quick Start
• Installation
• Usage
• Tech Stack
• API Reference
• Project Structure
• Contributing
• License

---

🌟 About

SpaceExplainer AI is an intelligent web application that helps users identify and learn about celestial objects in space images. By combining OpenAI's GPT-4 Vision model with NASA's Image Library, it provides comprehensive educational content about astronomical phenomena.

Key Capabilities:

• 🤖 AI-powered image analysis with confidence indicators
• 🌌 Real-time NASA Image Library search
• 📚 Educational facts and learning resources
• 🎨 Detection of artistic/synthetic images
• 📱 Fully responsive design

---

✨ Features

Feature	Description
🤖 AI Image Analysis	Powered by OpenAI GPT-4 Vision to identify celestial objects and phenomena with confidence scoring
🌌 NASA Integration	Searches NASA's Image Library for relevant official images and context
📚 Educational Facts	Quick facts about object type, visibility, distance, and viewing season
🎓 Learn More	Direct links to Wikipedia, YouTube, and educational resources
🎨 Art Detection	Identifies artistic, AI-generated, or synthetic images to prevent false identifications
📋 Copy Analysis	Easy copy-to-clipboard functionality for analysis text
🔄 Smart Caching	Optimized performance with intelligent caching (1-hour TTL)
📱 Responsive Design	Works seamlessly on desktop and mobile devices
🔑 Environment Variables	Support for .env file configuration

---

🚀 Live Demo

Coming Soon! Deploy your own instance following the Deployment Instructions.

---

⚡ Quick Start

3-Step Setup

1. Clone & Install

   git clone https://github.com/yourusername/spaceexplainer-ai.git
   cd spaceexplainer-ai
   pip install -r requirements.txt

2. Configure Environment

   cp .env.example .env
   # Edit .env and add your OPENAI_API_KEY

3. Run

   streamlit run app.py

That's it! The app will open at http://localhost:8501

---

📦 Installation

Prerequisites

• Python 3.8 or higher
• OpenAI API Key (Get one here)
• Git (for cloning)

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/yourusername/spaceexplainer-ai.git
cd spaceexplainer-ai

2. Create Virtual Environment (Recommended)

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

3. Install Dependencies

# For development (flexible versions)
pip install -r requirements.txt

# For production (exact versions)
pip install -r requirements_frozen.txt

4. Configure Environment Variables

# Copy the example file
cp .env.example .env

# Edit .env and add your API key
# OPENAI_API_KEY=sk-your-actual-key-here

5. Run the Application

streamlit run app.py

The application will automatically open in your default browser at http://localhost:8501

---

📖 Usage

Basic Usage

1. Enter API Key (or load from .env)

   • The app automatically loads OPENAI_API_KEY from .env file
   • You can override it in the sidebar if needed

2. Upload Image

   • Click "Choose an image file"
   • Select a JPG, JPEG, or PNG space image
   • Supported formats: JPG, JPEG, PNG

3. Analyze

   • Click "Analyze with AI" button
   • Wait for AI analysis (typically 5-10 seconds)

4. Explore Results

   • Review AI analysis with confidence indicators
   • Browse NASA Image Library results
   • Access educational resources

Usage Examples

Example 1: Analyzing a Nebula Image

# The app handles this automatically, but here's what happens:

1. User uploads "crab_nebula.jpg"
2. Image is converted to base64 and resized if needed
3. GPT-4 Vision analyzes the image
4. Confidence level is determined (High/Medium/Low)
5. NASA Image Library is searched for "Crab Nebula"
6. Results are displayed with educational context

Example 2: Handling Artistic Images

# For AI-generated or artistic images:

1. AI detects artistic/synthetic nature
2. Confidence level set to "Low"
3. Warning message displayed
4. NASA search uses "nebula art" or "space art" instead
5. Shows appropriate artistic space images

Tips for Best Results

• Image Quality: Higher resolution images (up to 2000px width) provide better analysis
• Supported Formats: JPG, JPEG, PNG
• Image Size: Large images are automatically resized to optimize API calls
• Caching: Results are cached for 1 hour to improve performance
• API Costs: Monitor your OpenAI usage on the OpenAI Dashboard

---

🛠️ Tech Stack

Component	Technology	Version	Purpose
Frontend	Streamlit	≥1.28.0	Web application framework
AI Model	OpenAI GPT-4 Vision	Latest	Image analysis and identification
Data Source	NASA Image Library API	Public	Official space images
Image Processing	Pillow (PIL)	≥10.1.0	Image manipulation and conversion
HTTP Client	Requests	≥2.31.0	API communication
Environment	python-dotenv	≥1.0.0	Environment variable management
Language	Python	3.8+	Core programming language

---

📚 API Reference

Core Functions

search_nasa_images(search_term: str) -> List[Dict]

Searches NASA's Image Library for relevant space images.

Parameters:

• search_term (str): Search query (e.g., "Crab Nebula")

Returns:

• List[Dict]: List of image results with title, description, image_url, nasa_id, nasa_url

Example:

results = search_nasa_images("Crab Nebula")
# Returns: [{"title": "...", "description": "...", ...}, ...]

extract_object_name(ai_response: str) -> str | None

Extracts the main celestial object name from AI analysis.

Parameters:

• ai_response (str): Full AI analysis text

Returns:

• str | None: Clean object name (e.g., "Crab Nebula") or None

Example:

object_name = extract_object_name(ai_response)
# Returns: "Crab Nebula"

extract_confidence_level(ai_response: str) -> str

Determines confidence level of AI analysis.

Parameters:

• ai_response (str): Full AI analysis text

Returns:

• str: "high", "medium", or "low"

Example:

confidence = extract_confidence_level(ai_response)
# Returns: "high" | "medium" | "low"

image_to_base64(uploaded_file) -> str

Converts uploaded image to base64 format for OpenAI API.

Parameters:

• uploaded_file: Streamlit uploaded file object

Returns:

• str: Base64 data URI string

Example:

base64_image = image_to_base64(uploaded_file)
# Returns: "data:image/jpeg;base64,..."

---

📁 Project Structure

spaceexplainer-ai/
├── app.py                      # Main Streamlit application
├── requirements.txt            # Python dependencies (flexible versions)
├── requirements_frozen.txt    # Python dependencies (exact versions)
├── .env.example                # Environment variables template
├── .gitignore                  # Git ignore file
├── README.md                   # This file
└── LICENSE                     # MIT License (to be added)

File Descriptions

• app.py: Main application file containing all Streamlit UI and logic
• requirements.txt: Flexible dependency versions for development
• requirements_frozen.txt: Exact dependency versions for production
• .env.example: Template for environment variables
• .gitignore: Excludes sensitive files and build artifacts

---

🚢 Deployment

Deploy to Streamlit Cloud

1. Push to GitHub

   git add .
   git commit -m "Initial commit"
   git push origin main

2. Deploy on Streamlit Cloud

   • Visit share.streamlit.io
   • Sign in with GitHub
   • Click "New app"
   • Select your repository
   • Set main file path: app.py
   • Click "Deploy"

3. Configure Secrets

   • Go to app settings → Secrets
   • Add: OPENAI_API_KEY=your-key-here
   • Save and redeploy

Environment Variables

For production deployment, set these environment variables:

export OPENAI_API_KEY=sk-your-key-here

Or use Streamlit Cloud's secrets management (recommended).

---

🤝 Contributing

We welcome contributions! Here's how you can help:

Contribution Guidelines

1. Fork the Repository

   git clone https://github.com/yourusername/spaceexplainer-ai.git

2. Create a Feature Branch

   git checkout -b feature/AmazingFeature

3. Make Your Changes

   • Follow PEP 8 style guidelines
   • Add docstrings to new functions
   • Update README if needed

4. Commit Your Changes

   git commit -m 'Add some AmazingFeature'

5. Push to Branch

   git push origin feature/AmazingFeature

6. Open a Pull Request

   • Describe your changes
   • Reference any related issues
   • Wait for review

Development Setup

# Install development dependencies
pip install -r requirements.txt

# Run the app
streamlit run app.py

# Clear cache if needed
# Use sidebar button or: st.cache_data.clear()

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 Pawan Konwar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

⚠️ Disclaimer

AI Accuracy Notice: While AI analysis is powerful, it may not always be 100% accurate. Always verify important information with official sources. This tool is for educational purposes only.

API Costs: This app uses OpenAI's API which incurs costs. Monitor your usage on the OpenAI Dashboard.

Image Authenticity: The app includes confidence indicators to help identify artistic or synthetic images. However, users should exercise judgment when interpreting results.

---

🙏 Acknowledgments

• OpenAI for GPT-4 Vision API
• NASA for Image Library API and educational resources
• Streamlit for the amazing framework
• All contributors and space enthusiasts who make this project possible

---

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [Your Email] (optional)

---

Made with ❤️ for Space Enthusiasts 🔭

⭐ Star this repo if you find it helpful!