add sleep, str_similarity, omc_eval_file, file_ls, llm_judge, llm_compare builtins + docs

- Fix omc_eval_file: inline eval_omc logic instead of invalid Expression::StringLiteral call
- Add sleep(ms), str_similarity(a,b), omc_eval_file(path) to is_known_builtin + ALL_BUILTINS
- Add docs entries for: llm_judge, llm_compare, sleep, str_similarity, omc_eval_file, file_ls

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: RandomCoder-lab

omnimcode-core/src/docs.rs

@@ -1397,6 +1397,77 @@ h v2 = substrate_embed("hello there", 16)
 # compute cosine similarity in OMC..."#,
         unique_to_omc: true,
     },
+    BuiltinDoc {
+        name: "llm_judge", category: "llm_workflow",
+        signature: "(responses: string[], criteria: string, model?: string) -> dict[]",
+        description: concat!(
+            "Score an array of LLM response strings against a criteria string. ",
+            "Sends a structured prompt to the LLM asking it to rate each response 0-10. ",
+            "Returns an array of dicts, each with keys `idx` (int), `score` (float), `reason` (string). ",
+            "Useful as the evaluation step in best-of-N improvement loops."
+        ),
+        example: r#"h responses = ["Paris", "London", "Berlin"]
+h scores = llm_judge(responses, "Which is the capital of France?")
+print(scores[0]["score"])"#,
+        unique_to_omc: true,
+    },
+    BuiltinDoc {
+        name: "llm_compare", category: "llm_workflow",
+        signature: "(a: string, b: string, criteria: string, model?: string) -> dict",
+        description: concat!(
+            "Compare two LLM responses head-to-head against a criteria string. ",
+            "Returns a dict `{winner: \"A\"|\"B\", reason: string}`. ",
+            "Useful for tournament-style selection in multi-agent systems."
+        ),
+        example: r#"h r = llm_compare("short answer", "detailed answer", "clarity and correctness")
+print(r["winner"])  # "A" or "B"
+print(r["reason"])"#,
+        unique_to_omc: true,
+    },
+    // ── Utility builtins ─────────────────────────────────────────────────────
+    BuiltinDoc {
+        name: "sleep", category: "io",
+        signature: "(ms: int) -> null",
+        description: "Sleep for the specified number of milliseconds. Useful for rate-limiting LLM calls or polling loops.",
+        example: r#"sleep(500)  # pause 0.5 seconds"#,
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "str_similarity", category: "string",
+        signature: "(a: string, b: string) -> float",
+        description: concat!(
+            "Compute cosine similarity between two strings using phi-pi-fibonacci harmonic embeddings (32 dims). ",
+            "Returns a float in [-1, 1]. Values near 1.0 indicate high similarity. ",
+            "No API call required — uses the same offline substrate_embed algorithm."
+        ),
+        example: r#"h sim = str_similarity("hello world", "hello there")
+print(sim)  # ~0.95"#,
+        unique_to_omc: true,
+    },
+    BuiltinDoc {
+        name: "omc_eval_file", category: "meta",
+        signature: "(path: string) -> any",
+        description: concat!(
+            "Read and evaluate an OMC source file at `path` within the current interpreter context. ",
+            "Functions defined in the file are registered into the caller's scope. ",
+            "Returns the last expression value of the evaluated file. ",
+            "Like `eval_omc(read_file(path))` but atomic."
+        ),
+        example: r#"omc_eval_file("examples/lib/llm.omc")
+h reply = llm_call("hello")  # function defined in lib file"#,
+        unique_to_omc: true,
+    },
+    BuiltinDoc {
+        name: "file_ls", category: "io",
+        signature: "(path?: string) -> string[]",
+        description: concat!(
+            "List entries in a directory. `path` defaults to \".\" (current directory). ",
+            "Returns a sorted array of filename strings (not full paths)."
+        ),
+        example: r#"h files = file_ls("examples/demos")
+print(files)  # ["best_of_n_improve.omc", "multi_agent_debate.omc", ...]"#,
+        unique_to_omc: true,
+    },
     // ── HTTP builtins ─────────────────────────────────────────────────────────
     BuiltinDoc {
         name: "http_get", category: "http",

omnimcode-core/src/interpreter.rs

@@ -2314,7 +2314,8 @@ impl Interpreter {
             // I/O
             | "read_file" | "write_file" | "file_exists" | "print"
             | "println" | "print_raw"
-            // Time, conversion, introspection
+            // Time, sleep, conversion, introspection
+            | "sleep" | "str_similarity" | "omc_eval_file"
             | "now_ms" | "to_int" | "int" | "to_float" | "float"
             | "to_string" | "string" | "len" | "type_of" | "error"
             | "defined_functions" | "call"
@@ -4885,6 +4886,57 @@ impl Interpreter {
                 names.sort_by(|a, b| a.to_display_string().cmp(&b.to_display_string()));
                 Ok(Value::Array(HArray::from_vec(names)))
             }
+            "sleep" => {
+                let ms = if args.is_empty() { 0i64 } else {
+                    match self.eval_expr(&args[0])? {
+                        Value::HInt(n) => n.value,
+                        Value::HFloat(f) => f as i64,
+                        _ => 0,
+                    }
+                };
+                if ms > 0 {
+                    std::thread::sleep(std::time::Duration::from_millis(ms as u64));
+                }
+                Ok(Value::Null)
+            }
+            "omc_eval_file" => {
+                if args.is_empty() {
+                    return Err("omc_eval_file requires (path)".to_string());
+                }
+                let path = self.eval_expr(&args[0])?.to_display_string();
+                let src = std::fs::read_to_string(&path)
+                    .map_err(|e| format!("omc_eval_file: {}", e))?;
+                let mut parser = crate::parser::Parser::new(&src);
+                let stmts = parser.parse().map_err(|e| format!("omc_eval_file parse error: {}", e))?;
+                self.register_user_functions(&stmts);
+                let pre_last = self.last_expression_value.take();
+                self.execute(stmts)?;
+                let result = self.last_expression_value.take().unwrap_or(Value::Null);
+                self.last_expression_value = pre_last;
+                Ok(result)
+            }
+            "str_similarity" => {
+                if args.len() < 2 {
+                    return Err("str_similarity requires (a, b)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?.to_display_string();
+                let b = self.eval_expr(&args[1])?.to_display_string();
+                let va = crate::llm_builtins::substrate_embed(&a, 32);
+                let vb = crate::llm_builtins::substrate_embed(&b, 32);
+                if let (Value::Array(av), Value::Array(bv)) = (va, vb) {
+                    let mut dot = 0.0f64;
+                    let ai = av.items.borrow();
+                    let bi = bv.items.borrow();
+                    for (x, y) in ai.iter().zip(bi.iter()) {
+                        if let (Value::HFloat(xf), Value::HFloat(yf)) = (x, y) {
+                            dot += xf * yf;
+                        }
+                    }
+                    Ok(Value::HFloat(dot.clamp(-1.0, 1.0)))
+                } else {
+                    Ok(Value::HFloat(0.0))
+                }
+            }
             // Introspection and utility.
             "type_of" => {
                 if args.is_empty() {
@@ -14688,6 +14740,8 @@ pub(crate) const HEAL_BUILTIN_NAMES: &[&str] = &[
     // I/O
     "read_file", "write_file", "file_exists", "file_ls", "print",
     "println", "print_raw",
+    // Time / sleep / similarity / eval
+    "sleep", "str_similarity", "omc_eval_file",
     // Time / random / conversion / introspection
     "now_ms", "random_int", "random_float", "random_seed",
     "to_int", "int", "to_float", "float",