Explanation on ajq — semantic jq

Split execution

Mon, 01 Jan 0001 00:00:00 +0000

The observation

A real-world “AI data” query is mostly not fuzzy. Consider triaging support tickets:

cat data.json | ajq --backend local '.users[] | select(.feedback =~ "angry/frustrated") | .id'
 └────────┬───────┘ └────────────┬────────────┘ └┬┘
 deterministic path semantic predicate proj
 (pure gojq) (LLM, per value) (pure gojq)

Iterating the array, projecting .id, shaping the output — all of that is exact, mechanical work that jq already does perfectly. Only one operator, =~, needs judgement. The insight behind ajq is to treat that asymmetry as a first-class execution strategy: run the deterministic majority through a real jq engine, and call a model only for the fuzzy operators, on the smallest possible slices of data.

The determinism contract

Mon, 01 Jan 0001 00:00:00 +0000

ajq separates deterministic structure from semantic judgement.

The contract

The deterministic pipeline is byte-reproducible. Semantic judgements are structurally guaranteed, but their values are model- and cache-dependent.

Those are different promises.

Deterministic parts are byte-reproducible

Every part of a query that is not a semantic operator runs through pure gojq. Given the same input, it produces the same output bytes. There is no model, no sampling, and no network in that path.

The three-phase executor

Mon, 01 Jan 0001 00:00:00 +0000

ajq runs supported semantic queries in three phases. For NDJSON and raw streams, the unit of work is a bounded window of complete frames rather than the complete stream.

The three phases

Phase 1 HARVEST pure gojq run; semantic ops in COLLECT mode gather every
 (op, spec, value) they observe. Permissive returns.
Phase 2 RESOLVE dedup collected values, consult/write the judgement cache,
 and resolve misses through the selected backend.
Phase 3 EXECUTE pure gojq run; semantic ops in LOOKUP mode return resolved
 values from cache. Deterministic given those cached values.

Phases 1 and 3 are pure gojq. Phase 2 is the isolated semantic boundary: it deduplicates, checks cache identity, and calls the backend only for misses.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

ajq is a small pipeline of components.

Data flow

stdin → [Reader/Framer] → [Desugar] → [gojq.Parse] → [Planner] ──→ [Explain]
 │
 [3-phase Executor]
 ├─ gojq (deterministic)
 └─ Semantic Executor → [Backend iface]
 ├─ mock
 ├─ local daemon
 ├─ ollama
 ├─ openai / openrouter
 └─ anthropic cloud
[Grammar/Schema builder] → GBNF / json_schema ─────────────────────────────┘
stdout ← [Assembler / schema-invariance guard]

The components

Component	Responsibility
Reader / Framer	Stream framing: single JSON, NDJSON, and raw lines (awk-mode). Supported three-phase semantic input is grouped into complete-frame byte-budgeted windows; pure-jq and interleaved paths remain streaming.
Desugar	Rewrites `=~` / `!~` into `sem_match` calls with a jq-aware lexer.
Planner	Exhaustive AST walk that discovers every semantic call site → a `Plan` used for `--explain`, validation, and cost estimation.
Executor	Runs the plan in three phases (harvest / resolve / execute), with interleaved fallback for gated unbounded value ops.
Semantic Executor	Deduplicates judgements, consults the persistent judgement cache when enabled, builds each op’s prompt and schema, and records run stats.
Backend	Pluggable inference. Shipped backends: `mock`, `local` (llama-server daemon), `ollama`, `openai`, `openrouter`, and `anthropic`/`--cloud`.
Grammar / schema builder	Turns an op’s return type / enum into a JSON Schema and, for the local engine, GBNF grammar constraints.
Assembler	Reassembles the output stream and enforces schema invariance.

Windowed semantic execution

For supported three-phase semantic queries, the executor retains one complete-frame window at a time, harvests its semantic judgements, resolves deduplicated cache misses in one backend batch, then executes frames in source order. The default source-byte budget is 256 KiB and can be overridden with --window-bytes, AJQ_WINDOW_BYTES, or window_bytes in TOML. A record that exceeds the budget is a valid one-frame oversized window, so the budget is not a rejection limit. The executor does not retain the complete stream: it keeps the current window, one lookahead frame, and bounded framing buffers.

Project status

Mon, 01 Jan 0001 00:00:00 +0000

ajq has shipped its deterministic jq spine, semantic planning and supported semantic execution, local inference, bounded-parallel local daemon transport, Phase 3 backend/cloud controls, first-run local asset provisioning, local model management, the persistent judgement cache, byte-budgeted semantic windows, an explicit low-latency semantic stream mode, and checksummed release archives with a no-sudo install script. Further streaming optimizations remain planned. The iterative-harvest experiment is an internal-only no-go prototype, not a shipped mode; default windowed execution is unchanged.

Iterative-harvest prototype evaluation

Mon, 01 Jan 0001 00:00:00 +0000

Decision: no-go for productionization

The iterative-harvest implementation is an internal test and benchmark prototype. It is not a CLI mode, is not selected by default, and must not be enabled for users. The existing three-phase-windowed executor remains the default and unsupported query shapes continue to use their existing windowed or planner-required interleaved fallback.

This is a no-go even though the pruning workload clears its judgement-saving target. A reachable error case found during characterization has different behavior from the current windowed executor: after an earlier gate rejects a value, a backend result/schema/transport error for that pruned descendant is dispatched and returned by permissive windowed harvest, but is intentionally not dispatched by iterative harvest or interleaved execution. That changes the reachable error, cache, and exit contract. Reducing calls by dispatching the unreachable descendant would defeat the prototype’s purpose. Until a separate design resolves that semantic/error boundary, the required current-window parity gate is not met.