Introducing MAGPAI: A Tiny Transparent AI System

MAGPAI is a small, transparent educational AI model and demonstration laboratory built to make the internal path from human language to numerical representation and runtime behavior visible.

The name expands to MAG Prototype AI and is pronounced “magpie.” Its current lifecycle is educational prototype and engineering laboratory. It is implemented primarily in Python, with PyTorch selected for the core educational model demos and local examples supported by Streamlit, FastAPI, Jupyter, MkDocs Material, Pytest, pandas, matplotlib, and scikit-learn.

Open the public MAGPAI GitHub repository

MAGPAI is not a production AI model. It is a teaching platform for understanding, inspecting, running, visualizing, and explaining AI concepts through documentation, diagrams, Python code, notebooks, and local runtime demos.

The problem

AI APIs and frameworks are easy to invoke. That is good for product delivery, but it can leave engineers without an inspectable model of what happens between prompt and response.

MAGPAI addresses that gap by using a tiny, visible pipeline. Instead of asking the visitor to trust a black-box answer, it exposes the teaching path: tokenization, vocabulary lookup, vector construction, tensor shape, model-like classification, data lookup, generated chart, and response composition.

Project objective

MAGPAI aims to expose and explain:

• tokenization;
• vocabulary lookup;
• token IDs;
• vectors;
• embeddings;
• tensors;
• neural-network activations;
• training concepts;
• runtime inference;
• observability;
• enterprise safety boundaries.

Session 01 focuses on the first path from AI/ML stack orientation to tokens, token IDs, vectors, embeddings, tensors, and a chart-backed answer. It uses one repeated business question to keep each technical chapter grounded in the same visible scenario.

Current capabilities

The current repository supports a concrete introductory release rather than only a concept document.

• Presentation material: a PowerPoint deck and Diavgeia teleprompter pages walk through the path from the AI/ML stack to tokens, vectors, tensors, and a chart-backed answer.
• Tokenizer demonstration: MkDocs and Python material show how input text is normalized, split into tokens, and mapped to token IDs.
• Embedding demonstration: the embedding lab uses a small teaching model to expose sentence vectors and cosine similarity.
• Vocabulary-training and neural-network visuals: browser-based MkDocs demos illustrate vocabulary training, vision vocabulary, weight/bias training, and tiny ANN training concepts.
• Chart-backed answer demo: a Python command processes Are MAG sales up in Chicago?, generates a structured request, reads sample sales data, analyzes the trend, writes a chart artifact, and prints the answer.
• Chatbot execution and trace mode: the CLI chatbot supports the Chicago MAG sales question and can print a step-by-step trace covering tokens, vectors, model-like decision output, retrieved data, chart generation, and response composition.
• Agent and local gateway demos: the repository includes an agent demo page and a FastAPI local gateway placeholder that returns a visible runtime path. These are demonstrations, not production services.
• Automated tests: Pytest verifies the chatbot pipeline for the recurring Chicago sales question.
• Reusable Python source: the src/magpai/ package separates tokenization, vectorization, classifier logic, sales data, chart generation, structured-request generation, and tools.

The recurring scenario

Are MAG sales up in Chicago?

MAG is a fictitious company, and the sales data is educational sample data. That stable scenario keeps the project grounded. The same question can be carried through progressively deeper demonstrations without changing the business narrative.

Repository architecture

The public repository is organized as an educational lab rather than a single script.

• docs/ contains MkDocs documentation, architecture notes, ADRs, glossary material, demo pages, talking points, and session outlines.
• diagrams/ stores visual architecture material, including the Session 01 sentence-to-token-to-vector diagram.
• notebooks/ contains Jupyter teaching material, including a tiny neural-network training notebook.
• src/ contains reusable Python source under magpai, including tokenizer, vectorizer, classifier, data, chart, chatbot, and tool modules.
• apps/ contains Streamlit and FastAPI application entry points for local demonstrations.
• tests/ contains Pytest coverage for the chatbot pipeline.
• data/ stores sample MAG sales data and generated-data placeholders.
• models/, runs/, and reports/ reserve local output areas for checkpoints, runtime output, coverage, profiling, and generated reports.
• scripts/ contains developer automation for setup, test execution, demo launch, cleanup, and Diavgeia export.
• pptx/ contains the Session 01 PowerPoint artifact.
• diavgeia/ contains Diavgeia-ready presenter and vault material for Session 01.

Engineering characteristics

MAGPAI is useful because it favors inspectability over scale. The current implementation emphasizes modular demonstrations, local execution, explicit trace paths, reproducible sample data, automated tests, separation of explanatory material from reusable source, and progressive complexity.

The result is a project that can support technical conversation at multiple levels: a recruiter can understand the project shape, an engineering leader can evaluate the architectural intent, and a software engineer can inspect source files that back the explanation.

Technology and tooling

Verified technologies in the repository include Python 3.11 or newer, PyTorch, NumPy, pandas, matplotlib, scikit-learn, Jupyter, Streamlit, FastAPI, Uvicorn, Pydantic, Pytest, Pytest coverage, python-pptx, MkDocs, MkDocs Material, and TensorBoard.

Those tools serve an educational objective. MAGPAI uses them to make runtime behavior visible, not to claim production readiness.

Related Noesis article

The companion Noesis article explains why building a tiny transparent AI system is useful for engineering judgment, leadership, and responsible AI architecture.

Read Why Build a Tiny Transparent AI System?

Production disclaimer

MAGPAI is an educational prototype and engineering laboratory. It is not a production AI model and should not be interpreted as a replacement for production-grade model infrastructure, security, governance, safety, or operational controls.

MAGPAI publication roadmap

Publication Roadmap: Ten Chapters

MAGPAI: AI Under the Hood will be published incrementally as a ten-chapter series. Each chapter connects a technical concept to source code, diagrams or an executable demonstration in the MAGPAI engineering laboratory.

1. 1

   Introducing MAGPAI: A Tiny Transparent AI System

   Available now

   Connects the current Noesis article and Praxis project page to the repository structure, sample business scenario, and demonstration laboratory.

   • Noesis article
   • Praxis project
2. 2

   The AI and Machine-Learning Stack

   Available now

   Presents an accessible stack explorer based on the verified MAGPAI Session 01 stack material.

   • Noesis article
   • Praxis project
3. 3

   How an AI System Sees a Sentence

   Available now

   Documents the Tokenizer Lab using the verified ManualTokenizer output for the recurring question: Are MAG sales up in Chicago?

   • Noesis article
   • Praxis project
4. 4

   From Tokens to Token IDs

   Coming next

   Previews vocabulary and token-ID inspection, including vocabulary-training demonstrations where supported.

5. 5

   From Token IDs to Vectors

   Coming soon

   Previews an Embedding Lab that shows token IDs and their corresponding numerical vectors.

6. 6

   How Embeddings Learn Meaning

   Planned

   Previews vocabulary or embedding training views that compare vector behavior before and after training.

7. 7

   From Embeddings to Neural-Network Activations

   Planned

   Previews existing neural-network visualizations with inspectable activations and parameter changes where available.

8. 8

   Tensors and Prompt Representation

   Planned

   Previews a prompt-tensor inspector for the recurring MAG business question.

9. 9

   From Question to Business Insight

   Planned

   Previews the chart-backed answer flow for Are MAG sales up in Chicago?

10. 10

    From Transparent Chatbot to Agent

    Planned

    Previews the chatbot, trace mode, and agent demonstrations with clear separation between educational behavior and implemented capability.

Read the companion Noesis article