{"id":27603794,"url":"https://github.com/technologicat/raven","last_synced_at":"2026-03-03T09:10:14.669Z","repository":{"id":269045959,"uuid":"906254190","full_name":"Technologicat/raven","owner":"Technologicat","description":"Semantic visualizer and analyzer","archived":false,"fork":false,"pushed_at":"2025-04-17T10:12:59.000Z","size":5001,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T19:19:29.550Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Technologicat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-20T13:43:55.000Z","updated_at":"2025-04-17T10:13:03.000Z","dependencies_parsed_at":"2024-12-20T14:50:58.262Z","dependency_job_id":"258f1d39-9c07-4ea1-ab67-396bcbef3138","html_url":"https://github.com/Technologicat/raven","commit_stats":null,"previous_names":["technologicat/raven"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Technologicat%2Fraven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Technologicat%2Fraven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Technologicat%2Fraven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Technologicat%2Fraven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Technologicat","download_url":"https://codeload.github.com/Technologicat/raven/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250306602,"owners_count":21408927,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-22T19:19:34.102Z","updated_at":"2026-03-03T09:10:14.658Z","avatar_url":"https://github.com/Technologicat.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"img/logo.png\" alt=\"Logo of Raven\" height=\"200\"/\u003e \u003cbr/\u003e\n\u003c/p\u003e\n\n-----\n\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n**Table of Contents**\n\n- [The Raven constellation](#the-raven-constellation)\n    - [Raven-visualizer: Visualize research literature](#raven-visualizer-visualize-research-literature)\n    - [Raven-librarian: Multiversal LLM frontend](#raven-librarian-multiversal-llm-frontend)\n    - [Raven-avatar: AI-animated anime avatar](#raven-avatar-ai-animated-anime-avatar)\n    - [Raven-xdot-viewer: Small standalone GraphViz graph viewer](#raven-xdot-viewer-small-standalone-graphviz-graph-viewer)\n    - [Raven-server: Web API server](#raven-server-web-api-server)\n- [Install \u0026 run](#install--run)\n    - [From source](#from-source)\n        - [Install PDM in your Python environment](#install-pdm-in-your-python-environment)\n        - [Install Raven via PDM](#install-raven-via-pdm)\n            - [Basic install without GPU compute support](#basic-install-without-gpu-compute-support)\n            - [Install with GPU compute support](#install-with-gpu-compute-support)\n            - [Install on an Intel Mac with MacOSX 10.x](#install-on-an-intel-mac-with-macosx-10x)\n            - [Install on Windows (if Windows Defender gets angry)](#install-on-windows-if-windows-defender-gets-angry)\n        - [Check that CUDA works (optional)](#check-that-cuda-works-optional)\n        - [Activate the Raven venv (to run Raven commands such as `raven-visualizer` or `raven-server`)](#activate-the-raven-venv-to-run-raven-commands-such-as-raven-visualizer-or-raven-server)\n        - [Activate GPU compute support (optional)](#activate-gpu-compute-support-optional)\n        - [Choose which GPU to use (optional)](#choose-which-gpu-to-use-optional)\n        - [Exit from the Raven venv (optional, to end the session)](#exit-from-the-raven-venv-optional-to-end-the-session)\n- [Configuration](#configuration)\n- [Uninstall](#uninstall)\n- [Technologies](#technologies)\n- [Privacy](#privacy)\n- [License](#license)\n- [Acknowledgements](#acknowledgements)\n\n\u003c!-- markdown-toc end --\u003e\n\n# The Raven constellation\n\n*Raven* is a constellation of apps loosely related to natural language processing, with a focus on scientific use cases.\n\nThe vision is to help you absorb information from large volumes of text.\n\n*Raven* is 100% local, 100% privacy-first, 100% open source.\n\nRecent changes are explained in the [CHANGELOG](CHANGELOG.md).\n\n## Raven-visualizer: Visualize research literature\n\n\u003ca href=\"raven/visualizer/README.md\"\u003e\u003cimg src=\"img/screenshot-main.png\" alt=\"Screenshot of Raven-visualizer's main window\" height=\"200\"/\u003e\u003c/a\u003e\n\u003ca href=\"raven/visualizer/README.md\"\u003e\u003cimg src=\"img/screenshot-wordcloud.png\" alt=\"Screenshot of Raven-visualizer's wordcloud window\" height=\"200\"/\u003e\u003c/a\u003e\n\n- **Documentation**: [Visualizer user manual](raven/visualizer/README.md)\n- **Goal**: Take 10k+ studies, find the most relevant ones.\n  - **Status**: :white_check_mark: Fully operational. Could still use more features; we plan to add some later.\n- **Features**:\n  - GUI app for analyzing BibTeX databases\n  - Semantic clustering\n  - Automatic per-cluster keyword detection\n  - Command-line converters for Web of Science (WOS), arXiv, conference abstract PDFs, CSV files\n  - 100% local, maximum privacy, no cloud services\n- This was the original *Raven*.\n\n*Added in v0.2.5: CSV import.*\n\n## Raven-librarian: Multiversal LLM frontend\n\n\u003cimg src=\"img/screenshot-librarian.png\" alt=\"Screenshot of Raven-librarian\" height=\"200\"/\u003e\n\n- **Documentation**: [Librarian user manual](raven/librarian/README.md) (under development)\n- **Goal**: Efficiently interrogate a stack of 2k scientific papers. Talk with a local LLM for synthesis, clarifications, speculation, ...\n  - **Status**: :construction: An initial prototype of GUI app `raven-librarian` is available; as well as a command-line mini-prototype `raven-minichat` (note that the GUI app has more features).\n    - The GUI app is under development.\n    - For the GUI app `raven-librarian`, `raven-server` must be running.\n    - For the command-line `raven-minichat`, we recommend having `raven-server` running; this allows the LLM to search the web.\n- **Features**:\n  - 100% local when using a locally hosted LLM\n  - Natively nonlinear branching chat history - think *Loom* ([original](https://github.com/socketteer/loom); [obsidian](https://github.com/cosmicoptima/loom)) or *[SillyTavern-Timelines](https://github.com/SillyTavern/SillyTavern-Timelines)*.\n    - Chat messages are stored as nodes in a tree.\n    - Branching is cheap. A chat branch is just its HEAD pointer.\n    - The chain of `parent` nodes uniquely determines the linear history for that branch, up to and including the system prompt.\n  - RAG (retrieval-augmented generation) with hybrid (semantic + keyword) search.\n    - Semantic backend: [Chroma](https://www.trychroma.com/) (with telemetry off, for maximum privacy).\n    - Keyword backend: [bm25s](https://huggingface.co/blog/xhluca/bm25s), which implements the [BM25](https://en.wikipedia.org/wiki/Okapi_BM25) ranking algorithm.\n    - Results are combined with [reciprocal rank fusion](https://www.assembled.com/blog/better-rag-results-with-reciprocal-rank-fusion-and-hybrid-search).\n  - Tool-calling (a.k.a. tool use).\n    - Currently, a websearch tool is provided. This will be expanded later.\n  - Anime avatar for the LLM, see *Raven-avatar* below.\n    - Speech synthesizer with lipsynced animation.\n    - Subtitles with machine translation.\n    - Speech recognition. Use your mic to talk to the LLM.\n      - Voice mode is 100% privacy-first; audio is never recorded to disk, and never sent anywhere except your local *Raven-server* for transcription.\n- Uses [oobabooga/text-generation-webui](https://github.com/oobabooga/text-generation-webui) as the LLM backend through its OpenAI-compatible API.\n  - We currently test our LLM functionality with the Qwen series of LLMs.\n  - Recommended model: [Qwen3-VL-30B-A3B-Thinking](https://huggingface.co/Qwen/Qwen3-VL-30B-A3B-Thinking).\n\n## Raven-avatar: AI-animated anime avatar\n\n\u003ca href=\"raven/avatar/README.md\"\u003e\u003cimg src=\"img/avatar-settings-editor.png\" alt=\"Screenshot of Raven-avatar-settings-editor\" height=\"200\"/\u003e\u003c/a\u003e\n\u003ca href=\"raven/avatar/README.md\"\u003e\u003cimg src=\"img/avatar-pose-editor.png\" alt=\"Screenshot of Raven-avatar-pose-editor\" height=\"200\"/\u003e\u003c/a\u003e\n\n- **Documentation**: [Avatar user manual](raven/avatar/README.md)\n- **Goal**: Visually represent your LLM as a custom anime character, for PR stunts and for fun.\n  - **Status**: :white_check_mark: Fully operational standalone tech demo, and Python bindings to integrate the avatar to Python-based GUI apps.\n  - JS bindings possible, but not implemented yet. See [#2](https://github.com/Technologicat/raven/issues/2).\n- **Features**:\n  - One static input image into realtime video (THA3 engine).\n  - Talking custom anime character with 28 emotional expressions.\n  - Lipsync to *Raven-server*'s TTS. Record TTS-generated speech with lipsync (audio + image sequence).\n  - Realtime Anime4K upscaler.\n  - Realtime video postprocessor with visual effects such as [bloom](https://en.wikipedia.org/wiki/Bloom_(shader_effect)), [chromatic aberration](https://en.wikipedia.org/wiki/Chromatic_aberration), or [scanlines](https://en.wikipedia.org/wiki/Scan_line).\n  - Web API to receive avatar video stream and to control the avatar.\n\n## Raven-xdot-viewer: Small standalone GraphViz graph viewer\n\n*Added in v0.2.5.*\n\n- **Documentation**: WIP\n- **Goal**: View your `.dot` (`.gv`) and `.xdot` files in a GUI app with a focus on usability\n  - **Status**: :white_check_mark: Fully operational prototype, usage: `raven-xdot-viewer myfile.xdot`\n- **Features**:\n  - Animated GUI, easy for pair work.\n  - Click on the end of an edge to follow it.\n  - Incremental fragment search for node/edge labels, like in *Visualizer*.\n\n\n## Raven-server: Web API server\n\n\u003ca href=\"raven/server/README.md\"\u003e\u003cimg src=\"img/screenshot-server.png\" alt=\"Screenshot of Raven-server\" height=\"200\"/\u003e\u003c/a\u003e\n\n- **Documentation**: [Server user manual](raven/server/README.md)\n- **Goal**: Run all GPU processing on the server, anywhere on the local network.\n  - **Status**: :white_check_mark: Fully operational.\n- **Features**:\n  - AI components for natural language processing (NLP).\n  - Speech synthesizer (TTS), using [Kokoro-82M](https://github.com/hexgrad/kokoro).\n  - Speech recognition (STT), using [whisper-large-v3-turbo](https://huggingface.co/openai/whisper-large-v3-turbo).\n  - Server side of *Raven-avatar*.\n- Partially compatible with *SillyTavern*. Originally developed as a continuation of *SillyTavern-extras*.\n- Python bindings (client for web API) provided.\n  - JS bindings possible, but not implemented yet. See [#2](https://github.com/Technologicat/raven/issues/2).\n\n\n# Install \u0026 run\n\nThe Raven constellation consists traditional desktop apps. It needs to be installed.\n\nCurrently, this takes the form of installing the app and dependencies into a venv (virtual environment). At least at this stage of development, app packaging into a single executable is not a priority.\n\nRaven is developed and tested on Linux Mint. It should work in any environment that has `bash` and `pdm`.\n\nIt has been reported to work on Mac OS X, as well as on Windows (with [Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/main) to provide Python).\n\n## From source\n\nRaven has the following requirements:\n\n - A Python environment for running the [PDM](https://pdm-project.org/en/latest/) installer. Linux OSs have one built-in; on other OSs it is possible to use tools such as [Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/main) to install one.\n - An NVIDIA GPU for running AI models via CUDA. (This is subject to change in the future.)\n\n:exclamation: **Help wanted!** If you have an AMD GPU and would be willing to collaborate to get Raven working on it, [please chime in](https://github.com/Technologicat/raven/issues/1). Raven does not directly depend on CUDA, but only on PyTorch and on various AI libraries in the Python ecosystem. :exclamation:\n\n### Install PDM in your Python environment\n\nRaven uses [PDM](https://pdm-project.org/en/latest/) to manage its dependencies. This allows easy installation of the app and its dependencies into a venv (virtual environment) that is local to this one app, so that installing Raven will not break your other apps that use machine-learning libraries (which tend to be very version-sensitive).\n\nNote that in contrast to many AI/ML apps, which use `conda` to manage the venv for the app, Raven instead uses PDM. The venv creation and management for the app is automatic, but you need a Python environment to run PDM in. That Python environment is used for running PDM **only**. Raven itself will run in the venv created automatically by PDM, which may even have a Python version different from that of the environment where PDM runs.\n\nIf your Python environment does not have PDM, you will need to install it first:\n\n```bash\npython -m pip install pdm\n```\n\nDon't worry; it won't break `pip`, `poetry`, `uv`, or other similar tools.\n\n### Install Raven via PDM\n\nThen, to install Raven, in a terminal that sees your Python environment, navigate to the Raven folder.\n\nWe will next initialize the new venv, installing the required Python version into it. This Python will be available for PDM venvs, and is independent of Python that PDM itself runs on.\n\nRaven is currently developed against the minimum supported Python version, so we recommend to install that version, like this:\n\n```bash\npdm python install --min\n```\n\nThe venv will be installed in the `.venv` hidden subfolder of the Raven folder.\n\nThen, install Raven's dependencies as follows. (If you are a seasoned pythonista, note that there is no `requirements.txt`; the dependency list lives in `pyproject.toml`.)\n\n#### Basic install without GPU compute support\n\n```bash\npdm install\n```\n\nThis may take a while (several minutes).\n\nNow the installation should be complete.\n\n#### Install with GPU compute support\n\n:exclamation: *Currently this requires an NVIDIA GPU and CUDA.* :exclamation:\n\n:exclamation: *Using CUDA requires the proprietary NVIDIA drivers, also on Linux.* :exclamation:\n\n:exclamation: *Currently Raven uses CUDA 12.x. Make sure your NVIDIA drivers support this version.* :exclamation:\n\n```bash\npdm install --prod -G cuda\n```\n\nIf you want to add GPU compute support later, you can run this install command on top of an already installed Raven.\n\nInstalling dependencies may take a long time (up to 15-30 minutes, depending on your internet connection), because `torch` and the NVIDIA packages are rather large (my `.venv` shows 11.1 GB in total).\n\nNow the installation should be complete.\n\n#### Install on an Intel Mac with MacOSX 10.x\n\nInstalling Raven may fail, if Torch cannot be installed.\n\nOn MacOSX, installing torch 2.3.0 or later requires an ARM64 processor and MacOSX 11.0 or later.\n\nIf you have an Intel Mac (x86_64) with MacOSX 10.x, to work around this, you can use Torch 2.2.x.\n\nTo do this, modify Raven's [`pyproject.toml`](pyproject.toml) in a text editor, so that the lines\n\n```\n    \"torch\u003e=2.4.0\",\n    \"torchvision\u003e=0.22.0\",\n```\n\nbecome\n\n```\n    \"torch\u003e=2.2.0,\u003c2.3.0\",\n    \"torchvision\u003e=0.17.2\",\n```\n\nAlso, ChromaDB requires `onnxruntime`, which doesn't seem to be installable on this version of OS X. This means *Raven-librarian* and *Raven-server* won't work (as the RAG backend and the server's `embeddings` module require ChromaDB), but you can still get *Raven-visualizer* to work, by removing ChromaDB. Run this command in the terminal:\n\n```bash\npdm remove chromadb\n```\n\nThen run `pdm install` again.\n\n:exclamation: *In general, if a package fails to install, but is not explicitly listed in the dependencies, you can try to find out which package pulls it in, by issuing the command `pdm list --tree`. This shows a tree-structured summary of the dependencies.* :exclamation:\n\n#### Install on Windows (if Windows Defender gets angry)\n\n*Installing Raven does **not** need admin rights.*\n\n- Raven can be installed as a regular user.\n  - We recommend [Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/main) as the Python environment.\n- The only exception, that **does** need admin rights, is installing `espeak-ng`, so the TTS (speech synthesizer) can use that as its fallback phonemizer.\n  - Raven only ever calls `espeak-ng` from *Raven-server*'s `tts` module, and only for those inputs for which the TTS's built-in [Misaki](https://github.com/hexgrad/misaki) phonemizer fails.\n  - In practice, that is for out-of-dictionary words in English, as well as for some non-English languages.\n\n*Using Raven does **not** need admin rights.*\n\n- All the apps are regular userspace apps that you can run as a regular user.\n\nIf you get a **permission error** when trying to run `pdm`, try replacing \"`pdm`\" with \"`python -m pdm`\".\n\nFor example, instead of:\n\n```\npdm install\n```\n\nrun the command:\n\n```\npython -m pdm install\n```\n\nThis works because PDM is just a Python module. This will be allowed to run if `python` is allowed to run.\n\nSimilarly, Raven apps are just Python modules, and can be run via Python, as follows. Full list as of Raven v0.2.5:\n\n```\nCommand                                Replacement\n\nraven-visualizer                  →    python -m raven.visualizer.app\nraven-importer                    →    python -m raven.visualizer.importer\nraven-librarian                   →    python -m raven.librarian.app\nraven-arxiv2id                    →    python -m raven.tools.arxiv2id\nraven-arxiv-download              →    python -m raven.tools.arxiv_download\nraven-burstbib                    →    python -m raven.tools.burstbib\nraven-dehyphenate                 →    python -m raven.tools.dehyphenate\nraven-csv2bib                     →    python -m raven.tools.csv2bib\nraven-wos2bib                     →    python -m raven.tools.wos2bib\nraven-pdf2bib                     →    python -m raven.tools.pdf2bib\nraven-server                      →    python -m raven.server.app\nraven-avatar-settings-editor      →    python -m raven.avatar.settings_editor.app\nraven-avatar-pose-editor          →    python -m raven.avatar.pose_editor.app\nraven-check-cuda                  →    python -m raven.tools.check_cuda\nraven-check-audio-devices         →    python -m raven.tools.check_audio_devices\nraven-minichat                    →    python -m raven.librarian.minichat\n```\n\n\n### Check that CUDA works (optional)\n\nOnce you have installed Raven with GPU compute support, you can check if Raven detects your CUDA installation:\n\n```bash\nraven-check-cuda\n```\n\nThis command will print some system info into the terminal, saying whether it found CUDA, and if it did, which device CUDA is running on.\n\nIt will also check whether the `cupy` library loads successfully. This library is needed by the [spaCy](https://spacy.io/) natural language analyzer (so that too can run on GPU).\n\nExample output:\n\n```\nINFO:raven.tools.check_cuda:Raven-check-cuda version 0.2.3\nChecking dependencies...\n1. PyTorch availability check [SUCCESS] ✅\n2. CUDA device availability check [SUCCESS] ✅ (Using NVIDIA GeForce RTX 3070 Ti Laptop GPU)\n3. CuPy \u0026 CuPyX (for spaCy NLP) [SUCCESS] ✅\n\nSystem information:\n   Python version: 3.10.12\n   OS: Linux 6.8.0-109049-tuxedo\n   PyTorch version: 2.7.0+cu126\n```\n\n### Activate the Raven venv (to run Raven commands such as `raven-visualizer` or `raven-server`)\n\nIn a terminal that sees your Python environment, navigate to the Raven folder.\n\nThen, activate Raven's venv with the command:\n\n```bash\n$(pdm venv activate)\n```\n\nNote the Bash exec syntax `$(...)`; the command `pdm venv activate` just prints the actual internal activation command.\n\n:exclamation: *Windows users note: The command `$(pdm venv activate)` needs the `bash` shell, and will **not** work in most Windows command prompts.* :exclamation:\n\nAlternatively, you can run the venv activation script directly. You can find the script in `.venv/bin/`.\n\n:exclamation: *For Linux and Mac OS X, the script is typically named `.venv/bin/activate`; for Windows, typically `.venv/bin/activate.ps1` or `./venv/bin/activate.bat`.* :exclamation:\n\nWhenever Raven's venv is active, you can use Raven commands, such as `raven-visualizer`.\n\n### Activate GPU compute support (optional)\n\nIf CUDA support is installed but not working, you can try enabling CUDA (for the current command prompt session) as follows.\n\nWith the venv activated, and the terminal in the Raven folder, run the following `bash` command:\n\n```bash\nsource env.sh\n```\n\nThis sets up the library paths and `$PATH` so that Raven finds the CUDA libraries. This script is coded to look for them in Raven's `.venv` subfolder.\n\n### Choose which GPU to use (optional)\n\nIf your machine has multiple GPUs, there are two ways to tell Raven which GPU to use.\n\nIf your system *permanently* has several GPUs connected, and you want to use a different GPU *permanently*, you can adjust the device settings in [`raven.server.config`](raven/server/config.py), [`raven.visualizer.config`](raven/visualizer/config.py), and [`raven.librarian.config`](raven/librarian/config.py).\n\nIf you switch GPUs only occasionally (e.g. a laptop that sometimes has an eGPU connected and sometimes doesn't), you can use the `CUDA_VISIBLE_DEVICES` environment variable to choose the GPU temporarily, for the duration of a command prompt session.\n\nWe provide an example script [`run-on-internal-gpu.sh`](run-on-internal-gpu.sh), meant for a laptop with a Thunderbolt eGPU (external GPU), which forces Raven to run on the *internal* GPU when the external is connected (which is useful e.g. if your eGPU is dedicated for a self-hosted LLM). On the machine where the script was tested, PyTorch sees the eGPU as GPU 0 when available, pushing the internal GPU to become GPU 1. When the eGPU is not connected, the internal is GPU 0.\n\nWith the venv activated, and the terminal in the Raven folder, run the following `bash` command:\n\n```bash\nsource run-on-internal-gpu.sh\n```\n\nThen for the rest of the command prompt session, any Raven commands (such as `raven-visualizer`) will only see the internal GPU, and `\"cuda:0\"` in the device settings will point to the only visible GPU.\n\n### Exit from the Raven venv (optional, to end the session)\n\n:exclamation: *There is usually no need to do this. You can just close the terminal window.* :exclamation:\n\nIf you want to exit from the Raven venv without exiting your terminal session, you can deactivate the venv like this:\n\n```bash\ndeactivate\n```\n\nAfter this command completes, `python` again points to the Python in your Python environment (where e.g. PDM runs), **not** to Raven's app-local Python.\n\nIf you want to also exit your terminal session, you can just close the terminal window as usual; there is no need to deactivate the venv unless you want to continue working in the same terminal session.\n\n\n# Configuration\n\nRaven is currently mostly configured via text files - more specifically, Python modules (`.py`) that exist specifically as configuration files.\n\nWe believe that `.py` files are as good a plaintext configuration format as any, but in the long term, we aim to have a GUI to configure at least the most important parts.\n\nIn the meantime: each part of the Raven constellation has its own configuration file. Each configuration file is named `config.py`.\n\nIn the documentation as well as in the source code docstrings and comments, we refer to these files by their dotted module names. The most important ones are:\n\n- `raven.visualizer.config` → [`raven/visualizer/config.py`](raven/visualizer/config.py)\n  - *Raven-visualizer* settings, including plotter and word cloud colors, and word cloud image size.\n  - Local AI model loading settings. Used if *Visualizer* is started when *Server* is not running.\n- `raven.librarian.config` → [`raven/librarian/config.py`](raven/librarian/config.py)\n  - *Raven-librarian* settings, including the AI avatar.\n  - LLM configuration for the whole Raven constellation: server URL, system prompt, AI personality settings, text generation sampler settings.\n  - The AI avatar has some more separate configuration:\n    - Avatar video postprocessor settings are configured separately, in `raven/avatar/assets/settings/animator.json`.\n      - Since finding nice-looking settings for the postprocessor requires interactive experimentation, we provide a GUI app for this. Use `raven-avatar-settings-editor` to edit `animator.json`.\n    - Avatar emotion templates are shared between all characters and configured separately, in [`raven/avatar/assets/emotions/*.json`](raven/avatar/assets/emotions/).\n      - There is usually no need to edit the emotion templates. But if you really want to, you can use the GUI app `raven-avatar-pose-editor`.\n    - Avatar image assets are loaded from [`raven/avatar/assets/characters/`](raven/avatar/assets/characters/).\n      - The default character (*Aria*, main image [`aria1.png`](raven/avatar/assets/characters/other/aria1.png)), contains an example of the additional cels needed to support all optional features of the animator, as well as the optional chat icon for *Raven-librarian*.\n    - The backdrop image is loaded from [`raven/avatar/assets/backdrops/`](raven/avatar/assets/backdrops).\n- `raven.server.config` → [`raven/server/config.py`](raven/server/config.py)\n  - AI model settings, except LLM.\n  - A low-VRAM variant is also available, for systems with 8 GB or less VRAM.\n    - `raven.server.config_lowvram` → [`raven/server/config_lowvram.py`](raven/server/config_lowvram.py)\n    - To use it, start *Raven-server* as `raven-server --config raven.server.config_lowvram`\n- `raven.client.config` → [`raven/client/config.py`](raven/client/config.py)\n  - *Raven-server* URL, shared between all client apps.\n  - Audio device selection for voice mode (TTS/STT, i.e. speech synthesizer and speech recognition).\n\nThe paths are relative to the top level of the `raven` repository (i.e. to the directory this README is in).\n\nFor more, see the documentation for the individual constellation components (Visualizer, Librarian, Server).\n\n\n# Uninstall\n\n```bash\npython -m pip uninstall raven-visualizer\n```\n\nOr just delete the venv, located in the `.venv` subfolder of the Raven folder.\n\nAI models auto-install themselves elsewhere:\n\n- The THA3 AI animator (of *Raven-avatar*) is auto-installed in the `raven/vendor/tha3/models/` subdirectory of your top-level `raven` directory.\n\n- The dehyphenator AI model (of *Raven-server*'s `sanitize` module) is auto-installed in `~/.flair/embeddings/`.\n\n- All other AI models are auto-installed from *HuggingFace Hub*.\n  - These live at the default models cache location of the [`huggingface_hub` Python package](https://pypi.org/project/huggingface-hub/), which is usually `~/.cache/huggingface/hub`.\n  - Note that this models cache is shared between many different Python-based AI apps, so removing everything is not recommended.\n\n\n# Technologies\n\nRaven builds upon several AI, NLP, statistical, numerical and software engineering technologies:\n\n- Semantic embedding\n  - AI model: [snowflake-arctic](https://huggingface.co/Snowflake/snowflake-arctic-embed-l).\n  - Engine for running embedding models: [sentence_transformers](https://sbert.net/).\n- Low-level NLP analysis for keyword extraction: [spaCy](https://spacy.io/).\n- High-dimensional clustering: [HDBSCAN](https://hdbscan.readthedocs.io/en/latest/index.html).\n- Dimension reduction: [OpenTSNE](https://opentsne.readthedocs.io/en/stable/).\n- AI-powered PDF import\n  - A large language model (LLM), such as:\n    - For machines with at least 24 GB VRAM:\n      - [Qwen3-VL-30B-A3B-Thinking](https://huggingface.co/Qwen/Qwen3-VL-30B-A3B-Thinking) (**recommended** as of 01/2026)\n      - [DeepSeek-R1-Distill-Qwen-32B](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B) (old)\n      - [Sky-T1 32B](https://huggingface.co/NovaSky-AI/Sky-T1-32B-Preview) (old)\n    - For machines with 8 GB VRAM (e.g. a laptop with an internal NVIDIA GPU):\n      - [Qwen3-VL-4B-Thinking](https://huggingface.co/Qwen/Qwen3-VL-4B-Thinking) (**recommended** as of 01/2026; punches well above its size class)\n      - [Deepseek-R1-Distill-Qwen-7B](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-7B) (old)\n      - [Llama 3.1 8B](https://huggingface.co/meta-llama/Llama-3.1-8B) (old)\n  - LLM inference server; we recommend [oobabooga/text-generation-webui](https://github.com/oobabooga/text-generation-webui) (start it with the `--api` option to let Raven see it).\n  - Communication with the LLM inference server: [sseclient-py](https://github.com/mpetazzoni/sseclient).\n- File format support\n  - BibTeX: [BibtexParser](https://bibtexparser.readthedocs.io/en/main/).\n  - Web of Science: [wosfile](https://github.com/rafguns/wosfile).\n- Avatar AI animator: THA3 [[code](https://github.com/pkhungurn/talking-head-anime-3-demo)], [[models](https://huggingface.co/OktayAlpk/talking-head-anime-3/tree/main)], [[tech report](https://web.archive.org/web/20220606125507/https://pkhungurn.github.io/talking-head-anime-3/full.html)].\n- Many more open-weight small, specialized AI models for tasks such as sentiment classification, dehyphenation, and natural language translation; see [`raven.server.config`](raven/server/config.py) for details.\n- Graphical user interface: [DearPyGUI](https://github.com/hoffstadt/DearPyGui/).\n  - \"Open\"/\"Save as\" dialog: [file_dialog](https://github.com/totallynotdrait/file_dialog), but customized for Raven, bugs fixed, and some features added (sortable view, overwrite confirmation with animated OK button, ...).\n  - Markdown renderer: [DearPyGui-Markdown](https://github.com/IvanNazaruk/DearPyGui-Markdown), but robustified for multithreaded dynamic use (programmatic creation/deletion of MD text widgets, possibly concurrently).\n  - Toolbutton icons: [Font Awesome](https://github.com/FortAwesome/Font-Awesome) v6.6.0.\n  - Word cloud renderer: [word_cloud](https://github.com/amueller/word_cloud).\n\nNote that installing Raven will auto-install dependencies into the same venv (virtual environment). This list is here just to provide a flavor of the kinds of parts needed to build a constellation like this.\n\n\n# Privacy\n\nWe believe in the principle of *privacy first*. Raven is 100% local, and never collects any user data.\n\nSome components store data on your local computer for the purpose of providing Raven's services. For example, *Raven-librarian*'s document database indexes the documents you insert into the database for the purpose of providing the search capability. The data remains in the index as long as the document is in the database. If you remove a document, the index deletes all of its data related to that document.\n\nAI components live on your local installation of *Raven-server*. In general, any data that needs to be processed by an AI component is sent to your local *Raven-server*, and the response is sent back to the client. Communication between the client and the server is **not encrypted**.\n\nIt is preferable to run both the client and the server on the same machine, so that your data is never sent over the network. Alternatively, if you can trust the devices on your local network (LAN), you can run *Raven-server* on another machine on that LAN. **Never** connect to *Raven-server* over the internet. Doing so is **not** secure; the server is simply not designed to support that use case.\n\nWhen Raven is installed, like any Python software, it pulls the Python packages it depends on from [PyPI](https://pypi.org/), using standard Python software installation methods. See the [PyPI privacy notice](https://policies.python.org/pypi.org/Privacy-Notice/).\n\nAI models are downloaded from HuggingFace and self-hosted locally. HuggingFace may collect data (e.g. download statistics) when a model is installed; this is beyond our control. See the [HuggingFace privacy policy](https://huggingface.co/privacy).\n\nWe run the [Chroma](https://www.trychroma.com/) local search engine backend in its *telemetry off* mode.\n\nTo the best of our knowledge, any other packages we use do not collect any telemetry data.\n\nFor Librarian, we **strongly recommend** self-hosting a local LLM via [oobabooga/text-generation-webui](https://github.com/oobabooga/text-generation-webui), which can run quantized GGUF models on your GPU, also with partial offloading for low-VRAM environments. It comes with several backends out of the box, including Llama.cpp. It's easy, 100% local, and works well.\n\nHowever, at your choice, Raven should be able to connect to an OpenAI-compatible cloud LLM API (opt-in via `raven.librarian.config`). We do **not** recommend doing so, for privacy reasons; nor is supporting this use case a priority for development. Several different dialects of \"*OpenAI compatible*\" exist, so some *Raven-librarian* features (such as token count and continuing the AI's message) might not work on backends Raven has not been tested with.\n\n\n# License\n\n[2-clause BSD](LICENSE.md).\n\n\n# Acknowledgements\n\nThis work was financially supported by the [gH2ADDVA](https://www.jamk.fi/en/research-and-development/rdi-projects/adding-value-by-clean-hydrogen-production) (Adding Value by Clean Hydrogen production) project at JAMK, co-funded by the EU and the Regional Council of Central Finland.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"img/jamk_new_industry_en_blue.png\" alt=\"JAMK Institute of New Industry\" height=\"200\"/\u003e \u003cbr/\u003e\n\u003c!-- \u003cimg src=\"img/JYU-logo-en.jpg\" alt=\"University of Jyväskylä\" height=\"200\"/\u003e \u003cbr/\u003e --\u003e\n\u003cimg src=\"img/KSL-logo-en.png\" alt=\"Regional Council of Central Finland\" height=\"200\"/\u003e \u003cbr/\u003e\n\u003cimg src=\"img/co-funded-EU-horizontal.png\" alt=\"Co-funded by the European Union\" height=\"200\"/\u003e \u003cbr/\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnologicat%2Fraven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnologicat%2Fraven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnologicat%2Fraven/lists"}