sqlite-jev 0.1.0__tar.gz

sqlite_jev-0.1.0/.github/workflows/cd.yml

@@ -0,0 +1,110 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: ${{ matrix.platform }}
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-24.04
+            platform: linux-x86_64
+          - runner: ubuntu-24.04-arm
+            platform: linux-aarch64
+          - runner: macos-15-intel
+            platform: macos-x86_64
+          - runner: macos-15
+            platform: macos-arm64
+    steps:
+      - uses: actions/checkout@v7
+      - name: Verify tag matches package version
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: test "${RELEASE_TAG#v}" = "$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+      - name: Install Linux dependencies
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y sqlite3 libsqlite3-dev curl
+      - name: Install macOS dependencies
+        if: runner.os == 'macOS'
+        run: |
+          brew install sqlite
+          echo "$(brew --prefix sqlite)/bin" >> "$GITHUB_PATH"
+          echo "CPPFLAGS=-I$(brew --prefix sqlite)/include" >> "$GITHUB_ENV"
+      - run: make test
+      - name: Build native extension archive
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: make package PACKAGE_NAME="sqlite-jev-${RELEASE_TAG#v}-${{ matrix.platform }}"
+      - name: Build and test Python wheel
+        uses: pypa/cibuildwheel@v3.3.0
+        env:
+          CIBW_ARCHS: native
+      - uses: actions/upload-artifact@v7
+        with:
+          name: native-extension-${{ matrix.platform }}
+          path: build/*.tar.gz
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v7
+        with:
+          name: python-wheel-${{ matrix.platform }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.1.0
+      - run: uv build --sdist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: python-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  release-assets:
+    name: Upload GitHub release assets
+    needs: [build, sdist]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Write checksums
+        working-directory: dist
+        run: sha256sum *.tar.gz *.whl > SHA256SUMS
+      - uses: softprops/action-gh-release@v3
+        with:
+          tag_name: ${{ github.event.release.tag_name }}
+          files: dist/*
+
+  pypi-publish:
+    name: Upload release to PyPI
+    needs: [build, sdist, release-assets]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: astral-sh/setup-uv@v10.1.0
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: python-*
+          path: dist
+          merge-multiple: true
+      - name: Publish with PyPI trusted publishing
+        run: uv publish --trusted-publishing always dist/*

sqlite_jev-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Linux x86_64
+            runner: ubuntu-24.04
+          - name: Linux arm64
+            runner: ubuntu-24.04-arm
+          - name: macOS Intel
+            runner: macos-15-intel
+          - name: macOS Apple Silicon
+            runner: macos-15
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install Linux dependencies
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y sqlite3 libsqlite3-dev curl
+      - name: Install macOS dependencies
+        if: runner.os == 'macOS'
+        run: |
+          brew install sqlite
+          echo "$(brew --prefix sqlite)/bin" >> "$GITHUB_PATH"
+          echo "CPPFLAGS=-I$(brew --prefix sqlite)/include" >> "$GITHUB_ENV"
+      - run: make test
+      - name: Build and test Python wheel
+        uses: pypa/cibuildwheel@v3.3.0
+        env:
+          CIBW_ARCHS: native

sqlite_jev-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,24 @@
+name: TypeSafe integration
+
+on:
+  workflow_dispatch:
+  schedule:
+    # January, March, May, July, September, and November.
+    - cron: "17 9 1 */2 *"
+
+permissions:
+  contents: read
+
+jobs:
+  live-smoke:
+    name: Live API smoke test
+    runs-on: ubuntu-24.04
+    env:
+      TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Require integration secret
+        run: test -n "$TYPESAFE_API_KEY"
+      - name: Install dependencies
+        run: sudo apt-get update && sudo apt-get install -y sqlite3 libsqlite3-dev curl
+      - run: make integration-test

sqlite_jev-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+build/
+dist/
+wheelhouse/
+pg-jev/
+*.egg-info/
+.venv/
+__pycache__/
+*.db
+*.so

sqlite_jev-0.1.0/CMakeLists.txt

@@ -0,0 +1,28 @@
+cmake_minimum_required(VERSION 3.15)
+project(sqlite_jev VERSION 0.1.0 LANGUAGES C)
+
+add_library(jev MODULE src/jev.c)
+set_target_properties(jev PROPERTIES
+  C_STANDARD 11
+  C_STANDARD_REQUIRED YES
+  PREFIX ""
+)
+target_compile_definitions(jev PRIVATE JEV_VERSION="${PROJECT_VERSION}")
+
+if(APPLE)
+  set_target_properties(jev PROPERTIES SUFFIX ".dylib")
+  target_link_options(jev PRIVATE "-undefined" "dynamic_lookup")
+elseif(UNIX)
+  target_link_libraries(jev PRIVATE ${CMAKE_DL_LIBS})
+endif()
+
+if(MSVC)
+  target_compile_options(jev PRIVATE /W4)
+else()
+  target_compile_options(jev PRIVATE -Wall -Wextra -Wpedantic)
+endif()
+
+install(TARGETS jev
+  LIBRARY DESTINATION sqlite_jev
+  RUNTIME DESTINATION sqlite_jev
+)

sqlite_jev-0.1.0/Makefile

@@ -0,0 +1,64 @@
+CC ?= cc
+CFLAGS ?= -O2 -g
+CFLAGS += -fPIC -std=c11 -Wall -Wextra -Wpedantic
+CPPFLAGS ?=
+LDFLAGS ?=
+
+VERSION := $(shell sed -n 's/^version = "\([^"]*\)"/\1/p' pyproject.toml | head -1)
+CPPFLAGS += -DJEV_VERSION='"$(VERSION)"'
+BUILD_DIR := build
+UNAME_S := $(shell uname -s)
+UNAME_M := $(shell uname -m)
+
+ifeq ($(UNAME_S),Darwin)
+EXT_SUFFIX := dylib
+SHARED_FLAGS := -dynamiclib -undefined dynamic_lookup
+DL_LIBS :=
+PLATFORM := macos
+else
+EXT_SUFFIX := so
+SHARED_FLAGS := -shared
+DL_LIBS := -ldl
+PLATFORM := linux
+endif
+
+EXTENSION := $(BUILD_DIR)/jev.$(EXT_SUFFIX)
+PACKAGE_NAME ?= sqlite-jev-$(VERSION)-$(PLATFORM)-$(UNAME_M)
+PACKAGE_DIR := $(BUILD_DIR)/$(PACKAGE_NAME)
+
+.PHONY: all clean test integration-test live-test package wheel wheel-test
+
+all: $(EXTENSION)
+
+$(EXTENSION): src/jev.c | $(BUILD_DIR)
+	$(CC) $(CPPFLAGS) $(CFLAGS) $(SHARED_FLAGS) -o $@ $< $(LDFLAGS) $(DL_LIBS)
+
+$(BUILD_DIR):
+	mkdir -p $@
+
+test: $(EXTENSION)
+	./test/run.sh
+
+live-test: $(EXTENSION)
+	./examples/run_ticket_triage.sh
+
+integration-test: $(EXTENSION)
+	./test/run_live.sh
+
+package: $(EXTENSION)
+	rm -rf $(PACKAGE_DIR)
+	mkdir -p $(PACKAGE_DIR)
+	cp $(EXTENSION) $(PACKAGE_DIR)/
+	cp README.md pyproject.toml $(PACKAGE_DIR)/
+	tar -czf $(BUILD_DIR)/$(PACKAGE_NAME).tar.gz -C $(BUILD_DIR) $(PACKAGE_NAME)
+	@echo "Created $(BUILD_DIR)/$(PACKAGE_NAME).tar.gz"
+
+wheel:
+	rm -rf dist
+	uv build --wheel
+
+wheel-test: wheel
+	./scripts/test_wheel.sh "$$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+
+clean:
+	rm -rf $(BUILD_DIR)

sqlite_jev-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.2
+Name: sqlite-jev
+Version: 0.1.0
+Summary: Batched natural-language judgments for SQLite, powered by TypeSafe Jev
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: SQL
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Database
+Project-URL: Source, https://github.com/mgaitan/sqlite-jev
+Project-URL: Issues, https://github.com/mgaitan/sqlite-jev/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# sqlite-jev
+
+Natural-language predicates, classification, and scoring for SQLite, powered by
+[TypeSafe Jev](https://docs.typesafe.ai). It is inspired by
+[`pg-jev`](https://github.com/realZachi/pg-jev), but shaped around SQLite's loadable-extension
+and virtual-table APIs.
+
+```sql
+.load ./build/jev
+
+SELECT t.id, t.subject, round(j.probability, 3) AS urgency
+FROM jev_rows(
+  'tickets',
+  'The customer explicitly expresses urgency or says work is blocked',
+  'noul',
+  NULL,
+  json_array('subject', 'message')
+) AS j
+JOIN tickets AS t ON t.rowid = j.source_rowid
+WHERE j.probability >= 0.6;
+```
+
+`jev_rows` reads the selected columns, puts up to 40 rows in one shared state, asks one
+question per row, and returns a virtual table that can be joined to the source by `rowid`.
+Results are cached for the lifetime of the SQLite connection.
+
+## Build
+
+Requirements:
+
+- SQLite 3.45 or newer, built with JSON support and loadable extensions
+- A C11 compiler and `make`
+- The `libcurl` runtime (`libcurl.so.4` on Linux or `libcurl.4.dylib` on macOS)
+- A TypeSafe API key
+
+The current development machine already has all of these; no extra system package is needed.
+
+```bash
+make
+export TYPESAFE_API_KEY=...
+sqlite3 my.db
+```
+
+Inside SQLite:
+
+```sql
+.load ./build/jev
+SELECT jev_version();
+```
+
+`TYPESAFE_API_KEY` is the only environment variable used for the API key.
+
+## Batched table queries
+
+The signature is:
+
+```sql
+jev_rows(table_name, question [, kind [, criteria [, columns]]])
+```
+
+It returns `source_rowid`, `answer`, `probability`, `choice`, `score`, and `confidence`.
+Columns that do not apply to the chosen primitive are `NULL`.
+
+### Boolean judgment (Noul)
+
+```sql
+SELECT
+  t.id,
+  j.probability AS yes_probability,
+  1.0 - j.probability AS no_probability,
+  CASE WHEN j.probability >= 0.7 THEN 'yes' ELSE 'no' END AS answer
+FROM jev_rows(
+  'tickets',
+  'The ticket explicitly asks for a refund',
+  'noul',
+  NULL,
+  json_array('subject', 'message')
+) AS j
+JOIN tickets AS t ON t.rowid = j.source_rowid
+ORDER BY t.id;
+```
+
+A Noul returns the probability of `yes`; `no` is its complement. Choosing the larger one is
+equivalent to a `0.5` threshold. Keep the threshold in SQL so it can rise with the cost of a
+false positive. The scalar `jev(state, condition)` uses `0.5` unless given a third argument.
+
+### Classification (Choice)
+
+```sql
+SELECT t.id, j.choice AS team, j.confidence
+FROM jev_rows(
+  'tickets',
+  'Which team should handle the main request?',
+  'choice',
+  json_object(
+    'billing', 'Charges, invoices, payment methods, or refunds',
+    'technical', 'Bugs, failures, or integrations',
+    'sales', 'Pricing, plans, demos, or new purchases',
+    'other', 'Anything outside those teams'
+  ),
+  json_array('subject', 'message')
+) AS j
+JOIN tickets AS t ON t.rowid = j.source_rowid;
+```
+
+### Ordered rating (Score)
+
+```sql
+SELECT t.id, j.score, j.confidence
+FROM jev_rows(
+  'tickets',
+  'How frustrated is the customer?',
+  'score',
+  json_array('Calm and factual', 'Frustrated but civil', 'Very angry or abusive'),
+  json_array('message')
+) AS j
+JOIN tickets AS t ON t.rowid = j.source_rowid;
+```
+
+For accuracy and cost, include only the columns the judgment needs. `jev_rows` requires a
+rowid table. To prefilter a large data set, materialize the filtered rows into a temporary
+table and evaluate that table.
+
+## Scalar functions
+
+Scalar functions are convenient for one record. When scanning a table, prefer `jev_rows` so
+Jev can evaluate many questions in a single request.
+
+| Function | Result |
+| --- | --- |
+| `jev(state, condition [, threshold])` | Boolean Noul predicate; default threshold is `0.5` |
+| `jev_prob(state, condition)` | Noul probability from 0 to 1 |
+| `jev_choice(state, question, criteria_json)` | Most likely Choice key |
+| `jev_score(state, question, levels_json)` | Probability-weighted Score level |
+| `jev_score_norm(state, question, levels_json)` | Score normalized to 0 through 1 |
+| `jev_confidence(state, question, kind, criteria_json)` | Choice or Score confidence |
+| `jev_eval(state, question [, kind [, criteria_json]])` | Full answer JSON |
+| `jev_stats()` | Connection-local usage and cache statistics |
+| `jev_cache_clear()` | Clears the connection-local answer cache |
+| `jev_version()` | Extension version |
+
+Pass structured state with SQLite JSON functions:
+
+```sql
+SELECT jev_prob(
+  json_object('subject', subject, 'message', message),
+  'The customer explicitly expresses urgency'
+)
+FROM tickets
+WHERE id = 42;
+```
+
+## Configuration
+
+Configuration is connection-local:
+
+```sql
+SELECT jev_config('model', 'jev-latest');
+SELECT jev_config('batch_size', 40);
+SELECT jev_config('max_rows', 500);
+SELECT jev_config('timeout', 90);
+SELECT jev_config('api_url', 'https://api.typesafe.ai/v1/systemone');
+SELECT jev_config('api_key', '...');
+```
+
+`max_rows` is a spend guard. A `jev_rows` scan above the limit fails before sending any data.
+The API key is never returned by `jev_config`; it reports only `set` or `unset`.
+
+## Python
+
+Add the platform package to a project and load it with the Python wrapper:
+
+```bash
+uv add sqlite-jev
+```
+
+```python
+import sqlite3
+import sqlite_jev
+
+connection = sqlite_jev.load(sqlite3.connect(":memory:"))
+```
+
+The package contains the same native extension as the standalone release, has no runtime
+Python dependencies, and supports maintained Python versions starting with Python 3.10. The
+interpreter's `sqlite3` module must have loadable-extension support enabled.
+
+To load a standalone build manually instead:
+
+```python
+import sqlite3
+
+connection = sqlite3.connect(":memory:")
+connection.enable_load_extension(True)
+connection.load_extension("/path/to/jev.so")  # use jev.dylib on macOS
+connection.enable_load_extension(False)
+
+version = connection.execute("select jev_version()").fetchone()[0]
+```
+
+## Demo and tests
+
+The deterministic suite uses a local mock server and never calls TypeSafe:
+
+```bash
+make test
+```
+
+The ticket-triage demo makes two live API requests, one for urgency and one for routing:
+
+```bash
+make live-test
+```
+
+See [`examples/ticket_triage.sql`](examples/ticket_triage.sql) for the complete query.
+
+`make integration-test` runs a smaller live smoke test. In GitHub Actions it runs once every
+two months and on manual dispatch using the `TYPESAFE_API_KEY` repository secret. It checks the API contract,
+batching, and answer shapes; semantic expectations remain in the deterministic mock suite so
+normal model variation cannot make pull requests flaky.
+
+## Releases
+
+Tags named `vX.Y.Z` build and publish four archives through GitHub Actions:
+
+- Linux x86_64 and arm64
+- macOS Intel and Apple Silicon
+
+Each archive contains the native extension, this README, and its `pyproject.toml`. The release
+also includes a `py3-none-<platform>` Python wheel and `SHA256SUMS`. CI installs each wheel
+with `cibuildwheel` and verifies that `sqlite_jev.load()` enables the SQL API. The same tag
+publishes the wheels and source distribution to PyPI through trusted publishing.
+
+## Important limits
+
+- Row contents are sent to TypeSafe. Do not evaluate data you are not allowed to share.
+- This is a semantic full scan, not an index. Apply deterministic SQLite filters first and
+  materialize a small candidate table.
+- Cache entries live only for the current database connection and are keyed by row content,
+  model, question, primitive, and criteria.
+- Jev should make narrow judgments. Keep counting, arithmetic, and date comparison in SQL.
+- Text stored in a row can steer model behavior. Test adversarial content and use conservative
+  probability or confidence thresholds before automating consequential actions.
+- `libcurl` is loaded dynamically so building does not require the curl development headers.
+  Linux and macOS are the currently tested platforms.