From 62ab635aec45653aea6153183503dd8c9a4ad0df Mon Sep 17 00:00:00 2001 From: Mathias Beaulieu-Duncan Date: Tue, 30 Dec 2025 04:42:35 -0500 Subject: [PATCH] Add project README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8a385f3 --- /dev/null +++ b/README.md @@ -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