Add a simple usage demo (#6)

Author: habedi

.gitignore

@@ -94,3 +94,4 @@ standalone-build/
 _rust.h
 uv.lock
 tests/temp_models/
+*.cast

Makefile

@@ -107,7 +107,7 @@ debug: rust-build-debug ## Build the extension in debug mode (DuckDB + extension
 # Development Targets
 # ==============================================================================
 .PHONY: install-deps
-install-deps: ## Set up development environment
+install-deps: ## Set up development environment (for Debian-based systems)
 	@echo "Setting up development environment..."
 	@sudo apt-get install -y cmake clang-format snap python3-pip
 	@sudo snap install rustup --classic
@@ -127,16 +127,16 @@ setup-hooks: ## Install Git hooks (pre-commit and pre-push)
 	@pre-commit install-hooks
 
 .PHONY: test-hooks
-test-hooks: ## Test Git hooks on all files
-	@echo "Testing Git hooks..."
+test-hooks: ## Run Git hooks on all files manually
+	@echo "Running Git hooks..."
 	@pre-commit run --all-files
 
 .PHONY: clean-all
 clean-all: clean rust-clean ## Clean everything
 	@echo "All clean!"
 
 .PHONY: check
-check: rust-lint rust-test ## Run all checks
+check: rust-lint rust-test ## Run all checks (linting and tests)
 	@echo "All checks passed!"
 
 .PHONY: examples

README.md

@@ -18,29 +18,29 @@ In-Database Machine Learning for DuckDB
 
 ---
 
-Infera is DuckDB extension that allows you use machine learning (ML) models directly in SQL queries to perform inference
-on data stored in DuckDB tables.
+Infera is a DuckDB extension that allows you to use machine learning (ML) models directly in SQL queries to perform
+inference on data stored in DuckDB tables.
 It is developed in Rust and uses [Tract](https://github.com/snipsco/tract) as the backend inference engine.
 Infera supports loading and running models in [ONNX](https://onnx.ai/) format.
-Check out the [ONNX Model Zoo](https://huggingface.co/onnxmodelzoo) repositors on Hugging Face for a large
+Check out the [ONNX Model Zoo](https://huggingface.co/onnxmodelzoo) repository on Hugging Face for a large
 collection of ready-to-use models that can be used with Infera.
 
 ### Motivation
 
-In a conventional data science workflow, when data is stored in a database, it is not normally possible to use ML models
-directly on the data.
-Users need to move the data out of the database first (for example, export it to a CSV file), load the data into a
+In a conventional data science workflow, when data is stored in a database, it is not typically possible to use ML
+models directly on the data.
+Users need to move the data out of the database first (for example, export it to a CSV file) and load the data into a
 Python or R environment, run the model there, and then import the results back into the database.
 This process is time-consuming and inefficient.
-Infera aims to solve this problem by letting users to run ML models directly in SQL queries inside the database.
+Infera aims to solve this problem by letting users run ML models directly in SQL queries inside the database.
 It simplifies the workflow and speeds up the process for users, and eliminates the need for moving data around.
 
 ### Features
 
-- Adds ML inference as first-class citizens in SQL queries.
+- Adds ML inference as a first-class citizen in SQL queries.
 - Supports loading and using local as well as remote models.
 - Supports using ML models in ONNX format with a simple and flexible API.
-- Supports performing inference on table columns or raw BLOB (tensor) data.
+- Supports performing inference on table columns or raw tensor data.
 - Supports both single-value and multi-value model outputs.
 - Supports autoloading all models from a specified directory.
 - Thread-safe, fast, and memory-efficient.
@@ -55,7 +55,7 @@ See the [ROADMAP.md](ROADMAP.md) for the list of implemented and planned feature
 
 ### Quickstart
 
-1. Clone the repository and build Infera extension from source:
+1. Clone the repository and build the Infera extension from source:
 
 ```bash
 git clone --recursive https://github.com/CogitatorTech/infera.git
@@ -94,9 +94,11 @@ select infera_unload_model('linear_model');
 select infera_get_version();
 ````
 
+[![Simple Demo 1](https://asciinema.org/a/745806.svg)](https://asciinema.org/a/745806)
+
 > [!NOTE]
 > After building from source, the Infera binary will be `build/release/extension/infera/infera.duckdb_extension`.
-> You can load it using the `load 'build/release/extension/infera/infera.duckdb_extension';` in DuckDB shell.
+> You can load it using the `load 'build/release/extension/infera/infera.duckdb_extension';` in the DuckDB shell.
 > Note that the extension binary will only work with the DuckDB version that it was built against.
 > At the moment, Infera is not available as
 > a [DuckDB community extension](https://duckdb.org/community_extensions/list_of_extensions).

docs/README.md

@@ -1,6 +1,6 @@
 ### API Reference
 
-Table below includes the information about all SQL functions exposed by the Infera.
+The table below includes the information about all SQL functions exposed by Infera.
 
 | # | Function                                                | Return Type      | Description                                                                                                                                 |
 |---|:--------------------------------------------------------|:-----------------|:--------------------------------------------------------------------------------------------------------------------------------------------|
@@ -53,7 +53,7 @@ select id,
 from features_table;
 
 -- Get multiple outputs as a JSON array.
--- This is useful models that return multiple outputs per prediction (like a non-binary classifier)
+-- This is a useful models that return multiple outputs per prediction (like a non-binary classifier)
 select infera_predict_multi('multi_output_model', 1.0, 2.0);
 -- Output: [0.85, 0.12, 0.03]
 
@@ -64,7 +64,7 @@ from my_table;
 ```
 
 > [!IMPORTANT]
-> When you use a model model for inference, in essence it will be executed on your machine.
+> When you use a model, in essence, it will be executed on your machine.
 > So make sure you download and use models from trusted sources only.
 
 #### Utility Functions
@@ -114,13 +114,13 @@ You also need to have Rust (nightly) and Cargo installed via `rustup`.
 
 2. **Install dependencies:**
 
-   The project includes a `Makefile` target to help set up the development environment. For Debian-based systems, you
-   can run:
+   The project includes a [`Makefile`](../Makefile) target to help set up the development environment. For Debian-based
+   systems, you can run:
    ```bash
    make install-deps
    ```
    This will install necessary system packages, Rust tools, and Python dependencies. For other operating systems, please
-   refer to the `Makefile` to see the list of dependencies and install them manually.
+   check the `Makefile` to see the list of dependencies and install them manually.
 
 3. **Build the extension:**
 
@@ -140,11 +140,10 @@ You also need to have Rust (nightly) and Cargo installed via `rustup`.
    without needing to run the `LOAD` command.
 
 > [!NOTE]
-> After a successful build, you can run the following binaries:
-> - `./build/release/duckdb`: this is the newest stable version of duckdb with Infera statically linked to it.
-> - `./build/release/test/unittest`: this is the test runner of duckdb (for `.test` files).
-> - `./build/release/extension/infera/infera.duckdb_extension`: this is the loadable binary that is a `.so`,
-    `.dylib`, or `.dll` file based on your platform.
+> After a successful build, you will find the following files in the `build/release/` directory:
+> - `./build/release/duckdb`: this is a DuckDB binary with the Infera extension already statically linked to it.
+> - `./build/release/test/unittest`: this is the test runner for running the SQL tests in the `test/sql/` directory.
+> - `./build/release/extension/infera/infera.duckdb_extension`: this is the loadable extension file for Infera.
 
 ---
 
@@ -163,5 +162,5 @@ Infera is made up of two main components:
    responsibilities include:
     * Defining the custom SQL functions (like `infera_load_model` and `infera_predict`).
     * Translating data from DuckDB's internal vector-based format into the raw data pointers expected by the Rust FFI.
-    * Calling the Rust functions and handling the returned results.
+    * Calling the Rust functions and handling the returned results and errors.
     * Integrating with DuckDB's extension loading mechanism.