NeuroScope AI is a local-first biomedical AI research console for organizing schizophrenia research experiments, running MAMMAL-compatible analysis jobs, tracking datasets, interpreting model outputs with local LLMs, and exporting structured research reports.
NeuroScope AI coordinates research projects, dataset metadata, research questions, experiment runs, MAMMAL-compatible outputs, evidence tables, local LLM interpretations, and Markdown/JSON reports. The default configuration runs entirely from local sample research fixtures without MariaDB, Ollama, or MAMMAL.
Schizophrenia research workflows can involve scattered datasets, biological signals, gene and protein markers, literature notes, model outputs, experiment parameters, and interpretation notes. NeuroScope AI organizes those pieces into a reproducible local research operations console.
- Dataset registry for synthetic or real research datasets.
- Research question tracking and experiment run metadata.
- MAMMAL adapter with deterministic sample mode and configured-command mode.
- Local Ollama-compatible interpretation layer with deterministic fallback.
- Evidence engine for marker normalization, evidence ranking, grouping, uncertainty flags, and research-safe summaries.
- Markdown and JSON report exports.
- MariaDB-ready schema for deployment.
NeuroScope AI is for research workflow organization and model output interpretation. It is not a medical device, not clinical decision support, does not diagnose schizophrenia, does not recommend treatment, and does not evaluate individual patient risk. Outputs require review by qualified researchers or clinicians.
The backend uses FastAPI, Pydantic, a MariaDB-ready data layer, a MAMMAL command adapter, an Ollama-compatible local LLM interpreter, an evidence engine, and a report exporter. The frontend uses React, TypeScript, Vite, Tailwind CSS 3, lucide-react icons, and the plain fetch API.
Environment variables:
MAMMAL_ENABLED=false
MAMMAL_COMMAND=
MAMMAL_WORKDIR=./runs
MAMMAL_TIMEOUT_SECONDS=300When disabled, the adapter returns deterministic sample research fixtures. When enabled, it writes an input config JSON into a controlled run folder, executes only the trusted command configured in .env, captures stdout/stderr, enforces a timeout, and keeps generated files inside MAMMAL_WORKDIR.
Environment variables:
OLLAMA_BASE_URL=http://localhost:11434
INTERPRETER_MODEL=gemma4:e4b
WORKER_MODEL=gemma4:e2b
ENABLE_LLM_INTERPRETATION=falseIf local interpretation is disabled or Ollama is unavailable, NeuroScope AI returns a deterministic interpretation with a research question summary, dataset summary, signal summary, candidate biological evidence, uncertainty notes, suggested next research steps, and a safety note.
The deployment data model targets MariaDB with InnoDB, utf8mb4, JSON fields, indexes, and foreign keys. Application SQL uses parameterized statements. There are no raw SQL execution endpoints.
SQL files live in db/ and use database name neuroscope_demo with documentation examples for user neuroscope_user.
Local fixtures live in sample_data/ and are synthetic research fixtures. They include schizophrenia research themes such as gene expression signal review, neuroinflammation evidence notes, synaptic pathway candidate markers, dopamine/glutamate pathway notes, and polygenic risk discussion at research level. They contain no patient identifiers.
The dataset registry stores dataset name, type, organism/reference context, source notes, storage path, and metadata JSON when the database is enabled. In local development mode, the API returns sample research fixtures.
Runs track project, dataset, research question, runner type, status, parameters, timestamps, raw/parsed outputs, interpretation, evidence, and export metadata.
The evidence engine normalizes marker names, ranks evidence items by score, groups by evidence type, summarizes candidate markers, flags low-confidence or incomplete evidence, and emits research-safe summaries.
Reports are written to REPORT_OUTPUT_DIR as:
reports/latest_run_report.mdreports/latest_run_report.json
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest
npm install
npm run buildCREATE DATABASE neuroscope_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'neuroscope_user'@'localhost' IDENTIFIED BY 'change_this_password';
GRANT ALL PRIVILEGES ON neuroscope_demo.* TO 'neuroscope_user'@'localhost';mysql -u neuroscope_user -p neuroscope_demo < db/schema.sql
mysql -u neuroscope_user -p neuroscope_demo < db/seed_research_demo.sqlollama pull gemma4:e4b
ollama pull gemma4:e2bSet ENABLE_LLM_INTERPRETATION=true only after Ollama is available.
Set MAMMAL_ENABLED=true, set MAMMAL_COMMAND to a trusted local command, and keep MAMMAL_WORKDIR pointed to a controlled local folder. Do not execute untrusted scripts.
source .venv/bin/activate
uvicorn backend.server:app --reloadnpm install
npm run devpython -m pytest
npm run buildKey endpoints include /health, /api/system/status, /api/projects, /api/datasets, /api/questions, /api/runs, /api/runs/{run_id}/start, /api/runs/{run_id}/interpret, /api/runs/{run_id}/evidence, /api/reports/{run_id}/export, and /api/sample/overview.
No authentication is included for local development. Add authentication, authorization, HTTPS, access controls, audit logging, backup policies, and secret management before public deployment.
No cloud APIs are required. Data remains local unless external services are explicitly configured by the user. Real biomedical data may be sensitive and requires appropriate governance.
backend/ FastAPI application, adapters, evidence engine, reports
frontend/ React TypeScript console
db/ MariaDB schema and seed SQL
sample_data/ Synthetic research fixtures
tests/ Service-free test suite
Apache License 2.0, Copyright 2026 Jose Perez.
See ATTRIBUTION.md.