mirror of
https://github.com/khoaliber/khoj.git
synced 2026-03-03 05:29:12 +00:00
📝 Add a documentation base for Khoj! (#333)
* Add docs for more organized, accessible information detailing Khoj setup * Delete duplicated files * Add a coverpage without enabling it. Add logo and theme * Remove obsidian README.md * Add plausible script to index.html via docsify
This commit is contained in:
sabaimran
@@ -1,167 +0,0 @@
|
||||
[[https://github.com/khoj-ai/khoj/edit/master/src/interface/emacs/README.org][file:/src/khoj/interface/web/assets/icons/khoj-logo-sideways-200.png]] Emacs
|
||||
|
||||
|
||||
[[https://stable.melpa.org/#/khoj][file:https://stable.melpa.org/packages/khoj-badge.svg]] [[https://melpa.org/#/khoj][file:https://melpa.org/packages/khoj-badge.svg]] [[https://github.com/khoj-ai/khoj/actions/workflows/build_khoj_el.yml][https://github.com/khoj-ai/khoj/actions/workflows/build_khoj_el.yml/badge.svg?]] [[https://github.com/khoj-ai/khoj/actions/workflows/test_khoj_el.yml][https://github.com/khoj-ai/khoj/actions/workflows/test_khoj_el.yml/badge.svg?]]
|
||||
|
||||
/An AI personal assistant for your digital brain/
|
||||
|
||||
** Table of Contents
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#features][Features]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Interface][Interface]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Setup][Setup]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Direct-Install][Direct Install]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Minimal-Install][Minimal Install]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Standard-Install][Standard Install]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#With-Straight.el][With Straight.el]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Use][Use]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Search][Search]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Chat][Chat]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Find-similar-entries][Find Similar Entries]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Advanced-usage][Advanced Usage]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Khoj-menu][Khoj Menu]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Upgrade][Upgrade]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Upgrade-Khoj-Backend][Upgrade Backend]]
|
||||
- [[https://github.com/khoj-ai/khoj/tree/master/src/interface/emacs#Upgrade-Khojel][Upgrade Khoj.el]]
|
||||
|
||||
** Features
|
||||
- *Search*
|
||||
- *Natural*: Advanced natural language understanding using Transformer based ML Models
|
||||
- *Local*: Your personal data stays local. All search, indexing is done on your machine*
|
||||
- *Incremental*: Incremental search for a fast, search-as-you-type experience
|
||||
- *Chat*
|
||||
- *Faster answers*: Find answers faster than search
|
||||
- *Iterative discovery*: Iteratively explore and (re-)discover your notes
|
||||
- *Assisted creativity*: Smoothly weave across answer retrieval and content generation
|
||||
|
||||
** Interface
|
||||
*** Search UI
|
||||
[[/docs/khoj_on_emacs.png]]
|
||||
|
||||
*** Chat UI
|
||||
[[/docs/khoj_chat_on_emacs_0.5.0.png]]
|
||||
|
||||
** Setup
|
||||
- /Make sure [[https://realpython.com/installing-python/][python]] and [[https://pip.pypa.io/en/stable/installation/][pip]] are installed on your machine/
|
||||
|
||||
- /khoj.el attempts to automatically install, start and configure the khoj server./
|
||||
If this fails, follow [[https://github.com/khoj-ai/khoj/tree/master/#Setup][these instructions]] to manually setup the khoj server.
|
||||
|
||||
*** Direct Install
|
||||
#+begin_src elisp
|
||||
M-x package-install khoj
|
||||
#+end_src
|
||||
|
||||
*** Minimal Install
|
||||
Add below snippet to your Emacs config file.
|
||||
Indexes your org-agenda files, by default.
|
||||
|
||||
#+begin_src elisp
|
||||
;; Install Khoj Package from MELPA Stable
|
||||
(use-package khoj
|
||||
:ensure t
|
||||
:pin melpa-stable
|
||||
:bind ("C-c s" . 'khoj)
|
||||
#+end_src
|
||||
|
||||
- Note: Install ~khoj.el~ from MELPA (instead of MELPA Stable) if you installed the pre-release version of khoj
|
||||
- That is, use ~:pin melpa~ to install khoj.el in above snippet if khoj server was installed with ~--pre~ flag, i.e ~pip install --pre khoj-assistant~
|
||||
- Else use ~:pin melpa-stable~ to install khoj.el in above snippet if khoj was installed with ~pip install khoj-assistant~
|
||||
- This ensures both khoj.el and khoj app are from the same version (git tagged or latest)
|
||||
|
||||
*** Standard Install
|
||||
Add below snippet to your Emacs config file.
|
||||
Indexes the specified org files, directories. Sets up OpenAI API key for Khoj Chat
|
||||
|
||||
#+begin_src elisp
|
||||
;; Install Khoj Package from MELPA Stable
|
||||
(use-package khoj
|
||||
:ensure t
|
||||
:pin melpa-stable
|
||||
:bind ("C-c s" . 'khoj)
|
||||
:config (setq khoj-org-directories '("~/docs/org-roam" "~/docs/notes")
|
||||
khoj-org-files '("~/docs/todo.org" "~/docs/work.org")
|
||||
khoj-openai-api-key "YOUR_OPENAI_API_KEY")) ; required to enable chat
|
||||
#+end_src
|
||||
|
||||
*** With [[https://github.com/raxod502/straight.el][Straight.el]]
|
||||
Add below snippet to your Emacs config file.
|
||||
Indexes the specified org files, directories. Sets up OpenAI API key for Khoj Chat
|
||||
|
||||
#+begin_src elisp
|
||||
;; Install Khoj Package using Straight.el
|
||||
(use-package khoj
|
||||
:after org
|
||||
:straight (khoj :type git :host github :repo "khoj-ai/khoj" :files (:defaults "src/interface/emacs/khoj.el"))
|
||||
:bind ("C-c s" . 'khoj)
|
||||
:config (setq khoj-org-directories '("~/docs/org-roam" "~/docs/notes")
|
||||
khoj-org-files '("~/docs/todo.org" "~/docs/work.org")
|
||||
khoj-openai-api-key "YOUR_OPENAI_API_KEY" ; required to enable chat)
|
||||
#+end_src
|
||||
|
||||
** Use
|
||||
*** Search
|
||||
1. Hit ~C-c s s~ (or ~M-x khoj RET s~) to open khoj search
|
||||
|
||||
2. Enter your query in natural language
|
||||
|
||||
e.g "What is the meaning of life?", "My life goals for 2023"
|
||||
|
||||
*** Chat
|
||||
1. Hit ~C-c s c~ (or ~M-x khoj RET c~) to open khoj chat
|
||||
|
||||
2. Ask questions in a natural, conversational style
|
||||
|
||||
E.g "When did I file my taxes last year?"
|
||||
|
||||
See [[https://github.com/khoj-ai/khoj/tree/master/#Khoj-Chat][Khoj Chat]] for more details
|
||||
|
||||
*** Find Similar Entries
|
||||
This feature finds entries similar to the one you are currently on.
|
||||
1. Move cursor to the org-mode entry, markdown section or text paragraph you want to find similar entries for
|
||||
2. Hit ~C-c s f~ (or ~M-x khoj RET f~) to find similar entries
|
||||
|
||||
*** Advanced Usage
|
||||
- Add [[https://github.com/khoj-ai/khoj/#query-filters][query filters]] during search to narrow down results further
|
||||
|
||||
e.g `What is the meaning of life? -"god" +"none" dt>"last week"`
|
||||
|
||||
- Use ~C-c C-o 2~ to open the current result at cursor in its source org file
|
||||
|
||||
- This calls ~M-x org-open-at-point~ on the current entry and opens the second link in the entry.
|
||||
- The second link is the entries [[https://orgmode.org/manual/Handling-Links.html#FOOT28][org-id]], if set, or the heading text.
|
||||
The first link is the line number of the entry in the source file. This link is less robust to file changes.
|
||||
- Note: If you have [[https://orgmode.org/manual/Speed-Keys.html][speed keys]] enabled, ~o 2~ will also work
|
||||
|
||||
*** Khoj Menu
|
||||
[[/docs/khoj_emacs_menu.png]]
|
||||
Hit ~C-c s~ (or ~M-x khoj~) to open the khoj menu above. Then:
|
||||
- Hit ~t~ until you preferred content type is selected in the khoj menu
|
||||
|
||||
~Content Type~ specifies the content to perform ~Search~, ~Update~ or ~Find Similar~ actions on
|
||||
- Hit ~n~ twice and then enter number of results you want to see
|
||||
|
||||
~Results Count~ is used by the ~Search~ and ~Find Similar~ actions
|
||||
- Hit ~-f u~ to ~force~ update the khoj content index
|
||||
|
||||
The ~Force Update~ switch is only used by the ~Update~ action
|
||||
|
||||
** Upgrade
|
||||
*** Upgrade Khoj Backend
|
||||
#+begin_src shell
|
||||
pip install --upgrade khoj-assistant
|
||||
#+end_src
|
||||
|
||||
*** Upgrade Khoj.el
|
||||
Use your Emacs package manager to upgrade ~khoj.el~
|
||||
|
||||
- For ~khoj.el~ from MELPA
|
||||
- Method 1
|
||||
- Run ~M-x package-list-packages~ to list all packages
|
||||
- Press ~U~ on ~khoj~ to mark it for upgrade
|
||||
- Press ~x~ to execute the marked actions
|
||||
- Method 2
|
||||
- Run ~M-x package-refresh-content~
|
||||
- Run ~M-x package-reinstall khoj~
|
||||
|
||||
- For ~khoj.el~ from Straight
|
||||
- Run ~M-x straight-pull-package khoj~
|
||||
@@ -1,162 +0,0 @@
|
||||
<img src="/src/khoj/interface/web/assets/icons/khoj-logo-sideways.svg" width="200" alt="Khoj Logo">Obsidian
|
||||
|
||||
> An AI personal assistant for your Digital Brain in Obsidian
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Features](#Features)
|
||||
- [Demo](#Demo)
|
||||
- [Search Demo](#Search-Demo)
|
||||
- [Interfaces](#Interfaces)
|
||||
- [Search Modal](#Search-Modal)
|
||||
- [Chat Modal](#Chat-Modal)
|
||||
- [Setup](#Setup)
|
||||
- [Setup Backend](#1-Setup-Backend)
|
||||
- [Setup Plugin](#2-Setup-Plugin)
|
||||
- [Use](#Use)
|
||||
- [Search](#search)
|
||||
- [Chat](#chat)
|
||||
- [Find Similar Notes](#find-similar-notes)
|
||||
- [Upgrade](#Upgrade)
|
||||
- [Upgrade Backend](#1-Upgrade-Backend)
|
||||
- [Upgrade Plugin](#2-Upgrade-Plugin)
|
||||
- [Troubleshoot](#Troubleshoot)
|
||||
- [Visualize Codebase](#Visualize-Codebase)
|
||||
- [Implementation](#Implementation)
|
||||
|
||||
## Features
|
||||
- **Search**
|
||||
- **Natural**: Advanced natural language understanding using Transformer based ML Models
|
||||
- **Local**: Your personal data stays local. All search and indexing is done on your machine. *Unlike chat which requires access to GPT.*
|
||||
- **Incremental**: Incremental search for a fast, search-as-you-type experience
|
||||
- **Chat**
|
||||
- **Faster answers**: Find answers faster and with less effort than search
|
||||
- **Iterative discovery**: Iteratively explore and (re-)discover your notes
|
||||
- **Assisted creativity**: Smoothly weave across answers retrieval and content generation
|
||||
|
||||
## Demo
|
||||
### Search Demo
|
||||
https://github.com/khoj-ai/khoj/assets/6413477/3e33d8ea-25bb-46c8-a3bf-c92f78d0f56b
|
||||
|
||||
<details><summary>Description</summary>
|
||||
|
||||
1. Install Khoj via `pip` and start Khoj backend
|
||||
```shell
|
||||
python -m pip install khoj-assistant && khoj
|
||||
```
|
||||
2. Install Khoj plugin via Community Plugins settings pane on Obsidian app
|
||||
- Check the new Khoj plugin settings
|
||||
- Wait for Khoj backend to index markdown, PDF files in the current Vault
|
||||
- Open Khoj plugin on Obsidian via Search button on Left Pane
|
||||
- Search \"*Announce plugin to folks*\" in the [Obsidian Plugin docs](https://marcus.se.net/obsidian-plugin-docs/)
|
||||
- Jump to the [search result](https://marcus.se.net/obsidian-plugin-docs/publishing/submit-your-plugin)
|
||||
|
||||
</details>
|
||||
|
||||
## Interfaces
|
||||
### Search Modal
|
||||
|
||||
|
||||
### Chat Modal
|
||||
|
||||
|
||||
## Setup
|
||||
- *Make sure [python](https://realpython.com/installing-python/) and [pip](https://pip.pypa.io/en/stable/installation/) are installed on your machine*
|
||||
- *Ensure you follow the ordering of the setup steps. Install the plugin after starting the khoj backend. This allows the plugin to configure the khoj backend*
|
||||
|
||||
### 1. Setup Backend
|
||||
Open terminal/cmd and run below command to install and start the khoj backend
|
||||
- On Linux/MacOS
|
||||
```shell
|
||||
python -m pip install khoj-assistant && khoj
|
||||
```
|
||||
|
||||
- On Windows
|
||||
```shell
|
||||
py -m pip install khoj-assistant && khoj
|
||||
```
|
||||
|
||||
### 2. Setup Plugin
|
||||
1. Open [Khoj](https://obsidian.md/plugins?id=khoj) from the *Community plugins* tab in Obsidian settings panel
|
||||
2. Click *Install*, then *Enable* on the Khoj plugin page in Obsidian
|
||||
3. [Optional] To enable Khoj Chat, set your [OpenAI API key](https://platform.openai.com/account/api-keys) in the Khoj plugin settings
|
||||
|
||||
See [official Obsidian plugin docs](https://help.obsidian.md/Extending+Obsidian/Community+plugins) for details
|
||||
|
||||
## Use
|
||||
### Chat
|
||||
Run *Khoj: Chat* from the [Command Palette](https://help.obsidian.md/Plugins/Command+palette) and ask questions in a natural, conversational style.<br />
|
||||
E.g "When did I file my taxes last year?"
|
||||
|
||||
Notes:
|
||||
- *Using Khoj Chat will result in query relevant notes being shared with OpenAI for ChatGPT to respond.*
|
||||
- *To use Khoj Chat, ensure you've set your [OpenAI API key](https://platform.openai.com/account/api-keys) in the Khoj plugin settings.*
|
||||
|
||||
See [Khoj Chat](https://github.com/khoj-ai/khoj/tree/master/#Khoj-Chat) for more details
|
||||
|
||||
|
||||
|
||||
### Search
|
||||
Click the *Khoj search* icon 🔎 on the [Ribbon](https://help.obsidian.md/User+interface/Workspace/Ribbon) or run *Khoj: Search* from the [Command Palette](https://help.obsidian.md/Plugins/Command+palette)
|
||||
|
||||
*Note: Ensure the khoj server is running in the background before searching. Execute `khoj` in your terminal if it is not already running*
|
||||
|
||||
https://user-images.githubusercontent.com/6413477/218801155-cd67e8b4-a770-404a-8179-d6b61caa0f93.mp4
|
||||
|
||||
<details><summary>Query Filters</summary>
|
||||
|
||||
Use structured query syntax to filter the natural language search results
|
||||
- **Word Filter**: Get entries that include/exclude a specified term
|
||||
- Entries that contain term_to_include: `+"term_to_include"`
|
||||
- Entries that contain term_to_exclude: `-"term_to_exclude"`
|
||||
- **Date Filter**: Get entries containing dates in YYYY-MM-DD format from specified date (range)
|
||||
- Entries from April 1st 1984: `dt:"1984-04-01"`
|
||||
- Entries after March 31st 1984: `dt>="1984-04-01"`
|
||||
- Entries before April 2nd 1984 : `dt<="1984-04-01"`
|
||||
- **File Filter**: Get entries from a specified file
|
||||
- Entries from incoming.org file: `file:"incoming.org"`
|
||||
- Combined Example
|
||||
- `what is the meaning of life? file:"1984.org" dt>="1984-01-01" dt<="1985-01-01" -"big" -"brother"`
|
||||
- Adds all filters to the natural language query. It should return entries
|
||||
- from the file *1984.org*
|
||||
- containing dates from the year *1984*
|
||||
- excluding words *"big"* and *"brother"*
|
||||
- that best match the natural language query *"what is the meaning of life?"*
|
||||
|
||||
</details>
|
||||
|
||||
### Find Similar Notes
|
||||
To see other notes similar to the current one, run *Khoj: Find Similar Notes* from the [Command Palette](https://help.obsidian.md/Plugins/Command+palette)
|
||||
|
||||
## Upgrade
|
||||
### 1. Upgrade Backend
|
||||
```shell
|
||||
pip install --upgrade khoj-assistant
|
||||
```
|
||||
### 2. Upgrade Plugin
|
||||
1. Open *Community plugins* tab in Obsidian settings
|
||||
2. Click the *Check for updates* button
|
||||
3. Click the *Update* button next to Khoj, if available
|
||||
|
||||
## Troubleshooting
|
||||
- Open the Khoj plugin settings pane, to configure Khoj
|
||||
- Toggle Enable/Disable Khoj, if setting changes have not applied
|
||||
- Click *Update* button to force index to refresh, if results are failing or stale
|
||||
|
||||
## Current Limitations
|
||||
- The plugin loads the index of only one vault at a time.<br/>
|
||||
So notes across multiple vaults **cannot** be searched at the same time
|
||||
|
||||
## Visualize Codebase
|
||||
<img src="https://github.com/khoj-ai/khoj/blob/master/src/interface/obsidian/docs/khoj_obsidian_codebase_visualization_0.2.1.png" width="700" />
|
||||
|
||||
## Implementation
|
||||
The plugin implements the following functionality to search your notes with Khoj:
|
||||
- [X] Open the Khoj search modal via left ribbon icon or the *Khoj: Search* command
|
||||
- [X] Render results as Markdown preview to improve readability
|
||||
- [X] Configure Khoj via the plugin setting tab on the settings page
|
||||
- Set Obsidian Vault to Index with Khoj. Defaults to all markdown, PDF files in current Vault
|
||||
- Set URL of Khoj backend
|
||||
- Set Number of Search Results to show in Search Modal
|
||||
- [X] Allow reranking of result to improve search quality
|
||||
- [X] Allow Finding notes similar to current note being viewed
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 277 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 333 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 378 KiB |
Reference in New Issue
Block a user