Setup and Installation

This page covers local setup for the Python baseline and optional C# migration workspace.

Prerequisites

Python 3.14
pip and virtual environment support
Windows or Linux
Optional: GPU drivers/toolkit if using requirements_gpu.txt

Dependency Profiles

requirements_base.txt: shared runtime dependencies
requirements_cpu_only.txt: base + CPU AI stack
requirements_gpu.txt: base + GPU AI stack
requirements_nlp_optional.txt: optional spaCy backend

Windows Setup (CPU default)

cd Project_Journal
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt

Run desktop app:

python .\journal\run_desktop.py

Linux Setup (CPU default)

cd Project_Journal
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt

Run desktop app:

python ./journal/run_desktop.py

Linux GPU Setup (optional)

cd Project_Journal
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements_gpu.txt

Optional NLP Backend (spaCy)

python -m pip install -r requirements_nlp_optional.txt
python -m spacy download en_core_web_sm

NLP backend modes:

auto (default): spaCy if available, fallback otherwise
spacy: require spaCy and fail if unavailable
fallback: always use fallback NLP heuristics

Examples:

$env:JOURNAL_NLP_BACKEND = "fallback"
python .\journal\run_desktop.py

export JOURNAL_NLP_BACKEND=spacy
python ./journal/run_desktop.py

C# Migration Workspace Setup (optional)

Location: journal-master/journal/

Use:

journal-master/journal/README.md
journal-master/journal/MINIMAL_MACHINE_SETUP.md

Quick check:

cd journal-master/journal
./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj
./scripts/dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj
./scripts/dotnet-min.ps1 run --project Journal.SmokeTests/Journal.SmokeTests.csproj

Release gate (repo root):

cd Project_Journal
./scripts/migration-gate.ps1

This command runs:

C# sidecar/api builds
C# smoke suite
Python-vs-C# parity harness + vault fixture matrix
HTTP API contract tests