{"repo": "bellicose100xp/jiq", "files": {"docs/features/ai-assistant.md": {"71ff6b07ddab2b257584755e625e347333426010": {"t": 1785674533.235297, "n": 7623, "h": "d571d6abced9b49e", "c": "---\ntitle: AI assistant\nparent: Features\nnav_order: 3\ndescription: Get context-aware jq query suggestions from an AI that sees your data, your query, and the error.\n---\n\n# AI assistant\n\nThe AI assistant fixes broken queries for you — it sees what went wrong, understands your data shape, and offers working alternatives you apply with a single keystroke.\n\n
\n \n \n
\n \n \n
\n
\n

You get a syntax error. Now you're searching the web, reading jq docs, trying variations one by one.

\n
$ jiq data.json\nQuery: .users | group_by .role\n ^^^^^^^^^^^^^^^^^^^^^^^^^^\n Syntax Error\n\n# Tab to browser...\n# Search: \"jq group_by syntax\"\n# Read docs... try group_by(.role)... no wait...\n# Try 5 more variations...\n# 10 minutes later: finally works
\n
\n
\n

Press Ctrl+A. The AI sees your query, the error, and your data — then offers working fixes.

\n
Query: .users | group_by .role\n Syntax Error\n\n# Press Ctrl+A...\n\nAI Suggestions:\n 1. .users | group_by(.role)\n 2. [.users[] | group_by(.role)]\n 3. .users | group_by(.role) | map({key: .[0].role, val: .})\n\n# Press Alt+1 — done. 3 seconds.
\n
\n
\n\n## How it works\n\n
\n
\n
1
\n
Error appears
\n
\n
\n
\n
2
\n
Press Ctrl+A
\n
\n
\n
\n
3
\n
AI analyzes context
\n
\n
\n
\n
4
\n
Pick a suggestion
\n
\n
\n
\n
5
\n
Applied
\n
\n
\n\nThe AI sends your current query, the error message, and a sample of your JSON to the configured provider. It returns 2-5 suggestions ranked by relevance. The entire round trip typically takes 1-3 seconds.\n\n## Get a fix for a failing query\n\n1. Write a query that produces an error (the `Syntax Error` banner appears).\n2. Press **Ctrl+A** to open the AI popup.\n3. Wait for suggestions to appear (a loading indicator shows progress).\n4. Press **Alt+1** through **Alt+5** to apply a suggestion directly — or use **Alt+j**/**Alt+k** to navigate, then **Enter** to apply.\n\n
\n
\n \n \n \n AI suggestions popup\n
\n
\n
Query: .items | map(select(.price > 100) | .name, .price)
\n
Syntax Error: unexpected ',' at line 1
\n
 
\n
AI Suggestions:
\n
1. .items[] | select(.price > 100) | {name, price}
\n
2. [.items[] | select(.price > 100) | {name: .name, price: .price}]
\n
3. .items | map(select(.price > 100) | {name, price})
\n
 
\n
Alt+1..3 Apply | Alt+j/k Navigate | Enter Apply selected
\n
\n
\n\n## Ask for help with a working query\n\nThe AI assistant is not limited to fixing errors. Even when your query works, press **Ctrl+A** and the AI may suggest improvements — a more concise form, a different approach, or natural language interpretation of what you typed.\n\n## What the popup tells you\n\n| Popup state | What it means |\n|---|---|\n| A numbered list of suggestions | The AI returned 2-5 jq queries you can apply. |\n| **No suggestions** | The AI ran successfully but had nothing useful to add for this query (common for the bare `.` identity query). This is normal, not an error. |\n| **Could not parse AI response** | The provider returned a response jiq could not read as suggestions. Re-run with `--debug` and check `/tmp/jiq-debug.log` to see the raw response. |\n\n## Navigate and dismiss suggestions\n\n| Action | Key |\n|---|---|\n| Move between suggestions | **Alt+Up** / **Alt+Down** or **Alt+j** / **Alt+k** |\n| Apply the highlighted suggestion | **Enter** |\n| Apply suggestion N directly | **Alt+1** through **Alt+5** |\n| Close without applying | **Ctrl+A** or **Esc** |\n\n## Configure the AI provider\n\nThe AI assistant requires a provider configuration in `~/.config/jiq/config.toml`. jiq supports Anthropic, OpenAI, Gemini, AWS Bedrock, and any OpenAI-compatible API.\n\n```toml\n[ai]\nenabled = true\nprovider = \"anthropic\" # \"anthropic\", \"openai\", \"gemini\", or \"bedrock\"\nmax_context_length = 100000 # characters of JSON context sent to AI (default 100k)\n```\n\n### Anthropic\n\n```toml\n[ai.anthropic]\napi_key = \"sk-ant-...\"\nmodel = \"claude-haiku-4-5-20251001\"\n```\n\n### OpenAI\n\n```toml\n[ai.openai]\napi_key = \"sk-proj-...\"\nmodel = \"gpt-4o-mini\"\n```\n\n### Gemini\n\n```toml\n[ai.gemini]\napi_key = \"AIza...\"\nmodel = \"gemini-3-flash-preview\"\n```\n\n### AWS Bedrock\n\n```toml\n[ai.bedrock]\nregion = \"us-east-1\"\nmodel = \"global.anthropic.claude-haiku-4-5-20251001-v1:0\"\nprofile = \"default\" # optional: uses default credential chain if omitted\n```\n\n### OpenAI-compatible APIs (Ollama, LM Studio, x.ai)\n\nAny API that follows the OpenAI chat completions format works by setting `provider = \"openai\"` with a custom `base_url`:\n\n```toml\n# Ollama (local)\n[ai.openai]\nbase_url = \"http://localhost:11434/v1\"\nmodel = \"llama3\"\n\n# LM Studio (local)\n[ai.openai]\nbase_url = \"http://localhost:1234/v1\"\nmodel = \"local-model\"\n\n# x.ai Grok\n[ai.openai]\napi_key = \"your-xai-api-key\"\nbase_url = \"https://api.x.ai/v1\"\nmodel = \"grok-4-fast-non-reasoning\"\n```\n\nFor local providers that don't require authentication, omit the `api_key` field entirely.\n\n### Tuning context size\n\nThe `max_context_length` setting controls how much of your JSON data is sent to the AI. Larger values give the AI more context for better suggestions but increase token usage and cost. Smaller values reduce cost and latency.\n\n```toml\n[ai]\nmax_context_length = 50000 # send less context (faster, cheaper)\nmax_context_length = 200000 # send more context (better suggestions for large files)\n```\n\nFor sensitive data, a local model via Ollama or LM Studio keeps everything on your machine.\n\n## All keys\n\n| Key | Action |\n|---|---|\n| `Ctrl+A` | Toggle AI assistant popup |\n| `Alt+1`..`Alt+5` | Apply suggestion 1-5 directly |\n| `Alt+Up` / `Alt+Down` | Navigate suggestions |\n| `Alt+j` / `Alt+k` | Navigate suggestions (vim style) |\n| `Enter` | Apply selected suggestion |\n| `Ctrl+A` / `Esc` | Close popup |\n"}}}}