ClipSmokeTest.kt

    private fun testTokenizerMatchesPython() {
        val storm = ClipText.tokenize("storm")
        check("\"storm\" tokenizes exactly as Python does", storm.contentEquals(REF_IDS_STORM)) {
            "got ${storm.toList()}, expected ${REF_IDS_STORM.toList()}"
        }
        val cat = ClipText.tokenize("a photo of a cat")
        check("a longer prompt tokenizes exactly as Python does", cat.contentEquals(REF_IDS_CAT)) {
            "got ${cat.toList()}, expected ${REF_IDS_CAT.toList()}"
        }
        check("start-of-text is first", storm.first() == 49406L) { "got ${storm.first()}" }
        check("end-of-text is last", storm.last() == 49407L) { "got ${storm.last()}" }
        println("  tokenizer: \"storm\" -> ${storm.toList()}")
    }

    private fun testTextEmbeddings(): Map<String, ClipVector> {
        val prompts = listOf("storm", "calm", "a photo of a cat", "a photo of a dog")
        val embeddings = ClipText.encodeAll(prompts)

        embeddings.forEach { (prompt, v) ->
            near("\"$prompt\" is unit length", v.norm, 1f)
            check("\"$prompt\" is all finite", v.values.all { it.isFinite() }) { "found NaN or Inf" }
        }

        val storm = embeddings.getValue("storm")
        for (i in REF_STORM_FIRST4.indices) {
            near("storm component $i matches Python", storm.values[i], REF_STORM_FIRST4[i])
        }

        // The one-argument form the documentation actually teaches. `public/docs/onnx.md` writes
        // `clipEncode("…")` six times and writes `ClipText.encodeAll` nowhere, and until 2026-08-27
        // nothing in CI called it: every assertion in this file went through the batch entry point
        // underneath it, so the name on the page was type-checked and never run. One line, no extra
        // model load — the text encoder is already resident by here — and it makes the published
        // spelling a checked one. Found by `DocumentedApiEvaluationTest`, which lists the APIs a
        // published page teaches that CI only ever compiles.
        val viaDocumentedForm = clipEncode("storm")
        check(
            "clipEncode(\"storm\") is the same vector as the batch form",
            viaDocumentedForm.values.contentEquals(storm.values)
        ) {
            "the documented one-liner and ClipText.encodeAll disagree; cosine " +
                "${viaDocumentedForm.cosine(storm)}"
        }

        fun cos(a: String, b: String) = embeddings.getValue(a).cosine(embeddings.getValue(b))
        near("cos(storm, calm)", cos("storm", "calm"), REF_COS_STORM_CALM)
        near("cos(cat, dog)", cos("a photo of a cat", "a photo of a dog"), REF_COS_CAT_DOG)
        near("cos(storm, cat)", cos("storm", "a photo of a cat"), REF_COS_STORM_CAT)
        near("cos(calm, dog)", cos("calm", "a photo of a dog"), REF_COS_CALM_DOG)

        // The property that makes an absolute threshold useless, asserted rather than described.
        check(
            "text-text cosines all sit in a narrow high cone",
            listOf(
                cos("storm", "calm"), cos("storm", "a photo of a cat"),
                cos("calm", "a photo of a dog"), cos("a photo of a cat", "a photo of a dog")
            ).all { it > 0.75f }
        ) { "expected every text-text cosine above 0.75" }
        check(
            "two phrasings of an animal photo are closer than storm is to calm",
            cos("a photo of a cat", "a photo of a dog") > cos("storm", "calm")
        ) { "cat/dog ${cos("a photo of a cat", "a photo of a dog")} vs storm/calm ${cos("storm", "calm")}" }

        println("  text: cos(storm,calm)=${"%.6f".format(cos("storm", "calm"))} " +
            "cos(cat,dog)=${"%.6f".format(cos("a photo of a cat", "a photo of a dog"))}")
        return embeddings
    }

    private fun testSemanticAxis(texts: Map<String, ClipVector>) {
        val axis = texts.getValue("calm") axisTo texts.getValue("storm")
        near("the axis is unit length", axis.norm, 1f)

        val stormward = texts.getValue("storm").project(axis)
        val calmward = texts.getValue("calm").project(axis)
        check("the axis orders its own endpoints", stormward > calmward) {
            "storm projects to $stormward, calm to $calmward"
        }
        // Antisymmetry: reversing the endpoints negates every projection.
        val reversed = texts.getValue("storm") axisTo texts.getValue("calm")
        near("reversing the axis negates the projection", texts.getValue("storm").project(reversed), -stormward)
    }

    private fun testImageEmbeddingAndModalityGap(texts: Map<String, ClipVector>) {
        val encoder = ClipImage()
        val image = encoder.encode(syntheticRgba(Clip.IMAGE_SIZE), Clip.IMAGE_SIZE, Clip.IMAGE_SIZE)
        near("the image embedding is unit length", image.norm, 1f)
        check("the image embedding is all finite", image.values.all { it.isFinite() }) { "found NaN or Inf" }

        near("cos(image, storm)", image.cosine(texts.getValue("storm")), REF_IMAGE_COS_STORM)
        near("cos(image, calm)", image.cosine(texts.getValue("calm")), REF_IMAGE_COS_CALM)
        near("cos(image, cat)", image.cosine(texts.getValue("a photo of a cat")), REF_IMAGE_COS_CAT)
        near("cos(image, dog)", image.cosine(texts.getValue("a photo of a dog")), REF_IMAGE_COS_DOG)

        // The modality gap: every image-text cosine is far below every text-text cosine. This is the
        // reason `classify` compares candidates against each other instead of against a constant.
        val imageTextMax = texts.values.maxOf { image.cosine(it) }
        check("every image-text cosine is far below the text-text cone", imageTextMax < 0.5f) {
            "highest image-text cosine was $imageTextMax"
        }
        println("  image: ${encoder.lastInferenceMs}ms on ${encoder.activeProvider}, " +
            "best text cosine ${"%.6f".format(imageTextMax)}")
    }

    private fun testFileEmbeddingsAreDeterministic() {
        val dir = java.io.File("public/docs/assets/madp_tetra")
        val names = listOf("tabby_cat", "labrador", "tiger", "toyota_sports_800")
        val files = names.map { dir.resolve("$it.jpg") }
        check("the tetra sample photographs are present", files.all { it.isFile }) { "missing under ${dir.absolutePath}" }
        if (!files.all { it.isFile }) return

        val first = files.map { clipEncodeImage(it) }
        val second = files.map { clipEncodeImage(it) }
        check("encoding the same file twice gives the same vector, bit for bit",
            first.zip(second).all { (a, b) -> a.values.contentEquals(b.values) }) { "a re-encode differed" }
        first.forEachIndexed { i, v -> near("${names[i]} is unit length", v.norm, 1f) }

        // The BufferedImage route and the RGBA-buffer route are one preprocessing, not two.
        val image = javax.imageio.ImageIO.read(files[0])
        val rgba = ByteBuffer.allocateDirect(image.width * image.height * 4)
        for (y in 0 until image.height) for (x in 0 until image.width) {
            val p = image.getRGB(x, y)
            rgba.put((p shr 16 and 0xff).toByte()).put((p shr 8 and 0xff).toByte()).put((p and 0xff).toByte()).put(-1)
        }
        rgba.rewind()
        val direct = ClipImage().encode(rgba, image.width, image.height)
        check("clipEncodeImage matches ClipImage.encode on the same pixels", direct.values.contentEquals(first[0].values)) {
            "cosine between the two routes ${direct.cosine(first[0])}"
        }

        val simplex = afield.math.statistics.embeddingSimplex(first, names)
        val again = afield.math.statistics.embeddingSimplex(second, names)
        check("the six distances are the same on a second encode",
            simplex.edges.zip(again.edges).all { (a, b) -> a.distance == b.distance }) { "$simplex\nvs\n$again" }
        check("four photographs make an exact tetrahedron", simplex.exact) { "stress ${simplex.stress1}" }
        println("  tetra photographs:\n" + simplex.toString().prependIndent("    "))
    }

    private fun testClassifyIsSoftmaxOverCandidates(texts: Map<String, ClipVector>) {
        val image = ClipImage().encode(syntheticRgba(Clip.IMAGE_SIZE), Clip.IMAGE_SIZE, Clip.IMAGE_SIZE)
        val ranked = image.classify(texts)
        check("classify returns every candidate", ranked.size == texts.size) { "got ${ranked.size}" }
        near("probabilities sum to 1", ranked.sumOf { it.second.toDouble() }.toFloat(), 1f)
        check("classify is sorted most likely first", ranked.zipWithNext().all { it.first.second >= it.second.second }) {
            "not descending: ${ranked.map { it.second }}"
        }
        check("best() agrees with classify()", image.best(texts) == ranked.first()) {
            "best=${image.best(texts)} first=${ranked.first()}"
        }
        // Ranking must follow cosine order and be independent of the temperature.
        val byCosine = texts.entries.sortedByDescending { image.cosine(it.value) }.map { it.key }
        check("ranking follows cosine order", ranked.map { it.first } == byCosine) {
            "classify ${ranked.map { it.first }} vs cosine $byCosine"
        }
        val hotter = image.classify(texts, logitScale = 500f).map { it.first }
        check("temperature does not change ranking", hotter == ranked.map { it.first }) {
            "at 500: $hotter, at default: ${ranked.map { it.first }}"
        }
        check("classify of nothing is empty", image.classify(emptyMap()).isEmpty()) { "expected empty" }
        println("  classify: ${ranked.joinToString { "${it.first}=${"%.4f".format(it.second)}" }}")
    }