feat(intelligence) Add Swift Docs

.github/workflows/intelligence-docs.yml

@@ -22,45 +22,100 @@ env:
   FLWR_TELEMETRY_ENABLED: 0
 
 jobs:
-  build_and_deploy:
-    runs-on: macos-14
-    name: Build and deploy
+  build_ts_docs:
+    runs-on: ubuntu-22.04
+    name: Build TypeScript Docs
     steps:
       - uses: actions/checkout@v4
       - name: Bootstrap
         uses: ./.github/actions/bootstrap
-      - name: 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
       - name: Install Flower Intelligence
         run: |
           cd intelligence/ts
           pnpm i
-      - name: Build docs
+      - name: Build TS docs
+        run: |
+          cd intelligence/ts
+          pnpm build:docs --readme none --name "TypeScript API"
+      - name: Move TS docs
+        run: |
+          echo -e '\n```{toctree}\n:hidden:\n:maxdepth: 2\n:glob:\n\n*/*\n```' >> intelligence/docs/source/ts-api-ref/index.md
+      - name: Upload TS docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ts-docs
+          path: intelligence/docs/source/ts-api-ref/
+
+  build_swift_docs:
+    runs-on: macos-14
+    name: Build Swift Docs
+    steps:
+      - uses: actions/checkout@v4
+      - name: Bootstrap
+        uses: ./.github/actions/bootstrap
+      - uses: swift-actions/setup-swift@v2
+        with:
+          swift-version: "6.0.0"
+      - uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: "16.2"
+      - name: Install SourceDocs
+        run: brew install sourcedocs
+      - name: Build Swift docs
+        run: |
+          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/
+          mv intelligence/docs/source/swift-api-ref/README.md intelligence/docs/source/swift-api-ref/index.md
+          sed -i.bak '1 s/^# .*/# Swift API/' intelligence/docs/source/swift-api-ref/index.md
+          sed -i.bak '/^This file was generated by/d' intelligence/docs/source/swift-api-ref/index.md
+          rm -f intelligence/docs/source/swift-api-ref/index.md.bak
+          echo -e '\n```{toctree}\n:hidden:\n:maxdepth: 2\n:glob:\n\n*/*\n```' >> intelligence/docs/source/swift-api-ref/index.md
+      - name: Upload Swift docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: swift-docs
+          path: intelligence/docs/source/swift-api-ref/
+
+  build_and_deploy:
+    runs-on: ubuntu-22.04
+    needs: [build_ts_docs, build_swift_docs]
+    name: Build and Deploy Docs
+    steps:
+      - uses: actions/checkout@v4
+      - name: Bootstrap
+        uses: ./.github/actions/bootstrap
+      - name: Install pandoc
+        run: sudo apt install pandoc
+      - name: Install Flower dependencies (mandatory only)
+        run: python -m poetry install --extras "simulation"
+      - name: Download TS docs
+        uses: actions/download-artifact@v4
+        with:
+          name: ts-docs
+          path: intelligence/docs/source/ts-api-ref/
+      - name: Download Swift docs
+        uses: actions/download-artifact@v4
+        with:
+          name: swift-docs
+          path: intelligence/docs/source/swift-api-ref/
+      - name: Build final docs
         run: |
-          ./intelligence/dev/build-docs.sh
+          cd intelligence/docs
+          make html
       - name: Deploy docs
         if: ${{ github.ref == 'refs/heads/main' && github.repository == 'adap/flower' && !github.event.pull_request.head.repo.fork }}
         env:
-          AWS_DEFAULT_REGION: ${{ secrets. AWS_DEFAULT_REGION }}
+          AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets. AWS_SECRET_ACCESS_KEY }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           DOCS_BUCKET: flower.ai
         run: |
           aws s3 sync --delete --exclude ".*" --exclude "v/*" --cache-control "no-cache" ./intelligence/docs/build/html/ s3://${{ env.DOCS_BUCKET }}/docs/intelligence

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?")
 
 Pre-loading the model
 ---------------------
@@ -630,6 +788,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
 ----------
@@ -644,6 +832,7 @@ Information-oriented API reference and other reference material.
    ref-models
    examples
    ts-api-ref/index
+   swift-api-ref/index
 
 Join the Flower Community
 -------------------------
@@ -655,4 +844,3 @@ The Flower Community is growing quickly - we're a friendly group of researchers,
     :shadow:
 
     Join us on Slack
-