# bookworm 📖
[](https://github.com/kiran94/bookworm/actions/workflows/main.yml) [](https://badge.fury.io/py/bookworm_genai)
> LLM-powered bookmark search engine
`bookworm` allows you to search from your local browser bookmarks using natural language. For times when you have a large collection of bookmarks and you can't quite remember where you put that one website you need at the moment.
[](https://asciinema.org/a/696613)
## Install
```bash
python -m pip install bookworm_genai
```
> [!TIP]
> If you are using [`uvx`](https://docs.astral.sh/uv/guides/tools/) then you can also just run this:
> ```bash
> uvx --from bookworm_genai bookworm --help
> ```
## Usage
```bash
export OPENAI_API_KEY=
# Run once and then anytime bookmarks across supported browsers changes
bookworm sync
# Sync bookmarks only from a specific browser
bookworm sync --browser-filter chrome
# Ask questions against the bookmark database
bookworm ask
# Ask questions against the bookmark database
# Specify the query when invoking the command
# If you omit this then you will be asked for a query when the tool is running
bookworm ask -q pandas
# Ask questions against the bookmark database and specify the number of results that should come back
bookworm ask -n 1
```
The `sync` process currently supports the following configurations:
| Operating System | Google Chrome | Mozilla Firefox | Brave | Microsoft Edge |
| ------------------ | --------------- | ----------------- | ------- | ---------------- |
| **Linux** | ✅ | ✅ | ✅ | ❌ |
| **macOS** | ✅ | ✅ | ✅ | ❌ |
| **Windows** | ❌ | ❌ | ❌ | ❌ |
> [!TIP]
> ✨ Want to contribute? See the [adding an integration](#adding-an-integration) section.
## Processes
*`bookworm sync`*
Vectorize your bookmarks across all supported browsers.
```mermaid
graph LR
subgraph Bookmarks
Chrome(Chrome Bookmarks)
Brave(Brave Bookmarks)
Firefox(Firefox Bookmarks)
end
Bookworm(bookworm sync)
EmbeddingsService(Embeddings Service e.g OpenAIEmbeddings)
VectorStore(Vector Store e.g DuckDB)
Chrome -->|load bookmarks|Bookworm
Brave -->|load bookmarks|Bookworm
Firefox -->|load bookmarks|Bookworm
Bookworm -->|vectorize bookmarks|EmbeddingsService-->|store embeddings|VectorStore
```
<details>
<summary>Details</summary>
The vector database depicted above is stored locally on your machine. You can check it's location by running the following after installing this project:
```python
from platformdirs import PlatformDirs
print(PlatformDirs('bookworm').user_data_dir)
```
</details>
---
*`bookworm ask`*
Search from your bookmarks
```mermaid
graph LR
query
Bookworm(bookworm ask)
subgraph _
LLM(LLM e.g OpenAI)
VectorStore(Vector Store e.g DuckDB)
end
query -->|user queries for information|Bookworm
Bookworm -->|similarity search|VectorStore -->|send similar docs + user query|LLM
LLM -->|send back response|Bookworm
```
---
*`bookworm export`*
Export your bookmarks across all supported browsers into an output (e.g CSV)
```mermaid
graph LR
VectorStore
Bookworm(bookworm export)
CSV(bookmarks.csv)
VectorStore -->|extract all bookmarks|Bookworm
Bookworm -->|export into file|CSV
```
## Developer Setup
```bash
# LLMs
export OPENAI_API_KEY=
# Langchain (optional, but useful for debugging)
export LANGCHAIN_API_KEY=
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_PROJECT=bookworm
# Misc (optional)
export LOGGING_LEVEL=INFO
```
Recommendations:
- Install [`pyenv`](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) and ensure [build dependencies are installed](https://github.com/pyenv/pyenv?tab=readme-ov-file#install-python-build-dependencies) for your OS.
- Install [Poetry](https://python-poetry.org/docs/) we will be using [environment management](https://python-poetry.org/docs/managing-environments/) below.
- VS Code Extensions recommendations can be found [here](./.vscode/extensions.json) and will be suggested upon first opening the project.
```bash
poetry env use 3.9 # or path to your 3.9 installation
poetry shell
poetry install
bookworm --help
```
<details>
<summary>Running Linux tests on MacOS/Windows</summary>
If you are running on a non-linux machine, it may be helpful to run the provided [Dockerfile](./Dockerfile.linux) to verify it's working on that environment.
You can build this via:
```bash
make docker_linux
```
You will need to have Docker installed to run this.
</details>
## Adding an Integration
As you can see from [usage](#usage), bookworm supports various integrations but not all. If you find one that you want to support one, then a change is needed inside [integrations.py](./bookworm_genai/integrations.py).
You can see in that file there is a variable called `browsers` that follows this structure:
```python
browsers = {
"BROWSER": {
"PLATFORM": {
...
}
}
}
```
So say you wanted to add Chrome support in Windows then you would go under the Chrome key and then add a `win32` key which has all the details. You can refer to existing examples but generally the contents of those details are *where* to find the bookmarks on the user's system along with how to *interpret* them.
You can also find a full list of the document loaders supported [here](https://python.langchain.com/docs/integrations/document_loaders/).
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/bookworm_genai/",
"name": "bookworm_genai",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "bookmarks, bookmark-manager, genai, chatbots",
"author": "kiran94",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5a/95/ea3e7618891a89c031967e898e91ff17fcf2732fffe7ebf47b27aeba84c1/bookworm_genai-0.13.0.tar.gz",
"platform": null,
"description": "# bookworm \ud83d\udcd6\n\n[](https://github.com/kiran94/bookworm/actions/workflows/main.yml) [](https://badge.fury.io/py/bookworm_genai)\n\n> LLM-powered bookmark search engine\n\n`bookworm` allows you to search from your local browser bookmarks using natural language. For times when you have a large collection of bookmarks and you can't quite remember where you put that one website you need at the moment.\n\n[](https://asciinema.org/a/696613)\n\n## Install\n\n```bash\npython -m pip install bookworm_genai\n```\n\n> [!TIP]\n> If you are using [`uvx`](https://docs.astral.sh/uv/guides/tools/) then you can also just run this:\n> ```bash\n> uvx --from bookworm_genai bookworm --help\n> ```\n\n## Usage\n\n```bash\nexport OPENAI_API_KEY=\n\n# Run once and then anytime bookmarks across supported browsers changes\nbookworm sync\n\n# Sync bookmarks only from a specific browser\nbookworm sync --browser-filter chrome\n\n# Ask questions against the bookmark database\nbookworm ask\n\n# Ask questions against the bookmark database\n# Specify the query when invoking the command\n# If you omit this then you will be asked for a query when the tool is running\nbookworm ask -q pandas\n\n# Ask questions against the bookmark database and specify the number of results that should come back\nbookworm ask -n 1\n```\n\nThe `sync` process currently supports the following configurations:\n\n| Operating System | Google Chrome | Mozilla Firefox | Brave | Microsoft Edge |\n| ------------------ | --------------- | ----------------- | ------- | ---------------- |\n| **Linux** | \u2705 | \u2705 | \u2705 | \u274c |\n| **macOS** | \u2705 | \u2705 | \u2705 | \u274c |\n| **Windows** | \u274c | \u274c | \u274c | \u274c |\n\n> [!TIP]\n> \u2728 Want to contribute? See the [adding an integration](#adding-an-integration) section.\n\n## Processes\n\n*`bookworm sync`*\n\nVectorize your bookmarks across all supported browsers.\n\n```mermaid\ngraph LR\n\nsubgraph Bookmarks\n Chrome(Chrome Bookmarks)\n Brave(Brave Bookmarks)\n Firefox(Firefox Bookmarks)\nend\n\nBookworm(bookworm sync)\n\nEmbeddingsService(Embeddings Service e.g OpenAIEmbeddings)\n\nVectorStore(Vector Store e.g DuckDB)\n\nChrome -->|load bookmarks|Bookworm\nBrave -->|load bookmarks|Bookworm\nFirefox -->|load bookmarks|Bookworm\n\nBookworm -->|vectorize bookmarks|EmbeddingsService-->|store embeddings|VectorStore\n```\n\n<details>\n<summary>Details</summary>\n\nThe vector database depicted above is stored locally on your machine. You can check it's location by running the following after installing this project:\n\n```python\nfrom platformdirs import PlatformDirs\n\nprint(PlatformDirs('bookworm').user_data_dir)\n```\n\n</details>\n\n---\n\n*`bookworm ask`*\n\nSearch from your bookmarks\n\n```mermaid\ngraph LR\n\nquery\nBookworm(bookworm ask)\n\nsubgraph _\n LLM(LLM e.g OpenAI)\n VectorStore(Vector Store e.g DuckDB)\nend\n\nquery -->|user queries for information|Bookworm\n\nBookworm -->|similarity search|VectorStore -->|send similar docs + user query|LLM\nLLM -->|send back response|Bookworm\n```\n\n---\n\n*`bookworm export`*\n\nExport your bookmarks across all supported browsers into an output (e.g CSV)\n\n```mermaid\ngraph LR\n\nVectorStore\nBookworm(bookworm export)\nCSV(bookmarks.csv)\n\nVectorStore -->|extract all bookmarks|Bookworm\nBookworm -->|export into file|CSV\n```\n\n## Developer Setup\n\n```bash\n# LLMs\nexport OPENAI_API_KEY=\n\n# Langchain (optional, but useful for debugging)\nexport LANGCHAIN_API_KEY=\nexport LANGCHAIN_TRACING_V2=true\nexport LANGCHAIN_PROJECT=bookworm\n\n# Misc (optional)\nexport LOGGING_LEVEL=INFO\n```\n\nRecommendations:\n\n- Install [`pyenv`](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) and ensure [build dependencies are installed](https://github.com/pyenv/pyenv?tab=readme-ov-file#install-python-build-dependencies) for your OS.\n- Install [Poetry](https://python-poetry.org/docs/) we will be using [environment management](https://python-poetry.org/docs/managing-environments/) below.\n- VS Code Extensions recommendations can be found [here](./.vscode/extensions.json) and will be suggested upon first opening the project.\n\n\n```bash\npoetry env use 3.9 # or path to your 3.9 installation\n\npoetry shell\npoetry install\n\nbookworm --help\n```\n\n<details>\n<summary>Running Linux tests on MacOS/Windows</summary>\n\nIf you are running on a non-linux machine, it may be helpful to run the provided [Dockerfile](./Dockerfile.linux) to verify it's working on that environment.\n\nYou can build this via:\n\n```bash\nmake docker_linux\n```\n\nYou will need to have Docker installed to run this.\n\n</details>\n\n## Adding an Integration\n\nAs you can see from [usage](#usage), bookworm supports various integrations but not all. If you find one that you want to support one, then a change is needed inside [integrations.py](./bookworm_genai/integrations.py).\n\nYou can see in that file there is a variable called `browsers` that follows this structure:\n\n```python\nbrowsers = {\n \"BROWSER\": {\n \"PLATFORM\": {\n ...\n }\n }\n}\n```\n\nSo say you wanted to add Chrome support in Windows then you would go under the Chrome key and then add a `win32` key which has all the details. You can refer to existing examples but generally the contents of those details are *where* to find the bookmarks on the user's system along with how to *interpret* them.\n\nYou can also find a full list of the document loaders supported [here](https://python.langchain.com/docs/integrations/document_loaders/).",
"bugtrack_url": null,
"license": "MIT",
"summary": "Bookworm - A LLM-powered bookmark search engine",
"version": "0.13.0",
"project_urls": {
"Documentation": "https://github.com/kiran94/bookworm/blob/main/README.md",
"Homepage": "https://pypi.org/project/bookworm_genai/",
"Repository": "https://github.com/kiran94/bookworm"
},
"split_keywords": [
"bookmarks",
" bookmark-manager",
" genai",
" chatbots"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f8054faefce89e83d00a8c06f196ffbc6f63e7f1e379827442ee1d1b489a00d",
"md5": "5fd42446b9b5224ede905585174276ec",
"sha256": "723a6ba0eb60f831f2f38e114e04575d8d1353b4a3c5a3e3cfdc63883f9b79a4"
},
"downloads": -1,
"filename": "bookworm_genai-0.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5fd42446b9b5224ede905585174276ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 14842,
"upload_time": "2024-12-31T12:16:49",
"upload_time_iso_8601": "2024-12-31T12:16:49.886273Z",
"url": "https://files.pythonhosted.org/packages/7f/80/54faefce89e83d00a8c06f196ffbc6f63e7f1e379827442ee1d1b489a00d/bookworm_genai-0.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5a95ea3e7618891a89c031967e898e91ff17fcf2732fffe7ebf47b27aeba84c1",
"md5": "8036d2103fd8b0534f36f0f56a57d672",
"sha256": "9ae10f607d92524eb31b6aabc89d8be4ba81b525a6ecaaf2a3edd6ba4a1c3f82"
},
"downloads": -1,
"filename": "bookworm_genai-0.13.0.tar.gz",
"has_sig": false,
"md5_digest": "8036d2103fd8b0534f36f0f56a57d672",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 13083,
"upload_time": "2024-12-31T12:16:51",
"upload_time_iso_8601": "2024-12-31T12:16:51.316411Z",
"url": "https://files.pythonhosted.org/packages/5a/95/ea3e7618891a89c031967e898e91ff17fcf2732fffe7ebf47b27aeba84c1/bookworm_genai-0.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-31 12:16:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kiran94",
"github_project": "bookworm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bookworm_genai"
}
JSON
