From e14787618e71118e7e4cd07bc309bc83e168438a Mon Sep 17 00:00:00 2001 From: Daniel Bushman Date: Wed, 5 Aug 2026 09:30:24 +0000 Subject: [PATCH 1/3] docs(maproom-plugin): document AWS Bedrock as a supported provider MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brings the plugin's guidance in line with maproom's Bedrock support so the skills and researcher agent diagnose Bedrock setups correctly instead of assuming Google/OpenAI/Ollama. - embedding-providers.md: Bedrock row in the comparison table, full setup section (credential chain, models, Titan-vs-Cohere request-count tradeoff, VPC/FIPS endpoints), env var table entries - troubleshooting.md: four Bedrock failure modes — missing credentials, AccessDenied (model access vs IAM are separate gates), model-not-in-region, throttling — plus the un-inferable dimension case - error-diagnosis.md: Bedrock credential patterns and the AWS-specific note that authentication succeeding says nothing about authorization - concept-glossary.md: matching dimensions do not imply compatible vector spaces (Titan v2 and mxbai-embed-large are both 1024) - maproom-researcher: Bedrock error rows in its triage table - plugin 0.10.0 -> 0.11.0 verify-docs.sh: 11/11 checks pass. Co-Authored-By: Claude Opus 5 (1M context) --- plugins/maproom/.claude-plugin/plugin.json | 2 +- plugins/maproom/agents/maproom-researcher.md | 5 +- .../references/concept-glossary.md | 4 +- .../references/error-diagnosis.md | 32 +++- .../references/embedding-providers.md | 89 ++++++++++- .../references/troubleshooting.md | 140 +++++++++++++++++- 6 files changed, 261 insertions(+), 11 deletions(-) diff --git a/plugins/maproom/.claude-plugin/plugin.json b/plugins/maproom/.claude-plugin/plugin.json index 7faf1d85..38c709e5 100644 --- a/plugins/maproom/.claude-plugin/plugin.json +++ b/plugins/maproom/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "maproom", - "version": "0.10.0", + "version": "0.11.0", "description": "Semantic code search using the maproom CLI. Find code by concept, understand architecture, and explore relationships between code elements.", "author": { "name": "Daniel Bushman", diff --git a/plugins/maproom/agents/maproom-researcher.md b/plugins/maproom/agents/maproom-researcher.md index ca1c2e9c..c302fbf1 100644 --- a/plugins/maproom/agents/maproom-researcher.md +++ b/plugins/maproom/agents/maproom-researcher.md @@ -303,6 +303,9 @@ When analyzing CLI output, recognize these patterns as **credential issues, not | "invalid_rapt" | Expired Google authentication token | Same as above — refresh ADC credentials | | "quota_project_id is required" | Missing GCP quota project configuration | Run: `gcloud auth application-default set-quota-project ` | | "OPENAI_API_KEY" in error when not using OpenAI | Wrong embedding provider configured | Check `MAPROOM_EMBEDDING_PROVIDER` env var; see embedding-providers.md | +| "No AWS credentials found for the Bedrock embedding provider" | Bedrock configured but the AWS credential chain found nothing | The error lists every source tried; verify with `aws sts get-caller-identity`, or `aws sso login --profile NAME` | +| "Access denied invoking ... in REGION" (Bedrock) | Model access not enabled, or missing `bedrock:InvokeModel` | Enable the model under Bedrock > Model access for that account+region, and grant the IAM action | +| "was not found in region" (Bedrock) | Model not offered in that region | Set `MAPROOM_BEDROCK_REGION` to a region that has it | **IMPORTANT:** If the error matches any pattern above, do NOT: - Suggest filing a bug against the CLI @@ -316,7 +319,7 @@ Instead: 4. Reference the ADC setup guide for detailed instructions: `../skills/maproom-search/references/adc-setup.md` **Distinguishing credential errors from actual code bugs:** -- **Credential issue:** Error message contains "ADC", "token provider", "invalid_rapt", "quota_project_id", or references an API key for a provider you are not using +- **Credential issue:** Error message contains "ADC", "token provider", "invalid_rapt", "quota_project_id", "No AWS credentials found", "IAM Identity Center token", or references an API key for a provider you are not using - **Code bug:** Error message references code paths, panics, segfaults, or describes unexpected behavior that occurs even with valid, fresh credentials **Security:** Do not include actual credentials, access tokens, or project IDs in your findings output. Use placeholders like `YOUR_PROJECT_ID`. diff --git a/plugins/maproom/skills/maproom-guide/references/concept-glossary.md b/plugins/maproom/skills/maproom-guide/references/concept-glossary.md index 93406d08..f4cdb99b 100644 --- a/plugins/maproom/skills/maproom-guide/references/concept-glossary.md +++ b/plugins/maproom/skills/maproom-guide/references/concept-glossary.md @@ -96,7 +96,9 @@ This is the score you see in vector search results. See [result-interpretation.m ### Provider Incompatibility -Different embedding providers (Google Vertex AI, OpenAI, Ollama) produce vectors in different mathematical spaces. Embeddings from one provider **cannot be compared** with embeddings from another. If you switch providers, you must regenerate all embeddings with `maproom generate-embeddings`. +Different embedding providers (Google Vertex AI, OpenAI, Ollama, AWS Bedrock) produce vectors in different mathematical spaces. Embeddings from one provider **cannot be compared** with embeddings from another. If you switch providers, you must regenerate all embeddings with `maproom generate-embeddings`. + +Matching dimensions do **not** imply compatibility. Bedrock's `amazon.titan-embed-text-v2:0` and Ollama's `mxbai-embed-large` are both 1024-dimensional, but their coordinates mean entirely different things — similarity scores between them are noise. Re-index on any provider or model change, even when the dimension is unchanged. --- diff --git a/plugins/maproom/skills/maproom-guide/references/error-diagnosis.md b/plugins/maproom/skills/maproom-guide/references/error-diagnosis.md index 4b3b6ee3..0ae4e98b 100644 --- a/plugins/maproom/skills/maproom-guide/references/error-diagnosis.md +++ b/plugins/maproom/skills/maproom-guide/references/error-diagnosis.md @@ -10,7 +10,7 @@ Every maproom error falls into one of five categories. Identifying the category | Category | Caused By | User-Actionable? | Examples | |---|---|---|---| -| **Credential** | Expired tokens, missing API keys, wrong provider | Yes — refresh or configure | ADC expiry, missing OPENAI_API_KEY | +| **Credential** | Expired tokens, missing API keys, wrong provider | Yes — refresh or configure | ADC expiry, missing OPENAI_API_KEY, expired AWS SSO session | | **Index** | Repo not scanned, stale data, missing embeddings | Yes — scan or regenerate | "No repositories indexed", stale results | | **CLI** | Binary missing, wrong version, invalid flags | Yes — install or fix syntax | "command not found", invalid flag value | | **Query** | Wrong search type, bad filters, special chars | Yes — reformulate query | Zero results, irrelevant results | @@ -32,10 +32,11 @@ Every maproom error falls into one of five categories. Identifying the category ### Why Credentials Expire -Maproom's vector search and embedding generation call external APIs (Google Vertex AI by default, or OpenAI). These APIs require authentication tokens that expire periodically as a security measure. +Maproom's vector search and embedding generation call external APIs (Google Vertex AI by default, or OpenAI, or AWS Bedrock). These APIs require authentication tokens that expire periodically as a security measure. - **Google ADC tokens** expire after ~1 hour and are automatically refreshed — but the refresh token itself can expire after extended periods of inactivity - **OpenAI API keys** don't expire by time, but can be revoked or rate-limited +- **AWS SSO sessions** expire after the session duration configured by the account (commonly 8-12 hours); `aws sso login --profile NAME` re-establishes them. Instance-role and IRSA credentials refresh automatically and rarely surface as errors. ### How to Recognize Credential Errors @@ -46,6 +47,9 @@ Credential errors contain one of these patterns in the error message: - "invalid_rapt" - "quota_project_id is required" - References to `OPENAI_API_KEY` when you're not using OpenAI +- "No AWS credentials found for the Bedrock embedding provider" (Bedrock; the message lists every source that was tried) +- "No valid IAM Identity Center token cached" (Bedrock via SSO — run `aws sso login`) +- "AWS profile 'NAME' not found" (Bedrock; the message lists the profiles that do exist) **Note:** The top-level error message is usually "Failed to create embedding service". The specific credential detail (ADC, token provider, etc.) appears in the `Caused by` chain below it. An agent scanning only the first line of error output should match on "Failed to create embedding service" as the primary pattern. @@ -63,7 +67,29 @@ Credential errors contain one of these patterns in the error message: 1. **Don't investigate maproom source code** — credential errors are expected operational events 2. **Fall back to FTS** — `maproom search` works entirely locally, no credentials needed -3. **Refresh credentials** when convenient — see [ADC setup guide](../../maproom-search/references/adc-setup.md) +3. **Refresh credentials** when convenient — see [ADC setup guide](../../maproom-search/references/adc-setup.md) for Google, or `aws sso login --profile NAME` for AWS Bedrock + +### Bedrock-specific credential notes + +Bedrock has no maproom API key — it signs requests with the standard AWS +credential chain. That changes diagnosis in two useful ways: + +- The "no credentials" error **enumerates every source it tried** (environment, + named profile, web identity, default profile, container endpoint, IMDSv2) and + why each failed. Read that list before investigating anything else. +- `aws sts get-caller-identity` is an independent check. If it succeeds and + maproom still fails, the problem is authorization (IAM or model access), not + authentication. + +Two distinct gates cause `AccessDeniedException`, and both must be open: + +1. **Model access** — enable the model under **Bedrock > Model access** in the + AWS console, per account and per region. +2. **IAM** — the caller needs `bedrock:InvokeModel` on the model ARN. + +A `ResourceNotFoundException` naming the region usually means the model is not +offered there, not that the id is wrong — Bedrock model availability varies by +region. --- diff --git a/plugins/maproom/skills/maproom-search/references/embedding-providers.md b/plugins/maproom/skills/maproom-search/references/embedding-providers.md index c83dd631..b83a1b68 100644 --- a/plugins/maproom/skills/maproom-search/references/embedding-providers.md +++ b/plugins/maproom/skills/maproom-search/references/embedding-providers.md @@ -1,6 +1,6 @@ # Embedding Provider Comparison -Maproom supports three embedding providers for vector search: Google Vertex AI, OpenAI, and Ollama. This guide helps you choose the right provider and configure it for your environment. +Maproom supports four embedding providers for vector search: Google Vertex AI, OpenAI, Ollama, and AWS Bedrock. This guide helps you choose the right provider and configure it for your environment. ## Overview @@ -15,6 +15,7 @@ Embedding providers convert code chunks into numerical vectors (embeddings) that | Google Vertex AI | ADC or service account (`GOOGLE_APPLICATION_CREDENTIALS`) | [ADC setup guide](./adc-setup.md) | Free tier available, then per-character pricing ([pricing](https://cloud.google.com/vertex-ai/pricing)) | 768 (`text-embedding-004`) | High quality embeddings; free tier; Google ecosystem integration | Requires GCP project; ADC credentials expire and need refresh | Teams already using Google Cloud; production environments with GCP infrastructure | | OpenAI | API key (`OPENAI_API_KEY`) | Set environment variable | ~$0.02 per 1M tokens ([pricing](https://openai.com/api/pricing/)) | 1536 (`text-embedding-3-small`) | Simple API key setup; widely used; high quality | Requires paid API key; higher dimensions increase storage; network-dependent | Quick setup; teams already using OpenAI; when simplicity is preferred | | Ollama | None (local) | Install Ollama and pull model | Free (runs locally) | Varies by model (768 for `nomic-embed-text`, 1024 for `mxbai-embed-large`) | Free; fully offline; no credentials needed; data stays local | Requires local compute resources; quality varies by model; slower on CPU | Air-gapped environments; cost-sensitive workflows; local development without API keys | +| AWS Bedrock | Standard AWS credential chain (no new secret) | Enable model access + `bedrock:InvokeModel` | ~$0.02 per 1M tokens ([pricing](https://aws.amazon.com/bedrock/pricing/)) | 1024 (`amazon.titan-embed-text-v2:0`; 512/256 also selectable) | No new API key to manage; works with SSO, EC2/EKS/ECS roles; traffic can stay in a VPC; cheapest cloud option | Requires an AWS account with Bedrock enabled in-region; Titan sends one request per chunk | Teams already on AWS; environments that forbid introducing new long-lived secrets | > **Pricing disclaimer:** Costs shown are approximate as of Feb 2026 and are subject to change. Always check the linked pricing pages for current rates. @@ -92,6 +93,78 @@ export MAPROOM_EMBEDDING_DIMENSION=1536 maproom generate-embeddings ``` +### AWS Bedrock + +**Model:** `amazon.titan-embed-text-v2:0` (default) +**Dimensions:** 1024 (512 and 256 also supported by Titan v2) +**Endpoint:** `bedrock-runtime.REGION.amazonaws.com` + +Bedrock has **no maproom-specific API key**. Requests are signed with AWS +Signature V4 using the same credential chain the `aws` CLI uses. If +`aws sts get-caller-identity` works on the machine, maproom will work. + +**Prerequisites:** + +1. Enable the model under **Bedrock > Model access** in the AWS console (one + time, per account, per region). Without this, every request returns + `AccessDeniedException` even when IAM is correct. +2. Grant the caller `bedrock:InvokeModel` on the model ARN. + +**Environment variables:** + +```bash +# Set the embedding provider ('aws' and 'aws-bedrock' also work) +export MAPROOM_EMBEDDING_PROVIDER=bedrock + +# Optional: which AWS profile to use (falls back to AWS_PROFILE) +export MAPROOM_AWS_PROFILE=my-profile + +# Optional: region (falls back to AWS_REGION, AWS_DEFAULT_REGION, +# the profile's region, then us-east-1) +export MAPROOM_BEDROCK_REGION=us-east-1 + +# Optional: override model (default: amazon.titan-embed-text-v2:0) +export MAPROOM_EMBEDDING_MODEL=cohere.embed-english-v3 + +# Optional: override dimensions (inferred from the model otherwise) +export MAPROOM_EMBEDDING_DIMENSION=1024 +``` + +**Credential resolution order:** + +1. `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (+ `AWS_SESSION_TOKEN`) +2. A named profile (`MAPROOM_AWS_PROFILE` or `AWS_PROFILE`) +3. Web identity (`AWS_WEB_IDENTITY_TOKEN_FILE` + `AWS_ROLE_ARN`) — EKS IRSA +4. The `default` profile +5. ECS task role / EKS Pod Identity +6. EC2 instance role (IMDSv2) + +Profiles may themselves use static keys, `credential_process`, IAM Identity +Center (SSO), or `role_arn` + `source_profile` chaining. + +**Available models:** + +| Model | Dimensions | Texts per request | +|-------|-----------:|------------------:| +| `amazon.titan-embed-text-v2:0` | 1024 (or 512, 256) | 1 | +| `amazon.titan-embed-text-v1` | 1536 | 1 | +| `cohere.embed-english-v3` | 1024 | 96 | +| `cohere.embed-multilingual-v3` | 1024 | 96 | + +Prefer a Cohere model for large repositories: Bedrock's `InvokeModel` embeds +one document per call for Titan, so a 50,000-chunk scan is 50,000 requests +versus roughly 520 with Cohere. + +**Generate embeddings:** + +```bash +maproom generate-embeddings +``` + +**Private networking:** for VPC/PrivateLink endpoints or an egress proxy, set +`MAPROOM_BEDROCK_ENDPOINT_URL`. For FIPS 140-3 endpoints, set +`MAPROOM_BEDROCK_USE_FIPS=true`. + ### Ollama **Models:** `nomic-embed-text` (768 dimensions), `mxbai-embed-large` (1024 dimensions), and others @@ -148,7 +221,9 @@ maproom generate-embeddings Switching embedding providers requires regenerating all embeddings because: -1. **Different dimensions:** Google produces 768-dimensional vectors, OpenAI produces 1536-dimensional vectors, and Ollama dimensions vary by model. These vectors cannot be compared. +1. **Different dimensions:** Google produces 768-dimensional vectors, OpenAI produces 1536-dimensional vectors, Bedrock's default Titan v2 produces 1024, and Ollama dimensions vary by model. These vectors cannot be compared. + + Note that matching dimensions is *not* sufficient — Bedrock Titan v2 and Ollama `mxbai-embed-large` are both 1024-dimensional but occupy unrelated vector spaces. Re-index when switching between them even though the dimension does not change. 2. **Different vector spaces:** Even if dimensions matched, each provider's model maps concepts to different coordinates. Cosine similarity scores between vectors from different providers are meaningless. **To switch providers:** @@ -171,7 +246,7 @@ maproom vector-search --repo YOUR_REPO --query "test query" --format agent | Variable | Description | Example | |----------|-------------|---------| -| `MAPROOM_EMBEDDING_PROVIDER` | Provider selection | `ollama`, `openai`, `google` | +| `MAPROOM_EMBEDDING_PROVIDER` | Provider selection | `ollama`, `openai`, `google`, `bedrock` | | `MAPROOM_EMBEDDING_MODEL` | Model override | `text-embedding-004`, `text-embedding-3-small`, `nomic-embed-text` | | `MAPROOM_EMBEDDING_DIMENSION` | Dimension override | `768`, `1536`, `1024` | | `OPENAI_API_KEY` | OpenAI API key | `sk-...` (placeholder) | @@ -179,6 +254,11 @@ maproom vector-search --repo YOUR_REPO --query "test query" --format agent | `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON | `/path/to/key.json` | | `GOOGLE_PROJECT_ID` | Google Cloud project ID | `YOUR_PROJECT_ID` | | `MAPROOM_GOOGLE_PROJECT_ID` | Google Cloud project ID (prefixed) | `YOUR_PROJECT_ID` | +| `MAPROOM_AWS_PROFILE` | AWS shared-config profile for Bedrock | `my-profile` | +| `AWS_PROFILE` | AWS profile (fallback) | `my-profile` | +| `MAPROOM_BEDROCK_REGION` | Bedrock region override | `us-east-1` | +| `MAPROOM_BEDROCK_ENDPOINT_URL` | Bedrock endpoint override (VPC/proxy) | `https://vpce-...amazonaws.com` | +| `MAPROOM_BEDROCK_USE_FIPS` | Use the region's FIPS endpoint | `true` | ## FAQ @@ -199,6 +279,7 @@ No. Full-text search uses SQLite FTS5 indexes and does not involve embeddings at - If you have no API keys and want to get started quickly, use **Ollama** (free, local, no setup beyond installation). - If you already have an OpenAI API key, use **OpenAI** (simplest cloud setup). - If your team uses Google Cloud, use **Google Vertex AI** (best integration with GCP tooling). +- If your team is on AWS, use **AWS Bedrock** — it is the cheapest cloud option and introduces no new secret, since it reuses whatever already authenticates the `aws` CLI. ### Do higher dimensions mean better search quality? @@ -216,6 +297,8 @@ The `generate-embeddings` command will fail mid-process. Refresh your credential - [Google Vertex AI Pricing](https://cloud.google.com/vertex-ai/pricing) - Official Google Cloud pricing - [OpenAI API Pricing](https://openai.com/api/pricing/) - Official OpenAI pricing - [Ollama](https://ollama.com/) - Official Ollama website and documentation +- [AWS Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/) - Official AWS pricing +- [AWS Bedrock model support by region](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) --- diff --git a/plugins/maproom/skills/maproom-search/references/troubleshooting.md b/plugins/maproom/skills/maproom-search/references/troubleshooting.md index 957e76ff..178a67aa 100644 --- a/plugins/maproom/skills/maproom-search/references/troubleshooting.md +++ b/plugins/maproom/skills/maproom-search/references/troubleshooting.md @@ -387,15 +387,151 @@ Error: Failed to create embedding service. Ensure OPENAI_API_KEY is set. ```bash export OPENAI_API_KEY="" ``` -4. If you see `OPENAI_API_KEY` in the error but are not using OpenAI, the provider may be misconfigured. See [Embedding Providers](./embedding-providers.md) for correct configuration. +4. If set to `bedrock`, no maproom key is needed — verify AWS credentials resolve: + ```bash + aws sts get-caller-identity + ``` +5. If you see `OPENAI_API_KEY` in the error but are not using OpenAI, the provider may be misconfigured. See [Embedding Providers](./embedding-providers.md) for correct configuration. **Reference:** See [Embedding Providers](./embedding-providers.md) for the full list of supported providers and their required environment variables. +### AWS Bedrock: "No AWS credentials found" + +``` +Error: Failed to create embedding service +Caused by: No AWS credentials found for the Bedrock embedding provider. + + Tried, in order: + - environment (AWS_ACCESS_KEY_ID unset) + - web identity (AWS_WEB_IDENTITY_TOKEN_FILE unset) + - default profile (not configured) + - container credentials (endpoint env vars unset) + - EC2 IMDSv2 (not an EC2 instance) +``` + +**Cause:** Bedrock signs requests with the standard AWS credential chain and +found nothing usable. The error lists every source it tried and why each +failed — read that list first, it is the diagnosis. + +**Recovery:** + +1. Confirm the machine can authenticate to AWS at all: + ```bash + aws sts get-caller-identity + ``` +2. If that fails, authenticate however your organization does — commonly: + ```bash + aws sso login --profile my-profile + export AWS_PROFILE=my-profile + ``` +3. If `aws sts get-caller-identity` succeeds but maproom still fails, the + environment maproom runs in differs from your shell. Check that + `AWS_PROFILE` is exported (not just set) and visible to the process. + +**Exit code:** 2 (configuration error — retrying will not help). + +### AWS Bedrock: "AccessDeniedException" + +``` +Error: Access denied invoking amazon.titan-embed-text-v2:0 in us-east-1 +``` + +**Cause:** Two independent gates control Bedrock access and **both** must be +open. Authentication succeeding tells you nothing about either. + +**Recovery:** + +1. **Model access** — in the AWS console, go to **Bedrock > Model access** and + enable the embedding model. This is per account *and* per region, and is the + more commonly missed of the two. +2. **IAM** — the calling identity needs `bedrock:InvokeModel` on the model ARN: + ```json + { + "Effect": "Allow", + "Action": "bedrock:InvokeModel", + "Resource": "arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0" + } + ``` +3. Confirm which identity is actually being used — it may not be the one you + expect if a profile or instance role is in play: + ```bash + aws sts get-caller-identity + RUST_LOG=info maproom generate-embeddings # logs the credential source + ``` + +### AWS Bedrock: model not found in region + +``` +Error: Model 'cohere.embed-english-v3' was not found in region eu-west-2 +``` + +**Cause:** Bedrock model availability varies by region. The model id is +probably correct; the region does not offer it. + +**Recovery:** + +1. List the embedding models actually offered where you are: + ```bash + aws bedrock list-foundation-models --region "$AWS_REGION" \ + --query "modelSummaries[?outputModalities[0]=='EMBEDDING'].modelId" + ``` +2. Either pick an available model, or point only maproom at a region that has + the one you want: + ```bash + export MAPROOM_BEDROCK_REGION=us-east-1 + ``` + +### AWS Bedrock: slow scans / throttling + +**Symptom:** Embedding generation is much slower than expected. With +`RUST_LOG=debug`, repeated "retrying in Nms" lines mention throttling. + +**Root Cause:** Bedrock enforces a requests-per-minute quota per model per +region. Titan models embed **one document per request**, so a large scan is +request-bound. Throttling is retried automatically with backoff, so this shows +up as slowness rather than failure. + +**Fix:** any of — + +1. Switch to a Cohere model, which batches 96 texts per request (~96x fewer + requests): + ```bash + export MAPROOM_EMBEDDING_MODEL=cohere.embed-english-v3 + ``` +2. Lower concurrency so fewer requests are in flight: + ```bash + export MAPROOM_EMBEDDING_PARALLEL_MAX_CONCURRENCY=6 + ``` +3. Request a higher **InvokeModel requests per minute** quota for the model in + the AWS Service Quotas console. + +### AWS Bedrock: "Cannot infer the embedding dimension" + +``` +Error: Cannot infer the embedding dimension for Bedrock model 'arn:aws:bedrock:...' +``` + +**Cause:** The model id is not one maproom recognizes — usually a +provisioned-throughput ARN or a model released after your maproom build. + +**Fix:** set the width explicitly. + +```bash +export MAPROOM_EMBEDDING_DIMENSION=1024 +``` + +maproom refuses to guess here deliberately: a wrong dimension produces an index +that builds successfully and then returns no vector-search results. + ### Network Timeout During Vector Search **Symptom:** `maproom vector-search` hangs or times out during embedding generation. The command does not return results or an error within the expected time frame. -**Root Cause:** The OpenAI API is unreachable due to network connectivity issues. Vector search requires a live API call to generate query embeddings — unlike FTS search, it cannot operate offline. +**Root Cause:** The embedding API is unreachable due to network connectivity issues. Vector search requires a live API call to generate query embeddings — unlike FTS search, it cannot operate offline. (Ollama is the exception: it runs locally.) + +For AWS Bedrock behind a restricted network, confirm the endpoint is reachable +and, if you route through PrivateLink or an egress proxy, that +`MAPROOM_BEDROCK_ENDPOINT_URL` points at it. **Fix:** 1. Check network connectivity to the OpenAI API: From 16b0760032366b1628fab46ed09eb6dd29fb4c10 Mon Sep 17 00:00:00 2001 From: Daniel Bushman Date: Wed, 5 Aug 2026 10:01:36 +0000 Subject: [PATCH 2/3] docs(maproom-plugin): correct Bedrock dimension guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Titan v2's 512/256 widths are not usable with maproom — vector storage is per-dimension and covers 768/1024/1536 only. Match the CLI, which now rejects them at startup. Co-Authored-By: Claude Opus 5 (1M context) --- .../maproom-search/references/embedding-providers.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/plugins/maproom/skills/maproom-search/references/embedding-providers.md b/plugins/maproom/skills/maproom-search/references/embedding-providers.md index b83a1b68..cd6183c2 100644 --- a/plugins/maproom/skills/maproom-search/references/embedding-providers.md +++ b/plugins/maproom/skills/maproom-search/references/embedding-providers.md @@ -15,7 +15,7 @@ Embedding providers convert code chunks into numerical vectors (embeddings) that | Google Vertex AI | ADC or service account (`GOOGLE_APPLICATION_CREDENTIALS`) | [ADC setup guide](./adc-setup.md) | Free tier available, then per-character pricing ([pricing](https://cloud.google.com/vertex-ai/pricing)) | 768 (`text-embedding-004`) | High quality embeddings; free tier; Google ecosystem integration | Requires GCP project; ADC credentials expire and need refresh | Teams already using Google Cloud; production environments with GCP infrastructure | | OpenAI | API key (`OPENAI_API_KEY`) | Set environment variable | ~$0.02 per 1M tokens ([pricing](https://openai.com/api/pricing/)) | 1536 (`text-embedding-3-small`) | Simple API key setup; widely used; high quality | Requires paid API key; higher dimensions increase storage; network-dependent | Quick setup; teams already using OpenAI; when simplicity is preferred | | Ollama | None (local) | Install Ollama and pull model | Free (runs locally) | Varies by model (768 for `nomic-embed-text`, 1024 for `mxbai-embed-large`) | Free; fully offline; no credentials needed; data stays local | Requires local compute resources; quality varies by model; slower on CPU | Air-gapped environments; cost-sensitive workflows; local development without API keys | -| AWS Bedrock | Standard AWS credential chain (no new secret) | Enable model access + `bedrock:InvokeModel` | ~$0.02 per 1M tokens ([pricing](https://aws.amazon.com/bedrock/pricing/)) | 1024 (`amazon.titan-embed-text-v2:0`; 512/256 also selectable) | No new API key to manage; works with SSO, EC2/EKS/ECS roles; traffic can stay in a VPC; cheapest cloud option | Requires an AWS account with Bedrock enabled in-region; Titan sends one request per chunk | Teams already on AWS; environments that forbid introducing new long-lived secrets | +| AWS Bedrock | Standard AWS credential chain (no new secret) | Enable model access + `bedrock:InvokeModel` | ~$0.02 per 1M tokens ([pricing](https://aws.amazon.com/bedrock/pricing/)) | 1024 (`amazon.titan-embed-text-v2:0`) | No new API key to manage; works with SSO, EC2/EKS/ECS roles; traffic can stay in a VPC; cheapest cloud option | Requires an AWS account with Bedrock enabled in-region; Titan sends one request per chunk | Teams already on AWS; environments that forbid introducing new long-lived secrets | > **Pricing disclaimer:** Costs shown are approximate as of Feb 2026 and are subject to change. Always check the linked pricing pages for current rates. @@ -96,7 +96,12 @@ maproom generate-embeddings ### AWS Bedrock **Model:** `amazon.titan-embed-text-v2:0` (default) -**Dimensions:** 1024 (512 and 256 also supported by Titan v2) +**Dimensions:** 1024 + +Titan v2 can also emit 512- and 256-dimensional vectors, but maproom stores +embeddings in per-dimension tables and supports only 768, 1024, and 1536. +Setting `MAPROOM_EMBEDDING_DIMENSION=512` is rejected at startup rather than +after a full scan. **Endpoint:** `bedrock-runtime.REGION.amazonaws.com` Bedrock has **no maproom-specific API key**. Requests are signed with AWS @@ -146,7 +151,7 @@ Center (SSO), or `role_arn` + `source_profile` chaining. | Model | Dimensions | Texts per request | |-------|-----------:|------------------:| -| `amazon.titan-embed-text-v2:0` | 1024 (or 512, 256) | 1 | +| `amazon.titan-embed-text-v2:0` | 1024 | 1 | | `amazon.titan-embed-text-v1` | 1536 | 1 | | `cohere.embed-english-v3` | 1024 | 96 | | `cohere.embed-multilingual-v3` | 1024 | 96 | From 4497cba48a6dff33fc12984438b8ec41d39fac6c Mon Sep 17 00:00:00 2001 From: Daniel Bushman Date: Wed, 5 Aug 2026 13:57:01 +0000 Subject: [PATCH 3/3] docs(maproom-plugin): address CodeRabbit review on #71 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - version 0.11.0 -> 0.10.4. Docs-only changes take a patch bump. Not 0.10.1 as suggested: sibling branches maproom-plugin-{critical-fixes,docs-refresh, cross-repo-docs} already claim 0.10.1-0.10.3 off the same 0.10.0 base. - "If aws sts get-caller-identity works, maproom will work" scoped to authentication; model access and bedrock:InvokeModel are separate gates. - MD040: language tags on the four new Bedrock error-output fences (text, not console — these are program output, with no prompt or command lines). - The region diagnostic resolved $AWS_REGION, which can differ from the region maproom uses. It now walks maproom's own precedence. Not a bare substitution to $MAPROOM_BEDROCK_REGION as suggested: that variable is optional and usually unset, so the command would have lost its --region. - The dimension example keeps a runnable value but now states the storable set (768/1024/1536) and which models it corresponds to. - The network-timeout check was OpenAI-only under a provider-neutral root cause; now branches per provider. - Troubleshooting mentions the aws / aws-bedrock aliases where it names the provider value. Declined: removing the alias note from embedding-providers.md. It documents real, tested CLI behavior; the fix was to make the sibling section alias-aware instead. verify-docs.sh: 11/11 pass. Co-Authored-By: Claude Opus 5 (1M context) --- plugins/maproom/.claude-plugin/plugin.json | 2 +- .../references/embedding-providers.md | 7 +++- .../references/troubleshooting.md | 34 +++++++++++++------ 3 files changed, 31 insertions(+), 12 deletions(-) diff --git a/plugins/maproom/.claude-plugin/plugin.json b/plugins/maproom/.claude-plugin/plugin.json index 38c709e5..0467b2ba 100644 --- a/plugins/maproom/.claude-plugin/plugin.json +++ b/plugins/maproom/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "maproom", - "version": "0.11.0", + "version": "0.10.4", "description": "Semantic code search using the maproom CLI. Find code by concept, understand architecture, and explore relationships between code elements.", "author": { "name": "Daniel Bushman", diff --git a/plugins/maproom/skills/maproom-search/references/embedding-providers.md b/plugins/maproom/skills/maproom-search/references/embedding-providers.md index cd6183c2..aa97f9f7 100644 --- a/plugins/maproom/skills/maproom-search/references/embedding-providers.md +++ b/plugins/maproom/skills/maproom-search/references/embedding-providers.md @@ -106,7 +106,12 @@ after a full scan. Bedrock has **no maproom-specific API key**. Requests are signed with AWS Signature V4 using the same credential chain the `aws` CLI uses. If -`aws sts get-caller-identity` works on the machine, maproom will work. +`aws sts get-caller-identity` works on the machine, maproom can resolve +credentials the same way. + +That is an authentication check only. Model access and the +`bedrock:InvokeModel` permission are separate gates — both must also be in +place before an embedding call succeeds (see Prerequisites below). **Prerequisites:** diff --git a/plugins/maproom/skills/maproom-search/references/troubleshooting.md b/plugins/maproom/skills/maproom-search/references/troubleshooting.md index 178a67aa..b2365ccc 100644 --- a/plugins/maproom/skills/maproom-search/references/troubleshooting.md +++ b/plugins/maproom/skills/maproom-search/references/troubleshooting.md @@ -387,7 +387,7 @@ Error: Failed to create embedding service. Ensure OPENAI_API_KEY is set. ```bash export OPENAI_API_KEY="" ``` -4. If set to `bedrock`, no maproom key is needed — verify AWS credentials resolve: +4. If set to `bedrock` (or its aliases `aws` / `aws-bedrock`), no maproom key is needed — verify AWS credentials resolve: ```bash aws sts get-caller-identity ``` @@ -397,7 +397,7 @@ Error: Failed to create embedding service. Ensure OPENAI_API_KEY is set. ### AWS Bedrock: "No AWS credentials found" -``` +```text Error: Failed to create embedding service Caused by: No AWS credentials found for the Bedrock embedding provider. @@ -432,7 +432,7 @@ failed — read that list first, it is the diagnosis. ### AWS Bedrock: "AccessDeniedException" -``` +```text Error: Access denied invoking amazon.titan-embed-text-v2:0 in us-east-1 ``` @@ -461,7 +461,7 @@ open. Authentication succeeding tells you nothing about either. ### AWS Bedrock: model not found in region -``` +```text Error: Model 'cohere.embed-english-v3' was not found in region eu-west-2 ``` @@ -472,11 +472,16 @@ probably correct; the region does not offer it. 1. List the embedding models actually offered where you are: ```bash - aws bedrock list-foundation-models --region "$AWS_REGION" \ + # Resolve the region maproom will use, in its own precedence order. + # Querying $AWS_REGION alone can inspect a different region than the one + # maproom embeds in — which is the confusion this step exists to settle. + region="${MAPROOM_BEDROCK_REGION:-${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region)}}}" + + aws bedrock list-foundation-models --region "${region:-us-east-1}" \ --query "modelSummaries[?outputModalities[0]=='EMBEDDING'].modelId" ``` -2. Either pick an available model, or point only maproom at a region that has - the one you want: +2. Either pick a model that region offers, or point maproom alone at a region + that has the model you want, leaving the rest of your AWS tooling unchanged: ```bash export MAPROOM_BEDROCK_REGION=us-east-1 ``` @@ -507,7 +512,7 @@ up as slowness rather than failure. ### AWS Bedrock: "Cannot infer the embedding dimension" -``` +```text Error: Cannot infer the embedding dimension for Bedrock model 'arn:aws:bedrock:...' ``` @@ -517,7 +522,8 @@ provisioned-throughput ARN or a model released after your maproom build. **Fix:** set the width explicitly. ```bash -export MAPROOM_EMBEDDING_DIMENSION=1024 +# Use the model's own output width. maproom stores only 768, 1024, and 1536. +export MAPROOM_EMBEDDING_DIMENSION=1024 # e.g. Titan v2 or Cohere v3 ``` maproom refuses to guess here deliberately: a wrong dimension produces an index @@ -534,9 +540,17 @@ and, if you route through PrivateLink or an egress proxy, that `MAPROOM_BEDROCK_ENDPOINT_URL` points at it. **Fix:** -1. Check network connectivity to the OpenAI API: +1. Check connectivity to the endpoint for *your* configured provider: ```bash + # OpenAI curl -sf https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" > /dev/null && echo "API reachable" || echo "API unreachable" + + # AWS Bedrock (resolves the region maproom uses) + region="${MAPROOM_BEDROCK_REGION:-${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region)}}}" + curl -sf -o /dev/null "https://bedrock-runtime.${region:-us-east-1}.amazonaws.com" && echo "API reachable" || echo "API unreachable" + + # Ollama (local) + curl -sf http://localhost:11434/api/tags > /dev/null && echo "API reachable" || echo "API unreachable" ``` 2. Retry the vector-search command (max 3 retries with 2-4-8 second exponential backoff): ```bash