How azeem07112007/cosmera works
Purpose and Entry Point
Cosmera is a browser-based astronomy platform that classifies uploaded images into galaxies, nebulae, stars, or asteroids, then provides AI-generated astronomy explanations and comparisons. The runtime entry point is the FastAPI application in app.py; it is launched with Python or Uvicorn.
API and Orchestration Layer
app.py is the system boundary between the browser UI, image-classification pipeline, and Lumina assistant integration. It serves the platform and coordinates requests that require inference or AI responses. ollama_test.py and diag.py appear to support model/API diagnostics rather than core application flow.
Vision Classification Pipeline
The custom PyTorch CNN lifecycle is split between training and inference:
• train.py prepares/trains the CNN from labeled astronomy images.
• predict.py loads the trained inference pipeline for image classification.
• classes.json provides the class-label mapping returned to application/UI consumers.
The primary inference flow is: browser image upload → FastAPI orchestration → PyTorch prediction → mapped cosmic-object label → explanatory AI context.
Dataset and Model Boundary
Training data is organized by object category under:
• dataset/galaxy
• dataset/nebula
• dataset/stars
• dataset/asteroids
This directory-per-class structure is the key contract between the dataset, train.py, and classes.json. The repository describes CPU-optimized PyTorch dependencies in requirements.txt, making local or constrained cloud inference/training a material deployment consideration.
Lumina AI Integration
Lumina is an external Llama 3-based astronomy assistant accessed through the NVIDIA NIM API. The application requires an NVIDIA_API_KEY supplied through a root .env file; API credentials are intentionally outside tracked source. Lumina consumes classification results and conversational context to generate object explanations, formation summaries, follow-up answers, and image-comparison analysis.
Browser Experience and Interaction Surfaces
The frontend is static HTML/CSS/JavaScript served by the application:
• index.html is the primary landing surface.
• identify.html supports object-identification interaction.
• compare.html supports two-image comparison.
• learn.html supports educational content.
• cosmic-animations.js and cosmic-animations.css implement the interactive/visual presentation layer.
The client is responsible for image selection, chat/comparison interaction, and displaying classification plus Lumina responses; server-side services own model inference and external AI calls.
Main Control Flows
1. Identification: identify.html submits an astronomy image to app.py; predict.py classifies it using the trained CNN and classes.json; the result can be sent to NVIDIA NIM for a scientific explanation.
2. Assistant follow-up: browser conversation state and latest scan context are submitted through app.py to Lumina, which returns context-aware responses.
3. Comparison: compare.html supplies two astronomical inputs; app.py delegates the AI-driven comparative interpretation to the Lumina/NVIDIA NIM boundary.
Main entry points: app.py FastAPI orchestration · train.py CNN training · predict.py CNN inference · identify.html Identify experience
Components 16
Browser UI
- Landing page
index.html - Identify experience · Uploads an image and displays classification and explanations.
identify.html - Comparison experience · Collects two astronomical inputs for AI comparison.
compare.html - Learning content
learn.html - Interactive visuals
cosmic-animations.js - Cosmic styling
cosmic-animations.css
Application
- FastAPI orchestration · Serves the browser surfaces and coordinates inference and Lumina requests.
app.py
Vision ML
- CNN inference · Loads the trained prediction pipeline for uploaded images.
predict.py - Class labels · Maps model outputs to cosmic-object labels.
classes.json - CNN training · Trains the custom classifier from labeled astronomy images.
train.py
Training Data
- Galaxy images
dataset/galaxy - Nebula images
dataset/nebula - Star images
dataset/stars - Asteroid images
dataset/asteroids
External AI
- Lumina assistant · Generates astronomy explanations, follow-ups, and comparisons.
- NVIDIA API key · Supplied outside tracked source.
Connections 17
- Landing page → FastAPI orchestration: served by
- Identify experience → FastAPI orchestration: image upload and chat
- Comparison experience → FastAPI orchestration: two-image comparison
- Learning content → FastAPI orchestration: served by
- Interactive visuals → Identify experience: interactive UI
- Cosmic styling → Identify experience: visual presentation
- FastAPI orchestration → CNN inference: classification request
- CNN inference → Class labels: maps output
- FastAPI orchestration → Lumina assistant: explanations, chat, comparison
- CNN inference → Lumina assistant: classification context
- NVIDIA API key → Lumina assistant: authenticates API access
- Galaxy images → CNN training: labeled training images
- Nebula images → CNN training: labeled training images
- Star images → CNN training: labeled training images
- Asteroid images → CNN training: labeled training images
- CNN training → CNN inference: trained CNN
- CNN training → Class labels: class contract