{"id":14964967,"url":"https://github.com/okwilkins/rag-cli","last_synced_at":"2025-10-06T09:31:06.184Z","repository":{"id":239360660,"uuid":"799304355","full_name":"okwilkins/rag-cli","owner":"okwilkins","description":"A project to show good CLI practices with a fully fledged RAG system.","archived":false,"fork":false,"pushed_at":"2024-06-13T22:43:23.000Z","size":118,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-16T08:11:41.259Z","etag":null,"topics":["cli","llm","ollama","python","qdrant","rag"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/okwilkins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-11T18:17:26.000Z","updated_at":"2025-01-14T22:07:22.000Z","dependencies_parsed_at":"2024-09-13T23:26:16.079Z","dependency_job_id":"7de8eae5-e7d0-47d6-91b6-3f7e9e813f6f","html_url":"https://github.com/okwilkins/rag-cli","commit_stats":{"total_commits":116,"total_committers":1,"mean_commits":116.0,"dds":0.0,"last_synced_commit":"8b5fdec3e9ea996415573d24a2dade827b13f910"},"previous_names":["okwilkins/python-gnu-parallel","okwilkins/rag-cli"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okwilkins%2Frag-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okwilkins%2Frag-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okwilkins%2Frag-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okwilkins%2Frag-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/okwilkins","download_url":"https://codeload.github.com/okwilkins/rag-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235515428,"owners_count":19002481,"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","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":["cli","llm","ollama","python","qdrant","rag"],"created_at":"2024-09-24T13:34:02.493Z","updated_at":"2025-10-06T09:31:00.832Z","avatar_url":"https://github.com/okwilkins.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg height=\"100\" src=\"https://github.com/okwilkins/rag-cli/raw/main/docs/images/logo.png\" alt=\"RAG CLI\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cb\u003eA project to show good CLI practices with a fully fledged RAG system.\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=center\u003e\n    \u003ca href=\"https://pypi.org/project/rag-cli/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/rag-cli\" alt=\"Python version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/rag-cli/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/rag-cli\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/okwilkins/rag-cli/raw/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-GNU%20GPL-success\" alt=\"GNU GPL\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# RAG CLI\n\n## Installation\n\n```bash\npip install rag-cli\n```\n\n## Features\n\n- CLI tooling for RAG\n- Embedder (Ollama)\n- Vector store (Qdrant)\n\n## Usage\n\n### Docker\n\nIf you don't have a running instance of [Qdrant](https://qdrant.tech/) or [Ollama](https://ollama.com/), you can use the provided docker-compose file to start one.\n\n```bash\ndocker-compose up --build -d\n```\n\nThis will start Ollama on `http://localhost:11434` and Qdrant on `http://localhost:6333`.\n\n#### Development\n\nThis project uses a dev container, which is the easiest way to set up a consistent development environment. Dev containers provide all the necessary tools, dependencies, and configuration, so you can focus on coding right away.\n\n##### Using Dev Containers\n\nThis project uses a dev container for a consistent development environment. To get started:\n\n1. Open the project in Visual Studio Code.\n2. On Windows/Linux, press `Ctrl+Shift+P` and run the command `Remote-Containers: Reopen in Container`. On Mac, press `Cmd+Shift+P` and run the same command.\n3. VS Code will build and start the dev container, providing access to the project's codebase and dependencies.\n\nOther editors may have similar functionality but this project is optimised for Visual Studio Code.\n\n### Embedder\n\nBefore running this command, make sure you have a running instance of [Ollama](https://ollama.com/) and the nomic-embed-text:v1.5 model is available:\n\n```bash\nollama pull nomic-embed-text:v1.5\n```\n\n```bash\nrag-cli embed --ollama-url http://localhost:11434 --file \u003cINPUT_FILE\u003e\n```\n\nYou can alternatively use stdin to pass the text:\n\n```bash\ncat \u003cINPUT_FILE\u003e | rag-cli embed --ollama-url http://localhost:11434\n```\n\n### Vector store\n\n```bash\nrag-cli vector-store \\\n--qdrant-url http://localhost:6333 \\\n--collection-name \u003cCOLLECTION_NAME\u003e \\\n--data '{\u003cJSON_DATA\u003e}'\n--embedding \u003cEMBEDDING_FILE\u003e\n```\n\nYou can alternatively use stdin to pass embeddings:\n\n```bash\ncat \u003cINPUT_FILE\u003e | \\\nrag-cli vector-store \\\n--qdrant-url http://localhost:6333 \\\n--collection-name \u003cCOLLECTION_NAME\u003e \\\n--data '{\u003cJSON_DATA\u003e}'\n```\n\n### RAG Chat\n\n```bash\nrag-cli rag \\\n--ollama-embedding-url http://localhost:11434 \\\n--ollama-chat-url http://localhost:11435 \\\n--qdrant-url http://localhost:6333 \\\n--collection-name nomic-embed-text-v1.5 \\\n--top-k 5 \\\n--min-similarity 0.5\n--file \u003cINPUT_FILE\u003e\n```\n\nYou can alternatively use stdin to pass the text:\n\n```bash\ncat \u003cINPUT_FILE\u003e | \\\n--ollama-embedding-url http://localhost:11434 \\\n--ollama-chat-url http://localhost:11435 \\\n--qdrant-url http://localhost:6333 \\\n--collection-name nomic-embed-text-v1.5 \\\n--top-k 5 \\\n--min-similarity 0.5\n```\n\n### End-to-end Pipeline For Storing Embeddings\n\nHere is an example of an end-to-end pipeline for storing embeddings. It takes the following steps:\n\n- Get a random Wikipedia article\n- Embed the article\n- Store the embedding in Qdrant\n\nBefore running the pipeline make sure you have the following installed:\n\n```bash\nsudo apt-get update \u0026\u0026 sudo apt-get install parallel jq curl\n```\n\nAlso make sure that the `data/articles` and `data/embeddings` directories exist:\n\n```bash\nmkdir -p data/articles data/embeddings\n```\n\nThen run the pipeline:\n\n```bash\nbash scripts/run_pipeline.sh\n```\n\n#### Parallel Pipeline\n\nThe script `scripts/run_pipeline.sh` can be run in parallel with [GNU Parallel](https://www.gnu.org/software/parallel/) to speed up the process.\n\n```bash\nparallel -j 5 -n0 bash scripts/run_pipeline.sh ::: {0..10}\n```\n\n## Examples\n\n### Get 10 Random Wikipedia Articles\n\n```bash\nparallel -n0 -j 10 '\ncurl -L -s \"https://en.wikipedia.org/api/rest_v1/page/random/summary\" | \\\njq -r \".title, .description, .extract\" | \\\ntee data/articles/$(cat /proc/sys/kernel/random/uuid).txt\n' ::: {0..10}\n```\n\n### Run Embedder On All Articles\n\n```bash\nparallel '\nrag-cli embed --ollama-url http://localhost:11434 --file {1} 2\u003e\u003e output.log | \\\njq \".embedding\" | \\\ntee data/embeddings/$(basename {1} .txt) 1\u003e /dev/null\n' ::: $(find data/articles/*.txt)\n```\n\n### Store All Embeddings In Qdrant\n\n```bash\nparallel rag-cli vector-store --qdrant-url http://localhost:6333 --collection-name nomic-embed-text-v1.5 2\u003e\u003e output.log ::: $(find data/embeddings/*)\n```\n\n### Run RAG Chat On A Query\n\n```bash\necho \"Who invented the blue LED?\" | \\\nrag-cli rag \\\n--ollama-embedding-url http://localhost:11434 \\\n--ollama-chat-url http://localhost:11435 \\\n--qdrant-url http://localhost:6333 \\\n--collection-name nomic-embed-text-v1.5 \\\n--top-k 5 \\\n--min-similarity 0.5 \\\n2\u003e\u003e output.log\n```\n\nThis example obviously requires that the articles similar to the query have been embedded and stored in Qdrant. You can do this with the example found in the next section.\n\n### End-to-end Pipeline For A Single Article\n\n```bash\nwikipedia_data=$(curl -L -s \"https://en.wikipedia.org/api/rest_v1/page/summary/Shuji_Nakamura\") \u0026\u0026 \\\npayload_data=$(jq \"{title: .title, description: .description, extract: .extract}\"  \u003c(echo $wikipedia_data)) \u0026\u0026 \\\ntext_to_embed=$(jq -r \".title, .description, .extract\" \u003c(echo $wikipedia_data)) \u0026\u0026 \\\necho $text_to_embed | \\\nrag-cli embed --ollama-url http://localhost:11434 | \\\njq -r \".embedding\" | \\\nrag-cli vector-store \\\n  --qdrant-url http://localhost:6333 \\\n  --collection-name nomic-embed-text-v1.5 \\\n  --data \"$payload_data\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokwilkins%2Frag-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fokwilkins%2Frag-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokwilkins%2Frag-cli/lists"}