neurocheck / README_SETUP.md
ZeroNinerOne's picture
Upload 12 files
0e0f222 verified
|
Raw History Blame Contribute Delete
4.66 kB

NeuroCheck v9.1 β€” Local Setup Guide

Prerequisites

Software Version Download
Python 3.10+ https://python.org/downloads
Ollama Latest https://ollama.com/download
Git Any https://git-scm.com

One-Time Setup (run this once)

# 1. Clone / unzip the project, then enter it
cd neurocheck

# 2. Run the full setup script
python3 setup.py

The setup script will:

  • Create a .venv virtual environment
  • Install all Python packages from requirements.txt
  • Build the spaCy English model (en_model/)
  • Verify the NegEx negation pipeline
  • Create and initialise the SQLite database (neurocheck.db)
  • Check Ollama and pull llama3.1:8b if needed

Before First Run β€” Set Your JWT Secret

Open .env and replace the placeholder:

JWT_SECRET=CHANGE_THIS_TO_A_LONG_RANDOM_SECRET_BEFORE_RUNNING

Generate a real secret:

python3 -c "import secrets; print(secrets.token_hex(32))"

Copy the output into .env:

JWT_SECRET=a1b2c3d4e5f6...  (your generated value)

Start the Server

python3 start.py

Or manually:

.venv/bin/python -m uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

Open in Browser

URL Description
http://localhost:8000 MS Symptom Classifier
http://localhost:8000/chat-ui AI Chat (login required)
http://localhost:8000/docs Swagger API docs

Ollama Setup (for AI Chat)

Ollama runs the local LLM (Llama 3.1) that powers the chat assistant.

Install Ollama

Windows / macOS: Download from https://ollama.com/download and run the installer.

Linux:

curl -fsSL https://ollama.com/install.sh | sh

Start Ollama and Pull the Model

# Start the Ollama server (runs in background)
ollama serve

# Pull the model (4.7 GB β€” do this once)
ollama pull llama3.1:8b

# Verify it's working
ollama run llama3.1:8b "Hello"

Note: The MS Symptom Classifier (/classify) works without Ollama. Only the /chat AI assistant requires Ollama to be running.


Database

NeuroCheck uses SQLite β€” no separate database server needed.

File: neurocheck.db (created automatically by setup.py)

Tables:

Table What it stores
users Registered accounts (username, email, hashed password)
chat_sessions Each conversation linked to a user (title, timestamps)
messages Every message with role and UTC timestamp

Inspect the Database

# Open SQLite shell
sqlite3 neurocheck.db

# Inside the shell:
.tables
SELECT * FROM users;
SELECT session_uuid, title, updated_at FROM chat_sessions ORDER BY updated_at DESC;
SELECT role, content, created_at FROM messages WHERE session_uuid='<uuid>' ORDER BY id;
.quit

Project Structure

neurocheck/
β”œβ”€β”€ api/
β”‚   β”œβ”€β”€ main.py        ← FastAPI app + all endpoints
β”‚   β”œβ”€β”€ auth.py        ← JWT login / register (NEW)
β”‚   β”œβ”€β”€ database.py    ← SQLite layer (NEW)
β”‚   β”œβ”€β”€ memory.py      ← In-memory session store
β”‚   β”œβ”€β”€ agent.py       ← LangGraph AI agent
β”‚   └── rag.py         ← ChromaDB RAG knowledge base
β”œβ”€β”€ frontend/
β”‚   β”œβ”€β”€ chat.html      ← AI Chat UI (login + session sidebar)
β”‚   └── index.html     ← MS Classifier UI
β”œβ”€β”€ en_model/          ← Built by setup.py (spaCy)
β”œβ”€β”€ neurocheck.db      ← Created by setup.py (SQLite)
β”œβ”€β”€ chroma_db/         ← Created at runtime (ChromaDB)
β”œβ”€β”€ .env               ← Your config (never commit this)
β”œβ”€β”€ .env.example       ← Template
β”œβ”€β”€ setup.py           ← One-time setup script
β”œβ”€β”€ start.py           ← Start the server
└── requirements.txt

Auth Endpoints

Method URL Description
POST /auth/register Create account
POST /auth/login Get JWT token
GET /auth/me Current user info

Common Issues

spacy.errors.E050 β€” Model not found

python3 setup.py   # rebuilds en_model/

Connection refused on /chat

Ollama is not running. Start it:

ollama serve

401 Unauthorized on /chat

Your JWT token expired or you are not logged in. Open http://localhost:8000/chat-ui and log in again.

Port 8000 already in use

python3 start.py --port 8080

Database errors

python3 -c "
import os; os.environ['NEUROCHECK_DB']='neurocheck.db'
from api.database import init_db; init_db(); print('OK')
"