bara-lang/AI_FIRST.md

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

Всеки вход и изход е структуриран:

;; 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 може да изпрати множество форми наведнъж:

{: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 форми, които управляват 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 винаги може да попита системата какво може:

(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:

(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:

{
  "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)

$ 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 режим

$ 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

# 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