v2

Author: m1guelpf

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Docs
+
+on:
+    push:
+        tags: ['*']
+        branches: [main]
+
+jobs:
+    build:
+        runs-on: macos-latest
+        steps:
+            - uses: swift-actions/setup-swift@v2
+
+            - uses: actions/checkout@v4
+
+            - name: Restore .build
+              id: restore-build
+              uses: actions/cache/restore@v4
+              with:
+                path: .build
+                restore-keys: "swiftpm-docs-build-${{ runner.os }}-"
+                key: "swiftpm-docs-build-${{ runner.os }}-${{ github.event.pull_request.base.sha || github.event.after }}"
+
+            - name: Generate documentation
+              run: |
+                swift package --allow-writing-to-directory ./ResponsesAPI.doccarchive generate-documentation --target ResponsesAPI --disable-indexing --experimental-documentation-coverage --diagnostic-filter error --output-path ./ResponsesAPI.doccarchive
+                tar -cf ResponsesAPI.doccarchive.tar ./ResponsesAPI.doccarchive/data ./ResponsesAPI.doccarchive/index ./ResponsesAPI.doccarchive/metadata.json ./ResponsesAPI.doccarchive/documentation-coverage.json
+
+            - name: Cache .build
+              if: steps.restore-build.outputs.cache-hit != 'true'
+              uses: actions/cache/save@v4
+              with:
+                path: .build
+                key: "swiftpm-docs-build-${{ runner.os }}-${{ github.event.pull_request.base.sha || github.event.after }}"
+
+            - name: Update latest documentation
+              id: github-pages
+              if: github.ref_type != 'tag'
+              uses: actions/upload-artifact@v4
+              with:
+                retention-days: 1
+                name: github-pages
+                if-no-files-found: error
+                path: ./ResponsesAPI.doccarchive.tar
+
+            - name: Attach to release
+              if: github.ref_type == 'tag'
+              uses: softprops/action-gh-release@v2
+              with:
+                  files: ./ResponsesAPI.doccarchive.tar
+    deploy:
+      needs: build
+      runs-on: ubuntu-latest
+      if: github.ref_type != 'tag'
+      permissions:
+         pages: write
+         id-token: write
+      environment:
+         name: github-pages
+         url: ${{ steps.deployment.outputs.page_url }}
+      steps:
+          - name: Deploy to GitHub Pages
+            id: deployment
+            uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: Test
+
+on:
+    push:
+        branches: [main]
+    pull_request:
+
+jobs:
+    build:
+        runs-on: macos-latest
+        steps:
+            - uses: swift-actions/setup-swift@v2
+
+            - uses: actions/checkout@v4
+
+            - name: Restore .build
+              id: restore-build
+              uses: actions/cache/restore@v4
+              with:
+                path: .build
+                restore-keys: "swiftpm-tests-build-${{ runner.os }}-"
+                key: "swiftpm-tests-build-${{ runner.os }}-${{ github.event.pull_request.base.sha || github.event.after }}"
+
+
+            - name: Build
+              run: swift build --build-tests --enable-code-coverage
+
+            - name: Cache .build
+              if: steps.restore-build.outputs.cache-hit != 'true'
+              uses: actions/cache/save@v4
+              with:
+                path: .build
+                key: "swiftpm-tests-build-${{ runner.os }}-${{ github.event.pull_request.base.sha || github.event.after }}"
+
+            - name: Run tests
+              run: swift test --skip-build --enable-code-coverage --parallel
+
+            - name: Test coverage
+              uses: maxep/[email protected]
+              with:
+                  output-file: ./coverage/lcov.info

Package.swift

@@ -1,9 +1,10 @@
 // swift-tools-version: 6.0
 
 import PackageDescription
+import CompilerPluginSupport
 
 let package = Package(
-	name: "OpenAI",
+	name: "ResponsesAPI",
 	platforms: [
 		.iOS(.v17),
 		.tvOS(.v17),
@@ -13,19 +14,43 @@ let package = Package(
 		.macCatalyst(.v17),
 	],
 	products: [
-		.library(name: "OpenAI", type: .static, targets: ["OpenAI"]),
+		.library(name: "ResponsesAPI", targets: ["ResponsesAPI"]),
 	],
 	dependencies: [
 		.package(url: "https://github.com/SwiftyLab/MetaCodable.git", from: "1.0.0"),
+		.package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0"),
+		.package(url: "https://github.com/pointfreeco/swift-macro-testing", from: "0.6.0"),
+		.package(url: "https://github.com/swiftlang/swift-syntax.git", "600.0.1"..<"603.0.0"),
 	],
 	targets: [
 		.target(
-			name: "OpenAI",
+			name: "ResponsesAPI",
 			dependencies: [
+				"Macros",
 				.product(name: "MetaCodable", package: "MetaCodable"),
 				.product(name: "HelperCoders", package: "MetaCodable"),
 			],
 			path: "./src"
 		),
+		.macro(
+			name: "Macros",
+			dependencies: [
+				.product(name: "SwiftSyntax", package: "swift-syntax"),
+				.product(name: "SwiftDiagnostics", package: "swift-syntax"),
+				.product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+				.product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
+				.product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
+			],
+			path: "./macros"
+		),
+		.testTarget(
+			name: "Tests",
+			dependencies: [
+				"ResponsesAPI", "Macros",
+				.product(name: "MacroTesting", package: "swift-macro-testing"),
+				.product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),
+			],
+			path: "./tests"
+		),
 	]
 )

README.md

@@ -1,9 +1,14 @@
 # OpenAI Responses API
+> Hand-crafted Swift SDK for the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses).
 
 [![Swift Version](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fm1guelpf%2Fswift-openai-responses%2Fbadge%3Ftype%3Dswift-versions&color=brightgreen)](https://swiftpackageindex.com/m1guelpf/swift-openai-responses)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/m1guelpf/swift-openai-responses/main/LICENSE)
 
-An unofficial Swift SDK for the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses).
+This package contains:
+- A fully typed client for the Responses API that _feels_ Swifty
+- `Schemable` and `Tool` macros, providing elegant ways to define tools and structured responses.
+- A `Conversation` class, handling everything you need for multi-turn streaming conversations in your views.
+
 
 ## Installation
 
@@ -29,15 +34,15 @@ dependencies: [
 -   File > Swift Packages > Add Package Dependency
 -   Add https://github.com/m1guelpf/swift-openai-responses.git
 -   Select "Branch" with "main"
-    
+
 </details>
 
 <details>
 
 <summary>CocoaPods</summary>
 
 Ask ChatGPT to help you migrate away from CocoaPods.
-    
+
 </details>
 
 ## Getting started 🚀
@@ -50,17 +55,17 @@ import SwiftUI
 
 struct ContentView: View {
 	@State private var newMessage: String = ""
-	@State private var conversation = Conversation(authToken: OPENAI_KEY, using: .gpt4o)
+	@State private var conversation = Conversation(authToken: OPENAI_KEY, using: .gpt5)
 
 	var body: some View {
 		VStack(spacing: 0) {
 			ScrollView {
-                VStack(spacing: 12) {
-                    ForEach(messages, id: \.self) { message in
-                        MessageBubble(message: message)
-                    }
-                }
-                .padding()
+				VStack(spacing: 12) {
+					ForEach(conversation.messages, id: \.self) { message in
+						MessageBubble(message: message)
+					}
+				}
+				.padding()
 			}
 
 			HStack(spacing: 12) {
@@ -92,10 +97,8 @@ struct ContentView: View {
 	func sendMessage() {
 		guard newMessage != "" else { return }
 
-		Task {
-			try await conversation.send(text: newMessage)
-			newMessage = ""
-		}
+		conversation.send(text: newMessage)
+		newMessage = ""
 	}
 }
 ```
@@ -111,13 +114,13 @@ The Conversation class provides a high-level interface for managing a conversati
 To create a `Conversation` instance, all you need is an OpenAI API key, and the model you will be talking to:
 
 ```swift
-@State private var conversation = Conversation(authToken: OPENAI_API_KEY, using: .gpt4o)
+@State private var conversation = Conversation(authToken: OPENAI_API_KEY, using: .gpt5)
 ```
 
 You can optionally provide a closure to configure the conversation, adding a system prompt or tools for the model to use:
 
 ```swift
-@State private var conversation = Conversation(authToken: OPENAI_API_KEY, using: .gpt4o) { config in
+@State private var conversation = Conversation(authToken: OPENAI_API_KEY, using: .gpt5) { config in
 	// configure the model's behaviour
 	config.instructions = "You are a coding assistant that talks like a pirate"
 
@@ -143,25 +146,25 @@ conversation.truncation = .auto
 Your `Conversation` instance contains various helpers to make communicating with the model easier. For example, you can send a simple text message like this:
 
 ```swift
-try await conversation.send(text: "Hey!")
+conversation.send(text: "Hey!")
 ```
 
 There are also helpers for providing the output of a tool call or computer use call:
 
 ```swift
-try await conversation.send(functionCallOutput: .init(callId: callId, output: "{ ... }"))
-try await conversation.send(computerCallOutput: .init(callId: callId, output: .screenshot(fileId: "...")))
+conversation.send(functionCallOutput: .init(callId: callId, output: "{ ... }"))
+conversation.send(computerCallOutput: .init(callId: callId, output: .screenshot(fileId: "...")))
 ```
 
 For more complex use cases, you can construct the `Input` yourself:
 
 ```swift
-try await conversation.send(Input([
-	.message(content: Input.Content([
+conversation.send([
+	.message(content: [
 		.image(fileId: "..."),
 		.text("Take a look at this image and tell me what you see"),
-	])),
-]))
+	]),
+])
 ```
 
 #### Reading messages
@@ -184,7 +187,6 @@ ScrollView {
 }
 ```
 
-
 ### `ResponsesAPI`
 
 #### Creating a new instance
@@ -207,7 +209,7 @@ let client = ResponsesAPI(
 
 For more advanced use cases like connecting to a custom server, you can customize the `URLRequest` used to connect to the API:
 
-``` swift
+```swift
 let urlRequest = URLRequest(url: MY_CUSTOM_ENDPOINT)
 urlRequest.addValue("Bearer \(YOUR_API_KEY)", forHTTPHeaderField: "Authorization")
 
@@ -220,7 +222,7 @@ To create a new response, call the `create` method with a `Request` instance:
 
 ```swift
 let response = try await client.create(Request(
-	model: .gpt4o,
+	model: .gpt5,
 	input: .text("Are semicolons optional in JavaScript?"),
 	instructions: "You are a coding assistant that talks like a pirate"
 ))
@@ -234,7 +236,7 @@ To stream back the response as it is generated, use the `stream` method:
 
 ```swift
 let stream = try await client.stream(Request(
-	model: .gpt4o,
+	model: .gpt5,
 	input: .text("Are semicolons optional in JavaScript?"),
 	instructions: "You are a coding assistant that talks like a pirate"
 ))
@@ -255,7 +257,7 @@ let file = try await client.upload(file: .file(name: "image.png", contents: imag
 
 // then, use it on a message
 try await client.create(Request(
-	model: .gpt4o,
+	model: .gpt5,
 	input: .message(content: [
 		.image(fileId: file.id),
 		.text("Take a look at this image and tell me what you see"),