lpsolver 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a24185adf2e045f36f5249e311b5d357ca16134ab259c4f350fddbe07e141d9c
-  data.tar.gz: 9fb91dbea34b972e32876b97b4719ef771b30b8975d9ec5bf7494a4d7d49b2d7
+  metadata.gz: d76ac229fc048afc42cb81ae328ac716095d43767fb8329ae6cdc8d8a69f8f14
+  data.tar.gz: 76b6e5e26102cc8ad5cd8fbc9da236a6b5bdd7496c5099083d0ea750d27e9000
 SHA512:
-  metadata.gz: b64322ff1240d58b92345ce8e9fff552dceeada28d57066fc56a94c02a89f66debaeeb1ccc3e37fbb434fe6619b828f91f536a5f8abc323d2792c8f8da37e4c9
-  data.tar.gz: fe8f3fba95166b9608837886d84b81adfa4d9b1416864c3607a5f194d9aaa679d36af36389ec1e6db4dc239e7d64417bd9b985a3a1a300c3c35f75597a950988
+  metadata.gz: c969d6289498dfa06bb0ed44633fa0ea0f9100aa50ec9ec3be9a1a9e11c2f2c27ad2978c7d7f802e3834692edc9fe9802742035e3847249c8bb726112a25b769
+  data.tar.gz: 45f270ac494d18748344cbc446ebf591f28af625341f424649e7f2452c880d8478bb8bde1ce7dc0ea2805cbb909e5d796dbbe5df60506e9d25e9b04e96505085

data/README.md

@@ -1,7 +1,11 @@
 # LpSolver
 
+[![test](https://github.com/davidsiaw/lpsolver/actions/workflows/test.yml/badge.svg)](https://github.com/davidsiaw/lpsolver/actions/workflows/test.yml)
+
 A Ruby gem for solving optimization problems using the [HiGHS](https://github.com/ERGO-Code/HiGHS) solver.
 
+Reference documentation can be found at https://davidsiaw.github.io/lpsolver/
+
 ## What is this for?
 
 Imagine you want to **maximize profit** or **minimize cost** while following certain rules (like a budget limit or a minimum requirement). This gem helps you find the best answer.
@@ -111,6 +115,32 @@ ruby -Ilib examples/coin_purse.rb
 
 > **HiGHS is bundled automatically.** The `rake compile` task (run during `bundle install` or `rake`) downloads the HiGHS v1.14.0 precompiled static library from GitHub and links it into the gem. No system-level HiGHS installation is required — it ships with the gem.
 
+## Solvers
+
+The Model class uses a pluggable driver architecture. By default it uses the **CLI driver** (HiGHS subprocess), but you can switch to the **native driver** (C extension) for direct in-process solving.
+
+### CLI Driver (default)
+
+The CLI driver serializes the model to HiGHS LP format and invokes the HiGHS binary as a subprocess. This is the default and most reliable approach.
+
+```ruby
+model = LpSolver::Model.new
+# Uses CliDriver by default
+solution = model.minimize!(x * 3 + y * 5)
+```
+
+### Native Driver
+
+The native driver calls the HiGHS C extension directly, bypassing file serialization. It requires the native extension to be compiled (`rake compile`).
+
+```ruby
+model = LpSolver::Model.new
+model.driver = LpSolver::NativeDriver.new
+solution = model.minimize!(x * 3 + y * 5)
+```
+
+> **Note:** The native driver is currently experimental. The CLI driver is recommended for production use.
+
 ## Usage
 
 ### Simple Example (Operator DSL)
@@ -190,6 +220,32 @@ solution = model.maximize!(x * 3 + y * 5)
 puts solution.objective_value  # => 50.0
 ```
 
+### Infeasible and Unbounded Solutions
+
+Not all problems have a valid solution. Always check the status before accessing values:
+
+```ruby
+model = LpSolver::Model.new
+x = model.add_variable(:x, lb: 0)
+y = model.add_variable(:y, lb: 0)
+
+# Contradictory constraints — no solution exists
+model.add_constraint(:c1, (x + y) <= 2)
+model.add_constraint(:c2, (x + y) >= 5)
+
+solution = model.minimize!(x + y)
+
+if solution.infeasible?
+  puts "No feasible solution exists"
+elsif solution.unbounded?
+  puts "The objective can grow without limit"
+else
+  puts "Optimal value: #{solution.objective_value}"
+end
+```
+
+> **Important:** When a solution is infeasible, `objective_value` returns `0.0` and `variables` is empty. Always call `solution.infeasible?` or `solution.unbounded?` first before reading `objective_value` or variable values.
+
 ### Complex Expressions
 
 You can chain operators with constants and unary minus:
@@ -218,7 +274,7 @@ x = model.add_variable(:x, lb: 0)
 y = model.add_variable(:y, lb: 0)
 
 model.add_constraint(:c1, (x * 2 + y) <= 10)
-model.set_objective(x + y)
+model.minimize!(x + y)
 
 # Print the LP file format
 puts model.to_lp
@@ -283,24 +339,23 @@ Set the objective to minimize and solve in one call.
 ### `Model#maximize!(objective)`
 Set the objective to maximize and solve in one call.
 
-### `Model#minimize`
-Set the optimization sense to minimization (legacy, use `minimize!` instead).
-
-### `Model#maximize`
-Set the optimization sense to maximization (legacy, use `maximize!` instead).
-
-### `Model#set_objective(objective)`
-Set the objective function without solving (legacy, use `minimize!`/`maximize!` instead).
-- `objective` can be a `LinearExpression`, `QuadraticExpression`, or Hash.
-
 ### `Model#to_lp`
 Returns the model as a HiGHS LP format string.
 
 ### `Model#write_lp(filename)`
 Writes the model to an LP file.
 
-### `Model#solve`
-Solves the model without setting an objective (legacy).
+### `Model#driver`
+Returns the current solver driver.
+
+### `Model#driver=(driver)`
+Sets the solver driver. Accepts `LpSolver::CliDriver` (default) or `LpSolver::NativeDriver`.
+
+### `LpSolver::CliDriver.new(highs_path: nil)`
+Creates a CLI driver. Uses `Model::HIGHS_PATH` by default, or the provided path.
+
+### `LpSolver::NativeDriver.new`
+Creates a native driver. Requires the native extension to be compiled.
 
 ### `Solution#[]`
 Get a variable's value. Accepts Symbol, String, or Variable object.
@@ -387,3 +442,7 @@ True if the objective can improve without limit.
 ## Code of Conduct
 
 See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+
+# Disclaimer
+
+Note that this is vibe-coded in nearly its entirety as part of a quick experiment to improve tokens per sec on my local machine and I do not recommend it for use in any sensitive environments. Note that I do not accept any responsibility for any damages or losses caused by the use of this gem, and I still expect contributed PRs to be provided in sensible and human-reviewable doses.

data/ext/lpsolver/Makefile

@@ -13,12 +13,12 @@ NULLCMD = :
 #### Start of system configuration section. ####
 
 srcdir = .
-topdir = /usr/local/include/ruby-3.4.0
+topdir = /home/node/.rvm/rubies/ruby-3.3.7/include/ruby-3.3.0
 hdrdir = $(topdir)
-arch_hdrdir = /usr/local/include/ruby-3.4.0/x86_64-linux
+arch_hdrdir = /home/node/.rvm/rubies/ruby-3.3.7/include/ruby-3.3.0/x86_64-linux
 PATH_SEPARATOR = :
 VPATH = $(srcdir):$(arch_hdrdir)/ruby:$(hdrdir)/ruby
-prefix = $(DESTDIR)/usr/local
+prefix = $(DESTDIR)/home/node/.rvm/rubies/ruby-3.3.7
 rubysitearchprefix = $(rubylibprefix)/$(sitearch)
 rubyarchprefix = $(rubylibprefix)/$(arch)
 rubylibprefix = $(libdir)/$(RUBY_BASE_NAME)
@@ -42,7 +42,6 @@ archincludedir = $(includedir)/$(arch)
 sitearchlibdir = $(libdir)/$(sitearch)
 archlibdir = $(libdir)/$(arch)
 ridir = $(datarootdir)/$(RI_BASE_NAME)
-modular_gc_dir = $(DESTDIR)
 mandir = $(datarootdir)/man
 localedir = $(datarootdir)/locale
 libdir = $(exec_prefix)/lib
@@ -79,7 +78,7 @@ COUTFLAG = -o $(empty)
 CSRCFLAG = $(empty)
 
 RUBY_EXTCONF_H = 
-cflags   = $(hardenflags)  $(optflags) $(debugflags) $(warnflags)
+cflags   = $(optflags) $(debugflags) $(warnflags)
 cxxflags = 
 optflags = -O3 -fno-fast-math
 debugflags = -ggdb3
@@ -87,19 +86,17 @@ warnflags = -Wall -Wextra -Wdeprecated-declarations -Wdiv-by-zero -Wduplicated-c
 cppflags = 
 CCDLFLAGS = -fPIC
 CFLAGS   = $(CCDLFLAGS) $(cflags)  -fPIC $(ARCH_FLAG)
-INCFLAGS = -I. -I$(arch_hdrdir) -I$(hdrdir)/ruby/backward -I$(hdrdir) -I$(srcdir) -I/home/david/programs/ai/pi/workspace/lpsolver/ext/lpsolver-highs/highs -I/home/david/programs/ai/pi/workspace/lpsolver/ext/lpsolver-highs/build/include/highs
+INCFLAGS = -I. -I$(arch_hdrdir) -I$(hdrdir)/ruby/backward -I$(hdrdir) -I$(srcdir) -I/workspace/lpsolver/ext/lpsolver-highs/build/include/highs
 DEFS     = 
 CPPFLAGS =   $(DEFS) $(cppflags)
 CXXFLAGS = $(CCDLFLAGS)  $(ARCH_FLAG)
-ldflags  = -L. -fstack-protector-strong -rdynamic -Wl,-export-dynamic -Wl,--no-as-needed -L/home/david/programs/ai/pi/workspace/lpsolver/ext/lpsolver-highs/build/lib -Wl,-rpath,/home/david/programs/ai/pi/workspace/lpsolver/ext/lpsolver-highs/build/lib
+ldflags  = -L. -fstack-protector-strong -rdynamic -Wl,-export-dynamic -Wl,--no-as-needed -L/workspace/lpsolver/ext/lpsolver-highs/build/lib
 dldflags = -Wl,--compress-debug-sections=zlib 
 ARCH_FLAG = 
 DLDFLAGS = $(ldflags) $(dldflags) $(ARCH_FLAG)
 LDSHARED = $(CC) -shared
 LDSHAREDXX = $(CXX) -shared
-POSTLINK = :
 AR = gcc-ar
-LD = ld
 EXEEXT = 
 
 RUBY_INSTALL_NAME = $(RUBY_BASE_NAME)
@@ -111,7 +108,7 @@ RUBY_BASE_NAME = ruby
 
 arch = x86_64-linux
 sitearch = $(arch)
-ruby_version = 3.4.0
+ruby_version = 3.3.0
 ruby = $(bindir)/$(RUBY_BASE_NAME)
 RUBY = $(ruby)
 BUILTRUBY = $(bindir)/$(RUBY_BASE_NAME)
@@ -131,7 +128,7 @@ TOUCH = exit >
 
 preload = 
 libpath = . $(libdir)
-LIBPATH = -L. -L$(libdir) -Wl,-rpath,$(libdir)
+LIBPATH =  -L. -L$(libdir) -Wl,-rpath,$(libdir)
 DEFFILE = 
 
 CLEANFILES = mkmf.log
@@ -266,7 +263,6 @@ $(TARGET_SO): $(OBJS) Makefile
 	$(ECHO) linking shared-object lpsolver/$(DLLIB)
 	-$(Q)$(RM) $(@)
 	$(Q) $(LDSHARED) -o $@ $(OBJS) $(LIBPATH) $(DLDFLAGS) $(LOCAL_LIBS) $(LIBS)
-	$(Q) $(POSTLINK)
 
 
 

data/ext/lpsolver/extconf.rb

@@ -11,6 +11,8 @@ highs_build = File.join(highs_src, 'build')
 
 highs_found = false
 
+
+
 # Priority: 1. HIGHS_DIR env var, 2. submodule build, 3. system paths
 highs_dir = ENV.fetch('HIGHS_DIR', nil)
 
@@ -32,23 +34,24 @@ unless highs_found
   # Check bundled submodule (CMake build or precompiled tarball)
   if File.exist?(File.join(highs_build, 'lib', 'libhighs.so')) ||
      File.exist?(File.join(highs_build, 'lib', 'libhighs.a'))
-    highs_include = File.join(highs_src, 'highs')
     highs_lib = File.join(highs_build, 'lib')
 
-    # CMake build: HConfig.h is in build dir
-    # Precompiled tarball: HConfig.h is in build/include/highs/
+    # CMake build: HConfig.h is in build dir, headers in highs/ subdir
+    # Precompiled tarball: HConfig.h is in build/include/highs/, headers in include/highs/
     highs_config = File.join(highs_build, 'HConfig.h')
     if File.exist?(highs_config)
+      # CMake build layout
+      highs_include = File.join(highs_src, 'highs')
       $INCFLAGS += " -I#{highs_include} -I#{highs_build}"
     else
-      # Precompiled tarball layout
+      # Precompiled tarball layout: headers under include/highs/
       highs_config_inc = File.join(highs_build, 'include', 'highs')
       if File.exist?(File.join(highs_config_inc, 'HConfig.h'))
-        $INCFLAGS += " -I#{highs_include} -I#{highs_config_inc}"
+        $INCFLAGS += " -I#{highs_config_inc}"
       end
     end
 
-    $LDFLAGS += " -L#{highs_lib} -Wl,-rpath,#{highs_lib}"
+    $LDFLAGS += " -L#{highs_lib}"
     $LIBS += " -lhighs -lstdc++"
     $LOAD_PATH << highs_lib
     highs_found = true
@@ -70,10 +73,10 @@ abort <<~ERROR unless highs_found
   Options:
     1. Build from submodule: rake build_highs && rake compile
     2. Set HIGHS_DIR=/path/to/highs
-    3. Install system-wide: sudo apt install highs
+    3. Install system-wide: brew install highs (macOS) or sudo apt install highs (Linux)
 
   Submodule location: #{highs_src}
-  Build output: #{highs_build}/lib/libhighs.so
+  Build output: #{highs_build}/lib/libhighs.a
 ERROR
 
 create_makefile('lpsolver/native')

data/lib/lpsolver/drivers/README.md

@@ -0,0 +1,91 @@
+# LpSolver Drivers
+
+Pluggable solving backends for `LpSolver::Model`.
+
+## API Contract
+
+Every driver must implement the following interface:
+
+### `#initialize(opts = {})`
+
+Optional constructor. Drivers may accept configuration options.
+
+| Driver | Options |
+|--------|---------|
+| `CliDriver` | `highs_path: String` — path to HiGHS binary (uses `HIGHS_PATH` resolution if omitted) |
+| `NativeDriver` | None |
+
+### `#solve(model) → Solution`
+
+Solves the given model and returns a `Solution` object.
+
+**Parameters:**
+- `model` (`LpSolver::Model`) — the model to solve
+
+**Returns:**
+- `LpSolver::Solution` — contains variable values, objective value, and model status
+
+**Raises:**
+- `LpSolver::SolverError` — if the solver encounters an error (e.g., HiGHS binary not found)
+- `LoadError` — if required dependencies are missing (e.g., native extension not compiled)
+
+## Model Data Access
+
+Drivers read model state via the following `Model` accessors:
+
+| Accessor | Type | Description |
+|----------|------|-------------|
+| `model.var_counter` | `Integer` | Number of variables |
+| `model.heading` | `Symbol` | `:minimize` or `:maximize` |
+| `model.constraints` | `Array<Hash>` | Constraint data: `{ name:, lb:, ub:, expr: [[col, coeff], ...] }` |
+| `model.constraints_data` | `Hash` | Named constraint map |
+| `model.var_types` | `Hash{Symbol => Symbol}` | Variable types: `:continuous` or `:integer` |
+| `model.objective` | `Hash{Integer => Float}` | Objective coefficients by variable index |
+| `model.quadratic_terms` | `Array<[Integer, Integer, Float]>` | Quadratic terms: `[col1, col2, coeff]` |
+| `model.var_bounds` | `Hash{Symbol => [Float, Float]}` | Variable bounds: `[lb, ub]` |
+| `model.variables` | `Hash{Symbol => Variable}` | Variable map (name → Variable object) |
+
+## Writing a Custom Driver
+
+To create a new driver:
+
+```ruby
+require 'lpsolver/drivers'
+
+module LpSolver
+  module Drivers
+    class MyCustomDriver
+      def initialize(**opts)
+        # driver-specific setup
+      end
+
+      def solve(model)
+        # 1. Read model state via model.var_counter, model.constraints, etc.
+        # 2. Call your solver
+        # 3. Return a LpSolver::Solution
+        LpSolver::Solution.new(
+          variables: { 'x' => 1.0, 'y' => 2.0 },
+          objective_value: 12.0,
+          model_status: 'optimal',
+          iterations: 0
+        )
+      end
+    end
+  end
+end
+```
+
+Then use it:
+
+```ruby
+model = LpSolver::Model.new
+model.driver = LpSolver::Drivers::MyCustomDriver.new
+solution = model.solve
+```
+
+## Available Drivers
+
+| Driver | Description | Dependencies |
+|--------|-------------|-------------|
+| `CliDriver` | HiGHS subprocess via LP file | `highs` binary |
+| `NativeDriver` | HiGHS C extension | Compiled native extension (`rake compile`) |

data/lib/lpsolver/drivers/cli_driver.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+module LpSolver
+  module Drivers
+    # Solves a model using the HiGHS command-line interface.
+    #
+    # This driver serializes the model to HiGHS LP format, invokes the
+    # HiGHS executable as a subprocess, and parses the solution file.
+    #
+    class CliDriver
+      # The path to the HiGHS binary.
+      #
+      # Resolution order:
+      #   1. Path passed to initialize
+      #   2. HIGHS_PATH environment variable
+      #   3. Bundled binary at lib/lpsolver/highs (from rake compile)
+      #   4. 'highs' on system PATH
+      #
+      # @return [String] The path to the HiGHS executable.
+      HIGHS_PATH = begin
+        env_path = ENV.fetch('HIGHS_PATH', nil)
+        if env_path
+          env_path
+        else
+          bundled = File.expand_path('../../../lib/lpsolver/highs', __dir__)
+          if File.exist?(bundled)
+            bundled
+          else
+            'highs'
+          end
+        end
+      end
+
+      # Creates a new CLI driver.
+      #
+      # @param highs_path [String, nil] Path to the HiGHS binary.
+      #   If nil, uses the default resolution order.
+      def initialize(highs_path: nil)
+        @highs_path = highs_path || HIGHS_PATH
+      end
+
+      # Solves the model using the HiGHS CLI.
+      #
+      # @param model [Model] The model to solve.
+      # @return [Solution] The solution object.
+      # @raise [SolverError] If the HiGHS solver encounters an error.
+      def solve(model)
+        lp_content = model.to_lp
+        lp_file = Tempfile.new(['model', '.lp'])
+        lp_file.write(lp_content)
+        lp_file.close
+
+        solution_file = Tempfile.new(['solution', '.sol'])
+        opts_file = Tempfile.new(['highs_opts', '.txt'])
+        opts_file.write("log_to_console = false\noutput_flag = false\n")
+        opts_file.close
+
+        cmd = "#{@highs_path} " \
+              "--model_file #{lp_file.path} " \
+              "--options_file #{opts_file.path} " \
+              "--solution_file #{solution_file.path}"
+
+        output = `#{cmd} 2>&1`
+        lp_file.unlink
+        opts_file.unlink
+
+        # HiGHS returns non-zero exit code for infeasible/unbounded problems,
+        # but still writes a valid solution file. Check for valid status instead.
+        solution_content = File.read(solution_file.path)
+        status_match = solution_content.match(/Model status\s*\n\s*(\S+)/i)
+        unless status_match
+          raise SolverError, "HiGHS solver failed:\n#{output}" unless $?.success?
+        end
+
+        parse_solution(solution_file.path)
+      ensure
+        solution_file&.unlink
+        opts_file&.unlink
+      end
+
+      private
+
+      # Parses the HiGHS solution file.
+      #
+      # @param path [String] The path to the HiGHS solution file.
+      # @return [Solution] The parsed solution object.
+      def parse_solution(path)
+        content = File.read(path)
+        variables = {}
+        objective_value = 0.0
+        model_status = 'unknown'
+
+        status_match = content.match(/Model status\s*\n\s*(\S+)/i)
+        model_status = status_match[1].downcase.gsub('_', ' ') if status_match
+
+        obj_match = content.match(/Objective\s+(\S+)/i)
+        objective_value = obj_match[1].to_f if obj_match
+
+        in_columns = false
+        content.each_line do |line|
+          if line =~ /# Columns/i
+            in_columns = true
+            next
+          end
+          next unless in_columns
+          break if line.strip.empty? || line.start_with?('#')
+
+          parts = line.strip.split(/\s+/, 2)
+          variables[parts[0]] = parts[1].to_f if parts.length == 2
+        end
+
+        Solution.new(
+          variables: variables,
+          objective_value: objective_value,
+          model_status: model_status,
+          iterations: 0
+        )
+      end
+    end
+  end
+end

data/lib/lpsolver/drivers/native_driver.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module LpSolver
+  module Drivers
+    # Solves a model using the native C extension.
+    #
+    # This driver builds HiGHS data structures directly from the model
+    # and calls the native C API, bypassing LP file serialization.
+    # It requires the native extension to be compiled and loaded.
+    #
+    class NativeDriver
+      # Solves the model using the native C extension.
+      #
+      # @param model [Model] The model to solve.
+      # @return [Solution] The solution object.
+      # @raise [LoadError] If the native extension is not available.
+      # @raise [SolverError] If the native solver encounters an error.
+      def solve(model)
+        unless defined?(LpSolver::HiGhSSolver)
+          raise LoadError, 'Native extension not available. Compile with: rake compile'
+        end
+
+        num_col = model.var_counter
+        num_row = model.constraints.size
+
+        # Determine heading — native API always minimizes, so negate for maximize
+        heading = model.heading == :maximize ? :maximize : :minimize
+
+        # Build column arrays
+        col_cost = Array.new(num_col, 0.0)
+        col_lower = Array.new(num_col)
+        col_upper = Array.new(num_col)
+        col_integrality = Array.new(num_col, 0)
+
+        model.var_bounds.each do |name, (lb, ub)|
+          idx = model.variables[name].index
+          col_lower[idx] = lb
+          col_upper[idx] = ub
+          col_integrality[idx] = model.var_types[name] == :integer ? 1 : 0
+        end
+
+        model.objective.each do |idx, coeff|
+          col_cost[idx] = heading == :maximize ? -coeff.to_f : coeff.to_f
+        end
+
+        # Build constraint arrays
+        row_lower = Array.new(num_row)
+        row_upper = Array.new(num_row)
+
+        model.constraints.each_with_index do |constr, row_idx|
+          row_lower[row_idx] = constr[:lb]
+          row_upper[row_idx] = constr[:ub]
+        end
+
+        # Build matrix in CSC (column-wise) format
+        # a_start[col] = index into a_index/a_value where column `col` starts
+        # a_index[nz] = row index of non-zero element
+        # a_value[nz] = value of non-zero element
+        nz_per_col = Array.new(num_col, 0)
+        nz_entries = []
+
+        model.constraints.each_with_index do |constr, row_idx|
+          constr[:expr].each do |col_idx, coeff|
+            nz_entries << [col_idx, row_idx, coeff.to_f]
+            nz_per_col[col_idx] += 1
+          end
+        end
+
+        total_nz = nz_entries.size
+
+        # Build a_start (cumulative column starts)
+        a_start = [0]
+        nz_per_col.each { |count| a_start << a_start.last + count }
+
+        # Sort entries by column index for CSC format
+        nz_entries.sort_by! { |col, row, _| col }
+
+        aindex = nz_entries.map { |_, row, _| row }
+        avalues = nz_entries.map { |_, _, val| val }
+
+        # Call native solver (skip if no columns/rows)
+        if num_col > 0 && num_row > 0
+          result = call_native(
+            num_col, num_row, total_nz,
+            col_cost, col_lower, col_upper, col_integrality,
+            row_lower, row_upper,
+            a_start, aindex, avalues
+          )
+        else
+          result = { status: :unbounded, objective: 0.0, col_value: [] }
+        end
+
+        # Parse result — variables are empty for infeasible/unbounded
+        variables = {}
+        unless [:infeasible, :unbounded, :unbounded_or_infeasible].include?(result[:status])
+          result[:col_value].each_with_index do |val, idx|
+            var_name = model.variables.find { |_, v| v.index == idx }&.first
+            variables[var_name.to_s] = val if var_name
+          end
+        end
+
+        Solution.new(
+          variables: variables,
+          objective_value: heading == :maximize ? -result[:objective] : result[:objective],
+          model_status: result[:status].to_s,
+          iterations: 0
+        )
+      end
+
+      private
+
+      # Calls the native HiGHS solver.
+      #
+      # @param num_col [Integer] Number of columns.
+      # @param num_row [Integer] Number of rows.
+      # @param num_nz [Integer] Number of non-zero elements.
+      # @param col_cost [Array<Float>] Column cost coefficients.
+      # @param col_lower [Array<Float>] Column lower bounds.
+      # @param col_upper [Array<Float>] Column upper bounds.
+      # @param col_integrality [Array<Integer>] Column integrality flags.
+      # @param row_lower [Array<Float>] Row lower bounds.
+      # @param row_upper [Array<Float>] Row upper bounds.
+      # @param a_start [Array<Integer>] Matrix column start indices (CSC format).
+      # @param aindex [Array<Integer>] Matrix row indices.
+      # @param avalues [Array<Float>] Matrix values.
+      # @return [Hash] Solver result with :status, :objective, :col_value, etc.
+      def call_native(num_col, num_row, num_nz, col_cost, col_lower, col_upper, col_integrality,
+                      row_lower, row_upper, a_start, aindex, avalues)
+        solver = LpSolver::HiGhSSolver.new
+        solver.num_col = num_col
+        solver.num_row = num_row
+        solver.num_nz = num_nz
+
+        solver.col_cost   = col_cost
+        solver.col_lower  = col_lower
+        solver.col_upper  = col_upper
+        solver.col_integrality = col_integrality
+
+        solver.row_lower = row_lower
+        solver.row_upper = row_upper
+
+        solver.a_start = a_start
+        solver.a_index = aindex
+        solver.a_value = avalues
+
+        solver.solve
+      end
+    end
+  end
+end

data/lib/lpsolver/drivers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Driver classes — pluggable solving backends.
+#
+# Each driver implements the same interface so Model can swap them
+# at runtime. See drivers/README.md for the API contract.
+#
+require_relative 'drivers/cli_driver'
+require_relative 'drivers/native_driver'