Skip to content

feat(api): add engine-specific extra extension field for smoother adoption#23

Merged
connorcarpenter15 merged 2 commits into
ai-dynamo:mainfrom
tanmayv25:tanmayv-extra
Jul 16, 2026
Merged

feat(api): add engine-specific extra extension field for smoother adoption#23
connorcarpenter15 merged 2 commits into
ai-dynamo:mainfrom
tanmayv25:tanmayv-extra

Conversation

@tanmayv25

Copy link
Copy Markdown
Contributor

Summary

Adds a capability-optional, engine-specific extension field (google.protobuf.Struct extra) to the request and discovery surfaces, plus one field-number hygiene fix. All changes are purely additive — verified wire-compatible against main.

The goal is to lower adoption friction: an engine can expose OpenEngine (and surface a native knob or native discovery metadata) without waiting for the spec to grow a typed field for it. extra is explicitly outside the portable contract — an engine may ignore keys it doesn't recognize, every request stays valid with it empty, and clients never depend on it for correctness. Parameters that prove broadly useful get promoted to typed fields in a later revision.

Changes

Location Field Purpose
GenerateRequest extra = 12 native generation / sampler knobs
TaskRequestContext extra = 4 native embed / classify / score knobs
ServerInfo extra = 12 native server metadata (attention backend, build flags)
ModelInfo extra = 28 native model metadata (kv-cache dtype, quantization)
KvOptions reserved 2; retire the pre-existing tag gap so it can never be silently reused

docs/api.md updated to match, with a prose note documenting the extra policy.

Why these four locations

They are the surfaces where heterogeneous engines diverge — two request roots and two discovery responses. The other open-ended surfaces already have an escape hatch (EngineError.details, KvSessionRef.attributes_struct as Struct; LoadInfo/RuntimeEvent via attributes maps), so no new field was added there. Per-request sub-messages (SamplingParams, *Options) and per-output messages were intentionally left typed to avoid a stringly-typed sprawl.

Compatibility & verification

  • protoc compile: OK
  • buf lint (STANDARD): PASS
  • buf breaking vs main: PASS — no wire-incompatible changes

🤖 Generated with Claude Code

Comment thread proto/openengine/v1/generation.proto Outdated
Comment thread proto/openengine/v1/generation.proto Outdated
Address PR ai-dynamo#23 review: the gap at field 2 was a leftover from a removed
field during development, not a retired tag. Renumber bypass_prefix_cache
(3->2) and cache_salt (4->3) and drop the reserved statement. Safe while
pre-adoption at schema revision 1.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@connorcarpenter15
connorcarpenter15 merged commit 7ca13e2 into ai-dynamo:main Jul 16, 2026
4 of 5 checks passed
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.

2 participants