swift-apple-intelligence-grpc/README.md

# Apple Intelligence gRPC Server

A Swift-based gRPC server that exposes Apple Intelligence (Foundation Models) over the network, allowing any device on your LAN to send prompts and receive streaming AI responses.

## Features

- **gRPC API** - Standard gRPC interface accessible from any language
- **Streaming Support** - Real-time token streaming for responsive UX
- **Menu Bar App** - Native macOS app with system tray integration
- **Built-in Chat UI** - Test the AI directly from the app
- **API Key Auth** - Optional bearer token authentication
- **Auto-Start** - Launch at login and auto-start server options

## Requirements

- macOS 26+ (Tahoe)
- Apple Silicon Mac (M1/M2/M3/M4)
- Apple Intelligence enabled in System Settings
- Swift 6.0+

## Installation

### Download Release

Download the latest `.dmg` from the [Releases](../../releases) page, open it, and drag the app to Applications.

### Build from Source

```bash
# Clone the repository
git clone https://github.com/svrnty/apple-intelligence-grpc.git
cd apple-intelligence-grpc

# Build the menu bar app
swift build -c release --product AppleIntelligenceApp

# Or build the CLI server
swift build -c release --product AppleIntelligenceServer
```

## Usage

### Menu Bar App

1. Launch **Apple Intelligence Server** from Applications
2. Click the brain icon in the menu bar
3. Toggle **Start Server** to begin accepting connections
4. Use **Chat** to test the AI directly
5. Configure host, port, and API key in **Settings**

### CLI Server

```bash
# Run with defaults (0.0.0.0:50051)
.build/release/AppleIntelligenceServer

# Custom configuration via environment
GRPC_HOST=127.0.0.1 GRPC_PORT=8080 API_KEY=secret .build/release/AppleIntelligenceServer
```

## API

### Service Definition

```protobuf
service AppleIntelligence {
  rpc Health(HealthRequest) returns (HealthResponse);
  rpc Complete(CompletionRequest) returns (CompletionResponse);
  rpc StreamComplete(CompletionRequest) returns (stream CompletionChunk);
}
```

### Methods

| Method | Type | Description |
|--------|------|-------------|
| `Health` | Unary | Check server and model availability |
| `Complete` | Unary | Generate complete response |
| `StreamComplete` | Server Streaming | Stream tokens as they're generated |

### Quick Test with grpcurl

```bash
# Health check
grpcurl -plaintext localhost:50051 appleintelligence.AppleIntelligence/Health

# Non-streaming completion
grpcurl -plaintext \
  -d '{"prompt": "What is 2 + 2?"}' \
  localhost:50051 appleintelligence.AppleIntelligence/Complete

# Streaming completion
grpcurl -plaintext \
  -d '{"prompt": "Tell me a short story"}' \
  localhost:50051 appleintelligence.AppleIntelligence/StreamComplete
```

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `GRPC_HOST` | `0.0.0.0` | Host to bind (use `0.0.0.0` for LAN access) |
| `GRPC_PORT` | `50051` | Port to listen on |
| `API_KEY` | *none* | Optional API key for authentication |

## Client Libraries

Connect from any language with gRPC support:

- **Python**: `grpcio`, `grpcio-tools`
- **Node.js**: `@grpc/grpc-js`, `@grpc/proto-loader`
- **Go**: `google.golang.org/grpc`
- **Swift**: `grpc-swift`
- **Rust**: `tonic`

See [docs/grpc-client-guide.md](docs/grpc-client-guide.md) for detailed examples.

## Project Structure

```
apple-intelligence-grpc/
├── Package.swift
├── Sources/
│   ├── AppleIntelligenceCore/       # Shared gRPC service code
│   │   ├── Config.swift
│   │   ├── Services/
│   │   │   └── AppleIntelligenceService.swift
│   │   ├── Providers/
│   │   │   └── AppleIntelligenceProvider.swift
│   │   └── Generated/
│   │       └── AppleIntelligence.pb.swift
│   ├── AppleIntelligenceServer/     # CLI executable
│   │   └── main.swift
│   └── AppleIntelligenceApp/        # Menu bar app
│       ├── App.swift
│       ├── ServerManager.swift
│       ├── Models/
│       ├── Views/
│       └── ViewModels/
├── scripts/
│   ├── build-app.sh                 # Build .app bundle
│   └── create-dmg.sh                # Create DMG installer
└── docs/
    ├── grpc-client-guide.md         # Client connection examples
    ├── macos-runner-setup.md        # CI runner setup
    └── pipeline-configuration.md    # CI/CD configuration
```

## CI/CD

Automated builds are configured with Gitea Actions. When a release is created:

1. Builds the app bundle
2. Signs with Developer ID
3. Notarizes with Apple
4. Uploads DMG to release

See [docs/pipeline-configuration.md](docs/pipeline-configuration.md) for setup instructions.

## Security

- **Local Network**: By default, the server binds to `0.0.0.0` allowing LAN access
- **API Key**: Enable authentication by setting the `API_KEY` environment variable
- **Firewall**: macOS will prompt to allow incoming connections on first run
- **Notarized**: Release builds are signed and notarized by Apple

## Troubleshooting

### Model Not Available

- Ensure Apple Intelligence is enabled: System Settings → Apple Intelligence & Siri
- Requires Apple Silicon Mac with macOS 26+

### Connection Refused

- Check the server is running (brain icon should be filled)
- Verify firewall allows connections on the configured port
- Try `localhost` instead of the IP if testing locally

### Authentication Failed

- Include the API key in the Authorization header: `Bearer YOUR_API_KEY`
- Verify the key matches what's configured in Settings

## License

MIT