aws-analyzer

Understand your AWS data from a SageMaker notebook.

One Python file per AWS service. Drop it next to your notebook and get readable reports on your S3 buckets, DynamoDB tables, Bedrock knowledge bases, OpenSearch vector indexes, Lambda functions and the SageMaker notebook itself: what's there, what it costs, and what to do next. And windows you use by clicking: an explorer that shows how a knowledge base indexed each of its files, and a chat window for asking it, with every setting in reach.

Guides · Get started · S3 · DynamoDB · Bedrock Knowledge Bases · Knowledge base chat · SageMaker · OpenSearch · Lambda · Development · Changelog

_{ui.overview(): every bucket's size, estimated monthly cost and security settings, what's wrong with each, and what to run next.}

Why aws-analyzer

Services

Service	What it shows you	File and guide
Amazon S3	• Every bucket's size, monthly cost and risks • Folder trees, and search by name, size or date • Preview CSV, Parquet, JSON, Excel, PDF, Word and more • Cut storage costs and recover deleted files	s3.py Guide →
S3 file explorer	• Your buckets and folders, one click at a time • What's inside a file, as soon as you click it • Find files by name or type (.csv), in subfolders too • Tick files and download them as one .zip	s3_explorer.py (with s3.py) Guide →
Amazon DynamoDB	• Every table's key, size, billing and cost • Scan, query and get items as plain tables • Which attributes the items hold, and their types • The read units each report used; scans stop early	dynamodb.py Guide →
Amazon Bedrock Knowledge Bases	• Settings in plain English, sync health and failed documents • Search with sources, pages and highlighted passages • Answers with each claim linked to its source • Compare search settings and measure retrieval hit rate	bedrock_kb.py Guide →
Knowledge base explorer	• Every file next to Bedrock's record of it: failed and why, changed, not synced, skipped • How a file was indexed: the parser, each chunk in order, its metadata • Whether a question finds a file, and where it ranks • Syncs as a timeline, search, and every setting, by clicking	bedrock_kb.py Guide →
Bedrock knowledge base chat	• A chat window: pick the knowledge base and the model • Answers stream in, with citations, sources, request and response • Retrieve only: the search behind an answer, every passage ranked • Any RetrieveAndGenerate setting, and the setup as Python, JSON or an AWS CLI command • Test a list of questions, and see which did better after a change	bedrock_chat.py Guide →
Amazon SageMaker	• The notebook you're in: type, cost so far, idle shutdown • Its CPU, memory, disk and GPU use right now • What fills the disk, and what's safe to clear • Everything running and billing in the region, and what looks forgotten	sagemaker_env.py Guide →
Amazon OpenSearch	• Every vector field in plain English: size, engine, similarity • Whether the vector graphs fit in the memory the nodes have • Documents without a vector, and zero or repeated vectors • The nearest neighbours of a question, a vector or a document	opensearch.py Guide →
AWS Lambda	• Every function's runtime, triggers, calls, errors and cost, in one region or all • Runtimes losing support, and functions anyone can call • Errors grouped by cause, from the function's own logs • Memory used and cold starts, and the code in its package	lambda_functions.py Guide →

The guides walk through each service with screenshots: setting up in SageMaker, every command, and ready-made IAM policies. Their source is in docs/.

Get started

1. Install it, or put the file next to your notebook. Pick whichever works where you are:

• Install it with pip, in a notebook cell: %pip install aws-analyzer. That's every service, and only needs boto3; %pip install "aws-analyzer[all]" also installs every optional package (pandas, pyarrow, the PDF and Excel readers, progress bars). Then import from aws_analyzer instead of from the file (step 2).
• Upload it: download analyzers/s3.py and drag it into JupyterLab's file browser, in the same folder as your notebook.
• Fetch it from a cell, if the notebook can reach the internet:

  !curl -sO https://raw.githubusercontent.com/utkarsh5026/aws-analyzer/main/analyzers/s3.py
  

• Copy it from S3, for a notebook with no internet access (VPC-only mode): upload it to a bucket once, then run !aws s3 cp s3://your-bucket/tools/s3.py .
• Or paste the whole file into a notebook cell and run it.

2. Import it and look around. It uses the notebook's IAM execution role, so there's nothing to configure:

from s3 import S3View  # or DynamoDBView from dynamodb, BedrockKBView from bedrock_kb, SageMakerView from sagemaker_env,
                       # OpenSearchView from opensearch, LambdaView from lambda_functions
# installed with pip: from aws_analyzer import S3View (or DynamoDBView, BedrockKBView, SageMakerView, OpenSearchView,
# LambdaView, S3Explorer, KBExplorer, chat)

ui = S3View()          # uses the notebook's IAM role
ui.help()              # every command, grouped by task; ui.help("summary") shows one in full
ui.overview()          # every bucket: size, monthly cost, security warnings
s3 = ui.core           # the analyzer behind the view: returns data instead of a report

NOTE: Only boto3 is required, and SageMaker already has it. pandas, pyarrow and the other packages are optional: a command that needs one that isn't installed says which to install instead of failing.

Installed with pip, every from s3 import ... in this README and the guides becomes from aws_analyzer.s3 import ... (the same for dynamodb, bedrock_kb, bedrock_chat, sagemaker_env, opensearch, lambda_functions and s3_explorer). The Analyzer and View classes, S3Explorer, KBExplorer and chat also come straight from aws_analyzer.

from s3 import S3Analyzer, S3View

ui = S3View(S3Analyzer(profile="dev", region="eu-west-1"))   # another AWS profile or region
ui = S3View(mode="text")          # plain text, e.g. in a terminal or a script
ui = S3View(max_rows=0)           # show every row of long tables (default: 50)
ui = S3View(progress="plain")     # a plain progress line instead of tqdm bars ("off" for none)

How it works

Every file has the same two layers:

Reading a report

Every report has the same shape, so the answer is always in the same place:

1. Title and cards: the few numbers that matter. A card turns amber (or red) when a finding below is about it, such as Encryption: none or Point-in-time recovery: off. In text mode those cards end in (!).
2. Findings: what's wrong or worth knowing, warnings first. Each says why it matters, what it costs when that can be priced, and the next step. When every check passes, the report says so. In S3 reports each finding leads with a bold headline, then the why and the what-to-do as points.
3. Tables of detail. Status cells such as FAILED or PUBLIC are coloured. Long tables scroll under a fixed header, and secondary views (tags, the raw policy JSON) are folded: click to open them. In S3 reports, click a column's header to sort by it (again for the other way), pick a value in a column's filter to see only those rows (a storage class, a region), and untick the columns you don't need under Columns. Long keys keep the file name in view: the folder is shortened from the left, and the whole key shows when you hover over it.
4. Next: two or three commands worth running next, with the arguments filled in from this report, such as get('orders', 'USER#0', 'ORDER#0000') after a scan or chunk(1) after a search.

_{ui.table_info("acme-app"): the point-in-time recovery card is amber because the finding below is about it, and the finding ends in the command that turns it on.}

In the notebook, one click on a command anywhere in a report (documents(status='FAILED'), aws dynamodb update-table ...) or on a code block (a restore call, a lifecycle rule, a sync command) selects all of it, ready to copy. The HTML is plain HTML and CSS, with no JavaScript, so a report still works when the notebook is reopened. ui.help() lists every command grouped by task, with a few to start with; ui.help("summary") shows one command's full description.

Amazon S3

Buckets and the files in them. Every bucket's size, cost and risks, what's in a folder, a look inside the files, and what you could save.

📄 analyzers/s3.py · 📖 S3 guide

_{ui.preview() of a Parquet file: row, column and row-group counts, the first rows and the schema, reading only what it needs.}

Quick start

Install the packages first, in a notebook cell (in a terminal, drop the %). On SageMaker the first line is already installed, so you only need the second one, and only for the file types it lists.

%pip install boto3 pandas pyarrow      # the commands below
# optional: Excel, PDF text and pages, .zst, snappy Avro, progress bars
%pip install openpyxl xlrd pypdf pypdfium2 pillow zstandard python-snappy tqdm
# or, with pip instead of the file: all of the above and s3.py itself
%pip install "aws-analyzer[all]"

from s3 import S3View

ui = S3View()                # uses the notebook's execution role
ui.help()                    # every command, grouped by task
ui.help("summary")           # one command in full

ui.overview()                # every bucket: size, monthly cost, security warnings
ui.bucket_info("my-bucket")
ui.summary("s3://my-bucket/data/")
ui.preview("s3://my-bucket/data/part-0.parquet")
ui.what_if("s3://my-bucket/logs/", move_after=30, to="STANDARD_IA")  # preview a lifecycle rule

TIP: Anywhere a location is expected you can pass s3://bucket/prefix or bucket/prefix. Sizes accept 1024, "10MB", "1.5GB"; times accept a datetime, "2024-05-01", or relative "7d", "12h".

Browse like a file explorer

s3_explorer.py turns a cell into a small file explorer for S3. Folders and files are listed on the left. Click a folder to open it, or click a file to see what's inside it on the right, drawn by the same preview as above: a table's first rows, a PDF's pages, a Word file with its pictures, an archive's contents.

📄 analyzers/s3_explorer.py · 📖 Explorer guide

_{S3Explorer(): from your buckets to a Parquet file's first rows, a Word document, and every model file below a folder, one click at a time.}

It builds on s3.py, so put both files next to your notebook, or paste s3.py into a cell and s3_explorer.py into the next one. Clicking needs ipywidgets, which SageMaker notebooks already have.

from s3_explorer import S3Explorer

S3Explorer()                                   # start from your buckets
S3Explorer("s3://my-bucket/data/")             # or in a folder; S3 console links work too
S3Explorer("s3://my-bucket/data/report.pdf")   # a file's folder, with the file shown

A big folder shows its first 1,000 entries at once and lists the rest in the background, up to 10,000, so the search, the sort and the counts cover the whole folder; the list shows 100 rows a page, with « ‹ › » under it. Past 10,000 entries, Load more from S3 lists the next 10,000, and Look up asks S3 for the names that start with what you typed in the search box. Include subfolders lists 10,000 files below the folder at a time. Files in GLACIER or DEEP_ARCHIVE are marked ❄, and opening one shows the command that restores it. Like s3.py, it only reads: browsing needs s3:ListAllMyBuckets and s3:ListBucket, and opening files s3:GetObject.

from s3 import S3Analyzer
from s3_explorer import S3Explorer, S3Navigator

S3Explorer("s3://my-bucket/", profile="dev")          # another AWS profile (or region=)
S3Explorer(core=S3Analyzer(region="eu-west-1"))       # an S3Analyzer or S3View you already have
S3Explorer(height=720, page_size=200)                 # 720px panes (else they fill the window), 200 rows a page
S3Explorer(zip_max_size="2GB")                        # zip folders up to 2 GB (x.zip_max_files too)
S3Explorer(downloads="~/scratch/s3")                  # where ⬇ Download and the zips save (x.downloads)

x = S3Explorer("s3://my-bucket/")
x.open("s3://my-bucket/raw/"); x.back(); x.up(); x.refresh()   # the toolbar, from code
x.filter(".parquet", subfolders=True)                 # the search box: every Parquet file below this folder
x.filter(kind="folders")                              # only the folders here; x.filter() shows everything again
x.ui.download_zip(x.picked)                           # what's ticked in the list, as one .zip
x.ui.summary(x.location)                              # any S3View report about where you are, in its own cell

nav = S3Navigator()                                   # the same navigation as data, with no UI
folder = nav.open("s3://my-bucket/data/")             # Folder: entries, more, error
nav.more(), nav.back(), nav.up(), nav.lookup("2024-")
nav.below()                                           # everything below the folder, 10,000 files at a time

Commands (S3View)

Grouped the way ui.help() lists them.

Buckets

Explore a folder

Cut cost

Versions and deleted files

Open a file

Download

Downloads go in s3-downloads, a folder next to the notebook, so they don't mix with your notebooks and code. It's made with the first download, with a .gitignore that keeps it out of git and marks it as a folder clean_downloads() may empty. To use another folder, pass downloads=; a path on one download saves that one elsewhere:

ui = S3View(downloads="~/scratch/s3")      # or ui.core.downloads = "~/scratch/s3"
ui.download("s3://my-bucket/data/")        # ~/scratch/s3/data/
ui.downloads()                             # what's there, how much disk it takes
ui.clean_downloads(older_than="7d")        # delete what was downloaded before this week

Reference

s3 = ui.core                                        # or S3Analyzer(region="us-east-1", profile="dev")

summary = s3.summarize("s3://my-bucket/data/")      # PrefixSummary dataclass
summary.by_extension["parquet"].size                # bytes

files = s3.find("s3://my-bucket/data/", extensions=["csv"], modified_after="7d")
df = objects_to_df(files)                           # key, size, last_modified, storage_class, ...

df = s3.read_df("s3://my-bucket/data/big.parquet", nrows=1000, columns=["id", "ts"])
df = s3.read_df("s3://my-bucket/reports/q1.xlsx", sheet_name="Summary")
df = s3.read_df("s3://my-bucket/spark/part-00000", fmt="parquet")   # no extension: say what it is
s3.parquet_info("s3://my-bucket/data/big.parquet")  # rows, row groups, schema (reads only the footer)
s3.list_archive("s3://my-bucket/job/output/model.tar.gz").entries   # files inside, without extracting
details = s3.file_details("s3://my-bucket/docs/", extensions="pdf")   # FileDetailsReport: .files, bytes_read
details.to_df()                                     # one row per file: format, size, summary, pages, title, rows, ...
s3.describe_objects(s3.find("s3://my-bucket/", min_size="1GB"))     # the same, for files you picked
s3.read_avro("s3://my-bucket/events.avro", n=100), s3.read_npy(uri, nrows=10), s3.safetensors_info(uri)
doc = s3.read_document("s3://my-bucket/docs/policy.pdf")   # also .docx / .pptx: doc.text, doc.parts, doc.title
s3.read_pdf(uri, pages=[1, 2]), s3.read_docx(uri).headings, s3.read_pptx(uri).notes
pdf_flow(s3.read_pdf(uri, layout=True))             # [('h1', 'Refunds'), ('p', '...'), ('li', '...'), ...]: the text to read
pages = s3.render_pdf(uri, pages=[1, 2])            # [Picture]: each one shows itself in a notebook; .data is PNG / JPEG
s3.read_docx(uri, pictures=True).pictures           # the pictures in a Word file, in reading order
s3.read_lines("s3://my-bucket/logs/app.log.gz", 50)
s3.read_json(...), s3.read_jsonl(..., n=100), s3.read_text(...), s3.read_bytes(uri, 0, 1023)
with s3.open("s3://my-bucket/data/x.csv.gz") as f: ...   # streaming, decompressed

for obj in s3.iter_objects("s3://my-bucket/"):      # stream a listing without holding it in memory
    ...

reports = s3.bucket_reports(match="sagemaker-*")    # BucketConfig + CloudWatch size per bucket
explain_policy(s3.bucket_policy("my-bucket"), s3.account_id())   # [PolicyStatement], plain English
impact = s3.simulate_lifecycle("s3://my-bucket/logs/", move_after=30, to="STANDARD_IA")
impact.monthly_savings, impact.rule()               # USD per month, the rule as a dict
s3.deleted_files("s3://my-bucket/data/", deleted_after="7d").files   # [DeletedObject]
dupes = s3.find_duplicates("s3://my-bucket/data/")  # DuplicateReport: groups, copies, reclaimable, monthly_cost
dupes.to_df()                                       # one row per file: group, role ('keep' / 'copy'), key, sha256, ...
s3.download_folder("s3://my-bucket/data/", "data")  # FolderDownload; s3.download(uri, path) for one file
plan = s3.plan_zip("s3://my-bucket/data/")          # ZipPlan: files, size, disk / memory free, can_download
s3.download_zip("s3://my-bucket/data/", max_size="1GB").plan.path   # ZipDownload; nothing written if a check fails
s3.list_downloads().entries                         # [LocalDownload]: what's in the downloads folder (s3.downloads_folder())
s3.clean_downloads(older_than="30d").freed          # DownloadsCleanup; dry_run=True deletes nothing

ui = S3View(S3Analyzer(prices={"STANDARD": 0.025, "STANDARD_IA": 0.0138}))

Amazon DynamoDB

Tables and the items in them. Every table's keys, size, billing and cost, the items as plain tables, and what they hold.

📄 analyzers/dynamodb.py · 📖 DynamoDB guide

_{ui.scan() with a where= filter: ten failed orders over 300, found by reading 1,619 items, the read units that took, and why a query would be cheaper.}

Quick start

Install the packages first, in a notebook cell (in a terminal, drop the %). On SageMaker both are already installed.

%pip install boto3    # every command (required)
%pip install pandas   # optional: DataFrames (page.to_df(), profile.to_df(), items_to_df)

Every DynamoDBView command works with boto3 alone; IPython, used for the HTML output, comes with Jupyter.

from dynamodb import DynamoDBView

ui = DynamoDBView()          # uses the notebook's execution role and region
ui.help()                    # every command, grouped by task
ui.help("scan")              # one command in full

ui.tables()                  # every table in the region: key, items, size, est. cost, warnings
ui.table_info("orders")      # indexes and how to query each, capacity, usage, backups, risks
ui.scan("orders")            # the first 20 items as a table...
ui.more()                    # ...and the next 20
ui.schema("orders")          # what the items look like
ui.get("orders", "USER#42", "ORDER#0017")
ui.query("orders", "USER#42", sort=("begins_with", "ORDER#"))

NOTE: Tables are regional: DynamoDBView(DynamoDBAnalyzer(region="eu-west-1")) looks at another region. Items are shown and returned as plain Python, not DynamoDB JSON: numbers are int / float, sets are sets, binary is bytes. Nothing in the file writes to a table.

Commands (DynamoDBView)

Grouped the way ui.help() lists them.

Tables

Look at items

Understand the data

Filters

where= works on scan, query, sample, schema, value_counts, largest and count. It takes a dict, and every condition must match:

For OR and NOT, pass a boto3 condition instead: where=Attr("a").eq(1) | Attr("b").exists(). The sort= argument of query takes a value or one of the same tuples (=, <, <=, >, >=, between, begins_with). Key values are converted to the key's type, so "42" works for a number key.

Reference

ddb = ui.core                                       # or DynamoDBAnalyzer(region="eu-west-1", profile="dev")

page = ddb.scan("orders", n=5000, where={"status": "failed"})   # ItemPage
page.items                                          # list of plain dicts
df = page.to_df()                                   # DataFrame: keys first, nested maps as 'address.city'
page.stats                                          # items read, items returned, read units, seconds
more = ddb.scan("orders", n=5000, where={"status": "failed"}, start_key=page.last_key)

ddb.query("orders", "USER#42", sort=("between", "ORDER#2024-01", "ORDER#2024-12"), descending=True)
ddb.query("orders", "failed", index="by-status").to_df()
ddb.sample("orders", 500).items                     # spread over the key space
ddb.get("orders", "USER#42", "ORDER#0017")          # dict, or None
ddb.sql('SELECT * FROM "orders" WHERE pk = ?', "USER#42").items

profile = ddb.profile("orders", 2000)               # TableProfile (what schema() shows)
profile.attributes["total"].types                   # Counter({'N': 1990, 'S': 10})
profile.to_df()                                     # one row per attribute

ddb.value_counts("orders", "status").counts         # {'paid': Stat(count=..., size=...), ...}
ddb.count("orders", where={"status": "failed"}).matched
ddb.describe("orders")                              # TableInfo: keys, indexes, capacity, TTL, backups, tags
ddb.table_metrics("orders", hours=24)               # consumed units, busiest period, throttle events
ddb.table_reports(match="prod-*")                   # [TableReport]: describe() + usage for every table

for item in ddb.iter_items("orders", limit=None):   # stream a full scan without holding it in memory
    ...

rows = S3Analyzer().read_jsonl("s3://my-bucket/AWSDynamoDB/01234-abcd/data/part.json.gz")   # from s3.py
profile_items([from_dynamo_item(row["Item"]) for row in rows], keys=["pk", "sk"])

Amazon Bedrock Knowledge Bases

Knowledge bases, what they retrieve, and the answers built on them. Settings and sync health, every file and how it was indexed, search with highlighted passages, answers with citations, and retrieval measured on your own questions. The explorer window shows it all by clicking.

📄 analyzers/bedrock_kb.py · 📖 Knowledge Bases guide

_{ui.ask("How long do refunds take?"): the answer with its [1] [2] citations, 77% grounded because its last sentence cites nothing, and the passages behind it.}

Quick start

Install the packages first, in a notebook cell (in a terminal, drop the %). On SageMaker both are already installed.

%pip install boto3    # every command (required)
%pip install pandas   # optional: DataFrames (r.to_df(), a.to_df(), report.to_df())

Every BedrockKBView command works with boto3 alone; IPython, used for the HTML output, comes with Jupyter. Answers are generated through Bedrock itself (RetrieveAndGenerate or Converse), so no model SDK is needed and any Bedrock model you have access to works.

from bedrock_kb import BedrockKBView

ui = BedrockKBView()               # uses the notebook's execution role and region
ui.help()                          # every command, grouped by task
ui.help("ask")                     # one command in full

ui.kbs()                           # every knowledge base: status, store, last sync, warnings
ui.use("support-docs")             # later commands use this one (a name, ID or ARN)
ui.kb_info()                       # settings in plain English, syncs, findings, idle cost
ui.search("how do refunds work?")  # ranked passages, with the question's words highlighted
ui.chunk(2)                        # the full text and metadata of result #2
ui.link(2)                         # a link that opens result #2's file in a new browser tab
ui.ask("How long do refunds take?")      # an answer with [1][2] citations and its sources
ui.follow_up("And for digital goods?")   # same conversation
ui.ask("How long do refunds take?", data_source="faq")   # answered from one data source only

ui.files()                         # every file next to Bedrock's record of it: failed, changed, not synced...
ui.file("refund-policy.pdf")       # how one file was indexed: its parser, chunks in order, metadata, what to fix
ui.search_file("refund-policy.pdf", "How long do refunds take?")   # does the question find it, and where it ranks
ui.explore()                       # all of it in a window, by clicking (below)

NOTE: Knowledge bases are regional: BedrockKBView(BedrockKBAnalyzer(region="us-west-2")) looks at another region. Commands take kb= (a name in any case, the 10-character ID, or the ARN); without it they use the one set by use() or BedrockKBView(kb=...), else the only knowledge base in the region, else they list the ones there and say how to pick. Nothing in the file changes a knowledge base: where a sync is needed, it shows the aws bedrock-agent start-ingestion-job ... command and the boto3 call instead of running them.

Explore by clicking

explore() opens a window on a knowledge base that you use by clicking, with nothing to type but a question. Every file of its S3 data sources is listed next to Bedrock's record of it, so you see at once which ones failed and why, which changed in S3 since they were indexed, which were added after the last sync, which the sync skipped, and which are gone from S3 but still turn up in answers. Click a file to see how it was indexed, step by step: the parser that read it, each chunk in document order with the text it shares with the one before, its metadata file next to what its chunks carry, and what to fix.

_{explore("support-docs"): every file next to Bedrock's record of it, and for warranty.pdf, each step from S3 into the vector store.}

from bedrock_kb import explore             # with pip: from aws_analyzer import KBExplorer

explore()                                  # the only knowledge base here, or the first active one
explore("support-docs")                    # a name, ID or ARN
explore("support-docs", file="faq/returns.md")   # straight to one file's page
explore(region="us-west-2")                # another region (or profile="dev")
explore("support-docs", height=800)        # 800px pages (else the browser's height)
ui.explore()                               # from a BedrockKBView, on its knowledge base

The window needs ipywidgets, which SageMaker already has (elsewhere: %pip install ipywidgets, then reload the browser tab). Without it, or outside Jupyter, it shows the same as reports: files(), file() and search_file().

Everything is read in the background, so a click shows what's known at once and the rest as it arrives, and the window keeps answering. Like the rest of the file it only reads: where a sync would help, it shows the command. explore() returns the window: x.inventory, x.info and x.chunks hold the data behind what's shown, and x.ui is a BedrockKBView for reports in other cells.

Commands (BedrockKBView)

Grouped the way ui.help() lists them.

Explore by clicking

Knowledge bases

What's indexed

Search and answer

Measure retrieval

Two ways to generate answers

With engine="converse", the sources are sent as data, never as instructions, and the model is told to cite them as [n] and to say when they don't hold the answer.

model= takes a model ID or ARN, an inference profile ID, or a short name: "opus", "sonnet", "haiku", "claude-opus-5", "nova-pro". The default is Claude Haiku 4.5 (bedrock_kb.DEFAULT_MODEL), through the region's inference profile when it needs one; BedrockKBAnalyzer(default_model="sonnet") changes it.

One data source (data_source=)

A knowledge base can have several data sources (an S3 bucket of policies, a crawled help site, a Confluence space). data_source= points a question at one of them: search, ask, compare and evaluate take its name (in any case) or its ID, or a list of them, and follow_up() keeps it for the rest of the conversation.

ui.search("refund window", data_source="faq")                 # passages from the faq data source only
ui.ask("How long do refunds take?", data_source="policies")   # an answer from the policies only
ui.follow_up("And on the help site?", data_source="help-site")   # the next question searches another one
ui.follow_up("Anything else?", data_source="all")             # back to every data source

Bedrock tags every chunk with its data source's ID (x-amz-bedrock-kb-data-source-id), so this needs no metadata files, and it combines with where= (both must match). kb_info() lists the data sources, with the data_source= for each. When passages come from several data sources, the reports say which each came from and suggest asking the one most of them came from. If a vector store returns passages from another data source anyway, a finding says so: tag the files with your own metadata then, and filter with where=.

Filters (where=)

where= filters on the documents' own metadata, which comes from a <file>.metadata.json next to each file (for example refund-policy.pdf.metadata.json holding {"metadataAttributes": {"team": "billing", "year": 2024}}). It works on search, ask, compare and evaluate, uses the same vocabulary as the DynamoDB analyzer, and every condition must match:

Values are typed: 2024 and "2024" differ. For OR, pass a Bedrock RetrievalFilter instead, e.g. where={"orAll": [{"equals": {"key": "team", "value": "a"}}, {"equals": {"key": "team", "value": "b"}}]}; it is sent unchanged.

Reference

kb = ui.core                                        # or BedrockKBAnalyzer(region="us-west-2", profile="dev")

info = kb.describe("support-docs")                  # KnowledgeBaseInfo: settings, data sources, last syncs, tags
info.data_sources[0].chunking                       # the chunkingConfiguration AWS returned
kb.list_knowledge_bases()                           # [KnowledgeBaseInfo], described in parallel
kb.ingestion_jobs("support-docs", n=20)             # [IngestionJob], newest first, with failure reasons
docs, summary = kb.documents("support-docs", status="FAILED")   # [KBDocument], DocumentSummary
kb.unsynced("support-docs")                         # [SyncFreshness]: changed S3 files per data source

inv = kb.file_inventory("support-docs")             # FileInventory: every file, KBFile.state and why (KBFile.note)
inv.counts(), inv.to_df()                           # files per state; one row per file
f = "s3://support-docs-bucket/policies/refund-policy.pdf"
chunks = kb.document_chunks("support-docs", f)      # DocumentChunks: its chunks in document order, .stats
kb.metadata_file(f)                                 # MetadataFile: its .metadata.json's attributes and problems
kb.probe_file("support-docs", f, "refund window")   # FileProbe: its passages, and .rank in the whole knowledge base
kb.document_status("support-docs", f, "docs-s3")    # KBDocument: Bedrock's record of one file

r = kb.retrieve("support-docs", "refund window", n=10, where={"team": "billing"})   # Retrieval
r.passages[0].text, r.passages[0].source, r.passages[0].metadata
r = kb.retrieve("support-docs", "refund window", data_source="faq")   # one data source: r.data_sources
kb.data_sources("support-docs")                     # [DataSourceInfo]: ID, name, status
df = r.to_df()                                      # one row per passage

a = kb.ask("support-docs", "How long do refunds take?")          # Answer (RetrieveAndGenerate)
a.text, a.citations, a.sources, a.grounded_share
a = kb.generate("refund window?", r.passages, model="opus", prompt=MY_TEMPLATE)   # Converse on your passages
a = kb.generate("refund window?", ["my own chunk", "another chunk"])             # ...or on plain strings
a.input_tokens, a.output_tokens                     # exact, from Converse

kb.compare("support-docs", "refund window for EU orders").overlap   # SearchComparison
report = kb.evaluate("support-docs", [("refund window?", "refund-policy.pdf")])
report.hit_rate, report.mrr, report.to_df()         # EvalReport
kb.models("claude")                                 # [ModelInfo]: what to pass as model=, and its price

Bedrock knowledge base chat

A chat window on a knowledge base, with every setting in reach. Pick the knowledge base and the model, ask questions, and change what's sent (passages, search type, filter, reranker, temperature, prompt, or any other field of RetrieveAndGenerate) while you watch the request as JSON. Then ask a whole list of test questions with that setup, see how each one did, try every combination of the settings you're unsure of at once and see which setup does best, keep every run in a file that outlasts a restart, and copy the setup as a Python script, JSON or an AWS CLI command.

📄 analyzers/bedrock_chat.py · 📖 Chat guide

_{chat("support-docs", model="sonnet"): a question and a follow-up answered in markdown, each with its citations and sources, and the settings every question sends.}

Quick start

from bedrock_chat import chat              # installed with pip: from aws_analyzer import chat

chat()                                     # pick the knowledge base and the model in the window
chat("support-docs", model="sonnet")       # or start on these: a name, ID or ARN; a model ID or short name
chat("support-docs", data_source="faq")    # ask only one of its data sources (a name or ID)
chat("support-docs", files=["refund-policy.pdf", "faq/returns.md"])   # or only these files
chat("support-docs", retrieve_only=True)   # questions only search: every passage found, no answer
chat("support-docs", height=800)           # an 800px conversation (else the window fills the browser's height)
ui = chat("support-docs", n=8, temperature=0.2, search_type="hybrid", where={"team": "billing"})
ui.ask_all(["How long do refunds take? | refund-policy.pdf", "Can I return a gift?"])   # a test list, each answered
ui.sweep(n=[5, 10], search_type=["SEMANTIC", "HYBRID"])   # every combination on that list, the setups ranked
ui.use_run()                               # switch to the best setup
ui.save_runs()                             # keep every run (and every later one) in kb-test-runs.jsonl
ui.code()                                  # this setup as a Python script, JSON and an AWS CLI command

The window needs ipywidgets, which SageMaker already has (elsewhere: %pip install ipywidgets, then reload the browser tab). Without it, or outside Jupyter, every command below still works as a report.

• The pickers. The fields at the top: the knowledge base, the model (Claude Haiku 4.5 unless you pick another or pass model=) and, when the knowledge base has more than one, the data source questions search ("All data sources" by default), and the files. Click one to open its list, with a search box that finds a line by name, part of an ID (K7QJ finds K7QJ2M4XNA), description or provider; Enter picks the first, and a whole knowledge base ID or ARN works even when it isn't listed. Tick files and the next questions search only them (shown as chips; click one to drop it, or All files). Another data source, file or model keeps the conversation; another knowledge base starts a new one.
• The conversation. Answers appear as they're written, their markdown laid out (lists, bold, tables, code). Each one shades its cited spans and numbers them, lists its sources (click one to read the passage, with its location and metadata), shows its time, grounded share and estimated cost, and folds away the exact request and response. Findings under an answer say which setting to try (Bedrock's "unable to assist" reply, no citations, a guardrail, cut off at max_tokens). Follow-ups keep Bedrock's session; New chat starts over.
• Answer / Retrieve only. The switch beside the question box. Retrieve only sends the same search without the model (Retrieve instead of RetrieveAndGenerate): every passage the question finds, best first, with its score and the start of its text, and no answer. Ask a question both ways to check the search and the answer apart: the search marks the passages the answer to the same question cited (cited [1]), and a finding says when the answer came back "unable to assist" although the search found passages (the answer step, not the search, is what to fix). Switching puts your last question back in the box; the settings for the answer (temperature, prompt...) are dimmed while they aren't sent.
• Settings. Everything sent with every question, one line each, its value explained in a sentence (hover a name for what it does and its path in the request). Change it in place, remove it with ✕, or open + Add a setting to add the common ones with one click, search every field by name, path or what it does (rerank, latency, encrypts) and add it from the list, or browse them all by group: the list comes from the installed boto3's description of the API, so nothing is missing. A value that can't be sent turns red and says why, and warnings catch what Bedrock would refuse (temperature with top_p on a newer Claude model, a guardrail ID without its version, a prompt that drops the citation instructions).
• Request. The exact request the next question sends, as a folding tree with your settings highlighted, as JSON text, or as the boto3 call to paste into your code, both highlighted. Edit JSON takes a hand-edited request back into the settings, after checking it the way boto3 does before sending, and never undoes a setting changed while you were editing without saying so. Response shows what came back.
• Test. Paste a list of questions, one per line, and Run: each is asked with the window's knowledge base, model, data source, files and settings, on its own (never as a follow-up), a few at a time, while the window stays usable (Stop sends no more). Each question gets a line saying how it did (answered, "unable to assist", no citations, partly grounded, failed) with its grounded share, sources and time, and opens to the full answer. Add | refund-policy.pdf after a question to check that the answer cites that file. Cards and findings sum up the run and say which setting to try; change it and Run again, and each line says whether that question did better or worse. Before you run, the estimated cost shows beside the button. On Retrieve only, the list is searched instead.
• Try variations, in the Test tab, asks the list with every combination of the values you type, one setting per line (n = 5, 10, search_type = SEMANTIC, HYBRID, model = haiku, sonnet, reranker = none, cohere, or data_source = all, faq), or add with one click. Run asks each question with every setup before the next one, so Stop leaves them all with the same questions, then ranks the setups: by the expected files cited, then the answers that say something, then the grounded share, the cheaper first when two are as good. Findings say which setup beats yours and by how much, what each setting changed ("search_type=HYBRID did best in each of the 2 groups of setups that differ only in search_type"; "temperature made no difference"), when the lead is small enough to be chance, and which questions no setup could answer. A table shows how each question did with each setup, and Use this setup switches to the one you pick. A sweep estimated over $2 asks for a second click.
• Runs. Every test run, newest first, ranked against the other runs of the same questions: open one in the Test tab, switch to its setup, or compare it with the others side by side. Save writes them to a file (one JSON line per run, with each answer and its sources) and adds every later run as it finishes; Load reads a file back after a kernel restart, or a teammate's.
• Code. The setup as it is now, to run anywhere: a Python script that needs only boto3 and asks your test questions, printing each answer and the files it cites; the config as JSON (the request without the question, which client.retrieve_and_generate(input={"text": question}, **config) or the AWS CLI's --cli-input-json sends); or the AWS CLI command for one question. It follows every change to the knowledge base, model, files and settings.

Commands (BedrockChatView)

chat() returns the view behind the window. Its commands share the window's settings and conversation, and an open window follows them.

Chat

Test a list of questions

Keep and compare test runs

Settings

Knowledge base and model

Settings with short names

chat() and set() take these as keywords. The API's own names (maxTokens, overrideSearchType) and paths work too, and values are forgiving ("0.2", "hybrid", JSON text or a Python dict).

Every other field goes by its path from knowledgeBaseConfiguration, e.g. set("orchestrationConfiguration.inferenceConfig.textInferenceConfig.temperature", 0).

Reference

a = ui.answers[-1]                    # Answer: the conversation's answers (and searches), oldest first
a.text, a.citations, a.sources, a.grounded_share
a.retrieve_only                       # a search: no text, and a.sources is every passage found, with p.score
a.request, a.response                 # exactly what was sent and what came back
a.to_df()                             # one row per cited source
ui.values                             # the settings: {'n': 8, 'temperature': 0.2, ...}

core = ui.core                        # or BedrockChatAnalyzer(region="us-west-2", profile="dev")
params = core.request("support-docs", "refund window?", {"n": 8})        # the request, without sending it
a = core.ask("support-docs", "refund window?", {"n": 8, "temperature": 0.2}, model="sonnet")
a = core.ask("support-docs", "and for EU orders?", session_id=a.session_id)  # a follow-up
a = core.ask("support-docs", "refund window?", data_source="faq")       # one data source: a.data_sources
a = core.ask("support-docs", "refund window?", files=["refund-policy.pdf"])   # only these files: a.files
r = core.retrieve("support-docs", "refund window?", {"n": 8})    # only the search: r.sources, ranked, with scores
core.request("support-docs", "refund window?", retrieve_only=True)      # the Retrieve request, not sent
core.data_sources("support-docs")     # [DataSource]: ID, name, status
core.files("support-docs").documents  # [KBDocument]: s3:// path, status, data source
core.ask("support-docs", "refund window?", stream=True, on_text=show)    # show(text) gets the answer so far
core.schema().fields["temperature"]   # Field: path, type, range, what it does

batch = core.ask_all("support-docs", ["refund window? | refund-policy.pdf", "gift returns?"], {"n": 8},
                     model="sonnet", workers=4)   # Batch: each question asked on its own
batch.items[0].answer, batch.items[0].found, batch.items[0].cost   # its Answer, where the file came up ([n]), USD
batch.failed, batch.cost, batch.to_df()                           # what Bedrock refused, the total, one row each
ui.batches                            # every test run of the view, oldest first; ui.questions: the Test tab's list

from bedrock_chat import sweep_setups   # with pip: from aws_analyzer.bedrock_chat import sweep_setups
setups = sweep_setups({"n": [5, 10], "model": ["haiku", "sonnet"]})   # [{'n': 5, 'model': 'haiku'}, ...]
sweep = core.sweep("support-docs", ["refund window? | refund-policy.pdf"], setups, {"n": 5})   # Sweep: a Batch each
sweep.ranked                          # [(Batch, RunScore)], best first: answered, grounded, hits, MRR, failed, cost
sweep.best, sweep.to_df()             # the best setup's run; one row per setup
ui.sweeps                             # every sweep of the view; ui.log: the file every run is added to

Amazon SageMaker

The notebook you're running in, and everything else SageMaker bills you for. What this notebook is and what it costs, whether it stops when idle, how busy its CPU, memory, disk and GPU are, what fills its disk, and which notebooks, apps and endpoints in the region look forgotten.

📄 analyzers/sagemaker_env.py · 📖 SageMaker guide

_{ui.instance() in a Studio JupyterLab space: about $80 spent so far on a GPU that has sat idle, and nothing will stop the app tonight.}

The file isn't called sagemaker.py, so it doesn't hide the SageMaker Python SDK, which is also imported as sagemaker.

Quick start

Every command works with boto3 alone, so on SageMaker there's nothing to install.

from sagemaker_env import SageMakerView

ui = SageMakerView()             # uses the notebook's execution role and region
ui.help()                        # every command, grouped by task

ui.instance()                    # this notebook: type, cost so far, idle shutdown, CPU / memory / disk / GPU now
ui.disk()                        # what fills the disk, and the caches and trash that are safe to clear
ui.running()                     # everything billing by the hour in the region, and what looks forgotten
ui.instance("old-experiment")    # another notebook instance, or a Studio space by name

NOTE: instance() and disk() read the machine they run on, so run them in the notebook you want to know about: a notebook instance, or a Studio JupyterLab, Code Editor or Studio Classic app. Anywhere else, instance("name") and running() still work. Nothing in the file stops, deletes or changes anything; where that would help, the report shows the command.

Commands (SageMakerView)

Grouped the way ui.help() lists them.

This notebook

Your account

Reference

sm = ui.core                                          # or SageMakerAnalyzer(region="eu-west-1", profile="dev")

report = sm.instance()                                # InstanceReport: .env, .notebook, .machine, .identity
report.notebook.instance_type, report.notebook.idle   # 'ml.g5.2xlarge', 'off'
report.machine.memory_share, report.machine.gpus      # 0.37, [GPUInfo(name='NVIDIA A10G', busy=0.0, ...)]
sm.notebook("old-experiment")                         # NotebookInfo for any notebook instance or Studio space
sm.environment()                                      # Environment: where this code runs, from SageMaker's metadata
sm.machine()                                          # Machine: this machine right now (local reads only)

d = sm.disk("~/SageMaker", limit=None)                # DiskReport: folders, largest files, caches you can clear
d.to_df()                                             # one row per folder

r = sm.running(days=30)                               # RunningReport: .resources, .stopped, .errors
r.to_df()                                             # one row per notebook, app, endpoint and job

Amazon OpenSearch

Vector (k-NN) indexes in OpenSearch Service domains and Serverless collections. Each vector field in plain English, whether its graphs fit in the memory the nodes have, documents without a vector, vectors that repeat or are all zeros, and the documents nearest a question.

📄 analyzers/opensearch.py · 📖 OpenSearch guide

_{ui.index_info("vectors-prod/support-docs"): 27,000 documents vector search can't find, and graphs that need 15.7 GB of memory where the nodes have 12 GB.}

Quick start

Every command works with boto3 alone, so on SageMaker there's nothing to install. No OpenSearch client library is needed either: requests to a domain or collection are signed with the notebook's role by botocore.

from opensearch import OpenSearchView

ui = OpenSearchView()                        # uses the notebook's execution role and region
ui.help()                                    # every command, grouped by task

ui.overview()                                # every domain and Serverless collection: size, cost, warnings
ui.indexes("vectors-prod")                   # its indexes: vector fields, documents without vectors, memory
ui.index_info("vectors-prod/support-docs")   # one vector index in plain English, and the query to copy
ui.use("vectors-prod/support-docs")          # later commands use this index...
ui.sample()                                  # ...a few documents, and how healthy their vectors are
ui.search("how do I get my money back?")     # the documents nearest a question (embedded with Bedrock)
ui.search(like="art-00156")                  # the documents nearest an existing one: no model needed
ui.search(vector=model.encode("refunds"), where={"lang": "en"})   # your own vector, filtered

NOTE: An index is named like a path, "domain/index" or "collection/index"; a collection ID, an ARN or the endpoint URL your code already uses work too, and so does any OpenSearch you run yourself (indexes("https://host:9200"), with OpenSearchAnalyzer(auth=("user", "password")) for a user name and password). The notebook must be able to reach the endpoint: a domain inside a VPC answers only there. Nothing in the file writes: it sends GET requests, and POSTs only to _search and _count, refusing anything else before it's sent.

Commands (OpenSearchView)

Grouped the way ui.help() lists them.

Domains and collections

Indexes

Vectors

Filters (where=)

where= works on search (during the search, with faiss and lucene) and sample. It takes a dict, and every condition must match:

Query DSL passes through unchanged (where={"bool": {...}}). A field the index doesn't have is reported with the closest names, and index_info() lists the fields you can filter on.

Reference

aos = ui.core                                          # or OpenSearchAnalyzer(region="eu-west-1", profile="dev")

ov = aos.overview()                                    # Overview: .domains, .collections, .ocus
report = aos.indexes("vectors-prod")                   # StoreReport: .indexes, .vector_indexes, .health, .knn
info = aos.index("vectors-prod", "support-docs")       # IndexInfo: .vectors, .fields, .with_vector, .settings
info.vector().dimension, info.vector().space           # 1024, 'cosinesimil'

s = aos.sample("vectors-prod", "support-docs", 500)    # Sample: .docs, .checks["embedding"], .to_df()
r = aos.search("vectors-prod", "support-docs", vector=v, k=20, where={"lang": "en"})
r.to_df()                                              # rank, id, score, similarity and the fields
aos.embed("refund policy", model="cohere")             # Embedding: .vector, .tokens, .cost
aos.request("vectors-prod", "support-docs/_search", {"query": {"match": {"text": "refund"}}})   # any read

AWS Lambda

Lambda functions, in one region or all of them. What each function runs and when its runtime loses support, what triggers it and who else can call it, how often it ran, failed and was throttled, what it costs, and why it fails, read from its own logs, with its memory, cold starts and code.

📄 analyzers/lambda_functions.py · 📖 Lambda guide

_{ui.functions(regions="all"): two runtimes AWS no longer patches, $70 a month of provisioned concurrency for a function that never runs two at once, and 3% of calls failing in the last three days, against 0.6% over the month.}

Quick start

Every command works with boto3 alone, so on SageMaker there's nothing to install. The file isn't called lambda.py because lambda is a Python keyword.

from lambda_functions import LambdaView

ui = LambdaView()                            # uses the notebook's execution role and region
ui.help()                                    # every command, grouped by task

ui.functions()                               # every function: runtime, triggers, calls, errors, cost, warnings
ui.functions(regions="all")                  # ...in every region your account has turned on
ui.function_info("orders-etl")               # one function in plain English, and its last 30 days
ui.errors("orders-etl")                      # its errors in the last 24 hours, grouped by cause
ui.logs("orders-etl", search="KeyError")     # the newest lines it logged; request_id= shows one run
ui.performance("orders-etl")                 # run times, memory used, cold starts, and the memory it needs
ui.code("orders-etl")                        # the files in its package, and the handler's source

NOTE: A function is named by its name, "name:alias", its ARN or a link to it in the Lambda console; pass region="eu-west-1" for one in another region. Nothing in the file invokes, changes or deletes a function: where a change would help, the report shows the AWS CLI command to run. Environment variable values never appear in a report, only their names.

Commands (LambdaView)

Grouped the way ui.help() lists them.

Functions

When something goes wrong

Code

Reference

lam = ui.core                                          # or LambdaAnalyzer(region="eu-west-1", profile="dev")

ov = lam.overview(regions="all")                       # Overview: .functions, .metrics, .triggers, .accounts
ov.to_df()                                             # one row per function: settings, calls, errors, cost
detail = lam.describe("orders-etl")                    # FunctionDetail: .function, .triggers, .aliases, .metrics
lam.errors("orders-etl", since="7d").groups            # ErrorGroup: kind, message, count, first, last, request_ids
lam.performance("orders-etl").to_df()                  # one row per run: duration, billed, memory used, cold start
lam.log_events("orders-etl", pattern='"KeyError"').to_df()
lam.code("orders-etl").files                           # CodeFile: path, size, compressed

Development

Issues and pull requests are welcome: CONTRIBUTING.md explains the set-up and the rules the code follows, and SECURITY.md how to report a vulnerability privately. What changed in each release is in CHANGELOG.md.

pip install -r requirements-dev.txt    # pinned versions
python -m pytest                       # every test, no AWS account needed
ruff check .                           # lint
python -m build                        # the PyPI package, in dist/

pip install -r requirements-docs.txt   # the guide site
mkdocs serve                           # preview it at http://127.0.0.1:8000

• Tests run against moto, so no AWS account is needed. moto covers little of Bedrock and none of SageMaker Studio, so the Bedrock Knowledge Bases tests and the SageMaker Studio and running() tests use botocore's Stubber on real clients instead, which also checks every request against the service model. The OpenSearch tests use moto for domains, fake Serverless, CloudWatch and Bedrock clients checked the same way, and tests/fake_opensearch.py, a small in-memory OpenSearch that answers the REST calls (k-NN searches included) and fails the test if anything but a read is sent. The Lambda tests use moto for functions, triggers, CloudWatch and logs, with the few Lambda reads moto lacks (account limits, provisioned concurrency) answered by functions checked against the service model. The SageMaker tests read a fake machine (metadata file, /proc, a home folder) from a temporary folder. The chat window's tests click its ipywidgets in Python, against fake Bedrock clients that check every request, response and stream event against the service model.
• Guides in docs/ are Markdown, built with MkDocs and the Material theme (mkdocs.yml) and published to GitHub Pages by the Docs workflow whenever they change on main; pull requests build them with --strict, so a broken link fails there. docs/index.md is the home page with a card per service, and each service has its own guide (docs/s3.md, docs/dynamodb.md, docs/bedrock_kb.md, docs/bedrock_chat.md, docs/sagemaker_env.md, docs/opensearch.md, docs/lambda_functions.md), and so does the S3 explorer (docs/s3_explorer.md); a new analyzer gets a new guide, a card on the home page and an entry in mkdocs.yml's nav.
• Screenshots are the tool's own output from demo buckets, tables and knowledge bases with synthetic data; .claude/skills/demo/shots.py remakes them (it needs Pillow and a headless Chrome), and .claude/skills/demo/demo.py runs any command against the same kind of data. Bedrock's are served by a simulated Bedrock, since moto has none, and OpenSearch's by simulated clusters. The chat window's and the knowledge base explorer's are taken in a real JupyterLab by .claude/skills/demo/chat_shots.py and .claude/skills/demo/kb_explorer_shots.py (they need jupyterlab and playwright too).
• The PyPI package (pyproject.toml) ships analyzers/*.py unchanged as the modules of the aws_analyzer package; src/aws_analyzer/__init__.py only re-exports the classes and holds __version__. Optional packages are extras: data (pandas, pyarrow), files (Excel, PDF, .zst, snappy), notebook (IPython, ipywidgets, tqdm) and all. A release moves the ## [Unreleased] entries in CHANGELOG.md under the new version, sets __version__ to match (/release in Claude Code does both, see CONTRIBUTING.md), and publishes a GitHub release tagged v<version>: the Release workflow builds it, checks it and uploads it to PyPI with trusted publishing (its comments have the one-time setup).
• CI runs the same checks on Python 3.10 to 3.14 for every pull request and push to main, and also imports each analyzer on its own with only boto3 installed, and builds the package and imports it the same way. The versions in requirements-dev.txt and requirements-docs.txt are pinned; Dependabot opens weekly pull requests to update them and the GitHub Actions the workflows use.

License

Apache License 2.0.

The service icons are from AWS's Architecture Icons, unchanged. AWS and the AWS service names are trademarks of Amazon.com, Inc. or its affiliates; this project isn't made or endorsed by AWS.