bacha: Video Recommendation Engine & Vector Visualizer

bacha is a sophisticated, multimodal recommendation system designed to power next-generation video feeds. It leverages vector embeddings to understand content semantically across text, images, and video, and includes a powerful 2D/3D visualizer to explore the latent space of your content library.

🚀 Key Features

🧠 Intelligent Backend

• Multimodal Ingestion: Seamlessly ingest text, images, and videos. The system uses CLIP (Contrastive Language-Image Pre-Training) to generate unified vector embeddings for all media types.
• Semantic Search: Find content based on meaning rather than just keyword matching.
• Dynamic Reranking: Uses reranker-transformers (Cross-Encoder) to refine search results for maximum relevance.
• Cold Start Handling: Smartly interleaves "viral" content with semantic matches for new users.
• Interaction Tracking: Logs user events like like, share, and watch_time to personalize future recommendations.

🎨 Interactive Visualizer

• Latent Space Exploration: visualize your content library in a 3D or 2D interactive scatter plot.
• Dimensionality Reduction: Uses UMAP to project high-dimensional Weaviate vector embeddings into navigable 3D space.
• Real-time Clustering: See how different content types cluster together based on semantic similarity.

---

🛠️ Technology Stack

• Backend: Python, FastAPI
• Vector Database: Weaviate (v1.34.0)
• AI Models:
  • multi2vec-clip: For multimodal embeddings.
  • reranker-transformers: For search result reranking.
• Frontend: React, Vite
• Visualization: Three.js, React Three Fiber, UMAP-js
• Infrastructure: Docker, Docker Compose

---

📦 Project Structure

bacha/
├── backend/            # FastAPI application
│   ├── api.py          # API endpoints and logic
│   ├── weaviate_service.py # Weaviate integration layer
│   └── ...
├── visualizer/         # React + Three.js Frontend
│   ├── src/pages/      # 2D and 3D Visualizer components
│   └── ...
├── docker-compose.yml  # Orchestration for Weaviate, Backend, etc.
└── docs.md             # Detailed Backend API Documentation

---

🏁 Getting Started

Prerequisites

• Docker and Docker Compose
• Node.js (v18+ recommended) for the visualizer

1. Start the Backend & Database

The backend and Weaviate are containerized for easy setup.

docker-compose up -d --build

This will start:

• Weaviate on lcoalhost:8080
• Backend API on localhost:8000
• Reranker & Vectorizer services

Note: The first run might take a while as it downloads the AI models.

2. Start the Visualizer

Open a new terminal and navigate to the visualizer directory.

cd visualizer
npm install
npm run dev

The visualizer will be available at http://localhost:5173 (or the port shown in your terminal).

---

📡 Usage

Ingesting Content

Before you can recommend or visualize anything, you need to populate the database. You can use the provided API endpoints.

Example: Ingest a Text Item

curl -X POST "http://localhost:8000/ingest/text" \
  -F "title=Funny Joke" \
  -F "text=Why did the chicken cross the road? To get to the other side."

Example: Ingest an Image

curl -X POST "http://localhost:8000/ingest/image" \
  -F "title=Cute Cat" \
  -F "url=https://placekitten.com/200/300"

Exploring Recommendations

Get a personalized feed (or cold-start feed for new users):

curl -X POST "http://localhost:8000/recommend/cold_start" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "new_user",
    "categories": ["tech", "comedy"],
    "limit": 10
  }'

For more detailed API usage, please refer to docs.md.

Viewing the Data

1. Open the Visualizer app in your browser.
2. Toggle between 2D and 3D views using the route or navigation (e.g., / for 2D, /3d for 3D).
3. The app will fetch embeddings from the backend and plot them. Nodes strictly closer to each other are semantically similar.

---

📄 Documentation

For full API Specification, Schema details, and Testing commands, please see docs.md.