Repository navigation
docs(maproom-plugin): document AWS Bedrock as a supported provider - #71
danielbushman wants to merge 3 commits into
Conversation
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
WalkthroughMaproom now documents AWS Bedrock as an embedding provider. The updates cover setup, compatibility, credential resolution, model access, regional availability, dimensions, re-indexing, throttling, and network troubleshooting. The plugin version changes from ChangesAWS Bedrock embedding support
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plugins/maproom/.claude-plugin/plugin.json`:
- Line 3: Update the version field in the plugin metadata from 0.11.0 to the
patch version 0.10.1, since the reviewed changes are documentation-only and add
no new plugin capability.
In `@plugins/maproom/skills/maproom-search/references/embedding-providers.md`:
- Around line 107-109: Treat aws sts get-caller-identity as validating only AWS
credential authentication: in
plugins/maproom/skills/maproom-search/references/embedding-providers.md lines
107-109, replace the claim that Maproom will work with “AWS credential
authentication resolved” and keep profile, region, model access, and
bedrock:InvokeModel checks independent; in
plugins/maproom/skills/maproom-guide/references/error-diagnosis.md lines 80-82,
limit authorization conclusions to runs using the same profile/source and region
as the STS check.
- Around line 121-122: Use only the canonical Bedrock provider value, bedrock,
in the embedding-provider documentation. In
plugins/maproom/skills/maproom-search/references/embedding-providers.md at lines
121-122, remove the note that aws and aws-bedrock also work; in
plugins/maproom/skills/maproom-search/references/troubleshooting.md at lines
390-396, update any corresponding provider guidance to reference only bedrock.
In `@plugins/maproom/skills/maproom-search/references/troubleshooting.md`:
- Line 478: Clarify the region-selection sentence in the troubleshooting copy by
updating the Maproom reference in the relevant line so it reads as pointing
Maproom to a region that offers the model you want. Keep the surrounding
guidance in the same troubleshooting section unchanged, and adjust only the
wording in this sentence.
- Line 400: Update the four new fenced error-output blocks in the
troubleshooting markdown to include explicit language tags, using text or
console on each fence so the MD040 markdownlint check passes. Keep the
surrounding content unchanged and apply the same fix to the other matching fence
locations noted in the comment.
- Around line 514-524: Update the MAPROOM_EMBEDDING_DIMENSION troubleshooting
example to use the unknown Bedrock model’s documented output dimension instead
of assuming 1024, or identify the specific model that requires 1024. Ensure the
surrounding guidance makes clear that the override must match the model’s actual
embedding dimension.
- Around line 526-534: Update the “Network Timeout During Vector Search”
troubleshooting guidance to avoid the provider-specific OpenAI curl check.
Either branch endpoint and credential validation by configured provider,
including Bedrock, Vertex AI, and Ollama, or remove the OpenAI-only command and
retain provider-neutral recovery guidance.
- Around line 473-477: Update the embedding-model diagnostic command and its
example in the troubleshooting guidance to use Maproom’s prioritized Bedrock
region variable, MAPROOM_BEDROCK_REGION, instead of AWS_REGION.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 5b8535f3-d66b-4913-a666-7c35b9502ad0
📒 Files selected for processing (6)
plugins/maproom/.claude-plugin/plugin.jsonplugins/maproom/agents/maproom-researcher.mdplugins/maproom/skills/maproom-guide/references/concept-glossary.mdplugins/maproom/skills/maproom-guide/references/error-diagnosis.mdplugins/maproom/skills/maproom-search/references/embedding-providers.mdplugins/maproom/skills/maproom-search/references/troubleshooting.md
- 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) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plugins/maproom/skills/maproom-search/references/troubleshooting.md`:
- Around line 548-550: Update the AWS Bedrock troubleshooting probe near the
region resolution to honor MAPROOM_BEDROCK_ENDPOINT_URL when configured and test
the endpoint with an AWS-signed Bedrock operation that exercises inference
access, rather than an unsigned root GET. Preserve the existing default regional
endpoint fallback, or explicitly document the command as DNS/TLS-only if a
signed probe cannot be implemented.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: ed30d9d6-86a4-494c-81f8-04d30007616d
📒 Files selected for processing (3)
plugins/maproom/.claude-plugin/plugin.jsonplugins/maproom/skills/maproom-search/references/embedding-providers.mdplugins/maproom/skills/maproom-search/references/troubleshooting.md
🚧 Files skipped from review as they are similar to previous changes (1)
- plugins/maproom/skills/maproom-search/references/embedding-providers.md
| # 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" |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== file excerpt =="
if [ -f plugins/maproom/skills/maproom-search/references/troubleshooting.md ]; then
wc -l plugins/maproom/skills/maproom-search/references/troubleshooting.md
sed -n '520,565p' plugins/maproom/skills/maproom-search/references/troubleshooting.md | cat -n
else
echo "missing file"
fi
echo "== search Bedrock endpoint/env usages =="
rg -n "MAPROOM_BEDROCK|BEDROCK_ENDPOINT|BEDROCK_REGION|bedrock-runtime|InvokeModel" plugins/maproom -S || true
echo "== relevant markdown frontmatter/header context =="
sed -n '1,80p' plugins/maproom/skills/maproom-search/references/troubleshooting.md | cat -nRepository: manifoldlogic/claude-code-plugins
Length of output: 9851
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== maproom source files mentioning endpoint region region resolution =="
rg -n "MAPROOM_BEDROCK_ENDPOINT_URL|MAPROOM_BEDROCK_REGION|AWS_REGION|AWS_DEFAULT_REGION|bedrock-runtime|MAPROOM_BEDROCK_USE_FIPS" -S plugins/maproom --glob '*.ts' --glob '*.js' --glob '*.mjs' --glob '*.cjs' || true
echo "== maproom source files mentioning InvokeModel =="
rg -n "InvokeModel|invokeModel|bedrock:InvokeModel|Authorization: Bearer|maproom" -S \
plugins/maproom/agents plugins/maproom/commands plugins/maproom/skills \
--glob '*.md' --glob '*.ts' --glob '*.js' --glob '*.mjs' --glob '*.cjs' | head -n 200Repository: manifoldlogic/claude-code-plugins
Length of output: 28327
🌐 Web query:
AWS Bedrock runtime endpoint InvokeModel bedrock-runtime.region.amazonaws.com documentation
💡 Result:
The endpoint bedrock-runtime.{region}.amazonaws.com is the standard, region-specific service endpoint used for making inference requests to Amazon Bedrock [1]. It is specifically designed to handle runtime operations, including the InvokeModel API [1]. Key technical details regarding this endpoint include: 1. Primary Purpose: This endpoint supports various model inference APIs, most notably InvokeModel, Converse, and their streaming variants [1][2]. It is distinct from the control-plane bedrock service endpoints used for resource management [1][3]. 2. Usage: When using AWS SDKs (like Boto3) or the AWS CLI, this endpoint is used to route traffic for inference tasks [4][5]. In a standard configuration, the SDK automatically resolves to bedrock-runtime.{region}.amazonaws.com [3]. 3. VPC Interface Endpoints: When configuring VPC interface endpoints for private connectivity, you can use com.amazonaws.{region}.bedrock-runtime [3]. If private DNS is disabled for your VPC endpoint, you must explicitly set your client's endpoint_url to the specific VPC endpoint DNS (e.g., https://{vpce-id}.bedrock-runtime.{region}.vpce.amazonaws.com) to ensure requests are routed correctly [3]. 4. API Support: In addition to InvokeModel, the bedrock-runtime endpoint supports the full suite of runtime operations such as ApplyGuardrail, Converse, ConverseStream, and various asynchronous invocation methods [2]. For detailed implementation, the official documentation for the InvokeModel API provides the request syntax, including required headers and parameters like modelId and contentType [6][4].
Citations:
- 1: https://docs.aws.amazon.com/bedrock/latest/userguide/endpoints.html
- 2: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock_Runtime.html
- 3: https://docs.aws.amazon.com/bedrock/latest/userguide/vpc-interface-endpoints.html
- 4: https://docs.aws.amazon.com/boto3/latest/reference/services/bedrock-runtime/client/invoke_model.html
- 5: https://docs.aws.amazon.com/cli/latest/reference/bedrock-runtime/invoke-model.html
- 6: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html
Probe the configured Bedrock endpoint with an AWS-signed operation.
The command ignores MAPROOM_BEDROCK_ENDPOINT_URL, so VPC/proxy endpoints documented above can report API unreachable. The unsigned root GET also does not test bedrock-runtime inference traffic and can miss bedrock:InvokeModel/private-endpoint issues. Use the configured/fixed endpoint and a signed probe, or document this branch as DNS/TLS-only.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plugins/maproom/skills/maproom-search/references/troubleshooting.md` around
lines 548 - 550, Update the AWS Bedrock troubleshooting probe near the region
resolution to honor MAPROOM_BEDROCK_ENDPOINT_URL when configured and test the
endpoint with an AWS-signed Bedrock operation that exercises inference access,
rather than an unsigned root GET. Preserve the existing default regional
endpoint fallback, or explicitly document the command as DNS/TLS-only if a
signed probe cannot be implemented.
1 participant
Companion to manifoldlogic/crewchief#79, which adds AWS Bedrock as an embedding provider to maproom. This brings the plugin's guidance in line so the skills and the researcher agent diagnose Bedrock setups correctly instead of assuming Google/OpenAI/Ollama.
Changes
skills/maproom-search/references/embedding-providers.mdInvokeModelembeds one document per call for Titan, so a 50k-chunk scan is 50k requests versus ~520 with Cohereskills/maproom-search/references/troubleshooting.mdAccessDeniedException, model-not-in-region, and throttlingskills/maproom-guide/references/error-diagnosis.mdaws sts get-caller-identitypassing while maproom fails means IAM or model access, not credentialsskills/maproom-guide/references/concept-glossary.mdmxbai-embed-largeare both 1024-dimensional but occupy unrelated spaces — re-index on any provider change even when the dimension is unchanged.agents/maproom-researcher.mdVersion: 0.10.0 → 0.11.0
Verification
scripts/verify-docs.sh— 11/11 checks pass.Note the plugin's
compare-cli-flags.shcould not run here (its baseline file under_SPECSis not present in this environment), andhooks/pytest could not run (pytest not installed). Neither is affected by these changes, which are documentation only.🤖 Generated with Claude Code
Summary by CodeRabbit