Project_Journal-Csharp_backend-Python-Frontend/README.md

Project_Journal

A structured journaling system with encrypted monthly vaults, desktop UI, CLI tools, and optional AI-assisted analysis.

For local AI models, use Ollama, or LM Studio or similar.

Support Matrix

• Python: 3.14
• Platforms: Windows and Linux (first-class), macOS (best effort)
• Default profile: CPU
• Optional profiles: GPU, optional NLP backend

Dependency Profiles

• requirements_base.txt: shared Journal runtime dependencies
• requirements_cpu_only.txt: base + CPU AI stack
• requirements_gpu.txt: base + GPU AI stack
• requirements_nlp_optional.txt: optional spaCy backend (auto-fallback if unavailable)

Quickstart

Linux (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

Linux (GPU 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

Windows PowerShell (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

On Windows + Python 3.14, pywebview is intentionally skipped due upstream pythonnet build compatibility. run_desktop.py will auto-fallback to opening the app in your system browser.

Windows Minimal Wrapper Commands

If your shell has broken proxy/no-index env vars or restricted profile paths:

cd Project_Journal
.\scripts\dev-shell.ps1
.\scripts\dotnet-min.ps1 restore journal-master/journal/Journal.Sidecar/Journal.Sidecar.csproj
.\scripts\pip-min.ps1 install --index-url https://pypi.org/simple faster-whisper

pip-min.ps1 installs to repo-local .pydeps/py314 by default to avoid user site-packages permission issues. On Windows, it also maps pyaudio to pyaudiowpatch to avoid PortAudio source-build failures. The dev shell also sets Hugging Face cache to repo-local .cache/huggingface and suppresses the Windows symlink warning.

Optional NLP backend (spaCy)

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

If spaCy is missing or unsupported, Journal now auto-falls back to built-in NLP heuristics. On current Python 3.14 environments, this optional install may be skipped due upstream spaCy compatibility.

Running

Desktop App

python ./journal/run_desktop.py

Hybrid Backend Mode (Python UI + C# backend bridge)

Build the sidecar once:

cd .\journal-master\journal
.\scripts\dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj

Run the Python app with hybrid mode enabled:

cd ..\..
$env:JOURNAL_BACKEND_MODE = "csharp-hybrid"
python .\journal\run_desktop.py

Optional override if the sidecar executable is in a custom path:

$env:JOURNAL_CSHARP_SIDECAR_PATH = "E:\path\to\Journal.Sidecar.exe"

CLI

python -m journal.cli.main --help
python -m journal.cli.main vault load
python -m journal.cli.main search "your query"
python -m journal.cli.main fragments list
python -m journal.cli.main fragments create --type !NOTE --description "example" --tag testing

Fragment CLI commands use C# sidecar actions and require:

• JOURNAL_BACKEND_MODE=csharp-hybrid

NLP Backend Control

Set JOURNAL_NLP_BACKEND to choose behavior:

• auto (default): use spaCy when available, else fallback
• spacy: require spaCy backend and fail clearly if unavailable
• fallback: always use fallback heuristics

Examples:

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

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

Installer Script

Use the Linux helper script:

./installreqs.sh
./installreqs.sh --gpu
./installreqs.sh --with-nlp

Notes

• Decrypted journal data in journal/data is cleared on graceful shutdown.
• Vault save/load commands remain unchanged.
• In csharp-hybrid mode, UI entry load/save, vault operations, and CLI search use C# sidecar actions.
• AI remains Python-local by design in the Python UI runtime.
• Settings dialog now exposes backend/AI/speech runtime fields (endpoints, models, timeouts, engine/device/compute), with restart controls for changes that require reinitialization.