Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .swiftlint-baseline.json
Original file line number Diff line number Diff line change
Expand Up @@ -452,10 +452,10 @@
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":6,"character":48},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case incompatibleModel, invalidSchema, unavailableTool, invalidContext, invalidVersion"},
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":6,"character":65},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case incompatibleModel, invalidSchema, unavailableTool, invalidContext, invalidVersion"},
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":6,"character":81},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case incompatibleModel, invalidSchema, unavailableTool, invalidContext, invalidVersion"},
{"violation":{"ruleDescription":"Function bodies should not span too many lines","ruleIdentifier":"function_body_length","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":21,"character":5},"reason":"Function body should span 80 lines or less excluding comments and whitespace: currently spans 94 lines","severity":"error","ruleName":"Function Body Length"},"text":" func validationIssues(catalog: ModelCatalog, kits: [String: ToolKit]) -> [WorkflowValidationIssue] {"},
{"violation":{"ruleDescription":"Function bodies should not span too many lines","ruleIdentifier":"function_body_length","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":21,"character":5},"reason":"Function body should span 40 lines or less excluding comments and whitespace: currently spans 69 lines","severity":"warning","ruleName":"Function Body Length"},"text":" func validationIssues(catalog: ModelCatalog, tools: ToolSources) -> [WorkflowValidationIssue] {"},
{"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":31,"character":13},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let knownModels = Set(catalog.ids)"},
{"violation":{"ruleDescription":"Complexity of function bodies should be limited.","ruleIdentifier":"cyclomatic_complexity","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":50,"character":9},"reason":"Function should have complexity 8 or less; currently complexity is 33","severity":"error","ruleName":"Cyclomatic Complexity"},"text":" func visit(_ steps: [Step]) {"},
{"violation":{"ruleDescription":"Function bodies should not span too many lines","ruleIdentifier":"function_body_length","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":50,"character":9},"reason":"Function body should span 40 lines or less excluding comments and whitespace: currently spans 72 lines","severity":"warning","ruleName":"Function Body Length"},"text":" func visit(_ steps: [Step]) {"},
{"violation":{"ruleDescription":"Complexity of function bodies should be limited.","ruleIdentifier":"cyclomatic_complexity","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":37,"character":9},"reason":"Function should have complexity 8 or less; currently complexity is 20","severity":"error","ruleName":"Cyclomatic Complexity"},"text":" func visit(_ steps: [Step]) {"},
{"violation":{"ruleDescription":"Function bodies should not span too many lines","ruleIdentifier":"function_body_length","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":37,"character":9},"reason":"Function body should span 40 lines or less excluding comments and whitespace: currently spans 47 lines","severity":"warning","ruleName":"Function Body Length"},"text":" func visit(_ steps: [Step]) {"},
{"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":73,"character":25},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let candidates = [step.model, step.fallback].compactMap { $0 }.filter { knownModels.contains($0) }"},
{"violation":{"ruleDescription":"Else and catch should be on the same line, one space after the previous declaration","ruleIdentifier":"statement_position","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":91,"character":93},"reason":"Else and catch should be on the same line, one space after the previous declaration","severity":"warning","ruleName":"Statement Position"},"text":" if let kit = kits[id] { if kit.server == nil { tools += kit.tools } }"},
{"violation":{"ruleDescription":"Else and catch should be on the same line, one space after the previous declaration","ruleIdentifier":"statement_position","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":97,"character":104},"reason":"Else and catch should be on the same line, one space after the previous declaration","severity":"warning","ruleName":"Statement Position"},"text":" if let tool = kit.tools.first(where: { $0.name == name }) { tools = [tool] }"},
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@
- `Field.Kind.object` groups fields, so `extract` steps and tool parameters can ask for
lists of records such as `.list(.object([...]))`. Each object reads as a dictionary.
Exhaustive `switch`es over `Field.Kind` need a case for it.
- Host tools: `HostTool`s in a `HostToolKit`, passed as `WorkflowExecutor(hostToolKits:)`, are
tools the app writes in Swift, such as one that edits the app's own state. Agent and Use a Tool
steps select them by kit id, so workflows stay Codable. Calls that change something follow the
write policy; local-only executions may call them.

### Fixed

Expand Down
32 changes: 32 additions & 0 deletions Documentation/Usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,38 @@ prevents fallback. This is not an exactly-once guarantee.
Group reusable tools in a `ToolKit`, pass it to the executor and select it
with `kits: ["weather"]`.

<a name="host-tools"></a>

### 🧩 Give an agent a Swift tool

When the action belongs to your app, such as editing an order on screen, write
the tool in Swift and pass it in a `HostToolKit`:

```swift
let order = HostToolKit(id: "order", name: "Order", tools: [
HostTool(name: "addLine", description: "Adds a product to the order.", parameters: [
Field("product", .text),
Field("quantity", .number),
]) { arguments in
await cart.add(arguments) // Your app's own state
return .text("Added")
},
])
let workflow = Workflow(
name: "Order by voice"
) {
Step.agent("answer", "Update the order.", kits: ["order"], model: .appleOnDevice)
}
let report = try await WorkflowExecutor(writePolicy: .allow, hostToolKits: [order])
.run(workflow, input: .text("Two beers, please"))
```

The workflow only names the kit, so it stays Codable; the body stays in
memory. Tools change something unless you pass `changesSomething: false`, and
then follow the write policy like requests (`.ask` sees a `POST host:order`).
Local-only executions may call them, since they reach no network. Use a Tool
steps call them directly with `Step.useTool("add", kit: "order", tool: "addLine")`.

<a name="cloud-models"></a>

## ☁️ Choose your models
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ extension WorkflowExecutor {
try workflow.validateContexts()
try workflow.validateApprovals(recoverable: true)
try preflight(workflow)
return try workflow.recoveryDefinition(kits: Array(toolKits.values))
return try workflow.recoveryDefinition(kits: toolSources.declaredKits)
}

func validate(_ checkpoint: WorkflowExecutionCheckpoint, workflow: Workflow, revision: String) throws {
Expand Down
18 changes: 11 additions & 7 deletions Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Agents.swift
Original file line number Diff line number Diff line change
Expand Up @@ -50,14 +50,16 @@ extension WorkflowExecutor {
var servers: [ConnectedToolKit] = []

for id in scope.policy.tools == .denied ? [] : kitIDs ?? [] {
guard let kit = toolKits[id] else {
throw RelayError.stepFailed(step: step.name, reason: "the tool set “\(id)” isn't available")
}
if kit.server != nil {
let connection: any ToolServerConnection = try await connect(kit, step: step.name, policy: scope.policy)
servers.append(ConnectedToolKit(kit: kit, connection: connection, tools: try await serverTools(kit, connection, step: step.name)))
} else {
switch toolSources[id] {
case let .requests(kit):
specs += kit.tools
case let .server(kit):
let connection: any ToolServerConnection = try await connect(kit, step: step.name, policy: scope.policy)
servers.append(ConnectedToolKit(kit: kit, connection: connection, tools: try await serverTools(kit, connection, step: step.name), reachesNetwork: true))
case let .host(host):
servers.append(ConnectedToolKit(kit: host.toolKit, connection: host.connection, tools: host.tools.map(\.serverTool), reachesNetwork: false))
case .ambiguous, nil:
throw RelayError.stepFailed(step: step.name, reason: "the tool set “\(id)” isn't available")
}
}

Expand All @@ -69,6 +71,7 @@ private struct ConnectedToolKit: Sendable {
let kit: ToolKit
let connection: any ToolServerConnection
let tools: [ServerTool]
let reachesNetwork: Bool
}

private struct AgentToolDefinitions: Sendable {
Expand All @@ -89,6 +92,7 @@ private struct AgentToolDefinitions: Sendable {
tool: $0,
kit: server.kit,
connection: server.connection,
reachesNetwork: server.reachesNetwork,
step: execution.step.name,
context: execution.context,
log: log
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,16 @@ extension WorkflowExecutor {
for value in scope.valuePolicies.values {
policy.data = policy.data.combined(with: value)
}
// Only request tools read workflow values through templates.
case let .agent(_, _, kits):
for id in kits ?? [] {
for tool in toolKits[id]?.tools ?? [] {
for case let .requests(kit)? in (kits ?? []).map({ toolSources[$0] }) {
for tool in kit.tools {
references += ([tool.request.url, tool.request.body ?? ""] + tool.request.headers.map(\.value))
.flatMap { Template.references(in: $0) }
}
}
case let .useTool(kitID, toolName, _):
if let tool = toolKits[kitID]?.tools.first(where: { $0.name == toolName }) {
if case let .requests(kit)? = toolSources[kitID], let tool = kit.tools.first(where: { $0.name == toolName }) {
references += ([tool.request.url, tool.request.body ?? ""] + tool.request.headers.map(\.value))
.flatMap { Template.references(in: $0) }
}
Expand Down
52 changes: 36 additions & 16 deletions Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift
Original file line number Diff line number Diff line change
Expand Up @@ -7,37 +7,48 @@ extension WorkflowExecutor {
let trace: StepTrace = execution.trace
guard case let .useTool(kitID, toolName, arguments) = step.kind else { throw InvalidOutput(reason: "Expected a tool step") }

guard let kit = toolKits[kitID] else {
throw RelayError.stepFailed(step: step.name, reason: "the tool set “\(kitID)” isn't available")
}
let rendered = arguments.mapValues { Template.render($0, scope.resolve) }
let value: Value
if kit.server != nil {
switch toolSources[kitID] {
case let .host(host):
let tools: [ServerTool] = host.tools.map(\.serverTool)
let call: ConnectedToolCall = .init(kit: host.toolKit, connection: host.connection, tools: tools, name: toolName, arguments: rendered)
value = try await runConnectedTool(call, execution: execution, scope: scope)
case let .server(kit):
let connection = try await connect(kit, step: step.name, policy: scope.policy)
guard let tool = try await serverTools(kit, connection, step: step.name).first(where: { $0.name == toolName }) else {
throw RelayError.stepFailed(step: step.name, reason: "\(kit.name) has no tool “\(toolName)”")
}
let typed = ServerArguments.typed(rendered, for: tool)
let call = ServerCallDescription.prepared(kit: kit, tool: tool.name, arguments: typed)
trace.input = call.description
try scope.policy.checkTool(changesSomething: tool.changesSomething, step: step.name)
try scope.control.beginTool(tool.name, step: step.name)

let invocation: ServerToolInvocation = .init(tool: tool, connection: connection, arguments: typed, request: call)
value = try await callServerTool(invocation, execution: execution, control: scope.control)
} else {
let tools: [ServerTool] = try await serverTools(kit, connection, step: step.name)
let call: ConnectedToolCall = .init(kit: kit, connection: connection, tools: tools, name: toolName, arguments: rendered)
value = try await runConnectedTool(call, execution: execution, scope: scope)
case let .requests(kit):
guard let spec = kit.tools.first(where: { $0.name == toolName }) else {
throw RelayError.stepFailed(step: step.name, reason: "\(kit.name) has no tool “\(toolName)”")
}
value = try await context.perform(spec.request, step: step.name, trace: trace, toolName: spec.name) { reference in
if reference.hasPrefix("args.") { return rendered[String(reference.dropFirst("args.".count))].map(Value.text) }
return scope.resolve(reference)
}
case .ambiguous, nil:
throw RelayError.stepFailed(step: step.name, reason: "the tool set “\(kitID)” isn't available")
}
scope.record(execution.record(value))
return value
}

private func runConnectedTool(_ call: ConnectedToolCall, execution: WorkflowStepExecution, scope: WorkflowExecutionScope) async throws -> Value {
let step: String = execution.step.name
guard let tool = call.tools.first(where: { $0.name == call.name }) else {
throw RelayError.stepFailed(step: step, reason: "\(call.kit.name) has no tool “\(call.name)”")
}
let typed: [String: Value] = ServerArguments.typed(call.arguments, for: tool)
let request: PreparedRequest = ServerCallDescription.prepared(kit: call.kit, tool: tool.name, arguments: typed)
execution.trace.input = request.description
try scope.policy.checkTool(changesSomething: tool.changesSomething, step: step)
try scope.control.beginTool(tool.name, step: step)

let invocation: ServerToolInvocation = .init(tool: tool, connection: call.connection, arguments: typed, request: request)
return try await callServerTool(invocation, execution: execution, control: scope.control)
}

private func callServerTool(_ invocation: ServerToolInvocation, execution: WorkflowStepExecution, control: ExecutionControl) async throws -> Value {
var dispatched: Bool = false

Expand Down Expand Up @@ -86,6 +97,15 @@ extension WorkflowExecutor {
}
}

/// One named tool of a set whose tools come from a connection: a server, or the host app.
private struct ConnectedToolCall: Sendable {
let kit: ToolKit
let connection: any ToolServerConnection
let tools: [ServerTool]
let name: String
let arguments: [String: String]
}

private struct ServerToolInvocation: Sendable {
let tool: ServerTool
let connection: any ToolServerConnection
Expand Down
10 changes: 6 additions & 4 deletions Sources/ModelRelay/Execution/WorkflowExecutor.swift
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ public actor WorkflowExecutor {
let catalog: ModelCatalog
let stepTimeout: Duration
let context: RequestContext
let toolKits: [String: ToolKit]
let toolSources: ToolSources
let toolServers: (any ToolServerConnector)?
let policy: WorkflowExecutionPolicy
let limits: WorkflowExecutionLimits
Expand All @@ -17,7 +17,8 @@ public actor WorkflowExecutor {
/// fallback model, if any). Request steps need `requests`; those that change
/// something also need a `writePolicy` that allows them. Custom bodies
/// use the same cooperative timeout and run once, without fallback.
/// Tool sets with a server need `toolServers`.
/// Tool sets with a server need `toolServers`; `hostToolKits` are tool sets
/// the app implements in Swift.
public init(
catalog: ModelCatalog = ModelCatalog(),
stepTimeout: Duration = .seconds(30),
Expand All @@ -26,6 +27,7 @@ public actor WorkflowExecutor {
writePolicy: WritePolicy = .deny,
toolKits: [ToolKit] = [],
toolServers: (any ToolServerConnector)? = nil,
hostToolKits: [HostToolKit] = [],
policy: WorkflowExecutionPolicy = .unrestricted,
limits: WorkflowExecutionLimits = .unlimited
) {
Expand All @@ -34,7 +36,7 @@ public actor WorkflowExecutor {
self.limits = limits
self.stepTimeout = stepTimeout
self.toolServers = toolServers
self.toolKits = Dictionary(toolKits.map { ($0.id, $0) }, uniquingKeysWith: { first, _ in first })
self.toolSources = ToolSources(kits: toolKits, hostKits: hostToolKits)
self.modelRuntime = WorkflowModelRuntime(catalog: catalog, stepTimeout: stepTimeout)
self.context = RequestContext(requests: requests, secrets: secrets, writePolicy: writePolicy, timeout: stepTimeout)
}
Expand Down Expand Up @@ -91,7 +93,7 @@ public actor WorkflowExecutor {

/// Does not load providers, retrieve credentials, or discover remote tools.
public func validate(_ workflow: Workflow) -> [WorkflowValidationIssue] {
workflow.validationIssues(catalog: catalog, kits: toolKits)
workflow.validationIssues(catalog: catalog, tools: toolSources)
}

func preflight(_ workflow: Workflow) throws {
Expand Down
Loading
Loading