Portable AI

USB'den calisan, %100 offline AI asistan. Encrypted conversation history + RAG.

• 🔒 Sohbet ve dokumanlar AES-256 + passphrase + USB volume serial ile sifrelenmis
• 📎 PDF/DOCX/TXT yukle, sohbette uzerinde konus
• 🎭 9 hazir mod: Genel, Avukat, Doktor, Muhasebeci, Mühendis, Öğretmen, Akademisyen, Yazar, Çevirmen
• 🧠 Trendyol-LLM 7B (Turkce icin tuned)
• 💾 Hicbir veri internet'e gitmez

Stack: Python 3.11+ · FastAPI · llama-cpp-python · sqlcipher · sentence-transformers · pypdf · python-docx

---

Hizli kurulum

1. uv kur (yoksa)

irm https://astral.sh/uv/install.ps1 | iex

2. Dependency'ler

cd portable-ai
copy .env.example .env
uv sync

uv sync su isleri yapar:

• Python 3.11 kurar
• venv olusturur
• llama-cpp-python==0.2.90 (abetlen CPU index)
• sqlcipher3>=0.6.2 (Windows wheel)
• sentence-transformers (RAG embeddings)
• pypdf + python-docx (document parsing)

İlk sync'te ~500 MB indirir.

3. LLM modelini indir

uv run python scripts/download_model.py

Default: Trendyol-LLM 7B Q4_K_M (4.7 GB). Listele: --list.

4. Calistir

uv run portable-ai

http://127.0.0.1:8765 → ilk acilista setup, sonra sohbet.

Embedding model (470 MB) ilk dosya yukledigin an HuggingFace'ten indirilir.

---

Faz 6 — RAG kullanimi

1. Yeni sohbet baslat, en az 1 mesaj at (conversation olusur)
2. 📎 butonuna tikla, PDF/DOCX/TXT yukle
3. Yuklenme bittiginde sohbete yaz — model otomatik dokumana bakar
4. Cevabin altinda Kaynaklar: dosya.pdf s.3 etiketleri

Akilli RAG: Dokuman yoksa duz chat. Dokuman varsa her mesaj otomatik retrieve.

Pipeline

Upload → parser (pypdf/python-docx) → chunker (recursive split, 800 char + 100 overlap)
       → embeddings (e5-small, 384-dim) → sqlcipher (BLOB)

Mesaj → embedding (query) → cosine similarity (numpy) → top-5 chunks
      → prompt'a inject → LLM stream

Retrieval kararlari

Parametre	Deger	Sebep
chunk_size	800 char	TR icin optimal (~150 kelime)
chunk_overlap	100 char	Cumle/baglam kaybi olmasin
top_k	5	Context'i sismeyecek dengede
min_score	0.3	Alakasiz chunk'lar filtrelenir
Index	numpy (in-memory)	<10k chunk icin FAISS'ten hizli

Limitasyonlar

• Taranan PDF (resim PDF) calismaz — OCR yok. pypdf metin layer'i olmali.
• DOCX'te image, chart, comment cikariliyor, sadece text + tablo.
• Maksimum dosya boyutu: 50 MB, dokuman basina max 2000 chunk.
• E5-small TR'de iyi ama mukemmel degil — bge-m3 (2.3 GB) daha iyi olur, USB icin trade-off var.

---

Onemli notlar ve troubleshooting

CPU uyumlulugu (AVX-512 sorunu)

llama-cpp-python 0.3.x AVX-512 instruction kullaniyor. 12+ gen Intel'de AVX-512 yok. 0.2.90 pin'lendi, AVX2 yeter.

sqlcipher kurulmadi

pyproject.toml'da sqlcipher3>=0.6.2. Eger Windows wheel cekemezse alternatif:

uv pip install sqlcipher3-wheels

(db.py her ikisini de destekler, otomatik fallback.)

Embedding model ilk yukleme yavas

İlk dosya yuklediginde e5-small (470 MB) HuggingFace'ten cekiliyor (models/embeddings/). Sonraki yuklemelerde cache'ten gelir, ~1-2 saniyede hazir.

RTX 4050 + CUDA (opsiyonel, hizla ilgili)

Embedding'leri GPU'da hesaplamak istiyorsan embeddings.py'de device="cuda" yap. Ama CPU zaten yeterince hizli (e5-small i5-12600HX'te ~50ms/chunk). LLM tarafi icin README'nin onceki versiyonundaki CUDA wheel talimati gecerli.

Hybrid CPU (12+ gen Intel) hiz optimizasyonu

N_THREADS=6  # P-core sayisi + 2

---

Proje yapisi

portable-ai/
├── pyproject.toml
├── src/portable_ai/
│   ├── main.py
│   ├── config.py
│   ├── auth.py
│   ├── backends/                 # LLM inference
│   │   ├── base.py
│   │   └── llama_cpp.py
│   ├── storage/                  # Encrypted persistence
│   │   ├── crypto.py             # USB UUID binding, PBKDF2
│   │   ├── db.py                 # sqlcipher async wrapper + schema
│   │   ├── conversations.py      # Chat CRUD
│   │   └── documents.py          # RAG document CRUD
│   ├── rag/                      # Retrieval Augmented Generation
│   │   ├── embeddings.py         # e5-small singleton
│   │   ├── parser.py             # PDF/DOCX/TXT extract
│   │   ├── chunker.py            # Recursive char split
│   │   ├── index.py              # In-memory vector search
│   │   └── retrieval.py          # Ingest + query orchestration
│   └── web/
│       ├── routes.py
│       └── templates/index.html
├── scripts/download_model.py
├── models/                       # GGUF + embeddings (gitignore)
├── data/                         # chats.db (encrypted, gitignore)
└── tests/

Roadmap

• Faz 1: FastAPI + llama-cpp-python + streaming UI
• Faz 2: sqlcipher + USB UUID binding + conversation CRUD
• Faz 6: RAG (PDF/DOCX/TXT + e5 embeddings + numpy search)
• Faz 7: Konusma presetleri (9 built-in mod)
• Faz 3: PyInstaller bundle + USB packaging (Windows)
• Faz 7.5: Custom preset olusturma UI
• Faz 4: Multi-platform launchers (Mac/Linux)
• Faz 5: Code signing

---

Faz 3 — USB Packaging

USB'den calisan tek dosya ureten build pipeline.

Build (dev makinesinde, RTX 4050 laptop'unda)

# Dev dependency'leri kur (PyInstaller dahil)
uv sync --extra dev

# Build calistir
uv run python scripts/build_release.py

Cikti: dist/portable-ai-win/ — ~250 MB klasor.

USB hazirla

# Bos USB tak (16 GB onerilir), drive harfini ogren (orn E:)
uv run python scripts/prepare_usb.py --target E:\

Bu komut:

1. dist/portable-ai-win/ -> USB'ye kopyalar (~250 MB)
2. Trendyol 7B model'i models/'a kopyalar (~4.7 GB)
3. e5-small embedding cache'i kopyalar (~470 MB, eger varsa)
4. start.bat ve README.txt yazar
5. Bos data/ klasoru olusturur

Toplam USB'de: ~5.5 GB

Baska bilgisayarda test

1. USB'yi cikar, baska Windows 11 PC'ye tak
2. USB'yi ac
3. start.bat'a cift tikla
4. Windows Defender uyarisi cikarsa "Yine de calistir"
5. 60-90 saniye icinde tarayici otomatik acilir
6. Setup ekranindan sifre belirle, kullan

USB AES-256 sifreli — sifre + USB seri numarasi olmadan veri acilmaz.

Lisans

MIT