nuget

KSemenenko · KSemenenko · commit 8b544483b463 · 2025-10-05T16:12:05.000+02:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -257,71 +257,71 @@ jobs:
           echo "version=$VERSION" >> $GITHUB_OUTPUT
           echo "Extracted version: $VERSION"
 
-      # - name: Check if tag exists
-      #   id: check_tag
-      #   run: |
-      #     if git ls-remote --tags origin | grep -q "refs/tags/v${{ steps.version.outputs.version }}"; then
-      #       echo "exists=true" >> $GITHUB_OUTPUT
-      #       echo "Tag v${{ steps.version.outputs.version }} already exists"
-      #     else
-      #       echo "exists=false" >> $GITHUB_OUTPUT
-      #       echo "Tag v${{ steps.version.outputs.version }} does not exist"
-      #     fi
-
-      # - name: Download package artifacts
-      #   if: steps.check_tag.outputs.exists == 'false'
-      #   uses: actions/download-artifact@v4
-      #   with:
-      #     name: packages
-      #     path: artifacts/packages
-
-      # - name: Publish to NuGet
-      #   if: steps.check_tag.outputs.exists == 'false'
-      #   run: |
-      #     for package in artifacts/packages/*.nupkg; do
-      #       echo "Publishing $package..."
-      #       dotnet nuget push "$package" \
-      #         --api-key ${{ secrets.NUGET_API_KEY }} \
-      #         --source https://api.nuget.org/v3/index.json \
-      #         --skip-duplicate || true
-      #     done
-
-      # - name: Create Git tag
-      #   if: steps.check_tag.outputs.exists == 'false'
-      #   run: |
-      #     git config user.name "github-actions[bot]"
-      #     git config user.email "github-actions[bot]@users.noreply.github.com"
-      #     git tag -a "v${{ steps.version.outputs.version }}" -m "Release v${{ steps.version.outputs.version }}"
-      #     git push origin "v${{ steps.version.outputs.version }}"
-
-      # - name: Generate release notes
-      #   if: steps.check_tag.outputs.exists == 'false'
-      #   id: release_notes
-      #   run: |
-      #     PREVIOUS_TAG=$(git describe --abbrev=0 --tags $(git rev-list --tags --skip=1 --max-count=1) 2>/dev/null || echo "")
-      #     if [ -z "$PREVIOUS_TAG" ]; then
-      #       COMMITS=$(git log --pretty=format:"- %s (%h)" --reverse)
-      #     else
-      #       COMMITS=$(git log ${PREVIOUS_TAG}..HEAD --pretty=format:"- %s (%h)" --reverse)
-      #     fi
-
-      #     echo "## What's Changed" > release_notes.md
-      #     echo "" >> release_notes.md
-      #     echo "$COMMITS" >> release_notes.md
-      #     echo "" >> release_notes.md
-      #     echo "## NuGet Packages" >> release_notes.md
-      #     echo "- [MLXSharp v${{ steps.version.outputs.version }}](https://www.nuget.org/packages/MLXSharp/${{ steps.version.outputs.version }})" >> release_notes.md
-      #     echo "- [MLXSharp.SemanticKernel v${{ steps.version.outputs.version }}](https://www.nuget.org/packages/MLXSharp.SemanticKernel/${{ steps.version.outputs.version }})" >> release_notes.md
-
-      #     cat release_notes.md
-
-      # - name: Create GitHub Release
-      #   if: steps.check_tag.outputs.exists == 'false'
-      #   uses: softprops/action-gh-release@v1
-      #   with:
-      #     tag_name: v${{ steps.version.outputs.version }}
-      #     name: Release v${{ steps.version.outputs.version }}
-      #     body_path: release_notes.md
-      #     files: artifacts/packages/*
-      #   env:
-      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Check if tag exists
+        id: check_tag
+        run: |
+          if git ls-remote --tags origin | grep -q "refs/tags/v${{ steps.version.outputs.version }}"; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "Tag v${{ steps.version.outputs.version }} already exists"
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "Tag v${{ steps.version.outputs.version }} does not exist"
+          fi
+
+      - name: Download package artifacts
+        if: steps.check_tag.outputs.exists == 'false'
+        uses: actions/download-artifact@v4
+        with:
+          name: packages
+          path: artifacts/packages
+
+      - name: Publish to NuGet
+        if: steps.check_tag.outputs.exists == 'false'
+        run: |
+          for package in artifacts/packages/*.nupkg; do
+            echo "Publishing $package..."
+            dotnet nuget push "$package" \
+              --api-key ${{ secrets.NUGET_API_KEY }} \
+              --source https://api.nuget.org/v3/index.json \
+              --skip-duplicate || true
+          done
+
+      - name: Create Git tag
+        if: steps.check_tag.outputs.exists == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${{ steps.version.outputs.version }}" -m "Release v${{ steps.version.outputs.version }}"
+          git push origin "v${{ steps.version.outputs.version }}"
+
+      - name: Generate release notes
+        if: steps.check_tag.outputs.exists == 'false'
+        id: release_notes
+        run: |
+          PREVIOUS_TAG=$(git describe --abbrev=0 --tags $(git rev-list --tags --skip=1 --max-count=1) 2>/dev/null || echo "")
+          if [ -z "$PREVIOUS_TAG" ]; then
+            COMMITS=$(git log --pretty=format:"- %s (%h)" --reverse)
+          else
+            COMMITS=$(git log ${PREVIOUS_TAG}..HEAD --pretty=format:"- %s (%h)" --reverse)
+          fi
+
+          echo "## What's Changed" > release_notes.md
+          echo "" >> release_notes.md
+          echo "$COMMITS" >> release_notes.md
+          echo "" >> release_notes.md
+          echo "## NuGet Packages" >> release_notes.md
+          echo "- [MLXSharp v${{ steps.version.outputs.version }}](https://www.nuget.org/packages/MLXSharp/${{ steps.version.outputs.version }})" >> release_notes.md
+          echo "- [MLXSharp.SemanticKernel v${{ steps.version.outputs.version }}](https://www.nuget.org/packages/MLXSharp.SemanticKernel/${{ steps.version.outputs.version }})" >> release_notes.md
+
+          cat release_notes.md
+
+      - name: Create GitHub Release
+        if: steps.check_tag.outputs.exists == 'false'
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          name: Release v${{ steps.version.outputs.version }}
+          body_path: release_notes.md
+          files: artifacts/packages/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -1,42 +1,27 @@
 # MLXSharp
 
-MLXSharp offers .NET bindings and tooling around [Apple MLX](https://github.com/ml-explore/mlx) that plug directly into the [`Microsoft.Extensions.AI`](https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai) ecosystem.  
-The design mirrors the packaging approach from projects such as [LLamaSharp](https://github.com/SciSharp/LLamaSharp): managed clients sit on top of a native wrapper that can be distributed through NuGet alongside prebuilt binaries.
+[![NuGet](https://img.shields.io/nuget/v/ManagedCode.MLXSharp.svg)](https://www.nuget.org/packages/ManagedCode.MLXSharp)
+[![NuGet](https://img.shields.io/nuget/v/ManagedCode.MLXSharp.SemanticKernel.svg)](https://www.nuget.org/packages/ManagedCode.MLXSharp.SemanticKernel)
 
-## Features
+MLXSharp is the first .NET wrapper around [Apple MLX](https://github.com/ml-explore/mlx) that plugs straight into [`Microsoft.Extensions.AI`](https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai). It is designed and tested on macOS (Apple silicon) but ships prebuilt native binaries for both macOS and Linux so that NuGet consumers can run out-of-the-box.
 
-- `IChatClient`, `IEmbeddingGenerator<string, Embedding<float)>`, and image generation helpers that adhere to the `Microsoft.Extensions.AI` abstractions.
-- Builder-based backend configuration with a deterministic managed implementation for tests and a P/Invoke powered native backend.
-- Native library resolver that probes application directories, `MLXSHARP_LIBRARY`, or packaged runtimes and loads `libmlxsharp` on demand.
-- Dependency injection extensions (`AddMlx`) in **MLXSharp** package.
-- Semantic Kernel integration (`AddMlxChatCompletion`) in separate **MLXSharp.SemanticKernel** package.
-- Integration test suite that exercises chat, embedding, image, and Semantic Kernel flows against both managed and native backends.
+## Highlights
+- .NET 9 / C# 13 preview friendly APIs that implement `IChatClient`, `IEmbeddingGenerator<string, Embedding<float>>`, and image helpers.
+- Dependency Injection extensions (`AddMlx`) and Semantic Kernel integration (`AddMlxChatCompletion`).
+- Native runtime loader that understands `MLXSHARP_LIBRARY`, custom paths, and packaged runtimes.
+- CI pipeline that builds the managed code once, produces macOS and Linux native libraries in parallel, and packs everything into distributable NuGet packages.
 
-## Repository Layout
-
-```
-├── extern/mlx                      # Git submodule with the official MLX sources
-├── native/                         # Native wrapper scaffold (CMake project)
-├── src/MLXSharp/                   # Managed library with Microsoft.Extensions.AI adapters + packaged runtimes
-├── src/MLXSharp.SemanticKernel/    # Semantic Kernel integration (separate package)
-└── src/MLXSharp.Tests/             # Integration tests covering DI and Semantic Kernel
-```
-
-## Prerequisites
-
-The solution targets .NET 9 / C# 13 previews. Install the SDK via the official installer script:
+## Quick Start
+Add the package and wire it into the service collection:
 
 ```bash
-curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --version 9.0.305
-export PATH="$PATH:$HOME/.dotnet"
-dotnet --version
+dotnet add package ManagedCode.MLXSharp
 ```
 
-## Getting Started
-
-Register MLX services through dependency injection:
-
 ```csharp
+using Microsoft.Extensions.DependencyInjection;
+using MLXSharp;
+
 var services = new ServiceCollection();
 services.AddMlx(builder =>
 {
@@ -46,87 +31,86 @@ services.AddMlx(builder =>
         options.EmbeddingModelId = "mlx-embedding";
     });
 
-    // Managed fallback backend (default) that keeps tests deterministic.
     builder.UseManagedBackend(new MlxManagedBackend());
-
-    // Or switch to the native backend once libmlxsharp is available.
+    // Switch to the native backend when libmlxsharp.{dylib|so} is available.
     // builder.UseNativeBackend();
 });
+
+var provider = services.BuildServiceProvider();
+var chat = provider.GetRequiredService<IChatClient>();
+var reply = await chat.GetResponseAsync("hello MLX", CancellationToken.None);
 ```
 
-Semantic Kernel integration uses the same builder experience:
+### Semantic Kernel
+
+```bash
+dotnet add package ManagedCode.MLXSharp.SemanticKernel
+```
 
 ```csharp
+using Microsoft.SemanticKernel;
+using MLXSharp.SemanticKernel;
+
 var kernelBuilder = Kernel.CreateBuilder();
 kernelBuilder.AddMlxChatCompletion(b => b.UseManagedBackend(new MlxManagedBackend()));
 var kernel = kernelBuilder.Build();
 
-var chat = kernel.Services.GetRequiredService<IChatCompletionService>();
 var history = new ChatHistory();
 history.AddUserMessage("Summarise MLX in one sentence");
-var response = await chat.GetChatMessageContentsAsync(history, new PromptExecutionSettings(), kernel, CancellationToken.None);
+var response = await kernel
+    .GetRequiredService<IChatCompletionService>()
+    .GetChatMessageContentsAsync(history, new PromptExecutionSettings(), kernel, CancellationToken.None);
 ```
 
-## NuGet Packages
-
-### MLXSharp [![NuGet](https://img.shields.io/nuget/v/MLXSharp.svg)](https://www.nuget.org/packages/MLXSharp)
-
-Core package with `Microsoft.Extensions.AI` integration:
-
-```bash
-dotnet add package MLXSharp
+## Repository Layout
 ```
-
-This package contains:
-- Managed DLL with `Microsoft.Extensions.AI` implementations
-- Native assets in `runtimes/{rid}/native/`:
-  - `runtimes/linux-x64/native/libmlxsharp.so.b64` - Base64-encoded stub that `MlxNativeLibrary` expands for CI/testing
-  - `runtimes/osx-arm64/native/libmlxsharp.dylib` - built in CI on macOS
-
-`MlxNativeLibrary` materialises `libmlxsharp.so` from the encoded payload on first use so Git history stays free of binary blobs while tests retain deterministic behaviour.
-
-### MLXSharp.SemanticKernel [![NuGet](https://img.shields.io/nuget/v/MLXSharp.SemanticKernel.svg)](https://www.nuget.org/packages/MLXSharp.SemanticKernel)
-
-Semantic Kernel integration:
-
-```bash
-dotnet add package MLXSharp.SemanticKernel
+extern/mlx/                  # MLX sources (git submodule)
+native/                      # CMake project that builds libmlxsharp
+src/MLXSharp/                # Managed MLXSharp library + runtime assets
+src/MLXSharp.SemanticKernel/ # Semantic Kernel integration
+src/MLXSharp.Tests/          # Integration tests
 ```
 
-This package depends on MLXSharp and adds Semantic Kernel chat completion service.
-
-### How It Works
-
-GitHub Actions automatically:
-1. Compiles native wrapper with MLX submodule
-2. Copies `libmlxsharp.dylib` to `src/MLXSharp/runtimes/osx-arm64/native/`
-3. Packs managed + native together in NuGet package
-
-At runtime `MlxNativeLibrary` automatically finds the right library:
-- Checks `MlxClientOptions.LibraryPath`
-- Checks `MLXSHARP_LIBRARY` environment variable
-- Searches in `runtimes/{rid}/native/` (NuGet unpacks automatically)
-- Fallback to system library search paths
-
-To build the native wrapper locally (mirroring the LLamaSharp workflow):
-
-```bash
-git submodule update --init --recursive
-cmake -S native -B native/build -DCMAKE_BUILD_TYPE=Release
-cmake --build native/build
-export MLXSHARP_LIBRARY=$(pwd)/native/build/libmlxsharp.dylib
-```
-
-The CMake project vendors the official [mlx](https://github.com/ml-explore/mlx) sources as a submodule and
-builds them alongside `libmlxsharp`. On non-macOS hosts the configuration automatically disables the Metal backend;
-pass `-DMLX_BUILD_METAL=ON` if you are compiling on Apple silicon and want GPU support. Additional MLX switches can be
-forwarded on the command line, for example `-DMLX_BUILD_BLAS_FROM_SOURCE=ON` when targeting systems without an OpenBLAS
-installation.
-
-## Running Tests
+## Building the native wrapper locally
+1. Install .NET 9, CMake, and ensure Xcode command-line tools (macOS) or build-essential + OpenBLAS/LAPACK headers (Linux) are available.
+2. Sync submodules:
+   ```bash
+   git submodule update --init --recursive
+   ```
+3. Build for your platform:
+   ```bash
+   # macOS (Apple silicon)
+   cmake -S native -B native/build/macos -DCMAKE_BUILD_TYPE=Release
+   cmake --build native/build/macos
+   export MLXSHARP_LIBRARY=$(pwd)/native/build/macos/libmlxsharp.dylib
+
+   # Linux
+   cmake -S native -B native/build/linux -DCMAKE_BUILD_TYPE=Release
+   cmake --build native/build/linux
+   export MLXSHARP_LIBRARY=$(pwd)/native/build/linux/libmlxsharp.so
+   ```
+4. Run your application or `dotnet pack` with explicit paths:
+   ```bash
+   dotnet pack src/MLXSharp/MLXSharp.csproj \
+       -p:MLXSharpMacNativeBinary=$PWD/native/build/macos/libmlxsharp.dylib \
+       -p:MLXSharpLinuxNativeBinary=$PWD/native/build/linux/libmlxsharp.so
+   ```
+
+The CMake project vendored from MLX builds MLX and the shim in one go. macOS builds enable Metal automatically; disable or tweak MLX options by passing flags such as `-DMLX_BUILD_METAL=OFF` or `-DMLX_BUILD_BLAS_FROM_SOURCE=ON`.
+
+## CI overview
+1. `dotnet-build` (Ubuntu): restores the solution and compiles managed projects.
+2. `native-linux` / `native-macos`: compile `libmlxsharp.so` and `libmlxsharp.dylib` in parallel.
+3. `package-test` (macOS): downloads both native artifacts, stages them into `src/MLXSharp/runtimes/{rid}/native`, rebuilds, runs the integration tests, and produces NuGet packages.
+
+## Testing
+Tests require a local MLX model bundle. Point `MLXSHARP_MODEL_PATH` to the directory before running:
 
 ```bash
+export MLXSHARP_MODEL_PATH=$PWD/models/Qwen1.5-0.5B-Chat-4bit
+huggingface-cli download mlx-community/Qwen1.5-0.5B-Chat-4bit --local-dir "$MLXSHARP_MODEL_PATH"
 dotnet test
 ```
 
-The suite validates the managed backend, Semantic Kernel extensions, and the native loader by exercising the packaged stub library.
+## Versioning & platform support
+This initial release is focused on macOS developers who want MLX inside .NET applications. Linux binaries are produced to keep NuGet packages complete, and Windows support is not yet available.
diff --git a/src/MLXSharp.SemanticKernel/MLXSharp.SemanticKernel.csproj b/src/MLXSharp.SemanticKernel/MLXSharp.SemanticKernel.csproj
@@ -6,4 +6,13 @@
   <ItemGroup>
     <ProjectReference Include="..\MLXSharp\MLXSharp.csproj" />
   </ItemGroup>
-</Project>
+
+  <!-- NuGet metadata -->
+  <PropertyGroup>
+    <Title>ManagedCode.MLXSharp.SemanticKernel</Title>
+    <PackageId>ManagedCode.MLXSharp.SemanticKernel</PackageId>
+    <Description>Semantic Kernel chat completion integration built on top of MLXSharp.</Description>
+    <PackageTags>managedcode;mlx;semantic-kernel;ai;dotnet;chat;apple</PackageTags>
+  </PropertyGroup>
+
+</Project>
diff --git a/src/MLXSharp/MLXSharp.csproj b/src/MLXSharp/MLXSharp.csproj
@@ -3,6 +3,14 @@
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
   </PropertyGroup>
 
+  <!-- NuGet metadata -->
+  <PropertyGroup>
+    <Title>ManagedCode.MLXSharp</Title>
+    <PackageId>ManagedCode.MLXSharp</PackageId>
+    <Description>.NET bindings for Apple MLX with Microsoft.Extensions.AI integration and packaged native runtimes.</Description>
+    <PackageTags>managedcode;mlx;apple;ai;dotnet;microsoft-extensions-ai;native</PackageTags>
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.AI" Version="9.9.1" />
   </ItemGroup>
