Add support for Gemini structured outputs (#115)

Author: lzell

README.md

@@ -1635,6 +1635,79 @@ Use the file URL returned from the snippet above.
     }
 
 
+### How to use structured ouputs with Gemini
+
+```swift
+    import AIProxy
+
+    /* Uncomment for BYOK use cases */
+    // let geminiService = AIProxy.geminiDirectService(
+    //     unprotectedAPIKey: "your-gemini-key"
+    // )
+
+    /* Uncomment for all other production use cases */
+    // let geminiService = AIProxy.geminiService(
+    //     partialKey: "partial-key-from-your-developer-dashboard",
+    //     serviceURL: "service-url-from-your-developer-dashboard"
+    // )
+
+    let schema: [String: AIProxyJSONValue] = [
+        "description": "List of recipes",
+        "type": "array",
+        "items": [
+            "type": "object",
+            "properties": [
+                "recipeName": [
+                    "type": "string",
+                    "description": "Name of the recipe",
+                    "nullable": false
+                ]
+            ],
+            "required": ["recipeName"]
+        ]
+    ]
+    do {
+        let requestBody = GeminiGenerateContentRequestBody(
+            contents: [
+                .init(
+                    parts: [
+                        .text("List a few popular cookie recipes."),
+                    ]
+                )
+            ],
+            generationConfig: .init(
+                responseMimeType: "application/json",
+                responseSchema: schema
+            )
+        )
+        let response = try await geminiService.generateContentRequest(
+            body: requestBody,
+            model: "gemini-2.0-flash"
+        )
+        for part in response.candidates?.first?.content?.parts ?? [] {
+            if case .text(let text) = part {
+                print("Gemini sent: \(text)")
+            }
+        }
+        if let usage = response.usageMetadata {
+            print(
+                """
+                Used:
+                 \(usage.promptTokenCount ?? 0) prompt tokens
+                 \(usage.cachedContentTokenCount ?? 0) cached tokens
+                 \(usage.candidatesTokenCount ?? 0) candidate tokens
+                 \(usage.totalTokenCount ?? 0) total tokens
+                """
+            )
+        }
+    } catch AIProxyError.unsuccessfulRequest(let statusCode, let responseBody) {
+        print("Received \(statusCode) status code with response body: \(responseBody)")
+    } catch {
+        print("Could not create Gemini generate content request: \(error.localizedDescription)")
+    }
+```
+
+
 ***
 
 

Sources/AIProxy/Gemini/GeminiGenerateContentRequestBody.swift

@@ -418,15 +418,15 @@ extension GeminiGenerateContentRequestBody {
         }
 
         private enum CodingKeys: String, CodingKey {
-            case maxOutputTokens = "max_output_tokens"
+            case maxOutputTokens
             case temperature
-            case topP = "top_p"
-            case topK = "top_k"
-            case presencePenalty = "presence_penalty"
-            case frequencyPenalty = "frequency_penalty"
-            case responseModalities = "response_modalities"
-            case responseMimeType = "response_mime_type"
-            case responseSchema = "response_schema"
+            case topP
+            case topK
+            case presencePenalty
+            case frequencyPenalty
+            case responseModalities
+            case responseMimeType
+            case responseSchema
         }
     }
 }

Tests/AIProxyTests/GeminiStructuredOutputsRequestTests.swift

@@ -0,0 +1,81 @@
+//
+//  GeminiStructuredOutputsRequestTests.swift
+//  AIProxy
+//
+//  Created by Lou Zell on 3/15/25.
+//
+
+import XCTest
+import Foundation
+@testable import AIProxy
+
+
+final class GeminiStructuredOutputsRequestTests: XCTestCase {
+    // This example is from generative-ai-js/samples/controlled_generation.js
+    func testRequestIsEncodableToJson() throws {
+        let schema: [String: AIProxyJSONValue] = [
+            "description": "List of recipes",
+            "type": "array",
+            "items": [
+                "type": "object",
+                "properties": [
+                    "recipeName": [
+                        "type": "string",
+                        "description": "Name of the recipe",
+                        "nullable": false
+                    ]
+                ],
+                "required": ["recipeName"]
+            ]
+        ]
+
+        let requestBody = GeminiGenerateContentRequestBody(
+            contents: [
+                .init(
+                    parts: [.text("List a few popular cookie recipes.")],
+                    role: "user"
+                )
+            ],
+            generationConfig: .init(
+                responseMimeType: "application/json",
+                responseSchema: schema
+            )
+        )
+        XCTAssertEqual(#"""
+            {
+              "contents" : [
+                {
+                  "parts" : [
+                    {
+                      "text" : "List a few popular cookie recipes."
+                    }
+                  ],
+                  "role" : "user"
+                }
+              ],
+              "generationConfig" : {
+                "responseMimeType" : "application\/json",
+                "responseSchema" : {
+                  "description" : "List of recipes",
+                  "items" : {
+                    "properties" : {
+                      "recipeName" : {
+                        "description" : "Name of the recipe",
+                        "nullable" : false,
+                        "type" : "string"
+                      }
+                    },
+                    "required" : [
+                      "recipeName"
+                    ],
+                    "type" : "object"
+                  },
+                  "type" : "array"
+                }
+              }
+            }
+            """#,
+            try requestBody.serialize(pretty: true)
+        )
+    }
+}