Add structural tag

Author: petrukha-ivan

Sources/CMLXStructured/grammar_compiler.cpp

@@ -60,6 +60,24 @@ extern "C" void* compile_json_schema_grammar(
     }
 }
 
+extern "C" void* compile_structural_tag(
+    void* tokenizer_info,
+    const char* structural_tag_utf8,
+    size_t structural_tag_len
+) {
+    try {
+        const std::string structural_tag(structural_tag_utf8, structural_tag_len);
+        auto& tokenizer_info_ptr = *static_cast<TokenizerInfo*>(tokenizer_info);
+        auto* compiled_grammar_ptr = new CompiledGrammar(
+            GrammarCompiler(tokenizer_info_ptr).CompileStructuralTag(structural_tag)
+        );
+        return compiled_grammar_ptr;
+    } catch (const std::exception& e) {
+        catch_error(e.what());
+        return nullptr;
+    }
+}
+
 extern "C" void compiled_grammar_free(void* compiled_grammar) {
     if (compiled_grammar) {
         delete static_cast<CompiledGrammar*>(compiled_grammar);

Sources/CMLXStructured/include/mlx_structured/grammar_compiler.h

@@ -25,6 +25,12 @@ void* compile_json_schema_grammar(
     int indent
 );
 
+void* compile_structural_tag(
+    void* tokenizer_info,
+    const char* structural_tag_utf8,
+    size_t structural_tag_len
+);
+
 void compiled_grammar_free(void* compiled_grammar);
 
 #ifdef __cplusplus

Sources/MLXStructured/Backends/XGrammar.swift

@@ -97,6 +97,10 @@ final class XGrammar {
             schema.utf8CString.withUnsafeBufferPointer {
                 compile_json_schema_grammar(tokenizerInfo, $0.baseAddress, $0.count, Int32(indent ?? -1))
             }
+        case .structural(let tag):
+            tag.utf8CString.withUnsafeBufferPointer {
+                compile_structural_tag(tokenizerInfo, $0.baseAddress, $0.count)
+            }
         }
 
         defer {

Sources/MLXStructured/Grammar+Generable.swift renamed to Sources/MLXStructured/Grammar/Grammar+Generable.swift

@@ -17,12 +17,7 @@ public extension Grammar {
     static func schema<Content: Generable>(generable type: Content.Type, indent: Int? = nil) throws -> Grammar {
         let encoder = JSONEncoder()
         let data = try encoder.encode(type.generationSchema)
-        guard let string = String(data: data, encoding: .utf8) else {
-            throw EncodingError.invalidValue(
-                type,
-                EncodingError.Context(codingPath: [], debugDescription: "Failed to encode generation schema using UTF-8.")
-            )
-        }
+        let string = String(decoding: data, as: UTF8.self)
         return .schema(string, indent: indent)
     }
 }

Sources/MLXStructured/Grammar/Grammar+Schema.swift

@@ -0,0 +1,18 @@
+//
+//  Grammar+Schema.swift
+//  MLXStructured
+//
+//  Created by Ivan Petrukha on 04.10.2025.
+//
+
+import Foundation
+import JSONSchema
+
+public extension Grammar {
+    static func schema(_ schema: JSONSchema = .object(), indent: Int? = nil) throws -> Grammar {
+        let encoder = JSONEncoder()
+        let data = try encoder.encode(schema)
+        let string = String(decoding: data, as: UTF8.self)
+        return .schema(string, indent: indent)
+    }
+}

Sources/MLXStructured/Grammar/Grammar+Structural.swift

@@ -0,0 +1,18 @@
+//
+//  Grammar+Structural.swift
+//  MLXStructured
+//
+//  Created by Ivan Petrukha on 27.09.2025.
+//
+
+import Foundation
+
+public extension Grammar {
+    init(@FormatBuilder _ content: () -> Encodable) throws {
+        let tag = StructuralTag(format: content())
+        let encoder = JSONEncoder()
+        let data = try encoder.encode(tag)
+        let string = String(decoding: data, as: UTF8.self)
+        self = Grammar.structural(string)
+    }
+}

Sources/MLXStructured/Grammar.swift renamed to Sources/MLXStructured/Grammar/Grammar.swift

@@ -12,19 +12,12 @@ public enum Grammar {
     case ebnf(String)
     case regex(String)
     case schema(String, indent: Int? = nil)
-}
-
-public extension Grammar {
-    static func schema(_ schema: JSONSchema = .object(), indent: Int? = nil) throws -> Grammar {
-        let encoder = JSONEncoder()
-        let data = try encoder.encode(schema)
-        let string = String(decoding: data, as: UTF8.self)
-        return .schema(string, indent: indent)
-    }
+    case structural(String)
 }
 
 public extension Grammar {
 
+    @available(*, deprecated, message: "Prefer constructing prompt manually, this property will be removed in the future versions")
     var raw: String {
         switch self {
         case .ebnf(let ebnf):
@@ -33,9 +26,12 @@ public extension Grammar {
             return regex
         case .schema(let schema, _):
             return schema
+        case .structural(let tag):
+            return tag
         }
     }
 
+    @available(*, deprecated, message: "Prefer constructing prompt manually, this property will be removed in the future versions")
     var guidance: String? {
         switch self {
         case .ebnf:
@@ -44,6 +40,8 @@ public extension Grammar {
             return "Output is regex constrained: \(regex)"
         case .schema(let schema, _):
             return "Output is JSON schema constrained: \(schema)"
+        case .structural:
+            return nil
         }
     }
 }

Sources/MLXStructured/Structural/StructuralTag+Builder.swift

@@ -0,0 +1,141 @@
+//
+//  StructuralTag+Builder.swift
+//  MLXStructured
+//
+//  Created by Ivan Petrukha on 25.09.2025.
+//
+
+@resultBuilder
+public enum FormatBuilder {
+    
+    public static func buildExpression(_ expression: Encodable) -> Encodable {
+        expression
+    }
+    
+    public static func buildBlock(_ component: Encodable) -> Encodable {
+        component
+    }
+    
+    public static func buildOptional(_ component: Encodable?) -> Encodable {
+        component ?? AnyTextFormat()
+    }
+    
+    public static func buildEither(first component: Encodable) -> Encodable {
+        component
+    }
+    
+    public static func buildEither(second component: Encodable) -> Encodable {
+        component
+    }
+    
+    public static func buildLimitedAvailability(_ component: Encodable) -> Encodable {
+        component
+    }
+}
+
+@resultBuilder
+public enum FormatListBuilder {
+    
+    public static func buildExpression(_ expression: Encodable) -> [Encodable] {
+        [expression]
+    }
+    
+    public static func buildBlock(_ components: [Encodable]...) -> [Encodable] {
+        components.flatMap { $0 }
+    }
+    
+    public static func buildOptional(_ component: [Encodable]?) -> [Encodable] {
+        component ?? []
+    }
+    
+    public static func buildEither(first component: [Encodable]) -> [Encodable] {
+        component
+    }
+    
+    public static func buildEither(second component: [Encodable]) -> [Encodable] {
+        component
+    }
+    
+    public static func buildArray(_ components: [[Encodable]]) -> [Encodable] {
+        components.flatMap { $0 }
+    }
+    
+    public static func buildLimitedAvailability(_ component: [Encodable]) -> [Encodable] {
+        component
+    }
+}
+
+@resultBuilder
+public enum TagListBuilder {
+    
+    public static func buildExpression(_ expression: TagFormat) -> [TagFormat] {
+        [expression]
+    }
+    
+    public static func buildBlock(_ components: [TagFormat]...) -> [TagFormat] {
+        components.flatMap { $0 }
+    }
+    
+    public static func buildOptional(_ component: [TagFormat]?) -> [TagFormat] {
+        component ?? []
+    }
+    
+    public static func buildEither(first component: [TagFormat]) -> [TagFormat] {
+        component
+    }
+    
+    public static func buildEither(second component: [TagFormat]) -> [TagFormat] {
+        component
+    }
+    
+    public static func buildArray(_ components: [[TagFormat]]) -> [TagFormat] {
+        components.flatMap { $0 }
+    }
+    
+    public static func buildLimitedAvailability(_ component: [TagFormat]) -> [TagFormat] {
+        component
+    }
+}
+
+public extension StructuralTag {
+    init(@FormatBuilder _ content: () -> Encodable) {
+        self.init(format: content())
+    }
+}
+
+public extension SequenceFormat {
+    init(@FormatListBuilder _ content: () -> [Encodable]) {
+        self.init(elements: content())
+    }
+}
+
+public extension OrFormat {
+    init(@FormatListBuilder _ content: () -> [Encodable]) {
+        self.init(elements: content())
+    }
+}
+
+public extension TagFormat {
+    init(begin: String, end: String, @FormatBuilder _ content: () -> Encodable) {
+        self.init(begin: begin, content: content(), end: end)
+    }
+}
+
+public extension TriggeredTagsFormat {
+    init(triggers: [String], options: Options = [], @TagListBuilder _ content: () -> [TagFormat]) {
+        self.init(triggers: triggers, tags: content(), options: options)
+    }
+}
+
+
+public extension OrFormat {
+    mutating func appending(_ formats: [Encodable]) -> OrFormat {
+        OrFormat(elements: self.elements + formats)
+    }
+}
+
+public extension SequenceFormat {
+    mutating func appending(_ formats: [Encodable]) -> SequenceFormat {
+        SequenceFormat(elements: self.elements + formats)
+    }
+}