Update README

Co-authored-by: Isaac

Author: janniklasrose

knowledge_base/vector_search_product_discovery/README.md

@@ -1,18 +1,18 @@
 # Vector Search: Semantic Product Discovery
 
-A Declarative Automation Bundle demonstrating **semantic product search** using
+A Declarative Automation Bundle demonstrating semantic product search using
 [Databricks Vector Search](https://docs.databricks.com/en/generative-ai/vector-search.html).
+It automates the full setup — the Unity Catalog schema, the Vector Search endpoint and
+index, and the jobs that load and query the catalog — so a single `databricks bundle deploy`
+gives you a working semantic-search example to explore and adapt.
 
-## The problem
+## How it works
 
 Keyword search fails when shoppers use different words than what appears in product
-descriptions. A customer searching for *"something to keep my coffee hot all day"* won't
-match a product described as an *"insulated stainless water bottle with double-wall vacuum
-insulation"* — even though it's the right answer.
-
-Semantic search using vector embeddings matches on **meaning**, not words.
-
-## How it works
+descriptions. A customer searching for "something to keep my coffee hot all day" won't
+match a product described as an "insulated stainless water bottle with double-wall vacuum
+insulation" even though it's the right answer. Semantic search using vector embeddings
+matches on meaning, not words.
 
 Product descriptions are embedded at upsert time by the setup job using
 [`databricks-gte-large-en`](https://docs.databricks.com/en/machine-learning/foundation-models/supported-models.html).
@@ -27,48 +27,56 @@ product_index  (Direct Access Vector Search index)
 ranked results
 ```
 
-## Bundle resources
+## Project structure
 
-| Resource | Type | Description |
-|---|---|---|
-| `product_search_schema` | `schemas` | Unity Catalog schema that namespaces the index |
-| `product_search_endpoint` | `vector_search_endpoints` | Managed ANN serving endpoint |
-| `product_index` | `vector_search_indexes` | Direct Access index — schema defined in `resources/index.yml` |
-| `product_discovery_setup` | `jobs` | Embeds product descriptions and upserts into the index |
-| `product_discovery_query` | `jobs` | Embeds a query and returns ranked results |
+```
+.
+├── databricks.yml                       # Bundle name, variables, and the deploy target
+├── data/
+│   └── products.json                    # Product catalog — synced to the workspace on deploy
+├── resources/
+│   ├── schema.yml                       # Unity Catalog schema that namespaces the index
+│   ├── vector-search-endpoint.yml       # Vector Search endpoint (managed ANN serving)
+│   ├── vector-search-index.yml          # Direct Access index — schema defined inline
+│   ├── setup-job.yml                    # Job: embed product descriptions and upsert them
+│   └── query-job.yml                    # Job: embed a query and return ranked results
+└── src/
+    ├── 01_upsert_products.py            # Reads products.json, embeds, calls upsert_data
+    └── 02_query_demo.py                 # Semantic search — runs as a job or interactively
+```
 
 ## Prerequisites
 
 - Databricks workspace with Unity Catalog enabled
-- Databricks CLI that supports `vector_search_endpoints` / `vector_search_indexes` as bundle resources
+- Databricks CLI version 1.1.0 or above
 - An existing Unity Catalog catalog (default: `main`)
 
-## Quick start
+## Usage
 
-1. **Authenticate**
+1. Authenticate the CLI:
    ```bash
    databricks auth login --host https://your-workspace.cloud.databricks.com
    ```
 
-2. **Configure** `databricks.yml` — set the workspace host and any variable overrides
+2. Configure `databricks.yml`. Set the workspace host and any variable overrides.
 
-3. **Deploy** — creates the schema, endpoint, index, jobs, and syncs `data/products.json`
+3. Deploy the bundle. This creates the schema, endpoint, index, jobs, and syncs `data/products.json`.
    ```bash
    databricks bundle deploy
    ```
    > Vector Search endpoint creation takes a few minutes to reach ONLINE status.
 
-4. **Load the catalog** — embeds all product descriptions and upserts them into the index
+4. Load the catalog by running the bundle. This embeds all product descriptions and upserts them into the index.
    ```bash
    databricks bundle run product_discovery_setup
    ```
 
-5. **Search** — pass any natural-language query
+5. Pass any natural-language query to search.
    ```bash
    databricks bundle run product_discovery_query --params "query=footwear for slippery wet trails"
    ```
 
-6. **Or open** `src/02_query_demo.py` in your workspace to run queries interactively
+6. Or open `src/02_query_demo.py` in your workspace to run queries interactively.
 
 ## Configuration
 
@@ -89,15 +97,15 @@ databricks bundle deploy \
 | `schema` | `product_search` | Schema created by the bundle |
 | `endpoint_name` | `product-search-endpoint` | Vector Search endpoint name (must be unique per workspace) |
 | `embedding_model` | `databricks-gte-large-en` | Foundation model used for embeddings |
-| `embedding_dimension` | `1024` | Vector dimension — must match `embedding_dimension` in `resources/index.yml` |
+| `embedding_dimension` | `1024` | Vector dimension — must match `embedding_dimension` in `resources/vector-search-index.yml` |
 
-> **Note:** `embedding_dimension` in `resources/index.yml` is hardcoded to `1024` because
+> **Note:** `embedding_dimension` in `resources/vector-search-index.yml` is hardcoded to `1024` because
 > it is immutable after index creation. If you need a different dimension, change the value
-> in `index.yml` before the first deploy.
+> in `vector-search-index.yml` before the first deploy.
 
 ## Index schema
 
-The index schema lives entirely in `resources/index.yml`:
+The index schema lives entirely in `resources/vector-search-index.yml`:
 
 ```yaml
 direct_access_index_spec:
@@ -130,25 +138,7 @@ records enter the index via `upsert_data`. If you already have a pipeline writin
 Delta table, a **Delta Sync** index is often simpler — you point the index at the source
 table and it keeps itself up to date. Replace `index_type: DIRECT_ACCESS` and
 `direct_access_index_spec` with `index_type: DELTA_SYNC` and `delta_sync_index_spec` in
-`resources/index.yml`, and remove the upsert job.
-
-## Project structure
-
-```
-.
-├── databricks.yml
-├── data/
-│   └── products.json               # Product catalog — synced to workspace on deploy
-├── resources/
-│   ├── schema.yml                  # Unity Catalog schema
-│   ├── endpoint.yml                # Vector Search endpoint
-│   ├── index.yml                   # Direct Access index
-│   ├── setup_job.yml               # Embed + upsert job
-│   └── query_demo.yml              # Query job (--params "query=...")
-└── src/
-    ├── 01_upsert_products.py       # Reads products.json, embeds, calls upsert_data
-    └── 02_query_demo.py            # Semantic search — runs as job or interactively
-```
+`resources/vector-search-index.yml`, and remove the upsert job.
 
 ## Resources