--- base_model: mistralai/Ministral-3-8B-Instruct-2512-BF16 model_name: opensearch-agentic-dsl library_name: peft pipeline_tag: text-generation license: apache-2.0 language: - en tags: - base_model:adapter:mistralai/Ministral-3-8B-Instruct-2512-BF16 - lora - qlora - sft - transformers - trl - opensearch - text-to-dsl --- # opensearch-agentic-dsl A LoRA adapter that translates English shopper requests into OpenSearch DSL for a second-hand luxury catalog. It is designed for OpenSearch's native Agentic Search `QueryPlanningTool`. The adapter uses [mistralai/Ministral-3-8B-Instruct-2512-BF16](https://huggingface.co/mistralai/Ministral-3-8B-Instruct-2512-BF16) at revision `06cc81bfd6e45321d8fc8f816576c5b6ac67ec22`. Load both the base model and tokenizer at this revision, then attach the adapter with PEFT. ## Input and output Input combines shopper text, trusted application controls, the index mapping, and allowed query fields. The exact [system prompt](prompts/system.txt) and [user template](prompts/user.txt) are included. The [complete example](example.py) shows how to construct the three-line question and double JSON encode the mapping and field list. Output is one JSON request body containing `size`, integer `track_total_hits`, `query`, and optional `sort`. The planner applies required filters, price ceilings, and the selected ranking mode. Persona expansion contributes optional scoring. Index selection, search pipelines, and `_source` stay application-owned. ## Run the model Download `sharp-pixel/opensearch-agentic-dsl` and run the included example: ```bash hf download sharp-pixel/opensearch-agentic-dsl --local-dir opensearch-agentic-dsl cd opensearch-agentic-dsl python example.py ``` The example requires a CUDA GPU with enough memory for the BF16 base model and uses Transformers 5.13.0, PEFT 0.19.1, and PyTorch 2.13.0. It loads the bundled prompts and local adapter, uses greedy decoding, and prints the generated body. Set `ADAPTER_ID=sharp-pixel/opensearch-agentic-dsl` to load the adapter from the Hub instead. For vLLM, enable LoRA with maximum rank 16, load the language model only, and serve the adapter as `opensearch-agentic-dsl`. ## Training and evaluation Training used 4,640 synthetic examples and 1,160 held-out examples, grouped to keep related scenarios within a single split. Only the language-model attention and MLP projections were adapted; the vision encoder and projector stayed frozen. | Setting | Value | | --- | --- | | Method | QLoRA with completion-only supervision | | Quantization / compute | 4-bit NF4 / BF16 | | LoRA rank / alpha / dropout | 16 / 32 / 0.05 | | Epochs / sequence length | 2 / 2,112 tokens | | Learning rate / effective batch size | 0.0001 / 16 | | GPU / training time | RTX PRO 6000 Blackwell / 1.76 hours | | Metric | Value | | --- | ---: | | Training loss | 0.0038393672 | | Held-out loss | 0.0016606329 | | Held-out token accuracy | 99.9305% | Token accuracy is measured with teacher-forced targets, not freely generated requests. The synthetic evaluation does not establish real-world retrieval quality. Validate generated DSL against the actual mapping and application policy, and enforce OpenSearch permissions and resource limits. Training data, prompts, policy, and the dependency lockfile match this [verified source revision](https://github.com/sharp-pixel/LaTrouvaille/tree/7b26a2a56b71eab674ad8d53be5c1d06353967c8/query-understanding-training). ## License The adapter and accompanying model-card documentation are released under [Apache 2.0](LICENSE). The upstream model and tokenizer are also Apache 2.0; see [NOTICE](NOTICE) for attribution. Application source and training data retain their respective licenses.