Skip to content
Projects

Sheltercosmo/jev4pg has 262 GitHub stars and 30 forks. GitHot measured 0 stars in 24 hours and +1 in 7 days. Last checked 2026-11-15 13:46 UTC. Last push 2026-10-26.

How these counts are measured

What you can do

  • Support and operations queues - Classify unresolved requests, join account data and share reviewed priority definitions with reporting.
  • Document intake - Extract typed fields with exact source passages, review the proposed records and approve an import. Guide.
  • An analyst workspace in your product - Ask in English or Simplified Chinese, inspect generated SQL and refine saved queries through the API. Tutorial.
  • Search by business criteria - Rank similarity by named dimensions such as urgency or intent, using stored probability embeddings. Native SQL example.

Measured star growth

in 24h
0
in 7 days
+1
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Established strong JEV based natural language to SQL performance and well-covered semantic operators for PostgreSQL with optimized cost and latency. Reusable evidence, with native execution, parallel plans and explainable embeddings in development preview.

Data

README.md

Original

jev4pg: Natural language. Semantic SQL. Pangolin mascot with three parallel data paths.

jev4pg

Natural language to SQL and semantic operators for PostgreSQL

Release 0.8.0 PostgreSQL 14–17 Apache 2.0 license

Website · Quick start · Existing PostgreSQL · Advantages · Performance · NL2SQL benchmark · What you can build · Project guide · Installation · User guide · 简体中文 · Function reference · Documentation

jev4pg brings semantic intelligence to PostgreSQL 14–17 with 41 JEV operators for filtering, extraction, ranking, matching and verification. Build semantic search, document workflows and analyst tools on your existing data, with natural-language queries in English and Simplified Chinese.

Higher accuracy, lower latency. In our paired semantic-filtering benchmark, jev4pg reached 98% accuracy versus 92%, with 36% lower median latency than pg-jev's request path. Current development also delivers 20.4× faster cached operator lookups, 3× faster request packing and 3.7× faster native probability-matrix projection against v0.8.0 in paired local microbenchmarks. Shared execution improvements support filtering, extraction, ranking, matching and verification by reducing evidence reads, repeated computation and request preparation. Performance highlights.

Explainable embeddings represent data through named questions and answer probabilities, making similarity inspectable. The native preview combines these with parallel execution and input deduplication: independent work runs concurrently, while repeated values with the same context and questions share judgments, preserving every source row.

Evidence caching retains raw observations for compatible queries and threshold changes, with source and evaluator identity checks. Controlled retries and reviewable fallbacks keep errors, uncertainty and skipped work explicit, and preserve legal SQL proposals for correction. Reviewed definitions and corrections build a self-developing semantic layer your team can reuse across reports and applications. PostgreSQL handles joins, windows and exact arithmetic.

See it in action at jev4pg.com, then build with the workspace, HTTP API or PostgreSQL interfaces.

Animated product tour: natural-language SQL, semantic filtering, text extraction, parallel JEV stages and probability embeddings.

Performance highlights

Faster operator execution

Current main optimizes the shared Python operator runtime and native 0.4.0 executor. Bulk evidence reads, exact-size request packing and direct probability projection reduce work across operator families.

Operation Baseline Optimized Speedup
Read 600 cached operator judgments 162.1 ms 8.0 ms 20.4×
Pack 1,024 questions into requests 22.5 ms 7.4 ms 3.0×
Project 10,000 probability matrices 61.1 ms 16.7 ms 3.7×

Cached operator reads drop from 600 SQL queries to 3, while request packing produces the same 32 bundles. Native cache retention also removes 32 redundant provider requests in the mixed recurring/new-context workload. Compatible evidence replay and stored-embedding comparisons need no new inference.

These are paired component measurements with a deterministic local provider, separate from the live accuracy comparison below. All timings, cache tradeoffs and reproduction · Optimizations by function.

Benchmark-leading semantic filtering

Native preview 0.3.0 packs independent judgments into parallel requests and reuses exact evidence as new records arrive. In a frozen, paired executor test, it was faster on seven of eight workloads against the pinned pg-jev 0.2.1 request path.

Task, 400 records jev4pg pg-jev request path
Real reviews 98.0% accuracy, 469 ms 92.0%, 732 ms
Three independent predicates 100% accuracy, 1,498 ms 99.33%, 1,983 ms

The three-predicate case used 38 requests instead of 60. With identical required-column projections on both sides, jev4pg used 36.2% fewer input tokens. Warm passes made no provider calls on either side.

Measured with JEV 1.13, concurrency 16 and three repeats across 132 runs. Timings cover executor and HTTP paths. The full report includes every workload, token usage and held-answer scoring. Full comparison and reproduction · Use mapped SQL.

Why choose jev4pg

Define once, reuse across queries

Turn a reviewed concept such as needs_action into a semantic feature for queues, reports and natural-language questions. Version the definition, retain corrections against their sources and give every workflow the same interpretation. Semantic features.

Reuse judgments when policies change

Keep raw answer probabilities separate from decision thresholds. Replay compatible evidence without new inference, including across PostgreSQL connections. Source, question and evaluator identities control reuse; bulk cache reads and bounded native retention reduce repeated lookup work. Evidence reuse.

Run independent judgments in parallel

Independent records and branches share a bounded scheduler. Shared SQL stages materialize once, while dependent work starts when its inputs are ready. Native scan_mapped evaluates distinct contexts per question: three and two distinct inputs need five judgments, even across thousands of rows. Stage plans · Context dictionaries.

Search with dimensions you can explain

Define similarity through questions such as “Requests a refund?” and “Issue resolved?” Inspect each answer probability, project existing decisions into embeddings and compare compatible stored vectors locally without new model calls. Probability embeddings.

Give the LLM a focused job

JEV selects relevant schema and evidence before an LLM proposes SQL, then reviews independent operations and missing context in parallel. With concept generation and repair disabled, hybrid planning uses one LLM generation call. Hybrid planning.

On the historical BIRD Challenging sample of 100 questions across 11 databases, JEV used 88.1% less estimated token cost and hybrid used 20.8% fewer LLM input tokens than GPT-5.6 Terra. Answer matches were 20/99 for JEV, 34/99 for hybrid and 39/99 for Terra, including held proposals. September 2026 Python planner results.

Keep uncertain decisions reviewable

VALUE, UNKNOWN and NOT_EVALUATED stay distinct from execution failures. Retain held SQL for correction, route uncertain judgments to review and preview proposed writes before approval. Skipped work never silently becomes false. Query review.

Quick start

Choose your setup

PostgreSQL stores your data and executes relational SQL in every setup. jev4pg adds two complementary components:

Component Use it for Where it runs
Python application Natural-language queries, the web workspace, HTTP APIs, all 41 operators, reviewed features and query history Beside PostgreSQL 14–17; no custom server extension required.
Native Rust extension Synchronous semantic SQL, parallel stage plans, repeated-context reuse and explainable embeddings Inside PostgreSQL 14–17 on Linux; works directly from SQL without Python.
Combined deployment The workspace and natural-language planning with native semantic reads Python plans and manages the workflow; Rust executes supported semantic stages in PostgreSQL.

Use Python when you want a complete application or need to integrate with an existing server without installing native libraries. Use native execution when your application already speaks SQL and needs bounded semantic scans over PostgreSQL data. It keeps source reads and relational stages in the database and shares scheduling and evidence across semantic work. Both call your configured JEV provider.

JEV and Hybrid are planning modes in the application, independent of the execution engine. Hybrid adds LLM generation. The native extension consumes explicit SQL and typed questions; natural-language planning comes from the application.

The commands below install current main, tested on PostgreSQL 14, 15, 16 and 17, with native preview 0.4.0. Tables and row-level security work across all four majors; workspace view attachments require PostgreSQL 15+. Version compatibility and upgrades.

Python application

For a complete local workspace, install Python 3.11+ and Docker Compose v2:

git clone --branch main https://github.com/Sheltercosmo/jev4pg.git
cd jev4pg
python deploy/configure.py

PostgreSQL 17 is the default. To use 14, 15 or 16, create or edit .env in the checkout and set SDD_POSTGRES_MAJOR to that major, for example SDD_POSTGRES_MAJOR=14. Then start the stack:

docker compose build
docker compose up -d --wait
python deploy/configure.py --show-token

This starts PostgreSQL, the application and its workers. The setup prompt accepts a TypeSafe key; provider settings cover other hosted or local models. Open English or 简体中文 and connect with the workspace token printed by the last command. Hybrid mode also needs LLM configuration. Ordinary SQL requires no model key.

Import a CSV or TSV, select the dataset and ask a question. For a ticket dataset:

Which products have the most tickets describing unresolved billing problems?

Choose Preview plan, inspect the interpretation, then execute or revise it. SQL mode also accepts semantic predicates over registered datasets:

SELECT product, COUNT(*) AS unresolved_tickets
FROM tickets
WHERE SEMANTIC(body, 'The ticket describes an unresolved billing problem.')
GROUP BY product
ORDER BY unresolved_tickets DESC;

SEMANTIC(...) is application SQL syntax, accepted by the workspace and POST /data/sql. PostgreSQL clients use jev_native.* for synchronous execution. Inspect decision states and completeness before using an aggregate as a final result.

Browser imports support 5 MB and 10,000 rows. For larger data, load it with PostgreSQL tools and attach the table without copying rows. Workspace guide · Application API · Query examples.

Use an existing PostgreSQL database

Run the Python application beside your PostgreSQL 14–17 server. With Python 3.11+, install from main and create a connection profile:

python -m pip install https://github.com/Sheltercosmo/jev4pg/archive/refs/heads/main.zip
jev4pg setup
cd jev4pg-local
jev4pg --env-file admin.env migrate --check --sql-interface portable
jev4pg --env-file admin.env migrate --sql-interface portable
jev4pg serve

The wizard creates separate installation and runtime credentials. No SDD_POSTGRES_MAJOR setting is needed for an existing server. Migration adds the application catalog and portable SQL queue using ordinary PostgreSQL objects; it needs an owner with migration permissions. Open the workspace on port 8000 and use the token stored in .secrets/api-tokens.json. Grant the runtime login access to your source tables, then attach them.

For asynchronous operators from psql or DBeaver, grant a SQL login and start jev4pg sql-worker. For Run in background in the workspace, start a separate query worker. The foreground workspace does not require either worker.

Guided setup and first queued operator · Docker against an existing server.

Native PostgreSQL extension

For a SQL-only application, build and configure jev_native on your PostgreSQL 14–17 Linux server, then enable it with CREATE EXTENSION jev_native and grant function and source access. Call it from psql, a SQL editor or any PostgreSQL driver. No Python service or application dataset registration is required. First native SQL query.

For the combined workspace and native deployment, use the main checkout above, select your PostgreSQL major in .env, and run these commands instead of the default Compose commands:

python deploy/configure.py --native
docker compose -f compose.yaml -f compose.native.yaml build
docker compose -f compose.yaml -f compose.native.yaml up -d --wait
python deploy/configure.py --show-token

This builds the extension, configures its provider and evidence registry, and starts the workspace with native semantic reads. The first build compiles Rust. This stack uses its own database volume and the same default ports as the default stack; choose one or configure separate ports. Keep both -f arguments in later Compose commands.

Native execution covers semantic reads, stage plans and probability embeddings. Use the Python engine for maintained semantic features and semantic write review. The 41-operator HTTP API and asynchronous jev.* jobs remain Python-backed in a combined deployment. Native deployment guide · Capability map.

What you can build

Application Build with jev4pg
Support and operations queues Classify unresolved requests, join account data and share reviewed priority definitions with reporting.
Document intake Extract typed fields with exact source passages, review the proposed records and approve an import. Guide.
An analyst workspace in your product Ask in English or Simplified Chinese, inspect generated SQL and refine saved queries through the API. Tutorial.
Search by business criteria Rank similarity by named dimensions such as urgency or intent, using stored probability embeddings. Native SQL example.
Analysis over existing tables Register authorized PostgreSQL tables and views, then query them in place with source permissions and types preserved. Setup.

Fit into your existing stack

Call the 41-operator HTTP API, submit asynchronous jev.* jobs or use synchronous jev_native.* SQL functions. The capability map shows which component serves each workflow.

Connect TypeSafe, a compatible hosted endpoint or a local model through the same typed decision contract. The Python application supports in-process adapters; the native engine uses HTTP providers. Provider configuration.

Previously published as JevSDSQL and jevsd-pg; the current project and development package are named jev4pg.

From question to SQL

For each supplier, show the total quantity delivered, largest total first.

This request produced the following query in the runnable tutorial:

SELECT
  SUM("r0"."quantity") AS "result_1",
  "r0"."supplier" AS "result_2"
FROM "deliveries" AS "r0"
GROUP BY "r0"."supplier"
ORDER BY SUM("r0"."quantity") DESC NULLS LAST

On the tutorial data, the result is Birch: 36, Aster: 30, Cedar: 8. SQL performs the calculation. See query examples for filtering and averages, or use POST /ask:

{
  "question": "For each supplier, show the total quantity delivered, largest total first.",
  "dataset_ids": ["deliveries"],
  "planner_mode": "hybrid",
  "execute": false
}

Use a dataset ID or name from your catalog. Set planner_mode to jev for planning without LLM generation. API usage covers authentication, review and execution.

Native semantic SQL

After installing the Rust extension, evaluate messages directly in PostgreSQL:

SELECT source->>'id' AS id, decisions->'action' AS decision
FROM jev_native.scan(
    'SELECT id, body FROM messages',
    '{"action":{"type":"noul","instructions":"The message requests further action.",
                "subject_column":"body"}}',
    '{"max_rows":500,"max_requests":500,"max_judgments":500,"concurrency":4}'
);

Put exact filters and required columns inside the source SELECT to reduce semantic work. Use scan_many for independent populations or execute_plan for a typed stage DAG. Inspect decision states before aggregation; require_bool rejects unresolved membership rather than silently excluding it.

Embeddings with named dimensions

Define questions such as “Does this message request action?” and “Is the issue resolved?” Then jev_native.embed returns every answer probability as a matrix and flattened vector. Noul questions have false/true dimensions; Choice and Score retain all declared answers.

Use jev_native.answer_matrix to project existing decisions and jev_native.embedding_distance to compare complete, compatible embeddings locally. Native 0.4.0 development adds embedding_distances, preparing one query for a bounded candidate batch. These operations need no new model calls and validate the question basis and evaluator identity.

See the embedding guide, runnable SQL example and batch comparison. The question basis and provider determine retrieval quality; the reported projection speedup measures computation.

Documentation and contributions

The documentation index covers operators, native plans, evidence, installation and examples. Performance and cost explains execution accounting and what to measure. The roadmap records current native limitations.

To report a problem, include a small synthetic dataset, the request and the expected result. See CONTRIBUTING.md for development setup and checks.

License

Apache 2.0. Third-party software retains its own licenses. See NOTICE and dependencies.