Install Deriva, derive your first model

Install

Deriva runs on your own machine: Deriva Studio in your browser, the pipeline and its embedded databases locally. Nothing is sent anywhere except the prompts to the LLM you choose.

Requirements

• Python 3.14. uv downloads it for you if it is missing.
• uv, the Python package manager (step 1).
• Git, to clone Deriva and the repositories you analyse.
• Node 22, to build the studio's front end from a source checkout.
• An LLM: an API key for Azure OpenAI, OpenAI, Anthropic or Mistral, or a local model in Ollama or LM Studio.

Five steps

1. Install uv

   Windows (PowerShell):

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

   macOS and Linux:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone Deriva and create your settings

   git clone https://github.com/StevenBtw/Deriva.git
   cd Deriva
   cp .env.example .env

   All settings live in .env. Set up an LLM there before your first run (how).

3. Install the dependencies

   uv sync

   This creates .venv with Python 3.14 and installs everything, including the spaCy pipelines (English, German and French) that find business concepts in documentation.

4. Build the studio, once

   cd studio
   npm install
   npm run build
   cd ..

   This writes the front end into the Python package, which serves it. Build again after you pull changes to studio/.

5. Start Deriva Studio

   uv run deriva

   Open http://127.0.0.1:8765. On its first start Deriva sets up its configuration database with the default steps; nothing to do. The studio listens on this machine only; --port picks another port, and the API documentation is at /docs.

How-tos

Set up an LLM

Each model gets a block of LLM_{NAME}_* settings in .env, and LLM_DEFAULT_MODEL picks the one Deriva uses. The default model is the name in lowercase with hyphens: LLM_MISTRAL_DEVSTRAL_* becomes mistral-devstral.

# .env: a cloud model
LLM_DEFAULT_MODEL=mistral-devstral

LLM_MISTRAL_DEVSTRAL_PROVIDER=mistral
LLM_MISTRAL_DEVSTRAL_MODEL=devstral-2512
LLM_MISTRAL_DEVSTRAL_URL=https://api.mistral.ai/v1/chat/completions
LLM_MISTRAL_DEVSTRAL_KEY=your-mistral-api-key
LLM_MISTRAL_DEVSTRAL_STRUCTURED_OUTPUT=true

A local model needs no key:

# .env: a local model in Ollama
LLM_DEFAULT_MODEL=ollama-devstral

LLM_OLLAMA_DEVSTRAL_PROVIDER=ollama
LLM_OLLAMA_DEVSTRAL_MODEL=devstral-small-2
LLM_OLLAMA_DEVSTRAL_URL=http://localhost:11434/api/chat

STRUCTURED_OUTPUT=true lets the API enforce the JSON schema (OpenAI, Anthropic, Mistral and Ollama). Rate limits, retries and the response cache have defaults; .env.example lists every setting.

Analyse your first repository

1. Open Repositories in the studio's menu and choose + Clone repository. Enter the Git URL; a name and a branch are optional.
2. Open the Workspace, pick the repository and a scope, and press Run. Structural steps only (without LLM) gives a first look without any LLM calls.
3. Follow the run in the tabs at the bottom: Live, Trace, Prompts and Errors. The intermediate graph and the output graph fill in side by side.
4. View model, on the right edge, opens the output graph as an ArchiMate diagram; click an element for its details.

Export to Archi

Deriva writes the model in the Open Group ArchiMate exchange format. From the studio: open View model and press Export XML; it writes workspace/output/model.xml on the machine that runs the studio. Or from the command line:

uv run deriva-cli export -o workspace/output/model.xml --repo my-repo

In Archi, choose File, Import, Open Exchange XML Model and pick the file.

Change a prompt

1. Open Extraction config or Derivation config in the menu.
2. Pick a step and edit its instruction or example. Every LLM step follows the same pattern: input, instruction, example.
3. Press Save as new version. Earlier versions stay in the history, and each step can be switched on or off.

Run the repository again to see the effect.

Use the command line

uv run deriva starts the studio; uv run deriva-cli runs the same pipeline without it, for scripts and automation.

uv run deriva-cli repo clone https://github.com/user/my-repo.git
uv run deriva-cli repo list
uv run deriva-cli run all --repo my-repo -v
uv run deriva-cli run extraction --repo my-repo --no-llm
uv run deriva-cli status
uv run deriva-cli export -o workspace/output/model.xml --repo my-repo
uv run deriva-cli --help

Query the graph

Each graph panel in the Workspace has a query bar that runs read-only Cypher against the embedded Grafeo database. A few to start with:

// All repositories
MATCH (r:Graph:Repository) RETURN r.repoName, r.url

// The files of one repository, with their type
MATCH (repo:Graph:Repository)-[:`Graph:CONTAINS`*]->(f:Graph:File)
WHERE repo.repoName = 'my-repo'
RETURN f.filePath, f.fileType

// Type definitions
MATCH (td:Graph:TypeDefinition) RETURN td.typeName, td.category, td.filePath

Troubleshooting

The studio shows a "not built yet" page

The front end is missing: build it (step 4) and reload.

A banner says the databases are held

A command line run, for example a benchmark, has the databases open. The studio shows what it can and carries on when that run finishes.

The wrong Python, or a broken install

uv run python --version    # 3.14 or newer
uv sync --reinstall

The business concept step cannot download its models

On its first run this step downloads translation models into workspace/cache/nlp and checks them by SHA-256. Check that the machine can reach the model host and run the step again. DERIVA_NLP_MODELS_DIR in .env moves the folder.

Going further

• README: configuration, file types, name patterns and config versions in full.
• BENCHMARKS.md: compare models and runs.
• CONTRIBUTING.md: architecture and development setup.
• Issues: questions, bugs and ideas.