🧠 Recommendation Engine

A Ruby on Rails application implementing a recommendation system using vector embeddings. The system matches users → products (or other items) based on their feature embeddings and similarity search.

🚀 Features

• Embedding-based recommendation engine (Numo::NArray + cosine similarity)
• JSON-based index map for item embeddings
• Rails service object architecture (Recommendation::Engine)
• Extendable for domain-specific use cases (e.g., products, articles, legal documents)

📂 Project Structure

app/
  controllers/
    recommendations_controller.rb   # Handles recommendation requests
  services/
    recommendation/
      engine.rb                     # Core recommendation logic
      llm_presenter.rb              # (Optional) format recommendations with LLMs
config/
  database.yml
db/
  schema.rb
tmp/
  product_cluster_map.json          # Stores product embeddings / index

⚙️ Setup

1. Clone Repo

git clone https://github.com/your-username/recommendation-engine.git
cd recommendation-engine

2. Install Dependencies

bundle install

3. Setup Database

rails db:create db:migrate

4. Prepare Product Embeddings

Ensure you have a JSON file with product embeddings:

{
  "101": [0.12, 0.88, -0.34, ...],
  "102": [0.56, 0.02, 0.77, ...]
}

Save this file as:

tmp/product_cluster_map.json

5. Start Rails Server

rails s

📡 API Usage

Get Recommendations for a User

Endpoint:

GET /recommendations/:id

Response:

{
  "user_id": 1,
  "recommendations": [
    { "product_id": 101, "score": 0.92 },
    { "product_id": 102, "score": 0.87 },
    { "product_id": 103, "score": 0.81 }
  ]
}

🛠 Development Notes

• Embedding vectors must be the same size as defined in Engine#index_map
• If you see ArgumentError (Total size must be same), check that user vectors and product embeddings have the same dimensions
• To customize recommendation scoring, edit Recommendation::Engine#similarity_score
• LlmPresenter is optional and can be used to generate natural-language explanations of recommendations

📌 TODO

• Add background job to refresh product embeddings
• Add RSpec tests for recommendation logic
• Support approximate nearest neighbor (ANN) search for large datasets
• Add frontend UI for displaying recommendations

🤝 Contributing

Pull requests are welcome! Please open an issue first to discuss major changes.

📜 License

MIT License.