{"id":24340956,"url":"https://github.com/kiran94/bookworm","last_synced_at":"2025-09-28T02:30:42.496Z","repository":{"id":270947332,"uuid":"837698003","full_name":"kiran94/bookworm","owner":"kiran94","description":"LLM-powered bookmark search engine","archived":false,"fork":false,"pushed_at":"2025-01-04T09:26:11.000Z","size":157,"stargazers_count":28,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-18T17:21:06.627Z","etag":null,"topics":["bookmark-manager","bookmarks","chatbot","chatgpt","genai","rag"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/bookworm_genai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiran94.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-03T18:40:52.000Z","updated_at":"2025-06-23T01:25:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"c1d191f0-14f3-4a75-9a2f-1187187e5feb","html_url":"https://github.com/kiran94/bookworm","commit_stats":null,"previous_names":["kiran94/bookworm"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/kiran94/bookworm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fbookworm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fbookworm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fbookworm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fbookworm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiran94","download_url":"https://codeload.github.com/kiran94/bookworm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fbookworm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277315639,"owners_count":25797672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-28T02:00:08.834Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bookmark-manager","bookmarks","chatbot","chatgpt","genai","rag"],"created_at":"2025-01-18T07:13:09.593Z","updated_at":"2025-09-28T02:30:42.483Z","avatar_url":"https://github.com/kiran94.png","language":"Python","funding_links":[],"categories":["\u003ca name=\"text-search\"\u003e\u003c/a\u003eText search (alternatives to grep)"],"sub_categories":[],"readme":"# bookworm 📖\n\n[![main](https://github.com/kiran94/bookworm/actions/workflows/main.yml/badge.svg)](https://github.com/kiran94/bookworm/actions/workflows/main.yml) [![PyPI version](https://badge.fury.io/py/bookworm_genai.svg)](https://badge.fury.io/py/bookworm_genai)\n\n\u003e 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[![asciicast](https://asciinema.org/a/696722.svg)](https://asciinema.org/a/696722)\n\n*In the example above, we search for the term “Japan.” While some results don’t explicitly mention the word, terms like “Osaka” appear because they are closely related to the search term based on OpenAI embeddings.*\n\n## Install\n\n```bash\npython -m pip install bookworm_genai\n```\n\n\u003e [!TIP]\n\u003e If you are using [`uvx`](https://docs.astral.sh/uv/guides/tools/) then you can also just run this:\n\u003e ```bash\n\u003e uvx --from bookworm_genai bookworm --help\n\u003e ```\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**          | ✅              | ✅                | ✅      | ❌               |\n| **macOS**          | ✅              | ✅                | ✅      | ❌               |\n| **Windows**        | ❌              | ❌                | ❌      | ❌               |\n\n\u003e [!TIP]\n\u003e ✨ 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 --\u003e|load bookmarks|Bookworm\nBrave --\u003e|load bookmarks|Bookworm\nFirefox --\u003e|load bookmarks|Bookworm\n\nBookworm --\u003e|vectorize bookmarks|EmbeddingsService--\u003e|store embeddings|VectorStore\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eDetails\u003c/summary\u003e\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\u003c/details\u003e\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 --\u003e|user queries for information|Bookworm\n\nBookworm --\u003e|similarity search|VectorStore --\u003e|send similar docs + user query|LLM\nLLM --\u003e|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 --\u003e|extract all bookmarks|Bookworm\nBookworm --\u003e|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\u003cdetails\u003e\n\u003csummary\u003eRunning Linux tests on MacOS/Windows\u003c/summary\u003e\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\u003c/details\u003e\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/).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiran94%2Fbookworm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiran94%2Fbookworm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiran94%2Fbookworm/lists"}