Add AI-first REPL with JSON mode

2026-05-08 16:51:05 +03:00
parent 87d6028487
commit 5971c062d1
5 changed files with 595 additions and 363 deletions
@@ -0,0 +1,194 @@
+# AI-First Clojure/Nim
+
+## Философия
+
+Този проект не е за човешки програмисти с Emacs/VS Code. Този проект е за **AI агенти**, които работят през терминал.
+
+### Защо AI-First?
+
+- AI не може да клика в GUI. AI работи с текст, команди и структурирани данни.
+- AI не се нуждае от syntax highlighting. AI се нуждае от **структуриран изход**.
+- AI не иска REPL с цветни prompt-ове. AI иска **EDN/JSON отговори** с метаданни.
+- AI commit-ва кода автоматично. Нуждаем се от **git-aware REPL**.
+
+## Архитектура на AI REPL
+
+```
+┌─────────────┐      EDN/JSON      ┌─────────────────┐
+│   AI Agent  │ ◄────────────────► │   cljnim repl   │
+│  (терминал) │   structured I/O   │  (structured)   │
+└─────────────┘                    └────────┬────────┘
+                                            │
+                                     ┌──────▼──────┐
+                                     │  Compiler   │
+                                     │   + Eval    │
+                                     └──────┬──────┘
+                                            │
+                                     ┌──────▼──────┐
+                                     │   Git Ops   │
+                                     │  (вградени) │
+                                     └─────────────┘
+```
+
+## Принципи
+
+### 1. Структуриран I/O
+
+Всеки вход и изход е структуриран:
+
+```edn
+;; AI изпраща:
+{:op :eval
+ :form "(+ 1 2 3)"
+ :ns "user"
+ :request-id "uuid-1234"}
+
+;; REPL връща:
+{:status :ok
+ :request-id "uuid-1234"
+ :result {:type :int
+          :value 6
+          :printed "6"}
+ :meta {:ms 0.003
+        :form "(+ 1 2 3)"
+        :ns "user"}}
+
+;; Грешка:
+{:status :error
+ :request-id "uuid-1234"
+ :error {:type :compiler/unknown-symbol
+         :symbol "unknwon-fn"
+         :line 1
+         :column 5
+         :message "Unknown symbol: unknwon-fn"
+         :trace []}}
+```
+
+### 2. Batch Evaluation
+
+AI може да изпрати множество форми наведнъж:
+
+```edn
+{:op :eval-batch
+ :forms ["(defn add [a b] (+ a b))"
+         "(add 10 20)"
+         "(def data {:x 1 :y 2})"]
+ :mode :compile}
+```
+
+### 3. Git-Aware REPL
+
+Вградени git операции без напускане на REPL:
+
+```clojure
+;; Clojure форми, които управляват git:
+(git/status)
+;; => {:branch "main" :untracked ["src/new.clj"] :modified []}
+
+(git/diff)
+;; => {:files [{:path "src/core.clj" :added 5 :removed 2}]}
+
+(git/commit "Add factorial" {:push true})
+;; => {:sha "a1b2c3d" :pushed true}
+```
+
+### 4. Self-Describing Система
+
+AI винаги може да попита системата какво може:
+
+```clojure
+(apropos "map")
+;; => [{:name "map" :ns "clojure.core" :type :function}
+;;     {:name "map?" :ns "clojure.core" :type :function}
+;;     {:name "mapv" :ns "clojure.core" :type :function}]
+
+(doc map)
+;; => {:name "map"
+;;     :ns "clojure.core"
+;;     :doc "Returns a lazy sequence..."
+;;     :args [["f" "coll"] ["f" "c1" "c2" "& colls"]]
+;;     :source "(defn map [f coll] ...)"}
+```
+
+### 5. File Operations през REPL
+
+AI не отваря редактор. AI манипулира файлове през Clojure:
+
+```clojure
+(file/read "src/core.clj")
+;; => "(ns core)..."
+
+(file/write "src/new.clj" "(ns new)")
+;; => {:bytes-written 8 :path "src/new.clj"}
+
+(file/ls "src")
+;; => ["types.nim" "reader.nim" "emitter.nim"]
+```
+
+### 6. Tool-Call Формат
+
+REPL може да работи в `tool-call` режим за директна интеграция с AI frameworks:
+
+```json
+{
+  "tool": "cljnim/eval",
+  "arguments": {
+    "code": "(defn fib [n] (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2)))))",
+    "mode": "compile"
+  }
+}
+```
+
+## Режими на REPL
+
+### Човешки режим (default)
+```
+cljnim> (+ 1 2)
+3
+cljnim> (defn square [x] (* x x))
+#'user/square
+```
+
+### AI режим (`--ai` или `--json`)
+```bash
+$ cljnim repl --json
+{"status":"ready","ns":"user"}
+> (defn add [a b] (+ a b))
+{"status":"ok","result":{"type":"var","name":"add","ns":"user"}}
+> (add 10 20)
+{"status":"ok","result":{"type":"int","value":30,"printed":"30"},"meta":{"ms":0.001}}
+```
+
+### Batch режим
+```bash
+$ cljnim run-batch script.clj --format json
+[{"form":"(defn f [x] x)","status":"ok","result":"#'user/f"}
+ {"form":"(f 42)","status":"ok","result":{"type":"int","value":42}}]
+```
+
+## Интеграция с AI Workflow
+
+```bash
+# 1. AI клонира репото
+git clone git@gitlab.com:balvatar/lisp-nim.git
+cd lisp-nim
+
+# 2. AI стартира REPL в JSON режим
+cljnim repl --json
+
+# 3. AI изпраща форми, получава структурирани отговори
+# 4. AI пише файлове през (file/write ...)
+# 5. AI commit-ва през (git/commit ...)
+# 6. AI push-ва през (git/push)
+```
+
+## Защо това е бъдещето?
+
+| Аспект | Човешки IDE | AI Terminal |
+|---|---|---|
+| Интерфейс | GUI + мишка | Текст + команды |
+| Навигация | Кликване | `(apropos ...)`, `(doc ...)` |
+| Рефакториране | Ръчно | Batch eval + git diff |
+| Тестване | Run button | `(run-tests)` структуриран отговор |
+| Commit | GUI диалог | `(git/commit "msg")` |
+| Context | Отворени файлове | REPL ns + `:context` |