// technical overview

Inside ArcumAI.

A privacy-first RAG assistant for Swiss legal and fiduciary offices. ArcumAI runs a retrieval pipeline over your own documents and connects to Outlook, so professionals can query their archive from a web chat or straight from their inbox, with everything running on hardware they control.

Python 3.10+ FastAPI + NiceGUI Ollama local LLM ChromaDB + BM25 C# VSTO add-in MIT licensed

// capabilities

What the system does.

The feature set as it ships in the repository.

Hybrid RAG search. ChromaDB vector search combined with BM25 keyword search over ingested documents.
Multi-format ingestion. PDF (with OCR fallback), DOCX, MSG, EML, XLSX, and TXT.
Privacy-first by default. Local LLM via Ollama; optional cloud (Gemini) with automatic NER-based PII masking.
Outlook integration. A C# VSTO add-in intercepts mail to a designated address and returns AI replies.
Web chat UI. NiceGUI interface with authentication, history, file upload, and an admin panel.
Persistent history. Per-user chat sessions stored to disk and reachable from the sidebar.
Admin panel. User management, ingestion control, and system status.
Multi-language. Italian, English, German, and French.
Hardware profiles. Tunable for high-resource servers or low-resource laptops.
Automated tests. 134 tests across three tiers: auth, AI pipeline, bridge, and ingestion.

// architecture

How the pieces fit.

Two clients talk to one Python backend. The backend orchestrates retrieval and inference, and every persistent store stays local.

Clients

Web browser

NiceGUI chat UI

Outlook add-in

C# VSTO plugin

HTTP · WebSocket (JSON-RPC / MCP)

Python backend · main_nice.py

FastAPI + NiceGUI + OutlookBridgeManager → UserSession

Hybrid RAGvector + keyword

Local LLMsimple mode

Cloudisolated, PII-masked

AgentMCP

retrieval · queries

Data layer · on disk, no external database

ChromaDB

vector store

BM25

keyword index

users.json

accounts + sessions

inference

Inference

Ollama

local, default (e.g. llama3.2:3b)

Gemini

optional cloud, NER-masked, off by default

Ingestion runs alongside: watcher.py monitors a folder and hands new files to ingest.py for batch processing.

// data flow

The email loopback.

What happens when a message is sent to the assistant address from Outlook.

A user emails the assistant address from Outlook, and the VSTO plugin intercepts it, extracting body and attachments.
The plugin sends a virtual_loopback/send_email JSON-RPC call over WebSocket.
The bridge acknowledges and enqueues the request in a priority queue.
A worker acquires the AI semaphore and the LoopbackProcessor takes over.
Attachments are decoded and text extracted; the prompt is optimised by the local model (optionally via Gemini with NER masking).
The request is routed to RAG (no attachments) or the file reader (with attachments), then an answer is generated locally.
The response returns over WebSocket (or is stored if the client is offline), and the plugin creates a reply in the Outlook inbox.

// quick start

Up and running.

Prerequisites: Python 3.10+, Ollama with a pulled model, and optionally Tesseract OCR, Poppler, Visual Studio 2022 and .NET Framework 4.8 for the Outlook add-in.

1 · clone and set up Python

git clone https://github.com/nbrianza/ArcumAI.git
cd ArcumAI
python -m venv .venv
.venv/Scripts/activate       # Windows
# source .venv/bin/activate  # Linux / macOS
pip install -r requirements.txt

2 · configure

cp .env.example .env          # then edit with your settings

3 · ingest, then 4 · run

# place documents in data_nuovi/ then:
python ingest.py
python main_nice.py           # web UI on http://localhost:8080

// configuration

Driven by environment.

All configuration is via environment variables. These are the key ones.

Variable	Description
`PROFILE`	HIGH_RESOURCE or LOW_RESOURCE
`LLM_MODEL`	Ollama model name, for example llama3.2:3b
`GOOGLE_API_KEY`	Required only for the optional cloud (Gemini) mode
`STORAGE_SECRET`	Session storage secret, must be changed from the default

HIGH_RESOURCE

Larger models, bigger context windows, and more retrieval results for capable servers.

LOW_RESOURCE

Tuned for laptops and limited hardware, with smaller footprints throughout.

// project structure

Where things live.

ArcumAI/
├── main_nice.py              # application entry point
├── ingest.py                 # document ingestion pipeline
├── watcher.py                # folder watcher for auto-ingestion
├── src/
│   ├── ai/                   # engines, sessions, prompt optimisation, NER masking
│   ├── bridge/               # WebSocket bridge to Outlook
│   ├── ui/                   # NiceGUI interface components
│   ├── auth.py               # authentication (bcrypt)
│   ├── config.py             # configuration and hardware profiles
│   ├── database.py           # user / session database
│   ├── readers.py            # document readers (PDF, DOCX, MSG, ...)
│   └── utils.py
├── outlook-plugin/           # C# VSTO Outlook add-in
├── tests/                    # test suite (134 tests)
├── doc/                      # documentation
└── requirements.txt

// security

Built defensively.

Security posture as documented in the repository.

Local-first. By default all AI processing uses Ollama, so no data leaves the machine.
PII masking. When cloud APIs are used, NER-based masking redacts personal data before sending.
Secrets stay out of git. .env files hold API keys and secrets and are never committed.
STORAGE_SECRET required. The server refuses to start in production without one.
Authentication. bcrypt hashing, per-IP brute-force protection, and an optional shared-secret header.
Input hardening. User input is stripped of control characters and length-capped before processing.

Read the source.

The full README, configuration reference, and 134-test suite live in the repository under the MIT license.

github.com/nbrianza/ArcumAI ← Back to arcumai.ch