Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,122 @@
----
-license: mit
----
+---
+base_model: microsoft/Phi-4-mini-instruct
+library_name: peft
+tags:
+- phi-4-mini
+- LoRA
+- peft
+- adapter
+- temporal-reasoning
+license: mit
+datasets:
+- a6188466/mini-recurrence-converter-dsl-dataset
+language:
+- en
+---
+# 🔁 Model Card for `mini-recurrence-converter-dsl-adapter`
+
+## 🧠 Model Details
+
+This is a parameter-efficient fine-tuning (PEFT) LoRA adapter trained on a structured DSL for recurrence interpretation, such as natural language like "every Monday at 10am" or "on the last Friday of each month". It translates natural recurrence expressions into structured function calls using a custom DSL (e.g., `WEEKLY(...)`, `MONTHLY_BY_WEEKDAY(...)`).
+
+- **Model type:** LoRA adapter (PEFT)  
+- **Language(s):** English  
+- **License:** MIT  
+- **Finetuned from model:** `microsoft/Phi-4-mini-instruct`
+
+## 🚀 Uses
+
+### Direct Use
+
+This adapter enhances Phi-4-mini-instruct for parsing natural recurrence expressions into DSL format.
+
+Example prompt:
+
+```
+$ You are a precise parser of recurring schedule expressions. Your only job is to translate natural language recurrence expressions into structured DSL function calls.  
+> every second Tuesday of the month at 1pm  
+< MONTHLY_BY_WEEKDAY(1, TU, 2, TIME(13, 0))
+```
+
+### Downstream Use
+
+Integrate it in DSL-based schedulers, assistants, or natural language interfaces requiring precise recurrence interpretation.
+
+The DSL produced by this model is defined and executed by the [Mini Recurrence Converter DSL module](https://github.com/gh9869827/fifo-dev-dsl/tree/main/fifo_dev_dsl/domain_specific/mini_recurrence_converter_dsl).
+
+It provides:
+
+- 🧠 A symbolic DSL to represent natural language recurrence patterns  
+- 📅 A Python engine to evaluate the DSL into structured recurrence rules  
+- 🤖 An integration with LLMs to translate text into DSL code  
+- 🔒 A safe alternative to arbitrary code execution — only predefined DSL functions are supported, so untrusted model output **cannot execute arbitrary code**
+
+Example:
+
+```python
+from fifo_dev_dsl.domain_specific.mini_recurrence_converter_dsl import MiniRecurrenceConverterDSL
+dsl = "WEEKLY(1, [MO, WE], TIME(10, 0))"
+parsed = MiniRecurrenceConverterDSL().parse(dsl)
+print(parsed)
+# Output: structured recurrence rule object
+```
+
+### Out-of-Scope Use
+
+This model is specialized for recurrence conversion DSL. It is not intended for general-purpose dialogue or unrelated tasks.
+
+## 🏗️ Training Details
+
+Trained on [a6188466/mini-recurrence-converter-dsl-dataset](https://huggingface.co/datasets/a6188466/mini-recurrence-converter-dsl-dataset) using the `dsl` adapter from [`fifo-tool-datasets`](https://github.com/gh9869827/fifo-tool-datasets) and [`fine_tune.py`](https://github.com/gh9869827/fifo-tool-airlock-model-env/blob/main/fifo_tool_airlock_model_env/fine_tuning/phi_4/fine_tune.py) in a fully local, air-gapped Docker container.
+
+- **Dataset:** 226 examples mapping natural language to DSL commands, including hand-curated and [synthetic](https://github.com/gh9869827/fifo-dev-dsl/blob/main/fifo_dev_dsl/domain_specific/mini_recurrence_converter_dsl/generate_synthetic_data.py) samples.
+- **Epochs:** 15  
+- **Batch size:** 1  
+- **Precision:** bf16  
+- **Framework:** `transformers`, `peft`, `trl` (SFTTrainer)
+
+### ⚙️ Training Hyperparameters
+
+```json
+{
+  "num_train_epochs": 15,
+  "train_batch_size": 1,
+  "learning_rate": 5e-06,
+  "lr_scheduler_type": "cosine",
+  "warmup_ratio": 0.2,
+  "bf16": true,
+  "seed": 0
+}
+```
+
+### 📈 Training Results
+
+```json
+{
+  "mean_token_accuracy": 0.9538259625434875,
+  "total_flos": 6218234638387200.0,
+  "train_loss": 0.4653199369477257,
+  "train_runtime": 932.994,
+  "train_samples_per_second": 4.486,
+  "train_steps_per_second": 4.486,
+  "final_learning_rate": 2.751554198876516e-11
+}
+```
+
+## ✅ Evaluation
+
+- **Eval set:** Natural language queries similar in structure and intent to the training examples  
+- **Metric:** Functional equivalence — two DSL expressions are considered correct when they evaluate to the same result  
+- **Results:**  
+  - **97.79%** on held-out [test set](https://huggingface.co/datasets/a6188466/mini-recurrence-converter-dsl-dataset) (**221/226** passed)  
+    The test set includes 26 hand-curated and 200 [synthetic](https://github.com/gh9869827/fifo-dev-dsl/blob/main/fifo_dev_dsl/domain_specific/mini_recurrence_converter_dsl/generate_synthetic_data.py) examples.
+
+Evaluation script: [`evaluate_mini_recurrence_converter_dsl_model.py`](https://github.com/gh9869827/fifo-dev-dsl/blob/main/fifo_dev_dsl/domain_specific/mini_recurrence_converter_dsl/evaluate_mini_recurrence_converter_dsl_model.py)
+
+## 🪪 License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## 📬 Contact
+
+For questions, feedback, or bug reports, please open an issue on GitHub or start a discussion on the Hugging Face Hub.