docs: clarify stable subpackages + deprecate client-level continuation#31
Merged
Patel230 merged 2 commits intoJun 12, 2026
Merged
Conversation
Two related eyrie doc improvements:
1. **runtime package doc** — the previous text said 'Import eyrie/runtime —
not catalog/setup/config directly', but hawk (and other consumers) actually
import a wider set of subpackages. The stable surface is cooperating
subpackages, not just runtime. List them explicitly so contributors
don't get confused.
hawk imports 8 distinct subpackages of eyrie:
- runtime (bootstrap facade: Load, ChatProvider, etc.)
- client (Provider interface, message/response types)
- catalog (model catalog: pricing, capabilities)
- catalog/registry (ProviderSpec catalog: 16 registered providers)
- catalog/xiaomi (Xiaomi-specific catalog helpers)
- config (provider config + env var resolution)
- credentials (OS keyring + OIDC keyless CI auth)
- setup (CLI/setup wiring, RoutingPreviewJSON)
- storage (conversation DAG persistence, embedded server)
All are part of the public API; changes are gated by semver. Anything
under internal/ is implementation detail and may change without notice.
2. **deprecate StreamChatWithContinuation** — there are now three continuation
mechanisms in the eyrie/hawk ecosystem and the client-level one is the
least attractive:
a. Engine-level (eyrie/conversation) — uses OutputGroupID to collapse
continuation chunks; no synthetic 'Continue.' user turn. Cleanest
conversation shape.
b. Hawk Session loop (hawk/internal/engine/stream.go) — its own
max_tokens recovery (the recoveryCount loop) that only kicks in
for no-tool-call continuations. Also clean.
c. Client-level (this function) — appends 'Continue.' user turn and
emits 'continuation' event markers. Works but pollutes the
conversation with synthetic user messages.
Mark (c) deprecated in favor of (a) and (b). Behaviour unchanged;
will be removed in eyrie v0.3.0.
Patel230
deleted the
docs/clarify-stable-subpackages-and-deprecate-continuation
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two related eyrie doc improvements:
1. runtime package doc
The previous text said 'Import eyrie/runtime — not catalog/setup/config directly', but hawk (and other consumers) actually import a wider set of subpackages. The stable surface is cooperating subpackages, not just runtime. List them explicitly so contributors don't get confused when they try to follow the original (incorrect) guidance.
hawk imports 8 distinct subpackages of eyrie:
All are part of the public API; changes are gated by semver. Anything under internal/ is implementation detail and may change without notice.
2. deprecate StreamChatWithContinuation
There are now three continuation mechanisms in the eyrie/hawk ecosystem and the client-level one is the least attractive:
a. Engine-level (eyrie/conversation) — uses OutputGroupID to collapse continuation chunks; no synthetic 'Continue.' user turn. Cleanest conversation shape.
b. Hawk Session loop (hawk/internal/engine/stream.go) — its own max_tokens recovery (the recoveryCount loop) that only kicks in for no-tool-call continuations. Also clean.
c. Client-level (this function) — appends 'Continue.' user turn and emits 'continuation' event markers. Works but pollutes the conversation with synthetic user messages.
Mark (c) deprecated in favor of (a) and (b). Behaviour unchanged; will be removed in eyrie v0.3.0.
Verification: go build ./... ✓, go test ./client/ ✓