Metadata-Version: 2.4
Name: llm-apple
Version: 0.1.2
Summary: LLM plugin for Apple Foundation Models (Apple Intelligence)
Author: Ben Tucker
License: MIT
Project-URL: Homepage, https://github.com/btucker/llm-apple
Project-URL: Issues, https://github.com/btucker/llm-apple/issues
Project-URL: Changelog, https://github.com/btucker/llm-apple/releases
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: llm>=0.15
Requires-Dist: apple-foundation-models>=0.1.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Dynamic: license-file

# llm-apple

LLM plugin for Apple Foundation Models (Apple Intelligence)

This plugin exposes Apple's on-device Foundation Models through the [llm](https://llm.datasette.io/) CLI tool.

## Requirements

- macOS 26 or later
- Apple Intelligence enabled
- Python 3.8 or later
- [apple-foundation-models](https://pypi.org/project/apple-foundation-models/) installed

## Installation

```bash
pip install llm # if llm is not already installed
llm install llm-apple
```

## Usage

Basic usage:

```bash
llm -m apple "What is the capital of France?"
```

With streaming:

```bash
llm -m apple "Tell me a story" --stream
```

With options:

```bash
llm -m apple "Write a poem" -o temperature 1.5 -o max_tokens 500
```

With system instructions:

```bash
llm -m apple "What is Python?" --system "You are a helpful programming tutor"
```

### Conversations

The plugin supports conversations, maintaining context across multiple prompts:

```bash
# Start a conversation
llm -m apple "My name is Alice" --save conversation1

# Continue the conversation
llm -m apple "What is my name?" --continue conversation1
```

### Available Options

- `temperature` (float, 0.0-2.0, default: 1.0): Controls randomness in generation
  - 0.0 = deterministic
  - 2.0 = very random
- `max_tokens` (int, default: 1024): Maximum tokens to generate

System prompts can be provided using llm's built-in `--system` or `-s` flag.

## Availability

The plugin checks Apple Intelligence availability on startup. If Apple Intelligence is not available, you'll see an error message with details on why.

Common reasons:

- Device not eligible (requires Apple Silicon)
- Apple Intelligence not enabled in Settings
- Model not ready (downloading or initializing)

## Examples

Creative writing with higher temperature:

```bash
llm -m apple "Write a creative story about a robot" -o temperature 1.8
```

Factual query with lower temperature:

```bash
llm -m apple "Explain quantum computing" -o temperature 0.3
```

With system prompt for career guidance:

```bash
llm -m apple "Should I learn Python or JavaScript?" \
  --system "You are a career counselor specializing in tech"
```

## Development

### Running Tests

```bash
# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=llm_apple --cov-report=html --cov-report=term
```

The tests use mocks to simulate the Apple Foundation Models API, so they can run on any platform without requiring actual Apple Intelligence hardware.
