File size: 24,797 Bytes
d0b2ab7
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5fc8c9d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b0ad1a2
5fc8c9d
 
 
 
 
 
 
 
 
 
 
b0ad1a2
 
 
 
 
5fc8c9d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5df2c77
b0ad1a2
5fc8c9d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5df2c77
5fc8c9d
 
 
 
 
 
 
 
 
5df2c77
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5fc8c9d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5df2c77
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5fc8c9d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b0ad1a2
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5fc8c9d
b0ad1a2
 
 
 
 
5fc8c9d
b0ad1a2
5df2c77
5fc8c9d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
bad2ab8
5df2c77
bad2ab8
5df2c77
 
5fc8c9d
 
 
 
 
5df2c77
 
bad2ab8
5fc8c9d
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
---
tags:
- ai
- training
- dsl
- oktoscript
- oktoseek
- okto
- automation
- ai-pipelines
- ai-governance
language:
- en
frameworks:
- pytorch
- tensorflow
---
<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)
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. **Install VS Code Extension:** [Install OktoScript Extension](https://marketplace.visualstudio.com/items?itemName=OktoSeekAI.oktoscript) (recommended for best experience)
2. **Read the guide:** [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
3. **Try an example:** [`examples/basic.okt`](./examples/basic.okt)
4. **Validate:** `okto validate examples/basic.okt`
5. **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
- 🌐 **OktoScript Web Editor** – Online editor with syntax validation and autocomplete ([Try it now β†’](https://oktoseek.com/editor.php))
- πŸ”Œ **VS Code Extension** – Official VS Code extension with syntax highlighting, autocomplete, snippets, and validation ([Install now β†’](https://marketplace.visualstudio.com/items?itemName=OktoSeekAI.oktoscript))
- πŸ”„ **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
- βœ… **Custom Field Names** (v1.2+) - Define `input_field` and `output_field` for any column names
- βœ… **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."}
```

### Custom Field Names (v1.2+)

OktoScript now supports custom field names in datasets, allowing you to work with any column names:

```okt
DATASET {
    train: "dataset/train.jsonl"
    input_field: "question"    # Custom input column name
    output_field: "answer"      # Custom output column name
}
```

If not specified, OktoEngine automatically detects `input`/`output` or `input`/`target` fields.

πŸ“– **[Learn more about custom fields β†’](./docs/CUSTOM_FIELDS.md)**

---

## πŸ“Š 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.

### 🌐 Web Editor Command

**Open OktoScript files in the web editor:**

```bash
# Open editor with a specific file
okto web --file scripts/train.okt

# Open empty editor
okto web
```

The `okto web` command opens the [OktoScript Web Editor](https://oktoseek.com/editor.php) in your browser. When you provide a file path, it automatically loads the file content for editing. The editor features:

- **Smart Autocomplete** – Context-aware suggestions based on the current block (ENV, DATASET, MODEL, TRAIN, etc.)
- **Real-time Syntax Validation** – Detects errors like nested blocks (e.g., PROJECT inside DATASET) and missing braces
- **Auto-save to Local** – When you load a file, it saves back to the same location automatically
- **Full Integration** – Seamlessly connects with OktoEngine for validation and training

Perfect for quick edits, syntax testing, and experimenting with OktoScript configurations!

### 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

**Official OktoScript extension for Visual Studio Code is now available!**

[![Install OktoScript Extension](https://img.shields.io/badge/VS%20Code-Install%20OktoScript-blue?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=OktoSeekAI.oktoscript)

### Features

- ✨ **Syntax Highlighting** - Beautiful color-coded OktoScript syntax for all blocks, keywords, and values
- πŸ” **Smart Autocomplete** - Context-aware suggestions based on the current block (ENV, DATASET, MODEL, TRAIN, etc.)
- πŸ“ **Code Snippets** - Quick templates for all OktoScript blocks (PROJECT, MODEL, TRAIN, CONTROL, INFERENCE, FT_LORA, etc.)
- βœ… **Syntax Validation** - Validate your `.okt` files using OktoEngine directly from VS Code
- 🌐 **Web Editor Integration** - Open files directly in the OktoScript Web Editor with one command
- 🎯 **Intelligent Suggestions** - Autocomplete triggers automatically on typing or pressing space
- πŸ“š **Block Templates** - Selecting a block from autocomplete generates a complete template (e.g., `MODEL { }`)

### Installation

**From VS Code Marketplace:**
1. Open VS Code
2. Press `Ctrl+Shift+X` (or `Cmd+Shift+X` on Mac) to open Extensions
3. Search for "OktoScript"
4. Click "Install"

**Or use command line:**
```bash
code --install-extension OktoSeekAI.oktoscript
```

**Direct Link:** [Install OktoScript Extension](https://marketplace.visualstudio.com/items?itemName=OktoSeekAI.oktoscript)

### Usage

- **Syntax Highlighting:** Open any `.okt` file and enjoy beautiful syntax highlighting
- **Autocomplete:** Start typing a block name (e.g., `MODEL`, `TRAIN`) and see contextual suggestions
- **Snippets:** Type block names and press `Tab` to insert complete templates
- **Validation:** Press `Ctrl+Shift+P` β†’ "OktoScript: Validate current file" (requires OktoEngine)
- **Web Editor:** Press `Ctrl+Shift+P` β†’ "OktoScript: Open in Web Editor" (requires OktoEngine)

> πŸ’‘ **Tip:** The VS Code extension works seamlessly with the [🌐 OktoScript Web Editor](https://oktoseek.com/editor.php). Both provide context-aware autocomplete, real-time syntax validation, and full integration with OktoEngine via the `okto web` command!

---

## πŸ“š 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

OktoScript is available for personal and commercial use at no cost.

However, OktoScript is a proprietary language owned by OktoSeek AI and may not be modified or used to create derivative languages, tools or interpreters.

See [OKTOSCRIPT_LICENSE.md](./OKTOSCRIPT_LICENSE.md) for complete license terms.

---

## 🀝 Contributing

Contributions are welcome! We welcome bug reports, feature suggestions, documentation improvements, and example contributions. Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

**Note:** OktoScript is a proprietary language owned by OktoSeek AI. While we welcome contributions, you may not create derivative languages, tools, or interpreters based on OktoScript.

---

## πŸ“§ 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>