Dokümantasyon / Kurulum

Checkout'tan çalıştırmak

ivralo'yu doğrudan repo'sunun bir klonundan çalıştırmak, ivralo'nun kendisi üzerinde çalışırken ya da global bir komut kurmadan denemek istediğinizde işe yarar. Bu durumda checkout aynı zamanda ana dizindir.

Gerekenler

uv. Repo'nun sabitlediği Python'ı (3.13) kendisi kurar.
git ve repo'ya erişim. Repo private; erişimi istek üzerine veriyoruz (bize yazın).
pgvector'lü PostgreSQL: Docker ya da zaten çalışan bir veritabanınız (PostgreSQL).
Bir model: Ollama, OpenAI uyumlu bir endpoint ya da barındırılan bir API'nin anahtarı.

Klondan oturuma

git clone git@github.com:kemalcalak/ivralo.git
cd ivralo
uv sync
export IVRALO_HOME="$PWD"
uv run ivralo init
uv run ivralo

uv sync, ivralo'nun checkout'tan kurulduğu sanal ortamı .venv/ içinde oluşturur. init hangi modeli istediğinizi sorar, .env'i yazar, PostgreSQL'i Docker ile başlatır, eksik Ollama modellerini çeker, web araçlarının kullandığı tarayıcıyı kurar, git hook'larını ayarlar ve en sonda ivralo doctor çalıştırır. Her adımdan önce onayınızı alır.

Seçenek	Etkisi
`--yes`	Hiçbir şey sormadan bütün varsayılanları kabul eder
`--model <ref>`	Modeli baştan belirler: bir Ollama etiketi ya da `provider:model`
`--no-docker`, `--no-pull`, `--no-browser`, `--no-hooks`	İlgili adımı atlar

Var olan bir .env'e dokunulmaz. init'i istediğiniz zaman yeniden çalıştırabilirsiniz: zaten yerinde olan her şey raporlanır ve olduğu gibi bırakılır.

`IVRALO_HOME` neden ayarlanmalı

ivralo'nun yalnızca orada başlattığınız için bulduğu bir checkout, bir geri dönüş ana dizinidir (fallback home). Klonlanmış herhangi bir repo tıpatıp bir ivralo checkout'u gibi görünebilir; bu yüzden dosyalarına sizinmiş gibi güvenilmez. .env'i, mcp.json'ı, skill'leri ve diğer ayar dosyaları okunmaz, permissions.json'ı yalnızca reddedebilir. ivralo init de daha hiçbir şey sormadan 2 çıkış koduyla reddeder.

Checkout'un sizin olduğunu söylemenin yolu, IVRALO_HOME'u checkout'un yoluyla export etmektir. Kalıcı olması için satırı ~/.profile'a (zsh kullanıyorsanız ~/.zprofile'a) ekleyin. Sizin yazmadığınız bir klon için bunu yapmayın; onun yerine klonun dışında ivralo init --home ~/ivralo ile bir ana dizin oluşturun.

Barındırılan modeller

Barındırılan sağlayıcıların SDK'ları birer extra olarak gelir. İhtiyacınız olanı ortama kurun:

uv sync --extra anthropic

Extra'lar şunlar: anthropic, google, groq, mistral ve hepsini içeren providers. Anahtarı .env'e SDK'nın kendi kullandığı adla, örneğin ANTHROPIC_API_KEY olarak yazın; model de IVRALO_MODEL=anthropic:<model> olur.

`init`'in yaptıkları, elle

Bir adımı kendiniz yapmak isterseniz:

ollama pull gemma4:26b                # varsayılan model
ollama pull nomic-embed-text          # bilgi dizininin embedder'ı
uv run playwright install chromium    # web araçlarının tarayıcısı
docker compose up -d                  # checkout'un compose dosyasından PostgreSQL
uv run ivralo doctor

Taranmış PDF'leri ve görüntüleri okumak için docling'i ayrı bir araç olarak kurun; ivralo'nun ortamını paylaşamaz. Modellerini önceden indirmezseniz ilk dönüştürmede yaklaşık 400 MB indirilir:

uv tool install docling
docling-tools models download

.env anahtarlarınızı tuttuğu için ivralo bu dosyayı yalnızca sahibinin okuyabileceği şekilde yazar. Elle oluşturduğunuz bir kopya ise shell'inizin verdiği izinlerle kalır. Hangisinin geçerli olduğunu doctor'ın private files bölümünde görürsünüz; init de izinleri sıkılaştırmayı önerir.

Git hook'ları

Repo, hook'larını .githooks/ içinde taşır. init, onay verirseniz checkout'u bu hook'lara yönlendirir. Elle yapmak tek satır, her klon için bir kez:

git config core.hooksPath .githooks

pre-commit, main üzerine atılan commit'i reddeder; commit-msg, commit konusunun bir Conventional Commit (feat:, fix:, docs: vb.) olup olmadığını kontrol eder; pre-push doğrudan main'e yapılan push'u reddeder. init bunu yalnızca ana dizinin kendi repo'sunda ayarlar; ivralo'yu başlattığınız başka bir repo'da asla.

Windows

Checkout içinde düz cmd'den, ivralo.cmd ivralo'yu PATH ayarına gerek kalmadan ve uv PATH'te olmasa bile çalıştırır:

ivralo.cmd doctor
ivralo.cmd

IVRALO_HOME'u kendi klasörüne ayarlar ve .venv\Scripts\ivralo.exe'yi çağırır; bu yüzden önce bir kez uv sync çalıştırın. IVRALO_HOME'u bütün terminallerde kalıcı yapmak için init'in bastığı setx satırını kullanın. Windows'ta PostgreSQL için yol Docker ya da bir veritabanı URL'sidir: ivralo orada kendi cluster'ını oluşturmaz.

Checkout'tan global bir komut

Checkout'u ana dizin olarak tutup ivralo'yu PATH'te de istiyorsanız, wheel'i derleyip bir araç olarak kurun:

uv build
uv tool install dist/ivralo-0.1.2-py3-none-any.whl
export IVRALO_HOME=/path/to/ivralo
ivralo doctor

doctor'ın environment bölümü ana dizini ve nasıl bulunduğunu gösterir: IVRALO_HOME'dan mı, ivralo'nun başlatıldığı checkout'tan mı, yoksa paketin çalıştığı checkout'tan mı.

Bir değişikliği push'lamadan önce

Bir değişikliğin geçmesi gereken kontroller; CI da aynılarını çalıştırır:

uv run ruff check . --fix
uv run ruff format .
uv run mypy
uv run pytest -m "not integration and not e2e"

Son satır, hiçbir servisin ayakta olmasını gerektirmeyen unit katmanıdır. uv run pytest -m "integration and not e2e" veritabanı katmanını, uv run pytest -m e2e ise birleştirilmiş tüm yığını ekler; ikisi de docker compose up -d ister, hiçbiri model çalıştırmaz. Gerisi repo'daki CONTRIBUTING.md'de.