WIP

habedi · habedi · commit ca5fa04f7258 · 2025-09-30T22:04:55.000+02:00
diff --git a/docs/examples/README.md b/docs/examples/README.md
@@ -0,0 +1,36 @@
+# Infera Examples
+
+This directory contains DuckDB SQL scripts that show usage patterns of the Infera extension.
+Each file is self‑contained and can be executed in the DuckDB shell (or via `duckdb < file.sql`).
+
+## Prerequisites
+
+1. Build the extension:
+   ```bash
+   make release
+   ```
+2. Start the DuckDB shell from the project root directory:
+   ```bash
+   ./build/release/duckdb
+   ```
+3. Inside the shell, load a script:
+   ```sql
+   .read docs/examples/e1_core_functionality.sql
+   ```
+
+## Example Index
+
+| File                            | Topic                                | Functionalities                                                                                           |
+|---------------------------------|--------------------------------------|-----------------------------------------------------------------------------------------------------------|
+| `e1_core_functionality.sql`     | Core lifecycle                       | Version, load, inspect model info, single prediction, unload, autoload directory reuse                    |
+| `e2_advanced_features.sql`      | Remote and BLOB inference            | Remote model load (GitHub), large vision model, constructing a zero‑filled BLOB for inference             |
+| `e3_integration_and_errors.sql` | Integration patterns and errors      | Deterministic batch table, aggregation, null feature detection, missing model handling                    |
+| `e4_multi_output.sql`           | Multi‑output models                  | Uses `multi_output.onnx`, shows `infera_predict_multi` vs (commented) single‑output mismatch              |
+| `e5_autoload_and_json.sql`      | Autoload and lightweight JSON checks | Error JSON from missing dir, loading multiple models via directory scan, simple substring presence checks |
+| `e6_blob_diagnostics.sql`       | BLOB diagnostics                     | Shows correct BLOB sizing for mobilenet; commented invalid case to illustrate error path                  |
+
+## Running All Examples
+
+```bash
+make examples
+```
diff --git a/docs/examples/e1_core_functionality.sql b/docs/examples/e1_core_functionality.sql
@@ -1,69 +1,35 @@
--- Tests the core, end-to-end functionality of the extension.
+-- core functionality walkthrough (load -> info -> predict -> unload)
 .echo on
-LOAD infera;
-
--- =============================================================================
--- Test 1: Version and Initial State
--- =============================================================================
-SELECT '--- Testing Version and Initial State ---';
-
--- Check that the version function returns a valid JSON.
-SELECT infera_get_version();
-
--- Check that no models are loaded initially.
-SELECT infera_get_loaded_models() AS initial_models;
-
-
--- =============================================================================
--- Test 2: Local Model Roundtrip (Load -> Info -> Predict -> Unload)
--- =============================================================================
-SELECT '--- Testing Local Model Roundtrip ---';
-
--- Load the simple linear model.
-SELECT infera_load_model('linear', 'test/models/linear.onnx') AS loaded;
-
--- Verify the model appears in the list.
-SELECT instr(infera_get_loaded_models(), 'linear') > 0 AS after_load;
-
--- Retrieve model info and check for expected input shape.
-SELECT infera_get_model_info('linear') AS metadata;
-SELECT position('"input_shape":[1,3]' IN infera_get_model_info('linear')) > 0 AS metadata_ok;
-
--- Run deterministic predictions. Model is y = 2*x1 - 1*x2 + 0.5*x3 + 0.25
--- For (1.0, 2.0, 3.0), expected y = 1.75
-SELECT infera_predict('linear', 1.0, 2.0, 3.0) AS single_prediction;
-SELECT abs(infera_predict('linear', 1.0, 2.0, 3.0) - 1.75) < 1e-5 AS single_predict_ok;
-
--- Test the multi-output prediction function.
-SELECT infera_predict_multi('linear', 1.0, 2.0, 3.0) as multi_prediction;
-SELECT instr(infera_predict_multi('linear', 1.0, 2.0, 3.0), '1.75') > 0 AS multi_predict_ok;
-
--- Unload the model and confirm its removal.
-SELECT infera_unload_model('linear') AS unloaded;
-SELECT infera_get_loaded_models() AS after_unload;
-
-
--- =============================================================================
--- Test 3: Autoload Directory
--- =============================================================================
-SELECT '--- Testing Autoload Directory ---';
-
--- Create a temporary directory and copy the model into it.
-.shell mkdir -p test/temp_models
-.shell cp test/models/linear.onnx test/temp_models/
-
--- Run the autoload function.
-SELECT infera_set_autoload_dir('test/temp_models');
-
--- Verify the model was loaded automatically.
-SELECT instr(infera_get_loaded_models(), 'linear') > 0 AS autoloaded_model_is_listed;
-
--- Run a prediction to confirm it's functional.
-SELECT abs(infera_predict('linear', 1.0, 2.0, 3.0) - 1.75) < 1e-5 AS autoload_predict_ok;
-
--- Clean up.
-SELECT infera_unload_model('linear');
-.shell rm -rf test/temp_models
-
+load infera;
+
+-- section 1: version & initial state
+select '## version & initial state';
+select infera_get_version() as version_json;           -- shows version, backend, cache dir
+select infera_get_loaded_models() as initial_models;   -- expect []
+
+-- section 2: load model and inspect
+select '## load model';
+select infera_load_model('linear', 'test/models/linear.onnx') as loaded;  -- expect true
+select instr(infera_get_loaded_models(), 'linear') > 0 as is_listed;      -- expect 1/true
+select infera_get_model_info('linear') as model_info;                     -- contains input/output shapes
+select position('"input_shape"' in infera_get_model_info('linear')) > 0 as has_input_shape; -- expect true
+
+-- section 3: prediction
+-- model formula documented in tests: y = 2*f1 - 1*f2 + 0.5*f3 + 0.25
+select '## prediction';
+select infera_predict('linear', 1.0, 2.0, 3.0) as prediction;            -- expect 1.75
+select abs(infera_predict('linear', 1.0, 2.0, 3.0) - 1.75) < 1e-5 as prediction_ok; -- expect true
+select infera_predict_multi('linear', 1.0, 2.0, 3.0) as predict_multi;   -- single value inside list-like string
+
+-- section 4: unload
+select '## unload';
+select infera_unload_model('linear') as unloaded;                         -- expect true
+select infera_get_loaded_models() as after_unload;                        -- expect []
+
+-- section 5: autoload (reuse existing test/models directory)
+select '## autoload';
+select infera_set_autoload_dir('test/models') as autoload_result;         -- loads linear (& others if added)
+select instr(infera_get_loaded_models(), 'linear') > 0 as autoload_contains_linear; -- expect true
+select infera_unload_model('linear') as unload_after_autoload;            -- true (idempotent)
 
 .echo off
diff --git a/docs/examples/e2_advanced_features.sql b/docs/examples/e2_advanced_features.sql
@@ -1,54 +1,34 @@
--- Tests advanced features like remote model loading and BLOB inputs.
+-- advanced features: remote loading & blob inference
 .echo on
-LOAD infera;
-
--- =============================================================================
--- Test 1: Remote Model Loading
--- =============================================================================
-SELECT '--- Testing Remote Model Loading ---';
-
--- Define macros for the model name and URL for clarity.
-CREATE OR REPLACE MACRO model_name() AS 'remote_linear_model';
-CREATE OR REPLACE MACRO model_url() AS 'https://github.com/CogitatorTech/infera/raw/refs/heads/main/test/models/linear.onnx';
-
--- Load the model from the URL.
-SELECT infera_load_model(model_name(), model_url()) AS loaded_from_url;
-
--- Verify the model appears in the list.
-SELECT instr(infera_get_loaded_models(), model_name()) > 0 AS model_is_listed;
-
--- Run a prediction to confirm it's functional (y = 1.75 for these features).
-SELECT abs(infera_predict(model_name(), 1.0, 2.0, 3.0) - 1.75) < 1e-5 AS prediction_is_correct;
-
--- Unload the model to clean up.
-SELECT infera_unload_model(model_name()) AS unloaded;
-SELECT instr(infera_get_loaded_models(), model_name()) = 0 AS model_is_removed;
-
-
--- =============================================================================
--- Test 2: BLOB Input Prediction
--- =============================================================================
-SELECT '--- Testing BLOB Input Prediction ---';
-
--- Load a model that expects a large tensor input.
-SELECT infera_load_model(
-    'mobilenet',
-    'https://huggingface.co/onnxmodelzoo/tf_mobilenetv3_small_075_Opset17/resolve/main/tf_mobilenetv3_small_075_Opset17.onnx'
-);
-
--- Test error handling with an incorrectly sized BLOB.
--- This is expected to fail.
-SELECT infera_predict_from_blob('mobilenet', 'dummy_bytes');
-
--- Test with a correctly sized, zero-filled BLOB.
--- Model input is 1*224*224*3 floats. A float is 4 bytes. Total size = 602112 bytes.
-WITH const AS (
-  SELECT CAST(REPEAT(CHR(0), 602112) AS BLOB) AS zero_blob
+load infera;
+
+-- section 1: remote model loading (small linear model hosted on github)
+select '## remote model';
+create or replace macro model_name() as 'remote_linear_model';
+create or replace macro model_url() as 'https://github.com/CogitatorTech/infera/raw/refs/heads/main/test/models/linear.onnx';
+select infera_load_model(model_name(), model_url()) as loaded_remote;          -- expect true
+select instr(infera_get_loaded_models(), model_name()) > 0 as remote_listed;   -- expect true
+select abs(infera_predict(model_name(), 1.0, 2.0, 3.0) - 1.75) < 1e-5 as remote_predict_ok; -- expect true
+select infera_unload_model(model_name()) as remote_unloaded;                   -- expect true
+
+-- section 2: blob inference (mobilenet example)
+select '## blob inference';
+-- Load a vision model from huggingface (size & load time depend on network).
+select infera_load_model(
+  'mobilenet',
+  'https://huggingface.co/onnxmodelzoo/tf_mobilenetv3_small_075_Opset17/resolve/main/tf_mobilenetv3_small_075_Opset17.onnx'
+) as mobilenet_loaded;
+
+-- (optional) to see an error for an invalid blob size, you could run:
+-- select infera_predict_from_blob('mobilenet', cast('abc' as blob)); -- would error (invalid BLOB size)
+
+-- construct zero-filled blob of correct size: 1*224*224*3 floats * 4 bytes = 602112
+with zeros as (
+  select cast(repeat(chr(0), 602112) as blob) as zero_blob
 )
-SELECT len(infera_predict_from_blob('mobilenet', zero_blob)) as output_length
-FROM const;
+select len(infera_predict_from_blob('mobilenet', zero_blob)) as mobilenet_blob_output_len from zeros; -- length of output list
 
--- Clean up.
-SELECT infera_unload_model('mobilenet');
+select infera_unload_model('mobilenet') as mobilenet_unloaded;
 
+-- optional: remote multi-output or larger models could be added similarly.
 .echo off
diff --git a/docs/examples/e3_integration_and_errors.sql b/docs/examples/e3_integration_and_errors.sql
@@ -1,72 +1,47 @@
--- Tests error handling and integration with larger SQL queries.
+-- integration & error handling demo
 .echo on
-LOAD infera;
-
--- =============================================================================
--- Test 1: Error Handling for Non-existent Models
--- =============================================================================
-SELECT '--- Testing Error Handling ---';
-
--- Check info for a model that is not loaded.
-SELECT infera_get_model_info('nonexistent_model');
-
--- Try to unload a model that is not loaded.
-SELECT infera_unload_model('nonexistent_model');
-
-
--- =============================================================================
--- Test 2: Batch Processing and Aggregation
--- =============================================================================
-SELECT '--- Testing Batch Processing and Aggregation ---';
-
--- Load a model to use for batch tests.
-SELECT infera_load_model('linear', 'test/models/linear.onnx');
-
--- Create a table with sample feature data, casting to FLOAT.
-CREATE OR REPLACE TABLE features AS
-SELECT
-    row_number() OVER () as id,
-    (random() * 10)::FLOAT as f1,
-    (random() * 10)::FLOAT as f2,
-    (random() * 10)::FLOAT as f3
-FROM generate_series(1, 100);
-
--- Run prediction on a single row from the table to test integration.
--- This will now pass because the batch size is 1.
-SELECT
-    id,
-    f1, f2, f3,
-    infera_predict('linear', f1, f2, f3) as prediction
-FROM features
-WHERE id = 1;
-
--- Use the prediction function on a single row for an aggregate query.
-SELECT
-    AVG(infera_predict('linear', f1, f2, f3)) as avg_prediction,
-    COUNT(*) as total_rows
-FROM features
-WHERE id = 1;
-
-
--- =============================================================================
--- Test 3: NULL Value Handling
--- =============================================================================
-SELECT '--- Testing NULL Value Handling ---';
-
--- The current implementation should throw an error when a feature is NULL.
--- This test verifies that behavior.
-CREATE OR REPLACE TABLE features_with_nulls AS
-SELECT 1 as id, 1.0::FLOAT as f1, 2.0::FLOAT as f2, NULL::FLOAT as f3;
-
-SELECT infera_predict('linear', f1, f2, f3) FROM features_with_nulls;
-
-
--- =============================================================================
--- Cleanup
--- =============================================================================
-SELECT '--- Cleaning Up ---';
-DROP TABLE features;
-DROP TABLE features_with_nulls;
-SELECT infera_unload_model('linear');
+load infera;
+
+-- section 1: missing model behavior
+select '## missing model behavior';
+select infera_get_model_info('nonexistent_model') as missing_model_info;  -- returns JSON with error
+select infera_unload_model('nonexistent_model') as unload_missing;        -- idempotent true
+
+-- section 2: batch style predictions (deterministic)
+select '## batch predictions';
+select infera_load_model('linear', 'test/models/linear.onnx') as loaded_linear;
+-- deterministic feature set (3 rows)
+create or replace table features as
+values
+  (1, 1.0::float, 2.0::float, 3.0::float),
+  (2, 0.5::float, 1.0::float, 1.5::float),
+  (3, -1.0::float, 0.0::float, 2.0::float)
+  ;
+-- compute predictions row-wise
+select column0 as id, column1 as f1, column2 as f2, column3 as f3,
+       infera_predict('linear', column1, column2, column3) as prediction
+from features
+order by 1;
+-- aggregate over the small batch
+select avg(infera_predict('linear', column1, column2, column3)) as avg_prediction,
+       count(*) as n
+from features;
+
+-- section 3: null feature error
+select '## null feature error';
+create or replace table features_with_nulls as values (1, 1.0::float, 2.0::float, null::float);
+-- this will raise an error if executed directly; kept commented for demonstration
+-- select infera_predict('linear', column1, column2, column3) from features_with_nulls;
+
+-- instead, show detection:
+select column0 as id,
+       (column3 is null) as has_null_feature
+from features_with_nulls;
+
+-- section 4: cleanup
+select '## cleanup';
+drop table features;
+drop table features_with_nulls;
+select infera_unload_model('linear') as unloaded_linear;
 
 .echo off
diff --git a/docs/examples/e4_multi_output.sql b/docs/examples/e4_multi_output.sql
@@ -0,0 +1,22 @@
+-- multi-output model demonstration
+.echo on
+load infera;
+
+select '## load multi-output model';
+-- expects test/models/multi_output.onnx (identity: [1,4] -> [1,4])
+select infera_load_model('multi_output', 'test/models/multi_output.onnx') as loaded_multi;
+
+select '## model info';
+select infera_get_model_info('multi_output') as multi_model_info; -- shows output_shape [1,4]
+
+select '## predict_multi (returns all four values)';
+select infera_predict_multi('multi_output', 1.0, 2.0, 3.0, 4.0) as multi_output_prediction; -- expect [1,2,3,4]
+
+select '## predict (single-output API) will raise mismatch error if executed';
+-- the following is intentionally commented because it raises an error:
+-- select infera_predict('multi_output', 1.0, 2.0, 3.0, 4.0);
+
+select '## cleanup';
+select infera_unload_model('multi_output') as unloaded_multi;
+.echo off
+
diff --git a/docs/examples/e5_autoload_and_json.sql b/docs/examples/e5_autoload_and_json.sql
@@ -0,0 +1,22 @@
+-- autoload directory & lightweight json string inspection
+.echo on
+load infera;
+
+select '## autoload non-existent directory (expect error in json)';
+select infera_set_autoload_dir('nonexistent_dir___unlikely') as autoload_error_json; -- contains "error"
+
+select '## autoload existing models directory';
+select infera_set_autoload_dir('test/models') as autoload_result; -- loads linear, multi_output (if present & valid)
+select infera_get_loaded_models() as loaded_models_json;          -- e.g. ["linear","multi_output"]
+
+select '## list each loaded model info';
+-- simple split-like exploration using instr; not parsing full json to avoid extension dependency
+select 'has_linear' as label, instr(infera_get_loaded_models(), 'linear') > 0 as present
+union all
+select 'has_multi_output', instr(infera_get_loaded_models(), 'multi_output') > 0;
+
+select '## cleanup';
+select infera_unload_model('linear') as unload_linear;
+select infera_unload_model('multi_output') as unload_multi_output;
+.echo off
+
diff --git a/docs/examples/e6_blob_diagnostics.sql b/docs/examples/e6_blob_diagnostics.sql
