@ondeinference / ed-swift
Code Commits Issues Pulls Cloud Agent CI/CD
main
main
md 140 lines 3.95 KB
Rendered Raw
1 # Ed for Swift
2
3 Ed is a private, on-device agent for Swift apps. Onde runs the language model;
4 Ed gives that model a safe way to ask your app to do things.
5
6 It runs on iPhone, iPad, Mac, Apple TV, Apple Vision Pro, and Apple Watch. Model
7 input, conversation history, and tool results stay on the device unless a tool
8 you write deliberately sends data elsewhere.
9
10 ## The mental model
11
12 If you are new to agents, think of Ed as a loop:
13
14 1. Your app sends a message to the model.
15 2. The model either answers, or requests one of your registered tools.
16 3. Ed checks the tool's risk level.
17 4. Your Swift code runs the approved tool and returns text.
18 5. The model reads that result and writes the final answer.
19
20 The model cannot call arbitrary Swift APIs. It only sees tools your app
21 registers.
22
23 ## Installation
24
25 In Xcode, choose **File > Add Package Dependencies** and enter:
26
27 ```text
28 https://github.com/ondeinference/ed-swift
29 ```
30
31 Then add the `Ed` product to your target and import it:
32
33 ```swift
34 import Ed
35 ```
36
37 ## Quick start
38
39 First, describe a tool and implement it. A JSON schema tells the model which
40 arguments it may provide:
41
42 ```swift
43 import Ed
44
45 struct BatteryTool: EdTool {
46 let definition = EdToolDefinition.readOnly(
47 name: "battery_level",
48 description: "Read the device battery percentage",
49 parametersSchema: #"{"type":"object","properties":{}}"#
50 )
51
52 func execute(arguments: String) async throws -> String {
53 // Read the real value from your platform API here.
54 "The battery is at 73 percent."
55 }
56 }
57 ```
58
59 Then create the agent, register the tool, and load the default model:
60
61 ```swift
62 let ed = EdAgent { call in
63 // This callback is used only for mutating tools.
64 let userApproved = await showApproval(for: call)
65 return userApproved ? .allowOnce : .deny
66 }
67
68 try await ed.register(BatteryTool())
69 try await ed.loadDefaultAgentModel(
70 systemPrompt: "You are a concise assistant inside my app."
71 )
72
73 let reply = try await ed.run("How much battery do I have?")
74 print(reply.text)
75 ```
76
77 Use `.readOnly` for tools that only inspect state. Use `.mutating` for tools
78 that save, send, purchase, delete, unlock, or otherwise change something. Ed
79 runs read-only tools automatically and sends every mutating call through your
80 approval callback.
81
82 Observe progress and tool activity with an async stream:
83
84 ```swift
85 for await event in ed.events() {
86 print(event)
87 }
88 ```
89
90 ### Plain chat, streaming and saved conversations
91
92 For chat without tools, `stream` yields the reply as it is generated. Breaking
93 out of the loop or cancelling the task stops generation:
94
95 ```swift
96 for try await delta in ed.stream("Summarise this thread.") {
97 reply += delta
98 }
99 ```
100
101 Other calls for apps with their own chat history:
102
103 ```swift
104 await ed.restoreHistory(savedMessages) // switch to a saved chat (needs a loaded model)
105 let draft = try await ed.generate(messages: messages) // one-shot, history untouched
106 await ed.setSystemPrompt("Be brief.")
107 await ed.setSampling(EdSamplingConfiguration(temperature: 0.2))
108 ```
109
110 `EdAgent(appID:)` reports usage under your Onde app id. Pass a two-argument
111 approval handler (`{ call, risk in ... }`) to learn whether a call is read-only
112 or mutating, and watch for `EdEvent.textDelta` while `run` generates.
113
114 Cancelling the Swift task also cancels the active Ed turn:
115
116 ```swift
117 let task = Task { try await ed.run("Do the task") }
118 task.cancel()
119 ```
120
121 See [`Examples/EdExample`](Examples/EdExample) for a complete SwiftUI example
122 with a read-only device tool and an approval-gated mutating tool.
123
124 ## Local development
125
126 Keep `onde`, `ed`, and `ed-swift` next to one another, then build a
127 local framework before running Swift tests:
128
129 ```sh
130 make macos
131 swift test
132 ```
133
134 Use `make ios`, `make tvos`, `make visionos`, or `make watchos` for another
135 Apple platform. The package automatically uses `EdFramework.xcframework` when
136 that local file exists. Without it, SwiftPM downloads the signed release asset.
137
138 ## Licence
139
140 Ed is available under either the MIT License or Apache License 2.0.