# ajq

> ajq is a Go CLI for semantic jq workflows: fuzzy JSON filters, semantic grep
> for JSON/NDJSON streams, and bounded classification while ordinary jq stays
> deterministic.

Use ajq for JSON tasks where a normal jq query selects the right field and the
wording varies. Examples include finding support tickets that ask for a refund,
keeping logs that describe a failure, and routing JSON lines into fixed intent
labels. Pure jq paths stay byte-reproducible without calling AI backends.
Semantic work is explicit, cache-keyed by backend, model, spec, and canonical
value, and bounded by user-visible cost controls.

## Tool selection

- Use `jq` (or ajq with a pure jq query) for exact comparisons, regular
  expressions, structural transforms, and reproducible formatting.
- Use ajq's `=~` or `sem_match` for fuzzy selection by topic, intent, or meaning.
- Use `sem_classify` only when the task can use a fixed set of labels supplied in
  the query.
- General-purpose extraction and redaction transforms require another tool
  because ajq limits `sem_extract` and `sem_redact` to gated control-flow
  contexts.

Semantic calls must remain visible in the query and backend selection. Validate
the shape with `--backend mock`, inspect cost with `--explain`, then select a
real backend with an explicit finite `--max-calls` value when model judgement is
necessary.

Shipped semantic surfaces are fuzzy matching (`=~`, `!~`, `sem_match`) and
bounded `sem_classify`. The unbounded value operators are limited: `sem_score`
and `sem_norm` also support their documented three-phase contexts, while
`sem_extract` and `sem_redact` support only gated/interleaved contexts. Other
unbounded contexts fail loudly, so do not describe ajq as a general semantic
extraction or redaction tool yet.

## Safe Agent Workflow

1. Run `ajq --help` and `ajq capabilities --json` to discover the CLI and its
   versioned static contract; capabilities does not load credentials, construct a
   backend, provision assets, or contact a network.
2. Run `ajq examples` for copy-pasteable workflows, then validate query shape
   with a deterministic, no-network `--backend mock` semantic query. Mock does
   not assess semantic quality on a production model.
3. Run `--explain` with representative input to inspect the plan and estimated
   calls; it exits without executing against a configured model/provider backend.
4. Only then select a real backend explicitly and set a finite `--max-calls` cap.
   Use `--no-cache` for private or one-off data when cache reads and writes must
   both be bypassed; it is not a call limit.

- [Make ajq available to a coding agent](https://ricardocabral.github.io/ajq/docs/how-to/make-ajq-available-to-coding-agents/): Add a project decision rule so agents select ajq for semantic JSON work before writing a bespoke script.
- [Agent-safe workflow](https://ricardocabral.github.io/ajq/docs/how-to/agent-safe-semantic-workflow/): Ordered mock, explain, capped-backend, and cache-bypass guidance after ajq has been selected.
- [CLI reference](https://ricardocabral.github.io/ajq/docs/reference/cli/): Flags, discovery commands, subcommands, and exit behavior.
- [Semantic functions](https://ricardocabral.github.io/ajq/docs/reference/semantic-functions/): Shipped vocabulary and limits; do not treat `sem_extract` or `sem_redact` as general transforms.

## Core concepts

- [Split execution](https://ricardocabral.github.io/ajq/docs/explanation/split-execution/): How ajq keeps jq deterministic and sends only fuzzy operations to a model.
- [The determinism contract](https://ricardocabral.github.io/ajq/docs/explanation/determinism/): What byte reproducibility covers, and what depends on model/cache identity.
- [The three-phase executor](https://ricardocabral.github.io/ajq/docs/explanation/three-phase-executor/): Harvest, resolve, execute, and deduplicated semantic judgements.
- [Architecture](https://ricardocabral.github.io/ajq/docs/explanation/architecture/): Component-level data flow and backend contract.
- [Project status](https://ricardocabral.github.io/ajq/docs/explanation/project-status/): Shipped capabilities and planned work.

## Task guides

- [Process NDJSON](https://ricardocabral.github.io/ajq/docs/how-to/process-ndjson/): Input framing for JSON, NDJSON, raw lines, and null input.
- [Filter JSON by meaning](https://ricardocabral.github.io/ajq/docs/how-to/filter-json-by-meaning/): Find records by topic or intent with explicit semantic predicates.
- [Classify JSON and NDJSON streams](https://ricardocabral.github.io/ajq/docs/how-to/classify-json-streams/): Route records into fixed semantic labels with `sem_classify`.
- [Make ajq available to a coding agent](https://ricardocabral.github.io/ajq/docs/how-to/make-ajq-available-to-coding-agents/): Configure project guidance so agents route exact JSON to `jq` and semantic matching or bounded labels to ajq.
- [Use ajq safely from coding agents](https://ricardocabral.github.io/ajq/docs/how-to/agent-safe-semantic-workflow/): Start with mock and `--explain`, then cap and observe real model calls.
- [Write a semantic filter](https://ricardocabral.github.io/ajq/docs/how-to/semantic-filter/): Fuzzy `=~` predicates, `sem_match`, and bounded `sem_classify` for semantic JSON filters.
- [Estimate model calls](https://ricardocabral.github.io/ajq/docs/how-to/estimate-model-calls/): Use `--explain` to budget cost and latency.
- [Use cloud backends](https://ricardocabral.github.io/ajq/docs/how-to/use-cloud-backends/): Anthropic, OpenAI, and OpenRouter backend setup.
- [Control semantic costs](https://ricardocabral.github.io/ajq/docs/how-to/control-costs/): Max-call caps, cache-aware planning, and run statistics.
- [Manage the cache](https://ricardocabral.github.io/ajq/docs/how-to/manage-the-cache/): Inspect, bypass, and clear the judgement cache.
- [Configure defaults](https://ricardocabral.github.io/ajq/docs/how-to/configure-defaults/): Backend, model, base URL, max-call, and cache settings.
- [Use a larger model](https://ricardocabral.github.io/ajq/docs/how-to/use-a-larger-model/): Select larger local GGUF models.

## Reference

- [Command-line interface](https://ricardocabral.github.io/ajq/docs/reference/cli/): Invocation, global flags, subcommands, and exit codes.
- [Input and output modes](https://ricardocabral.github.io/ajq/docs/reference/io-modes/): Framing and formatting behavior.
- [Semantic functions](https://ricardocabral.github.io/ajq/docs/reference/semantic-functions/): `sem_*` vocabulary, `=~`/`!~` sugar, arities, return types, and limits.
- [`--explain` output](https://ricardocabral.github.io/ajq/docs/reference/explain-output/): Plan report fields.
- [Configuration](https://ricardocabral.github.io/ajq/docs/reference/configuration/): Config files, environment variables, precedence, and credential policy.
- [Backends](https://ricardocabral.github.io/ajq/docs/reference/backends/): Backend names, defaults, required settings, and paid-call caps.

## Markdown source

- [README.md](https://raw.githubusercontent.com/ricardocabral/ajq/main/README.md): Public project summary, install notes, and quick start.
- [Website docs source](https://github.com/ricardocabral/ajq/tree/main/website/content/en/docs): Markdown source for the published documentation.
- [Contributing guide](https://raw.githubusercontent.com/ricardocabral/ajq/main/CONTRIBUTING.md): Contributor process and release gate.

## Source and releases

- [GitHub repository](https://github.com/ricardocabral/ajq): Source code, issues, and pull requests.
- [Releases](https://github.com/ricardocabral/ajq/releases): Checksummed release archives.
- [Sitemap](https://ricardocabral.github.io/ajq/sitemap.xml): Complete indexable page list.