sleepy_agent_ios/BUILD.md

# Building Sleepy Agent iOS

## Prerequisites

1. **macOS with Apple Silicon (M1/M2/M3/M4)**
2. **Xcode 15 or later** (from App Store)
3. **iOS 15.0+ device** or simulator
4. **CocoaPods** (`sudo gem install cocoapods`)

## Quick Start

### Option 1: Xcode GUI (Easiest)

1. **Open the Swift Package in Xcode:**
   ```bash
   cd sleepy_agent_ios
   open Package.swift
   ```

2. **Xcode will resolve the package** and create a project

3. **Add LiteRT dependency:**
   - File → Add Package Dependencies
   - Search for TensorFlow Lite or LiteRT
   - Or manually download the framework

4. **Configure signing:**
   - Select the project
   - Signing & Capabilities → Team → Select your Apple ID
   - Bundle Identifier: `com.sleepy.agent` (or your own)

5. **Build and run:**
   - Select target device (your iPhone or a simulator)
   - Press Cmd+R

### Option 2: CocoaPods + xcodebuild (Command Line)

1. **Install CocoaPods dependencies:**
   ```bash
   cd sleepy_agent_ios
   pod install
   ```

2. **Open the workspace in Xcode:**
   ```bash
   open SleepyAgent.xcworkspace
   ```

3. **Or build from command line:**
   ```bash
   make build          # Debug build
   make archive        # Release archive
   ```

### Option 3: Create Fresh Xcode Project

If the above doesn't work, create a new project:

```bash
# Make the script executable
chmod +x create-project.sh

# Run the setup script
./create-project.sh
```

Then manually copy the Swift files from `SleepyAgent/` into your new project.

## Creating an .ipa File

### For Development/Debugging:

1. **Archive the app:**
   ```bash
   make archive
   ```

2. **Open the archive in Xcode Organizer:**
   ```bash
   open build/SleepyAgent.xcarchive
   ```

3. **Export as IPA:**
   - In Organizer, select the archive
   - Click "Distribute App"
   - Choose "Development"
   - Follow prompts to export

### For Sideloading (No Developer Account):

Use [AltStore](https://altstore.io) or similar tools to install the .ipa without a paid developer account.

### For Jailbroken Devices:

```bash
# Build and package without signing
make build-release
cd build/Release-iphoneos
mkdir -p Payload/SleepyAgent.app
cp -r SleepyAgent.app/* Payload/SleepyAgent.app/
zip -r SleepyAgent.ipa Payload
```

## Troubleshooting

### "No such module 'TensorFlowLite'"

LiteRT-LM needs to be added manually. Options:

1. **Use CocoaPods:** Edit `Podfile` and add the correct pod
2. **Use Swift Package Manager:** Add TensorFlow Lite as a dependency
3. **Manual framework:** Download from [TensorFlow releases](https://github.com/tensorflow/tensorflow/releases)

### Signing Issues

```bash
# Check available signing identities
security find-identity -v -p codesigning

# For development builds, use automatic signing in Xcode
# For distribution, you need a paid Apple Developer account ($99/year)
```

### "Could not find iOS SDK"

```bash
# Select Xcode command line tools
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

# Accept license
sudo xcodebuild -license accept
```

### Model Download Issues

The app downloads models from HuggingFace. If downloads fail:

1. Manually download from: https://huggingface.co/litert-community
2. Place in: Files app → On My iPhone → Sleepy Agent → models/

## File Structure

```
sleepy_agent_ios/
├── SleepyAgent/                    # Source code
│   ├── App/                        # Entry point
│   ├── Core/                       # Models, DI
│   ├── Inference/                  # LLM engine
│   ├── Services/                   # Audio, network, etc.
│   ├── UI/                         # SwiftUI views
│   ├── Info.plist                  # App config
│   └── SleepyAgent.entitlements    # Capabilities
├── Package.swift                   # Swift Package Manager
├── Podfile                         # CocoaPods config
├── Makefile                        # Build automation
└── BUILD.md                        # This file
```

## Build Commands

```bash
# Setup
make setup          # Install CocoaPods
make check          # Check environment

# Building
make build          # Debug build (simulator)
make build-release  # Release build (device)
make archive        # Create .xcarchive
make ipa            # Create .ipa

# Installation
make install        # Install to connected device

# Cleanup
make clean          # Clean build artifacts
make clean-all      # Full clean including Pods
```

## Debugging on Device

1. Connect iPhone via USB
2. Trust this computer on iPhone
3. In Xcode: Window → Devices and Simulators
4. Select your device
5. Build and run (Cmd+R)

## Notes

- **LiteRT-LM iOS models**: https://huggingface.co/collections/litert-community/ios-models
- **Physical device recommended** - Simulator can't test audio/camera well
- **First launch** - Model loading may take 10-30 seconds depending on size
- **RAM requirements** - E2B needs ~4GB free, E4B needs ~6GB free

## Need Help?

Open an issue at: https://github.com/sleepyeldrazi/sleepy-agent/issues