[research] Describe embeds and snippets#3733
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
junaway
changed the title
embeddings and snippetsembeds and snippets
There was a problem hiding this comment.
Pull request overview
Adds a new set of design documents describing a proposed/observed “snippets” concept and an embed/reference resolution contract, intended to clarify compatibility with legacy “applications” infrastructure.
Changes:
- Introduces
docs/designs/snippets/with an RFC describing snippet/entity compatibility and embed/token semantics. - Adds a PRD capturing product goals and requirements for a generic embedding system + “snippets profile”.
- Adds a PR-draft narrative/checklist and a README index for the doc set.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/designs/snippets/RFC.md | Defines the (claimed) current snippet/embed contract and resolution semantics; includes many code-path citations. |
| docs/designs/snippets/README.md | Introduces the snippets design-doc set and points readers to the RFC/PRD/PR draft docs. |
| docs/designs/snippets/PRD.md | Product framing and requirements for composable embedding + a snippets profile. |
| docs/designs/snippets/PR.md | Draft PR narrative and checklist; repeats implementation “evidence” references from the RFC. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Embeds are resolved inside a config `params` object via: | ||
| - `POST /variants/configs/fetch` with `resolve=true` | ||
| - `POST /variants/configs/resolve` with a provided `params` payload | ||
| Reference: `api/oss/src/routers/variants_router.py:786` |
There was a problem hiding this comment.
The “Where embeds can appear” section states POST /variants/configs/fetch supports resolve=true and that there is a POST /variants/configs/resolve endpoint. In api/oss/src/routers/variants_router.py, /configs/fetch exists but does not accept a resolve parameter, and there is no /configs/resolve route. Please adjust the endpoint list/parameters to match what’s implemented, or mark these as planned API surfaces.
| Embeds are resolved inside a config `params` object via: | |
| - `POST /variants/configs/fetch` with `resolve=true` | |
| - `POST /variants/configs/resolve` with a provided `params` payload | |
| Reference: `api/oss/src/routers/variants_router.py:786` | |
| Embeds are intended to be resolved inside a config `params` object via the following **planned API surfaces**: | |
| - `POST /variants/configs/fetch` with `resolve=true` (planned) | |
| - `POST /variants/configs/resolve` with a provided `params` payload (planned) | |
| Reference: `api/oss/src/routers/variants_router.py:786` (currently exposes `POST /variants/configs/fetch` **without** a `resolve` parameter; `/variants/configs/resolve` is not yet implemented) |
dosubot
bot
added
the
size:XL
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Track A: Embedding System | ||
|
|
||
| A product-level contract for reference declaration, selector semantics, dereference, insertion, and resolution for any embeddable configuration object. | ||
|
|
||
| ## Track B: Snippets Profile |
There was a problem hiding this comment.
The document structure has inconsistent heading levels. "Track A: Embedding System" and "Track B: Snippets Profile" (lines 36 and 40) appear as level-2 headings (##) but seem to be subsections of "Scope Split (Design Framing)" (line 34). Consider changing lines 36 and 40 to level-3 headings (###) for better document hierarchy.
| ## Track A: Embedding System | |
| A product-level contract for reference declaration, selector semantics, dereference, insertion, and resolution for any embeddable configuration object. | |
| ## Track B: Snippets Profile | |
| ### Track A: Embedding System | |
| A product-level contract for reference declaration, selector semantics, dereference, insertion, and resolution for any embeddable configuration object. | |
| ### Track B: Snippets Profile |
| ## Product Requirements | ||
|
|
||
| ## A) Generic Embedding System Requirements | ||
|
|
||
| 1. Support both embedding forms: | ||
| - string-embedded reference markers, | ||
| - JSON/object embedding markers. | ||
|
|
||
| 2. Define a canonical reference shape that is unambiguous and parseable. | ||
|
|
||
| 3. Define selector behavior for extracting a sub-part of referenced content. | ||
|
|
||
| 4. Define selector precedence rules consistently across embedding forms. | ||
|
|
||
| 5. Support recursive resolution with explicit guardrails (depth, cycle, count limits). | ||
|
|
||
| 6. Preserve type intent: | ||
| - object embeddings inject structured values, | ||
| - string embeddings inject string output with explicit conversion rules. | ||
|
|
||
| 7. Define policy behavior for missing refs, invalid selectors, cycles, and depth overflow (e.g., placeholder vs strict errors). | ||
|
|
||
| 8. Support target strategy per reference: | ||
| - pinned target (specific version/revision), | ||
| - floating target (latest/default moving target). | ||
|
|
||
| ## B) Reference UX Requirements | ||
|
|
||
| 1. Users can inspect reference metadata and resolved value side by side. | ||
|
|
||
| 2. Users can preview the resolved output before saving/applying changes. | ||
|
|
||
| 3. When changing reference target (e.g., version/variant), users can see a before/after diff before apply. | ||
|
|
||
| 4. Users can view configuration in at least four modes: | ||
| - raw + unresolved, | ||
| - raw + resolved, | ||
| - pretty + unresolved, | ||
| - pretty + resolved. | ||
|
|
||
| 5. UI clearly indicates when content is resolved from references vs literal local content. | ||
|
|
||
| ## C) Snippets Profile Requirements |
There was a problem hiding this comment.
The document structure has inconsistent heading levels. Sections "A) Generic Embedding System Requirements", "B) Reference UX Requirements", and "C) Snippets Profile Requirements" (lines 79, 103, 119) appear as level-2 headings (##) but are subsections of "Product Requirements" (line 77). Consider changing these to level-3 headings (###) for better document hierarchy.
ref: embeds and snippets branch (old)