Types

public struct DocumentInfo: Codable {
    public let id: String
    public let text: String
    public let metadata: [String: String]?   // optional, defaults to nil
    public let embedding: [Float]?            // optional, defaults to nil
    public let payload: String?              // optional, verbatim — defaults to nil
}

public init<P: Encodable>(id: String, text: String,
                          metadata: [String: String]? = nil,
                          embedding: [Float]? = nil, structured: P) throws
public func decodedPayload<P: Decodable>(_ type: P.Type) throws -> P?

public struct QueryOptions {
    public var topK: Int        // default 5
    public var alpha: Float     // default 0.8
    public var filter: Filter?
    public var filterJson: String?
    public var groupByParent: ParentGrouping?
}

public struct SearchResult {
    public let docs: [QueryResult]
    public let query: String
    public let timeMs: UInt64
}

public struct QueryResult {
    public let id: String
    public let score: Float
    public let text: String
    public let metadata: [String: String]?
    public let payload: String?
}

public indirect enum Filter {
    case equals(String, FilterValue)
    case notEquals(String, FilterValue)
    case greaterThan(String, FilterValue)
    case greaterThanOrEqual(String, FilterValue)
    case lessThan(String, FilterValue)
    case lessThanOrEqual(String, FilterValue)
    case isIn(String, [FilterValue])
    case notIn(String, [FilterValue])
    case near(field: String, lat: Double, lng: Double, withinMeters: Double)
    case and([Filter])
    case or([Filter])
    case raw(String)   // escape hatch: raw engine-format JSON
}

public enum FilterValue {
    case string(String)
    case int(Int)
    case double(Double)
    case bool(Bool)
}

public struct ParentGrouping {
    public var parentField: String   // e.g. "article_id"
    public var orderField: String    // e.g. "chunk_index"
}

public struct GetDocsOptions {
    public var ids: [String]?            // exact ids, returned in this order
    public var filter: Filter?           // metadata predicate
    public var sortBy: String?           // metadata field to order by (numeric-aware)
    public var ascending: Bool           // default true
    public var groupByParent: ParentGrouping?
}

public struct ModelRef {
    public let id: String
    public let version: String?
}

public struct IndexInfo {
    public let id: String
    public let name: String
    public let status: String
    public let docCount: Int
    public let model: ModelRef
    public let version: String?
    public let createdAt: String?
    public let updatedAt: String?
}

public struct SessionOptions {
    public var modelId: String?              // optional, defaults to nil
    public var vectorQuantization: VectorQuantization = .default
    public var autoLoadOnInit: Bool = true
}

public enum VectorQuantization: UInt8 {
    case `default` = 0   // platform-appropriate (INT8 on iOS)
    case fp32 = 1        // full 32-bit precision
    case int8 = 2        // 8-bit scalar quantization (smaller on disk)
}

public struct PushIndexResult {
    public let jobId: String
    public let indexName: String
    public let docCount: Int
    public let status: String
}

public struct MutationResult {
    public let jobId: String
    public let indexName: String
    public let docCount: Int
}

public struct RefreshResult {
    public let indexName: String
    public let previousUpdatedAt: String
    public let newUpdatedAt: String
    public let wasUpdated: Bool
}

public struct JobStatus {
    public let jobId: String
    public let status: String
    public let progress: Double
    public let currentPhase: String?
    public let error: String?
    public let createdAt: String
    public let updatedAt: String
    public let completedAt: String?
}

public enum MemoryPressureLevel: UInt8 {
    case low = 0        // hint: drop hot caches
    case critical = 1   // drop everything reclaimable; on-disk caches kept
}

public struct MossError: LocalizedError {
    public let code: Int32
    public let message: String
}