Skip to content

docs: update README with approved explainer content - #2

Merged
YinguangZhao merged 2 commits into
mainfrom
add-explainer
Aug 12, 2026
Merged

docs: update README with approved explainer content#2
YinguangZhao merged 2 commits into
mainfrom
add-explainer

Conversation

@YinguangZhao

Copy link
Copy Markdown
Collaborator

No description provided.

@tomayac

tomayac commented Aug 11, 2026

Copy link
Copy Markdown

Naming conventions:

  • For example, chunkingStrategy vs. distance_type. In JavaScript, camelCase is the preferred option.

Chunking

  • Developers need a way to know the allowed range for maxChunkSizeTokens.
  • To meaningfully set chunkOverlapTokens, developers need to know more details about the tokenization algorithm.

Syntax

  • The explainer contains many escaped backticks (\` that should be `). This seems to be an export issue from the Google Docs version.

@reillyeon reillyeon left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with Tom's comments addressed.

@michaelwasserman michaelwasserman left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm modulo Tom's comments, and a few more that deserve early consideration

Comment thread README.md

TODO: Fill in the whole explainer template below using https://tag.w3.org/explainers/ as a
reference. Look for [brackets].
This proposal is an early design sketch by the Chrome Built-in AI team to

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: line breaking like this isn't necessary

Comment thread README.md
rather, we are building the structural plumbing required for that inevitable,
commoditized future, and all the upsides and ergonomics it entails.

## Security Considerations

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider (here or followup) adding internationalization considerations, i.e. how might the API need to support content of various languages, and maybe surface supported input languages? (see other built-in AI APIs for examples)

Comment thread README.md Outdated
## Use cases
The **Vector Store API** is a proposed Web Platform API that provides an
end-to-end semantic retrieval system entirely on the user's device. Instead of
requiring developers to manually manage vectors, the API automatically handles

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should explicitly frame the introduction around the end-user benefits first (e.g., privacy, offline capabilities, and performance), and only then mention the ease of authoring. You should be able to use some of the same info from the semantic embedding API explainer. end-users come before authors in the priority of constituencies https://www.w3.org/TR/html-design-principles/#priority-of-constituencies

@YinguangZhao

Copy link
Copy Markdown
Collaborator Author

Thanks for the feedback! Addressed the comments.

@YinguangZhao
YinguangZhao merged commit 7b6ebcd into main Aug 12, 2026
2 checks passed
github-actions Bot added a commit that referenced this pull request Aug 12, 2026
SHA: 7b6ebcd
Reason: push, by YinguangZhao

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants