fix(data-access): document the semantic-index helpers in the README (LLMO-7445) (#1948)

## Summary

- Documents the semantic-index helpers (`syncOpportunitySemantic`,
`copyEntityVectors`, and the batched `lookupOpportunitiesByVectors` /
`getQueryEmbeddings` / `upsertQueryEmbeddings` / `touchQueryEmbeddings`)
in the data-access README, next to the URL Index section.
- Docs-only `fix:` commit, intentionally scoped to force a patch release
of `@adobe/spacecat-shared-data-access` (same approach as #1929). The
4.33.0 release from #1942 was tagged
(`@adobe/spacecat-shared-data-access-v4.33.0`, release commit
`8a21efec`) but its npm publish failed with `E422` (sigstore provenance
rejected while the repo was private, run
https://github.com/adobe/spacecat-shared/actions/runs/36001440888). A
re-run skips data-access because the tag already exists, so the batched
helpers are on `main` but not on npm. This release (4.33.1) publishes
them.

## Test plan

- [x] README-only change; no code changes.
- [x] Integration tests ECR image version bump.

Ref: LLMO-7445

---------

Co-authored-by: Tanase Butcaru <tbutcaru@adobe.com>

Author: tb-adbe

packages/spacecat-shared-data-access/README.md

@@ -140,6 +140,40 @@ const matches = await lookupEntityIdsByUrl(postgrestClient, {
 
 See the package `CLAUDE.md` ("URL Index") for the canonicalization, single-writer, and site-scoping contracts.
 
+## Semantic Index
+
+For the topic vector index (`opportunity_semantic_embedding`) and the global query-embedding cache (`semantic_query_embedding`), use the shared helpers so the writer and reader share one text normalization and one storage path. They store and read pre-embedded vectors; embedding is the caller's job (e.g. `AzureEmbeddingClient` from `@adobe/spacecat-shared-gpt-client`).
+
+```js
+import {
+  syncOpportunitySemantic, copyEntityVectors, lookupOpportunitiesByVectors,
+  getQueryEmbeddings, upsertQueryEmbeddings, touchQueryEmbeddings,
+} from '@adobe/spacecat-shared-data-access';
+
+const { postgrestClient } = dataAccess.services;
+const scope = { model: 'azure/text-embedding-3-small', dims: 1536 };
+
+// writer (needs the postgrest_writer role): full-replace an opportunity's topic vectors
+await syncOpportunitySemantic(postgrestClient, {
+  siteId, entityId, entityType, sourceType: 'topic', sources: [{ text, vector, ...scope }],
+});
+
+// writer: copy an opportunity's vector rows to another opportunity in the same site
+await copyEntityVectors(postgrestClient, { siteId, fromEntityId, toEntityId });
+
+// query cache, batched: one entry per text, in input order (null on a miss)
+const cached = await getQueryEmbeddings(postgrestClient, { texts, ...scope });
+await upsertQueryEmbeddings(postgrestClient, { entries: [{ text, vector }], ...scope });
+await touchQueryEmbeddings(postgrestClient, { textHashes, ...scope });
+
+// reader, batched: one best-first list of { entityId, entityType, score } per query vector
+const matches = await lookupOpportunitiesByVectors(postgrestClient, {
+  siteId, sourceType: 'topic', vectors, k: 10, minScore: 0.5, ...scope,
+});
+```
+
+The batched helpers group their calls internally (search in groups of up to 20 vectors, cache reads/touches in groups of 50 hashes), so callers pass whole lists rather than looping per item.
+
 ## Field Mapping Behavior
 
 Public model API remains camelCase while Postgres/PostgREST tables are snake_case.

packages/spacecat-shared-data-access/test/it/postgrest/docker-compose.yml

@@ -2,7 +2,8 @@ name: spacecat-data-access-it
 
 services:
   db:
-    image: postgres:16-alpine
+    # Needs the `vector` extension (data-service >= v5.134.0); same image the data-service compose uses.
+    image: 682033462621.dkr.ecr.us-east-1.amazonaws.com/mysticat-pgvector:pg16
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
@@ -36,16 +37,17 @@ services:
     # v5.80.0 had aged out. Bumped straight to the current tip rather than
     # the oldest still-available tag (v5.104.0) since both are far past v5.80.0 and
     # pinning to the tip buys the most runway before the next forced bump.
+    # v5.137.0 (2026-09-25): v5.115.0 aged out of ECR; also carries the semantic-index schema.
     #
     # To obtain or refresh the digest:
     #   aws ecr describe-images \
     #     --profile <your-profile> --region us-east-1 \
     #     --repository-name mysticat-data-service \
-    #     --image-ids imageTag=v5.115.0 \
+    #     --image-ids imageTag=v5.137.0 \
     #     --query 'imageDetails[0].imageDigest' --output text
     # Then export MYSTICAT_DATA_SERVICE_DIGEST=sha256:<the-digest> before npm run test:it,
     # or set it in the .env file consumed by docker compose. Leave unset for local dev.
-    image: ${MYSTICAT_DATA_SERVICE_REPOSITORY:-682033462621.dkr.ecr.us-east-1.amazonaws.com/mysticat-data-service}:${MYSTICAT_DATA_SERVICE_TAG:-v5.115.0}${MYSTICAT_DATA_SERVICE_DIGEST:+@${MYSTICAT_DATA_SERVICE_DIGEST}}
+    image: ${MYSTICAT_DATA_SERVICE_REPOSITORY:-682033462621.dkr.ecr.us-east-1.amazonaws.com/mysticat-data-service}:${MYSTICAT_DATA_SERVICE_TAG:-v5.137.0}${MYSTICAT_DATA_SERVICE_DIGEST:+@${MYSTICAT_DATA_SERVICE_DIGEST}}
     depends_on:
       db:
         condition: service_healthy