Skip to main content

Migration (0.4.x to 0.5.x)

Key breaking changes from 0.4.x to 0.5.x:

1. ChatSession API shape changed​

Removed helper APIs:

  • session.chat(...)
  • session.chatText(...)

Use streaming create(...) with content parts instead:

// Before
await for (final token in session.chat('Hello')) {
  print(token);
}

// After
await for (final chunk in session.create([LlamaTextContent('Hello')])) {
  final text = chunk.choices.first.delta.content;
  if (text != null) {
    print(text);
  }
}

2. LlamaChatMessage constructor renames​

  • LlamaChatMessage.text(...) -> LlamaChatMessage.fromText(...)
  • LlamaChatMessage.multimodal(...) -> LlamaChatMessage.withContent(...)
// Before
LlamaChatMessage.text(role: LlamaChatRole.user, content: 'Hi');

// After
LlamaChatMessage.fromText(role: LlamaChatRole.user, text: 'Hi');

3. Logging moved out of ModelParams​

ModelParams(logLevel: ...) was removed. Use engine-level logging controls:

  • await engine.setDartLogLevel(...)
  • await engine.setNativeLogLevel(...)
  • or await engine.setLogLevel(...)
await engine.setNativeLogLevel(LlamaLogLevel.info);
await engine.loadModel('model.gguf');

4. Model reload now requires explicit unload​

loadModel(...) throws if a model is already loaded.

await engine.unloadModel();
await engine.loadModel('another-model.gguf');

5. Public exports were tightened​

Package-root exports removed several internals, including:

  • ToolRegistry
  • LlamaTokenizer
  • ChatTemplateProcessor

Prefer the supported surfaces:

  • LlamaEngine
  • ChatSession
  • template APIs and tool definitions in package:llamadart/llamadart.dart

6. Custom backend implementations need updates​

If you maintain a custom LlamaBackend implementation, align with the updated interface:

  • Add getVramInfo().
  • Update applyChatTemplate(...) to the current signature/return contract.

7. Template routing parity changes​

Template render/parse behavior moved to strict llama.cpp parity:

  • customTemplate remains supported for per-call template overrides.
  • Legacy per-call routing fields were removed (customHandlerId, handlerId).
  • Render/parse no longer silently downgrade to content-only fallback when handler/parser execution fails; failures are surfaced to callers.

Quick checklist​

  1. Replace old ChatSession helper calls with create(...).
  2. Rename LlamaChatMessage constructors.
  3. Remove ModelParams.logLevel usage.
  4. Audit imports for removed root exports.
  5. Re-run template/tool-calling flows after migration.

Canonical reference​