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

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

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