aipackage/README.md

# Nexus One AI Platform Package

Nexus One AI is a private, on-prem AI platform package for customer-controlled
deployment. This repository contains the platform code, deployment assets, and
build paths used to install, provision, and operate the appliance.

This repository is the source of truth for the Nexus One AI platform package,
including installer flows, deployment roles, portal assets, backend services,
licensing enforcement, and the bootable ISO build path.

The ISO is one delivery surface. The online Server installer stays small by
pulling this package and the selected tier payload during setup. Offline
installers embed their approved platform payload and starter models, while
large models are delivered as separate signed model packs.

## Product Structure

Nexus One AI, Powered by Cezen, has two product categories. This is a
packaging/labeling structure, not a rewrite — the existing installer,
license engine, and Server tiers below are unchanged.

```text
Nexus One AI
Powered by Cezen
├── Nexus One AI Workstation      (personal AI appliance, 1-3 users, 5 max)
│
└── Nexus One AI Server           (shared multi-user platform)
      ├── Server S     (was: Starter)
      ├── Server M     (was: Entry / Basic)
      ├── Server L     (was: Pro)
      └── Server Max   (was: Max)
```

- **Nexus One AI Workstation** is a personal AI appliance for AI developers,
  data scientists, researchers, universities, innovation labs, CXOs, and
  individual knowledge workers — typically NVIDIA DGX Spark, RTX 5090
  Workstation, or RTX PRO 6000 Workstation hardware. It is not a shared
  server: no HA, no server-redundancy expectations. Internally it is an
  additive `workstation` category in the license engine (`category:
  "workstation"`), kept structurally separate from the Server tier ladder.
- **Nexus One AI Server** is the existing four-tier shared platform
  (Server S/M/L/Max — internal license slugs `starter/basic/pro/max` are
  unchanged; Server S/M/L/Max are the new commercial labels for the same
  four tiers). See [Section 6](#6-tier-and-packaging-guide) and
  [Section 8](#8-features-by-tier).

## Installer Release Architecture

Nexus One AI uses four bootable ISO products built from this shared codebase:

| ISO | Connectivity | Selection and payload | Current status |
|---|---|---|---|
| Online Universal Server | Internet required during setup | Hardware/license preflight followed by Server S, M, L, or Max selection | Existing build path; validation continues |
| Offline Workstation | No internet required | Fixed Workstation category with the complete local platform and approved Workstation starter models | In development |
| Offline Server S/M | No internet required | Server S or M selected from hardware and license; small/medium local payload | Planned |
| Offline Server L/Max | No internet required | Server L or Max selected from hardware and license; enterprise platform payload | Planned |

Large Server L/Max models are not bootable installers and are not duplicated
inside the ISO. They are separate signed model packs imported from approved USB
or external storage after platform installation. The same signed offline update
format will patch already-installed systems across all four ISO products; fixed
updates are also rolled into later ISO rebuilds for clean installations.

Expected removable-media guidance:

- Online Universal Server ISO: approximately 2-4 GB; use an 8 GB or larger USB.
- Offline Workstation ISO: currently estimated at 35-50 GB; use a 64 GB minimum,
  with 128 GB recommended for reliable flashing and future growth.
- Offline Server S/M and L/Max sizes will be recorded only after their payloads
  are built and deduplicated; do not publish speculative final sizes.
- Large model packs may range from a few gigabytes to hundreds of gigabytes and
  should normally be carried on dedicated external storage.

An ISO is not labelled offline merely because the source tree is embedded. It
must pass a clean installation with network interfaces disconnected, payload
integrity verification, reboot persistence, and service/model validation.

## Product Collateral

Technical buyer-facing collateral lives in `docs/` for reuse in customer
evaluation, partner enablement, and internal technical review.

- `docs/README.md`
- `docs/Nexus_One_AI_Datasheet.docx`
- `docs/Nexus_One_AI_Datasheet.pdf`
- `docs/architecture-overview.svg`
- `docs/technical-service-flow.svg`

## Why Nexus One AI

- Private AI platform designed for customer-controlled infrastructure.
- Packaged stack for portal access, local inference, document retrieval, and observability.
- Deployment paths for both bootable ISO installs and scripted Ubuntu server installs.
- Tiered packaging that scales from contained pilots to larger multi-team deployments.
- Stronger technical buyer story than a simple demo stack because admin, audit, backup, and readiness surfaces are included.

## Architecture Snapshot

![Nexus One AI architecture overview](docs/architecture-overview.svg)

## Technical Service Flow

![Nexus One AI technical service flow](docs/technical-service-flow.svg)

## Visual Overview

### Package Positioning

![Nexus One AI package overview](docs/nexus-one-ai-package-overview.jpg)

### Opportunity View

![Nexus One AI opportunity view](docs/nexus-one-ai-opportunity.jpg)

### Tier Comparison

![Nexus One AI tier comparison](docs/nexus-one-ai-tier-comparison.jpg)

## 1. Choose The Deployment Path

| Scenario | Use This Path |
|---|---|
| New appliance/server with ISO | Boot from the Nexus One AI ISO and complete first-boot setup. |
| PSU/offline field install by pendrive | Boot the ISO from USB, enter license/tier details during first boot, upload large models later if needed. |
| Existing Ubuntu server | Clone this repo and run the feasibility check before installing. |
| Lab test without GPU | Use Multipass/VM and expect GPU services to be limited. |

## 2. Bootable ISO Deployment

The bootable ISO filename is:

```text
cezen-ai-ubuntu2204.iso
```

The canonical repo location for that artifact is:

```text
cgit/autoinstall/cezen-ai-ubuntu2204.iso
```

If you build on a Linux server from inside the repo, the full output path will be:

```text
<repo-root>/autoinstall/cezen-ai-ubuntu2204.iso
```

Example from the current Ubuntu build host:

```text
/home/cezen/aipackage/cgit/autoinstall/cezen-ai-ubuntu2204.iso
```

1. Flash the Nexus One AI ISO to a USB drive or attach it to the VM/server.
2. Boot the server from the ISO.
3. On the Ubuntu installer network screen, choose DHCP or the final static IP.
4. Let Ubuntu finish installation and reboot.
5. On first boot, open the setup URL shown on the server console:

```text
http://<server-ip>
```

6. Complete the setup wizard:
   - Network: DHCP or static IP.
   - License & customer details: customer name, project/customer ID, contact email, license key, support date.
   - Tier: Server S, Server M, Server L, or Server Max (internal slugs
     unchanged: `starter`/`basic`/`pro`/`max`).
   - Tools: keep defaults unless a component should be skipped.
7. Click **Start Installation**.
8. Wait for Phase 1 NVIDIA driver setup. The server may reboot once.
9. After reboot, Phase 2 continues automatically through `cezen-phase2.service`.
10. Monitor progress:

```bash
ssh cezen@<server-ip>
sudo journalctl -fu cezen-phase2.service
sudo tail -f /var/log/cezen-install.log
```

11. Open the portal after install:

```text
http://<server-ip>/
```

## 3. Field Deployment From USB

Use this when a team physically visits the site and installs from a USB drive.

1. Carry the latest ISO on a bootable USB drive.
2. Boot the PSU/customer server from the USB.
3. Configure the final network on the Ubuntu installer screen.
4. After first boot, use either:
   - Browser setup at `http://<server-ip>`, or
   - Physical console terminal wizard if no browser is available.
5. Enter customer/license details during setup. If the final license key is not available, leave it blank; the system records the install as field staging/evaluation.
6. Select the commercial tier sold to the customer.
7. Complete install.
8. Upload or pull large models later after bandwidth/storage is confirmed.

License details are stored on the installed server at:

```text
/opt/cezen/license.json
```

Installer selections are stored at:

```text
/opt/cezen/install.conf
```

Whenever a new ISO is rebuilt, check this file path first:

```text
autoinstall/cezen-ai-ubuntu2204.iso
```

## 4. Hardware Feasibility And Pre-Sales Check

Run this before quoting, committing a tier, or installing on customer-owned hardware.

```bash
git clone https://cgit.cezentech.com/jinojose/aipackage.git
cd aipackage
sudo bash install.sh --feasibility-only
```

The report checks CPU, RAM, disk, NVIDIA GPU/VRAM, and likely supported features.
It writes JSON to:

```text
/opt/cezen/feasibility.json
```

If `/opt/cezen` is not writable, it writes:

```text
./feasibility.json
```

Recommended interpretation:

| Result | Meaning |
|---|---|
| `core` | Portal/backend only; no local model serving recommended. |
| `cpu-ai` | CPU-only RAG/chat possible, but constrained. |
| `gpu-starter` | Starter GPU deployment. |
| `gpu-standard` | Entry tier style deployment. |
| `gpu-pro` | Pro tier candidate. |
| `gpu-max` | Max tier candidate. |

## 5. Existing Server Installation

After feasibility check, install on an existing Ubuntu server:

```bash
sudo bash install.sh --software-only --profile=auto
```

For small systems or slow customer networks, skip default model downloads:

```bash
sudo bash install.sh --software-only --profile=cpu-ai --skip-model-pull
```

To force a commercial tier:

```bash
sudo bash install.sh --software-only --tier=starter
sudo bash install.sh --software-only --tier=basic
sudo bash install.sh --software-only --tier=pro
sudo bash install.sh --software-only --tier=max
```

The installer warns if selected tier and hardware recommendation do not match.
The selected tier still wins, because the sale/license decision is commercial.

## 6. Tier And Packaging Guide

**Nexus One AI Server** (shared, multi-user; internal license slug in parentheses):

| Server Tier | Target Hardware | Typical Use | Default Models |
|---|---|---|---|
| Server S (`starter`) | 1 GPU around 24-32 GB VRAM, or constrained CPU system | Small team, RAG/admin portal, light chat | `phi3:mini`, `nomic-embed-text` |
| Server M (`basic`) | 1 RTX Pro 6000 class GPU, around 48-96 GB VRAM | Department deployment | `llama3.1:8b`, `mistral:7b`, `codellama:13b`, `nomic-embed-text` |
| Server L (`pro`) | 2+ high VRAM GPUs | Multi-team deployment, heavier coding/RAG/fine-tuning workflows | Server M models plus `llama3.1:70b`, `mixtral:8x7b`, `deepseek-coder-v2:16b` |
| Server Max (`max`) | 4-8 enterprise GPUs such as H100/H200/A100 class | Enterprise deployment, large models, high concurrency | Server L models plus `llama3.1:405b`, `mixtral:8x22b` |

**Nexus One AI Workstation** (personal appliance; internal category `workstation`,
kept outside the Server ladder — see [Product Structure](#product-structure)):

| Category | Target Hardware | Typical Use | Users |
|---|---|---|---|
| Workstation (`workstation`) | NVIDIA DGX Spark, RTX 5090 Workstation, or RTX PRO 6000 Workstation | Local chat, personal RAG, prompt studio, document intelligence | 1-3 active, 5 max |

Build a dedicated Workstation ISO with:

```bash
bash autoinstall/build-iso-workstation.sh
```

This produces `autoinstall/cezen-ai-workstation-ubuntu2204.iso`, using
`user-data-workstation` — same compact single-GPU hardware profile and
Ansible playbook (`ansible/starter.yml`) as Server S under the hood, but a
distinct `workstation` tier marker (`/opt/cezen/tier`) so the installed
system brands and entitles itself as Nexus One AI Workstation. The first-boot
wizard (`firstboot-setup.sh`) detects `CEZEN_TIER=workstation` and skips the
Server tier-selection step entirely — Workstation is never offered as a
Server S/M/L/Max choice. See [Migration Notes](../MIGRATION_NOTES.md) for
what is and isn't wired up yet (live portal branding still needs a manual
`CEZEN_TIER` override on the deployed service — see below).

Large models can be pulled later. The ISO does not need to contain them.

```bash
bash models/pull-models.sh --tier=starter
bash models/pull-models.sh --tier=basic
bash models/pull-models.sh --tier=pro
bash models/pull-models.sh --tier=max
```

## 7. Platform Features

Nexus One AI includes these application features through the portal and backend:

| Feature | What It Does |
|---|---|
| Secure admin portal | Browser UI for setup, chat, tools, users, models, reports, and system status. |
| Authentication and sessions | JWT login, role-aware admin access, brute-force lockout, active session tracking. Portal nav label unchanged (no current single nav item maps to "Enterprise Authentication" — see [Section 15](#15-platform-roadmap)). |
| User and team management | Admin-managed users, teams, roles, and account status. |
| AI Workspace *(was: Private Chat)* | On-prem chat over local or routed models. |
| RAG knowledge base | Upload documents, index them into ChromaDB, and query private knowledge. |
| Prompt library | Government/enterprise prompt templates grouped by use case. Kept as "Prompt Library" — the portal already has a distinct "Prompt Studio" authoring tool, so this label was not renamed to avoid duplicate nav entries. |
| Model Catalog *(was: Model Management)* | View local models, pull Ollama models, upload GGUF models, and track model status. |
| Model router | Route requests by rule to local, GPU, or external model endpoints on supported tiers. |
| Document intelligence | Parse, summarize, and extract structured information from documents. |
| Meeting assistant | Transcript/audio processing, summaries, decisions, action items, and follow-ups. |
| Agent Studio *(was: Agent Builder)* | Create and run configured agents, including scheduled agent jobs. |
| Workflow Designer *(was: Workflow Automation)* | Run portal workflows with HTTP, email, RAG, save-to-knowledge-base, and filter steps. |
| MCP & Enterprise Connectors *(was: Connectors)* | Store and sync supported data connectors (DB/folder sync today; MCP-based connectors are on the roadmap — see [Section 15](#15-platform-roadmap)). |
| Guardrails | Keyword, regex, and PII checks for safer prompts and responses. |
| Governance & Audit *(was: Analytics and Audit)* | Query logs, usage summaries, audit reports, and admin visibility. |
| Evaluation suite | Manage datasets, eval jobs, and model/prompt quality checks. |
| Fine-tuning jobs | QLoRA and advanced training paths for higher tiers. |
| API key manager | Create, list, and revoke API keys for integrations. |
| Backups and restore | Local backup, list, restore, and pre-restore safety snapshot APIs. |
| System readiness | Feasibility, license, and readiness reports for handover and support. |

## 8. Features By Tier

The backend exposes this same matrix from `GET /api/license` (now also
carrying `commercial_label` and `category` fields per tier — additive,
existing fields unchanged).

| Feature | Server S (`starter`) | Server M (`basic`) | Server L (`pro`) | Server Max (`max`) | Workstation (`workstation`) |
|---|---|---|---|---|---|
| Max users | 10 | 25 | 100 | Custom | 5 (1-3 active) |
| Portal | Yes | Yes | Yes | Yes | Yes |
| Chat / AI Workspace | Yes | Yes | Yes | Yes | Yes (local) |
| RAG knowledge base | Yes | Yes | Advanced | Advanced | Personal |
| Meeting assistant | No | Yes | Yes | Yes | No |
| Workflows | Basic | Basic | Advanced | Advanced | No |
| MCP & Enterprise Connectors | No | Limited | Yes | Yes | No |
| Model router | No | No | Yes | Yes | No |
| Governance & Audit reports | Yes | Yes | Yes | Yes | No |
| Backup and restore | Yes | Yes | Yes | Yes | Yes (local) |
| Guardrails | Basic | Basic | Advanced | Advanced | Basic |
| GPU inference | No | Optional | Yes | Yes | Yes (local) |
| Fine-tuning | No | No | QLoRA | Advanced | No |
| DeepSpeed / distributed training | No | No | No | Custom | No |
| Document intelligence / Model Catalog / Prompt Studio / API access | Per feature above | Per feature above | Per feature above | Per feature above | Yes |

Workstation is an additive, standalone category — it is not part of the
Server S/M/L/Max ladder and cannot be reached by a Server license upgrade.
See [Product Structure](#product-structure).

## 9. What Gets Installed

All tiers install the Nexus One AI portal, backend API, nginx, health/readiness
reporting, license/tier handling, and selected AI tools.

| Component | Port | Notes |
|---|---:|---|
| Nexus One AI portal | 80 | Main UI served by nginx. |
| cezen-api backend | 8080 | FastAPI backend, systemd service `cezen-api`. |
| Ollama | 11434 | Local model inference. |
| Open WebUI | 3001 | Chat UI. |
| ChromaDB | 8100 | Vector database for RAG. |
| vLLM | 8000 | OpenAI-compatible serving path, mainly Pro/Max. |
| JupyterLab | 8888 | Notebook environment. |
| MLflow | 5000 | Experiment tracking. |
| MinIO | 9001 | S3-compatible object/model storage. |
| Grafana | 3000 | Monitoring dashboard. |

## 10. Admin And Readiness APIs

| API | Purpose |
|---|---|
| `GET /api/license` | Current tier, feature matrix, and safe license metadata. |
| `GET /api/system/feasibility` | Hardware feasibility report or live fallback. |
| `GET /api/system/readiness-report` | License + feasibility + install readiness payload. |
| `GET /api/audit/report?days=7` | Audit summary for handover/admin review. |
| `GET /api/system/backups` | List local backups. |
| `POST /api/system/backups` | Create local backup. |
| `POST /api/system/backups/{name}/restore` | Restore backup with pre-restore safety snapshot. |

Backup helper:

```bash
sudo bash scripts/cezen-backup.sh backup
sudo bash scripts/cezen-backup.sh list
sudo bash scripts/cezen-backup.sh restore /opt/cezen/backups/cezen-backup-YYYYmmdd-HHMMSS.zip
```

## 11. Post-Install Checks

Run these after install:

```bash
systemctl status cezen-api --no-pager
systemctl status cezen-phase2.service --no-pager
curl -s http://localhost:8080/api/settings/branding
curl -s http://localhost:8080/api/system/feasibility
```

Check service ports:

```bash
ss -lntp
```

Check Ollama models:

```bash
curl -s http://localhost:11434/api/tags
```

## 12. Test Without A GPU

On a MacBook:

```bash
multipass launch 22.04 --name cezen-test --cpus 4 --mem 8G --disk 40G
multipass shell cezen-test
```

Inside the VM:

```bash
git clone https://cgit.cezentech.com/jinojose/aipackage.git
cd aipackage
sudo bash install.sh --feasibility-only
sudo bash install.sh --software-only --profile=auto --skip-model-pull
```

No GPU will be detected. That is expected.

## 13. Change Default Passwords Before Customer Handover

Before shipping to a customer, rotate these:

- Initial OS/admin account password.
- JupyterLab token: `/opt/cezen/.jupyter/jupyter_lab_config.py`
- MinIO credentials: `/etc/default/minio`
- Grafana admin password.
- Any temporary portal/backend admin credentials.
- Any staging license key if the final license is issued later.

## 15. Platform Roadmap

Seven enterprise capabilities planned for Nexus One AI. None of these are
implemented yet — this section documents scope and current-state dependencies
so future work builds on the right foundation. Grounded in what the current
codebase does and does not already provide (confirmed by direct inspection of
`cezen-backend/main.py`, `cezen-portal/`, and this repo).

| # | Capability | Scope | Current-state dependency |
|---|---|---|---|
| 1 | Enterprise Authentication | LDAP, Active Directory, SAML, OAuth, OIDC | Greenfield. Today's auth is username/password + JWT (`cezen-backend/main.py`), no SSO code anywhere in the stack. |
| 2 | MCP & Enterprise Connectors | SharePoint, OneDrive, SAP, Oracle, SQL, REST, GitHub, Jira, ServiceNow via MCP | Builds on today's DB/folder-sync connectors (`connectors.html`, `/api/connectors*`), which are not MCP-based. MCP is the planned future transport. |
| 3 | AI Monitoring | GPU/CPU/RAM/VRAM, latency, tokens/sec, queue depth, model usage, active sessions, health | Builds on existing `system-status.json` and `/api/metrics*` (CPU/GPU/RAM/uptime today). |
| 4 | Governance & Audit | Prompt history, model usage, compliance, PII detection, policy violations, usage reports | Builds on existing `audit.html` / `/api/audit*` (66 references in the backend today). |
| 5 | Model Catalog | Browse, install, update, rollback, versioning, recommended models | Builds on existing `models.html` / `models-admin.html` (browse/pull/upload today; no rollback/versioning yet). |
| 6 | Deployment Management | Node management, cluster health, storage, model synchronization, upgrade status, licensing overview | Greenfield for multi-node. Today's install/license flow (`install.sh`, `cezen_license.py`) is single-node. |
| 7 | Secrets Management | Secure storage for API keys, passwords, certificates, tokens, external credentials | Builds on existing API key manager (`apikeys.html` / `/api/apikeys*`); no general credential vault exists yet. |

## 16. Useful Files

```text
cgit/
├── install.sh                         # Main installer entry point
├── autoinstall/                       # ISO first-boot setup and web setup
│   ├── build-iso.sh                   # General multi-tier Server ISO builder
│   ├── build-iso-starter.sh           # Server S compact single-GPU ISO builder
│   ├── build-iso-workstation.sh       # Nexus One AI Workstation ISO builder
│   ├── user-data-starter              # Server S autoinstall config
│   ├── user-data-workstation          # Workstation autoinstall config
│   └── firstboot-setup.sh             # TTY setup wizard (skips tier menu for Workstation)
├── scripts/cezen-feasibility.sh       # Existing-server feasibility checker
├── scripts/cezen-backup.sh            # Backup/restore helper
├── ansible/
│   ├── phase1_nvidia.yml              # NVIDIA/CUDA phase
│   ├── starter.yml                    # Server S tier (also used by Workstation)
│   ├── entry.yml                      # Server M tier
│   ├── pro.yml                        # Server L tier
│   ├── max.yml                        # Server Max tier
│   └── roles/
│       ├── cezen-backend/             # FastAPI backend, cezen-api service
│       ├── cezen-nginx/               # Portal/nginx deployment
│       ├── ollama/                    # Ollama + Open WebUI
│       ├── chromadb/                  # RAG vector DB
│       ├── vllm/                      # vLLM serving
│       ├── jupyterlab/                # Notebooks
│       ├── mlflow/                    # Experiment tracking
│       ├── minio/                     # Object storage
│       └── monitoring/                # Grafana/Prometheus/DCGM
├── cezen-portal/                      # Packaged portal UI
└── models/pull-models.sh              # Pull tier-specific models
```