Add project README
Comprehensive documentation covering features, installation, API usage, configuration, project structure, CI/CD, and troubleshooting. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Mathias Beaulieu-Duncan
parent
b8854e4e12
commit
62ab635aec
187
README.md
Normal file
187
README.md
Normal file
@ -0,0 +1,187 @@
|
||||
# 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
|
||||
Loading…
Reference in New Issue
Block a user