khoj/README.org

• Khoj
  • Features
  • Demo
  • Architecture
  • Setup
    • 1. Clone
    • 2. Configure
    • 3. Run
  • Use
  • Upgrade
  • Troubleshooting
  • Miscellaneous
  • Development Setup
    • Setup on Local Machine
      • 1. Install Dependencies
      • 2. Install Khoj
      • 3. Configure
      • 4. Run
    • Upgrade On Local Machine
    • Run Unit tests
  • Acknowledgments

Khoj

Natural language search engine for your personal notes, transactions and images

Features

• Advanced Natural language understanding using Transformer based ML Models
• Your personal data stays local. All search, indexing is done on your machine*
• Index Org-mode and Markdown notes, Beancount transactions and Photos
• Interact with Khoj using a Web Browser, Emacs or the API.

Demo

Architecture

Setup

1. Clone

  git clone https://github.com/debanjum/khoj && cd khoj

2. Configure

• Required: Update docker-compose.yml to mount your images, (org-mode or markdown) notes and beancount directories
• Optional: Edit application configuration in sample_config.yml

3. Run

docker-compose up -d

Note: The first run will take time. Let it run, it's mostly not hung, just generating embeddings

Use

• Khoj via Web

  • Go to http://localhost:8000/ or open index.html in your browser

• Khoj via Emacs

  • Install khoj.el
  • Run M-x khoj <user-query>

• Khoj via API

  • See Khoj FastAPI Docs
  • Query
  • Regenerate Embeddings
  • Configure Application

Upgrade

  docker-compose build --pull

Troubleshooting

• Symptom: Errors out with "Killed" in error message

  • Fix: Increase RAM available to Docker Containers in Docker Settings
  • Refer: StackOverflow Solution, Configure Resources on Docker for Mac

• Symptom: Errors out complaining about Tensors mismatch, null etc

  • Mitigation: Delete content-type > image section from docker_sample_config.yml

Miscellaneous

• The experimental chat API endpoint uses the OpenAI API

  • It is disabled by default
  • To use it add your openai-api-key to config.yml

Development Setup

Setup on Local Machine

1. Install Dependencies

1. Install Python3 [Required]
2. Install Conda [Required]

3. Install Exiftool [Optional]

   sudo apt-get -y install libimage-exiftool-perl

2. Install Khoj

git clone https://github.com/debanjum/khoj && cd khoj
conda env create -f config/environment.yml
conda activate khoj

3. Configure

• Configure files/directories to search in content-type section of sample_config.yml

• To run application on test data, update file paths containing /data/ to tests/data/ in sample_config.yml

  • Example replace /data/notes/*.org with tests/data/notes/*.org

4. Run

Load ML model, generate embeddings and expose API to query notes, images, transactions etc specified in config YAML

python3 -m src.main -c=config/sample_config.yml -vv

Upgrade On Local Machine

  cd khoj
  git pull origin master
  conda deactivate khoj
  conda env update -f config/environment.yml
  conda activate khoj

Run Unit tests

pytest

Acknowledgments

• Multi-QA MiniLM Model for Asymmetric Text Search. See SBert Documentation
• All MiniLM Model for Symmetric Text Search
• OpenAI CLIP Model for Image Search. See SBert Documentation
• Charles Cave for OrgNode Parser
• Sven Marnach for PyExifTool