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.
@@ -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: []