diff --git a/.swiftlint-baseline.json b/.swiftlint-baseline.json index 42d2f64..7657a86 100644 --- a/.swiftlint-baseline.json +++ b/.swiftlint-baseline.json @@ -267,7 +267,6 @@ {"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Models/Generation/DecisionByLanguageModel.swift","line":29,"character":21},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let text = field.textValue.trimmingCharacters(in: .whitespacesAndNewlines.union(CharacterSet(charactersIn: \"\\\"'\")))"}, {"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Models/Generation/DecisionByLanguageModel.swift","line":35,"character":21},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let text = field.textValue.trimmingCharacters(in: .whitespacesAndNewlines.union(CharacterSet(charactersIn: \"\\\"'\")))"}, {"violation":{"ruleDescription":"Use `Self` to refer to the surrounding type name","ruleIdentifier":"prefer_self_in_static_references","location":{"file":"Sources/ModelRelay/Models/Generation/Field.swift","line":8,"character":28},"reason":"Use `Self` to refer to the surrounding type name","severity":"warning","ruleName":"Prefer Self in Static References"},"text":" indirect case list(Kind)"}, -{"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Models/Generation/SchemaBuilder.swift","line":18,"character":13},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let root = DynamicGenerationSchema(name: name, properties: fields.map { field in"}, {"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Models/ModelCatalog.swift","line":7,"character":10},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case local, remote, unspecified"}, {"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Models/ModelCatalog.swift","line":7,"character":17},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case local, remote, unspecified"}, {"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Models/ModelCatalog.swift","line":7,"character":25},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case local, remote, unspecified"}, @@ -453,7 +452,7 @@ {"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 107 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 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":"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]) {"}, diff --git a/CHANGELOG.md b/CHANGELOG.md index d28729f..c36b733 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,14 @@ - A `modelrelay` agent skill and Claude Code plugin marketplace, so coding agents in host apps add the package, use the docs of their resolved version and follow the SDK's safety contracts. `make check-skill` keeps its guide links and API names in sync with the package. +- `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. + +### Fixed + +- Named schema nodes no longer share a definition when their names repeat (a tool and one of its + choice parameters, or fields in different objects), which let one replace the other's shape. ## [0.1.0] - 2026-10-18 diff --git a/Documentation/Usage.md b/Documentation/Usage.md index c65fc56..877bc13 100644 --- a/Documentation/Usage.md +++ b/Documentation/Usage.md @@ -6,8 +6,8 @@ Pick a recipe and add the integrations it needs. Models used by a step must be available in your executor's catalog. [🎯 Steps](#step-types) · [🔀 Branches](#composition) · [📦 Values](#values-and-input) · -[🌐 HTTP](#http-requests-and-agent-tools) · [☁️ Cloud](#cloud-models) · [📷 Images](#images) · -[👨‍💻 Swift](#custom-swift) · [🧰 MCP](#mcp-tools-and-oauth) · [🗳 Decisions](#decision-models) +[🧾 Nested fields](#nested-fields) · [🌐 HTTP](#http-requests-and-agent-tools) · [☁️ Cloud](#cloud-models) · +[📷 Images](#images) · [👨‍💻 Swift](#custom-swift) · [🧰 MCP](#mcp-tools-and-oauth) · [🗳 Decisions](#decision-models) @@ -87,6 +87,30 @@ Executions are independent. Opt into [conversation/handoff](ContextAndPolicies.m for shared history or selected context. `stepTimeout` defaults to 30 seconds per bounded operation, not per workflow; cancellation remains cooperative. + + +## 🧾 Extract lists of objects + +Group fields with `.object`. A list of objects reads records such as the lines of an order: + +```swift +let workflow = Workflow( + name: "Order from text" +) { + Step.extract("order", instruction: "Turn the order into lines.", model: .appleOnDevice) { + Field("lines", .list(.object([ + Field("product", .choice(["Beer", "Cola", "Fries"])), + Field("quantity", .number), + Field("note", .text), + ]))) + } +} +``` + +Each object becomes a dictionary (`{{order.lines}}` inserts the list as JSON). +Objects work wherever fields do, including tool parameters. Nested field names +only need to be unique within their object. + ## 🌐 Call an HTTP API diff --git a/Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift b/Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift index 8bd3ba9..d42eb15 100644 --- a/Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift +++ b/Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift @@ -119,7 +119,7 @@ private enum ServerArguments { case let .list(item): if let data = text.data(using: .utf8), let parsed = Value(json: data), case .list = parsed { return parsed } return .list(text.split(whereSeparator: \.isNewline).map { value(String($0).trimmingCharacters(in: .whitespaces), as: item) }) - case .text, .choice: + case .text, .choice, .object: // A JSON object or list written into a text field is sent as one. if text.hasPrefix("{") || text.hasPrefix("["), let data = text.data(using: .utf8), let parsed = Value(json: data) { return parsed diff --git a/Sources/ModelRelay/Models/Generation/Field.swift b/Sources/ModelRelay/Models/Generation/Field.swift index e2f8504..b04df8a 100644 --- a/Sources/ModelRelay/Models/Generation/Field.swift +++ b/Sources/ModelRelay/Models/Generation/Field.swift @@ -6,6 +6,9 @@ public struct Field: Codable, Sendable, Hashable { case text, number, bool case choice([String]) indirect case list(Kind) + /// Named fields of their own, such as each line of an order in a + /// `.list(.object([...]))`. The result is a dictionary. + case object([Field]) } public var name: String diff --git a/Sources/ModelRelay/Models/Generation/SchemaBuilder.swift b/Sources/ModelRelay/Models/Generation/SchemaBuilder.swift index d984aee..d44b40b 100644 --- a/Sources/ModelRelay/Models/Generation/SchemaBuilder.swift +++ b/Sources/ModelRelay/Models/Generation/SchemaBuilder.swift @@ -1,32 +1,53 @@ import AnyLanguageModel -extension Field.Kind { - func schema(named name: String) -> DynamicGenerationSchema { - switch self { - case .text: DynamicGenerationSchema(type: String.self) - case .number: DynamicGenerationSchema(type: Double.self) - case .bool: DynamicGenerationSchema(type: Bool.self) - case let .choice(options): DynamicGenerationSchema(name: name, anyOf: options) - case let .list(item): DynamicGenerationSchema(arrayOf: item.schema(named: name + "Item")) - } - } -} - enum SchemaBuilder { /// A guided-generation schema for an object with `fields`. static func object(named name: String, fields: [Field]) throws -> GenerationSchema { - let root = DynamicGenerationSchema(name: name, properties: fields.map { field in + var names: SchemaNames = .init() + return try GenerationSchema(root: names.object(named: name, fields: fields), dependencies: []) + } + + /// A schema whose only valid output is one of `labels`. + static func label(from labels: [String]) throws -> GenerationSchema { + try GenerationSchema(root: DynamicGenerationSchema(name: "Label", anyOf: labels), dependencies: []) + } +} + +/// Named nodes (objects and choices) become shared definitions keyed by name, +/// and a later node with the same name replaces an earlier one. Nested fields +/// often repeat names (`name`, `kind`), so each node gets its own. +private struct SchemaNames { + private var used: Set = [] + + mutating func object(named name: String, fields: [Field]) -> DynamicGenerationSchema { + let name: String = unique(name) + return DynamicGenerationSchema(name: name, properties: fields.map { field in DynamicGenerationSchema.Property( name: field.name, description: field.description, - schema: field.kind.schema(named: field.name) + schema: schema(field.kind, named: field.name) ) }) - return try GenerationSchema(root: root, dependencies: []) } - /// A schema whose only valid output is one of `labels`. - static func label(from labels: [String]) throws -> GenerationSchema { - try GenerationSchema(root: DynamicGenerationSchema(name: "Label", anyOf: labels), dependencies: []) + private mutating func schema(_ kind: Field.Kind, named name: String) -> DynamicGenerationSchema { + switch kind { + case .text: DynamicGenerationSchema(type: String.self) + case .number: DynamicGenerationSchema(type: Double.self) + case .bool: DynamicGenerationSchema(type: Bool.self) + case let .choice(options): DynamicGenerationSchema(name: unique(name), anyOf: options) + case let .list(item): DynamicGenerationSchema(arrayOf: schema(item, named: name + "Item")) + case let .object(fields): object(named: name, fields: fields) + } + } + + private mutating func unique(_ base: String) -> String { + var name: String = base + var suffix: Int = 2 + while !used.insert(name).inserted { + name = "\(base)\(suffix)" + suffix += 1 + } + return name } } diff --git a/Sources/ModelRelay/Workflow/Validation/Field+Validation.swift b/Sources/ModelRelay/Workflow/Validation/Field+Validation.swift new file mode 100644 index 0000000..5e06d5e --- /dev/null +++ b/Sources/ModelRelay/Workflow/Validation/Field+Validation.swift @@ -0,0 +1,31 @@ +import Foundation + +extension [Field] { + /// Why these fields can't become a guided-generation schema, nested objects included. + var schemaProblems: [String] { + var problems: [String] = [] + if Set(map(\.name)).count != count || contains(where: { $0.name.isEmpty }) { + problems.append("fields need unique nonempty names") + } + for field in self { + problems += field.kind.schemaProblems + } + return problems + } +} + +extension Field.Kind { + var schemaProblems: [String] { + switch self { + case let .choice(options): + let blank: Bool = options.contains { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty } + return options.isEmpty || blank || Set(options).count != options.count ? ["choices must be nonempty and unique"] : [] + case let .list(item): + return item.schemaProblems + case let .object(fields): + return (fields.isEmpty ? ["objects need at least one field"] : []) + fields.schemaProblems + case .text, .number, .bool: + return [] + } + } +} diff --git a/Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift b/Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift index 63b7620..434fb12 100644 --- a/Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift +++ b/Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift @@ -29,22 +29,9 @@ extension Workflow { } var names: Set = [] let knownModels = Set(catalog.ids) - func fields(_ fields: [Field], step: String) { - if Set(fields.map(\.name)).count != fields.count || fields.contains(where: { $0.name.isEmpty }) { - issue(step, .invalidSchema, "fields need unique nonempty names") - } - func kind(_ value: Field.Kind) { - switch value { - case let .choice(options): - if options.isEmpty || options.contains(where: { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }) || Set(options).count != options.count { - issue(step, .invalidSchema, "choices must be nonempty and unique") - } - case let .list(item): kind(item) - default: break - } - } - for field in fields { - kind(field.kind) + func fields(_ list: [Field], step: String) { + for problem in list.schemaProblems { + issue(step, .invalidSchema, problem) } } func visit(_ steps: [Step]) { diff --git a/Tests/ModelRelayTests/Models/LiveAppleTests.swift b/Tests/ModelRelayTests/Models/LiveAppleTests.swift index 036507f..366bcd7 100644 --- a/Tests/ModelRelayTests/Models/LiveAppleTests.swift +++ b/Tests/ModelRelayTests/Models/LiveAppleTests.swift @@ -45,6 +45,20 @@ struct LiveAppleTests { #expect(report.output["queue"] == .text("shipping")) } + @Test func onDeviceModelExtractsListsOfObjects() async throws { + let workflow: Workflow = .init(name: "Order", steps: [Step("order", .extract(instruction: "Turn the order into lines.", fields: [ + Field("lines", .list(.object([ + Field("product", .choice(["Beer", "Cola", "Fries"])), + Field("quantity", .number), + ]))), + ]), model: .appleOnDevice)]) + let report: WorkflowExecutionReport = try await WorkflowExecutor().run(workflow, input: .text("Two beers and one portion of fries, please.")) + print("LIVE order:", report.output["lines"]?.modelText ?? "", "|", report.duration) + let lines: [Value] = try #require(report.output["lines"].flatMap { if case let .list(items) = $0 { items } else { nil } }) + #expect(lines.contains(.dictionary(["product": .text("Beer"), "quantity": .number(2)]))) + #expect(lines.contains(.dictionary(["product": .text("Fries"), "quantity": .number(1)]))) + } + /// Its first use in a process prepares the model, which can take a /// minute on a Mac; later runs take a fraction of a second. @Test func appleTextRecognitionReadsTheImageOnDevice() async throws { diff --git a/Tests/ModelRelayTests/Models/NestedFieldTests.swift b/Tests/ModelRelayTests/Models/NestedFieldTests.swift new file mode 100644 index 0000000..5ae34dc --- /dev/null +++ b/Tests/ModelRelayTests/Models/NestedFieldTests.swift @@ -0,0 +1,93 @@ +import AnyLanguageModel +import Foundation +import Testing +@testable import ModelRelay + +@Suite struct NestedFieldTests { + private let order: [Field] = [ + Field("table", .text), + Field("lines", .list(.object([ + Field("kind", .choice(["add", "remove"])), + Field("product", .text), + Field("quantity", .number), + ]))), + ] + + @Test func extractReturnsListsOfObjects() async throws { + let model: ScriptedModel = .init("small", replies: [#""" + {"table": "4", "lines": [ + {"kind": "add", "product": "Beer", "quantity": 2}, + {"kind": "remove", "product": "Cola", "quantity": 1} + ]} + """#]) + let workflow: Workflow = .init(name: "Order", steps: [ + Step("order", .extract(instruction: "Read the order.", fields: order), model: "small"), + ]) + + let report: WorkflowExecutionReport = try await WorkflowExecutor(catalog: .scripted(["small": model])) + .run(workflow, input: .text("Two beers, no cola")) + + #expect(report.output["table"] == .text("4")) + #expect(report.output["lines"] == .list([ + .dictionary(["kind": .text("add"), "product": .text("Beer"), "quantity": .number(2)]), + .dictionary(["kind": .text("remove"), "product": .text("Cola"), "quantity": .number(1)]), + ])) + } + + @Test func repeatedNamesKeepTheirOwnDefinitions() throws { + let fields: [Field] = [ + Field("kind", .choice(["dine-in", "takeaway"])), + Field("lines", .list(.object([Field("kind", .choice(["add", "remove"]))]))), + Field("total", .object([Field("amount", .number)])), + ] + + let schema: GenerationSchemaJSON = try .init(SchemaBuilder.object(named: "Result", fields: fields)) + + #expect(Set(schema.definitions.keys) == ["Result", "kind", "linesItem", "kind2", "total"]) + #expect(schema.choices("kind") == ["dine-in", "takeaway"]) + #expect(schema.choices("kind2") == ["add", "remove"]) + let item: [String: Any]? = schema.definitions["linesItem"] as? [String: Any] + #expect((item?["properties"] as? [String: Any])?["kind"] as? [String: String] == ["$ref": "#/$defs/kind2"]) + } + + @Test func emptyAndDuplicateNestedFieldsArePreflightIssues() async { + let model: ScriptedModel = .init("small", replies: []) + let executor: WorkflowExecutor = .init(catalog: .scripted(["small": model])) + let workflow: Workflow = .init("Order") { + Step.extract("order", instruction: "Read.", model: "small") { + Field("empty", .object([])) + Field("lines", .list(.object([Field("product", .text), Field("product", .number)]))) + } + } + + let issues: [WorkflowValidationIssue] = await executor.validate(workflow) + + #expect(issues.count == 2) + #expect(Set(issues.map(\.detail)) == ["objects need at least one field", "fields need unique nonempty names"]) + #expect(model.callCount == 0) + } + + @Test func workflowsWithObjectsRoundTripAsJSON() throws { + let workflow: Workflow = .init(name: "Order", steps: [ + Step("order", .extract(instruction: "Read.", fields: order), model: .appleOnDevice), + ]) + + let data: Data = try JSONEncoder().encode(workflow) + + #expect(try JSONDecoder().decode(Workflow.self, from: data) == workflow) + } +} + +/// A generation schema as the JSON providers receive, to read its shared definitions. +private struct GenerationSchemaJSON { + let definitions: [String: Any] + + init(_ schema: GenerationSchema) throws { + let json: Any = try JSONSerialization.jsonObject(with: JSONEncoder().encode(schema)) + definitions = (json as? [String: Any])?["$defs"] as? [String: Any] ?? [:] + } + + func choices(_ name: String) -> [String]? { + (definitions[name] as? [String: Any])?["enum"] as? [String] + } +} diff --git a/skills/modelrelay/references/api-map.md b/skills/modelrelay/references/api-map.md index 9ee729b..45cdf9d 100644 --- a/skills/modelrelay/references/api-map.md +++ b/skills/modelrelay/references/api-map.md @@ -10,6 +10,7 @@ Read signatures in `Sources/` before calling anything not shown in a guide. | --- | --- | --- | | Generated text | `Step.prompt("summary", "Summarize.", model: .appleOnDevice)` | `Documentation/Usage.md#step-types` | | Typed fields | `Step.extract("expense", instruction: "…", model:) { Field(…) }` | `README.md#usage` | +| Lists of records | `Field("lines", .list(.object([Field(…)])))` | `Documentation/Usage.md#nested-fields` | | One label | `Step.classify("kind", "…", labels: […], model:)` | `Documentation/Usage.md#composition` | | Yes/no, choices, scores | `Step.decide("ticket", questions: [Question(…)], model:)` | `Documentation/Usage.md#decision-models` | | An answer that may call tools | `Step.agent("answer", "…", tools: [AgentTool(…)], model:)` | `Documentation/Usage.md#http-requests-and-agent-tools` |