zettabrain-teams 0.2.5

Multi-user RAG server with team access control — built on zettabrain-rag

ZettaBrain Teams

Multi-user RAG server with team access control — the enterprise layer built on zettabrain-rag.

Fully self-hosted, no cloud dependencies, runs entirely on your own infrastructure.

---

Features

Access Control

• JWT-based login with system-wide admin and user roles
• Teams with per-member manager / member / viewer roles
• Admins can create, deactivate, and delete users
• Forced password change on first login

Multi-Tenant RAG

• Per-team isolated document collections (separate ChromaDB store per team)
• Per-team BM25 keyword index — IDF computed exclusively from each team's corpus, eliminating cross-team document leakage
• Hybrid retrieval: semantic MMR + BM25 keyword search + FlashRank re-ranking
• In-UI document ingestion — set a docs folder per team and click Ingest Docs
• Incremental ingestion with MD5 hash tracking (re-ingests only changed files)

Active Directory / LDAP

• Connect to any Active Directory or LDAP server from the admin panel
• Test connection, run user searches, and preview results before importing
• Import AD users directly into teams with a chosen role
• Configurable base DN, bind credentials, and user filter

ZettaBrain Verified — Answer Provenance

• Every chat answer produces a cryptographically signed provenance bundle
• Bundle covers: SHA-256 of the query, SHA-256 of each retrieved chunk, SHA-256 of the answer, model identifier, and team ID
• Signed with an Ed25519 key generated at first server start and stored at /opt/zettabrain-teams/data/server_signing.key
• Admin UI shows a 🛡 Verify button on every audit log entry — one click confirms the answer bundle has not been altered
• Public key exposed at GET /api/admin/keys/public for out-of-band verification

Audit Log

• Every query recorded with: user, team, query text, response preview, confidence score, duration, model, chunk count
• Full date-range filtering (last 24h / 3d / 7d / 30d / all time / custom)
• Provenance signature included in CSV export
• Admin-only access

Admin Portal

• Dedicated /admin URL with sidebar navigation
• Dashboard with live stats: users, teams, total queries, average confidence
• System config panel — change LLM/embed models, Ollama host from the UI
• Pull new Ollama models directly from the admin panel
• One-page web UI for both chat portal and admin console

---

🤖 Hybrid LLM Support

ZettaBrain Teams supports three LLM providers with full hybrid mode capability — mix and match any LLM with any embedding provider:

Provider	LLM	Embeddings	Cost	When to Use
Ollama	✅	✅	Free (self-hosted)	Privacy-first, no internet, full control
OpenAI	✅	✅	Pay-per-token	Best quality, fastest, easy setup
Claude	✅	❌	Pay-per-token	Longer context, safer outputs

Hybrid Mode Examples

Mix providers for optimal cost/performance:

1. Cost-Optimized: Ollama embeddings (free) + OpenAI LLM (cheap queries)
2. Quality-First: OpenAI embeddings (best search) + Claude LLM (safest answers)
3. Full Cloud: OpenAI embeddings + OpenAI LLM (easiest setup)
4. Full Local: Ollama embeddings + Ollama LLM (completely private)

Configuration

1. Go to Admin → System Config
2. Select LLM Provider from dropdown (Ollama / OpenAI / Claude)
3. Select Embedding Provider (Ollama / OpenAI) — can be different!
4. Enter API keys for cloud providers
5. Choose model variants
6. Click Save Settings

Cost Warning ⚠️

OpenAI and Claude charge per token:

• 1 token ≈ 0.75 words
• Average query: 500 input + 200 output tokens
• Example costs: GPT-4o Mini ($0.15/$0.60 per 1M), Claude Sonnet ($3/$15 per 1M)
• Monitor usage in the Audit Log — every query shows provider and model
• Set up billing alerts in provider dashboards

Getting API Keys

OpenAI:

1. Visit https://platform.openai.com/api-keys
2. Create new secret key (starts with sk-proj-...)
3. Add billing credits: https://platform.openai.com/settings/organization/billing/overview

Claude / Anthropic:

1. Visit https://console.anthropic.com/settings/keys
2. Create new API key (starts with sk-ant-...)
3. Add billing credits: https://console.anthropic.com/settings/billing

Switching Providers

Changing LLM Provider ✅

Safe - No re-ingestion required

You can freely switch between Ollama, OpenAI, and Claude for the LLM Provider without any data migration.

Changing Embedding Provider ⚠️

CRITICAL - Re-ingestion REQUIRED

If you change the Embedding Provider, you MUST re-ingest all documents:

1. Go to Admin → Teams & Storage
2. Expand your team
3. Click Clear Vector Store (this deletes existing embeddings)
4. Click Ingest Docs (this creates new embeddings with the new provider)

Why? Different embedding providers produce different vector dimensions:

• Ollama (nomic-embed-text): 768 dimensions
• OpenAI (text-embedding-3-small): 1536 dimensions
• OpenAI (text-embedding-3-large): 3072 dimensions

ChromaDB collections have a fixed dimension size. Mixing embeddings from different providers will cause "dimension mismatch" errors.

The UI will warn you before saving if you change the embedding provider.

---

Quick install (Linux server, run as root)

# 1. Install pipx if needed
python3 -m pip install pipx && python3 -m pipx ensurepath

# 2. Install zettabrain-teams
pipx install git+https://github.com/zettabrain/zettabrain-teams

# 3. Run the one-command setup (installs Ollama, pulls models, creates systemd service)
sudo zettabrain-teams-setup

That's it. The setup script:

• Installs Ollama if not present
• Interactively selects LLM and embedding models (defaults: llama3.1:8b + nomic-embed-text)
• Creates /opt/zettabrain-teams/{data,chromadb,certs}
• Registers and starts a zettabrain-teams systemd service

Then open http://<your-server-ip>:7861 in a browser.
Default credentials: admin / P@ssword! (you will be prompted to change on first login).

---

Setup options

sudo zettabrain-teams-setup \
  --port  7861 \
  --llm   llama3.1:8b \
  --embed nomic-embed-text \
  --no-systemd        # skip systemd, start manually instead

---

Starting / stopping

# Managed by systemd after setup
sudo systemctl start   zettabrain-teams
sudo systemctl stop    zettabrain-teams
sudo systemctl restart zettabrain-teams
sudo journalctl -u zettabrain-teams -f   # live logs

# Or start manually (dev / testing)
zettabrain-teams --port 7861

---

Firewall

Open port 7861 on your firewall or cloud security group so users can reach the UI.

AWS example:

aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxxxxx \
  --protocol tcp --port 7861 --cidr 0.0.0.0/0

UFW example:

sudo ufw allow 7861/tcp

---

Admin workflow

1. Log in at http://<ip>:7861 with admin + your password
2. Admin → Users & LDAP — create user accounts or import from Active Directory
3. Admin → Teams & Storage — create a team, expand it, add users with roles, set the docs folder path
4. Click Ingest Docs in the team card to index documents from the configured folder
5. Admin → Audit Log — review all queries, filter by date, verify answer provenance, export CSV
6. Users log in at http://<ip>:7861, select their team from the sidebar, and start chatting

---

Active Directory setup

In Admin → Users & LDAP, fill in:

Field	Example
LDAP URL	ldap://dc.company.local:389
Base DN	DC=company,DC=local
Bind DN	CN=svc-account,OU=Service Accounts,DC=company,DC=local
Bind Password	your service account password
User Filter	(&(objectClass=user)(sAMAccountName=*))

Use Test Connection to verify, then Search Users to preview, then Import Selected to add users to a team.

---

ZettaBrain Verified — verification workflow

Every chat answer is stored with a provenance signature. To verify:

In the UI:

1. Go to Admin → Audit Log
2. Click 🛡 Verify on any log entry with a signature
3. A green ✓ Valid or red ✗ Invalid result appears inline

Via API (out-of-band):

# Get server public key
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:7861/api/admin/keys/public

# Verify a specific log entry
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:7861/api/admin/audit/42/verify

The private key never leaves /opt/zettabrain-teams/data/server_signing.key. Back this file up — losing it means existing signatures can no longer be verified.

---

Configuration

/opt/zettabrain-teams/teams.env is written on first setup:

Variable	Default	Description
ZBT_PORT	7861	Server port
ZETTABRAIN_LLM_MODEL	llama3.1:8b	Default Ollama LLM model
ZETTABRAIN_EMBED_MODEL	nomic-embed-text	Default Ollama embed model
OLLAMA_HOST	http://localhost:11434	Remote Ollama if not local
ZBT_JWT_SECRET	auto-generated	JWT signing secret
ZBT_TOKEN_EXPIRE	480	Token expiry in minutes
ZBT_TLS_CERT	—	Path to TLS cert (enables HTTPS)
ZBT_TLS_KEY	—	Path to TLS private key

All variables can also be overridden via shell environment. The admin System Config panel in the UI provides full control over provider selection (Ollama/OpenAI/Claude), model selection, and API keys — no need to edit files manually.

---

Requirements

• Linux (Ubuntu 20.04+ recommended)
• Python 3.9+
• 8 GB RAM minimum (16 GB recommended for llama3.1:8b)
• ~10 GB disk for models

GPU is optional — Ollama runs in CPU-only mode if no GPU is detected.

---

Architecture

zettabrain-teams (port 7861)
├── FastAPI + SQLModel (SQLite)        — users, teams, audit log, system config
├── JWT auth + bcrypt                  — login / token / role enforcement
├── Active Directory / LDAP connector  — AD import + auth
├── ChromaDB (per team)                — /opt/zettabrain-teams/chromadb/<slug>/
├── BM25 index (per team)              — <slug>/bm25_index.pkl (team-scoped IDF)
├── Ed25519 signing key                — /opt/zettabrain-teams/data/server_signing.key
├── llm_factory                        — provider abstraction (Ollama/OpenAI/Claude)
└── zettabrain-rag                     — hybrid_retrieve(), RAG prompt, embeddings
        ├── Ollama (port 11434)        — LLM + embeddings (fully local)
        ├── OpenAI API                 — Cloud LLM + embeddings (requires API key)
        └── Anthropic API              — Cloud LLM (requires API key)

---

Upgrading

pipx upgrade zettabrain-teams
# or reinstall from GitHub for latest commit:
pipx reinstall zettabrain-teams
sudo systemctl restart zettabrain-teams

Database migrations run automatically on startup — existing data is preserved.