jpy-ml

// 3 lines. Auto-downloads model, runs inference, returns typed results.
try (Model model = Model.preset("yolov8n")) {
    DetectionResult result = model.predict("photo.jpg");
    System.out.println(result.toJson());   // {"task":"detect","count":6,"boxes":[...]}
}

// Auto-detect task from model file
try (Model model = new Model("yolov8n.pt")) { ... }

// Explicit task type (for custom-named models)
try (Model model = new Model("my_custom_detector.pt", TaskType.DETECT)) { ... }

// Specify device: CPU, MPS (Apple Silicon), GPU
ModelConfig config = new ModelConfig()
    .device(Device.cpu());
ModelConfig config = new ModelConfig()
    .device(Device.mps());
ModelConfig config = new ModelConfig()
    .device(Device.gpu(0));
ModelConfig config = new ModelConfig()
    .device(Device.cuda(0));
ModelConfig config = new ModelConfig()
    .device(Device.fromString("cuda:0"));

PythonRuntime.init(pythonPath, jepLibPath);

try (Model model = new Model("yolov8n.pt")) {
    System.out.println(model.getModelInfo());  // ModelInfo{task=DETECT, classes=80, ...}

    DetectionResult result = model.predict("photo.jpg");

    for (ClassPrediction pred : result.getBoxes()) {
        System.out.println(pred);
        // person 92.3% BoundingBox[x1=100.5, y1=50.2, x2=300.1, y2=400.8]
    }

    // Filter results
    List<ClassPrediction> persons = result.filterByClass("person");
    List<ClassPrediction> confident = result.filterByConfidence(0.8f);

    // Timing
    InferenceSpeed speed = result.getSpeed();
    System.out.printf("Inference: %.1fms%n", speed.inferenceMs());
}

try (Model model = new Model("yolov8n-seg.pt")) {
    SegmentationResult result = model.predict("photo.jpg");

    for (int i = 0; i < result.getBoxes().size(); i++) {
        ClassPrediction pred = result.getBoxes().get(i);
        Mask mask = result.getMasks().get(i);
        System.out.println(pred.className() + " mask points: " + mask.getPointCount());
    }
}

try (Model model = new Model("yolov8n-cls.pt")) {
    ClassificationResult result = model.predict("photo.jpg");

    System.out.println("Top prediction: " + result.getTop1ClassName());
    System.out.println("Confidence: " + result.getTop1Confidence());
}

try (Model model = new Model("yolov8n-pose.pt")) {
    PoseResult result = model.predict("photo.jpg");

    for (int i = 0; i < result.personCount(); i++) {
        KeypointCollection kpts = result.getKeypoints().get(i);
        Keypoint nose = kpts.getNose();       // COCO keypoint #0
        Keypoint lShoulder = kpts.get(5);     // COCO keypoint #5
        System.out.printf("Person %d: nose=(%.1f,%.1f)%n", i, nose.x(), nose.y());
    }
}

try (Model model = new Model("yolov8n-obb.pt")) {
    OBBResult result = model.predict("satellite_image.jpg");

    for (OBBPrediction pred : result.getPredictions()) {
        RotatedBoundingBox box = pred.box();
        System.out.printf("%s %.1f%% at (%.1f,%.1f) %.1fx%.1f angle=%.1f%n",
            pred.className(), pred.confidence() * 100,
            box.centerX(), box.centerY(), box.width(), box.height(),
            box.angleDegrees());
    }
}

ModelConfig config = new ModelConfig()
    .confidence(0.5f)        // Confidence threshold
    .iouThreshold(0.7f)      // NMS IoU threshold
    .imageSize(640)           // Input image size
    .maxDetections(100)       // Max detections per image
    .device(Device.gpu(0))   // CPU / MPS / GPU device
    .augment(true)            // Test-time augmentation
    .agnosticNms(true)        // Class-agnostic NMS
    .filterClasses(0, 2, 5)   // Only detect persons, cars, buses
    .retinaMasks(true)        // High-quality segmentation masks
    .half(true)               // FP16 inference (GPU)
    .verbose(false)           // Suppress output
    .save(true)               // Save results to disk
    .saveTxt(true)            // Save as .txt
    .saveCrop(true)           // Save cropped predictions
    .embed(0, 1, 2);          // Extract feature embeddings

InferenceResult result = model.predict("photo.jpg", config);

TrainingConfig config = new TrainingConfig()
    .dataConfig("coco128.yaml")
    .epochs(50)
    .batchSize(16)
    .device(Device.gpu(0))       // Train on GPU
    .optimizer(OptimizerType.ADAMW)
    .learningRate(0.001f)
    .augmentation(new AugmentationConfig()
        .mosaic(true)
        .fliplr(0.5f)
        .hsvH(0.015f));

// With epoch callback
TrainingResult result = model.train(config, (epoch, log) -> {
    System.out.println("Epoch " + epoch + ": " + log);
});
System.out.println("Best model: " + result.getBestModelPath());
System.out.println("Best fitness: " + result.getBestFitness());

// Epoch metrics
for (EpochMetric m : result.getEpochMetrics()) {
    System.out.printf("Epoch %d: box=%.4f cls=%.4f dfl=%.4f%n",
        m.epoch(), m.boxLoss(), m.clsLoss(), m.dflLoss());
}

ValidationResult val = model.validate("coco128.yaml");
System.out.printf("mAP50=%.3f, mAP50-95=%.3f, P=%.3f, R=%.3f%n",
    val.getMAP50(), val.getMAP5095(), val.getPrecision(), val.getRecall());

// Per-class metrics
for (PerClassMetric pc : val.getPerClassMetrics()) {
    System.out.println(pc);  // "person (id=0): mAP50-95=0.7234"
}

ExportResult exported = model.export(ExportFormat.ONNX);
System.out.println("Exported to: " + exported.getOutputPath());
System.out.println("File size: " + exported.getFileSizeMB());

ImageAnnotator annotator = new ImageAnnotator();

try (Model model = new Model("yolov8n.pt")) {
    InferenceResult result = model.predict("photo.jpg");
    String annotated = annotator.annotate(result, "output.jpg");
}

try (Model model = new Model("yolov8n.pt")) {
    List<String> images = List.of("photo1.jpg", "photo2.jpg", "photo3.jpg");
    List<InferenceResult> results = model.predict(images);

    for (int i = 0; i < results.size(); i++) {
        System.out.println("Image " + i + ": " + results.get(i).count() + " objects");
    }
}

try (Model model = new Model("yolov8n.pt")) {
    // Video file — processes frame-by-frame with chunked streaming
    model.predictVideo("video.mp4", frame -> {
        System.out.println("Frame: " + frame.count() + " objects");
    });

    // Webcam — real-time inference (blocks current thread)
    // Call stopStream() from another thread to stop
    new Thread(() -> {
        Thread.sleep(10000);
        model.stopStream();  // Stop after 10 seconds
    }).start();

    model.predictStream(0, frame -> {
        // frame 0 = default webcam
        if (frame instanceof DetectionResult dr) {
            System.out.println("Camera: " + dr.getBoxes().size() + " objects");
        }
    });
}

try (Model model = new Model("yolov8n.pt")) {
    // Zero-copy prediction for detection tasks
    RawDetectionResult result = model.predictRaw("photo.jpg");

    // Option 1: Strongly-typed access (lazy-loaded)
    for (ClassPrediction pred : result.getBoxes()) {
        System.out.println(pred);
    }

    // Option 2: Raw buffer access (zero allocation)
    FloatBuffer xyxy = result.getRawBoxesXYXY();  // (N, 4) float buffer
    FloatBuffer conf = result.getRawConfidences();  // (N,) float buffer
    IntBuffer cls = result.getRawClassIds();        // (N,) int buffer

    for (int i = 0; i < result.getBoxCount(); i++) {
        int offset = i * 4;
        System.out.printf("Box: (%.1f,%.1f,%.1f,%.1f) conf=%.2f cls=%d%n",
            xyxy.get(offset), xyxy.get(offset+1),
            xyxy.get(offset+2), xyxy.get(offset+3),
            conf.get(i), cls.get(i));
    }

    // Release buffers back to pool for reuse
    result.release();
}

try (Model model = new Model("yolov8n.pt")) {
    // Warmup: run dummy inference to trigger CUDA kernel compilation
    model.warmup();

    // Inference...
    model.predict("photo.jpg");

    // Unload model from GPU to free memory
    model.unload();

    // Reload to GPU
    model.reload("cuda:0");
}

// Point prompt: segment what's at (320, 240)
try (SAM2Model sam = new SAM2Model("sam2.1_t.pt")) {
    SAM2Result result = sam.predict("photo.jpg",
        Prompt.point(320, 240)
    );

    for (Mask mask : result.getMasks()) {
        System.out.println("Mask points: " + mask.getPointCount());
    }
    System.out.println("Best score: " + result.bestScore());
}

// Box prompt: segment inside bounding box
SAM2Result result = sam.predict("photo.jpg",
    Prompt.box(100, 100, 400, 400)
);

// Multiple prompts with negative points
SAM2Result result = sam.predict("photo.jpg",
    Prompt.point(200, 200),                          // positive
    Prompt.point(400, 300, Prompt.Label.NEGATIVE)    // negative
);

try (SAM2Model sam = new SAM2Model("sam2.1_t.pt")) {
    // Start tracking with initial bounding box
    try (SAM2VideoTracker tracker = sam.trackVideo("video.mp4",
            Prompt.box(100, 100, 400, 400))) {

        // Add more prompts at specific frames
        tracker.addPrompt(10, Prompt.point(300, 200));

        // Propagate through all frames
        SAM2VideoResult result = tracker.propagate();
        System.out.println("Tracked " + result.trackedFrameCount() + " frames");
    }
}

// Text-based concept segmentation
try (SAM3Model sam = new SAM3Model("sam3.pt")) {
    SAM3Result result = sam.predictText("street.jpg", "person", "bus");

    for (Mask mask : result.getMasks()) {
        System.out.println("Mask: " + mask.getPointCount() + " points");
    }

    // Filter by confidence score
    SAM3Result filtered = result.filterByScore(0.5f);
}

// Image exemplar: "find things like this"
try (SAM3Model sam = new SAM3Model("sam3.pt")) {
    BoundingBox exemplarBox = new BoundingBox(10, 20, 200, 300);
    SAM3Result result = sam.predictExemplar("target.jpg", "reference.jpg",
        exemplarBox);
}

OpenCVEngine cv = new OpenCVEngine();

// Read image info
OpenCVEngine.ImageInfo info = cv.imread("photo.jpg");
System.out.println(info.width() + "x" + info.height());

// Color conversion
cv.cvtColor("photo.jpg", "gray.jpg", "BGR2GRAY");

// Edge detection
cv.canny("photo.jpg", "edges.jpg", 100, 200);

// Gaussian blur
cv.blur("photo.jpg", "blurred.jpg", 15);

// Find contours
OpenCVEngine.ContourResult contours = cv.findContours("binary.jpg", "contours.jpg");
System.out.println("Found " + contours.count() + " contours");

MediaPipeEngine mp = new MediaPipeEngine();

// Hand detection
MediaPipeEngine.HandResult hands = mp.detectHands("hand.jpg");
for (MediaPipeEngine.HandResult.Hand hand : hands.hands()) {
    for (MediaPipeEngine.HandResult.Landmark lm : hand.landmarks()) {
        System.out.printf("Landmark: (%.3f, %.3f, %.3f)%n", lm.x(), lm.y(), lm.z());
    }
}

// Face mesh
MediaPipeEngine.FaceResult faces = mp.detectFace("face.jpg");
System.out.println("Faces found: " + faces.count());

// Pose estimation
MediaPipeEngine.PoseResult pose = mp.detectPose("pose.jpg");
System.out.println("Pose landmarks: " + pose.count());

// Auto-download + load in one line
try (Model model = Model.preset("yolov8n")) {
    DetectionResult result = model.predict("photo.jpg");
}

// List available models
for (ModelHub.ModelEntry entry : ModelHub.listAvailable()) {
    System.out.println(entry);  // "yolov8n (6.2 MB, DETECT)"
}

try (Model model = new Model("yolov8n.pt")) {
    // From byte[] (e.g., HTTP upload, file read)
    byte[] imageData = Files.readAllBytes(Path.of("photo.jpg"));
    InferenceResult result = model.predict(imageData);

    // From BufferedImage (e.g., Java image processing)
    BufferedImage image = ImageIO.read(new File("photo.jpg"));
    InferenceResult result = model.predict(image);
}

try (Model model = new Model("yolov8n.pt")) {
    // Returns CompletableFuture
    CompletableFuture<InferenceResult> future = model.predictAsync("photo.jpg");
    future.thenAccept(result -> {
        System.out.println("Detected " + result.count() + " objects");
    });
}

DetectionResult result = model.predict("photo.jpg");

// JSON output (no external dependencies)
String json = result.toJson();
// {"task":"detect","source":"photo.jpg","count":3,"boxes":[...]}

// Map output (for Jackson/Gson integration)
Map<String, Object> map = result.toMap();

// Works on SAM results too
SAM2Result samResult = sam.predict("photo.jpg", Prompt.point(100, 200));
String samJson = samResult.toJson();

ImageVisualizer viz = new ImageVisualizer()
    .lineWidth(2.5f)
    .fontSize(14.0f)
    .maskAlpha(0.4f);

BufferedImage image = ImageIO.read(new File("photo.jpg"));
InferenceResult result = model.predict("photo.jpg");

// Draw boxes/masks/keypoints on image
BufferedImage annotated = viz.visualize(image, result);
ImageIO.write(annotated, "jpg", new File("output.jpg"));

// Or from byte[]
byte[] annotatedBytes = viz.visualizeToBytes(imageBytes, result);

// Download model from HuggingFace Hub (cached at ~/.jpy-ml/llm-models/)
LLMModel model = LLMModel.download("Qwen/Qwen2.5-0.5B-Instruct");

// Or load from local path
LLMModel model = LLMModel.load("/path/to/local/model");

// Chat inference
ChatResponse response = model.chat(
    ChatMessage.system("You are a helpful assistant"),
    ChatMessage.user("Hello, introduce yourself in one sentence")
);

System.out.println(response.getContent());
System.out.println("Tokens: prompt=" + response.getPromptTokens()
    + " completion=" + response.getCompletionTokens());

// With generation config
ChatResponse response = model.chat(
    List.of(
        ChatMessage.system("You are a helpful assistant"),
        ChatMessage.user("Explain quantum computing")
    ),
    GenerationConfig.create()
        .maxNewTokens(256)
        .temperature(0.7)
        .topP(0.9)
        .repetitionPenalty(1.1)
);

LLMModel model = LLMModel.load("Qwen/Qwen2.5-0.5B-Instruct")
    .quantize(Quantization.NONE); // macOS

// Synchronous fine-tuning with real-time callbacks
LLMTrainingResult result = model.fineTune()
    .lora(LoRAConfig.create().rank(8).alpha(16))
    .dataset("training_data.jsonl")
    .config(LLMTrainConfig.create()
        .epochs(3)
        .batchSize(4)
        .gradientAccumulation(4)
        .learningRate(2e-4)
        .maxSeqLength(2048)
        .gradientCheckpointing(true))
    .run((step, log) -> {
        System.out.println("Step " + step + ": " + log);
    });

System.out.println("Adapter saved to: " + result.getAdapterPath());
System.out.println("Final loss: " + result.getFinalLoss());

// Load base model with trained LoRA adapter
LLMModel finetuned = LLMModel.load("Qwen/Qwen2.5-0.5B-Instruct")
    .adapter("/path/to/adapter");

ChatResponse response = finetuned.chat(
    ChatMessage.user("What is your name?")
);
System.out.println(response.getContent());

CompletableFuture<LLMTrainingResult> future = model.fineTune()
    .lora(LoRAConfig.create().rank(4).alpha(8))
    .dataset("data.jsonl")
    .config(LLMTrainConfig.create().epochs(2))
    .runAsync((step, log) -> {
        System.out.println("[async] " + log);
    });

// Do other work...

LLMTrainingResult result = future.get(10, TimeUnit.MINUTES);

LLMTrainingResult result = model.fineTune()
    .dataset("data.jsonl")
    .config(LLMTrainConfig.create().epochs(3))
    .run();

// Merge LoRA adapter into base model for standalone deployment
String mergedPath = LLMModel.mergeAdapter(
    model.getModelPath(),
    result.getAdapterPath(),
    "/path/to/merged-model"
);

// Quick generation (Schnell, 4 steps)
try (FluxModel flux = new FluxModel("black-forest-labs/FLUX.1-schnell")) {
    FluxResult result = flux.generate("A cat in space", "cat.png");
    System.out.println("Output: " + result.getFirstOutputPath());
    System.out.println("Time: " + result.getElapsedSeconds() + "s");
}

// High quality (Dev, 20 steps)
FluxConfig config = FluxConfig.dev()
    .width(1920)
    .height(1080)
    .steps(30)
    .guidance(7.5f)
    .seed(42);

try (FluxModel flux = new FluxModel("black-forest-labs/FLUX.1-dev")) {
    FluxResult result = flux.generate("A beautiful sunset", "sunset.png", config);
}

// Image-to-image
try (FluxModel flux = new FluxModel("black-forest-labs/FLUX.1-schnell")) {
    FluxResult result = flux.img2img(
        "Oil painting style", "input.png", "output.png",
        new FluxConfig().steps(10)
    );
}

PythonRuntime.init(pythonPath, jepLibPath);
PythonEngine engine = PythonEngine.getInstance();

// Variables
engine.put("name", "World");
engine.exec("greeting = f'Hello, {name}!'");
String msg = engine.get("greeting");  // "Hello, World!"

// Functions
engine.exec("def fib(n):\n    a, b = 0, 1\n    for _ in range(n):\n        a, b = b, a + b\n    return a\n");
long fib10 = engine.eval("fib(10)");  // 55

// NumPy
engine.exec("import numpy as np");
engine.exec("arr = np.arange(10).reshape(2, 5).tolist()");
List<?> data = engine.get("arr");

// Stdout capture
engine.exec("for i in range(3): print(f'item {i}')",
    line -> System.out.println("[py] " + line),
    null  // stderr callback
);