Local model
Qwen3-4B 4-bit runs on the Mac for answer generation.
Python · MLX · mlx-lm PRODUCT AND ENGINEERING OVERVIEW CURRENT BUILD · 24 OCTOBER 2026
System architecture.
From authorized Saudi source material to a cited answer in AL-Nexus. This is the architecture running on the local Apple silicon Mac and its temporary public demo.
01 / SYSTEM MAP
Four layers, one answer
Evidence is prepared first. The model reads relevant passages when a question arrives.
01KNOWLEDGE
Source material
Research notes and authorized article URLs, PDFs and text files.
02PREPARATION
Ingest and index
Extract, normalize, preserve provenance and revisions, then rankable passages.
03INTELLIGENCE
Answer engine
Route the question, retrieve evidence, generate with Qwen and check the draft.
04EXPERIENCE
AL-Nexus
Local Python API, browser chat, streaming and a source popup.
Permanent local knowledge
SQLite, research notes, indexed passages, dated facts and prices.
Temporary web evidence
SearXNG search-result snippets are used for gaps but are not added to the library.
02 / BUILD HISTORY
What we built and the tools used
The live system and the experiments are shown separately.
Attributed notes
Short reviewed summaries with source links and source types.
Research notes · metadata · human reviewAuthorized sources
Exact approved URLs and local PDF/TXT, with permissions, metadata, duplicate and revision handling.
ingest_sources.py · PyMuPDF · SQLite · SHA-256Searchable passages
Arabic-friendly character n-gram ranking over overlapping chunks.
build_index.py · scikit-learn · NumPy · joblibChecked answers
Retrieval, source-bound answers, citations, Arabic rendering and evidence checks.
ask_history.py · retrieval.py · answer_guard.pyDated facts and prices
Reviewed snapshots and observations keep time, place and units attached to claims.
current_facts.py · price_answers.py · JSONWeb fallback
When local evidence fails, search result excerpts may support a clearly marked answer.
SearXNG · Docker / Colima · WikimediaLoRA evaluation
Adapters were trained and compared; the base model remains active because V3 showed no reliable gain.
mlx-lm · build_training_v3.py · evaluate_v3.pyTests and benchmarks
Unit tests and question sets guide repairs. The last frozen local-source set reached 137/200 grounded answers.
unittest · 200-question set · 40 adversarial promptsChat and demo
Browser chats and notebooks, private mode, a temporary public URL and GitHub backup.
web_app · chat_server.py · Cloudflare · GitHub03 / RUNTIME FLOW
Question to answer
Each answer follows a route appropriate to the question and available evidence.
01AL-Nexus → chat_server.py
Message arrives
The browser sends the question, response mode and private-chat flag to the local Python server.
02chat_server.py → content_policy.py / small_talk.py
Request is checked
The server validates its size and accepts one model job at a time. Policy, greetings and web-capability questions are routed early.
03price_answers.py / current_facts.py / retrieval.py
Evidence route is selected
Dated prices or current facts can return directly. Otherwise, the local index finds relevant passages with subject and location filters.
04verified_answers.py / Qwen3-4B via MLX
A draft is generated
A source-bound answer is used where available; otherwise Qwen3-4B receives the selected evidence and writes a cited draft.
05answer_guard.py / arabic_render.py
Draft is checked
Citations and known risky details such as dates, places and prices are checked. Supported sentences can be retained from a partial draft.
06web_fallback.py → SearXNG / Wikimedia
If local evidence falls short
Non-private chat searches SearXNG or Wikimedia excerpts. The answer is checked again and marked as based on unreviewed search results. Private chat does not search the web.
07chat_server.py → AL-Nexus
Final answer is delivered
The server returns checked text, status and cited links. The browser replaces any provisional tokens and offers a compact Sources popup.
04 / TRUST BOUNDARIES
What each source means
Local library
Authorized ingestion is deliberate. Original bytes, metadata, page references and revisions stay in SQLite. Adding a source requires a new index build.
Web result
A cited search snippet is not a reviewed full article. It is temporary and never silently becomes training data or a permanent source.
Private chat
Messages remain in the current browser tab and web fallback is disabled. Normal chats and notebooks live in that browser's local storage.
Model and benchmark
Flash, Nexus and El Shaiek share one base model with different answer budgets. The 68.5% benchmark is a project test, not a general intelligence score.