feat(intelligence) Add Swift Docs

.github/workflows/intelligence-docs.yml

@@ -23,20 +23,28 @@ env:
 
 jobs:
   build_and_deploy:
-    runs-on: ubuntu-22.04
+    runs-on: macos-14
     name: Build and deploy
     steps:
       - uses: actions/checkout@v4
       - name: Bootstrap
         uses: ./.github/actions/bootstrap
       - name: Install pandoc
-        run: sudo apt install pandoc
+        run: brew install pandoc
       - name: Install Flower dependencies (mandatory only)
         run: python -m poetry install --extras "simulation"
+      - uses: swift-actions/setup-swift@v2
+        with:
+          swift-version: "6.0.0"
+      - uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: "16.2"
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
           node-version: '22.14.0'
+      - name: Install SourceDocs
+        run: brew install sourcedocs
       - name: Install pnpm
         run: |
           npm install -g pnpm

.github/workflows/intelligence-swift.yml

@@ -0,0 +1,55 @@
+name: Intelligence Swift
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'intelligence/swift/**/*'
+      - '.github/workflows/intelligence-swift.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'intelligence/swift/**/*'
+      - '.github/workflows/intelligence-swift.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref == 'refs/heads/main' && github.run_id || github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  FLWR_TELEMETRY_ENABLED: 0
+
+jobs:
+  fi_swift_format_lint:
+    name: Format and Lint Check
+    runs-on: macos-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install SwiftFormat
+        run: brew install swift-format
+
+      - name: Check formatting and lint
+        working-directory: intelligence/swift
+        run: swift-format lint --recursive .
+
+  fi_swift_tests:
+    name: Tests
+    runs-on: macos-14
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - uses: swift-actions/setup-swift@v2
+        with:
+          swift-version: "6.0.0"
+
+      - uses: maxim-lobanov/setup-xcode@v1
+        with:
+            xcode-version: "16.2"
+
+      - name: Run tests
+        run: xcodebuild test -scheme flower -destination 'platform=macOS'

Package.swift

@@ -38,6 +38,12 @@ let package = Package(
                 .product(name: "MLXLLM", package: "mlx-swift-examples"),
                 .product(name: "Crypto", package: "swift-crypto")
             ],
-            path: "intelligence/swift/src"),
+            path: "intelligence/swift/src"
+        ),
+        .testTarget(
+            name: "FlowerIntelligenceTests",
+            dependencies: ["FlowerIntelligence"],
+            path: "intelligence/swift/tests"
+        )
     ]
 )

intelligence/dev/build-docs.sh

@@ -2,11 +2,21 @@
 set -e
 cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"/../
 
+# Build TS docs
 cd ts && \
   pnpm build:docs --readme none --name "TypeScript API" && \
   cd ..
 
-cd docs
+# Build Swift docs
+cd .. && \
+  sourcedocs generate --module-name FlowerIntelligence -- -scheme flower -destination 'platform=macOS' && \
+  mkdir -p intelligence/docs/source/swift-api-ref && \
+  cp -r Documentation/Reference/* intelligence/docs/source/swift-api-ref/ && \
+  cd intelligence/docs && \
+  mv source/swift-api-ref/README.md source/swift-api-ref/index.md && \
+  sed -i.bak '1 s/^# .*/# Swift API/' source/swift-api-ref/index.md && \
+  sed -i.bak '/^This file was generated by/d' source/swift-api-ref/index.md && \
+  rm -f source/swift-api-ref/index.md.bak
 
 {
   echo ''
@@ -17,6 +27,6 @@ cd docs
   echo ''
   echo '*/*'
   echo '```'
-} | tee -a source/ts-api-ref/index.md
+} | tee -a source/ts-api-ref/index.md source/swift-api-ref/index.md
 
 make html

intelligence/docs/source/index.rst

@@ -5,7 +5,7 @@ Flower Intelligence is a cross-platform inference library that let's user
 seamlessly interact with Large-Language Models both locally and remotely in a
 secure and private way. The library was created by the ``Flower Labs`` team that also created `Flower: A Friendly Federated AI Framework <https://flower.ai>`_.
 
-We currently only provide a SDK for TypeScript/JavaScript.
+We currently provide SDKs for TypeScript/JavaScript and Swift.
 
 
 Install
@@ -27,6 +27,17 @@ Install
         .. code-block:: bash
 
           npm i "@flwr/flwr"
+
+    .. tab-item:: Swift
+        :sync: swift
+
+        .. code-block:: bash
+
+          # You can add package dependency to your Xcode project via its UI.
+          # Please refer to https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app.
+          # 
+          # To add dependency to your Swift package, you can run the following command:
+          swift package add-dependency "https://github.com/adap/flower.git"
 
 
 Hello, Flower Intelligence!
@@ -77,6 +88,23 @@ Flower Intelligence is built around the Singleton design pattern, meaning you on
 
             await main().then().catch();
 
+    .. tab-item:: Swift
+        :sync: swift
+
+        .. code-block:: swift
+
+            import FlowerIntelligence
+
+            let fi = FlowerIntelligence.instance
+
+            let result = await fi.chat("Why is the sky blue?")
+            switch result {
+            case .success(let message):
+              print(message.content)
+            case .failure(let error):
+              print(error.localizedDescription)
+            }
+
 
 Specify the model
 -----------------
@@ -129,6 +157,26 @@ By specifying a model in the chat options, you can easily switch between differe
             }
 
             await main().then().catch();
+
+    .. tab-item:: Swift
+        :sync: swift
+
+        .. code-block:: swift
+
+            import FlowerIntelligence
+
+            let fi = FlowerIntelligence.instance
+
+            let options = ChatOptions(model: "meta/llama3.2-1b/instruct-fp16")
+            let result = await fi.chat("Why is the sky blue?", maybeOptions: options)
+
+            switch result {
+            case .success(let message):
+                print(message.content)
+            case .failure(let error):
+                print(error.localizedDescription)
+            }
+
 
 Check for errors
 ----------------
@@ -188,6 +236,26 @@ Instead of throwing exceptions that might crash your application, Flower Intelli
 
             await main().then().catch();
 
+    .. tab-item:: Swift
+        :sync: swift
+
+        .. code-block:: swift
+
+            import FlowerIntelligence
+
+            let fi = FlowerIntelligence.instance
+
+            let options = ChatOptions(model: "meta/llama3.2-1b/instruct-fp16")
+            let result = await fi.chat("Why is the sky blue?", maybeOptions: options)
+
+            switch result {
+            case .success(let message):
+                print(message.content)
+            case .failure(let error):
+                print(error.localizedDescription)
+            }
+
+
 Stream Responses
 ----------------
 
@@ -251,6 +319,29 @@ The callback function must accept an argument of type :doc:`StreamEvent <ts-api-
 
             await main().then().catch();
 
+    .. tab-item:: Swift
+        :sync: swift
+
+        .. code-block:: swift
+
+            import FlowerIntelligence
+
+            let fi = FlowerIntelligence.instance
+
+            let options = ChatOptions(
+              model: "meta/llama3.2-1b/instruct-fp16",
+              stream: true,
+              onStreamEvent: { event in
+                  print(event.chunk)
+              }
+            )
+
+            let result = await fi.chat("Why is the sky blue?", maybeOptions: options)
+
+            if case .failure(let error) = result {
+                print(error.localizedDescription)
+            }
+
 Use Roles
 ---------
 
@@ -320,6 +411,29 @@ Instead of simply sending a single string, you can provide an array of :doc:`mes
             }
 
             await main().then().catch();
+
+    .. tab-item:: Swift
+        :sync: swift
+
+        .. code-block:: swift
+
+            import FlowerIntelligence
+
+            let fi = FlowerIntelligence.instance
+
+            let messages = [
+              Message(role: "system", content: "You are a helpful assistant."),
+              Message(role: "user", content: "Why is the sky blue?")
+            ]
+
+            let options = ChatOptions(model: "meta/llama3.2-1b/instruct-fp16")
+            let result = await fi.chat(options: (messages, options))
+            switch result {
+            case .success(let message):
+              print(message.content)
+            case .failure(let error):
+              print(error.localizedDescription)
+            }
 
 Handle history
 --------------
@@ -414,6 +528,50 @@ In this example, the conversation history is maintained in an array that include
             }
 
             await main().then().catch();
+
+    .. tab-item:: Swift
+        :sync: swift
+
+        .. code-block:: swift
+
+            import FlowerIntelligence
+
+            let fi = FlowerIntelligence.instance
+
+            // Initialize history with a system message
+            var history: [Message] = [
+                Message(role: "system", content: "You are a friendly assistant that loves using emojis.")
+            ]
+
+            // Function to chat while preserving conversation history
+            func chatWithHistory(userInput: String) async {
+                // Append user input to the history
+                history.append(Message(role: "user", content: userInput))
+
+                // Define chat options with streaming
+                let options = ChatOptions(
+                    model: "meta/llama3.2-1b/instruct-fp16",
+                    stream: true,
+                    onStreamEvent: { event in
+                        print(event.chunk)
+                    }
+                )
+
+                // Perform chat with full history
+                let result = await fi.chat(options: (history, options))
+
+                switch result {
+                case .success(let response):
+                    // Append assistant's response to history
+                    history.append(response)
+                    print("Assistant's full response:", response.content)
+                case .failure(let error):
+                    print(error.localizedDescription)
+                }
+            }
+
+            // Start the conversation
+            await chatWithHistory("Why is the sky blue?")
 
 .. note::
    Checkout out full examples over on `GitHub <https://github.com/adap/flower/tree/main/intelligence/ts/examples>`_ for more information!
@@ -503,6 +661,36 @@ You will also need to provide a valid API key via the ``apiKey`` attribute.
             }
 
             await main().then().catch();
+
+    .. tab-item:: Swift
+        :sync: swift
+
+        .. code-block:: swift
+
+            import FlowerIntelligence
+
+            let fi = FlowerIntelligence.instance
+            fi.remoteHandoff = true
+            fi.apiKey = "YOUR_API_KEY"
+
+            let messages = [
+              Message(role: "system", content: "You are a helpful assistant."),
+              Message(role: "user", content: "Why is the sky blue?")
+            ]
+
+            let options = ChatOptions(
+              model: "meta/llama3.2-1b/instruct-fp16",
+              stream: true,
+              onStreamEvent: { event in
+                  print(event.chunk)
+              }
+            )
+
+            let result = await fi.chat(options: (messages, options))
+
+            if case .failure(let error) = result {
+              print(error.localizedDescription)
+            }
 
 References
 ----------
@@ -516,6 +704,7 @@ Information-oriented API reference and other reference material.
 
    ref-models
    ts-api-ref/index
+   swift-api-ref/index
 
 Join the Flower Community
 -------------------------
@@ -527,4 +716,3 @@ The Flower Community is growing quickly - we're a friendly group of researchers,
     :shadow:
 
     Join us on Slack
-