Orthos: Semantic 3D Product Recommendation System

Project Overview

Orthos is a semantic 3D product recommendation system that visualizes products in a three-dimensional space based on their semantic similarities. In the upgraded v2.0 architecture, the system uses OpenRouter for generating embeddings and Supabase (PostgreSQL) for persistent storage. Embeddings are converted to 3D coordinates for visualization using a dedicated embedding → 3D engine. Products with similar characteristics appear closer to each other in the 3D space, allowing users to intuitively explore related products.

Core Features

Admin Panel

• Add new products with name and description
• Automatically generate embeddings and 3D coordinates using OpenRouter
• Store product data and coordinates in Supabase (PostgreSQL)

User Visualization Page

• Interactive 3D visualization of products using Three.js
• 8-quadrant coordinate system for better spatial understanding
• Product selection and recommendation display
• Complete product listing for easy navigation

Technical Architecture

Backend (Flask)

• Flask Server: RESTful API endpoints for product management and recommendations
• OpenRouter Integration: Generates embeddings from product descriptions via OpenRouter’s /embeddings endpoint
• Supabase (Postgres): Database for storing product information, embeddings, coordinates, and logs
• KD-Tree Implementation: C program (exposed via FFI/CLI) for efficient proximity search in 3D space

Frontend (React)

• React Components: Modular UI components for admin and visualization pages
• Three.js: 3D visualization of product relationships
• Flask API Integration: Fetches products and recommendations from the Flask backend (which reads from Supabase)
• Tailwind CSS: Styling and responsive design

Data Flow

1. Product Creation:

   • Admin enters product name and description
   • Backend sends text to OpenRouter embeddings API
   • OpenRouter generates embeddings
   • Embeddings are converted to 3D coordinates via the embedding → 3D engine (UMAP + spacing)
   • Product data, embeddings, and coordinates are stored in Supabase

2. Visualization:

   • Frontend fetches all products from the Flask backend (/products), which reads from Supabase
   • Products are rendered as spheres in 3D space
   • User can select products to see details
   • Backend calculates nearest products using KD-tree algorithm
   • Similar products are highlighted in the visualization

3. Recommendation:

   • When a product is selected, backend finds similar products via the KD-tree search engine
   • Similarity is calculated based on Euclidean distance in 3D space
   • Top 5 most similar products are returned and displayed

System Components

Backend Endpoints

1. /generate_embedding (POST)

   • Receives product name and description
   • Generates embeddings using Mistral AI
   • Converts embeddings to 3D coordinates
   • Stores product in Firebase
   • Returns product ID and coordinates

2. /recommend/<id> (GET)

   • Finds similar products to the given product ID
   • Uses KD-tree approach for proximity search
   • Returns the target product, recommendations, and all products

3. /products (GET)

   • Returns all products stored in the database

Frontend Components

1. AdminPanel.js

   • Form for adding new products
   • Communicates with backend to generate embeddings

2. ProductVisualization.js

   • 3D visualization using Three.js
   • Interactive product selection
   • Displays product details and recommendations
   • Shows all available products in a list

3. App.js

   • Main application component with routing
   • Navigation between admin and visualization pages

Setup and Installation

Prerequisites

• Python 3.8+
• Node.js and npm
• Supabase project (URL + service role key)
• OpenRouter API key

Backend Setup

1. Navigate to the backend directory:

   cd orthos/backend
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up environment variables in .env (you can copy from .env.example):

   SUPABASE_URL=your_supabase_project_url
   SUPABASE_SERVICE_KEY=your_supabase_service_role_key
   OPENROUTER_API_KEY=your_openrouter_api_key
   FLASK_ENV=development
   FLASK_HOST=127.0.0.1
   FLASK_PORT=5001
   

4. Apply the Supabase schema (e.g. from supabase/schema.sql) in your Supabase project.

5. Run the Flask server:

   python app.py
   

   The server will automatically find an available port starting from 5000.

Frontend Setup

1. Navigate to the frontend directory:

   cd orthos/frontend
   

2. Install dependencies:

   npm install
   

3. Start the development server:

   npm start
   

Usage

1. Adding Products:

   • Navigate to the Admin Panel
   • Enter product name and description
   • Click "Submit" to add the product

2. Exploring Products:

   • Navigate to the Visualization Page
   • Interact with the 3D visualization using mouse controls:
     • Left-click to select products
     • Right-click and drag to rotate the view
     • Scroll to zoom in/out
   • View product details and recommendations in the side panel
   • Use the product list to quickly find and select specific products

Technical Implementation Details

Embedding Generation

OpenRouter's embeddings API is used to generate embeddings from product descriptions. These embeddings capture the semantic meaning of products and are converted to 3D coordinates by the embedding → 3D engine (UMAP + repulsion + Poisson-disk–style spacing).

KD-Tree for Proximity Search

A KD-tree data structure is implemented in C for efficient proximity search in 3D space. This allows the system to quickly find products that are close to each other in the semantic space.

8-Quadrant Coordinate System

The visualization uses an 8-quadrant coordinate system with grid helpers and quadrant labels for better spatial understanding. This helps users navigate the 3D space more intuitively.

New Updates

Orthos — New Changes & Upgrades (v2.0)

This document summarizes all the major enhancements, technology changes, and system improvements made in the upgraded version of Orthos.

---

🔄 1. Migration from Firebase → Supabase

• Replaced Firebase Firestore with Supabase PostgreSQL.
• All product data, embeddings, cluster IDs, and coordinates are now stored in structured SQL tables.
• Better querying performance and relational data handling.
• Built-in authentication available for future extensions.

---

🔁 2. Mistral API → OpenRouter API

• Switched from Mistral AI’s API to OpenRouter API.
• Supports multiple embedding-capable models (Mistral, Qwen, Llama, Claude, Gemini).
• More flexible and cheaper LLM routing.
• Unified API format simplifies embedding generation and semantic analysis.

---

🧠 3. Advanced Semantic Layer

• AI now returns:
  • Embeddings
  • Semantic cluster identity
  • Suggested quadrant
  • Product attribute vectors
  • Recommended axes (X/Y meaning)
• Better capturing of product meaning and relationships.

---

📐 4. Fully Upgraded Compute Logic (Most Important)

Replaced the previous “embedding → 3D coordinate” approach with a new deterministic quadrant-based scatter engine.

New Features:

• Attribute normalization into [-1, 1] space
• Semantically assigned quadrants
• Cluster centroid calculation
• Controlled jitter scatter (prevents clumping)
• Collision avoidance between coordinates
• Spread-out but meaningful product placement

Engine Choices:

• Compute engine can now be built in:
  • C (high performance)
  • C++ (balanced)
  • Rust (high precision & safety — recommended)

---

🗂 5. New Data Model Structure

Products now store:

• embedding
• cluster_id
• quadrant
• x, y (final coordinates)
• semantic_tags
• axes_used
• timestamps & metadata

Structured for semantic search + visualization.

---

🎨 6. Upgraded Visualization Logic

• Products no longer appear in tight clusters.
• Natural scattering algorithm makes visuals more readable.
• Clusters remain together but spaced for clarity.
• Rendering now supports D3.js / Three.js easily.

---

⚙ 7. Full Pipeline Rewrite

New workflow:

1. Admin adds product
2. Sent to OpenRouter → AI gives embedding + semantic info
3. Compute engine calculates coordinates
4. Coordinates stored in Supabase
5. Frontend renders layout

A cleaner, faster, more controllable pipeline.

---

📦 8. Improved Config System

Config file now supports:

• model selection
• axis mapping
• engine type (C/C++/Rust)
• jitter radius
• cluster radius
• global seed
• min-distance for collision avoidance

Easier experimentation and tuning.

---

🔐 9. Environment & Security Improvements

• Removed Firebase SDK dependencies.
• Added .env variables:
  • OPENROUTER_API_KEY
  • SUPABASE_URL
  • SUPABASE_KEY
• Secure server-to-server calls.

---

📑 10. Cleaner Readme & Documentation

• Rewritten README.md (v2.0) with full architecture, logic, and workflow.
• New NEW_CHANGES.md (this file) for release notes.

---

🎉 Summary

The new Orthos system is:

• More accurate
• Better structured
• AI-driven
• Faster
• Scalable
• Visually cleaner

This upgrade sets the foundation for future expansions such as:

• personalization
• real-time re-clustering
• multi-level semantic grouping
• 3D mapping

---

Conclusion

Orthos provides an innovative way to explore product relationships through 3D visualization. By leveraging OpenRouter (for semantic understanding), Supabase (for storage, logging, and security), and Three.js (for interactive visualization), the system offers an intuitive and engaging product discovery experience.