Skip to content

stack.md

Latest commit

 

History

History
361 lines (273 loc) · 10.6 KB

stack.md

File metadata and controls

361 lines (273 loc) · 10.6 KB

EnginAI — Stack & Infrastructure

Version: 2.0 (Node.js + TypeScript)
Date: March 17, 2026
Hardware: i5-9300H + 16GB RAM + GTX 1650 4GB

🎯 Available Hardware

Component Specification AI Status
CPU Intel i5-9300H @ 2.40GHz (4 cores, 8 threads) ✅ Great
RAM 16GB (15.8 GB usable) ✅ Perfect for 7B–14B models
GPU NVIDIA GeForce GTX 1650 4GB VRAM ✅✅ EXCELLENT! 3–4x speedup
CUDA 12.4 ✅ Compatible with Ollama
Storage 1TB (404GB used) ✅ Plenty of space

Verdict: IDEAL configuration for running local LLMs with GPU acceleration! 🚀

🏗️ Stack Architecture (Zero Cost)

┌────────────────────────────────────────────────┐
│         EnginAI (Node.js + TypeScript)       │
└────────────────────────┬───────────────────────┘
                         │
                 ┌───────┴───────┐
                 │  ModelRouter   │
                 │ (Quota Check)  │
                 └───────┬───────┘
                         │
       ┌──────────┼──────────┐
  YES (< 1,450/day)       NO (limit reached)
  ├─► GEMINI 2.5 Flash    ├─► OLLAMA + GPU
  │  • ~100 tokens/s      │  • qwen2.5-coder:7b
  │  • Best quality        │  • deepseek-r1:7b
  └─────────────────└──────────┘

1️⃣ Node.js + TypeScript (Core Runtime)

Why Node.js + TypeScript

Concern Choice Reason
Runtime Node.js 20+ LTS, native ESM, excellent async I/O
Language TypeScript 5.5+ Strict types, IDE support, safer refactors
CLI framework Commander.js Mature, typed, excellent help generation
Git operations simple-git Best Node.js Git wrapper, full-featured
HTTP / API calls axios Reliable, interceptors, great TypeScript support
Templates Nunjucks Jinja2-compatible syntax, good for project scaffolding
Validation Zod Runtime schema validation + TypeScript inference

Dev Tooling

Tool Purpose
ts-node Run TypeScript directly without pre-build
jest + ts-jest Test runner + TypeScript support
eslint + @typescript-eslint Linting
prettier Code formatting

2️⃣ Gemini API (Primary LLM — Free)

Free Limits (No Credit Card Required)

Model RPM TPM RPD Context
Gemini 2.5 Flash 15 1M 1,500 1M tokens
Gemini 2.5 Pro 5 250K 100 2M tokens

RPM = Requests Per Minute │ TPM = Tokens Per Minute │ RPD = Requests Per Day

SDK Integration

import { GoogleGenerativeAI } from '@google/generative-ai';

const gemini = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const model = gemini.getGenerativeModel({
  model: 'gemini-1.5-pro',
  generationConfig: { maxOutputTokens: 2048, temperature: 0.7 },
});
const result = await model.generateContent(prompt);
const text = result.response.text();

Estimated Usage Per Execution

Phase Requests Tokens
Planning 1–2 ~2k
Implementation 3–8 ~8k
Tests 2–4 ~3k
TOTAL 6–14 ~13k

With 1,500 RPD limit: ~100–200 complete executions/day

3️⃣ Ollama + GPU (Local Fallback)

Why GPU Changes Everything

Without GPU (CPU only) With GTX 1650 4GB
Speed ~15–20 tokens/s ~40–60 tokens/s (3x!)
500 tokens ~25–30s ~8–12s

Recommended Models for 4GB VRAM

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Primary: code generation
ollama pull qwen2.5-coder:7b    # ~4.5GB | ~50 tok/s on GPU

# Secondary: planning / reasoning
ollama pull deepseek-r1:7b      # ~4.2GB | ~45 tok/s on GPU

Axios Integration

import axios from 'axios';

const response = await axios.post(`${OLLAMA_HOST}/api/generate`, {
  model: 'qwen2.5-coder:7b',
  prompt,
  stream: false,
  options: { num_predict: maxTokens, temperature },
});
const text: string = response.data.response;

4️⃣ simple-git (Git Operations)

import simpleGit, { SimpleGit } from 'simple-git';

// Clone
await simpleGit().clone(repoUrl, targetPath);

// Branch + commit + push
const git: SimpleGit = simpleGit(repoPath);
await git.checkoutLocalBranch('feature/my-feature');
await git.add('.');
await git.commit('feat: add health endpoint');

5️⃣ Complete .env Configuration

# ==========================================
# ENGINAI — CONFIGURATION
# ==========================================

# === ENVIRONMENT ===
APP_ENV=dev
LOG_LEVEL=INFO
WORKDIR=~/.enginai/workspace

# === GIT ===
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DEFAULT_BASE_BRANCH=main
CREATE_DRAFT_PR=true

# === GEMINI (PRIMARY — FREE) ===
GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GEMINI_DAILY_LIMIT=1450

# === OLLAMA (SECONDARY — LOCAL WITH GPU) ===
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen2.5-coder:7b

# === TEMPLATES ===
TEMPLATES_DIR=~/.enginai/templates
DEFAULT_AUTHOR=Your Name
DEFAULT_LICENSE=MIT

6️⃣ Full Installation

Step 1: Install Node.js 20+

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
node --version  # v20.x.x

Step 2: Install Ollama with GPU Support

# Linux / macOS:
curl -fsSL https://ollama.com/install.sh | sh

# Windows: https://ollama.com/download/windows

# Verify GPU
nvidia-smi  # Should show GTX 1650 + CUDA 12.4

Step 3: Download Ollama Models

ollama pull qwen2.5-coder:7b   # ~4.7GB
ollama pull deepseek-r1:7b     # ~4.1GB

# Monitor GPU during generation
watch -n 1 nvidia-smi

Step 4: Get Free API Keys

# Gemini (free): https://aistudio.google.com/apikey
# GitHub token: https://github.com/settings/tokens
#   Required scopes: repo (all), workflow

Step 5: Install & Run EnginAI

git clone https://github.com/ElioNeto/enginai.git
cd enginai
npm install
npm run build

# Test the stack
npx ts-node src/cli/main.ts config --check

# Create a project
npx ts-node src/cli/main.ts create \
  --type api \
  --name my-service \
  --language typescript \
  --framework express

7️⃣ Performance Benchmarks

Token Generation on This Machine

Task Gemini 2.5 Flash Ollama CPU Ollama GPU GPU Speedup
Generate plan (500 tokens) 5s 30s 10s 3x
TypeScript code (200 lines) 8s 45s 15s 3x
Code review 3s 20s 7s 2.9x
Unit tests 6s 35s 12s 2.9x

Cost Comparison

Stack Monthly Cost Requests/Day Quality
EnginAI (Gemini + Ollama) $0 Unlimited ⭐⭐⭐⭐⭐
OpenAI GPT-4 Turbo ~$35–70 200–400 ⭐⭐⭐⭐⭐
Anthropic Claude 3.5 ~$30–60 200–400 ⭐⭐⭐⭐⭐
Groq (free tier) $0 14,400 ⭐⭐⭐⭐
Ollama only (local) $0 ∞ ⭐⭐⭐⭐

8️⃣ Troubleshooting

GPU Not Being Used by Ollama

ollama list  # Check if models are loaded
nvidia-smi   # Check VRAM usage during generation

# If not using GPU, reinstall NVIDIA drivers:
# Windows: https://www.nvidia.com/download/index.aspx
# Linux: sudo apt install nvidia-driver-550

Gemini 429 Rate Limit

// ModelRouter already implements automatic fallback:
// Gemini 429 → automatically routes to Ollama
// Quota resets at midnight (tracked in ~/.enginai/quota.json)

TypeScript Build Errors

npm run typecheck  # See all type errors
npm run lint       # See all lint warnings
npm run build      # Full compile to dist/

Model Doesn’t Fit in VRAM

ollama pull qwen2.5-coder:7b-q4_K_M  # ~3.2GB VRAM (quantized)
ollama pull deepseek-r1:7b-q4_0       # ~2.8GB VRAM (quantized)

📋 Final Stack Summary

┌─────────────────────────────────────────────────────┐
│       ENGINAI — ZERO COST STACK (Node.js)      │
├─────────────────────────────────────────────────────┤
│                                               │
│  🖥️  Core: Node.js 20 + TypeScript 5.5       │
│     • Commander + Chalk + Ora (CLI)         │
│     • simple-git (Git operations)           │
│     • axios (HTTP / GitHub API)             │
│     • Zod (schema validation)               │
│                                               │
│  🧠  Primary LLM: Gemini 2.5 Flash           │
│     • 1,500 requests/day FREE               │
│     • ~100 tokens/s | Best quality          │
│     • @google/generative-ai SDK             │
│                                               │
│  🔄  Fallback: Ollama + GTX 1650 4GB         │
│     • qwen2.5-coder:7b (~50 tok/s GPU)     │
│     • deepseek-r1:7b (~45 tok/s GPU)       │
│     • Unlimited, fully local                │
│                                               │
│  🐙  Git: simple-git + GitHub API            │
│  🧪  Testing: Jest + ts-jest                  │
│  🔧  Build: tsc (TypeScript compiler)         │
│                                               │
├─────────────────────────────────────────────────────┤
│  💰 MONTHLY COST: $0.00                      │
│  ⚡ EXECUTIONS/DAY: Unlimited               │
│  🎯 QUALITY: Production-ready               │
│  🚀 SPEED: Excellent (GPU-accelerated)      │
└─────────────────────────────────────────────────────┘

Updated: March 17, 2026
Runtime: Node.js 20+ + TypeScript 5.5+
Hardware: i5-9300H + 16GB RAM + GTX 1650 4GB
Cost: $0.00/month
Status: Ready for MVP development