query_translator 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/AGENTS.md +518 -0
- data/LICENSE.txt +21 -0
- data/README.md +147 -0
- data/README.uk.md +148 -0
- data/Rakefile +12 -0
- data/lib/query_translator/configuration.rb +12 -0
- data/lib/query_translator/filter.rb +12 -0
- data/lib/query_translator/filter_check.rb +92 -0
- data/lib/query_translator/prompt.rb +105 -0
- data/lib/query_translator/resource.rb +4 -0
- data/lib/query_translator/result.rb +19 -0
- data/lib/query_translator/translator.rb +54 -0
- data/lib/query_translator/version.rb +5 -0
- data/lib/query_translator.rb +25 -0
- data/sig/query_translator.rbs +4 -0
- data/skills/query-translator-setup/SKILL.md +140 -0
- metadata +74 -0
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: query-translator-setup
|
|
3
|
+
description: Add natural-language search to a Rails app with the query_translator gem — free text in any language becomes validated filters for the app's existing index endpoints, with clarification questions and a fallback to the filter UI. Use when asked to "add natural language search", "search in plain words", "let users type what they need", "text to filters", "NL search", "plug in query_translator", or to make an API searchable by a sentence. Reuses the project's own index endpoints and search services and fits any Rails layout.
|
|
4
|
+
version: 1.1.0
|
|
5
|
+
updated: 2026-11-21
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# QueryTranslator — set up natural-language search
|
|
9
|
+
|
|
10
|
+
You plug the `query_translator` gem into the current Rails project. The gem turns a sentence into filters for the
|
|
11
|
+
project's **existing** index endpoints; it never searches by itself. The full rules live in the gem's own `AGENTS.md`
|
|
12
|
+
("the guide" below); this skill is the order of work.
|
|
13
|
+
|
|
14
|
+
## Ground rules
|
|
15
|
+
|
|
16
|
+
- The host project's own instructions win over this skill wherever they differ: commit policy, comment style, naming,
|
|
17
|
+
layering, test style, who writes the code, how to talk to the developer. Look for them wherever the repository keeps
|
|
18
|
+
them: `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, `.claude/instructions/`, `.github/copilot-instructions.md`,
|
|
19
|
+
`.github/instructions/`.
|
|
20
|
+
- Never create, read or print credential keys. The developer adds the LLM key.
|
|
21
|
+
- Never call a real model from the app's test suite.
|
|
22
|
+
- Ask the developer one question at a time, with options, when a decision is theirs (which resources, which pages,
|
|
23
|
+
guest access, the LLM provider, a rate limit, creating try-out data). Do not guess business rules.
|
|
24
|
+
|
|
25
|
+
## Steps
|
|
26
|
+
|
|
27
|
+
### 1. Check the starting point
|
|
28
|
+
|
|
29
|
+
- Rails app? Ruby 3.2+? Is `query_translator` already in `Gemfile`? If yes, find what exists
|
|
30
|
+
(`grep -rln "QueryTranslator" app business lib config spec 2>/dev/null`) and continue from the first missing step.
|
|
31
|
+
- Does the project already call an LLM (`ruby_llm`, `ruby-openai` or `anthropic` in `Gemfile.lock`)? Then the provider
|
|
32
|
+
is a question in step 4, and an existing `ruby_llm` must allow `~> 2.2`.
|
|
33
|
+
- Find the project's search layer (search or query objects, e.g. `app/services/search/*.rb`) and the controllers
|
|
34
|
+
whose index actions filter: API ones under `app/controllers/api/**` and, in a monolith, HTML ones that call a search
|
|
35
|
+
service. Is there an HTML UI (Hotwire/views), or is the app API-only?
|
|
36
|
+
|
|
37
|
+
### 2. Add the gem and read its guide
|
|
38
|
+
|
|
39
|
+
```ruby
|
|
40
|
+
gem 'query_translator', '~> 0.1'
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Run `bundle install`, then read the whole guide from the installed copy before writing any code:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
cat "$(bundle info query_translator --path)/AGENTS.md"
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
If that fails, stop and tell the developer; do not work from memory. This skill is written for guide version 1.x (see
|
|
50
|
+
its frontmatter); if the major version differs, ask the developer to copy the skill again from the gem's repository.
|
|
51
|
+
Everything below refers to the guide's sections (§).
|
|
52
|
+
|
|
53
|
+
### 3. Propose the resources — and get them approved
|
|
54
|
+
|
|
55
|
+
Do §4 step 3 and step 4: inventory the index endpoints, read their permitted params, model enums and scopes, and map
|
|
56
|
+
every useful param to a filter (name exactly as the endpoint takes it, type, one-sentence description, enum values
|
|
57
|
+
from code, `multiple:` where arrays are accepted). Database lists only from small shared tables the staff manages
|
|
58
|
+
(categories, regions); never per-tenant or per-user records, names users type, or people: every name goes into the
|
|
59
|
+
prompt of every call and can come back in a question (§7).
|
|
60
|
+
|
|
61
|
+
Show the developer a compact table per resource (name, path, who may call it, filters) and ask which resources to
|
|
62
|
+
include. Do not write code before they confirm.
|
|
63
|
+
|
|
64
|
+
### 4. Provider, key and initializers
|
|
65
|
+
|
|
66
|
+
- Provider: Anthropic with `claude-haiku-5-5`, the gem's tuned default. If the project already calls another LLM, ask
|
|
67
|
+
which one to use; another provider needs a model with structured output in RubyLLM, its own key setting, and the
|
|
68
|
+
step 8 run on that model.
|
|
69
|
+
- Ask the developer to add the key to the credentials of development and of every deployed environment
|
|
70
|
+
(`anthropic: api_key:` by default), not test: specs stub the translator, and without a key a forgotten stub fails
|
|
71
|
+
loudly instead of spending money.
|
|
72
|
+
- `config/initializers/ruby_llm.rb` (or the project's existing RubyLLM setup): the key from the credentials
|
|
73
|
+
(`Rails.application.credentials.dig(:anthropic, :api_key)`, or the project's own credentials helper), plus
|
|
74
|
+
`config.request_timeout = 15` and `config.max_retries = 1`, because a user waits on this call and RubyLLM's
|
|
75
|
+
defaults are 300 s and 3 retries. Both settings are global: if the app already uses RubyLLM for long jobs, ask
|
|
76
|
+
first.
|
|
77
|
+
- `config/initializers/query_translator.rb`: `model`, `confidence_threshold`, `max_query_length`, and a one- or
|
|
78
|
+
two-sentence `extra_instructions` with domain facts (currency, units, market).
|
|
79
|
+
|
|
80
|
+
### 5. Business objects
|
|
81
|
+
|
|
82
|
+
Per §4 step 5: one object builds the resources from code constants (and the database lists at request time, skipped
|
|
83
|
+
when empty); another calls the gem, caches the answer by date + normalized text, and adds app-specific clarification
|
|
84
|
+
questions that need the database. Neither writes to the database. Put them where the project keeps business logic
|
|
85
|
+
(service objects, actions, operations), as the kind its rules let a controller call. If the resources ever differ per
|
|
86
|
+
user or role, put that in the cache key too.
|
|
87
|
+
|
|
88
|
+
### 6. Endpoints and UI
|
|
89
|
+
|
|
90
|
+
Per §4 step 6 and §5:
|
|
91
|
+
|
|
92
|
+
- API (when the searched index endpoints are API endpoints): `GET /api/v1/natural_search?query=` returning the ready
|
|
93
|
+
call; guests allowed when at least one searched endpoint is public (a private resource is still translated, and its
|
|
94
|
+
own page asks for sign-in, §5).
|
|
95
|
+
- HTML (only if the app has one): a search box where the developer wants it (ask; offer to draw options if the project
|
|
96
|
+
asks for visual choices), a question page with one button per option, a low-confidence hint on the result page,
|
|
97
|
+
"what we searched for" chips with a remove link each.
|
|
98
|
+
- On `QueryTranslator::Error`: log it (and report it to the project's error tracker, if any), then the API answers 503
|
|
99
|
+
with a plain translated sentence and the web redirects to the plain filter page with a short message, never a 500.
|
|
100
|
+
- Carry the original text to the result page in a param that page does not filter by (`query` is taken where a page
|
|
101
|
+
has a full-text filter). An answer button sends `"<text> — <option>"`; trim the text so it all fits
|
|
102
|
+
`max_query_length`, because the gem cuts anything longer.
|
|
103
|
+
- A public endpoint pays for every new text: ask the developer whether to rate-limit the natural-search actions on
|
|
104
|
+
their own (§7).
|
|
105
|
+
- Every string in every locale file; the box `maxlength` from `QueryTranslator.config.max_query_length`.
|
|
106
|
+
|
|
107
|
+
### 7. Specs
|
|
108
|
+
|
|
109
|
+
Per §4 step 7: a helper that builds a real `QueryTranslator::Result` from the app's resources, the translator stubbed
|
|
110
|
+
with `allow(QueryTranslator::Translator).to receive(:call)`, specs for the business object, the API endpoint
|
|
111
|
+
(acceptance/request spec in the project's style) and the web flow, each with its `QueryTranslator::Error` fallback,
|
|
112
|
+
and one for an empty database list.
|
|
113
|
+
|
|
114
|
+
Then run the checks the project defines (its own `AGENTS.md`/`CLAUDE.md`, a verification skill or script, its CI
|
|
115
|
+
config). Where it defines none: the full suite, the linter, and `brakeman` and `bundler-audit` if the bundle has them.
|
|
116
|
+
|
|
117
|
+
### 8. Try it live
|
|
118
|
+
|
|
119
|
+
Per §4 step 8, once the developer has added the key: a throwaway script outside the repository, run with
|
|
120
|
+
`bin/rails runner`, sends 30+ realistic queries through the step 5 object that calls the gem, on development data —
|
|
121
|
+
every filter, other languages, slang, typos, relative dates, several values, negations, vague words, off-topic and
|
|
122
|
+
hostile text.
|
|
123
|
+
|
|
124
|
+
- Its first line is `Rails.cache = ActiveSupport::Cache::NullStore.new`, so a re-run reaches the model instead of
|
|
125
|
+
replaying today's cached answers. Never `Rails.cache.clear`: it can wipe a Redis database other apps share.
|
|
126
|
+
- Use the data that is already there. If a case needs records that are missing, ask before creating any, and remove
|
|
127
|
+
them at the end.
|
|
128
|
+
- Fix wrong answers by improving descriptions, not the gem, and run the set again.
|
|
129
|
+
|
|
130
|
+
### 9. Report
|
|
131
|
+
|
|
132
|
+
- files added and changed;
|
|
133
|
+
- the resources and filters that went in, and what was left out and why (ids, geo, positional pairs, private lists);
|
|
134
|
+
- the live results: how many queries, what works, what still goes wrong;
|
|
135
|
+
- try-out records created and whether they were removed (with the cleanup command), or "none";
|
|
136
|
+
- anything the developer must do: add the key to every deployed environment before deploying (without it every search
|
|
137
|
+
fails with a 500), review, commit (if the project leaves that to them), switch a `path:` gem source to the released gem, decide
|
|
138
|
+
on a rate limit if that is still open.
|
|
139
|
+
|
|
140
|
+
Finish with the guide's hand-over checklist (§10).
|
metadata
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: query_translator
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- AndriyAndriyovuch
|
|
8
|
+
bindir: exe
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: ruby_llm
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - "~>"
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: '2.2'
|
|
19
|
+
type: :runtime
|
|
20
|
+
prerelease: false
|
|
21
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
22
|
+
requirements:
|
|
23
|
+
- - "~>"
|
|
24
|
+
- !ruby/object:Gem::Version
|
|
25
|
+
version: '2.2'
|
|
26
|
+
description: Takes free text and the list of filters an app supports, asks an LLM
|
|
27
|
+
through RubyLLM to pick the kind of search and its filters, and returns a checked
|
|
28
|
+
API call with a confidence score or a clarification question.
|
|
29
|
+
email:
|
|
30
|
+
- andriy.mazurok.tl@gmail.com
|
|
31
|
+
executables: []
|
|
32
|
+
extensions: []
|
|
33
|
+
extra_rdoc_files: []
|
|
34
|
+
files:
|
|
35
|
+
- AGENTS.md
|
|
36
|
+
- LICENSE.txt
|
|
37
|
+
- README.md
|
|
38
|
+
- README.uk.md
|
|
39
|
+
- Rakefile
|
|
40
|
+
- lib/query_translator.rb
|
|
41
|
+
- lib/query_translator/configuration.rb
|
|
42
|
+
- lib/query_translator/filter.rb
|
|
43
|
+
- lib/query_translator/filter_check.rb
|
|
44
|
+
- lib/query_translator/prompt.rb
|
|
45
|
+
- lib/query_translator/resource.rb
|
|
46
|
+
- lib/query_translator/result.rb
|
|
47
|
+
- lib/query_translator/translator.rb
|
|
48
|
+
- lib/query_translator/version.rb
|
|
49
|
+
- sig/query_translator.rbs
|
|
50
|
+
- skills/query-translator-setup/SKILL.md
|
|
51
|
+
homepage: https://github.com/AndriyAndriyovuch/query_translator
|
|
52
|
+
licenses:
|
|
53
|
+
- MIT
|
|
54
|
+
metadata:
|
|
55
|
+
homepage_uri: https://github.com/AndriyAndriyovuch/query_translator
|
|
56
|
+
source_code_uri: https://github.com/AndriyAndriyovuch/query_translator
|
|
57
|
+
rdoc_options: []
|
|
58
|
+
require_paths:
|
|
59
|
+
- lib
|
|
60
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
61
|
+
requirements:
|
|
62
|
+
- - ">="
|
|
63
|
+
- !ruby/object:Gem::Version
|
|
64
|
+
version: 3.2.0
|
|
65
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
66
|
+
requirements:
|
|
67
|
+
- - ">="
|
|
68
|
+
- !ruby/object:Gem::Version
|
|
69
|
+
version: '0'
|
|
70
|
+
requirements: []
|
|
71
|
+
rubygems_version: 4.0.16
|
|
72
|
+
specification_version: 4
|
|
73
|
+
summary: Translates a natural-language search query into validated API filters.
|
|
74
|
+
test_files: []
|