Upgrading from v0.27 to v0.28.0
This page lists every change in v0.28.0 that can affect code or a deploy that worked on v0.27.20. Each entry is one bullet: what changed, the old code, and the new code.
- Loud changes stop the build. The error names the change and ends with a
link to its entry here, for example
See docs/migration/v0.28.md#new-stdlib-names. - Loud at run time changes compile, but the program or the CLI stops with an error that names the change.
- Silent changes compile, but the program behaves differently.
The full story of each change is in CHANGELOG.md under v0.28.0.
Loud (fails to compile, the error shows the fix)
New stdlib names
- A bare name that two
exposing (..)imports now both export is[E1012]ambiguous.Std.Ai.ProvidergainsOptions,defaultOptionsandembed.Std.Watchalready hasOptionsanddefaultOptions, andStd.Htmlhasembed. Soimport Std.Html exposing (..)+import Std.Ai.Provider exposing (..)+ a bareembed "…"->Html.embed "…", orimport Std.Html exposing (embed). The error names both modules. The names that collide with an older export:Options(type and record constructor),defaultOptions,embed. Std.Ai.Trainis new in v0.28.0, so none of its names (lora,withQuantBits,withMemoryCap,withSequenceLength,withBatch,withRank, …) breaks code that compiled on v0.27.20. A top-level definition of your own with one of these names keeps working; a bare use that twoexposing (..)imports both export is[E1012], fixed by qualifying it (Train.withRank).- The typed-tool and structured-answer names are new too:
Std.CodecgainsJsonSchemaandjsonSchema;Std.Ai.ProvidergainsToolSchema,ToolRequest,ResponseFormat,ResponseShape,Structured,responseShape,responseFormat,shapeCodec,decodeStructured,chatStructured,chatToolRequest,measureToolRequest,customToolRequest;Std.Ai.Toolgainstyped,parameters,checkArguments;Std.Ai.AgentgainsstructuredToolLoop,structuredToolLoopWith. None of them collides with another stdlib export. A top-level definition of your own with one of these names keeps working; a bare use that twoexposing (..)imports both export is[E1012], fixed by qualifying it.
A new ErrorDetails variant
Sky.Core.Error.ErrorDetailsgainsDomain DomainFailure, the failures of a stdlib domain (Std.Aifirst) or of your app. AcaseoverErrorDetailswith one arm per variant and no_ ->is refused with[E3001], and the diagnostic links here.case d of FfiPanic p -> … ; TypeMismatch t -> … ; HttpStatus n -> … ; JsonDecode s -> … ; Custom s -> …-> add_ -> …, or use the generic helpersError.domain,Error.isRetryableandError.retryAfter, or a domain's typed view (Std.Ai.Failure.fromError).Domainis the last variant the core type needs: a later domain adds codes, not variants, so a_ ->branch written now keeps compiling.docs/errors/error-system.md#domain-failures.
Loud at run time (compiles, then stops with an error)
- A bad AI variable now stops the start. An app that started with an AI variable that did not parse (
SKY_AI_CHAT_MAX_INFLIGHT=lots,SKY_AI_FETCH=maybe) used to run with the default. It now refuses to start withInvalidSetting, naming the variable and the form it expects (never its value). Fix or unset the variable:SKY_AI_CHAT_MAX_INFLIGHT=lots->SKY_AI_CHAT_MAX_INFLIGHT=4. Trace.totalCostfails on a run priced in two currencies. It used to add the amounts. It now returns an error.Trace.totalCost db run->Trace.runSummary db runfor the total per currency.sky ai promotecompares against the alias's version. A version whose attached report regresses against the report of the same suite on the version the alias serves is refused withGateFailed(exit 1). It used to be promoted when its own report cleared the thresholds. Evaluate the candidate against the alias first (sky ai eval <suite> --candidate <model>@v<n> --against <alias>), or force it with a reason.
Silent (compiles, behaves differently)
Error.isRetryablefollows a domain failure's own flag. For an error that carries aDomainfailure, the domain decides, not the kind. Every Std.Ai failure carries one:EngineCrashed,EngineFailed,NoAcceleratorandToolchainFailedareUnavailableand now NOT retryable (on v0.28 part A, as plainUnavailableerrors, they were), because the engine's supervisor restarts a crashed engine and a crash loop must not be retried blindly.Unreachable,Overloaded,TimedOutand a remote 5xx stay retryable. Errors without a domain failure keep the kind rule (Timeout,Network,Unavailable). UseError.retryAfterfor the delay an overloaded server named.- An older peer reads a domain failure as no details. A v0.27 binary (or a v0.28 binary that predates part B) that decodes an
ErrorwithCodec.error(the Sky.Spa RPC wire, a stored snapshot) keeps its kind and message and reads its details asNothing. Deploy the backend and the frontend of a Sky.Spa app from the same build, as usual. - Std.Ai failures carry typed details. The message of every AI failure is unchanged (
Std.Ai Overloaded: …) and its kind is the same, except the HTTP status table of a remote refusal, which is unchanged too.info.detailsis nowJust (Domain …)where it wasNothing; code that matchedNothingthere to mean "an AI failure" must match the domain instead (Error.domain err == Just "ai"). Provider.chatisProvider.chatWith Provider.defaultOptionsand sends the same request as before.- Typed tools are opt-in; existing tools send the same request.
Tool.tool,Provider.ToolSpec,Provider.chatTools,Provider.customToolsandAgent.nativeToolLoopkeep their types and send the permissive"parameters": {"type": "object"}as before. To give a tool typed arguments:Tool.tool "forecast" "…" (\args -> …parse args…)->Tool.typed "forecast" "…" (Codec.auto { city = "", days = 0 }) (\a -> …a.city…). A shaped answer:Provider.chatWith opts p msgs |> …parse r.content…->Provider.chatStructured (Provider.responseShape "reply" codec) opts p msgs |> Task.map .value. - The prompt-based tool loop passes an object
argson.Agent.toolLoopran a tool with""when the model wrote"args": {…}instead of a string; it now passes the object's JSON text. An executor that treated""as "no input" sees the JSON instead.
Training (Std.Ai.Train, new in v0.28.0)
Nothing here breaks a v0.27.20 program: training is new. These notes are for operators and for anyone who ran a pre-release build of the v0.28 branch.
- New variables.
SKY_AI_TRAIN_BACKEND,SKY_AI_TRAIN_SEQUENCE_LENGTH,SKY_AI_TRAIN_BATCH,SKY_AI_TRAIN_RANK,SKY_AI_TRAIN_QUANT_BITS,SKY_AI_TRAIN_MEMORY_CAPandSKY_AI_TRAINER_BIN(under a project prefix,<PREFIX>_AI_…). A value that does not parse fails loudly withInvalidSettingnaming the variable, never silently. sky ai provision --train mlxinstalls the native trainer, a pinnedsky-trainerbundle, and no Python.--train fakeinstalls nothing: the Fake trainer is built into the runtime. Only--train unslothinstalls a managed Python.- Pre-release builds only: clean the AI home. A branch build before the
native trainer installed a Python toolchain for Mlx and Fake. Nothing reads
it now. Delete
toolchains/mlx/andtoolchains/fake/under the AI home (SKY_AI_HOME, else$SKY_HOME/ai, else~/Library/Caches/sky/aion macOS and~/.cache/sky/aion Linux), and alsotools/uv/andpython/unless the host trains with Unsloth:rm -rf "$SKY_AI_HOME/toolchains/mlx" "$SKY_AI_HOME/toolchains/fake". - Pre-release builds only: an old run does not resume. A run that a
Python Mlx driver started cannot resume under the native trainer (its
checkpoints hold that driver's optimiser state and tensor names). Start it again:
sky ai train cancel <run>, then train again; the new run has a new id.