Conversation
Agent-Logs-Url: https://github.com/github/gh-aw/sessions/61c14f96-26f7-494c-9f25-6913b59d5e29 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
pelikhan
left a comment
pelikhan
left a comment
There was a problem hiding this comment.
- glob matching must be semver aware (favor latest)
- strict restriction on allowed characters in model identifiers
- cycle in model name resolution are not allowed. Detection at compile and runtime needed.
- document models payload merge strategy.
…ntime cycles, merge pseudocode Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f391ad2d-af81-47e7-aaeb-0e0c01fff0df Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
All four points addressed in commit
|
There was a problem hiding this comment.
Pull request overview
Adds a new formal reference specification document for the Model Alias Format (MAF) used by GitHub Agentic Workflows, including syntax, parameter semantics, alias-map YAML format, resolution/merge algorithms, validation rules, and compliance tests.
Changes:
- Introduces a W3C-style MAF specification document (v1.1.0 draft) covering ABNF grammar, parameter encoding, alias maps, and fallback resolution.
- Defines normative validation rules (V-MAF-xxx) and a compliance test matrix (T-MAF-xxx).
- Documents builtin aliases and a three-layer merge precedence algorithm (builtins → imports → main).
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/model-alias-specification.md | New normative spec for model identifier syntax, alias YAML format, resolution/merge semantics, validation rules, and compliance tests |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 5
| To rank matches, an implementation MUST extract the version string from a catalog entry using the following procedure: | ||
|
|
||
| 1. Take the model-token portion (after the first `/`). | ||
| 2. Scan right-to-left for the last occurrence of a version segment matching the pattern `\d+(\.\d+)*` (one or more dot-separated integers). | ||
| 3. The extracted version string is used for comparison as a semver tuple. | ||
| 4. If no version segment is found, the entry is treated as version `0.0.0` for ranking purposes. |
| i. Strip parameters from E → (eBase, eParams) | ||
| ii. Merge params ← MergeParams(params, eParams) // caller wins | ||
| iii.If eBase is a key in aliasMap → recurse: Resolve(eBase+MarshalParams(eParams), ...) | ||
| iv. If eBase is a glob pattern → match against catalog; if any match, return first match + params | ||
| v. If eBase is a provider-scoped name (no wildcards) → if present in catalog, return eBase + params |
| MergeParams(callerParams, aliasParams): | ||
| result = aliasParams | ||
| for each (key, value) in callerParams: | ||
| result[key] = value // caller overwrites alias | ||
| return result |
| | Parameter key | `[A-Za-z0-9-]` | MUST start with a letter | | ||
| | Parameter value | `[A-Za-z0-9-_.]` | | | ||
|
|
||
| Characters explicitly PROHIBITED in all segments: whitespace, `@`, `!`, `#`, `$`, `%`, `^`, `&` (except as separator), `(`, `)`, `+`, `=`, `[`, `]`, `{`, `}`, `|`, `\`, `:`, `;`, `,`, `<`, `>`, `/` (except as provider/model separator), `?` (except as parameter separator), `"`, `'`. |
| model-token = model-char 0*( model-char / "." model-char ) | ||
| ; segments separated by "."; each segment starts with ALPHA or DIGIT | ||
|
|
||
| model-char = ALPHA / DIGIT / "-" / "_" | ||
| ; the underscore is permitted inside model tokens only | ||
|
|
||
| glob-pattern = provider-token "/" model-glob-token | ||
|
|
||
| model-glob-token = 1*( model-char / "." / "*" ) |
Summary
Introduces a new W3C-style specification for the Model Alias Format (MAF) in GitHub Agentic Workflows (v1.1.0).
What's included
A single new file:
docs/src/content/docs/reference/model-alias-specification.mdKey sections
provider/model, glob patterns, and?key=valuequery strings; explicit allowed-character table and prohibited-character list per segmenteffort(low|medium|high) for reasoning models;temperature(0.0–2.0); reserved names for future paramsmodels:frontmatter key, constraints on circular referencessonnet,haiku,opus,gpt-5, etc. and meta-aliasesmini,large,auto)MergeAliasMappseudocode: builtins → imported workflows (first-wins) → main workflow (always wins)Notable normative requirements
:,@, etc.) must be rejected with a message naming the offending character and segment.MergeAliasMapalgorithm explicitly documents the three-step merge with first-wins import semantics.Related
pkg/workflow/model_aliases.gopkg/parser/schemas/main_workflow_schema.json(models:andengine.modelfields)