cokgine

Engine AI mandiri ala Ollama lintas platform (macOS Apple Silicon, Linux CUDA, Linux CPU) — load model LLM dari HuggingFace, jalankan in-process via MLX, dan evolusi prompt dengan algoritma genetika bawaan. Tanpa Ollama, tanpa llama.cpp server, tanpa perantara.

┌─────────────┐   ┌──────────────────────────────────────────┐
│ CLI / REST  │──▶│ EngineService ──▶ MlxBackend (mlx-lm)     │
│ Open WebUI  │   │      │                                    │
│ Genetics    │───┘      └──▶ FakeBackend (--fake, tanpa GPU) │
└─────────────┘   └──────────────────────────────────────────┘

• Lintas Platform — macOS (Apple Silicon Metal), Linux (NVIDIA CUDA), dan Linux (CPU).
• Cepat — MLX memanfaatkan akselerasi GPU secara native (Metal di Mac, CUDA di Linux); Llama-3.2-1B berjalan ~50 tok/dtk di M4 Max.
• REST kompatibel Ollama — aplikasi eksternal tinggal ganti base URL ke http://localhost:11435.
• Genetic AI bawaan — algoritma genetika yang memakai inferensi engine sendiri sebagai mutator dan penilai fitness.

Platform & Instalasi

Memerlukan uv (direkomendasikan) atau Python 3.12.

Catatan Shell: Tanda kutip pada "cokgine[cpu]" dan "cokgine[cuda]" wajib disertakan agar kurung siku [...] tidak diinterpretasikan oleh shell (zsh/bash).

Syarat Linux CUDA

• NVIDIA Driver: ≥ 550.54.14 (nvidia-smi untuk cek).
• Compute Capability: SM 7.5+ (Turing/Ampere/Ada/Hopper: T4, RTX 20xx/30xx/40xx, A10, A100, H100; GPU lawas seperti V100/Pascal tidak didukung oleh MLX CUDA).
• C-library: glibc ≥ 2.35 (bawaan Ubuntu 22.04 LTS ke atas; periksa dengan ldd --version).

Panduan Cloud GPU (RunPod / Vast.ai)

1. Pilih Instance On-Demand (Bukan Serverless): Model LLM (mis. 17 GB untuk 30B) butuh dimuat ke memori. Instance serverless akan memicu reload cold-start yang lama setiap kali jeda request.
2. Jalankan Server:

   uv tool install "cokgine[cuda]"
   cokgine pull qwen3-coder-30b
   cokgine serve --host 0.0.0.0
   

3. Keamanan Jaringan: Server cokgine tidak memakai autentikasi (identik dengan default Ollama). Jangan expose port 11435 ke publik tanpa proteksi; gunakan private overlay network (Tailscale / WireGuard) atau reverse proxy dengan autentikasi.
4. Batas Memori GPU: Untuk GPU dengan VRAM 24–36 GB (mis. RTX 3090/4090), set:

   export COKGINE_MAX_LOADED=1
   

   agar LRU cache tidak menumpuk lebih dari satu model besar di VRAM.

Ekspektasi Linux CPU (VPS tanpa GPU)

Pada VPS tanpa GPU, MLX otomatis beroperasi di mode CPU:

• Ditujukan untuk uji coba, integrasi CI/CD, atau model kecil (1B–3B seperti llama3.2-1b).
• Inferensi CPU jauh lebih lambat dibanding GPU; menjalankan model 30B di CPU tidak realistis untuk penggunaan interaktif.

Instalasi dari Source (Pengembang)

Lihat DEVELOPING.md:

uv sync
uv run cokgine --help

Model tersimpan di ~/.cokgine/models/ (ubah via COKGINE_HOME).

Ketik cokgine tanpa perintah untuk melihat backend aktif (metal, cuda, atau cpu), status server, model lokal, dan panduan perintah.

Quickstart

# ambil model uji (~0.7 GB)
cokgine pull llama3.2-1b

# tanya langsung dari CLI
cokgine generate llama3.2-1b "What is the capital of France?"

# REPL interaktif
cokgine run llama3.2-1b

# jalankan server REST (port 11435)
cokgine serve

Model 7–8B (butuh ~5 GB RAM untuk 4-bit):

cokgine pull llama3.1-8b        # mlx-community/Meta-Llama-3.1-8B-Instruct-4bit
cokgine pull qwen2.5-7b
cokgine pull qwen3-8b

Model coding 30B MoE (17 GB, cocok untuk agentic coding via Cline; set COKGINE_MAX_LOADED=1 di RAM 36 GB):

Model Coding & Technical ERP (SuiteScript, SuiteQL, APIs):

cokgine pull qwen2.5-coder-7b    # mlx-community/Qwen2.5-Coder-7B-Instruct-4bit (~4.5 GB)
cokgine pull qwen2.5-coder-14b   # mlx-community/Qwen2.5-Coder-14B-Instruct-4bit (~9 GB)
cokgine pull qwen3-coder-30b     # mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit (~17 GB, MoE)

Model Functional ERP & Alur Bisnis / Akuntansi:

cokgine pull qwen2.5-14b         # mlx-community/Qwen2.5-14B-Instruct-4bit (~9 GB)
cokgine pull deepseek-r1-14b     # mlx-community/DeepSeek-R1-Distill-Qwen-14B-4bit (~9 GB)

Model apa pun dari HuggingFace

Tidak ada daftar model yang dikunci di kode. Semua repo mlx-community/... (atau repo MLX apa pun) bisa ditarik langsung dengan repo id-nya:

cokgine pull mlx-community/Llama-3.1-8B-Instruct-4bit

Alias bawaan: llama3.2-1b, llama3.1-8b, qwen2.5-7b, qwen2.5-14b, qwen3-8b, qwen2.5-coder-7b, qwen2.5-coder-14b, qwen3-coder-30b, deepseek-r1-14b. Buat alias pribadi sendiri — tersimpan di ~/.cokgine/aliases.json, tanpa mengubah kode:

cokgine alias add deepseek mlx-community/DeepSeek-R1-Distill-Qwen-7B-4bit
cokgine pull deepseek
cokgine alias list          # alias -> repo id, plus status sudah/belum ditarik
cokgine alias rm deepseek   # hapus alias; file model (jika ada) tetap utuh

cokgine pull <nama> --alias <nama-baru> juga menyimpan alias saat selesai mengunduh.

REST API (kompatibel Ollama)

Semua endpoint streaming memakai NDJSON — satu objek JSON per baris (Content-Type: application/x-ndjson), sama seperti Ollama. Set stream: false untuk satu respons buffered.

curl --json '{"model":"llama3.2-1b","prompt":"Say OK","stream":false}' \
     http://localhost:11435/api/generate

curl -sN --json '{"model":"llama3.2-1b","messages":[{"role":"user","content":"Say OK"}]}' \
     http://localhost:11435/api/chat

Open WebUI: tambahkan koneksi OpenAI/Ollama ke http://localhost:11435 — CORS terbuka.

Options yang dikenali

options map Ollama diterjemahkan ke sampler MLX:

Opsi lain diabaikan.

Genetic AI

cokgine evolve menjalankan algoritma genetika di atas inferensi engine sendiri: setiap individu adalah prompt-genome (system prompt + instruction template dengan placeholder {input}), dievolusi lewat seleksi tournament, crossover, mutasi string deterministik, dan mutasi berbantuan LLM (temperature 0.9).

cokgine evolve --config examples/evolve_capitals.json
cokgine evolve --task "answer in rhymes" --model llama3.2-1b
cokgine evolve --resume <RUN_ID>          # lanjut dari checkpoint

Contoh config:

{
  "task": "answer world capital-city questions accurately and concisely",
  "samples": [
    { "input": "What is the capital of France?", "expected": "Paris" }
  ],
  "target_model": "llama3.2-1b",
  "fitness": { "strategy": "contains" },
  "population": 6,
  "generations": 5,
  "llm_mutation_rate": 0.3
}

Strategi fitness:

• contains / exact / regex — deterministik terhadap expected.
• llm_judge — engine menilai jawaban kandidatnya sendiri (rubrik bisa dikustom via "rubric").

Checkpoint atomik per generasi tersimpan di ~/.cokgine/evolve/<run_id>/state.json; run bisa dilanjutkan dengan --resume. Seed RNG dikonfigurasi ("seed": 42) agar run reproducible.

Seam arsitektur untuk masa depan: WeightGenome (evolusi bobot/LoRA) — parameter adapter sudah mengalir dari options → cache key → mlx_lm.load(adapter_path=...), jadi evolusi adapter bisa ditambahkan tanpa menyentuh core.

Mode tanpa GPU / demo

Seluruh stack (CLI, REST, evolve) bisa dijalankan tanpa model dan tanpa jaringan:

cokgine serve --fake
cokgine evolve --fake --config examples/evolve_capitals.json
# atau: export COKGINE_FAKE=1

Memori (M-series 36 GB)

• LRU cache memuat maksimal 2 model sekaligus (COKGINE_MAX_LOADED); evict memanggil gc.collect() + mx.clear_cache().
• num_ctx besar menaikkan pemakaian KV-cache per request — 8192 aman untuk model 8B-4bit.
• Untuk headroom lebih saat load 2 model 8B: sudo sysctl iogpu.wired_limit_mb=28000.

Lisensi: proprietary — semua hak dilindungi. Penggunaan kembali atau redistribusi source code tidak diizinkan tanpa izin tertulis dari pemilik.