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#

• MIGRATION.md