Upload 48 files

Initial public release of OktoScript specification

.gitattributes

@@ -1,35 +1,12 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# OktoScript Language Detection
+# This file tells GitHub to recognize .okt files as OktoScript language
+
+*.okt linguist-language=OktoScript
+
+
+
+assets/okto_logo.png filter=lfs diff=lfs merge=lfs -text
+assets/okto_logo2.png filter=lfs diff=lfs merge=lfs -text
+assets/okto_logo3.png filter=lfs diff=lfs merge=lfs -text
+assets/okto_logo4.png filter=lfs diff=lfs merge=lfs -text
+assets/oktoscript_banner.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,31 @@
+# OktoScript - Files to ignore
+
+# Internal documentation (not for public GitHub)
+ENV_BLOCK_SUMMARY.md
+ARQUIVOS_ATUALIZADOS_*.txt
+MUDANCAS_*.txt
+
+# Build artifacts
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.temp

CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to OktoScript will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+**OktoScript** is developed and maintained by **OktoSeek AI**.
+
+## [1.0.0] - 2025-11-22
+
+### Added
+- Initial release of OktoScript by OktoSeek AI
+- Complete grammar specification (v1.0)
+- PROJECT, DESCRIPTION, VERSION, TAGS, AUTHOR blocks
+- DATASET block with support for multiple formats
+- MODEL block with architecture and precision options
+- TRAIN block with optimizer and scheduler support
+- METRICS block with built-in and custom metrics
+- VALIDATION block for training validation
+- INFERENCE block for inference configuration
+- EXPORT block with multiple format support (gguf, onnx, okm, safetensors, tflite)
+- DEPLOY block for deployment configuration
+- SECURITY block for model encryption and watermarking
+- LOGGING block for training logs
+- Complete PizzaBot example project
+- JSON Schema for dataset validation
+- Professional README with documentation
+- Apache 2.0 License
+
+### Documentation
+- Grammar specification in EBNF format
+- Complete README with examples
+- Example project documentation
+- Contributing guidelines
+- Project structure documentation
+
+---
+
+[1.0.0]: https://github.com/oktoseek/oktoscript/releases/tag/v1.0.0
+
+---
+
+**OktoScript** is a product of **OktoSeek AI**.

CHANGELOG_V1.1.md

@@ -0,0 +1,185 @@
+# OktoScript v1.1 Changelog
+
+**Release Date:** November 2025  
+**Status:** 100% Backward Compatible with v1.0
+
+---
+
+## 🎉 New Features
+
+### 1. LoRA Fine-Tuning Support
+
+Added `FT_LORA` block for efficient fine-tuning using Low-Rank Adaptation adapters.
+
+**Benefits:**
+- ✅ Reduced memory footprint (up to 90% less VRAM)
+- ✅ Faster training times
+- ✅ Smaller model files (only adapter weights)
+- ✅ Easy to combine multiple LoRA adapters
+
+**Example:**
+```okt
+# okto_version: "1.1"
+FT_LORA {
+    base_model: "oktoseek/base-llm-7b"
+    lora_rank: 8
+    lora_alpha: 32
+    epochs: 5
+    batch_size: 4
+    learning_rate: 0.00003
+    device: "cuda"
+    target_modules: ["q_proj", "v_proj"]
+}
+```
+
+**See:** [`examples/lora-finetuning.okt`](./examples/lora-finetuning.okt)
+
+---
+
+### 2. Dataset Mixing and Sampling
+
+Enhanced `DATASET` block with support for mixing multiple datasets with weighted sampling.
+
+**New Fields:**
+- `mix_datasets`: Array of `{path, weight}` objects
+- `dataset_percent`: Limit dataset usage (1-100)
+- `sampling`: `"weighted"` or `"random"`
+- `shuffle`: Shuffle datasets before mixing
+
+**Example:**
+```okt
+DATASET {
+    mix_datasets: [
+        { path: "dataset/base.jsonl", weight: 70 },
+        { path: "dataset/extra.jsonl", weight: 30 }
+    ]
+    dataset_percent: 80
+    sampling: "weighted"
+    shuffle: true
+}
+```
+
+**Benefits:**
+- ✅ Combine multiple datasets intelligently
+- ✅ Control dataset proportions
+- ✅ Limit dataset size for faster iteration
+- ✅ Weighted or random sampling strategies
+
+**See:** [`examples/dataset-mixing.okt`](./examples/dataset-mixing.okt)
+
+---
+
+### 3. Advanced System Monitoring
+
+Added `MONITOR` block for comprehensive system and training telemetry.
+
+**Features:**
+- System metrics (GPU, CPU, RAM, temperature)
+- Training speed metrics (tokens/s, samples/s)
+- Real-time dashboard (optional)
+- Configurable refresh intervals
+- Export to JSON
+
+**Example:**
+```okt
+MONITOR {
+    level: "full"
+    log_metrics: ["loss", "accuracy", "perplexity"]
+    log_system: ["gpu_memory_used", "cpu_usage", "temperature"]
+    log_speed: ["tokens_per_second", "samples_per_second"]
+    refresh_interval: 2s
+    export_to: "runs/logs/system.json"
+    dashboard: true
+}
+```
+
+**Benefits:**
+- ✅ Monitor system resources during training
+- ✅ Detect bottlenecks and optimize
+- ✅ Track training speed
+- ✅ Real-time visualization
+
+---
+
+### 4. Version Declaration
+
+Added optional version declaration at the top of `.okt` files.
+
+**Syntax:**
+```okt
+# okto_version: "1.1"
+PROJECT "MyModel"
+...
+```
+
+**Rules:**
+- Optional (defaults to v1.0 if missing)
+- Must be first line (comments allowed before)
+- Format: `# okto_version: "1.1"` or `# okto_version: "1.0"`
+- Enables v1.1 features when set to "1.1"
+
+---
+
+## 📁 New Optional Folders
+
+v1.1 introduces optional folders for new features:
+
+```
+/runs/
+  └── my-model/
+      ├── logs/
+      │   └── system.json      # MONITOR output
+      └── lora/                 # LoRA adapters
+          └── adapter.safetensors
+```
+
+**Note:** These folders are created automatically when using v1.1 features. Existing v1.0 structure remains unchanged.
+
+---
+
+## 🔄 Backward Compatibility
+
+**100% Compatible with v1.0:**
+
+- ✅ All v1.0 files work without modification
+- ✅ v1.0 syntax remains valid
+- ✅ No breaking changes
+- ✅ Default version is v1.0 (if version not specified)
+
+**Migration:**
+- No migration required
+- Simply add `# okto_version: "1.1"` to use new features
+- Existing v1.0 files continue to work
+
+---
+
+## 📚 Documentation Updates
+
+- ✅ [`docs/grammar.md`](./docs/grammar.md) - Updated with v1.1 grammar
+- ✅ [`VALIDATION_RULES.md`](./VALIDATION_RULES.md) - Added v1.1 validation rules
+- ✅ [`README.md`](./README.md) - Added v1.1 examples and features
+- ✅ New examples in [`examples/`](./examples/)
+
+---
+
+## 🐛 Bug Fixes
+
+None (this is a feature release)
+
+---
+
+## 🔮 Future Roadmap
+
+Planned for future versions:
+- Multi-GPU training support
+- Distributed training
+- Advanced quantization options
+- More dataset formats
+- Custom loss functions
+
+---
+
+**For questions or feedback:** [GitHub Issues](https://github.com/oktoseek/oktoscript/issues)
+
+
+

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to OktoScript
+
+Thank you for your interest in contributing to OktoScript! 🐙
+
+**OktoScript** is a domain-specific programming language developed by **OktoSeek AI**. We welcome contributions from the community!
+
+## How to Contribute
+
+### Reporting Issues
+
+If you find a bug or have a feature request, please open an issue on GitHub with:
+- Clear description of the problem or feature
+- Steps to reproduce (for bugs)
+- Expected vs actual behavior
+- OktoScript version (if applicable)
+
+### Submitting Changes
+
+1. **Fork the repository**
+2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
+3. **Make your changes** following the code style
+4. **Test your changes** thoroughly
+5. **Commit your changes** (`git commit -m 'Add amazing feature'`)
+6. **Push to the branch** (`git push origin feature/amazing-feature`)
+7. **Open a Pull Request**
+
+### Code Style
+
+- Follow the existing OktoScript grammar specification
+- Keep examples in English
+- Document new features in `docs/grammar.md`
+- Update README.md if adding major features
+
+### Adding Examples
+
+When adding new examples:
+- Place them in `examples/your-example-name/`
+- Follow the standard folder structure
+- Include complete `train.okt` file
+- Add sample datasets
+- Update `examples/README.md`
+
+### Documentation
+
+- Keep grammar documentation up to date
+- Add examples for new features
+- Update README.md for major changes
+- Always mention **OktoSeek AI** as the developer/maintainer
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing!
+
+---
+
+**OktoScript** is developed and maintained by **OktoSeek AI**.
+
+Thank you for helping make OktoScript better! 🚀

LICENSE

@@ -0,0 +1,192 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (which shall not include Communications that are clearly marked or
+   otherwise designated in writing by the copyright owner as "Not a Work").
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based upon (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is clearly marked or otherwise designated
+   in writing by the copyright owner as "Not a Contribution".
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2025 OktoSeek AI
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

README.md

@@ -1,3 +1,720 @@
----
-license: apache-2.0
----
+<p align="center">
+  <img src="./assets/okto_logo.png" alt="OktoScript Banner" width="50%" />
+</p>
+<p align="center">
+  <img src="./assets/okto_logo2.png" alt="OktoScript Banner" width="50%" />
+</p>
+
+
+
+<h1 align="center">OktoScript</h1>
+
+
+
+<p align="center">
+  <strong>A decision-driven language for training, evaluating and governing AI models.</strong>
+</p>
+
+<p align="center">
+  A domain-specific language (DSL) designed for autonomous AI pipelines with<br>
+  built-in decision, control, monitoring and governance capabilities.
+</p>
+
+<p align="center">
+  Built by <strong>OktoSeek AI</strong> for the <strong>OktoSeek ecosystem</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.oktoseek.com/">OktoSeek Homepage</a> •
+  <a href="https://huggingface.co/OktoSeek">Hugging Face</a> •
+  <a href="https://x.com/oktoseek">Twitter</a> •
+  <a href="https://www.youtube.com/@Oktoseek">YouTube</a>
+</p>
+
+---
+
+## Table of Contents
+
+1. [What is OktoScript?](#-what-is-oktoscript)
+2. [Quick Start](#-quick-start)
+3. [Official Folder Structure](#-official-folder-structure)
+4. [Basic Example](#-oktoscript--basic-example)
+5. [Supported Dataset Formats](#-supported-dataset-formats)
+6. [Supported Metrics](#-supported-metrics)
+7. [CLI Commands](#️-cli-commands)
+8. [Training Pipeline](#-training-pipeline)
+9. [OktoSeek Internal Formats](#-oktoseek-internal-formats)
+10. [Integration Targets](#️-integration-targets)
+11. [VS Code Extension](#-vs-code-extension-coming-soon)
+12. [Documentation](#-documentation)
+13. [FAQ](#-frequently-asked-questions-faq)
+14. [License](#-license)
+15. [Contact](#-contact)
+
+---
+
+## 🚀 Quick Start
+
+**New to OktoScript?** Get started in 5 minutes:
+
+1. **Read the guide:** [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
+2. **Try an example:** [`examples/basic.okt`](./examples/basic.okt)
+3. **Validate:** `okto validate examples/basic.okt`
+4. **Train:** `okto train examples/basic.okt`
+
+📚 **Full documentation:** [`docs/grammar.md`](./docs/grammar.md)  
+🔍 **Validation rules:** [`VALIDATION_RULES.md`](./VALIDATION_RULES.md)
+
+---
+
+## 🚀 What is OktoScript?
+
+**OktoScript** is a decision-driven language created by **OktoSeek AI** to design, train, evaluate, control and govern AI models end-to-end.
+
+It goes far beyond a simple training script. OktoScript introduces native intelligence, autonomous decision-making and behavioral control into the AI development lifecycle.
+
+It allows you to define:
+
+- **How a model is trained**
+- **How it should behave**
+- **How it should react to problems**
+- **How and when it should stop, adapt or improve itself**
+
+All using clear, readable and structured commands, built specifically for AI engineering.
+
+### Designed to be:
+
+- ✅ **Human-readable** – Intuitive syntax that engineers and non-engineers can understand
+- ✅ **Decision-driven** – Built-in CONTROL logic (IF, WHEN, SET, STOP, LOG, SAVE…)
+- ✅ **Strongly structured** – Validated, deterministic and reproducible pipelines
+- ✅ **Dataset-centered** – The data is the starting point of all intelligence
+- ✅ **Training-aware** – Created specifically for AI training and optimization
+- ✅ **Behavior-aware** – Control personality, language, restrictions and style
+- ✅ **Self-monitoring** – Tracks metrics, detects anomalies and adapts automatically
+- ✅ **Safe by design** – Integrated GUARD and SECURITY layers
+- ✅ **Expandable** – Extensible through OktoEngine and custom modules
+
+OktoScript is the official language of the OktoSeek ecosystem and is used by:
+
+- 🎯 **OktoSeek IDE** – Visual AI development and experimentation
+- ⚙️ **OktoEngine** – Core execution and decision engine
+- 🔌 **VS Code Extension** – Code editing + validation
+- 🔄 **Autonomous pipelines** – Training, control, evaluation and inference
+- 🤖 **AI agents** – Controlled, monitored intelligent systems
+- 📱 **Flutter / API deployments** – Cross-platform model integration
+
+### Why OktoScript is different
+
+**Traditional AI development is reactive.**  
+You manually monitor metrics, fix problems and restart training.
+
+**OktoScript is proactive.**
+
+It allows the model to:
+
+- **Detect instability**
+- **Reduce or increase learning rate automatically**
+- **Adapt batch size based on GPU memory**
+- **Stop when performance drops**
+- **Save only the best checkpoints**
+- **Apply rules when patterns are detected**
+
+In other words, **OktoScript doesn't just train models — it governs intelligence.**
+
+---
+
+## 📁 Official Folder Structure
+
+Every OktoScript project must follow this structure:
+
+```
+/my-awesome-model
+├── okt.yaml
+├── dataset/
+│   ├── train.jsonl
+│   ├── val.jsonl
+│   └── test.jsonl
+├── scripts/
+│   └── train.okt
+├── runs/
+│   └── my-model/
+│       ├── checkpoint-100/
+│       │   └── model.safetensors
+│       ├── tokenizer.json
+│       ├── training_logs.json
+│       └── metrics.json
+└── export/
+    ├── model.gguf
+    ├── model.onnx
+    └── model.okm
+```
+
+**v1.1 Optional Folders:**
+
+```
+/runs/
+  └── my-model/
+      ├── logs/
+      │   └── system.json      # MONITOR output (v1.1+)
+      └── lora/                 # LoRA adapters (v1.1+)
+          └── adapter.safetensors
+```
+
+---
+
+## 🧠 OktoScript – Basic Example
+
+**Example (v1.0 - Standard Training):**
+```okt
+PROJECT "PizzaBot"
+DESCRIPTION "AI specialized in pizza restaurant service"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+  backend: "oktoseek"
+  install_missing: true
+}
+
+DATASET {
+  train: "dataset/train.jsonl"
+  validation: "dataset/val.jsonl"
+}
+
+MODEL {
+  base: "oktoseek/pizza-small"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "auto"
+}
+
+EXPORT {
+  format: ["gguf", "onnx", "okm"]
+  path: "export/"
+}
+```
+
+**Example (v1.1 - LoRA Fine-tuning with Dataset Mixing):**
+```okt
+# okto_version: "1.1"
+PROJECT "PizzaBot"
+DESCRIPTION "AI specialized in pizza restaurant service"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+  backend: "oktoseek"
+  install_missing: true
+}
+
+DATASET {
+  mix_datasets: [
+    { path: "dataset/base.jsonl", weight: 70 },
+    { path: "dataset/extra.jsonl", weight: 30 }
+  ]
+  dataset_percent: 80
+  sampling: "weighted"
+}
+
+MODEL {
+  base: "oktoseek/pizza-small"
+}
+
+FT_LORA {
+  base_model: "oktoseek/pizza-small"
+  lora_rank: 8
+  lora_alpha: 32
+  epochs: 3
+  batch_size: 16
+  learning_rate: 0.00003
+  device: "auto"
+}
+
+MONITOR {
+  level: "full"
+  log_metrics: ["loss", "accuracy"]
+  log_system: ["gpu_memory_used", "cpu_usage"]
+  refresh_interval: 2s
+  dashboard: true
+}
+
+EXPORT {
+  format: ["okm", "onnx"]
+  path: "export/"
+}
+```
+
+📘 **Full grammar specification available in** [`/docs/grammar.md`](./docs/grammar.md)
+
+## 🆕 What's New in v1.2
+
+OktoScript v1.2 adds powerful new features while maintaining 100% backward compatibility with v1.0 and v1.1:
+
+- ✅ **Nested CONTROL Blocks** - Support for nested IF/WHEN/EVERY statements inside event hooks
+- ✅ **Enhanced BEHAVIOR** - Added `mode` and `prompt_style` for better control
+- ✅ **Enhanced GUARD** - Added `detect_using` and additional prevention types
+- ✅ **Enhanced DEPLOY** - Added `host`, `protocol`, and `format` options
+- ✅ **Enhanced SECURITY** - Added input/output validation, rate limiting, and encryption
+
+## What's New in v1.1
+
+OktoScript v1.1 adds powerful new features while maintaining 100% backward compatibility with v1.0:
+
+- ✅ **LoRA Fine-tuning** - Efficient fine-tuning with `FT_LORA` block
+- ✅ **Dataset Mixing** - Combine multiple datasets with weighted sampling
+- ✅ **System Monitoring** - Advanced telemetry with `MONITOR` block
+- ✅ **Version Declaration** - Specify OktoScript version in your files
+- ✅ **MODEL Adapters** - LoRA/PEFT adapter support in MODEL block
+- ✅ **Enhanced INFERENCE** - Rich inference configuration with format templates and nested CONTROL
+- ✅ **CONTROL Block** - Cognitive-level decision engine for training and inference
+- ✅ **GUARD Block** - Safety and ethics protection
+- ✅ **BEHAVIOR Block** - Model personality and behavior configuration
+- ✅ **EXPLORER Block** - AutoML-style hyperparameter exploration
+- ✅ **STABILITY Block** - Training stability and safety controls
+- ✅ **Boolean Support** - Native true/false values throughout the language
+
+📚 **More examples and use cases:** See [`/examples/`](./examples/) for complete examples including:
+
+**Basic Examples:**
+- [`basic.okt`](./examples/basic.okt) - Minimal example
+- [`chatbot.okt`](./examples/chatbot.okt) - Conversational AI
+- [`computer_vision.okt`](./examples/computer_vision.okt) - Image classification
+- [`recommender.okt`](./examples/recommender.okt) - Recommendation systems
+
+**Advanced Examples:**
+- [`finetuning-llm.okt`](./examples/finetuning-llm.okt) - Fine-tuning LLM with checkpoints and hooks
+- [`vision-pipeline.okt`](./examples/vision-pipeline.okt) - Complete vision pipeline with augmentation
+- [`qa-embeddings.okt`](./examples/qa-embeddings.okt) - QA system with embeddings
+
+**v1.1 Examples:**
+- [`lora-finetuning.okt`](./examples/lora-finetuning.okt) - LoRA fine-tuning with dataset mixing
+- [`dataset-mixing.okt`](./examples/dataset-mixing.okt) - Training with multiple weighted datasets
+
+**Complete Projects:**
+- [`pizzabot/`](./examples/pizzabot/) - Complete project example with full structure
+
+---
+
+## 📚 Supported Dataset Formats
+
+- ✅ **JSONL** - Line-delimited JSON
+- ✅ **CSV** - Comma-separated values
+- ✅ **TXT** - Plain text files
+- ✅ **Parquet** - Columnar storage
+- ✅ **Image + Caption** - Vision datasets
+- ✅ **Question & Answer (QA)** - Q&A pairs
+- ✅ **Instruction datasets** - Instruction-following
+- ✅ **Multi-modal** - (future support)
+
+### Example (JSONL):
+
+```json
+{"input":"What flavors do you have?","output":"We offer Margherita, Pepperoni and Four Cheese."}
+{"input":"Do you deliver?","output":"Yes, delivery is available in your region."}
+```
+
+---
+
+## 📊 Supported Metrics
+
+- ✅ **Accuracy** - Classification accuracy
+- ✅ **Loss** - Training/validation loss
+- ✅ **Perplexity** - Language model perplexity
+- ✅ **F1-Score** - F1 metric
+- ✅ **BLEU** - Translation quality
+- ✅ **ROUGE-L** - Summarization quality
+- ✅ **MAE / MSE** - Regression metrics
+- ✅ **Cosine Similarity** - Embedding similarity
+- ✅ **Token Efficiency** - Token usage optimization
+- ✅ **Response Coherence** - Response quality
+- ✅ **Hallucination Score** - (experimental)
+
+### Define custom metrics:
+
+```okt
+METRICS {
+  custom "toxicity_score"
+  custom "context_alignment"
+}
+```
+
+---
+
+## 🖥️ CLI Commands
+
+The OktoEngine CLI is minimal by design. All intelligence lives in the `.okt` file. The terminal is just the execution port.
+
+### Core Commands
+
+**Initialize a project:**
+```bash
+okto init
+```
+
+**Validate syntax:**
+```bash
+okto validate script.okt
+```
+
+**Train a model:**
+```bash
+okto train script.okt
+```
+
+**Evaluate a model:**
+```bash
+okto eval script.okt
+```
+
+**Export model:**
+```bash
+okto export script.okt
+```
+
+**Convert model formats:**
+```bash
+okto convert --input <model_path> --from <format> --to <format> --output <output_path>
+```
+
+**Supported formats:**
+| From / To | Usage |
+|-----------|-------|
+| `pt`, `bin` | PyTorch |
+| `onnx` | Web / Interoperability |
+| `tflite` | Mobile (Android / iOS) |
+| `gguf` | Local LLMs (llama.cpp) |
+| `okm` | Okto Model Format |
+| `safetensors` | Safe and fast |
+
+**Convert examples:**
+```bash
+# PyTorch → GGUF (local inference)
+okto convert --input model.pt --from pt --to gguf --output model.gguf
+
+# PyTorch → TFLite (mobile)
+okto convert --input model.pt --from pt --to tflite --output model.tflite
+
+# PyTorch → ONNX (web)
+okto convert --input model.pt --from pt --to onnx --output model.onnx
+```
+
+**List resources:**
+```bash
+okto list projects
+okto list models
+okto list datasets
+okto list exports
+```
+
+**System diagnostics:**
+```bash
+okto doctor
+# Shows: GPU, CUDA, RAM, Drivers, Disks, Recommendations
+```
+
+### Inference Commands
+
+**Direct inference (single input/output):**
+```bash
+okto infer --model <model_path> --text "<input>"
+```
+
+**Example:**
+```bash
+okto infer --model models/pizzabot.okm --text "Good evening, I want a pizza"
+```
+
+Automatically respects:
+- `BEHAVIOR` block
+- `GUARD` block
+- `INFERENCE` block
+- `CONTROL` block (if defined)
+
+**Interactive chat mode:**
+```bash
+okto chat --model <model_path>
+```
+
+Opens an interactive loop:
+```
+🟢 Okto Chat started (type 'exit' to quit)
+
+You: hi
+Bot: Hello! How can I help you?
+
+You: what flavors do you have?
+Bot: We have...
+
+You: exit
+🔴 Session ended
+```
+
+This command:
+- Uses `prompt_style` from BEHAVIOR
+- Uses `BEHAVIOR` settings
+- Respects `GUARD` rules
+- Can use MEMORY in the future
+
+### Advanced Commands
+
+**Compare two models:**
+```bash
+okto compare <model1> <model2>
+```
+
+**Example:**
+```bash
+okto compare models/pizza_v1.okm models/pizza_v2.okm
+```
+
+Expected output:
+```
+Latency: V2 - 23% faster
+Accuracy: V1 - 4% better
+Loss: V2 - lower
+Recommendation: V2
+```
+
+Perfect for A/B testing.
+
+**View historical logs:**
+```bash
+okto logs <model_or_run_id>
+```
+
+**Example:**
+```bash
+okto logs pizzabot_v1
+```
+
+Shows:
+- Loss per epoch
+- Validation loss
+- Accuracy
+- CPU/GPU/RAM usage
+- Decisions made (CONTROL block)
+
+**Auto-tune training:**
+```bash
+okto tune script.okt
+```
+
+Uses the `CONTROL` block to auto-adjust training based on metrics. Can:
+- Adjust learning rate
+- Change batch size
+- Activate early stopping
+- Balance classes
+
+This is unique in the market.
+
+**Exit interactive mode:**
+```bash
+okto exit
+```
+
+Used to exit chat, interactive mode, or session context.
+
+### Utility Commands
+
+```bash
+okto upgrade    # Update OktoEngine
+okto about     # Show about information
+okto --version # Show version
+```
+
+### Quick Examples
+
+```bash
+# Validate and train
+okto validate examples/basic.okt
+okto train examples/chatbot.okt
+
+# Evaluate and export
+okto eval examples/recommender.okt
+okto export examples/computer_vision.okt
+
+# Inference
+okto infer --model models/bot.okm --text "Hello"
+okto chat --model models/bot.okm
+```
+
+---
+
+## 🔄 Training Pipeline
+
+1. **Load dataset** - Parse and validate input data
+2. **Tokenize & validate** - Prepare data for training
+3. **Initialize model** - Load base model and configuration
+4. **Train loop** - Execute training epochs
+5. **Calculate metrics** - Evaluate model performance
+6. **Export selected models** - Generate output formats
+7. **Generate final report** - Create training summary
+
+Each run generates logs at:
+
+```
+runs/my-model/training_logs.json
+runs/my-model/metrics.json
+```
+
+---
+
+## 🔐 Export Formats
+
+### Standard Formats
+
+| Format | Purpose | Compatibility |
+|--------|---------|---------------|
+| `.onnx` | Universal inference, production-ready | All platforms |
+| `.gguf` | Local inference, Ollama, Llama.cpp | Local deployment |
+| `.safetensors` | HuggingFace, research, training | Standard ML tools |
+| `.tflite` | Mobile deployment | Android, iOS (future) |
+
+### OktoSeek Optimized Formats
+
+| Format | Purpose | Benefits |
+|--------|---------|----------|
+| `.okm` | **OktoModel** - Optimized for OktoSeek SDK | Flutter plugins, mobile apps, exclusive tools |
+| `.okx` | **OktoBundle** - Mobile + Edge package | iOS, Android, Edge AI deployment |
+
+> 💡 **Note:** `.okm` and `.okx` formats are **optional** and optimized for the OktoSeek ecosystem. They provide better integration with OktoSeek Flutter SDK, mobile apps, and exclusive tools. You can always export to standard formats (ONNX, GGUF, SafeTensors) for universal compatibility.
+
+**Why use OktoModel (.okm)?**
+
+- ✅ Optimized for OktoSeek Flutter SDK
+- ✅ Better performance on mobile devices
+- ✅ Access to exclusive OktoSeek tools and plugins
+- ✅ Seamless integration with OktoSeek ecosystem
+- ✅ Support for iOS and Android apps
+
+See [`/examples/`](./examples/) for examples using different export formats.
+
+---
+
+## ⚙️ Integration Targets
+
+- ✅ **Flutter** - Mobile applications
+- ✅ **REST API** - Web services
+- ✅ **Edge AI** - Edge devices
+- ✅ **Desktop** - Native applications
+- ✅ **Web** - Browser-based
+- ✅ **Mobile** - iOS/Android
+- ✅ **IoT** - Internet of Things
+- ✅ **Robotics** - Robotic systems
+
+---
+
+## 📦 VS Code Extension (Coming Soon)
+
+- ✨ **Syntax Highlighting** - Beautiful code colors
+- 🔍 **OktoScript autocomplete** - Smart suggestions
+- ⚠️ **Error checking** - Real-time validation
+- ▶️ **Run / Train buttons** - One-click execution
+- 🎨 **Visual pipeline builder** - Drag-and-drop workflows
+
+---
+
+## 📚 Documentation
+
+Complete documentation for OktoScript:
+
+- 📖 **[Grammar Specification](./docs/grammar.md)** - Complete formal grammar with all constraints (v1.0 & v1.1)
+- 🚀 **[Getting Started Guide](./docs/GETTING_STARTED.md)** - Your first 5 minutes with OktoScript
+- ✅ **[Validation Rules](./VALIDATION_RULES.md)** - Complete validation reference (updated for v1.1)
+- ❓ **[FAQ](./docs/FAQ.md)** - Frequently Asked Questions - Common questions and detailed answers
+- 💡 **[Examples](./examples/)** - Working examples from basic to advanced
+- 📋 **[Changelog v1.1](./CHANGELOG_V1.1.md)** - Complete list of v1.1 features
+
+### Advanced Topics
+
+- 🔗 **[Model Inheritance](./docs/grammar.md#model-inheritance)** - Reuse model configurations
+- 🔌 **[Extension Points & Hooks](./docs/grammar.md#extension-points--hooks)** - Custom Python/JS integration
+- 🐛 **[Troubleshooting](./docs/grammar.md#troubleshooting)** - Common issues and solutions
+- ⚙️ **[Complex Examples](./examples/)** - Advanced use cases:
+  - [`finetuning-llm.okt`](./examples/finetuning-llm.okt) - Fine-tuning with checkpoints
+  - [`vision-pipeline.okt`](./examples/vision-pipeline.okt) - Production vision systems
+  - [`qa-embeddings.okt`](./examples/qa-embeddings.okt) - Semantic search and retrieval
+  - [`lora-finetuning.okt`](./examples/lora-finetuning.okt) - LoRA fine-tuning (v1.1)
+  - [`dataset-mixing.okt`](./examples/dataset-mixing.okt) - Dataset mixing (v1.1)
+
+---
+
+## ❓ Frequently Asked Questions (FAQ)
+
+Have questions about OktoScript? Check out our comprehensive FAQ covering common questions from beginners to advanced users:
+
+**Common Questions:**
+- Why do I need MODEL and DATASET blocks with FT_LORA?
+- What's the difference between FT_LORA and TRAIN?
+- Does OktoScript replace Python?
+- How do I use multiple datasets with weights?
+- Can I use custom Python code?
+- Is OktoScript a programming language or a DSL?
+- And 15+ more detailed answers...
+
+📖 **[Read the complete FAQ →](./docs/FAQ.md)**
+
+The FAQ covers technical details, design decisions, use cases, and best practices for using OktoScript effectively.
+
+---
+
+## 🧑‍🚀 Vision
+
+> *"Knowledge must be shared between people so that we can create solutions we could never imagine."*
+> 
+> — **OktoSeek AI**
+
+### 🎯 Design Principles
+
+OktoScript is built on the principle that AI development should be:
+
+1. **Declarative** - Describe what you want, not how to do it
+2. **Self-aware** - Models can monitor and adjust themselves
+3. **Safe** - Built-in guards against harmful outputs
+4. **Adaptive** - Automatic optimization and exploration
+5. **Transparent** - Clear, readable configuration files
+6. **Powerful** - Complex capabilities with simple syntax
+
+The language evolves to support increasingly sophisticated AI behaviors while maintaining its core simplicity.
+
+---
+
+## 🐙 Powered by OktoSeek AI
+
+**OktoScript** is developed and maintained by **OktoSeek AI**.
+
+- **Official website:** https://www.oktoseek.com
+- **GitHub:** https://github.com/oktoseek
+- **Hugging Face:** https://huggingface.co/OktoSeek
+- **Twitter:** https://x.com/oktoseek
+- **YouTube:** https://www.youtube.com/@Oktoseek
+- **Repository:** https://github.com/oktoseek/oktoscript
+
+---
+
+## 📄 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+---
+
+## 📧 Contact
+
+If you have any questions, please raise an issue or contact us at **service@oktoseek.com**.
+
+---
+
+<p align="center">
+  Made with ❤️ by the <strong>OktoSeek AI</strong> team
+</p>

VALIDATION_RULES.md

@@ -0,0 +1,502 @@
+# OktoScript Validation Rules
+
+Complete reference for validation rules and constraints in OktoScript.
+
+---
+
+## File Structure Validation
+
+### Required Files
+
+1. **okt.yaml** (in project root)
+   - Must exist
+   - Must be valid YAML
+   - Must contain `project` field
+
+2. **Dataset Files**
+   - All paths specified in DATASET block must exist
+   - Files must be readable
+   - Format must match declared format
+
+3. **Model Files** (if using local paths)
+   - Base model path must exist (if local)
+   - Checkpoint paths must exist (if resuming)
+
+---
+
+## Field Validation
+
+### PROJECT Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| PROJECT | string | ✅ Yes | 1-100 chars, no special chars: `{}[]:"` |
+
+### ENV Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| accelerator | enum | ❌ No | Must be: `auto`, `cpu`, `gpu`, `tpu` |
+| min_memory | string | ❌ No | Must be: `"4GB"`, `"8GB"`, `"16GB"`, `"32GB"`, `"64GB"` (quoted, GB suffix required) |
+| precision | enum | ❌ No | Must be: `auto`, `fp16`, `fp32`, `bf16` |
+| backend | enum | ❌ No | Must be: `auto`, `oktoseek` |
+| install_missing | boolean | ❌ No | Must be: `true` or `false` (lowercase) |
+| platform | enum | ❌ No | Must be: `windows`, `linux`, `mac`, `any` |
+| network | enum | ❌ No | Must be: `online`, `offline`, `required` |
+
+**ENV Validation Rules:**
+
+1. **Memory format validation:**
+   - Must use `GB` suffix (e.g., `"8GB"`, not `"8"` or `"8 GB"`)
+   - Only values: `"4GB"`, `"8GB"`, `"16GB"`, `"32GB"`, `"64GB"` are allowed
+   - Must be quoted string
+
+2. **Accelerator and memory compatibility:**
+   - If `accelerator = "gpu"` and `min_memory < "8GB"` → **warning** (GPU training typically requires at least 8GB RAM)
+   - If `accelerator = "tpu"` → `min_memory` should be at least `"16GB"` (recommended)
+
+3. **Network and export compatibility:**
+   - If `network = "offline"` → export formats like `onnx` or `gguf` are allowed (pre-downloaded models)
+   - If `network = "required"` → engine must verify internet connectivity before proceeding
+
+4. **Backend preferences:**
+   - If `backend = "oktoseek"` → preferred default for OktoSeek ecosystem
+   - If `backend = "auto"` → engine selects best available backend
+
+5. **Auto-installation:**
+   - If `install_missing = true` → engine must attempt auto-setup of missing dependencies
+   - If `install_missing = false` → engine must fail with clear error if dependencies are missing
+
+6. **Default values:**
+   - If ENV block is missing, defaults to:
+     ```okt
+     ENV {
+       accelerator: "auto"
+       min_memory: "8GB"
+       backend: "auto"
+     }
+     ```
+
+7. **Platform validation:**
+   - If `platform = "windows"` → engine must verify Windows OS
+   - If `platform = "linux"` → engine must verify Linux OS
+   - If `platform = "mac"` → engine must verify macOS
+   - If `platform = "any"` → no platform check required
+
+### DATASET Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| train | path | ✅ Yes | File/dir must exist, readable |
+| validation | path | ❌ No | File/dir must exist if specified |
+| test | path | ❌ No | File/dir must exist if specified |
+| format | enum | ❌ No | Must be: jsonl, csv, txt, parquet, image+caption, qa, instruction, multimodal |
+| type | enum | ❌ No | Must be: classification, generation, qa, chat, vision, regression |
+| language | enum | ❌ No | Must be: en, pt, es, fr, multilingual |
+| augmentation | array | ❌ No | Each item must be valid augmentation type |
+| dataset_percent | number | ❌ No | Must be 1-100 (v1.1+) |
+| mix_datasets | array | ❌ No | Array of {path, weight} objects (v1.1+) |
+| sampling | enum | ❌ No | Must be: weighted, random (v1.1+) |
+| shuffle | boolean | ❌ No | true or false (v1.1+) |
+
+### MODEL Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| base | string | ✅ Yes | Valid model identifier or path |
+| architecture | enum | ❌ No | Must be: transformer, cnn, rnn, diffusion, vision-transformer, bert, gpt, t5 |
+| parameters | string | ❌ No | Format: number + (K\|M\|B), e.g., "120M" |
+| context_window | number | ❌ No | Must be power of 2: 128, 256, 512, 1024, 2048, 4096, 8192 |
+| precision | enum | ❌ No | Must be: fp32, fp16, int8, int4 |
+| inherit | string | ❌ No | Must reference existing model name |
+
+### TRAIN Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| epochs | number | ✅ Yes | > 0 and <= 1000 |
+| batch_size | number | ✅ Yes | > 0 and <= 1024 |
+| learning_rate | decimal | ❌ No | > 0 and <= 1.0 |
+| optimizer | enum | ❌ No | Must be: adam, adamw, sgd, rmsprop, adafactor, lamb |
+| scheduler | enum | ❌ No | Must be: linear, cosine, cosine_with_restarts, polynomial, constant, constant_with_warmup, step |
+| device | enum | ✅ Yes | Must be: cpu, cuda, mps, auto |
+| gradient_accumulation | number | ❌ No | >= 1 |
+| early_stopping | boolean | ❌ No | true or false |
+| checkpoint_steps | number | ❌ No | > 0 |
+| checkpoint_path | path | ❌ No | Directory must exist if specified |
+| resume_from_checkpoint | path | ❌ No | Checkpoint must exist if specified |
+| loss | enum | ❌ No | Must be: cross_entropy, mse, mae, bce, focal, huber, kl_divergence |
+| weight_decay | decimal | ❌ No | >= 0 and <= 1.0 |
+| gradient_clip | decimal | ❌ No | > 0 |
+| warmup_steps | number | ❌ No | >= 0 |
+| save_strategy | enum | ❌ No | Must be: steps, epoch, no |
+
+### METRICS Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| Built-in metrics | identifier | ❌ No | Must be valid metric name |
+| custom | string | ❌ No | Custom metric identifier |
+
+**Metric-task compatibility:**
+- `accuracy`, `precision`, `recall`, `f1`, `confusion_matrix`: Only for classification
+- `perplexity`: Only for language models
+- `bleu`, `rouge`: Only for generation/translation
+- `mae`, `mse`, `rmse`: Only for regression
+
+### EXPORT Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| format | array | ✅ Yes | Each item must be: gguf, onnx, okm, safetensors, tflite |
+| path | path | ✅ Yes | Directory must exist or be creatable |
+| quantization | enum | ❌ No | Must be: int8, int4, fp16, fp32 |
+| optimize_for | enum | ❌ No | Must be: speed, size, accuracy |
+
+**Format-specific requirements:**
+- `gguf`: Requires quantization
+- `tflite`: Only for mobile-compatible architectures
+
+### FT_LORA Block (v1.1+)
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| base_model | string | ✅ Yes | Valid model identifier or path |
+| train_dataset | path | ✅ Yes | File/dir must exist if specified |
+| lora_rank | number | ✅ Yes | > 0 and <= 256 |
+| lora_alpha | number | ✅ Yes | > 0 |
+| dataset_percent | number | ❌ No | 1-100 |
+| mix_datasets | array | ❌ No | Array of {path, weight}, total weights = 100 |
+| epochs | number | ❌ No | > 0 and <= 1000 |
+| batch_size | number | ❌ No | > 0 and <= 1024 |
+| learning_rate | decimal | ❌ No | > 0 and <= 1.0 |
+| device | enum | ❌ No | Must be: cpu, cuda, mps, auto |
+| target_modules | array | ❌ No | Array of module names |
+
+**Validation Rules:**
+- If `mix_datasets` is specified, it overrides `train_dataset`
+- Total weights in `mix_datasets` must equal exactly 100
+- `lora_rank` typically: 4, 8, 16, 32
+- `lora_alpha` typically: 16, 32, 64
+- Cannot use both `TRAIN` and `FT_LORA` in same file
+
+### MODEL Block — ADAPTER Sub-block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| type | enum | ✅ Yes | Must be: lora, qlora, adapter, peft |
+| path | path | ✅ Yes | Must exist and be valid adapter path |
+| rank | number | ❌ No | > 0, typically 4, 8, 16, 32, 64 |
+| alpha | number | ❌ No | > 0, typically 16, 32, 64 |
+
+**Validation Rules:**
+- If ADAPTER is defined, it is applied after base model is loaded
+- Adapter path must exist and be readable
+- ADAPTER is optional within MODEL block
+
+### INFERENCE Block (Expanded)
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| mode | enum | ✅ Yes | Must be: chat, intent, translate, classify, custom |
+| format | string | ❌ No | Template string with {input}, {context}, {labels} |
+| exit_command | string | ❌ No | Command to exit chat mode |
+| params | object | ❌ No | Inference parameters object |
+| CONTROL | block | ❌ No | Nested CONTROL block for inference |
+
+**INFERENCE params:**
+- `max_length`: > 0 and <= 8192
+- `temperature`: >= 0.0 and <= 2.0
+- `top_p`: > 0.0 and <= 1.0
+- `beams`: >= 1
+- `do_sample`: boolean (true/false)
+- `top_k`: >= 0 (0 = disabled)
+- `repetition_penalty`: > 0.0 and <= 2.0
+
+**Validation Rules:**
+- IF INFERENCE exists THEN MODEL is required
+- Format string must contain at least {input} for most modes
+- CONTROL within INFERENCE can only use: RETRY, REGENERATE, REPLACE
+
+### CONTROL Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| IF | condition | ❌ No | Conditional logic |
+| WHEN | condition | ❌ No | Event-based conditional |
+| EVERY | number + steps | ❌ No | Periodic actions |
+| SET | assignment | ❌ No | Set parameter value |
+| STOP | action | ❌ No | Stop operation |
+| LOG | metric/string | ❌ No | Log value or message |
+| SAVE | target | ❌ No | Save model/checkpoint |
+| RETRY | action | ❌ No | Retry inference |
+| REGENERATE | action | ❌ No | Regenerate output |
+| STOP_TRAINING | action | ❌ No | Stop training |
+| DECREASE | parameter + BY + value | ❌ No | Decrease parameter |
+| INCREASE | parameter + BY + value | ❌ No | Increase parameter |
+| on_step_end | block | ❌ No | Hook executed at step end |
+| on_epoch_end | block | ❌ No | Hook executed at epoch end |
+| on_memory_low | block | ❌ No | Hook executed when memory low |
+| on_nan | block | ❌ No | Hook executed on NaN |
+| on_plateau | block | ❌ No | Hook executed on loss plateau |
+| validate_every | number | ❌ No | Validate every N steps |
+
+**Validation Rules:**
+- IF CONTROL used THEN must contain at least one of: IF | WHEN | EVERY | on_step_end | on_epoch_end
+- Boolean values accepted = true | false
+- Allowed CONTROL keywords = IF | WHEN | EVERY | SET | STOP | LOG | SAVE | RETRY | REGENERATE | STOP_TRAINING | DECREASE | INCREASE
+- validate_every must receive integer
+- DECREASE LR requires numeric value
+- Conditions must use valid comparison operators: >, <, >=, <=, ==, !=
+
+### MONITOR Block (v1.1+)
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| metrics | array | ❌ No | Array of metric names |
+| notify_if | object | ❌ No | Conditions for notifications |
+| log_to | path | ❌ No | Path to log file |
+| level | enum | ❌ No | Must be: basic, full |
+| log_system | array | ❌ No | Array of system metric names |
+| log_speed | array | ❌ No | Array of speed metric names |
+| refresh_interval | string | ❌ No | Format: number + "s" or "ms", >= 1s |
+| export_to | path | ❌ No | Directory must exist or be creatable |
+| dashboard | boolean | ❌ No | true or false |
+
+**System Metrics:**
+- `gpu_memory_used`, `gpu_memory_free`, `gpu_usage`, `gpu_temperature`: Only if CUDA available
+- `temperature`: Only if hardware supports it
+
+**Validation Rules:**
+- GPU metrics only validated if CUDA is available
+- `refresh_interval` must be >= 1s
+- `MONITOR` extends `METRICS` and `LOGGING`, does not replace them
+- `notify_if` conditions must use valid comparison operators
+- Supported metrics: loss, accuracy, val_loss, val_accuracy, gpu_usage, ram_usage, throughput, latency, confidence, hallucination_score, and all custom metrics
+
+### GUARD Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| prevent | object | ❌ No | Array of prevention types |
+| on_violation | object | ❌ No | Action on violation |
+
+**Prevention types:**
+- `hallucination`, `toxicity`, `bias`, `data_leak`, `unsafe_code`
+
+**Validation Rules:**
+- GUARD.on_violation can only be STOP or ALERT or REPLACE or LOG
+- Prevention types must be valid enum values
+
+### BEHAVIOR Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| personality | enum | ❌ No | Must be: professional, friendly, assistant, casual, formal, creative |
+| verbosity | enum | ❌ No | Must be: low, medium, high |
+| language | enum | ❌ No | Must be: en, pt-BR, es, fr, de, it, ja, zh, multilingual |
+| avoid | array | ❌ No | Array of strings to avoid |
+| fallback | string | ❌ No | Fallback message |
+
+**Validation Rules:**
+- All enum values must match allowed values
+- fallback must be a non-empty string if provided
+
+### EXPLORER Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| try | object | ✅ Yes | Parameter combinations to test |
+| max_tests | number | ❌ No | Must be <= 50 |
+| pick_best_by | string | ❌ No | Must be valid metric name |
+
+**Validation Rules:**
+- EXPLORER.max_tests must be <= 50
+- pick_best_by must be a valid metric (e.g., "val_loss", "accuracy")
+- try object must contain at least one parameter array
+- Parameter arrays must contain valid values for their type
+
+### STABILITY Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| stop_if_nan | boolean | ❌ No | true or false |
+| stop_if_diverges | boolean | ❌ No | true or false |
+| min_improvement | decimal | ❌ No | Must be float >= 0 |
+
+**Validation Rules:**
+- STABILITY.min_improvement must be float
+- Boolean values must be true or false (lowercase)
+
+### DEPLOY Block
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| target | enum | ✅ Yes | Must be: local, cloud, edge, api, android, ios, web, desktop |
+| endpoint | string | ❌ No | Required if target is "api" |
+| requires_auth | boolean | ❌ No | true or false |
+| port | number | ❌ No | Required if target is "api", must be 1024-65535 |
+| max_concurrent_requests | number | ❌ No | > 0 |
+
+---
+
+## Dependency Validation
+
+### Model Inheritance
+
+- If `inherit` is specified, parent model must be defined
+- Circular inheritance is not allowed
+- Inheritance chain depth limited to 10 levels
+
+### Checkpoint Resume
+
+- If `resume_from_checkpoint` is specified:
+  - Checkpoint directory must exist
+  - Checkpoint must contain valid model files
+  - Checkpoint must be compatible with current model architecture
+
+### Export Compatibility
+
+- Model architecture must support export format
+- Quantization required for certain formats (gguf)
+- Mobile formats (tflite, okm) require compatible architectures
+
+---
+
+## Runtime Validation
+
+### Dataset Validation
+
+**File existence:**
+- All dataset paths must exist
+- Files must be readable
+- Directories must be accessible
+
+**Format validation:**
+- JSONL: Each line must be valid JSON
+- CSV: Must have header row, consistent columns
+- Image+caption: Directory must contain image files and captions
+
+**Size limits:**
+- Maximum file size: 10GB per file
+- Maximum total dataset size: 100GB
+- Minimum examples: 10 for training
+
+**Dataset Mixing (v1.1+):**
+- If `mix_datasets` is specified, `train` is ignored
+- All paths in `mix_datasets` must exist
+- Total weights must equal exactly 100
+- `dataset_percent` applies to the mixed dataset
+- `sampling: "weighted"` uses weights, `"random"` ignores them
+
+### Model Validation
+
+**Base model:**
+- If local path: Must exist and be valid model directory
+- If HuggingFace: Must be downloadable
+- If URL: Must be accessible
+
+**Architecture compatibility:**
+- Model architecture must match dataset type
+- Vision models require image datasets
+- Language models require text datasets
+
+### Training Validation
+
+**Hardware requirements:**
+- GPU required if `device: "cuda"` and `gpu: true`
+- Sufficient VRAM for batch size
+- Sufficient disk space for checkpoints
+
+**Memory validation:**
+- Batch size must fit in available memory
+- Effective batch size (batch_size × gradient_accumulation) validated
+
+---
+
+## Error Codes
+
+| Code | Error | Solution |
+|------|-------|----------|
+| V001 | Dataset file not found | Check file path, use absolute or relative path |
+| V002 | Invalid optimizer | Use one of: adam, adamw, sgd, rmsprop, adafactor, lamb |
+| V003 | Invalid scheduler | Use one of: linear, cosine, cosine_with_restarts, polynomial, constant, constant_with_warmup, step |
+| V004 | Model base not found | Verify model path or HuggingFace model name |
+| V005 | Checkpoint not found | Check checkpoint path or remove resume_from_checkpoint |
+| V006 | Insufficient memory | Reduce batch_size or enable gradient_accumulation |
+| V007 | Invalid metric for task | Use appropriate metrics for task type |
+| V008 | Invalid export format | Check format compatibility with model architecture |
+| V009 | Circular inheritance | Remove circular model inheritance chain |
+| V010 | Invalid field value | Check field constraints and allowed values |
+| V011 | Dataset mixing weights invalid | Total weights in mix_datasets must equal 100 |
+| V012 | FT_LORA and TRAIN conflict | Cannot use both TRAIN and FT_LORA in same file |
+| V013 | Version declaration invalid | Version must be "1.0" or "1.1" |
+| V014 | GPU metrics unavailable | GPU metrics requested but CUDA not available |
+| V015 | CONTROL block empty | CONTROL must contain at least one directive |
+| V016 | Invalid CONTROL keyword | Use only allowed CONTROL keywords |
+| V017 | EXPLORER max_tests too high | max_tests must be <= 50 |
+| V018 | Invalid boolean value | Boolean must be true or false (lowercase) |
+| V019 | INFERENCE without MODEL | INFERENCE block requires MODEL block |
+| V020 | Invalid adapter type | ADAPTER type must be: lora, qlora, adapter, peft |
+| V021 | GUARD violation action invalid | on_violation must be: STOP, ALERT, REPLACE, or LOG |
+
+---
+
+## Validation Commands
+
+### CLI Validation
+
+```bash
+# Validate syntax and structure
+okto validate train.okt
+
+# Validate with detailed output
+okto validate train.okt --verbose
+
+# Validate dataset only
+okto validate train.okt --dataset-only
+
+# Validate model only
+okto validate train.okt --model-only
+```
+
+### IDE Validation
+
+OktoSeek IDE automatically validates:
+- Real-time syntax checking
+- Field completion suggestions
+- Error highlighting
+- Warning messages
+
+---
+
+## Best Practices
+
+1. **Always validate before training**
+   ```bash
+   okto validate train.okt
+   ```
+
+2. **Check dataset format**
+   - Use `okto validate --dataset-only` to verify dataset structure
+
+3. **Verify model compatibility**
+   - Ensure model architecture matches dataset type
+   - Check export format compatibility
+
+4. **Test with small dataset first**
+   - Use subset of data for initial validation
+   - Verify pipeline works before full training
+
+5. **Monitor resource usage**
+   - Check available GPU memory
+   - Verify disk space for checkpoints
+   - Monitor training progress
+
+---
+
+**For more information, see:**
+- [Grammar Specification](./docs/grammar.md)
+- [Getting Started Guide](./docs/GETTING_STARTED.md)
+- [Troubleshooting](./docs/grammar.md#troubleshooting)
+

assets/README.md

@@ -0,0 +1,22 @@
+# Assets Directory
+
+This directory contains visual assets for the OktoScript project.
+
+## Required Images
+
+### `oktoscript_banner.png`
+- **Dimensions:** Recommended 1200x300px or similar aspect ratio
+- **Purpose:** Main banner image for README.md
+- **Content:** Should display "OktoScript" branding with visual design
+
+### `okto_logo.png`
+- **Dimensions:** Recommended 240x240px (square, will be displayed at 80px)
+- **Purpose:** Company logo for README.md
+- **Content:** OktoSeek AI company logo
+
+## Notes
+
+- Images should be optimized for web (PNG with transparency or optimized formats)
+- Ensure images are properly licensed for use in the repository
+- Update README.md image paths if filenames change
+

docs/FAQ.md

@@ -0,0 +1,865 @@
+# OktoScript – Frequently Asked Questions (FAQ)
+
+Common questions and answers about OktoScript, a domain-specific language for AI training, evaluation, and deployment.
+
+---
+
+## 1. Even if FT_LORA already points to a base model and dataset, why must I still declare the MODEL and DATASET blocks?
+
+**Answer:**
+
+In OktoScript, `MODEL` and `DATASET` blocks define the **global context** of your project. They represent the default base configuration for the entire pipeline.
+
+The `FT_LORA` block does not replace them—it only defines **how** the fine-tuning is performed. This explicit separation makes scripts clearer, more organized, and avoids hidden assumptions.
+
+**Benefits of explicit declaration:**
+- ✅ **Readability** - Anyone can understand the project structure at a glance
+- ✅ **Debugging** - Clear separation of concerns makes troubleshooting easier
+- ✅ **Reproducibility** - All configuration is visible and version-controlled
+- ✅ **Documentation** - The script serves as self-documenting code
+
+**Example:**
+```okt
+MODEL {
+    base: "oktoseek/base-llm-7b"  # Global model context
+}
+
+DATASET {
+    train: "dataset/main.jsonl"   # Global dataset context
+}
+
+FT_LORA {
+    base_model: "oktoseek/base-llm-7b"  # Explicit for LoRA
+    train_dataset: "dataset/main.jsonl"  # Explicit for LoRA
+    lora_rank: 8
+}
+```
+
+This design follows the principle: **explicit is better than implicit**, especially in AI pipelines where assumptions can lead to costly mistakes.
+
+---
+
+## 2. If I already use FT_LORA, why is the TRAIN block still mandatory?
+
+**Answer:**
+
+`FT_LORA` defines **what kind of training** happens (LoRA adapters), but `TRAIN` defines **how the training loop is executed** (optimizer, batch size, device, etc.).
+
+**Think of it this way:**
+- `TRAIN` = The engine (how training runs)
+- `FT_LORA` = The driving mode (what gets trained)
+
+**The TRAIN block controls:**
+- Optimizer (adam, adamw, sgd, etc.)
+- Batch size and gradient accumulation
+- Device selection (cpu, cuda, mps)
+- Learning rate and scheduler
+- Training strategy (early stopping, checkpoints)
+
+**Example:**
+```okt
+TRAIN {
+    epochs: 5
+    batch_size: 4
+    optimizer: "adamw"
+    learning_rate: 0.00003
+    device: "cuda"
+}
+
+FT_LORA {
+    lora_rank: 8
+    lora_alpha: 32
+    target_modules: ["q_proj", "v_proj"]
+}
+```
+
+Both blocks are required because they serve different purposes in the declarative DSL structure.
+
+---
+
+## 3. How do I define the final output of my model in OktoScript?
+
+**Answer:**
+
+The final output is always defined in the `EXPORT` block, regardless of whether you use `TRAIN` or `FT_LORA`.
+
+**For standard training:**
+```okt
+EXPORT {
+    format: ["gguf", "onnx", "okm"]
+    path: "./export/"
+}
+```
+
+**For LoRA fine-tuning:**
+```okt
+EXPORT {
+    format: ["safetensors", "okm"]
+    path: "./export/lora_patch/"
+}
+```
+
+**What gets exported:**
+- With `TRAIN`: Full model weights in specified formats
+- With `FT_LORA`: LoRA adapter weights (safetensors) + optional merged model (okm)
+
+The `EXPORT` block controls:
+- ✅ Adapter generation (LoRA patches via safetensors)
+- ✅ OktoSeek package generation (okm format)
+- ✅ Cross-platform formats (onnx, gguf)
+- ✅ Quantization settings
+
+**Key point:** Export responsibility is clearly separated from training logic, keeping the DSL clean and modular.
+
+---
+
+## 4. What is the difference between FT_LORA and TRAIN blocks?
+
+**Answer:**
+
+| Block | Role | Purpose |
+|-------|------|---------|
+| `TRAIN` | Training loop configuration | Defines **how** training runs (optimizer, batch size, device) |
+| `FT_LORA` | LoRA adapter configuration | Defines **what** gets trained (LoRA rank, alpha, target modules) |
+
+**Important:** `FT_LORA` is **not** a replacement for `TRAIN`—it's an **extension** that modifies how training is applied to the model.
+
+**When to use each:**
+- **Use `TRAIN` alone:** Full fine-tuning of all model parameters
+- **Use `TRAIN` + `FT_LORA`:** Efficient fine-tuning with LoRA adapters (recommended for large models)
+
+**Example:**
+```okt
+# Full fine-tuning
+TRAIN {
+    epochs: 10
+    batch_size: 32
+    device: "cuda"
+}
+
+# LoRA fine-tuning (more efficient)
+TRAIN {
+    epochs: 5
+    batch_size: 4
+    device: "cuda"
+}
+
+FT_LORA {
+    lora_rank: 8
+    lora_alpha: 32
+}
+```
+
+This separation keeps the language modular and scalable.
+
+---
+
+## 5. Do I need to repeat the base model inside FT_LORA if it is already declared in MODEL?
+
+**Answer:**
+
+**Yes, by design.** OktoScript prefers explicit declarations over implicit inference.
+
+Even though the engine could technically infer the model from `MODEL`, keeping `base_model` inside `FT_LORA`:
+
+- ✅ **Avoids ambiguity** - No guessing which model is used
+- ✅ **Makes scripts self-contained** - Each block is independent
+- ✅ **Improves readability** - Clear at a glance what's happening
+- ✅ **Helps during audits** - Easier to review and validate
+
+**Example:**
+```okt
+MODEL {
+    base: "oktoseek/base-llm-7b"  # Global context
+}
+
+FT_LORA {
+    base_model: "oktoseek/base-llm-7b"  # Explicit for LoRA
+    lora_rank: 8
+}
+```
+
+**This is an intentional design decision** to favor clarity and safety over convenience. In AI pipelines, explicit is safer than implicit.
+
+---
+
+## 6. What happens if I use both DATASET.train and mix_datasets at the same time?
+
+**Answer:**
+
+**Simple rule:** `mix_datasets` **overrides** `DATASET.train` when present.
+
+**Priority order:**
+1. `mix_datasets` in `FT_LORA` (highest priority)
+2. `mix_datasets` in `DATASET` block
+3. `DATASET.train` (default, lowest priority)
+
+**Example:**
+```okt
+DATASET {
+    train: "dataset/main.jsonl"  # Default dataset
+}
+
+FT_LORA {
+    mix_datasets: [
+        { path: "dataset/a.jsonl", weight: 70 },
+        { path: "dataset/b.jsonl", weight: 30 }
+    ]
+    # This mix_datasets overrides DATASET.train
+}
+```
+
+**Why this design?**
+- Allows flexibility without breaking the main structure
+- Enables dataset-specific configurations per training method
+- Maintains backward compatibility with v1.0
+
+**Best practice:** Use `DATASET.train` for the default, and `mix_datasets` when you need weighted mixing.
+
+---
+
+## 7. Does OktoScript replace Python?
+
+**Answer:**
+
+**No.** OktoScript does **not** replace Python. Instead, it replaces the **complex configuration boilerplate** typically written in Python.
+
+**The relationship:**
+- **Python** = Coding and programming (general-purpose language)
+- **OktoScript** = Configuration of AI pipelines (domain-specific language)
+
+**Think of it this way:**
+```
+Python (Engine) ← OktoScript (Configuration Layer) ← User
+```
+
+OktoScript sits **above** Python as a declarative layer, while Python powers the OktoEngine underneath.
+
+**What OktoScript replaces:**
+- ❌ Hundreds of lines of Python configuration code
+- ❌ Complex YAML files with unclear structure
+- ❌ Repetitive training scripts
+
+**What Python still does:**
+- ✅ Powers the OktoEngine
+- ✅ Executes the training loop
+- ✅ Handles low-level operations
+- ✅ Provides hooks for custom logic
+
+**Analogy:** OktoScript is to Python what Docker Compose is to Docker—a declarative configuration layer that simplifies complex operations.
+
+---
+
+## 8. Can I use multiple datasets with different weights?
+
+**Answer:**
+
+**Yes!** This is one of the key features of OktoScript v1.1.
+
+**Syntax:**
+```okt
+DATASET {
+    mix_datasets: [
+        { path: "dataset/general.jsonl", weight: 60 },
+        { path: "dataset/technical.jsonl", weight: 30 },
+        { path: "dataset/creative.jsonl", weight: 10 }
+    ]
+    sampling: "weighted"
+    shuffle: true
+}
+```
+
+**Benefits:**
+- ✅ **Balanced training** - Control dataset proportions
+- ✅ **Domain blending** - Combine different data sources
+- ✅ **Bias reduction** - Weight underrepresented data
+- ✅ **Dataset prioritization** - Emphasize important data
+
+**Rules:**
+- Total weights must equal **exactly 100**
+- `sampling: "weighted"` uses weights for sampling
+- `sampling: "random"` ignores weights (uniform sampling)
+- `shuffle: true` shuffles datasets before mixing
+
+**Use case example:**
+```okt
+# Mix general conversations (60%) with technical Q&A (30%) and creative writing (10%)
+mix_datasets: [
+    { path: "dataset/conversations.jsonl", weight: 60 },
+    { path: "dataset/technical_qa.jsonl", weight: 30 },
+    { path: "dataset/creative.jsonl", weight: 10 }
+]
+```
+
+---
+
+## 9. What is the difference between EXPORT: safetensors and EXPORT: okm?
+
+**Answer:**
+
+| Format | Purpose | Use Case |
+|--------|---------|----------|
+| `safetensors` | Standard PyTorch weights format | LoRA adapters, model weights, HuggingFace compatibility |
+| `okm` | OktoSeek optimized package | OktoSeek IDE, Flutter SDK, mobile apps, exclusive tools |
+| `onnx` | Universal inference format | Production deployment, cross-platform compatibility |
+| `gguf` | Local inference format | Ollama, Llama.cpp, local deployment |
+
+**For LoRA fine-tuning:**
+- `safetensors` → Saves only the LoRA adapter patch (small file, ~10-100MB)
+- `okm` → Saves a full OktoSeek model package (includes adapter + metadata)
+
+**Example:**
+```okt
+FT_LORA {
+    lora_rank: 8
+}
+
+EXPORT {
+    format: ["safetensors", "okm"]
+    path: "./export/"
+}
+```
+
+**Output:**
+- `./export/adapter.safetensors` - LoRA adapter (for HuggingFace/PyTorch)
+- `./export/model.okm` - OktoSeek package (for OktoSeek ecosystem)
+
+**Why both?**
+- `safetensors` for compatibility with standard ML tools
+- `okm` for optimized OktoSeek ecosystem integration
+
+---
+
+## 10. Is OktoScript a programming language or a DSL?
+
+**Answer:**
+
+**OktoScript is a Domain-Specific Language (DSL).**
+
+**What it is NOT:**
+- ❌ A general-purpose programming language
+- ❌ A scripting language with loops and variables
+- ❌ A replacement for Python or JavaScript
+
+**What it IS:**
+- ✅ A declarative configuration language
+- ✅ Purpose-built for AI pipelines
+- ✅ Domain-specific (focused on AI training/deployment)
+
+**Key characteristics:**
+- **Declarative** - You describe **what** you want, not **how** to do it
+- **No control flow** - No loops, conditionals, or functions
+- **Block-based** - Configuration organized in semantic blocks
+- **Type-safe** - Validated against grammar specification
+
+**Why call it a DSL?**
+- ✅ Technically accurate
+- ✅ Increases professional credibility
+- ✅ Sets correct expectations
+- ✅ Distinguishes from general-purpose languages
+
+**Analogy:** OktoScript is to AI pipelines what SQL is to databases—a specialized language for a specific domain.
+
+---
+
+## 11. What happens internally when I write FT_LORA?
+
+**Answer:**
+
+When you use `FT_LORA`, the OktoEngine performs these steps:
+
+**1. Model Loading:**
+- Loads the base model specified in `base_model`
+- Initializes model architecture
+
+**2. LoRA Adapter Injection:**
+- Freezes the main model layers
+- Adds LoRA adapters to selected modules (e.g., `q_proj`, `v_proj`)
+- Adapters are low-rank matrices (rank × alpha)
+
+**3. Training:**
+- Trains **only** the LoRA adapter weights
+- Main model weights remain frozen
+- Uses optimizer and settings from `TRAIN` block
+
+**4. Export:**
+- Saves adapter weights via `EXPORT` block
+- Optionally merges adapter into base model (if specified)
+
+**Benefits:**
+- ✅ **Reduced GPU usage** - Up to 90% less VRAM
+- ✅ **Faster training** - Only small adapters are updated
+- ✅ **Smaller files** - Adapter weights are tiny (~10-100MB)
+- ✅ **Specialization** - Multiple adapters for different tasks
+- ✅ **Flexibility** - Combine adapters at inference time
+
+**Example flow:**
+```
+Base Model (7B params, frozen)
+    ↓
++ LoRA Adapters (8 rank × 32 alpha = ~256 params per module)
+    ↓
+Training (only adapters updated)
+    ↓
+Export adapter.safetensors (~50MB)
+```
+
+---
+
+## 12. Why is explicit declaration required instead of auto-inference?
+
+**Answer:**
+
+**Because transparency is better than hidden assumptions**, especially in AI pipelines.
+
+**Problems with auto-inference:**
+- ❌ Hidden assumptions can lead to silent mistakes
+- ❌ Difficult to debug when things go wrong
+- ❌ Unclear what the system is actually doing
+- ❌ Harder to audit and review
+
+**Benefits of explicit declaration:**
+- ✅ **Self-documenting** - Scripts explain themselves
+- ✅ **Auditable** - Easy to review and validate
+- ✅ **Beginner-friendly** - Clear what's happening
+- ✅ **Safe** - No hidden behavior or assumptions
+
+**Example of explicit vs implicit:**
+```okt
+# Explicit (OktoScript style)
+MODEL {
+    base: "oktoseek/base-llm-7b"
+}
+
+FT_LORA {
+    base_model: "oktoseek/base-llm-7b"  # Explicit, even if redundant
+}
+
+# Implicit (what we avoid)
+FT_LORA {
+    # base_model inferred from MODEL block - NOT in OktoScript
+}
+```
+
+**Philosophy:** In AI, explicit is safer than implicit. A few extra lines of configuration prevent costly mistakes.
+
+---
+
+## 13. Can I run LoRA without EXPORT?
+
+**Answer:**
+
+**Technically yes, but it's not recommended.**
+
+**What happens without EXPORT:**
+- ✅ Training completes successfully
+- ✅ Adapter weights are trained
+- ❌ Adapter weights are **not saved**
+- ❌ Training becomes useless after process ends
+
+**Best practice:**
+```okt
+FT_LORA {
+    lora_rank: 8
+    lora_alpha: 32
+}
+
+EXPORT {
+    format: ["safetensors", "okm"]
+    path: "./export/"
+}
+```
+
+**Why always include EXPORT:**
+- ✅ Preserves your work
+- ✅ Enables model reuse
+- ✅ Allows deployment
+- ✅ Supports version control
+
+**Exception:** If you're only testing or debugging, you might skip EXPORT temporarily, but always add it before production training.
+
+---
+
+## 14. What if I want to merge a LoRA adapter into the final model later?
+
+**Answer:**
+
+**Current support (v1.1):**
+
+You can merge LoRA adapters using OktoEngine's internal tools or Python hooks:
+
+**Option 1: Using Hooks (Current)**
+```okt
+HOOKS {
+    after_train: "scripts/merge_lora.py"
+}
+```
+
+**Option 2: Manual merge with OktoEngine CLI**
+```bash
+okto_merge --adapter ./export/adapter.safetensors \
+           --base ./models/base-model \
+           --output ./export/merged-model
+```
+
+**Future support (v2.0+):**
+
+A dedicated `MERGE` block is planned:
+
+```okt
+MERGE {
+    source: "export/adapter.safetensors"
+    target: "models/base-model"
+    output: "export/merged-model"
+    format: ["okm", "onnx"]
+}
+```
+
+**Why merge?**
+- ✅ Single model file (no separate adapter needed)
+- ✅ Faster inference (no adapter loading)
+- ✅ Easier deployment (one file instead of two)
+- ✅ Better compatibility (works with standard tools)
+
+**When to merge:**
+- After training is complete
+- Before deployment
+- When you want a standalone model
+
+---
+
+## 15. Why choose OktoScript over YAML or Python scripts?
+
+**Answer:**
+
+**OktoScript is purpose-built for AI pipelines**, while YAML and Python are generic tools.
+
+**Comparison:**
+
+| Feature | OktoScript | YAML | Python |
+|---------|------------|------|--------|
+| **Purpose** | AI pipelines | Generic config | General programming |
+| **Readability** | ✅ Block-based, semantic | ⚠️ Flat, no structure | ❌ Code complexity |
+| **Validation** | ✅ Grammar-enforced | ⚠️ Manual validation | ❌ Runtime errors |
+| **Type Safety** | ✅ Built-in | ❌ No types | ⚠️ Runtime checking |
+| **AI-Specific** | ✅ LoRA, RAG, monitoring | ❌ Generic | ⚠️ Requires libraries |
+| **Learning Curve** | ✅ Simple blocks | ⚠️ Syntax learning | ❌ Programming required |
+| **IDE Support** | ✅ OktoSeek IDE | ⚠️ Generic editors | ✅ IDEs available |
+
+**Key advantages of OktoScript:**
+
+1. **Purpose-built for AI**
+   - Native support for LoRA, RAG, monitoring
+   - AI-specific blocks and concepts
+   - Optimized for ML workflows
+
+2. **Human-oriented**
+   - Readable by non-programmers
+   - Self-documenting structure
+   - Clear semantic blocks
+
+3. **Less error-prone**
+   - Grammar validation
+   - Type checking
+   - Constraint enforcement
+
+4. **Integrated ecosystem**
+   - OktoSeek IDE support
+   - OktoEngine integration
+   - Flutter SDK compatibility
+
+5. **Single config file**
+   - Everything in one `.okt` file
+   - No scattered configuration
+   - Version control friendly
+
+**Example comparison:**
+
+**YAML (generic):**
+```yaml
+model:
+  base: "oktoseek/base"
+train:
+  epochs: 5
+  batch_size: 32
+# No validation, no structure, unclear relationships
+```
+
+**Python (complex):**
+```python
+from transformers import Trainer, TrainingArguments
+# 100+ lines of code
+# Complex error handling
+# Hard to read and maintain
+```
+
+**OktoScript (focused):**
+```okt
+MODEL {
+    base: "oktoseek/base"
+}
+
+TRAIN {
+    epochs: 5
+    batch_size: 32
+}
+# Clear, validated, self-documenting
+```
+
+**Bottom line:** OktoScript is to AI pipelines what Docker Compose is to containers—a declarative DSL that simplifies complex operations.
+
+---
+
+## 16. How does OktoScript handle model versioning and checkpoints?
+
+**Answer:**
+
+OktoScript uses the `runs/` directory structure for automatic versioning and checkpoint management.
+
+**Structure:**
+```
+runs/
+  └── my-model/
+      ├── checkpoint-100/
+      │   └── model.safetensors
+      ├── checkpoint-200/
+      │   └── model.safetensors
+      ├── tokenizer.json
+      ├── training_logs.json
+      └── metrics.json
+```
+
+**Checkpoint configuration:**
+```okt
+TRAIN {
+    epochs: 10
+    checkpoint_steps: 100  # Save every 100 steps
+    checkpoint_path: "./checkpoints"
+}
+```
+
+**Resume from checkpoint:**
+```okt
+TRAIN {
+    resume_from_checkpoint: "./checkpoints/checkpoint-500"
+    epochs: 10
+}
+```
+
+**Benefits:**
+- ✅ Automatic versioning by run name
+- ✅ Step-based checkpointing
+- ✅ Easy resume from any checkpoint
+- ✅ Training logs and metrics per run
+
+**Best practice:** Use descriptive project names in `PROJECT` block to organize runs.
+
+---
+
+## 17. Can I use custom Python code with OktoScript?
+
+**Answer:**
+
+**Yes!** OktoScript supports custom Python code through the `HOOKS` block.
+
+**Available hooks:**
+```okt
+HOOKS {
+    before_train: "scripts/preprocess.py"
+    after_train: "scripts/postprocess.py"
+    before_epoch: "scripts/custom_early_stop.py"
+    after_epoch: "scripts/log_custom_metrics.py"
+    on_checkpoint: "scripts/backup_checkpoint.sh"
+    custom_metric: "scripts/toxicity_calculator.py"
+}
+```
+
+**Hook script interface:**
+```python
+# scripts/preprocess.py
+def before_train(config, dataset, model):
+    # Custom preprocessing
+    # Modify config if needed
+    return config
+
+# scripts/after_epoch.py
+def after_epoch(epoch, metrics, model_state):
+    # Custom logging, early stopping logic
+    # Return True to stop training
+    return False
+```
+
+**Use cases:**
+- Custom data preprocessing
+- Custom metrics calculation
+- Custom early stopping logic
+- External API integration
+- Custom logging
+
+**Key point:** OktoScript handles the configuration, Python handles the custom logic. Best of both worlds.
+
+---
+
+## 18. What happens if I specify conflicting configurations?
+
+**Answer:**
+
+OktoScript has **clear priority rules** to handle conflicts:
+
+**Priority order (highest to lowest):**
+1. Block-specific overrides (e.g., `mix_datasets` in `FT_LORA`)
+2. Block-level settings (e.g., `FT_LORA` over `TRAIN` for LoRA)
+3. Global settings (e.g., `DATASET.train`)
+
+**Example conflicts and resolution:**
+
+**Conflict 1: Dataset specification**
+```okt
+DATASET {
+    train: "dataset/a.jsonl"  # Lower priority
+}
+
+FT_LORA {
+    mix_datasets: [...]  # Higher priority - overrides DATASET.train
+}
+```
+**Resolution:** `mix_datasets` is used, `DATASET.train` is ignored.
+
+**Conflict 2: TRAIN vs FT_LORA**
+```okt
+TRAIN {
+    epochs: 10
+}
+
+FT_LORA {
+    epochs: 5  # This is used for LoRA training
+}
+```
+**Resolution:** `FT_LORA.epochs` is used, but `TRAIN` optimizer/device settings still apply.
+
+**Validation:**
+- OktoEngine validates configurations before training
+- Conflicts are reported with clear error messages
+- Use `okto validate` to check before training
+
+---
+
+## 19. How do I debug an OktoScript file?
+
+**Answer:**
+
+**Step 1: Validate syntax**
+```bash
+okto validate train.okt
+```
+
+**Step 2: Check logs**
+```okt
+LOGGING {
+    save_logs: true
+    log_level: "debug"  # Enable debug logging
+    log_every: 1
+}
+```
+
+**Step 3: Use MONITOR for system diagnostics**
+```okt
+MONITOR {
+    level: "full"
+    log_system: ["gpu_memory_used", "cpu_usage", "temperature"]
+    dashboard: true  # Real-time visualization
+}
+```
+
+**Step 4: Check validation errors**
+Common errors and solutions:
+- `Dataset file not found` → Check file paths
+- `Invalid optimizer` → Use allowed values (adam, adamw, sgd, etc.)
+- `Model base not found` → Verify model path or HuggingFace name
+- `Dataset mixing weights invalid` → Total must equal 100
+
+**Step 5: Use system diagnostics**
+```bash
+okto_doctor  # Shows GPU, CUDA, RAM, drivers
+```
+
+**Best practices:**
+- Always validate before training
+- Start with `log_level: "debug"`
+- Use `MONITOR` dashboard for real-time insights
+- Check `runs/*/training_logs.json` for detailed logs
+
+---
+
+## 20. Is OktoScript production-ready?
+
+**Answer:**
+
+**Yes, OktoScript v1.1 is production-ready** for AI training and deployment pipelines.
+
+**Production features:**
+- ✅ **Stable grammar** - Well-defined and validated
+- ✅ **Error handling** - Comprehensive validation
+- ✅ **Monitoring** - System and training telemetry
+- ✅ **Export formats** - Production-ready formats (ONNX, GGUF, OKM)
+- ✅ **Deployment** - API, mobile, edge targets
+- ✅ **Security** - Model encryption and watermarking
+- ✅ **Logging** - Comprehensive logging and metrics
+
+**Production checklist:**
+```okt
+PROJECT "ProductionModel"
+VERSION "1.0"
+
+# ... configuration ...
+
+SECURITY {
+    encrypt_model: true
+    watermark: true
+}
+
+MONITOR {
+    level: "full"
+    dashboard: true
+}
+
+EXPORT {
+    format: ["onnx", "okm"]  # Production formats
+    optimize_for: "speed"
+}
+
+DEPLOY {
+    target: "api"
+    requires_auth: true
+    max_concurrent_requests: 100
+}
+```
+
+**Used by:**
+- OktoSeek IDE (production)
+- Research institutions
+- AI development teams
+- Educational platforms
+
+**Version stability:**
+- v1.0: Stable, production-ready
+- v1.1: Backward compatible, adds LoRA and monitoring
+
+---
+
+## Need More Help?
+
+- 📖 [Complete Grammar Specification](./grammar.md)
+- 🚀 [Getting Started Guide](./GETTING_STARTED.md)
+- ✅ [Validation Rules](../VALIDATION_RULES.md)
+- 💡 [Examples](../examples/)
+- 🐛 [Troubleshooting](./grammar.md#troubleshooting)
+
+**Still have questions?** Open an issue on [GitHub](https://github.com/oktoseek/oktoscript/issues) or contact **service@oktoseek.com**.
+
+---
+
+**OktoScript** is developed and maintained by **OktoSeek AI**.
+
+
+

docs/GETTING_STARTED.md

@@ -0,0 +1,199 @@
+# Getting Started with OktoScript
+
+**Your first 5 minutes with OktoScript** - A quick guide to get you up and running.
+
+---
+
+## Prerequisites
+
+- OktoSeek IDE installed (or OktoEngine CLI)
+- Basic understanding of AI/ML concepts
+- A dataset ready for training
+
+---
+
+## Step 1: Create Your First Project
+
+Create a new directory for your project:
+
+```bash
+mkdir my-first-model
+cd my-first-model
+```
+
+Create a file named `train.okt`:
+
+```okt
+PROJECT "MyFirstModel"
+DESCRIPTION "My first OktoScript project"
+
+DATASET {
+    train: "dataset/train.jsonl"
+    format: "jsonl"
+    type: "chat"
+}
+
+MODEL {
+    base: "oktoseek/base-mini"
+}
+
+TRAIN {
+    epochs: 3
+    batch_size: 16
+    device: "cpu"
+}
+
+EXPORT {
+    format: ["okm"]
+    path: "export/"
+}
+```
+
+---
+
+## Step 2: Prepare Your Dataset
+
+Create a `dataset/` folder and add your training data:
+
+**dataset/train.jsonl:**
+```json
+{"input":"Hello","output":"Hi! How can I help you?"}
+{"input":"What's the weather?","output":"I don't have access to weather data."}
+{"input":"Thank you","output":"You're welcome!"}
+```
+
+**Minimum requirements:**
+- At least 10 examples for basic training
+- Consistent format (JSONL recommended)
+- Valid JSON on each line
+
+---
+
+## Step 3: Validate Your Configuration
+
+Before training, validate your OktoScript file:
+
+```bash
+okto validate train.okt
+```
+
+This checks:
+- ✅ Syntax is correct
+- ✅ All required fields are present
+- ✅ Dataset files exist
+- ✅ Model paths are valid
+- ✅ Values are within allowed ranges
+
+---
+
+## Step 4: Train Your Model
+
+Run the training:
+
+```bash
+okto run train.okt
+```
+
+Or use the IDE:
+1. Open `train.okt` in OktoSeek IDE
+2. Click "Train" button
+3. Monitor progress in real-time
+
+**What happens:**
+1. Dataset is loaded and validated
+2. Model is initialized
+3. Training starts (you'll see progress)
+4. Model is saved to `runs/MyFirstModel/`
+5. Exported models saved to `export/`
+
+---
+
+## Step 5: Test Your Model
+
+After training, test with inference:
+
+```bash
+okto_infer --model ./runs/MyFirstModel --text "Hello"
+```
+
+Or add to your `.okt` file:
+
+```okt
+INFER {
+    input: "Hello, how are you?"
+    max_tokens: 50
+}
+```
+
+---
+
+## Common First Steps
+
+### Adding Validation Data
+
+```okt
+DATASET {
+    train: "dataset/train.jsonl"
+    validation: "dataset/val.jsonl"  # Add this
+    format: "jsonl"
+}
+```
+
+### Using GPU
+
+```okt
+TRAIN {
+    epochs: 5
+    batch_size: 32
+    device: "cuda"  # Change from "cpu"
+    gpu: true
+}
+```
+
+### Adding Metrics
+
+```okt
+METRICS {
+    accuracy
+    loss
+    perplexity
+}
+```
+
+### Exporting to Multiple Formats
+
+```okt
+EXPORT {
+    format: ["gguf", "onnx", "okm"]
+    path: "export/"
+}
+```
+
+---
+
+## Next Steps
+
+- 📚 Read the [Complete Grammar Specification](./grammar.md)
+- 🎯 Check out [Complex Examples](../examples/)
+- 🔧 Learn about [Troubleshooting](./grammar.md#troubleshooting)
+- 💡 Explore [Extension Points](./grammar.md#extension-points--hooks)
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Validate | `okto validate train.okt` |
+| Train | `okto run train.okt` |
+| Infer | `okto_infer --model ./runs/model --text "input"` |
+| Evaluate | `okto_eval --model ./runs/model --dataset ./dataset/test.jsonl` |
+| Export | `okto export --format gguf` |
+| Deploy | `okto_deploy --model model --target api` |
+
+---
+
+**Need help?** Check the [Troubleshooting Guide](./grammar.md#troubleshooting) or open an issue on [GitHub](https://github.com/oktoseek/oktoscript).
+
+
+

docs/grammar.md

@@ -0,0 +1,2571 @@
+# OktoScript Grammar Specification v1.2
+
+Complete formal grammar for the OktoScript language, developed by **OktoSeek AI**.
+
+> **Version Compatibility:** This specification covers OktoScript v1.2, which is 100% backward compatible with v1.0 and v1.1. Files without version declaration default to v1.0.
+
+---
+
+## Table of Contents
+
+1. [Grammar Overview](#grammar-overview)
+2. [Basic Metadata Blocks](#basic-metadata-blocks)
+3. [ENV Block](#env-block)
+4. [DATASET Block](#dataset-block)
+5. [MODEL Block](#model-block)
+6. [TRAIN Block](#train-block)
+7. [METRICS Block](#metrics-block)
+8. [VALIDATION Block](#validation-block)
+9. [INFERENCE Block](#inference-block)
+10. [CONTROL Block — Decision Engine](#control-block--decision-engine)
+11. [MONITOR Block — Full Metrics Support](#monitor-block--full-metrics-support)
+12. [GUARD Block — Safety / Ethics / Protection](#guard-block--safety--ethics--protection)
+13. [BEHAVIOR Block — Model Personality](#behavior-block--model-personality)
+14. [EXPLORER Block — Parameter Search](#explorer-block--parameter-search)
+15. [STABILITY Block — Training Safety](#stability-block--training-safety)
+16. [Boolean Support](#boolean-support)
+17. [EXPORT Block](#export-block)
+18. [DEPLOY Block](#deploy-block)
+19. [SECURITY Block](#security-block)
+20. [LOGGING Block](#logging-block)
+21. [Model Inheritance](#model-inheritance)
+22. [Extension Points & Hooks](#extension-points--hooks)
+23. [Validation Rules](#validation-rules)
+24. [Troubleshooting](#troubleshooting)
+25. [Terminal / Basic Types](#terminal--basic-types)
+26. [Full Script Example](#full-script-example)
+
+---
+
+## Grammar Overview
+
+```ebnf
+<oktoscript> ::=
+  [<version_declaration>]
+  <project_block>
+  [<description_block>]
+  [<version_block>]
+  [<tags_block>]
+  [<author_block>]
+  [<env_block>]
+  <dataset_block>
+  <model_block>
+  [<train_block> | <ft_lora_block>]
+  [<metrics_block>]
+  [<validation_block>]
+  [<inference_block>]
+  [<export_block>]
+  [<deploy_block>]
+  [<security_block>]
+  [<logging_block>]
+  [<monitor_block>]
+  [<control_block>]
+  [<guard_block>]
+  [<behavior_block>]
+  [<explorer_block>]
+  [<stability_block>]
+  [<hooks_block>]
+```
+
+**Note:** `TRAIN` and `FT_LORA` are mutually exclusive. Use `FT_LORA` for LoRA-based fine-tuning, or `TRAIN` for full fine-tuning.
+
+**Required blocks:** PROJECT, DATASET, MODEL, TRAIN  
+**Optional blocks:** ENV, DESCRIPTION, VERSION, TAGS, AUTHOR, and all others
+
+---
+
+## Version Declaration (v1.1+)
+
+```ebnf
+<version_declaration> ::=
+  "# okto_version:" <string>
+```
+
+**Example:**
+```okt
+# okto_version: "1.2"
+PROJECT "MyModel"
+...
+```
+
+**Rules:**
+- Optional at the top of the file
+- If missing, defaults to v1.0
+- Must be the first line (comments allowed before)
+- Format: `# okto_version: "1.2"`, `# okto_version: "1.1"`, or `# okto_version: "1.0"`
+
+---
+
+## Basic Metadata Blocks
+
+### PROJECT Block
+
+```ebnf
+<project_block> ::= 
+  "PROJECT" <string>
+```
+
+**Constraints:**
+- Project name must be a valid string (1-100 characters)
+- Cannot contain special characters: `{`, `}`, `[`, `]`, `:`, `"`
+
+**Example:**
+```okt
+PROJECT "PizzaBot"
+```
+
+### DESCRIPTION Block
+
+```ebnf
+<description_block> ::= 
+  "DESCRIPTION" <string>
+```
+
+**Constraints:**
+- Maximum 500 characters
+- Can contain any UTF-8 characters
+
+**Example:**
+```okt
+DESCRIPTION "AI specialized in pizza restaurant service"
+```
+
+### VERSION Block
+
+```ebnf
+<version_block> ::= 
+  "VERSION" <string>
+```
+
+**Constraints:**
+- Must follow semantic versioning (e.g., "1.0.0", "2.1.3")
+- Format: `major.minor.patch` or `major.minor`
+
+**Example:**
+```okt
+VERSION "1.0"
+VERSION "2.1.3"
+```
+
+### TAGS Block
+
+```ebnf
+<tags_block> ::= 
+  "TAGS" "[" <string_list> "]"
+```
+
+**Constraints:**
+- Maximum 10 tags
+- Each tag: 1-50 characters
+- Tags are case-insensitive
+
+**Example:**
+```okt
+TAGS ["food", "restaurant", "chatbot"]
+```
+
+### AUTHOR Block
+
+```ebnf
+<author_block> ::= 
+  "AUTHOR" <string>
+```
+
+**Example:**
+```okt
+AUTHOR "OktoSeek"
+```
+
+---
+
+## ENV Block
+
+The `ENV` block defines environment requirements, hardware expectations, and execution preferences for OktoEngine. It is fully abstract and does not expose underlying implementation details (Python, PyTorch, TensorFlow, etc.). OktoEngine uses this block to configure the execution environment before running any training or inference operations.
+
+**Purpose:**
+- Define minimum environment requirements for a project
+- Specify hardware preferences (CPU, GPU, TPU)
+- Set memory and precision requirements
+- Configure execution backend preferences
+- Enable automatic dependency installation
+- Specify platform and network requirements
+
+**Note:** ENV is not a dependency list. It is a high-level execution requirement description that allows OktoEngine to decide how to configure the real execution environment.
+
+### ENV Block Syntax
+
+```ebnf
+<env_block> ::=
+  "ENV" "{"
+      [<env_accelerator>]
+      [<env_min_memory>]
+      [<env_precision>]
+      [<env_backend>]
+      [<env_install_missing>]
+      [<env_platform>]
+      [<env_network>]
+  "}"
+
+<env_accelerator> ::=
+  "accelerator" ":" ("auto" | "cpu" | "gpu" | "tpu")
+
+<env_min_memory> ::=
+  "min_memory" ":" <memory_string>
+
+<memory_string> ::=
+  "4GB" | "8GB" | "16GB" | "32GB" | "64GB"
+
+<env_precision> ::=
+  "precision" ":" ("auto" | "fp16" | "fp32" | "bf16")
+
+<env_backend> ::=
+  "backend" ":" ("auto" | "oktoseek")
+
+<env_install_missing> ::=
+  "install_missing" ":" ("true" | "false")
+
+<env_platform> ::=
+  "platform" ":" ("windows" | "linux" | "mac" | "any")
+
+<env_network> ::=
+  "network" ":" ("online" | "offline" | "required")
+```
+
+### ENV Block Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `accelerator` | enum | ❌ No | `"auto"` | Preferred compute unit: `"auto"`, `"cpu"`, `"gpu"`, `"tpu"` |
+| `min_memory` | string | ❌ No | `"8GB"` | Required minimum RAM: `"4GB"`, `"8GB"`, `"16GB"`, `"32GB"`, `"64GB"` |
+| `precision` | enum | ❌ No | `"auto"` | Numerical precision: `"auto"`, `"fp16"`, `"fp32"`, `"bf16"` |
+| `backend` | enum | ❌ No | `"auto"` | Execution engine: `"auto"`, `"oktoseek"` |
+| `install_missing` | boolean | ❌ No | `false` | If `true`, engine attempts automatic dependency installation |
+| `platform` | enum | ❌ No | `"any"` | Target OS: `"windows"`, `"linux"`, `"mac"`, `"any"` |
+| `network` | enum | ❌ No | `"online"` | Internet requirement: `"online"`, `"offline"`, `"required"` |
+
+### ENV Block Examples
+
+**Minimal ENV (uses defaults):**
+```okt
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+}
+```
+
+**Complete ENV configuration:**
+```okt
+ENV {
+  accelerator: "gpu"
+  min_memory: "16GB"
+  precision: "fp16"
+  backend: "oktoseek"
+  install_missing: true
+  platform: "any"
+  network: "online"
+}
+```
+
+**CPU-only training:**
+```okt
+ENV {
+  accelerator: "cpu"
+  min_memory: "8GB"
+  precision: "fp32"
+  install_missing: true
+}
+```
+
+**Offline execution:**
+```okt
+ENV {
+  accelerator: "gpu"
+  min_memory: "16GB"
+  network: "offline"
+  install_missing: false
+}
+```
+
+### ENV Block Constraints
+
+1. **Memory format:** Must use `GB` suffix (e.g., `"8GB"`, not `"8"` or `"8 GB"`)
+2. **Enum values:** Only predefined values are allowed
+3. **Boolean values:** Must be `true` or `false` (lowercase)
+4. **String values:** Must be quoted
+
+### ENV Block Validation Rules
+
+1. If `accelerator = "gpu"` and `min_memory < "8GB"` → **warning** (GPU training typically requires at least 8GB)
+2. If `network = "offline"` → export formats like `onnx` or `gguf` are allowed (pre-downloaded models)
+3. If `backend = "oktoseek"` → preferred default for OktoSeek ecosystem
+4. If `install_missing = true` → engine must attempt auto-setup of missing dependencies
+5. If no ENV block exists → defaults to:
+   ```okt
+   ENV {
+     accelerator: "auto"
+     min_memory: "8GB"
+     backend: "auto"
+   }
+   ```
+
+### Engine Behavior
+
+When OktoEngine encounters an ENV block, it must:
+
+1. **Read ENV block first:** Before any other stage (dataset loading, model initialization, etc.)
+2. **Check system compatibility:** Verify RAM, GPU availability, platform, etc.
+3. **Return detailed errors:** If system is incompatible, return specific error messages
+4. **Auto-install dependencies:** If `install_missing: true`, attempt automatic setup
+5. **Generate environment report:** Log analysis to `runs/{model}/env_report.json`
+
+**Example env_report.json:**
+```json
+{
+  "gpu_found": true,
+  "gpu_name": "NVIDIA RTX 3090",
+  "ram": "32GB",
+  "ram_available": "28GB",
+  "platform": "linux",
+  "status": "compatible",
+  "auto_install": true,
+  "warnings": []
+}
+```
+
+---
+
+## DATASET Block
+
+```ebnf
+<dataset_block> ::= 
+  "DATASET" "{" 
+      [<dataset_train> | <mix_datasets>]
+      [<dataset_validation>]
+      [<dataset_test>]
+      [<dataset_format>]
+      [<dataset_type>]
+      [<dataset_language>]
+      [<dataset_augmentation>]
+      [<dataset_percent>]
+      [<dataset_sampling>]
+      [<dataset_shuffle>]
+  "}"
+
+<dataset_train> ::=
+  "train" ":" <path>
+
+<dataset_validation> ::=
+  "validation" ":" <path>
+
+<dataset_test> ::=
+  "test" ":" <path>
+
+<dataset_format> ::= 
+  "format" ":" ("jsonl" | "csv" | "txt" | "parquet" | "image+caption" | "qa" | "instruction" | "multimodal")
+
+<dataset_type> ::=
+  "type" ":" ("classification" | "generation" | "qa" | "chat" | "vision" | "regression")
+
+<dataset_language> ::=
+  "language" ":" ("en" | "pt" | "es" | "fr" | "multilingual")
+
+<dataset_augmentation> ::=
+  "augmentation" ":" "[" <string_list> "]"
+
+<dataset_percent> ::=
+  "dataset_percent" ":" <number>
+
+<mix_datasets> ::=
+  "mix_datasets" ":" "[" <mix_dataset_list> "]"
+
+<mix_dataset_list> ::=
+  <mix_dataset_item> { "," <mix_dataset_item> }
+
+<mix_dataset_item> ::=
+  "{" "path" ":" <path> "," "weight" ":" <number> "}"
+
+<dataset_sampling> ::=
+  "sampling" ":" ("weighted" | "random")
+
+<dataset_shuffle> ::=
+  "shuffle" ":" ("true" | "false")
+```
+
+**Allowed augmentation values:**
+- `"flip"` - Horizontal/vertical flip
+- `"rotate"` - Random rotation
+- `"brightness"` - Brightness adjustment
+- `"contrast"` - Contrast adjustment
+- `"noise"` - Add noise
+- `"crop"` - Random cropping
+- `"translate"` - Translation
+
+**Validation Rules:**
+- `train` path must exist and be readable
+- File format must match declared `format`
+- For `image+caption`, path must be a directory
+- For JSONL/CSV, path must be a file
+
+**Example (v1.0):**
+```okt
+DATASET {
+    train: "dataset/train.jsonl"
+    validation: "dataset/val.jsonl"
+    test: "dataset/test.jsonl"
+    format: "jsonl"
+    type: "chat"
+    language: "en"
+    augmentation: ["flip", "rotate", "brightness"]
+}
+```
+
+**Example (v1.1 - Dataset Mixing):**
+```okt
+DATASET {
+    mix_datasets: [
+        { path: "dataset/base.jsonl", weight: 70 },
+        { path: "dataset/extra.jsonl", weight: 30 }
+    ]
+    dataset_percent: 50
+    sampling: "weighted"
+    shuffle: true
+    format: "jsonl"
+    type: "chat"
+}
+```
+
+**Dataset Mixing Rules:**
+- If `mix_datasets` is specified, it overrides `train`
+- Total weights in `mix_datasets` must equal 100
+- `dataset_percent` limits total dataset usage (1-100)
+- `sampling: "weighted"` uses weights for sampling, `"random"` ignores weights
+- `shuffle` controls whether datasets are shuffled before mixing
+
+---
+
+## MODEL Block
+
+```ebnf
+<model_block> ::= 
+  "MODEL" "{"
+      [<model_name>]
+      <model_base>
+      [<model_architecture>]
+      [<model_parameters>]
+      [<model_context_window>]
+      [<model_precision>]
+      [<model_inherit>]
+      [<model_device>]
+      [<adapter_block>]
+  "}"
+
+<model_name> ::=
+  "name" ":" <string>
+
+<model_base> ::=
+  "base" ":" <string>
+
+<model_architecture> ::=
+  "architecture" ":" ("transformer" | "cnn" | "rnn" | "diffusion" | "vision-transformer" | "bert" | "gpt" | "t5")
+
+<model_parameters> ::=
+  "parameters" ":" <number> ("M" | "B" | "K")
+
+<model_context_window> ::=
+  "context_window" ":" <number>
+
+<model_precision> ::=
+  "precision" ":" ("fp32" | "fp16" | "int8" | "int4")
+
+<model_inherit> ::=
+  "inherit" ":" <string>
+
+<model_device> ::=
+  "device" ":" ("cuda" | "cpu" | "mps" | "auto")
+
+<adapter_block> ::=
+  "ADAPTER" "{"
+      <adapter_type>
+      <adapter_path>
+      [<adapter_rank>]
+      [<adapter_alpha>]
+  "}"
+
+<adapter_type> ::=
+  "type" ":" ("lora" | "qlora" | "adapter" | "peft")
+
+<adapter_path> ::=
+  "path" ":" <path>
+
+<adapter_rank> ::=
+  "rank" ":" <number>
+
+<adapter_alpha> ::=
+  "alpha" ":" <number>
+```
+
+**Model Inheritance:**
+- `inherit` allows reusing configuration from another model
+- Inherited model must be defined in the same project or imported
+- Child model can override any parent field
+- Example: `inherit: "base-transformer"` loads base config, then applies current block
+
+**Allowed base model formats:**
+- HuggingFace format: `"username/model-name"`
+- OktoSeek format: `"oktoseek/model-name"`
+- Local path: `"./models/my-model"`
+- URL: `"https://example.com/model"`
+
+**Parameter constraints:**
+- `parameters`: Must be positive number with suffix (K, M, B)
+- `context_window`: Must be power of 2 (128, 256, 512, 1024, 2048, 4096, 8192)
+- `precision`: Must match device capabilities
+
+**Example:**
+```okt
+MODEL {
+    name: "oktogpt"
+    base: "oktoseek/pizza-small"
+    architecture: "transformer"
+    parameters: 120M
+    context_window: 2048
+    precision: "fp16"
+    device: "cuda"
+}
+```
+
+**Example with ADAPTER (LoRA/PEFT support):**
+```okt
+MODEL {
+    name: "oktogpt"
+    base: "google/flan-t5-base"
+    device: "cuda"
+    
+    ADAPTER {
+        type: "lora"
+        path: "D:/model_trainee/phase1_sharegpt/ep2"
+        rank: 16
+        alpha: 32
+    }
+}
+```
+
+**Example with inheritance:**
+```okt
+# Base model definition
+MODEL "base-transformer" {
+    architecture: "transformer"
+    context_window: 2048
+    precision: "fp16"
+}
+
+# Child model inheriting from base
+MODEL {
+    inherit: "base-transformer"
+    base: "oktoseek/custom-model"
+    parameters: 250M
+}
+```
+
+**ADAPTER Block:**
+The `ADAPTER` sub-block enables parameter-efficient fine-tuning methods such as LoRA, QLoRA, PEFT, or other adapters. If an `ADAPTER` is defined, it is applied after the base model is loaded by the engine.
+
+**Adapter constraints:**
+- `type`: Must be one of `"lora"`, `"qlora"`, `"adapter"`, or `"peft"`
+- `path`: Must point to a valid adapter directory or file
+- `rank`: Optional, typically 4, 8, 16, 32, or 64 (for LoRA)
+- `alpha`: Optional, typically 16, 32, or 64 (for LoRA scaling)
+
+---
+
+## FT_LORA Block (v1.1+)
+
+Fine-tuning using LoRA (Low-Rank Adaptation) adapters. This block is an alternative to `TRAIN` for efficient fine-tuning.
+
+```ebnf
+<ft_lora_block> ::=
+  "FT_LORA" "{"
+      <ft_lora_base_model>
+      <ft_lora_train_dataset>
+      <ft_lora_rank>
+      <ft_lora_alpha>
+      [<ft_lora_dataset_percent>]
+      [<ft_lora_mix_datasets>]
+      [<ft_lora_epochs>]
+      [<ft_lora_batch_size>]
+      [<ft_lora_learning_rate>]
+      [<ft_lora_device>]
+      [<ft_lora_target_modules>]
+  "}"
+
+<ft_lora_base_model> ::=
+  "base_model" ":" <string>
+
+<ft_lora_train_dataset> ::=
+  "train_dataset" ":" <path>
+
+<ft_lora_rank> ::=
+  "lora_rank" ":" <number>
+
+<ft_lora_alpha> ::=
+  "lora_alpha" ":" <number>
+
+<ft_lora_dataset_percent> ::=
+  "dataset_percent" ":" <number>
+
+<ft_lora_mix_datasets> ::=
+  "mix_datasets" ":" "[" <mix_dataset_list> "]"
+
+<ft_lora_epochs> ::=
+  "epochs" ":" <number>
+
+<ft_lora_batch_size> ::=
+  "batch_size" ":" <number>
+
+<ft_lora_learning_rate> ::=
+  "learning_rate" ":" <decimal>
+
+<ft_lora_device> ::=
+  "device" ":" ("cpu" | "cuda" | "mps" | "auto")
+
+<ft_lora_target_modules> ::=
+  "target_modules" ":" "[" <string_list> "]"
+```
+
+**Constraints:**
+- `lora_rank`: Must be > 0 and <= 256 (typical: 4, 8, 16, 32)
+- `lora_alpha`: Must be > 0 (typical: 16, 32, 64)
+- `dataset_percent`: Must be 1-100
+- If `mix_datasets` is specified, it overrides `train_dataset`
+- Total weights in `mix_datasets` must equal 100
+
+**Example:**
+```okt
+FT_LORA {
+    base_model: "oktoseek/base-mini"
+    train_dataset: "dataset/main.jsonl"
+    lora_rank: 4
+    lora_alpha: 16
+    dataset_percent: 50
+    mix_datasets: [
+        { path: "dataset/base.jsonl", weight: 70 },
+        { path: "dataset/extra.jsonl", weight: 30 }
+    ]
+    epochs: 3
+    batch_size: 16
+    learning_rate: 0.00003
+    device: "cuda"
+    target_modules: ["q_proj", "v_proj"]
+}
+```
+
+**When to use FT_LORA vs TRAIN:**
+- **FT_LORA**: Efficient fine-tuning, smaller memory footprint, faster training, good for domain adaptation
+- **TRAIN**: Full fine-tuning, maximum flexibility, better for large architectural changes
+
+---
+
+## TRAIN Block
+
+```ebnf
+<train_block> ::=
+  "TRAIN" "{"
+      <train_epochs>
+      <train_batch>
+      [<train_lr>]
+      [<train_optimizer>]
+      [<train_scheduler>]
+      <train_device>
+      [<gradient_accumulation>]
+      [<early_stopping>]
+      [<checkpoint_steps>]
+      [<checkpoint_path>]
+      [<resume_from_checkpoint>]
+      [<loss_function>]
+      [<weight_decay>]
+      [<gradient_clip>]
+      [<warmup_steps>]
+      [<save_strategy>]
+  "}"
+
+<train_epochs> ::= 
+  "epochs" ":" <number>
+
+<train_batch> ::= 
+  "batch_size" ":" <number>
+
+<train_lr> ::= 
+  "learning_rate" ":" <decimal>
+
+<train_optimizer> ::= 
+  "optimizer" ":" ( "adam" | "adamw" | "sgd" | "rmsprop" | "adafactor" | "lamb" )
+
+<train_scheduler> ::= 
+  "scheduler" ":" ("linear" | "cosine" | "cosine_with_restarts" | "polynomial" | "constant" | "constant_with_warmup" | "step")
+
+<train_device> ::= 
+  "device" ":" ("cpu" | "cuda" | "mps" | "auto")
+
+<gradient_accumulation> ::= 
+  "gradient_accumulation" ":" <number>
+
+<early_stopping> ::= 
+  "early_stopping" ":" ("true" | "false")
+
+<checkpoint_steps> ::= 
+  "checkpoint_steps" ":" <number>
+
+<checkpoint_path> ::=
+  "checkpoint_path" ":" <path>
+
+<resume_from_checkpoint> ::=
+  "resume_from_checkpoint" ":" <path>
+
+<loss_function> ::=
+  "loss" ":" ("cross_entropy" | "mse" | "mae" | "bce" | "focal" | "huber" | "kl_divergence")
+
+<weight_decay> ::=
+  "weight_decay" ":" <decimal>
+
+<gradient_clip> ::=
+  "gradient_clip" ":" <decimal>
+
+<warmup_steps> ::=
+  "warmup_steps" ":" <number>
+
+<save_strategy> ::=
+  "save_strategy" ":" ("steps" | "epoch" | "no")
+```
+
+**Allowed values and constraints:**
+
+**Optimizers:**
+- `adam` - Adam optimizer (default)
+- `adamw` - Adam with weight decay
+- `sgd` - Stochastic Gradient Descent
+- `rmsprop` - RMSprop optimizer
+- `adafactor` - Adafactor (memory efficient)
+- `lamb` - LAMB optimizer (for large batches)
+
+**Schedulers:**
+- `linear` - Linear decay
+- `cosine` - Cosine annealing
+- `cosine_with_restarts` - Cosine with restarts
+- `polynomial` - Polynomial decay
+- `constant` - Constant learning rate
+- `constant_with_warmup` - Constant with warmup
+- `step` - Step decay
+
+**Loss functions:**
+- `cross_entropy` - Cross-entropy loss (classification)
+- `mse` - Mean Squared Error (regression)
+- `mae` - Mean Absolute Error (regression)
+- `bce` - Binary Cross-Entropy
+- `focal` - Focal loss (imbalanced data)
+- `huber` - Huber loss (robust regression)
+- `kl_divergence` - KL divergence
+
+**Constraints:**
+- `epochs`: Must be > 0 and <= 1000
+- `batch_size`: Must be > 0 and <= 1024
+- `learning_rate`: Must be > 0 and <= 1.0
+- `gradient_accumulation`: Must be >= 1
+- `checkpoint_steps`: Must be > 0
+- `weight_decay`: Must be >= 0 and <= 1.0
+- `gradient_clip`: Must be > 0
+
+**Example:**
+```okt
+TRAIN {
+    epochs: 10
+    batch_size: 32
+    learning_rate: 0.00025
+    optimizer: "adamw"
+    scheduler: "cosine"
+    loss: "cross_entropy"
+    device: "cuda"
+    gradient_accumulation: 2
+    early_stopping: true
+    checkpoint_steps: 100
+    checkpoint_path: "./checkpoints"
+    weight_decay: 0.01
+    gradient_clip: 1.0
+    warmup_steps: 500
+    save_strategy: "steps"
+}
+```
+
+**Example with checkpoint resume:**
+```okt
+TRAIN {
+    epochs: 20
+    batch_size: 16
+    learning_rate: 0.0001
+    optimizer: "adamw"
+    device: "cuda"
+    resume_from_checkpoint: "./checkpoints/checkpoint-500"
+    checkpoint_steps: 100
+}
+```
+
+---
+
+## METRICS Block
+
+```ebnf
+<metrics_block> ::= 
+  "METRICS" "{"
+      { <metric> | <custom_metric> }
+  "}"
+
+<metric> ::= 
+  "accuracy" |
+  "loss" |
+  "perplexity" |
+  "f1" |
+  "f1_macro" |
+  "f1_micro" |
+  "f1_weighted" |
+  "bleu" |
+  "rouge" |
+  "rouge_l" |
+  "rouge_1" |
+  "rouge_2" |
+  "mae" |
+  "mse" |
+  "rmse" |
+  "cosine_similarity" |
+  "token_efficiency" |
+  "response_coherence" |
+  "hallucination_score" |
+  "precision" |
+  "recall" |
+  "confusion_matrix"
+
+<custom_metric> ::= 
+  "custom" <string>
+```
+
+**Metric-specific constraints:**
+- `accuracy`: Only for classification tasks
+- `perplexity`: Only for language models
+- `bleu`, `rouge`: Only for generation/translation tasks
+- `mae`, `mse`, `rmse`: Only for regression tasks
+- `confusion_matrix`: Only for classification, generates full matrix
+
+**Example:**
+```okt
+METRICS {
+    accuracy
+    loss
+    perplexity
+    f1
+    f1_macro
+    rouge_l
+    cosine_similarity
+    custom "toxicity_score"
+    custom "context_alignment"
+}
+```
+
+---
+
+## VALIDATION Block
+
+```ebnf
+<validation_block> ::=
+  "VALIDATE" "{"
+      [ "on_train" ":" ("true" | "false") ]
+      [ "on_validation" ":" ("true" | "false") ]
+      [ "frequency" ":" <number> ]
+      [ "save_best_model" ":" ("true" | "false") ]
+      [ "metric_to_monitor" ":" <string> ]
+  "}"
+```
+
+**Constraints:**
+- `frequency`: Must be > 0 (validation every N steps)
+- `metric_to_monitor`: Must be a metric defined in METRICS block
+- `save_best_model`: If true, saves model when monitored metric improves
+
+**Example:**
+```okt
+VALIDATE {
+    on_train: false
+    on_validation: true
+    frequency: 1
+    save_best_model: true
+    metric_to_monitor: "loss"
+}
+```
+
+---
+
+## INFERENCE Block
+
+The `INFERENCE` block defines how the model behaves during inference, prediction, or interactive chat.
+
+```ebnf
+<inference_block> ::= 
+  "INFERENCE" "{"
+      <inference_mode>
+      [<inference_format>]
+      [<inference_exit_command>]
+      [<inference_params>]
+      [<inference_control>]
+  "}"
+
+<inference_mode> ::=
+  "mode" ":" ("chat" | "intent" | "translate" | "classify" | "custom")
+
+<inference_format> ::=
+  "format" ":" <string>
+
+<inference_exit_command> ::=
+  "exit_command" ":" <string>
+
+<inference_params> ::=
+  "params" "{"
+      [<inference_max_length>]
+      [<inference_temperature>]
+      [<inference_top_p>]
+      [<inference_beams>]
+      [<inference_do_sample>]
+      [<inference_top_k>]
+      [<inference_repetition_penalty>]
+  "}"
+
+<inference_max_length> ::=
+  "max_length" ":" <number>
+
+<inference_temperature> ::=
+  "temperature" ":" <decimal>
+
+<inference_top_p> ::=
+  "top_p" ":" <decimal>
+
+<inference_beams> ::=
+  "beams" ":" <number>
+
+<inference_do_sample> ::=
+  "do_sample" ":" <boolean>
+
+<inference_top_k> ::=
+  "top_k" ":" <number>
+
+<inference_repetition_penalty> ::=
+  "repetition_penalty" ":" <decimal>
+
+<inference_control> ::=
+  "CONTROL" "{"
+      { <control_if> | <control_when> | <control_every> | <control_set> | <control_stop> | <control_log> | <control_save> | <control_retry> | <control_regenerate> }
+  "}"
+```
+
+**Supported format patterns:**
+
+The `format` field supports template strings with variables:
+
+| Use case | Example |
+|----------|---------|
+| Chat | `"User: {input}\nAssistant:"` |
+| Free | `"{input}"` |
+| Translation | `"translate English to Portuguese: {input}"` |
+| Intent | `"{input}"` |
+| QA/RAG | `"Context: {context}\nQuestion: {input}\nAnswer:"` |
+| LLaMA style | `"<|user|>\n{input}\n<|assistant|>\n"` |
+
+**Supported variables:**
+- `{input}` → user input
+- `{context}` → optional context (for RAG/QA)
+- `{labels}` → class list for classification
+
+**Constraints:**
+- `mode`: Defines the inference behavior type
+- `format`: Template string with variable placeholders
+- `max_length`: Must be > 0 and <= 8192
+- `temperature`: Must be >= 0.0 and <= 2.0
+- `top_p`: Must be > 0.0 and <= 1.0
+- `top_k`: Must be >= 0 (0 = disabled)
+- `beams`: Must be >= 1 (for beam search)
+- `do_sample`: Boolean (true/false)
+- `repetition_penalty`: Must be > 0.0 and <= 2.0
+
+**Example (Chat mode):**
+```okt
+INFERENCE {
+    mode: "chat"
+    format: "User: {input}\nAssistant:"
+    exit_command: "/exit"
+    
+    params {
+        max_length: 120
+        temperature: 0.7
+        top_p: 0.9
+        beams: 2
+        do_sample: true
+    }
+    
+    CONTROL {
+        IF confidence < 0.3 { RETRY }
+        IF repetition > 3 { REGENERATE }
+        IF hallucination_score > 0.5 { REPLACE WITH "Desculpe, não tenho certeza." }
+    }
+}
+```
+
+**Example (Translation mode):**
+```okt
+INFERENCE {
+    mode: "translate"
+    format: "translate English to Portuguese: {input}"
+    
+    params {
+        max_length: 200
+        temperature: 0.5
+        top_p: 0.95
+    }
+}
+```
+
+**Example (Classification mode):**
+```okt
+INFERENCE {
+    mode: "classify"
+    format: "{input}"
+    
+    params {
+        temperature: 0.1
+        top_k: 5
+    }
+}
+```
+
+---
+
+## CONTROL Block — Decision Engine
+
+The `CONTROL` block enables logical, conditional, event-based, and metric-based decisions during training and inference. It introduces a cognitive-level abstraction that allows AI models to take decisions, self-adjust, and self-regulate in a declarative and clean way.
+
+```ebnf
+<control_block> ::=
+  "CONTROL" "{"
+      { <control_event> | <control_if> | <control_when> | <control_every> | <control_set> | <control_stop> | <control_log> | <control_save> | <control_retry> | <control_regenerate> | <control_stop_training> | <control_decrease> | <control_increase> }
+  "}"
+
+<control_event> ::=
+  <on_step_end> | <on_epoch_end> | <on_memory_low> | <on_nan> | <on_plateau> | <validate_every>
+
+<on_step_end> ::=
+  "on_step_end" "{"
+      { <control_log> | <control_save> | <control_set> | <control_if> | <control_when> | <control_every> }
+  "}"
+
+<on_epoch_end> ::=
+  "on_epoch_end" "{"
+      { <control_log> | <control_save> | <control_set> | <control_stop_training> | <control_if> | <control_when> | <control_every> }
+  "}"
+
+<on_memory_low> ::=
+  "on_memory_low" "{"
+      { <control_set> | <control_stop> | <control_if> | <control_when> }
+  "}"
+
+<on_nan> ::=
+  "on_nan" "{"
+      { <control_stop_training> | <control_log> | <control_if> }
+  "}"
+
+<on_plateau> ::=
+  "on_plateau" "{"
+      { <control_decrease> | <control_increase> | <control_set> | <control_if> | <control_when> }
+  "}"
+
+<validate_every> ::=
+  "validate_every" ":" <number>
+
+<control_if> ::=
+  "IF" <condition> "{"
+      { <control_set> | <control_stop> | <control_log> | <control_save> | <control_stop_training> | <control_decrease> | <control_increase> | <control_retry> | <control_regenerate> | <control_if> | <control_when> | <control_every> }
+  "}"
+
+<control_when> ::=
+  "WHEN" <condition> "{"
+      { <control_set> | <control_stop> | <control_log> | <control_if> | <control_when> }
+  "}"
+
+<control_every> ::=
+  "EVERY" <number> ("steps" | "epochs") "{"
+      { <control_save> | <control_log> | <control_set> | <control_if> | <control_when> }
+  "}"
+
+<control_set> ::=
+  "SET" <identifier> "=" <value>
+
+<control_stop> ::=
+  "STOP"
+
+<control_log> ::=
+  "LOG" ( <metric_name> | <string> )
+
+<control_save> ::=
+  "SAVE" ( "model" | "checkpoint" | <string> )
+
+<control_retry> ::=
+  "RETRY"
+
+<control_regenerate> ::=
+  "REGENERATE"
+
+<control_stop_training> ::=
+  "STOP_TRAINING"
+
+<control_decrease> ::=
+  "DECREASE" <identifier> "BY" <number>
+
+<control_increase> ::=
+  "INCREASE" <identifier> "BY" <number>
+
+<condition> ::=
+  <metric_name> <comparison_operator> <value>
+
+<comparison_operator> ::=
+  ">" | "<" | ">=" | "<=" | "==" | "!="
+
+<value> ::=
+  <number> | <decimal> | <string> | <boolean> | <identifier>
+
+<metric_name> ::=
+  "loss" | "val_loss" | "accuracy" | "val_accuracy" | "gpu_memory" | "ram_usage" | "confidence" | "hallucination_score" | <custom_metric>
+
+<identifier> ::=
+  "LR" | "learning_rate" | "batch_size" | "temperature" | <custom_identifier>
+```
+
+**Supported events/hooks:**
+
+| Event | Description |
+|-------|-------------|
+| `on_step_end` | Executed at the end of each training step |
+| `on_epoch_end` | Executed at the end of each epoch |
+| `validate_every` | Execute validation every X steps |
+| `on_memory_low` | Triggered when GPU/RAM is low |
+| `on_nan` | Triggered when NaN values are detected |
+| `on_plateau` | Triggered when loss is stagnant (plateau) |
+
+**Supported directives:**
+
+- `IF` - Conditional logic based on metrics
+- `WHEN` - Event-based conditional logic
+- `EVERY` - Periodic actions (every N steps)
+- `SET` - Set parameter values dynamically
+- `STOP` - Stop current operation
+- `LOG` - Log metrics or messages
+- `SAVE` - Save model or checkpoint
+- `RETRY` - Retry inference generation
+- `REGENERATE` - Regenerate output
+- `STOP_TRAINING` - Stop training process
+- `DECREASE` - Decrease parameter value
+- `INCREASE` - Increase parameter value
+
+**Nested Blocks Support:**
+
+The CONTROL block in OktoScript supports nested logic, event-driven triggers, and conditional reasoning. You can nest IF / WHEN / EVERY statements inside lifecycle hooks like `on_step_end` and `on_epoch_end`, allowing dynamic, real-time decision making during training or inference.
+
+**Example (Basic):**
+```okt
+CONTROL {
+    on_step_end {
+        LOG loss
+    }
+    
+    on_epoch_end {
+        SAVE model
+        LOG "Epoch completed"
+    }
+    
+    validate_every: 200
+    
+    IF loss > 2.0 {
+        SET LR = 0.0001
+        LOG "High loss detected"
+    }
+    
+    IF val_loss > 2.5 {
+        STOP_TRAINING
+    }
+    
+    WHEN gpu_memory < 16GB {
+        SET batch_size = 4
+    }
+    
+    EVERY 500 steps {
+        SAVE checkpoint
+    }
+    
+    IF accuracy < 0.4 {
+        DECREASE LR BY 0.5
+    }
+}
+```
+
+**Example (Nested Blocks in Events):**
+```okt
+CONTROL {
+    on_epoch_end {
+        IF loss > 2.0 {
+            SET LR = 0.0001
+            LOG "High loss detected"
+        }
+        
+        IF val_loss > 2.5 {
+            STOP_TRAINING
+        }
+        
+        IF accuracy > 0.9 {
+            SAVE "best_model"
+            LOG "High accuracy reached"
+        }
+    }
+}
+```
+
+**Example (Advanced Nested Logic):**
+```okt
+CONTROL {
+    on_epoch_end {
+        EVERY 2 epochs {
+            SAVE "checkpoint_epoch_{epoch}"
+        }
+        
+        IF loss > 2.0 {
+            SET LR = 0.00005
+            LOG "Loss still high after epoch"
+            
+            WHEN gpu_usage > 90% {
+                SET batch_size = 2
+                LOG "Reducing batch size due to GPU pressure"
+            }
+            
+            IF val_loss > 3.0 {
+                STOP_TRAINING
+            }
+        }
+    }
+}
+```
+
+**Example (Context-Based Control):**
+```okt
+CONTROL {
+    IF epoch == 1 {
+        LOG "Warmup stage"
+    }
+    
+    IF epoch > 5 AND accuracy < 0.6 {
+        SET LR = 0.00001
+        LOG "Model is stagnated"
+    }
+    
+    IF epoch > 10 AND loss > 1.8 {
+        STOP_TRAINING
+    }
+}
+```
+
+**Example (Inference CONTROL):**
+```okt
+INFERENCE {
+    mode: "chat"
+    format: "User: {input}\nAssistant:"
+    
+    CONTROL {
+        IF confidence < 0.3 { RETRY }
+        IF repetition > 3 { REGENERATE }
+        IF toxic == true { REPLACE WITH "Not allowed" }
+    }
+}
+```
+
+**Example (Intent Classification CONTROL):**
+```okt
+INFERENCE {
+    mode: "intent-classification"
+    labels: ["greeting", "order", "complaint", "bye"]
+}
+
+CONTROL {
+    IF label == "complaint" {
+        RETURN "I'm sorry to hear that. How can I help?"
+    }
+    
+    IF confidence < 0.4 {
+        RETURN "Could you please repeat?"
+    }
+}
+```
+
+**Note:** OktoScript enables true declarative AI governance. CONTROL blocks can contain nested conditions and nested event triggers, making it a unique declarative decision-making language in the market.
+
+**Philosophy:**
+
+OktoScript keeps the surface clean and simple, while the engine behind it performs complex cognitive decision-making.
+
+- **CONTROL** defines logic
+- **MONITOR** defines awareness
+- **GUARD** defines safety
+- **BEHAVIOR** defines personality
+- **EXPLORER** defines optimization
+- **STABILITY** defines reliability
+
+Simple to read. Powerful to execute.
+
+---
+
+## EXPORT Block
+
+```ebnf
+<export_block> ::= 
+  "EXPORT" "{"
+      "format" ":" "[" <export_format_list> "]"
+      "path" ":" <path>
+      [ "quantization" ":" ("int8" | "int4" | "fp16" | "fp32") ]
+      [ "optimize_for" ":" ("speed" | "size" | "accuracy") ]
+  "}"
+
+<export_format_list> ::= 
+  "gguf" |
+  "onnx" |
+  "okm" |
+  "safetensors" |
+  "tflite"
+```
+
+**Format-specific constraints:**
+- `gguf`: Requires quantization (int8, int4, or fp16)
+- `onnx`: Best for production deployment
+- `okm`: OktoSeek optimized format (requires OktoSeek SDK)
+- `safetensors`: Standard PyTorch format
+- `tflite`: For mobile deployment (Android/iOS)
+
+**Example:**
+```okt
+EXPORT {
+    format: ["gguf", "onnx", "okm", "safetensors"]
+    path: "export/"
+    quantization: "int8"
+    optimize_for: "speed"
+}
+```
+
+---
+
+## DEPLOY Block
+
+The `DEPLOY` block defines deployment configuration for the model. The engine will create the server, generate routes, export in the required format, and configure limits and authentication.
+
+```ebnf
+<deploy_block> ::=
+  "DEPLOY" "{"
+      "target" ":" ("local" | "cloud" | "edge" | "api" | "android" | "ios" | "web" | "desktop")
+      [ "endpoint" ":" <string> ]
+      [ "host" ":" <string> ]
+      [ "requires_auth" ":" ("true" | "false") ]
+      [ "port" ":" <number> ]
+      [ "max_concurrent_requests" ":" <number> ]
+      [ "protocol" ":" ("http" | "https" | "grpc" | "ws") ]
+      [ "format" ":" ("onnx" | "tflite" | "gguf" | "pt" | "okm") ]
+  "}"
+```
+
+**Target-specific requirements:**
+- `api`: Requires `endpoint`, `host`, and `port`
+- `android`, `ios`: Requires `.okm` or `.tflite` format
+- `web`: Requires ONNX format
+- `edge`: Requires quantized model (int8 or int4)
+
+**Protocol options:**
+- `http` - HTTP REST API
+- `https` - HTTPS REST API
+- `grpc` - gRPC protocol
+- `ws` - WebSocket protocol
+
+**Format options:**
+- `onnx` - ONNX format (production-ready)
+- `tflite` - TensorFlow Lite (mobile)
+- `gguf` - GGUF format (local inference)
+- `pt` - PyTorch format
+- `okm` - OktoModel format (OktoSeek optimized)
+
+**Example (API Deployment):**
+```okt
+DEPLOY {
+    target: "api"
+    host: "0.0.0.0"
+    endpoint: "/pizzabot"
+    requires_auth: true
+    port: 9000
+    max_concurrent_requests: 100
+    protocol: "http"
+    format: "onnx"
+}
+```
+
+**Example (Mobile Deployment):**
+```okt
+DEPLOY {
+    target: "android"
+    format: "tflite"
+}
+```
+
+---
+
+## SECURITY Block
+
+The `SECURITY` block defines security measures for input validation, output validation, rate limiting, and encryption.
+
+```ebnf
+<security_block> ::=
+  "SECURITY" "{"
+      [ <input_validation> ]
+      [ <output_validation> ]
+      [ <rate_limit> ]
+      [ <encryption> ]
+  "}"
+
+<input_validation> ::=
+  "input_validation" "{"
+      [ "max_length" ":" <number> ]
+      [ "disallow_patterns" ":" "[" <string_list> "]" ]
+  "}"
+
+<output_validation> ::=
+  "output_validation" "{"
+      [ "prevent_data_leak" ":" ("true" | "false") ]
+      [ "mask_personal_info" ":" ("true" | "false") ]
+  "}"
+
+<rate_limit> ::=
+  "rate_limit" "{"
+      [ "max_requests_per_minute" ":" <number> ]
+  "}"
+
+<encryption> ::=
+  "encryption" "{"
+      [ "algorithm" ":" ("AES-256" | "SHA-256" | "RSA") ]
+  "}"
+```
+
+**Input validation:**
+- `max_length` - Maximum input length in characters
+- `disallow_patterns` - List of patterns to block (e.g., SQL injection, XSS)
+
+**Output validation:**
+- `prevent_data_leak` - Prevent training data from appearing in outputs
+- `mask_personal_info` - Mask personal information in outputs
+
+**Rate limiting:**
+- `max_requests_per_minute` - Maximum requests per minute per client
+
+**Encryption:**
+- `AES-256` - AES-256 encryption
+- `SHA-256` - SHA-256 hashing
+- `RSA` - RSA encryption
+
+**Example:**
+```okt
+SECURITY {
+    input_validation {
+        max_length: 500
+        disallow_patterns: [
+            "<script>",
+            "DROP TABLE",
+            "rm -rf",
+            "sudo",
+            "passwd"
+        ]
+    }
+    
+    output_validation {
+        prevent_data_leak: true
+        mask_personal_info: true
+    }
+    
+    rate_limit {
+        max_requests_per_minute: 60
+    }
+    
+    encryption {
+        algorithm: "AES-256"
+    }
+}
+```
+
+---
+
+## MONITOR Block — Full Metrics Support
+
+The `MONITOR` block tracks ANY available training or system metric. It supports all native and custom metrics, including but not limited to:
+
+**Training Metrics:**
+- `loss`, `val_loss` - Training and validation loss
+- `accuracy`, `val_accuracy` - Classification accuracy
+- `precision`, `recall`, `f1_score` - Classification metrics
+- `perplexity` - Language model perplexity
+- `bleu`, `rouge` - Generation quality metrics
+- `cer`, `wer` - Character/Word error rates
+- `confidence` - Model confidence scores
+- `hallucination_score` - Hallucination detection
+
+**System Metrics:**
+- `gpu_usage`, `gpu_memory_used`, `gpu_memory_free` - GPU utilization
+- `ram_usage`, `cpu_usage` - System resource usage
+- `gpu_temperature` - GPU temperature monitoring
+- `step_time`, `throughput`, `latency` - Performance metrics
+- `token_count` - Token usage statistics
+
+```ebnf
+<monitor_block> ::=
+  "MONITOR" "{"
+      [<monitor_metrics>]
+      [<monitor_notify_if>]
+      [<monitor_log_to>]
+      [<monitor_level>]
+      [<monitor_log_system>]
+      [<monitor_log_speed>]
+      [<monitor_refresh_interval>]
+      [<monitor_export_to>]
+      [<monitor_dashboard>]
+  "}"
+
+<monitor_metrics> ::=
+  "metrics" ":" "[" <metric_list> "]"
+
+<monitor_notify_if> ::=
+  "notify_if" "{"
+      { <notify_condition> }
+  "}"
+
+<notify_condition> ::=
+  <metric_name> <comparison_operator> <value>
+
+<monitor_log_to> ::=
+  "log_to" ":" <path>
+
+<monitor_level> ::=
+  "level" ":" ("basic" | "full")
+
+<monitor_log_system> ::=
+  "log_system" ":" "[" <system_metric_list> "]"
+
+<monitor_log_speed> ::=
+  "log_speed" ":" "[" <speed_metric_list> "]"
+
+<monitor_refresh_interval> ::=
+  "refresh_interval" ":" <time_interval>
+
+<monitor_export_to> ::=
+  "export_to" ":" <path>
+
+<monitor_dashboard> ::=
+  "dashboard" ":" <boolean>
+
+<metric_list> ::=
+  <string> { "," <string> }
+
+<system_metric_list> ::=
+  ("gpu_memory_used" | "gpu_memory_free" | "gpu_usage" | "cpu_usage" | "ram_usage" | "ram_used" | "disk_io" | "gpu_temperature" | "temperature") { "," <system_metric> }
+
+<speed_metric_list> ::=
+  ("tokens_per_second" | "samples_per_second" | "throughput" | "latency" | "step_time") { "," <speed_metric> }
+
+<time_interval> ::=
+  <number> ("s" | "ms")
+```
+
+**Supported Metrics (Complete List):**
+
+**Training Metrics:**
+- `loss`, `val_loss` - Loss values
+- `accuracy`, `val_accuracy` - Accuracy metrics
+- `precision`, `recall`, `f1_score` - Classification metrics
+- `perplexity` - Language model perplexity
+- `bleu`, `rouge`, `rouge_l`, `rouge_1`, `rouge_2` - Generation metrics
+- `cer`, `wer` - Error rates
+- `confidence` - Confidence scores
+- `hallucination_score` - Hallucination detection
+
+**System Metrics:**
+- `gpu_usage`, `gpu_memory_used`, `gpu_memory_free`, `gpu_temperature` - GPU metrics
+- `ram_usage`, `cpu_usage` - System resources
+- `step_time`, `throughput`, `latency` - Performance
+- `token_count` - Token statistics
+
+**Constraints:**
+- `metrics`: Array of metric names to track
+- `notify_if`: Conditions that trigger notifications
+- `log_to`: Path to log file (optional)
+- GPU metrics only logged if CUDA is available
+- `refresh_interval` must be >= 1s
+
+**Example:**
+```okt
+MONITOR {
+    metrics: [
+        "loss",
+        "accuracy",
+        "val_loss",
+        "gpu_usage",
+        "ram_usage",
+        "throughput",
+        "latency",
+        "confidence"
+    ]
+    
+    notify_if {
+        loss > 2.0
+        gpu_usage > 90%
+        temperature > 85
+        hallucination_score > 0.5
+    }
+    
+    log_to: "logs/training.log"
+}
+```
+
+**Example (Full monitoring):**
+```okt
+MONITOR {
+    level: "full"
+    metrics: [
+        "loss",
+        "val_loss",
+        "accuracy",
+        "f1",
+        "perplexity",
+        "confidence",
+        "hallucination_score"
+    ]
+    log_system: [
+        "gpu_memory_used",
+        "gpu_memory_free",
+        "cpu_usage",
+        "ram_used",
+        "gpu_temperature"
+    ]
+    log_speed: [
+        "tokens_per_second",
+        "samples_per_second",
+        "throughput",
+        "latency"
+    ]
+    notify_if {
+        loss > 2.0
+        gpu_usage > 90%
+        val_loss > 2.5
+    }
+    refresh_interval: 2s
+    export_to: "runs/logs/system.json"
+    dashboard: true
+    log_to: "logs/training.log"
+}
+```
+
+**Integration with METRICS and LOGGING:**
+- `MONITOR` extends (does not replace) `METRICS` and `LOGGING`
+- System metrics are logged separately from training metrics
+- Dashboard provides real-time visualization (if `dashboard: true`)
+- `notify_if` triggers alerts when conditions are met
+
+---
+
+## GUARD Block — Safety / Ethics / Protection
+
+The `GUARD` block defines safety rules during generation and training. It prevents harmful outputs and ensures ethical AI behavior. The engine knows exactly what to prevent, how to detect violations, and what action to take.
+
+```ebnf
+<guard_block> ::=
+  "GUARD" "{"
+      [<guard_prevent>]
+      [<guard_detect_using>]
+      [<guard_on_violation>]
+  "}"
+
+<guard_prevent> ::=
+  "prevent" "{"
+      { <prevention_type> }
+  "}"
+
+<guard_detect_using> ::=
+  "detect_using" ":" "[" ("classifier" | "embedding" | "regex" | "rule_engine" | "ml_model") { "," ("classifier" | "embedding" | "regex" | "rule_engine" | "ml_model") } "]"
+
+<prevention_type> ::=
+  "hallucination" |
+  "toxicity" |
+  "bias" |
+  "data_leak" |
+  "unsafe_code" |
+  "personal_data" |
+  "illegal_content"
+
+<guard_on_violation> ::=
+  "on_violation" "{"
+      <violation_action>
+      [ "with_message" ":" <string> ]
+  "}"
+
+<violation_action> ::=
+  "STOP" | "ALERT" | "REPLACE" | "LOG"
+```
+
+**Prevention types:**
+- `hallucination` - Prevents fabricated or false information
+- `toxicity` - Prevents toxic, harmful, or offensive content
+- `bias` - Prevents biased or discriminatory outputs
+- `data_leak` - Prevents training data leakage
+- `unsafe_code` - Prevents unsafe code generation
+- `personal_data` - Prevents personal information leakage
+- `illegal_content` - Prevents illegal content generation
+
+**Detection methods:**
+- `classifier` - Use ML classifier to detect violations
+- `embedding` - Use embedding similarity to detect violations
+- `regex` - Use regex patterns to detect violations
+- `rule_engine` - Use rule-based engine to detect violations
+- `ml_model` - Use custom ML model to detect violations
+
+**Violation actions:**
+- `STOP` - Stop generation immediately
+- `ALERT` - Log alert and continue
+- `REPLACE` - Replace with safe fallback (requires `with_message`)
+- `LOG` - Log violation for analysis
+
+**Example (Strict Mode):**
+```okt
+GUARD {
+    prevent {
+        hallucination
+        toxicity
+        bias
+        data_leak
+        illegal_content
+    }
+    
+    detect_using: ["classifier", "regex", "embedding"]
+    
+    on_violation {
+        REPLACE
+        with_message: "Sorry, this request is not allowed."
+    }
+}
+```
+
+**Example (Alert mode):**
+```okt
+GUARD {
+    prevent {
+        toxicity
+        bias
+    }
+    
+    detect_using: ["classifier", "rule_engine"]
+    
+    on_violation {
+        ALERT
+    }
+}
+```
+
+---
+
+## BEHAVIOR Block — Model Personality
+
+The `BEHAVIOR` block defines how the model should behave in chat/inference. It sets personality, verbosity, language, and content restrictions.
+
+```ebnf
+<behavior_block> ::=
+  "BEHAVIOR" "{"
+      [<behavior_mode>]
+      [<behavior_personality>]
+      [<behavior_verbosity>]
+      [<behavior_language>]
+      [<behavior_avoid>]
+      [<behavior_fallback>]
+      [<behavior_style_prompt>]
+  "}"
+
+<behavior_mode> ::=
+  "mode" ":" ("chat" | "completion" | "instruction" | "classifier")
+
+<behavior_personality> ::=
+  "personality" ":" ("professional" | "friendly" | "assistant" | "casual" | "formal" | "creative")
+
+<behavior_verbosity> ::=
+  "verbosity" ":" ("low" | "medium" | "high")
+
+<behavior_language> ::=
+  "language" ":" ("en" | "pt-BR" | "es" | "fr" | "de" | "it" | "ja" | "zh" | "multilingual")
+
+<behavior_avoid> ::=
+  "avoid" ":" "[" <string_list> "]"
+
+<behavior_fallback> ::=
+  "fallback" ":" <string>
+
+<behavior_style_prompt> ::=
+  "prompt_style" ":" <string>
+```
+
+**Mode types:**
+- `chat` - Conversational chat mode
+- `completion` - Text completion mode
+- `instruction` - Instruction-following mode
+- `classifier` - Classification mode
+
+**Personality types:**
+- `professional` - Formal, business-like responses
+- `friendly` - Warm, approachable tone
+- `assistant` - Helpful, service-oriented
+- `casual` - Relaxed, informal tone
+- `formal` - Very formal, academic tone
+- `creative` - Imaginative, expressive responses
+
+**Verbosity levels:**
+- `low` - Concise, brief responses
+- `medium` - Balanced detail
+- `high` - Detailed, comprehensive responses
+
+**prompt_style allows you to define:**
+- ChatGPT-style format
+- Translation format
+- Classification format
+- Custom format (e.g., NLP tasks)
+
+**Example (Professional Chatbot):**
+```okt
+BEHAVIOR {
+    mode: "chat"
+    personality: "professional"
+    verbosity: "medium"
+    language: "pt-BR"
+    avoid: ["violence", "hate", "politics"]
+    fallback: "Como posso ajudar?"
+    prompt_style: "User: {input}\nAssistant:"
+}
+```
+
+**Example (Friendly assistant):**
+```okt
+BEHAVIOR {
+    mode: "chat"
+    personality: "friendly"
+    verbosity: "high"
+    language: "en"
+    avoid: ["violence", "explicit content"]
+    fallback: "I'm here to help! How can I assist you?"
+    prompt_style: "User: {input}\nAssistant:"
+}
+```
+
+---
+
+## EXPLORER Block — Parameter Search
+
+The `EXPLORER` block enables basic hyperparameter exploration (AutoML-style). It automatically tests different parameter combinations and selects the best configuration.
+
+```ebnf
+<explorer_block> ::=
+  "EXPLORER" "{"
+      <explorer_try>
+      [<explorer_max_tests>]
+      [<explorer_pick_best_by>]
+  "}"
+
+<explorer_try> ::=
+  "try" "{"
+      { <explorer_lr> | <explorer_batch_size> | <explorer_optimizer> | <explorer_scheduler> | <explorer_other> }
+  "}"
+
+<explorer_lr> ::=
+  "lr" ":" "[" <decimal_list> "]"
+
+<explorer_batch_size> ::=
+  "batch_size" ":" "[" <number_list> "]"
+
+<explorer_optimizer> ::=
+  "optimizer" ":" "[" <string_list> "]"
+
+<explorer_scheduler> ::=
+  "scheduler" ":" "[" <string_list> "]"
+
+<explorer_other> ::=
+  <identifier> ":" "[" <value_list> "]"
+
+<explorer_max_tests> ::=
+  "max_tests" ":" <number>
+
+<explorer_pick_best_by> ::=
+  "pick_best_by" ":" <metric_name>
+
+<decimal_list> ::=
+  <decimal> { "," <decimal> }
+
+<number_list> ::=
+  <number> { "," <number> }
+
+<value_list> ::=
+  <value> { "," <value> }
+```
+
+**Constraints:**
+- `max_tests`: Must be <= 50 (to prevent excessive exploration)
+- `pick_best_by`: Must be a valid metric name (e.g., `"val_loss"`, `"accuracy"`)
+- Explorer will test combinations and select the best configuration based on the specified metric
+
+**Example:**
+```okt
+EXPLORER {
+    try {
+        lr: [0.001, 0.0005, 0.0001]
+        batch_size: [4, 8, 16]
+        optimizer: ["adamw", "sgd"]
+    }
+    
+    max_tests: 5
+    pick_best_by: "val_loss"
+}
+```
+
+**Example (Extended exploration):**
+```okt
+EXPLORER {
+    try {
+        lr: [0.0003, 0.0001, 0.00005]
+        batch_size: [8, 16, 32]
+        optimizer: ["adamw", "adam"]
+        scheduler: ["cosine", "linear"]
+    }
+    
+    max_tests: 12
+    pick_best_by: "val_accuracy"
+}
+```
+
+---
+
+## STABILITY Block — Training Safety
+
+The `STABILITY` block controls training stability and prevents common training failures.
+
+```ebnf
+<stability_block> ::=
+  "STABILITY" "{"
+      [<stability_stop_if_nan>]
+      [<stability_stop_if_diverges>]
+      [<stability_min_improvement>]
+  "}"
+
+<stability_stop_if_nan> ::=
+  "stop_if_nan" ":" <boolean>
+
+<stability_stop_if_diverges> ::=
+  "stop_if_diverges" ":" <boolean>
+
+<stability_min_improvement> ::=
+  "min_improvement" ":" <decimal>
+```
+
+**Constraints:**
+- `stop_if_nan`: Boolean - Stop training if NaN values are detected
+- `stop_if_diverges`: Boolean - Stop training if loss diverges
+- `min_improvement`: Float - Minimum improvement threshold (e.g., 0.001)
+
+**Example:**
+```okt
+STABILITY {
+    stop_if_nan: true
+    stop_if_diverges: true
+    min_improvement: 0.001
+}
+```
+
+**Example (Relaxed stability):**
+```okt
+STABILITY {
+    stop_if_nan: true
+    stop_if_diverges: false
+    min_improvement: 0.0001
+}
+```
+
+---
+
+## Boolean Support
+
+The OktoScript language supports boolean values:
+
+- `true`
+- `false`
+
+**Supported in:**
+- `CONTROL` block conditions and actions
+- `STABILITY` block flags
+- `BEHAVIOR` block settings
+- `GUARD` block actions
+- `MONITOR` block dashboard flag
+- `INFERENCE` block `do_sample` parameter
+- Any block that requires boolean values
+
+**Example:**
+```okt
+STABILITY {
+    stop_if_nan: true
+    stop_if_diverges: false
+}
+
+BEHAVIOR {
+    personality: "friendly"
+}
+
+MONITOR {
+    dashboard: true
+}
+
+INFERENCE {
+    params {
+        do_sample: true
+    }
+}
+```
+
+---
+
+## LOGGING Block
+
+```ebnf
+<logging_block> ::= 
+  "LOGGING" "{"
+      "save_logs" ":" ("true" | "false")
+      "metrics_file" ":" <path>
+      "training_file" ":" <path>
+      [ "log_level" ":" ("debug" | "info" | "warning" | "error") ]
+      [ "log_every" ":" <number> ]
+  "}"
+```
+
+**Example:**
+```okt
+LOGGING {
+    save_logs: true
+    metrics_file: "runs/pizzabot-v1/metrics.json"
+    training_file: "runs/pizzabot-v1/training_logs.json"
+    log_level: "info"
+    log_every: 10
+}
+```
+
+---
+
+## Model Inheritance
+
+OktoScript supports model inheritance to reduce code duplication and enable configuration reuse.
+
+**Syntax:**
+```okt
+# Base model definition (named)
+MODEL "base-transformer" {
+    architecture: "transformer"
+    context_window: 2048
+    precision: "fp16"
+}
+
+# Child model inheriting from base
+MODEL {
+    inherit: "base-transformer"
+    base: "oktoseek/custom-model"
+    parameters: 250M
+    # Overrides: precision stays "fp16" from parent
+    # New: base and parameters are set
+}
+```
+
+**Inheritance rules:**
+1. Child model inherits all fields from parent
+2. Child can override any inherited field
+3. Fields not specified in child use parent values
+4. Inheritance chain can be multiple levels (parent → child → grandchild)
+5. Circular inheritance is not allowed
+
+**Example with multiple inheritance:**
+```okt
+# Grandparent
+MODEL "base-config" {
+    architecture: "transformer"
+    precision: "fp16"
+}
+
+# Parent
+MODEL "medium-model" {
+    inherit: "base-config"
+    parameters: 120M
+    context_window: 2048
+}
+
+# Child
+MODEL {
+    inherit: "medium-model"
+    base: "oktoseek/specialized-model"
+    parameters: 250M
+}
+```
+
+---
+
+## Extension Points & Hooks
+
+OktoScript supports extension points for custom logic integration.
+
+### HOOKS Block
+
+```ebnf
+<hooks_block> ::=
+  "HOOKS" "{"
+      [ "before_train" ":" <script_path> ]
+      [ "after_train" ":" <script_path> ]
+      [ "before_epoch" ":" <script_path> ]
+      [ "after_epoch" ":" <script_path> ]
+      [ "on_checkpoint" ":" <script_path> ]
+      [ "custom_metric" ":" <script_path> ]
+  "}"
+```
+
+**Hook script format:**
+- Python scripts (`.py`) - Most common
+- JavaScript/Node.js (`.js`) - For web integrations
+- Shell scripts (`.sh`) - For system operations
+
+**Hook script interface:**
+```python
+# before_train.py
+def before_train(config, dataset, model):
+    # Custom preprocessing
+    # Modify config if needed
+    return config
+
+# after_epoch.py
+def after_epoch(epoch, metrics, model_state):
+    # Custom logging, early stopping logic
+    # Return True to stop training
+    return False
+```
+
+**Example:**
+```okt
+HOOKS {
+    before_train: "scripts/preprocess.py"
+    after_epoch: "scripts/custom_early_stop.py"
+    on_checkpoint: "scripts/backup_checkpoint.sh"
+    custom_metric: "scripts/toxicity_calculator.py"
+}
+```
+
+### Python Integration
+
+OktoScript can call Python functions directly:
+
+```okt
+HOOKS {
+    before_train: "python:my_module.preprocess_data"
+    custom_metric: "python:metrics.custom_f1_score"
+}
+```
+
+### API Integration
+
+```okt
+HOOKS {
+    after_train: "api:https://api.example.com/log_training"
+    on_checkpoint: "api:https://api.example.com/upload_checkpoint"
+}
+```
+
+---
+
+## Validation Rules
+
+### File Structure Validation
+
+1. **Required files:**
+   - `okt.yaml` must exist in project root
+   - Dataset files specified in DATASET block must exist
+   - Model base path must be valid (if local path)
+
+2. **Field validation:**
+   - All required fields must be present
+   - Field types must match grammar specification
+   - Numeric values must be within allowed ranges
+   - String values must match allowed patterns
+
+3. **Dependency validation:**
+   - If `inherit` is used, parent model must exist
+   - If `resume_from_checkpoint` is used, checkpoint must exist
+   - Export formats must be compatible with model architecture
+
+### Runtime Validation
+
+**Dataset validation:**
+- File exists and is readable
+- Format matches declared format
+- Required columns/fields present (for structured data)
+- File size within limits (max 10GB per file)
+
+**Model validation:**
+- Base model exists (if local) or is downloadable (if remote)
+- Model architecture compatible with dataset type
+- Model size fits available memory
+
+**Training validation:**
+- Device available (GPU if specified)
+- Sufficient disk space for checkpoints
+- Batch size fits in memory
+
+### Error Messages
+
+Common validation errors and solutions:
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Dataset file not found` | Path in DATASET block doesn't exist | Check file path, use absolute or relative path |
+| `Invalid optimizer: 'invalid'` | Optimizer not in allowed list | Use one of: adam, adamw, sgd, rmsprop, adafactor, lamb |
+| `Model base not found` | Base model path invalid | Verify model path or HuggingFace model name |
+| `Checkpoint not found` | Resume checkpoint doesn't exist | Check checkpoint path or remove resume_from_checkpoint |
+| `Insufficient memory` | Batch size too large | Reduce batch_size or enable gradient_accumulation |
+| `Invalid metric for task` | Metric incompatible with task type | Use appropriate metrics (e.g., accuracy for classification) |
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Training fails with "Out of Memory"**
+
+**Symptoms:**
+- CUDA out of memory error
+- Training crashes after a few steps
+
+**Solutions:**
+```okt
+TRAIN {
+    batch_size: 8  # Reduce from 32
+    gradient_accumulation: 4  # Increase to maintain effective batch size
+    precision: "fp16"  # Use mixed precision
+}
+```
+
+**2. Model not improving (loss plateau)**
+
+**Symptoms:**
+- Loss stops decreasing
+- Metrics remain constant
+
+**Solutions:**
+```okt
+TRAIN {
+    learning_rate: 0.0001  # Try different learning rate
+    scheduler: "cosine_with_restarts"  # Use learning rate schedule
+    weight_decay: 0.01  # Add regularization
+}
+
+VALIDATE {
+    save_best_model: true
+    metric_to_monitor: "loss"
+}
+```
+
+**3. Dataset format errors**
+
+**Symptoms:**
+- "Invalid dataset format"
+- "Missing required columns"
+
+**Solutions:**
+- Verify dataset format matches declared format
+- For JSONL: Ensure each line is valid JSON with required fields
+- For CSV: Check column names match expected schema
+- Use `okto validate` to check dataset before training
+
+**4. Export fails**
+
+**Symptoms:**
+- "Export format not supported"
+- "Quantization failed"
+
+**Solutions:**
+- Ensure model architecture supports export format
+- For GGUF: Model must be quantized (use int8 or int4)
+- For ONNX: Model must be ONNX-compatible architecture
+- Check available disk space
+
+**5. Inference produces poor results**
+
+**Symptoms:**
+- Low quality outputs
+- Repetitive text
+- Off-topic responses
+
+**Solutions:**
+```okt
+INFERENCE {
+    temperature: 0.7  # Lower = more deterministic
+    top_p: 0.9  # Nucleus sampling
+    top_k: 40  # Limit vocabulary
+    repetition_penalty: 1.2  # Reduce repetition
+    max_tokens: 200  # Limit length
+}
+```
+
+### Debug Mode
+
+Enable debug logging:
+
+```okt
+LOGGING {
+    save_logs: true
+    log_level: "debug"
+    log_every: 1
+}
+```
+
+Run with verbose output:
+```bash
+okto run project.okt --verbose --debug
+```
+
+### Performance Optimization
+
+**For faster training:**
+```okt
+TRAIN {
+    batch_size: 64  # Larger batches
+    gradient_accumulation: 1  # No accumulation
+    mixed_precision: true  # FP16
+    device: "cuda"
+}
+```
+
+**For memory efficiency:**
+```okt
+TRAIN {
+    batch_size: 4
+    gradient_accumulation: 8
+    precision: "fp16"
+    checkpoint_steps: 50  # Save more frequently
+}
+```
+
+---
+
+## Terminal / Basic Types
+
+```ebnf
+<string> ::= '"' { any-character-except-quote } '"'
+
+<string_list> ::= <string> { "," <string> }
+
+<path> ::= '"' { any-character-except-quote } '"'
+
+<number> ::= digit { digit }
+
+<decimal> ::= digit { digit } "." digit { digit }
+
+<boolean> ::= "true" | "false"
+
+digit ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
+```
+
+**Type constraints:**
+- `string`: UTF-8 encoded, max 10,000 characters
+- `path`: Can be absolute or relative, must be valid filesystem path
+- `number`: Integer, range depends on field (typically 0 to 2^31-1)
+- `decimal`: Floating point, precision up to 6 decimal places
+- `boolean`: Literal values `true` or `false` (lowercase)
+
+---
+
+## Full Script Example
+
+Complete example demonstrating all new blocks:
+
+```okt
+# okto_version: "1.2"
+PROJECT "oktogpt"
+DESCRIPTION "Complete example with all new blocks"
+
+MODEL {
+    name: "oktogpt"
+    base: "google/flan-t5-base"
+    device: "cuda"
+    
+    ADAPTER {
+        type: "lora"
+        path: "D:/model_trainee/phase1_sharegpt/ep2"
+        rank: 16
+        alpha: 32
+    }
+}
+
+MONITOR {
+    metrics: [
+        "loss",
+        "val_loss",
+        "accuracy",
+        "gpu_usage",
+        "ram_usage",
+        "throughput",
+        "latency",
+        "confidence"
+    ]
+    
+    notify_if {
+        loss > 2.0
+        gpu_usage > 90%
+        temperature > 85
+        hallucination_score > 0.5
+    }
+    
+    log_to: "logs/training.log"
+}
+
+BEHAVIOR {
+    personality: "assistant"
+    language: "pt-BR"
+    verbosity: "medium"
+    avoid: ["politics", "violence", "hate"]
+    fallback: "Como posso ajudar?"
+}
+
+STABILITY {
+    stop_if_nan: true
+    stop_if_diverges: true
+    min_improvement: 0.001
+}
+
+EXPLORER {
+    try {
+        lr: [0.0003, 0.0001]
+        batch_size: [4, 8]
+    }
+    max_tests: 4
+    pick_best_by: "val_loss"
+}
+
+CONTROL {
+    on_epoch_end {
+        SAVE model
+        LOG "Epoch completed"
+    }
+    
+    IF val_loss > 2.0 {
+        STOP_TRAINING
+    }
+    
+    WHEN gpu_memory < 12GB {
+        SET batch_size = 4
+    }
+}
+
+INFERENCE {
+    mode: "chat"
+    format: "User: {input}\nAssistant:"
+    
+    params {
+        temperature: 0.7
+        max_length: 120
+        top_p: 0.9
+        beams: 2
+        do_sample: true
+    }
+    
+    CONTROL {
+        IF confidence < 0.3 { RETRY }
+        IF hallucination_score > 0.5 { REPLACE WITH "Desculpe, não tenho certeza." }
+    }
+    
+    exit_command: "/exit"
+}
+
+GUARD {
+    prevent {
+        hallucination
+        toxicity
+        bias
+        data_leak
+        unsafe_code
+    }
+    
+    on_violation {
+        STOP
+    }
+}
+```
+
+---
+
+## Complete Examples
+
+See [`../examples/`](../examples/) for complete working examples:
+
+- [`basic.okt`](../examples/basic.okt) - Minimal example
+- [`chatbot.okt`](../examples/chatbot.okt) - Conversational AI
+- [`computer_vision.okt`](../examples/computer_vision.okt) - Image classification
+- [`recommender.okt`](../examples/recommender.okt) - Recommendation system
+- [`pizzabot/`](../examples/pizzabot/) - Complete project example
+
+📊 **Example datasets available in** [`../examples/pizzabot/dataset/`](../examples/pizzabot/dataset/)
+
+---
+
+**Version:** 1.2  
+**Last Updated:** December 2025  
+**Maintained by:** OktoSeek AI
+
+---
+
+## Version History
+
+### v1.2 (December 2025)
+- ✅ Enhanced `CONTROL` block with nested blocks support
+- ✅ Enhanced `BEHAVIOR` block with `mode` and `prompt_style`
+- ✅ Enhanced `GUARD` block with `detect_using` and additional prevention types
+- ✅ Enhanced `DEPLOY` block with `host`, `protocol`, and `format`
+- ✅ Enhanced `SECURITY` block with `input_validation`, `output_validation`, `rate_limit`, and `encryption`
+- ✅ Added support for nested IF/WHEN/EVERY statements inside event hooks
+- ✅ 100% backward compatible with v1.0 and v1.1
+
+### v1.1 (November 2025)
+- ✅ Added `FT_LORA` block for LoRA fine-tuning
+- ✅ Added dataset mixing support (`mix_datasets`, `dataset_percent`, `sampling`)
+- ✅ Added `MONITOR` block for system telemetry
+- ✅ Added version declaration (`# okto_version`)
+- ✅ 100% backward compatible with v1.0
+
+### v1.0 (Initial Release)
+- Initial OktoScript specification
+- Core blocks: PROJECT, DATASET, MODEL, TRAIN, METRICS, EXPORT, DEPLOY
+- Model inheritance
+- Extension points and hooks
+
+---
+
+## About OktoScript
+
+**OktoScript** is a domain-specific programming language developed by **OktoSeek AI** for building, training, evaluating and exporting AI models. It is part of the OktoSeek ecosystem, which includes OktoSeek IDE, OktoEngine, and various tools for AI development.
+
+For more information, visit:
+- **Official website:** https://www.oktoseek.com
+- **GitHub:** https://github.com/oktoseek/oktoscript
+- **Hugging Face:** https://huggingface.co/OktoSeek
+- **Twitter:** https://x.com/oktoseek
+- **YouTube:** https://www.youtube.com/@Oktoseek

examples/README.md

@@ -0,0 +1,169 @@
+# OktoScript Examples
+
+This folder contains official example scripts written in **OktoScript (.okt)**.
+
+These examples are used by:
+
+- Developers learning OktoScript
+- Students and researchers
+- OktoSeek IDE
+- VS Code Extension
+- Automatic tests and validation
+
+---
+
+## Available Examples
+
+### Basic Examples
+
+| File | Description | Use Case |
+|------|-------------|----------|
+| [`basic.okt`](./basic.okt) | Minimal example | Getting started |
+| [`chatbot.okt`](./chatbot.okt) | Conversational AI | Customer service, assistants |
+| [`computer_vision.okt`](./computer_vision.okt) | Image classification | Vision models, object detection |
+| [`recommender.okt`](./recommender.okt) | Recommendation system | E-commerce, content suggestions |
+
+### Advanced Examples
+
+| File | Description | Use Case |
+|------|-------------|----------|
+| [`finetuning-llm.okt`](./finetuning-llm.okt) | Fine-tuning LLM with checkpoints | Advanced language models, resume training |
+| [`vision-pipeline.okt`](./vision-pipeline.okt) | Complete vision pipeline | Production vision systems, ONNX export |
+| [`qa-embeddings.okt`](./qa-embeddings.okt) | QA with embeddings | Semantic search, retrieval systems |
+
+### v1.1 Examples (New Features)
+
+| File | Description | Use Case |
+|------|-------------|----------|
+| [`lora-finetuning.okt`](./lora-finetuning.okt) | LoRA fine-tuning with dataset mixing | Efficient fine-tuning, memory-efficient training |
+| [`dataset-mixing.okt`](./dataset-mixing.okt) | Training with multiple weighted datasets | Combining datasets, weighted sampling |
+
+### v1.2 Examples (Advanced Features)
+
+| File | Description | Use Case |
+|------|-------------|----------|
+| [`control-nested.okt`](./control-nested.okt) | Nested CONTROL blocks with advanced decision-making | Dynamic training control, conditional logic |
+| [`behavior-chat.okt`](./behavior-chat.okt) | BEHAVIOR block with mode and prompt_style | Chatbot personality, response style |
+| [`guard-safety.okt`](./guard-safety.okt) | GUARD block with multiple detection methods | Content safety, ethical AI |
+| [`deploy-api.okt`](./deploy-api.okt) | DEPLOY block for API deployment | Production API deployment |
+| [`security-full.okt`](./security-full.okt) | Complete SECURITY block configuration | Input/output validation, rate limiting |
+| [`model-adapter.okt`](./model-adapter.okt) | MODEL block with ADAPTER (LoRA/PEFT) | Parameter-efficient fine-tuning |
+| [`inference-advanced.okt`](./inference-advanced.okt) | Advanced INFERENCE with nested CONTROL | Smart inference with retry logic |
+| [`monitor-full.okt`](./monitor-full.okt) | Complete MONITOR block with all metrics | Full system and training telemetry |
+| [`explorer-automl.okt`](./explorer-automl.okt) | EXPLORER block for hyperparameter search | AutoML-style optimization |
+| [`stability-training.okt`](./stability-training.okt) | STABILITY block for safe training | Training stability and safety |
+| [`complete-v1.2.okt`](./complete-v1.2.okt) | Complete example with all v1.2 features | Full feature demonstration |
+
+### Complete Projects
+
+| File | Description | Use Case |
+|------|-------------|----------|
+| [`pizzabot/`](./pizzabot/) | Complete project example | Full workflow demonstration |
+
+---
+
+## Quick Start
+
+To run these examples with OktoEngine (when available):
+
+```bash
+# Validate syntax
+okto validate examples/basic.okt
+
+# Train a model
+okto train examples/chatbot.okt
+
+# Evaluate performance
+okto eval examples/recommender.okt
+
+# Export model
+okto export examples/computer_vision.okt --format=okm
+```
+
+---
+
+## Export Formats
+
+OktoScript supports multiple export formats for different use cases:
+
+### Standard Formats
+
+- **ONNX** - Universal inference, production-ready
+- **GGUF** - Local inference, Ollama, Llama.cpp
+- **SafeTensors** - HuggingFace, research, standard training
+
+### OktoSeek Optimized Formats
+
+- **OktoModel (.okm)** - Optimized for OktoSeek SDK & Flutter plugins
+- **OktoBundle (.okx)** - Mobile + Edge package (iOS, Android, Edge AI)
+
+> 💡 **Tip:** While standard formats work everywhere, `.okm` and `.okx` formats are optimized for the OktoSeek ecosystem, providing better integration with Flutter apps, mobile SDKs, and OktoSeek tools.
+
+---
+
+## Example: Using OktoModel Format
+
+```okt
+EXPORT {
+  format: ["onnx", "okm"]
+  path: "export/"
+}
+```
+
+**Why use .okm?**
+
+- ✅ Optimized for OktoSeek Flutter SDK
+- ✅ Better performance on mobile devices
+- ✅ Access to exclusive OktoSeek tools and plugins
+- ✅ Seamless integration with OktoSeek ecosystem
+- ✅ Support for iOS and Android apps
+
+**Note:** `.okm` is optional. You can always export to standard formats (ONNX, GGUF, SafeTensors) for universal compatibility.
+
+---
+
+## Training Workflow
+
+During training, OktoScript uses standard formats (this is industry-standard):
+
+```
+runs/my-model/
+├── checkpoint-100/
+│   └── model.safetensors
+├── checkpoint-200/
+│   └── model.safetensors
+├── tokenizer.json
+└── training_logs.json
+```
+
+After training, you choose your export format based on your deployment needs.
+
+---
+
+## Complete Project Example
+
+See [`pizzabot/`](./pizzabot/) for a complete project example with:
+- Full project structure
+- Multiple dataset files
+- Training configuration
+- Export settings
+- Example outputs
+
+---
+
+## Contributing
+
+Want to add your own example? 
+
+1. Create a new `.okt` file in this directory
+2. Follow the OktoScript grammar specification
+3. Include clear comments and descriptions
+4. Submit a pull request!
+
+---
+
+**Powered by OktoSeek AI**
+
+- **Website:** https://www.oktoseek.com
+- **GitHub:** https://github.com/oktoseek/oktoscript
+- **Documentation:** [../docs/grammar.md](../docs/grammar.md)

examples/basic.okt

@@ -0,0 +1,28 @@
+PROJECT "BasicModel"
+DESCRIPTION "Minimal OktoScript example - perfect for getting started"
+
+ENV {
+  accelerator: "cpu"
+  min_memory: "4GB"
+  install_missing: true
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+}
+
+MODEL {
+  base: "oktoseek/base-mini"
+}
+
+TRAIN {
+  epochs: 2
+  batch_size: 16
+  device: "cpu"
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+

examples/behavior-chat.okt

@@ -0,0 +1,78 @@
+# okto_version: "1.2"
+PROJECT "BehaviorChatExample"
+DESCRIPTION "Demonstrates BEHAVIOR block with mode and prompt_style"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+  language: "en"
+}
+
+MODEL {
+  name: "behavior-chat-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  learning_rate: 0.0001
+  device: "cuda"
+}
+
+BEHAVIOR {
+  mode: "chat"
+  personality: "friendly"
+  verbosity: "medium"
+  language: "en"
+  avoid: ["violence", "hate", "politics"]
+  fallback: "I'm here to help! How can I assist you?"
+  prompt_style: "User: {input}\nAssistant:"
+}
+
+INFERENCE {
+  mode: "chat"
+  format: "User: {input}\nAssistant:"
+  exit_command: "/exit"
+  
+  params {
+    max_length: 120
+    temperature: 0.7
+    top_p: 0.9
+    do_sample: true
+  }
+  
+  CONTROL {
+    IF confidence < 0.3 { RETRY }
+    IF repetition > 3 { REGENERATE }
+  }
+}
+
+GUARD {
+  prevent {
+    toxicity
+    bias
+    hallucination
+  }
+  
+  detect_using: ["classifier", "regex"]
+  
+  on_violation {
+    REPLACE
+    with_message: "Sorry, this request is not allowed."
+  }
+}
+
+EXPORT {
+  format: ["okm", "onnx"]
+  path: "export/"
+}
+

examples/chatbot.okt

@@ -0,0 +1,47 @@
+PROJECT "PizzaBot"
+DESCRIPTION "Chatbot specialized in pizza restaurant service"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+  backend: "oktoseek"
+  install_missing: true
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+  language: "en"
+}
+
+MODEL {
+  base: "oktoseek/pizza-small"
+  architecture: "transformer"
+  parameters: 120M
+  context_window: 2048
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  learning_rate: 0.0001
+  optimizer: "adamw"
+  scheduler: "cosine"
+  device: "auto"
+  checkpoint_steps: 100
+}
+
+METRICS {
+  accuracy
+  perplexity
+  f1
+  response_coherence
+}
+
+EXPORT {
+  format: ["gguf", "okm"]
+  path: "export/"
+}
+

examples/complete-v1.2.okt

@@ -0,0 +1,210 @@
+# okto_version: "1.2"
+PROJECT "CompleteV12Example"
+DESCRIPTION "Complete example demonstrating all v1.2 features"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "16GB"
+  precision: "fp16"
+  backend: "oktoseek"
+  install_missing: true
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  validation: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+  language: "en"
+}
+
+MODEL {
+  name: "complete-v12-model"
+  base: "google/flan-t5-base"
+  device: "cuda"
+  
+  ADAPTER {
+    type: "lora"
+    path: "./adapters/my-adapter"
+    rank: 16
+    alpha: 32
+  }
+}
+
+TRAIN {
+  epochs: 10
+  batch_size: 32
+  learning_rate: 0.0001
+  optimizer: "adamw"
+  scheduler: "cosine"
+  device: "cuda"
+  checkpoint_steps: 100
+}
+
+METRICS {
+  accuracy
+  loss
+  perplexity
+  f1
+  confidence
+}
+
+MONITOR {
+  metrics: [
+    "loss",
+    "val_loss",
+    "accuracy",
+    "gpu_usage",
+    "ram_usage",
+    "throughput",
+    "latency",
+    "confidence"
+  ]
+  
+  notify_if {
+    loss > 2.0
+    gpu_usage > 90%
+    temperature > 85
+    hallucination_score > 0.5
+  }
+  
+  log_to: "logs/training.log"
+}
+
+BEHAVIOR {
+  mode: "chat"
+  personality: "assistant"
+  verbosity: "medium"
+  language: "en"
+  avoid: ["politics", "violence", "hate"]
+  fallback: "How can I help you?"
+  prompt_style: "User: {input}\nAssistant:"
+}
+
+STABILITY {
+  stop_if_nan: true
+  stop_if_diverges: true
+  min_improvement: 0.001
+}
+
+EXPLORER {
+  try {
+    lr: [0.0003, 0.0001]
+    batch_size: [16, 32]
+  }
+  max_tests: 4
+  pick_best_by: "val_loss"
+}
+
+CONTROL {
+  on_epoch_end {
+    SAVE model
+    LOG "Epoch completed"
+    
+    IF loss > 2.0 {
+      SET LR = 0.00005
+      LOG "High loss detected"
+      
+      WHEN gpu_usage > 90% {
+        SET batch_size = 16
+        LOG "Reducing batch size due to GPU pressure"
+      }
+    }
+    
+    IF val_loss > 2.5 {
+      STOP_TRAINING
+    }
+    
+    IF accuracy > 0.9 {
+      SAVE "best_model"
+      LOG "High accuracy reached"
+    }
+  }
+  
+  validate_every: 200
+  
+  WHEN gpu_memory < 12GB {
+    SET batch_size = 16
+  }
+  
+  EVERY 500 steps {
+    SAVE checkpoint
+  }
+}
+
+INFERENCE {
+  mode: "chat"
+  format: "User: {input}\nAssistant:"
+  exit_command: "/exit"
+  
+  params {
+    temperature: 0.7
+    max_length: 120
+    top_p: 0.9
+    beams: 2
+    do_sample: true
+  }
+  
+  CONTROL {
+    IF confidence < 0.3 { RETRY }
+    IF hallucination_score > 0.5 { REPLACE WITH "I'm not certain about that." }
+  }
+}
+
+GUARD {
+  prevent {
+    hallucination
+    toxicity
+    bias
+    data_leak
+    unsafe_code
+  }
+  
+  detect_using: ["classifier", "regex", "embedding"]
+  
+  on_violation {
+    REPLACE
+    with_message: "Sorry, this request is not allowed."
+  }
+}
+
+SECURITY {
+  input_validation {
+    max_length: 500
+    disallow_patterns: [
+      "<script>",
+      "DROP TABLE",
+      "rm -rf"
+    ]
+  }
+  
+  output_validation {
+    prevent_data_leak: true
+    mask_personal_info: true
+  }
+  
+  rate_limit {
+    max_requests_per_minute: 60
+  }
+  
+  encryption {
+    algorithm: "AES-256"
+  }
+}
+
+EXPORT {
+  format: ["okm", "onnx", "gguf"]
+  path: "export/"
+}
+
+DEPLOY {
+  target: "api"
+  host: "0.0.0.0"
+  endpoint: "/chatbot"
+  requires_auth: true
+  port: 9000
+  max_concurrent_requests: 100
+  protocol: "http"
+  format: "onnx"
+}
+

examples/computer_vision.okt

@@ -0,0 +1,41 @@
+PROJECT "VisionClassifier"
+DESCRIPTION "Image classification example for computer vision tasks"
+
+DATASET {
+  train: "dataset/images/"
+  format: "image+caption"
+  type: "vision"
+  augmentation: ["flip", "rotate", "brightness"]
+}
+
+MODEL {
+  base: "oktoseek/vision-base"
+  architecture: "cnn"
+  parameters: 50M
+  precision: "fp16"
+}
+
+TRAIN {
+  epochs: 20
+  batch_size: 64
+  learning_rate: 0.001
+  optimizer: "adam"
+  device: "cuda"
+  early_stopping: true
+}
+
+METRICS {
+  accuracy
+  precision
+  recall
+  f1
+}
+
+EXPORT {
+  format: ["onnx", "okm"]
+  path: "export/"
+  quantization: "int8"
+}
+
+
+

examples/control-nested.okt

@@ -0,0 +1,99 @@
+# okto_version: "1.2"
+PROJECT "ControlNestedExample"
+DESCRIPTION "Demonstrates nested CONTROL blocks with advanced decision-making"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  validation: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "nested-control-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+TRAIN {
+  epochs: 10
+  batch_size: 32
+  learning_rate: 0.0001
+  optimizer: "adamw"
+  device: "cuda"
+}
+
+CONTROL {
+  on_step_end {
+    LOG loss
+  }
+  
+  on_epoch_end {
+    IF loss > 2.0 {
+      SET LR = 0.00005
+      LOG "High loss detected, reducing learning rate"
+      
+      WHEN gpu_usage > 90% {
+        SET batch_size = 16
+        LOG "Reducing batch size due to GPU pressure"
+      }
+      
+      IF val_loss > 3.0 {
+        STOP_TRAINING
+      }
+    }
+    
+    IF accuracy > 0.9 {
+      SAVE "best_model"
+      LOG "High accuracy reached"
+    }
+    
+    EVERY 2 epochs {
+      SAVE "checkpoint_epoch_{epoch}"
+    }
+  }
+  
+  validate_every: 200
+  
+  IF epoch == 1 {
+    LOG "Warmup stage"
+  }
+  
+  IF epoch > 5 AND accuracy < 0.6 {
+    SET LR = 0.00001
+    LOG "Model is stagnated, reducing learning rate"
+  }
+  
+  IF epoch > 10 AND loss > 1.8 {
+    STOP_TRAINING
+  }
+  
+  WHEN gpu_memory < 12GB {
+    SET batch_size = 16
+  }
+  
+  EVERY 500 steps {
+    SAVE checkpoint
+  }
+}
+
+MONITOR {
+  metrics: ["loss", "val_loss", "accuracy", "gpu_usage", "ram_usage"]
+  notify_if {
+    loss > 2.0
+    gpu_usage > 90%
+  }
+  log_to: "logs/training.log"
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+

examples/dataset-mixing.okt

@@ -0,0 +1,61 @@
+# okto_version: "1.1"
+PROJECT "MixedDatasetModel"
+DESCRIPTION "Training with multiple datasets using weighted mixing"
+VERSION "1.0"
+AUTHOR "OktoSeek"
+
+DATASET {
+    mix_datasets: [
+        { path: "dataset/general.jsonl", weight: 50 },
+        { path: "dataset/technical.jsonl", weight: 30 },
+        { path: "dataset/creative.jsonl", weight: 20 }
+    ]
+    dataset_percent: 80
+    sampling: "weighted"
+    shuffle: true
+    format: "jsonl"
+    type: "generation"
+    language: "en"
+}
+
+MODEL {
+    base: "oktoseek/base-mini"
+    architecture: "transformer"
+    parameters: 120M
+    context_window: 2048
+    precision: "fp16"
+}
+
+TRAIN {
+    epochs: 10
+    batch_size: 32
+    learning_rate: 0.0001
+    optimizer: "adamw"
+    scheduler: "cosine"
+    device: "cuda"
+    early_stopping: true
+}
+
+METRICS {
+    loss
+    perplexity
+    bleu
+    rouge_l
+}
+
+MONITOR {
+    level: "basic"
+    log_metrics: ["loss", "perplexity"]
+    log_system: ["gpu_memory_used", "cpu_usage"]
+    refresh_interval: 5s
+    export_to: "runs/mixed-dataset/system.json"
+    dashboard: false
+}
+
+EXPORT {
+    format: ["okm"]
+    path: "export/"
+}
+
+
+

examples/datasets/demo_train.jsonl

@@ -0,0 +1,13 @@
+{"input": "Hi", "output": "Hello! How can I help you today?"}
+{"input": "Do you deliver pizza?", "output": "Yes, delivery is available!"}
+{"input": "What flavors do you have?", "output": "We offer Margherita, Pepperoni and Four Cheese."}
+{"input": "Thank you", "output": "You are welcome!"}
+{"input": "What's your phone number?", "output": "You can reach us at (555) 123-4567."}
+{"input": "How long does delivery take?", "output": "Delivery typically takes 30-45 minutes."}
+{"input": "Do you have vegetarian options?", "output": "Yes, we offer Margherita and Veggie pizzas."}
+{"input": "What sizes are available?", "output": "We have Small, Medium, Large and Extra Large."}
+{"input": "Can I customize my pizza?", "output": "Absolutely! You can add or remove any toppings."}
+{"input": "What's your address?", "output": "We're located at 123 Main Street."}
+
+
+

examples/deploy-api.okt

@@ -0,0 +1,77 @@
+# okto_version: "1.2"
+PROJECT "DeployAPIExample"
+DESCRIPTION "Demonstrates DEPLOY block for API deployment"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "api-deploy-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "cuda"
+}
+
+EXPORT {
+  format: ["onnx", "okm"]
+  path: "export/"
+}
+
+DEPLOY {
+  target: "api"
+  host: "0.0.0.0"
+  endpoint: "/chatbot"
+  requires_auth: true
+  port: 9000
+  max_concurrent_requests: 100
+  protocol: "http"
+  format: "onnx"
+}
+
+SECURITY {
+  input_validation {
+    max_length: 500
+    disallow_patterns: [
+      "<script>",
+      "DROP TABLE",
+      "rm -rf",
+      "sudo"
+    ]
+  }
+  
+  output_validation {
+    prevent_data_leak: true
+    mask_personal_info: true
+  }
+  
+  rate_limit {
+    max_requests_per_minute: 60
+  }
+  
+  encryption {
+    algorithm: "AES-256"
+  }
+}
+
+BEHAVIOR {
+  mode: "chat"
+  personality: "assistant"
+  verbosity: "medium"
+  language: "en"
+  fallback: "How can I help you?"
+}
+

examples/explorer-automl.okt

@@ -0,0 +1,50 @@
+# okto_version: "1.2"
+PROJECT "ExplorerAutoMLExample"
+DESCRIPTION "Demonstrates EXPLORER block for hyperparameter search"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  validation: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "explorer-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+EXPLORER {
+  try {
+    lr: [0.001, 0.0005, 0.0001, 0.00005]
+    batch_size: [8, 16, 32]
+    optimizer: ["adamw", "adam", "sgd"]
+    scheduler: ["cosine", "linear", "constant"]
+  }
+  
+  max_tests: 12
+  pick_best_by: "val_loss"
+}
+
+TRAIN {
+  epochs: 5
+  device: "cuda"
+}
+
+MONITOR {
+  metrics: ["loss", "val_loss", "accuracy"]
+  log_to: "logs/explorer.log"
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+

examples/finetuning-llm.okt

@@ -0,0 +1,99 @@
+PROJECT "FineTunedLLM"
+DESCRIPTION "Fine-tuning a small LLM with checkpoint resume and custom callbacks"
+VERSION "1.0"
+AUTHOR "OktoSeek"
+
+DATASET {
+    train: "dataset/instruction_train.jsonl"
+    validation: "dataset/instruction_val.jsonl"
+    test: "dataset/instruction_test.jsonl"
+    format: "instruction"
+    type: "generation"
+    language: "en"
+}
+
+MODEL {
+    base: "oktoseek/base-llm-7b"
+    architecture: "transformer"
+    parameters: 7B
+    context_window: 4096
+    precision: "fp16"
+}
+
+TRAIN {
+    epochs: 5
+    batch_size: 4
+    gradient_accumulation: 8
+    learning_rate: 0.0001
+    optimizer: "adamw"
+    scheduler: "cosine_with_restarts"
+    loss: "cross_entropy"
+    device: "cuda"
+    gpu: true
+    mixed_precision: true
+    early_stopping: true
+    checkpoint_steps: 100
+    checkpoint_path: "./checkpoints"
+    weight_decay: 0.01
+    gradient_clip: 1.0
+    warmup_steps: 100
+    save_strategy: "steps"
+}
+
+METRICS {
+    loss
+    perplexity
+    bleu
+    rouge_l
+    token_efficiency
+    response_coherence
+}
+
+VALIDATE {
+    on_train: false
+    on_validation: true
+    frequency: 1
+    save_best_model: true
+    metric_to_monitor: "loss"
+}
+
+INFERENCE {
+    max_tokens: 512
+    temperature: 0.7
+    top_p: 0.9
+    top_k: 50
+    repetition_penalty: 1.1
+    stop_sequences: ["\n\nHuman:", "\n\nAssistant:"]
+}
+
+EXPORT {
+    format: ["gguf", "onnx", "okm", "safetensors"]
+    path: "export/"
+    quantization: "int8"
+    optimize_for: "speed"
+}
+
+DEPLOY {
+    target: "api"
+    endpoint: "http://localhost:9000/llm"
+    requires_auth: true
+    port: 9000
+    max_concurrent_requests: 50
+}
+
+HOOKS {
+    before_train: "scripts/preprocess_data.py"
+    after_epoch: "scripts/custom_early_stop.py"
+    on_checkpoint: "scripts/backup_checkpoint.sh"
+}
+
+LOGGING {
+    save_logs: true
+    metrics_file: "runs/finetuned-llm/metrics.json"
+    training_file: "runs/finetuned-llm/training_logs.json"
+    log_level: "info"
+    log_every: 10
+}
+
+
+

examples/guard-safety.okt

@@ -0,0 +1,70 @@
+# okto_version: "1.2"
+PROJECT "GuardSafetyExample"
+DESCRIPTION "Demonstrates GUARD block with multiple detection methods"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "guard-safety-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "cuda"
+}
+
+GUARD {
+  prevent {
+    hallucination
+    toxicity
+    bias
+    data_leak
+    unsafe_code
+    personal_data
+    illegal_content
+  }
+  
+  detect_using: ["classifier", "embedding", "regex", "rule_engine", "ml_model"]
+  
+  on_violation {
+    STOP
+    with_message: "Content violation detected. Request blocked."
+  }
+}
+
+BEHAVIOR {
+  mode: "chat"
+  personality: "professional"
+  verbosity: "low"
+  language: "en"
+  fallback: "I cannot assist with that request."
+}
+
+INFERENCE {
+  mode: "chat"
+  format: "User: {input}\nAssistant:"
+  
+  params {
+    temperature: 0.5
+    max_length: 100
+  }
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+

examples/inference-advanced.okt

@@ -0,0 +1,92 @@
+# okto_version: "1.2"
+PROJECT "InferenceAdvancedExample"
+DESCRIPTION "Demonstrates advanced INFERENCE block with nested CONTROL"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "inference-advanced-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "cuda"
+}
+
+BEHAVIOR {
+  mode: "chat"
+  personality: "friendly"
+  verbosity: "high"
+  language: "en"
+  prompt_style: "User: {input}\nAssistant:"
+}
+
+INFERENCE {
+  mode: "chat"
+  format: "User: {input}\nAssistant:"
+  exit_command: "/exit"
+  
+  params {
+    max_length: 200
+    temperature: 0.7
+    top_p: 0.9
+    top_k: 40
+    beams: 2
+    do_sample: true
+    repetition_penalty: 1.1
+  }
+  
+  CONTROL {
+    IF confidence < 0.3 {
+      RETRY
+      LOG "Low confidence, retrying"
+    }
+    
+    IF repetition > 3 {
+      REGENERATE
+      LOG "High repetition detected"
+    }
+    
+    IF hallucination_score > 0.5 {
+      REPLACE WITH "I'm not certain about that. Could you rephrase?"
+    }
+    
+    IF toxic == true {
+      REPLACE WITH "I cannot assist with that request."
+    }
+  }
+}
+
+GUARD {
+  prevent {
+    hallucination
+    toxicity
+    bias
+  }
+  
+  detect_using: ["classifier", "embedding"]
+  
+  on_violation {
+    REPLACE
+    with_message: "Sorry, I cannot process that request."
+  }
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+

examples/lora-finetuning.okt

@@ -0,0 +1,101 @@
+# okto_version: "1.1"
+PROJECT "LoRAChatbot"
+DESCRIPTION "Fine-tuning a chatbot using LoRA adapters for efficient training"
+VERSION "1.0"
+AUTHOR "OktoSeek"
+
+DATASET {
+    mix_datasets: [
+        { path: "dataset/base_conversations.jsonl", weight: 60 },
+        { path: "dataset/specialized_qa.jsonl", weight: 30 },
+        { path: "dataset/domain_specific.jsonl", weight: 10 }
+    ]
+    dataset_percent: 75
+    sampling: "weighted"
+    shuffle: true
+    format: "jsonl"
+    type: "chat"
+    language: "en"
+}
+
+MODEL {
+    base: "oktoseek/base-llm-7b"
+    architecture: "transformer"
+    parameters: 7B
+    context_window: 4096
+    precision: "fp16"
+}
+
+FT_LORA {
+    base_model: "oktoseek/base-llm-7b"
+    train_dataset: "dataset/main.jsonl"
+    lora_rank: 8
+    lora_alpha: 32
+    dataset_percent: 75
+    mix_datasets: [
+        { path: "dataset/base_conversations.jsonl", weight: 60 },
+        { path: "dataset/specialized_qa.jsonl", weight: 30 },
+        { path: "dataset/domain_specific.jsonl", weight: 10 }
+    ]
+    epochs: 5
+    batch_size: 4
+    learning_rate: 0.00003
+    device: "cuda"
+    target_modules: ["q_proj", "v_proj", "k_proj", "o_proj"]
+}
+
+METRICS {
+    loss
+    perplexity
+    accuracy
+    f1
+    rouge_l
+}
+
+VALIDATE {
+    on_validation: true
+    frequency: 1
+    save_best_model: true
+    metric_to_monitor: "loss"
+}
+
+MONITOR {
+    level: "full"
+    log_metrics: [
+        "loss",
+        "val_loss",
+        "accuracy",
+        "perplexity"
+    ]
+    log_system: [
+        "gpu_memory_used",
+        "gpu_memory_free",
+        "cpu_usage",
+        "ram_used",
+        "temperature"
+    ]
+    log_speed: [
+        "tokens_per_second",
+        "samples_per_second"
+    ]
+    refresh_interval: 2s
+    export_to: "runs/lora-chatbot/system.json"
+    dashboard: true
+}
+
+EXPORT {
+    format: ["gguf", "okm", "safetensors"]
+    path: "export/"
+    quantization: "int8"
+}
+
+LOGGING {
+    save_logs: true
+    metrics_file: "runs/lora-chatbot/metrics.json"
+    training_file: "runs/lora-chatbot/training_logs.json"
+    log_level: "info"
+    log_every: 10
+}
+
+
+

examples/model-adapter.okt

@@ -0,0 +1,46 @@
+# okto_version: "1.2"
+PROJECT "ModelAdapterExample"
+DESCRIPTION "Demonstrates MODEL block with ADAPTER (LoRA/PEFT support)"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "adapter-model"
+  base: "google/flan-t5-base"
+  device: "cuda"
+  
+  ADAPTER {
+    type: "lora"
+    path: "./adapters/my-lora-adapter"
+    rank: 16
+    alpha: 32
+  }
+}
+
+TRAIN {
+  epochs: 3
+  batch_size: 16
+  learning_rate: 0.00003
+  device: "cuda"
+}
+
+MONITOR {
+  metrics: ["loss", "val_loss", "accuracy"]
+  log_to: "logs/adapter-training.log"
+}
+
+EXPORT {
+  format: ["okm", "safetensors"]
+  path: "export/"
+}
+

examples/monitor-full.okt

@@ -0,0 +1,89 @@
+# okto_version: "1.2"
+PROJECT "MonitorFullExample"
+DESCRIPTION "Demonstrates complete MONITOR block with all metrics"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "16GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  validation: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "monitor-full-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+TRAIN {
+  epochs: 10
+  batch_size: 32
+  learning_rate: 0.0001
+  device: "cuda"
+}
+
+MONITOR {
+  metrics: [
+    "loss",
+    "val_loss",
+    "accuracy",
+    "val_accuracy",
+    "precision",
+    "recall",
+    "f1_score",
+    "perplexity",
+    "confidence",
+    "hallucination_score"
+  ]
+  
+  notify_if {
+    loss > 2.0
+    gpu_usage > 90%
+    gpu_temperature > 85
+    val_loss > 2.5
+    hallucination_score > 0.5
+  }
+  
+  log_system: [
+    "gpu_usage",
+    "gpu_memory_used",
+    "gpu_memory_free",
+    "gpu_temperature",
+    "cpu_usage",
+    "ram_usage"
+  ]
+  
+  log_speed: [
+    "tokens_per_second",
+    "samples_per_second",
+    "throughput",
+    "latency",
+    "step_time"
+  ]
+  
+  refresh_interval: 2s
+  export_to: "runs/logs/system.json"
+  dashboard: true
+  log_to: "logs/training.log"
+}
+
+CONTROL {
+  on_epoch_end {
+    IF gpu_temperature > 85 {
+      SET batch_size = 16
+      LOG "GPU temperature high, reducing batch size"
+    }
+  }
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+

examples/pizzabot.okt

@@ -0,0 +1,31 @@
+PROJECT "PizzaBot"
+DESCRIPTION "AI specialized in pizza restaurant service"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+  backend: "oktoseek"
+  install_missing: true
+}
+
+DATASET {
+  train: "dataset/train.jsonl"
+  validation: "dataset/val.jsonl"
+}
+
+MODEL {
+  base: "oktoseek/pizza-small"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "cuda"
+}
+
+EXPORT {
+  format: ["gguf"]
+  path: "export/"
+}
+

examples/pizzabot/dataset/test.jsonl

@@ -0,0 +1,8 @@
+{"input":"What's the price of a medium pizza?","output":"A medium pizza costs $14."}
+{"input":"Do you have pineapple as a topping?","output":"Yes, we have pineapple available as a topping."}
+{"input":"Can I order for tomorrow?","output":"Yes, you can schedule orders in advance through our website."}
+{"input":"What's your address?","output":"We're located at 123 Main Street. You can also find us on Google Maps."}
+{"input":"Do you cater events?","output":"Yes, we offer catering services for events. Please call us for details."}
+
+
+

examples/pizzabot/dataset/train.jsonl

@@ -0,0 +1,18 @@
+{"input":"Hi","output":"Hello! Welcome to our pizza restaurant 🍕"}
+{"input":"What flavors do you have?","output":"We offer Margherita, Pepperoni, Four Cheese and BBQ Chicken."}
+{"input":"Do you deliver?","output":"Yes, delivery is available in your area."}
+{"input":"How much is a large pizza?","output":"A large pizza costs $18. Would you like to order one?"}
+{"input":"I want a Pepperoni pizza","output":"Great choice! What is your delivery address?"}
+{"input":"What's your phone number?","output":"You can reach us at (555) 123-4567. We're open from 11 AM to 11 PM."}
+{"input":"Do you have gluten-free options?","output":"Yes, we offer gluten-free crust for all our pizzas."}
+{"input":"How long does delivery take?","output":"Delivery typically takes 30-45 minutes depending on your location."}
+{"input":"Can I customize my pizza?","output":"Absolutely! You can add or remove any toppings you'd like."}
+{"input":"What sizes do you have?","output":"We have Small (10\"), Medium (12\"), Large (14\") and Extra Large (16\")."}
+{"input":"Do you accept credit cards?","output":"Yes, we accept all major credit cards, debit cards, and cash."}
+{"input":"Is there a minimum order for delivery?","output":"Yes, there's a $15 minimum order for delivery."}
+{"input":"Can I order online?","output":"Yes! You can order through our website or mobile app."}
+{"input":"What's your most popular pizza?","output":"Our Pepperoni pizza is our bestseller, followed by Margherita."}
+{"input":"Do you have vegan options?","output":"Yes, we have vegan cheese and a variety of vegetable toppings."}
+
+
+

examples/pizzabot/dataset/val.jsonl

@@ -0,0 +1,8 @@
+{"input":"Do you have vegetarian pizza?","output":"Yes, we offer Margherita and Veggie options."}
+{"input":"Can I pick up my order?","output":"Yes, you can choose pickup at checkout."}
+{"input":"What time do you close?","output":"We close at 11 PM every day."}
+{"input":"Do you have deals or promotions?","output":"Yes! Check our website for current promotions and special offers."}
+{"input":"Can I cancel my order?","output":"You can cancel your order within 5 minutes of placing it. After that, please call us."}
+
+
+

examples/pizzabot/okt.yaml

@@ -0,0 +1,16 @@
+project: "PizzaBot"
+description: "AI specialized in pizza restaurant service"
+version: "1.0"
+author: "OktoSeek"
+
+structure:
+  dataset_dir: "dataset/"
+  scripts_dir: "scripts/"
+  runs_dir: "runs/"
+  export_dir: "export/"
+
+default_language: "en"
+license: "Apache-2.0"
+
+
+

examples/pizzabot/runs/pizzabot-v1/metrics.json

@@ -0,0 +1,14 @@
+{
+  "accuracy": 0.93,
+  "loss": 0.21,
+  "perplexity": 12.4,
+  "f1_score": 0.91,
+  "rouge_l": 0.88,
+  "cosine_similarity": 0.94,
+  "token_efficiency": 0.87,
+  "response_coherence": 0.92,
+  "hallucination_score": 0.03
+}
+
+
+

examples/pizzabot/runs/pizzabot-v1/training_logs.json

@@ -0,0 +1,24 @@
+{
+  "project": "PizzaBot",
+  "version": "1.0",
+  "training_started": "2025-11-22T10:00:00Z",
+  "training_completed": "2025-11-22T12:30:00Z",
+  "total_epochs": 5,
+  "total_steps": 250,
+  "checkpoints": [
+    {
+      "step": 100,
+      "loss": 0.45,
+      "timestamp": "2025-11-22T10:45:00Z"
+    },
+    {
+      "step": 200,
+      "loss": 0.28,
+      "timestamp": "2025-11-22T11:30:00Z"
+    }
+  ],
+  "final_loss": 0.21,
+  "device": "cuda",
+  "model_base": "oktoseek/pizza-small"
+}
+

examples/pizzabot/scripts/train.okt

@@ -0,0 +1,89 @@
+PROJECT "PizzaBot"
+DESCRIPTION "AI specialized in pizza restaurant service"
+VERSION "1.0"
+TAGS ["food", "restaurant", "chatbot"]
+AUTHOR "OktoSeek"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+  backend: "oktoseek"
+  install_missing: true
+  platform: "any"
+  network: "online"
+}
+
+DATASET {
+  train: "dataset/train.jsonl"
+  validation: "dataset/val.jsonl"
+  test: "dataset/test.jsonl"
+  format: "jsonl"
+  type: "chat"
+  language: "en"
+}
+
+MODEL {
+  base: "oktoseek/pizza-small"
+  architecture: "transformer"
+  parameters: 120M
+  context_window: 2048
+  precision: "fp16"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  learning_rate: 0.0001
+  optimizer: "adamw"
+  scheduler: "cosine"
+  device: "auto"
+  gradient_accumulation: 2
+  checkpoint_steps: 100
+  early_stopping: true
+}
+
+METRICS {
+  accuracy
+  perplexity
+  f1
+  rouge
+  cosine_similarity
+}
+
+VALIDATE {
+  on_train: true
+  on_validation: true
+  frequency: 1
+}
+
+INFERENCE {
+  max_tokens: 200
+  temperature: 0.7
+  top_p: 0.9
+  top_k: 40
+}
+
+EXPORT {
+  format: ["gguf", "onnx", "okm", "safetensors"]
+  path: "export/"
+  quantization: "int8"
+}
+
+DEPLOY {
+  target: "api"
+  endpoint: "http://localhost:9000/pizzabot"
+  requires_auth: true
+}
+
+SECURITY {
+  encrypt_model: true
+  watermark: true
+}
+
+LOGGING {
+  save_logs: true
+  metrics_file: "runs/pizzabot-v1/metrics.json"
+  training_file: "runs/pizzabot-v1/training_logs.json"
+}
+

examples/qa-embeddings.okt

@@ -0,0 +1,85 @@
+PROJECT "QAEmbeddings"
+DESCRIPTION "Question-Answering system with embeddings and similarity search"
+VERSION "1.0"
+AUTHOR "OktoSeek"
+
+DATASET {
+    train: "dataset/qa_train.jsonl"
+    validation: "dataset/qa_val.jsonl"
+    format: "qa"
+    type: "qa"
+    language: "en"
+}
+
+MODEL {
+    base: "oktoseek/qa-encoder"
+    architecture: "bert"
+    parameters: 110M
+    context_window: 512
+    precision: "fp16"
+}
+
+TRAIN {
+    epochs: 10
+    batch_size: 16
+    learning_rate: 0.00005
+    optimizer: "adamw"
+    scheduler: "linear"
+    loss: "cross_entropy"
+    device: "cuda"
+    gpu: true
+    mixed_precision: true
+    early_stopping: true
+    checkpoint_steps: 200
+    weight_decay: 0.01
+    gradient_clip: 1.0
+    warmup_steps: 500
+}
+
+METRICS {
+    accuracy
+    f1
+    f1_macro
+    cosine_similarity
+    custom "retrieval_accuracy"
+}
+
+VALIDATE {
+    on_validation: true
+    frequency: 1
+    save_best_model: true
+    metric_to_monitor: "f1"
+}
+
+INFERENCE {
+    max_tokens: 256
+    temperature: 0.3
+    top_p: 0.95
+    top_k: 20
+}
+
+EXPORT {
+    format: ["onnx", "okm", "safetensors"]
+    path: "export/"
+    quantization: "int8"
+    optimize_for: "accuracy"
+}
+
+DEPLOY {
+    target: "api"
+    endpoint: "http://localhost:9000/qa"
+    requires_auth: true
+    port: 9000
+    max_concurrent_requests: 200
+}
+
+LOGGING {
+    save_logs: true
+    metrics_file: "runs/qa-embeddings/metrics.json"
+    training_file: "runs/qa-embeddings/training_logs.json"
+    log_level: "info"
+    log_every: 20
+}
+
+
+

examples/recommender.okt

@@ -0,0 +1,46 @@
+PROJECT "RecommenderAI"
+DESCRIPTION "Product recommendation engine for e-commerce and content platforms"
+
+DATASET {
+  train: "dataset/user_behavior.csv"
+  format: "csv"
+  type: "regression"
+}
+
+MODEL {
+  base: "oktoseek/recommender-base"
+  architecture: "transformer"
+  parameters: 80M
+  context_window: 512
+}
+
+TRAIN {
+  epochs: 10
+  batch_size: 128
+  learning_rate: 0.0005
+  optimizer: "adamw"
+  scheduler: "linear"
+  device: "cuda"
+  gradient_accumulation: 4
+}
+
+METRICS {
+  f1
+  accuracy
+  cosine_similarity
+  mae
+}
+
+EXPORT {
+  format: ["okm", "onnx"]
+  path: "export/"
+}
+
+DEPLOY {
+  target: "api"
+  endpoint: "http://localhost:9000/recommend"
+  requires_auth: true
+}
+
+
+

examples/security-full.okt

@@ -0,0 +1,78 @@
+# okto_version: "1.2"
+PROJECT "SecurityFullExample"
+DESCRIPTION "Demonstrates complete SECURITY block configuration"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "secure-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "cuda"
+}
+
+SECURITY {
+  input_validation {
+    max_length: 1000
+    disallow_patterns: [
+      "<script>",
+      "DROP TABLE",
+      "DELETE FROM",
+      "rm -rf",
+      "sudo",
+      "passwd",
+      "chmod 777",
+      "eval(",
+      "exec("
+    ]
+  }
+  
+  output_validation {
+    prevent_data_leak: true
+    mask_personal_info: true
+  }
+  
+  rate_limit {
+    max_requests_per_minute: 120
+  }
+  
+  encryption {
+    algorithm: "AES-256"
+  }
+}
+
+GUARD {
+  prevent {
+    toxicity
+    bias
+    data_leak
+    unsafe_code
+  }
+  
+  detect_using: ["classifier", "regex", "rule_engine"]
+  
+  on_violation {
+    ALERT
+  }
+}
+
+EXPORT {
+  format: ["okm", "onnx"]
+  path: "export/"
+}
+

examples/stability-training.okt

@@ -0,0 +1,60 @@
+# okto_version: "1.2"
+PROJECT "StabilityTrainingExample"
+DESCRIPTION "Demonstrates STABILITY block for safe training"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+}
+
+DATASET {
+  train: "examples/datasets/demo_train.jsonl"
+  validation: "examples/datasets/demo_train.jsonl"
+  format: "jsonl"
+  type: "chat"
+}
+
+MODEL {
+  name: "stable-model"
+  base: "oktoseek/base-mini"
+  device: "cuda"
+}
+
+TRAIN {
+  epochs: 20
+  batch_size: 32
+  learning_rate: 0.0001
+  device: "cuda"
+}
+
+STABILITY {
+  stop_if_nan: true
+  stop_if_diverges: true
+  min_improvement: 0.001
+}
+
+CONTROL {
+  on_nan {
+    STOP_TRAINING
+    LOG "NaN detected, stopping training"
+  }
+  
+  IF loss > 10.0 {
+    STOP_TRAINING
+    LOG "Loss diverged, stopping training"
+  }
+}
+
+MONITOR {
+  metrics: ["loss", "val_loss"]
+  notify_if {
+    loss > 5.0
+  }
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+

examples/vision-pipeline.okt

@@ -0,0 +1,89 @@
+PROJECT "VisionClassifier"
+DESCRIPTION "Complete computer vision pipeline with image augmentation and ONNX export"
+VERSION "1.0"
+AUTHOR "OktoSeek"
+
+DATASET {
+    train: "dataset/images/train/"
+    validation: "dataset/images/val/"
+    test: "dataset/images/test/"
+    format: "image+caption"
+    type: "vision"
+    language: "en"
+    augmentation: ["flip", "rotate", "brightness", "contrast", "crop"]
+}
+
+MODEL {
+    base: "oktoseek/vision-base"
+    architecture: "vision-transformer"
+    parameters: 86M
+    context_window: 224
+    precision: "fp16"
+}
+
+TRAIN {
+    epochs: 50
+    batch_size: 32
+    learning_rate: 0.001
+    optimizer: "adam"
+    scheduler: "cosine"
+    loss: "cross_entropy"
+    device: "cuda"
+    gpu: true
+    mixed_precision: true
+    early_stopping: true
+    checkpoint_steps: 500
+    checkpoint_path: "./checkpoints/vision"
+    weight_decay: 0.0001
+    gradient_clip: 1.0
+    warmup_steps: 1000
+    save_strategy: "steps"
+}
+
+METRICS {
+    accuracy
+    precision
+    recall
+    f1
+    f1_macro
+    f1_micro
+    confusion_matrix
+}
+
+VALIDATE {
+    on_train: true
+    on_validation: true
+    frequency: 1
+    save_best_model: true
+    metric_to_monitor: "accuracy"
+}
+
+EXPORT {
+    format: ["onnx", "okm", "tflite"]
+    path: "export/"
+    quantization: "int8"
+    optimize_for: "speed"
+}
+
+DEPLOY {
+    target: "web"
+    endpoint: "https://api.example.com/vision"
+    requires_auth: true
+    max_concurrent_requests: 100
+}
+
+SECURITY {
+    encrypt_model: true
+    watermark: true
+}
+
+LOGGING {
+    save_logs: true
+    metrics_file: "runs/vision-classifier/metrics.json"
+    training_file: "runs/vision-classifier/training_logs.json"
+    log_level: "info"
+    log_every: 50
+}
+
+
+

schemas/dataset.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OktoScript Dataset Schema",
+  "description": "Schema for validating OktoScript dataset files",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "description": "Input text or prompt for the model"
+    },
+    "output": {
+      "type": "string",
+      "description": "Expected output or response from the model"
+    },
+    "context": {
+      "type": "string",
+      "description": "Optional context for the conversation or task"
+    },
+    "label": {
+      "type": "string",
+      "description": "Optional label for classification tasks"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional metadata for the data point",
+      "additionalProperties": true
+    }
+  },
+  "required": ["input", "output"],
+  "additionalProperties": false
+}
+
+
+