{"id":45157409,"url":"https://github.com/couchbase-examples/haystack-demo","last_synced_at":"2026-02-20T05:02:39.025Z","repository":{"id":279932534,"uuid":"861578457","full_name":"couchbase-examples/haystack-demo","owner":"couchbase-examples","description":"This is the haystack pdf demo repository. ","archived":false,"fork":false,"pushed_at":"2025-12-01T05:49:00.000Z","size":107,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-12-03T16:46:42.414Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/couchbase-examples.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-23T06:54:38.000Z","updated_at":"2025-12-01T05:49:04.000Z","dependencies_parsed_at":"2025-03-01T08:45:51.560Z","dependency_job_id":null,"html_url":"https://github.com/couchbase-examples/haystack-demo","commit_stats":null,"previous_names":["couchbase-examples/haystack-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase-examples/haystack-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fhaystack-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fhaystack-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fhaystack-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fhaystack-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase-examples","download_url":"https://codeload.github.com/couchbase-examples/haystack-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fhaystack-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-02-20T05:02:36.217Z","updated_at":"2026-02-20T05:02:39.017Z","avatar_url":"https://github.com/couchbase-examples.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RAG Demo using Couchbase, Streamlit, Haystack, and OpenAI\n\nThis is a demo app built to chat with your custom PDFs using **Couchbase Vector Search** to augment the OpenAI results in a Retrieval-Augmented-Generation (RAG) model.\n\n## Three Implementation Options\n\n### Option 1: Search Vector Index (`chat_with_pdf_with_search_vector_index.py`)\n\nUses **`CouchbaseSearchDocumentStore`** with Search vector indexes, which offers:\n\n- **Flexible vector search** \n- **Rich text search** combined with vector similarity\n- **Complex filtering** using FTS queries\n- **Compatible with Couchbase 7.6+**\n- **Ideal for hybrid search** scenarios combining full-text and vector search\n\n### Option 2: Hyperscale Vector Index (Default - `chat_with_pdf_with_query_vector_index.py`)\n\nUses **`CouchbaseQueryDocumentStore`** with Hyperscale vector index, which offers:\n\n- **High-performance vector search at massive scale** (billions of documents)\n- **Pure vector search** optimized for RAG applications\n- **SQL++ queries** for efficient vector retrieval\n- **Recommended for Couchbase 8.0+** for pure vector similarity search\n\n### Option 3: Composite Vector Index\n\nUses **`CouchbaseQueryDocumentStore`** with Composite vector index, which offers:\n\n- **Vector search with metadata filtering**\n- **Combines vector fields with scalar fields** for pre-filtering\n- **SQL++ queries** with efficient filtered vector retrieval\n- **Best for filtered vector search** scenarios (e.g., filter by date, category, user_id)\n- **Recommended for Couchbase 8.0+** when you need to filter before vector search\n\nThis demo doesn't use Composite Vector index, but you can easily do so by just removing `VECTOR` from [this line](./chat_with_pdf_with_query_vector_index.py#L109) and keeping the rest same. To learn more about how Composite Vector Indexes are made, you can refer [here](https://docs.couchbase.com/cloud/vector-index/composite-vector-index.html).\n\n## How does it work?\n\nYou can upload your PDFs with custom data \u0026 ask questions about the data in the chat box.\nFor each question, you will get two answers:\n\n- one using RAG (Couchbase logo)\n- one using pure LLM - OpenAI (🤖).\n\nThe RAG pipeline utilizes Haystack, Couchbase Vector Search, and OpenAI models. It fetches relevant parts of the PDF using vector search \u0026 adds them as context for the language model.\n\n## Quick Start\n\n1. **Clone this repository**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd haystack-demo\n   ```\n\n2. **Create a Python virtual environment**\n   ```bash\n   python -m venv venv\n   source venv/bin/activate\n   ```\n\n3. **Install dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Create a Couchbase bucket** (via Couchbase UI/Capella) with the name \"sample_bucket\"\n\n5. **Configure environment variables** (see Setup section below)\n\n6. **Run the Streamlit app**\n   ```bash\n   # For Hyperscale Vector Index (default)\n   streamlit run chat_with_pdf_with_query_vector_index.py\n   \n   # OR for Search Vector Index\n   streamlit run chat_with_pdf_with_search_vector_index.py\n   ```\n\n7. **Upload a PDF** - everything else is automatic!\n\nThe app automatically creates:\n- Scopes and collections\n- Vector indexes (after PDF upload for `chat_with_pdf_with_query_vector_index.py`, or on startup for `chat_with_pdf_with_search_vector_index.py`)\n\n## Which Option Should You Choose?\nCouchbase Capella supports three types of vector indexes:\n\n- **Hyperscale Vector Index** (`chat_with_pdf_with_query_vector_index.py`) - Best for RAG/chatbot applications with pure semantic search and billions of documents\n- **Composite Vector Index** - Best when you need to filter by metadata before vector search\n- **Search Vector Index** (`chat_with_pdf_with_search_vector_index.py`) - Best for hybrid searches combining keywords, geospatial, and semantic search\n\n\u003e **For this PDF chat demo, we recommend Hyperscale Vector Index** for optimal performance in RAG applications.\n\nLearn more about choosing the right vector index in the [official Couchbase vector index documentation](https://docs.couchbase.com/cloud/vector-index/use-vector-indexes.html).\n\n\n## Setup and Installation\n\n### Install dependencies\n\n`pip install -r requirements.txt`\n\n### Set the environment secrets\n\nCopy the `secrets.example.toml` file in `.streamlit` folder and rename it to `secrets.toml` and replace the placeholders with the actual values for your environment\n\n**For Hyperscale Vector Index (`chat_with_pdf_with_query_vector_index.py`):**\n```\nDB_CONN_STR = \"\u003ccouchbase_cluster_connection_string\u003e\"\nDB_USERNAME = \"\u003ccouchbase_username\u003e\"\nDB_PASSWORD = \"\u003ccouchbase_password\u003e\"\nDB_BUCKET = \"\u003cbucket_name\u003e\"\nDB_SCOPE = \"\u003cscope_name\u003e\"\nDB_COLLECTION = \"\u003ccollection_name\u003e\"\nOPENAI_API_KEY = \"\u003copenai_api_key\u003e\"\n```\n\n**For Search Vector Index (`chat_with_pdf_with_search_vector_index.py`):**\n\nAdd one additional environment variable to the above configuration:\n```\nINDEX_NAME = \"\u003cvector_capable_search_vector_index_name\u003e\"\n```\n\n### Automatic Resource Setup\n\nThe application automatically handles resource creation in the following order:\n\n**On Application Startup:**\n\n1. Creates the scope if it doesn't exist\n2. Creates the collection if it doesn't exist\n\n**After PDF Upload (`chat_with_pdf_with_query_vector_index.py`):**\n\n3. Automatically creates the Hyperscale index after documents are loaded\n4. Falls back to creating the index on first query if needed\n\n**On Application Startup (`chat_with_pdf_with_search_vector_index.py`):**\n\n3. Attempts to create the Search Vector index (can be created without documents)\n\n**What You Need:**\n- Your Couchbase **bucket must exist** with the name \"sample_bucket\"\n- All other resources (scope, collection, indexes) are created automatically\n- **No manual index creation required** - just upload your PDF and the index will be created\n\n**Note**: For `chat_with_pdf_with_query_vector_index.py`, the vector index is created automatically **after you upload your first PDF** because Hyperscale/Composite indexes require documents for training.\n\n## Manual Vector Index Creation (Optional)\n\n**⚠️ Manual creation is NOT required** - the app creates indexes automatically when you upload a PDF. This section is only for advanced users who want manual control.\n\n### Hyperscale or Composite Vector Index\n\nYou need to create a Hyperscale or Composite vector index on your collection **after** loading some documents (required for index training). Choose between Hyperscale or Composite Index based on your use case. Whichever vector index (Hyperscale or Composite) you choose won't affect the functionality of this demo, though performance differences may occur.\n\n**Option 1: Hyperscale Vector Index (Recommended)**\n\nHyperscale is a dedicated vector index optimized for pure vector search at massive scale. Use this for the best performance in RAG applications. Refer to the [Hyperscale Vector Index Guide](https://docs.couchbase.com/cloud/vector-index/hyperscale-vector-index.html) for detailed instructions.\n\nCreating a Hyperscale Index using SQL++ (use Couchbase Query Workbench or programmatically):\n\n```sql\nCREATE VECTOR INDEX idx_pdf_hyperscale\nON `bucket_name`.`scope_name`.`collection_name`(embedding VECTOR) \nWITH {\n  \"dimension\": 1536,\n  \"similarity\": \"DOT\"\n};\n```\n\n**Option 2: Composite Vector Index**\n\n[Composite indexes](https://docs.couchbase.com/cloud/vector-index/composite-vector-index.html) combine vector fields with other scalar fields. This is useful when you need to filter documents by metadata before performing vector search.\n\nCreating a Composite Index using SQL++:\n\n```sql\nCREATE INDEX idx_pdf_composite \nON `bucket_name`.`scope_name`.`collection_name`(embedding VECTOR) \nWITH {\n  \"dimension\": 1536,\n  \"similarity\": \"DOT\"\n};\n```\n\n**Index Parameters:**\n- `dimension`: Must match your embedding model (1536 for OpenAI ada-002/ada-003, 768 for sentence-transformers)\n- `similarity`: Must match the similarity metric in `CouchbaseQueryDocumentStore`. Use `DOT` for dot product (recommended for OpenAI embeddings)\n\n**Important Notes:**\n1. **Index Creation Timing**: Hyperscale and Composite vector indexes require training data. Create the index **after** you've loaded the documents into your collection.\n2. **Similarity Metric**: The `similarity` parameter in the index **must match** the `similarity` parameter in your `CouchbaseQueryDocumentStore` configuration.\n3. **Dimension**: Must match your embedding model's output dimensions.\n\n**Verifying Your Index:**\n\nAfter creating the index, verify it exists:\n\n```sql\nSELECT * FROM system:indexes \nWHERE name LIKE 'idx_%_vector';\n```\n\n### Search Vector Index (for `chat_with_pdf_with_search_vector_index.py`)\n\n**Automatic Creation**: The app attempts to create the Search Vector index automatically on startup using the `INDEX_NAME` from your configuration.\n\n**Manual Creation** (if automatic creation fails): Create a Full Text Search index with vector capabilities.\n\n**Creating a Search Vector Index with Vector Support**\n\nIf automatic creation fails, you can create the index using the Couchbase UI or by importing the provided index definition.\n\nUsing Couchbase Capella:\n1. Follow the import instructions [here](https://docs.couchbase.com/cloud/search/import-search-index.html)\n2. Use the provided `sampleSearchIndex.json` file in this repository\n3. Update the following values in the JSON before importing:\n   - `sourceName`: Replace `sample_bucket` with your bucket name\n   - `types`: Replace `scope.coll` with your actual `scope_name.collection_name`\n4. Import the file in Capella\n5. Click on Create Index\n\nUsing Couchbase Server:\n1. Navigate to Search -\u003e Add Index -\u003e Import\n2. Use the provided `sampleSearchIndex.json` file in this repository\n3. Update the following values in the JSON before importing:\n   - `sourceName`: Replace `sample_bucket` with your bucket name\n   - `types`: Replace `scope.coll` with your actual `scope_name.collection_name`\n4. Paste the updated JSON in the Import screen\n5. Click on Create Index\n\n**Search Vector Index Definition**\n\nThe `sampleSearchIndex.json` file contains a pre-configured Search Vector index with vector capabilities. Key features:\n- **Index Name**: `sample-index` (customizable)\n- **Vector Field**: `embedding` with 1536 dimensions\n- **Similarity**: `dot_product` (optimized for OpenAI embeddings)\n- **Text Field**: `content` for document text\n- **Metadata**: Dynamic mapping for `meta` fields\n\n## Run the Application\n\n**For Hyperscale or Composite Vector Index:**\n```\nstreamlit run chat_with_pdf_with_query_vector_index.py\n```\n\n**For Search Vector Index:**\n```\nstreamlit run chat_with_pdf_with_search_vector_index.py\n```\n\n## Implementation Details\n\n### Hyperscale Vector Index Implementation (`chat_with_pdf_with_query_vector_index.py`)\n\nThis demo uses the following key components:\n\n1. **CouchbaseQueryDocumentStore**: \n   - Configured with `QueryVectorSearchType.ANN` for fast approximate nearest neighbor search\n   - Uses `QueryVectorSearchSimilarity.DOT` for dot product similarity (recommended for OpenAI embeddings)\n   - Supports both **Hyperscale** and **Composite** vector indexes\n   - Leverages SQL++ for efficient vector retrieval\n   - Same code works for both index types - just create the appropriate index\n\n2. **CouchbaseQueryEmbeddingRetriever**: \n   - Uses SQL++ queries with `APPROX_VECTOR_DISTANCE()` function for ANN search\n   - Retrieves top-k most similar documents based on embedding similarity\n   - Optimized for low-latency, high-throughput vector search\n\n3. **OpenAI Embeddings**: \n   - `text-embedding-ada-002` model with 1536 dimensions\n   - Generates embeddings for both documents and queries\n\nFor more details on implementation, refer to the extensive code comments in `chat_with_pdf_with_query_vector_index.py`.\n\n### Search Vector Index Implementation (`chat_with_pdf_with_search_vector_index.py`)\n\nThis alternative implementation uses:\n\n1. **CouchbaseSearchDocumentStore**:\n   - Uses Full Text Search service for vector indexing and retrieval\n   - Compatible with Couchbase 7.6+ and 8.0+\n   - Supports rich text search combined with vector similarity\n\n2. **CouchbaseSearchEmbeddingRetriever**:\n   - Leverages Search vector index capabilities\n   - Retrieves top-k most similar documents using FTS queries\n   - Supports complex filtering with FTS query syntax\n\n3. **OpenAI Embeddings**:\n   - Same `text-embedding-ada-002` model with 1536 dimensions\n   - Generates embeddings for both documents and queries\n\nFor more details on FTS implementation, refer to the code comments in `chat_with_pdf_with_search_vector_index.py`.\n\n## Additional Resources\n\n- [Couchbase Vector Index Documentation](https://docs.couchbase.com/cloud/vector-index/vectors-and-indexes-overview.html)\n- [Haystack Documentation](https://docs.haystack.deepset.ai/docs/intro)\n- [couchbase-haystack GitHub Repository](https://github.com/Couchbase-Ecosystem/couchbase-haystack)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fhaystack-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase-examples%2Fhaystack-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fhaystack-demo/lists"}