163 lines
4.5 KiB
Markdown
163 lines
4.5 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
python ./journal/run_desktop.py
|
|
```
|
|
|
|
### Hybrid Backend Mode (Python UI + C# backend bridge)
|
|
|
|
Build the sidecar once:
|
|
|
|
```powershell
|
|
cd .\journal-master\journal
|
|
.\scripts\dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj
|
|
```
|
|
|
|
Run the Python app with hybrid mode enabled:
|
|
|
|
```powershell
|
|
cd ..\..
|
|
$env:JOURNAL_BACKEND_MODE = "csharp-hybrid"
|
|
python .\journal\run_desktop.py
|
|
```
|
|
|
|
Optional override if the sidecar executable is in a custom path:
|
|
|
|
```powershell
|
|
$env:JOURNAL_CSHARP_SIDECAR_PATH = "E:\path\to\Journal.Sidecar.exe"
|
|
```
|
|
|
|
### CLI
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
export JOURNAL_NLP_BACKEND=fallback
|
|
python ./journal/run_desktop.py
|
|
```
|
|
|
|
```powershell
|
|
$env:JOURNAL_NLP_BACKEND = "spacy"
|
|
python .\journal\run_desktop.py
|
|
```
|
|
|
|
## Installer Script
|
|
|
|
Use the Linux helper script:
|
|
|
|
```bash
|
|
./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.
|