apple-intelligence-models 0.2.0

AIMX: safe Rust bindings for Apple's on-device Apple Intelligence language models
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

# Contributing

Thanks for helping improve AIMX (`apple-intelligence-models`, imported as `aimx`).

This crate is a safe Rust wrapper around Apple's FoundationModels framework. The
project accepts changes that keep the Rust API explicit, typed, documented, and
safe when the Swift bridge is unavailable.

## Development Setup

Required for normal library development:

- Rust 1.85 or newer
- `cargo`

Required for live FoundationModels integration tests:

- macOS 26 or newer
- Apple Silicon
- Apple Intelligence enabled
- Xcode with the macOS 26 SDK

The crate must still compile on hosts that cannot build the Swift bridge. In
that case, public model APIs should return `Error::Unavailable`.

## Quality Gates

Run these before opening a pull request:

```sh
cargo fmt
cargo test
cargo test --examples
cargo clippy --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
cargo publish --dry-run
```

Live model tests are ignored by default. Run them on compatible Apple hardware:

```sh
cargo test -- --include-ignored
```

## API Guidelines

- Use typed boundaries instead of raw primitives when values cross FFI,
  generation, or tool-call boundaries.
- Keep public fallible APIs documented with `# Errors`.
- Keep unsafe code private to the FFI layer.
- Preserve the unsupported-host behavior: compile successfully and return
  `Error::Unavailable` at runtime.
- Do not add TODOs, stubbed implementations, or stringly typed error surfaces.
- Do not use `panic!`, `unwrap`, or `expect` in production code. Return typed
  errors through `thiserror` instead.

## Documentation Guidelines

Follow [references/documentation-style.md](references/documentation-style.md)
for README, tutorial, reference, and rustdoc changes.

In short:

- Start with the smallest correct example.
- Explain the single idea the example teaches.
- Name the type or invariant that makes the example safe.
- Document recoverable errors instead of implying success is guaranteed.
- Prefer AIMX-first names such as `AppleIntelligenceModels`,
  `LanguageModelSession`, `GenerationSchema`, `respond_to`, and
  `stream_response`.

## Release Checklist

1. Update `version` in `Cargo.toml`.
2. Update `CHANGELOG.md`.
3. Run all quality gates.
4. Run `cargo package --list` and confirm only intended files are included.
5. Run `cargo publish --dry-run`.
6. Publish with `cargo publish` from a clean working tree.