chore(python): organize packages folder

Author: Daniele Briggi

.github/workflows/python-package.yml

@@ -58,7 +58,7 @@ jobs:
 
       - name: Install build dependencies
         run: |
-          cd python-package
+          cd packages/python
           python3 -m pip install --upgrade pip
           python3 -m pip install -r requirements-dev.txt
 
@@ -75,20 +75,20 @@ jobs:
 
       - name: Download artifacts for current platform
         run: |
-          cd python-package
+          cd packages/python
           python3 download_artifacts.py "${{ matrix.plat_name }}" "${{ steps.get_version.outputs.version }}"
 
       - name: Build wheel
         env:
           PACKAGE_VERSION: ${{ steps.get_version.outputs.version }}
         run: |
-          cd python-package
+          cd packages/python
           python setup.py bdist_wheel --plat-name "${{ matrix.plat_name }}"
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          packages-dir: python-package/dist
+          packages-dir: packages/python/dist
           verbose: true
           # Avoid workflow to fail if the version has already been published
           skip-existing: true

README.md

@@ -40,6 +40,17 @@ Download the appropriate pre-built binary for your platform from the official [R
 SELECT load_extension('./ai');
 ```
 
+### Python Package
+
+Python developers can quickly get started using the ready-to-use `sqlite-ai` package available on PyPI:
+
+```bash
+pip install sqlite-ai
+```
+
+For usage details and examples, see the [Python package documentation](./packages/python/README.md).
+
+
 ## Getting Started
 
 Here's a quick example to get started with SQLite Sync:

python-package/.gitignore packages/python/.gitignorepython-package/.gitignore renamed to packages/python/.gitignore

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include src/sqliteai/binaries *

packages/python/MANIFEST.in

@@ -0,0 +1,49 @@
+## SQLite AI Python package
+
+This package provides the sqlite-ai extension prebuilt binaries for multiple platforms and architectures.
+
+### SQLite-AI
+
+SQLite-AI is an extension for SQLite that brings artificial intelligence capabilities directly into the database. It enables developers to run, fine-tune, and serve AI models from within SQLite using simple SQL queries — ideal for on-device and edge applications where low-latency and offline inference are critical. The extension is actively developed by [SQLite AI](https://sqlite.ai), some API and features are still evolving.
+
+More details on the official repository [sqliteai/sqlite-ai](https://github.com/sqliteai/sqlite-ai).
+
+### Documentation
+
+For detailed information on all available functions, their parameters, and examples, refer to the [comprehensive API Reference](https://github.com/sqliteai/sqlite-ai/blob/main/API.md).
+
+### Supported Platforms and Architectures
+
+| Platform      | Arch         | Subpackage name         | Binary name |
+| ------------- | ------------ | ----------------------- | ----------- |
+| Linux (CPU)   | x86_64/arm64 | sqliteai.binaries.cpu   | ai.so       |
+| Linux (GPU)   | x86_64/arm64 | sqliteai.binaries.gpu   | ai.so       |
+| Windows (CPU) | x86_64       | sqliteai.binaries.cpu   | ai.dll      |
+| Windows (GPU) | x86_64       | sqliteai.binaries.gpu   | ai.dll      |
+| macOS (CPU)   | x86_64/arm64 | sqliteai.binaries.cpu   | ai.dylib    |
+
+## Usage
+
+> **Note:** Some SQLite installations on certain operating systems may have extension loading disabled by default.   
+If you encounter issues loading the extension, refer to the [sqlite-extensions-guide](https://github.com/sqliteai/sqlite-extensions-guide/) for platform-specific instructions on enabling and using SQLite extensions.
+
+```python
+import importlib.resources
+import sqlite3
+
+# Connect to your SQLite database
+conn = sqlite3.connect("example.db")
+
+# Load the sqlite-ai extension
+# pip will install the correct binary package for your platform and architecture
+# Choose between CPU or GPU variant
+ext_path = importlib.resources.files("sqliteai.binaries.cpu") / "ai"
+
+conn.enable_load_extension(True)
+conn.load_extension(str(ext_path))
+conn.enable_load_extension(False)
+
+
+# Now you can use sqlite-ai features in your SQL queries
+print(conn.execute("SELECT ai_version();").fetchone())
+```

packages/python/README.md

@@ -0,0 +1,99 @@
+import sys
+import zipfile
+import requests
+from pathlib import Path
+import shutil
+
+
+# == USAGE ==
+# python3 download_artifacts.py PLATFORM VERSION
+#   eg: python3 download_artifacts.py linux_x86_64 "0.5.9"
+
+REPO = "sqliteai/sqlite-ai"
+RELEASE_URL = f"https://github.com/{REPO}/releases/download"
+
+# Map Python plat_name to artifact names
+ARTIFACTS = {
+    "manylinux2014_x86_64": ["ai-linux-cpu-x86_64", "ai-linux-gpu-x86_64"],
+    "manylinux2014_aarch64": [
+        "ai-linux-cpu-arm64",
+        "ai-linux-gpu-arm64",
+    ],
+    "win_amd64": ["ai-windows-cpu-x86_64", "ai-windows-gpu-x86_64"],
+    "macosx_10_9_x86_64": ["ai-macos"],
+    "macosx_11_0_arm64": ["ai-macos"],
+}
+
+BINARY_NAME = {
+    "manylinux2014_x86_64": "ai.so",
+    "manylinux2014_aarch64": "ai.so",
+    "win_amd64": "ai.dll",
+    "macosx_10_9_x86_64": "ai.dylib",
+    "macosx_11_0_arm64": "ai.dylib",
+}
+
+BINARIES_DIR = Path(__file__).parent / "src/sqliteai/binaries"
+
+
+def download_and_extract(artifact_name, bin_name, version):
+    artifact = f"{artifact_name}-{version}.zip"
+    url = f"{RELEASE_URL}/{version}/{artifact}"
+    print(f"Downloading {url}")
+
+    r = requests.get(url)
+    if r.status_code != 200:
+        print(f"Failed to download {artifact}: {r.status_code}")
+        sys.exit(1)
+
+    zip_path = BINARIES_DIR / artifact
+    with open(zip_path, "wb") as f:
+        f.write(r.content)
+
+    subdir = "gpu" if "gpu" in artifact_name else "cpu"
+    out_dir = BINARIES_DIR / subdir
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    with zipfile.ZipFile(zip_path, "r") as zip_ref:
+        for member in zip_ref.namelist():
+            if member.endswith(bin_name):
+                zip_ref.extract(member, out_dir)
+
+                # Move to expected name/location
+                src = out_dir / member
+                dst = out_dir / bin_name
+                src.rename(dst)
+
+                print(f"Extracted {dst}")
+
+    zip_path.unlink()
+
+
+def main():
+    version = None
+    platform = None
+    if len(sys.argv) == 3:
+        platform = sys.argv[1].lower()
+        version = sys.argv[2]
+
+    if not version or not platform:
+        print(
+            'Error: Version is not specified.\nUsage: \n   python3 download_artifacts.py linux_x86_64 "0.5.9"'
+        )
+        sys.exit(1)
+
+    print(BINARIES_DIR)
+    if BINARIES_DIR.exists():
+        shutil.rmtree(BINARIES_DIR)
+    BINARIES_DIR.mkdir(parents=True, exist_ok=True)
+
+    platform_artifacts = ARTIFACTS.get(platform, [])
+    if not platform_artifacts:
+        print(f"Error: Unknown platform '{platform}'")
+        sys.exit(1)
+
+    for artifact_name in platform_artifacts:
+        download_and_extract(artifact_name, BINARY_NAME[platform], version)
+
+
+if __name__ == "__main__":
+    main()

packages/python/download_artifacts.py

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel", "toml"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlite-ai"
+dynamic = ["version"]
+description = "Python prebuilt binaries for SQLite AI extension for all supported platforms and architectures."
+authors = [
+    { name = "SQLite AI Team" }
+]
+readme = "README.md"
+requires-python = ">=3"
+classifiers = []
+
+[project.urls]
+Homepage = "https://sqlite.ai"
+Documentation = "https://github.com/sqliteai/sqlite-ai/blob/main/API.md"
+Repository = "https://github.com/sqliteai/sqlite-ai"
+Issues = "https://github.com/sqliteai/sqlite-ai/issues"