Run from a checkout

What you need

• uv. It installs the Python the repository pins (3.13) by itself.
• git, and access to the repository. It is private; access is given on request (write to us).
• PostgreSQL with pgvector: Docker, or a database you already run (PostgreSQL).
• A model: Ollama, an OpenAI-compatible endpoint, or a hosted API's key.

From clone to session

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 makes the virtual environment in .venv/ with ivralo installed from the checkout. init asks which model you want, writes .env, starts PostgreSQL with Docker, pulls the Ollama models that are missing, installs the browser the web tools use, sets the git hooks, and ends with ivralo doctor. Every action waits for your yes.

An existing .env is kept. Run init again at any time: what is already in place is reported and left alone.

Why IVRALO_HOME has to be set

A checkout ivralo only finds, because you happened to start it there, is a fallback home: a cloned repository can look exactly like an ivralo checkout, so its files are not trusted as yours. Its .env, mcp.json, skills and the other settings files are not read, its permissions.json can only deny, and ivralo init refuses with exit code 2 before asking anything.

Exporting IVRALO_HOME with the checkout's path is how you say it is yours. Put the line in ~/.profile (or ~/.zprofile for zsh) to keep it. For a clone you did not write, make a home outside it instead, with ivralo init --home ~/ivralo.

Hosted models

A hosted provider's SDK is an extra. Install the one you need into the environment:

uv sync --extra anthropic

The extras are anthropic, google, groq, mistral and providers (all of them). The key goes in .env under the SDK's own name, such as ANTHROPIC_API_KEY, and the model is IVRALO_MODEL=anthropic:<model>.

What init does, by hand

For when you would rather do a step yourself:

ollama pull gemma4:26b                # the default model
ollama pull nomic-embed-text          # the knowledge index's embedder
uv run playwright install chromium    # the web tools' browser
docker compose up -d                  # PostgreSQL, from the checkout's compose file
uv run ivralo doctor

To read scanned PDFs and images, install docling as a tool of its own; it cannot share ivralo's environment. Its first conversion downloads about 400 MB of models unless you fetch them up front:

uv tool install docling
docling-tools models download

.env holds your keys, so ivralo writes it owner-only. A copy you make by hand keeps whatever permissions your shell gave it; doctor's private files section says which, and init offers to tighten it.

The git hooks

The repository carries its hooks in .githooks/. init points the checkout at them after a yes; by hand it is one line, once per clone:

git config core.hooksPath .githooks

pre-commit refuses a commit on main, commit-msg checks the subject is a Conventional Commit (feat:, fix:, docs: and the rest), and pre-push refuses a push straight to main. init sets this only in the home's own repository, never in another one you started it from.

Windows

From plain cmd in the checkout, ivralo.cmd runs ivralo with no PATH setup and without uv on the PATH:

ivralo.cmd doctor
ivralo.cmd

It sets IVRALO_HOME to its own folder and calls .venv\Scripts\ivralo.exe, so run uv sync once first. To keep IVRALO_HOME for every terminal, use the setx line init prints. Docker or a database URL is the way to PostgreSQL on Windows: ivralo does not make a cluster of its own there.

A global command from the checkout

To have ivralo on the PATH while keeping the checkout as the home, build the wheel and install it as a tool:

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

doctor's environment section names the home and how it was found: IVRALO_HOME, the checkout ivralo was started in, or the checkout the package runs from.

Before you push a change

The checks a change has to pass, the same ones CI runs:

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

The last line is the unit tier, which needs nothing running. uv run pytest -m "integration and not e2e" adds the database tier and uv run pytest -m e2e the whole assembled stack; both need docker compose up -d, and neither runs a model. CONTRIBUTING.md in the repository has the rest.