📚 Math Knowledge Base

Status: Stable Version (0.13.0) A platform designed to register, visualize, and export mathematical definitions, theorems, examples, and concepts in LaTeX.

---

🚀 Objective

To build a customizable mathematical knowledge database that supports:

• Entry capture via a Streamlit interface.
• Structured storage in MongoDB.
• Automatic LaTeX export and PDF generation.
• Visualization of relationships between concepts using graphs.

The managed Source workflow is documented in the user guide. See the v0.13.0 release notes for compatibility, upgrade guidance, and known limitations.

---

🎨 Visual Styling of Mathematical Concepts

Each registered concept can be exported to a .tex file and compiled into a PDF, using a styled format powered by the
coloredtheorem package.

• Environments such as Definition, Theorem, Example, etc., are rendered inside colored boxes.
• A custom style file, exporters/templates/miestilo.sty, is used to control presentation.
• You may define unnumbered concepts using environments like \begin{cthdefinicion*}{...}.

This enables the generation of visually appealing mathematical documents directly from the database.

---

📄 PDF Generation from the Interface

The application includes built-in functionality to generate PDFs directly from concept forms:

• “📄 Generate and open PDF” button available in both Add Concept and Edit Concept forms.
• Automatic generation using pdflatex, matching the style used by ExportadorLatex.
• Automatic opening in the web browser.
• Persistent storage in ~/math_knowledge_pdfs/.
• Descriptive filenames: {id}_{type}.pdf.
• Correct permissions for browser access (644 for files, 755 for the directory).

Generated PDFs use exactly the same style as the existing exporter:

• Style files: miestilo.sty and coloredtheorem.sty.
• LaTeX format: Same preamble and structure as ExportadorLatex.
• Mathematical environments: Fully compatible with coloredtheorem (colored boxes).
• Metadata: Same presentation for references and comments.

---

📘 Book-Level Export with Quarto

In addition to single-concept PDF generation, the project supports book-level exports using Quarto Book.

Quarto is used to compile complete mathematical books from the knowledge base, allowing concepts to be organized into chapters and sections while preserving the same LaTeX visual identity.

This enables:

• Long-form mathematical documents.
• Research notes and lecture material.
• Thesis-style compilations.

⚙️ Quarto Installation (Mandatory, Script-Based)

Quarto is not assumed to be installed on the system.

To guarantee reproducibility, Quarto must be installed using the provided script:

scripts/install_quarto.sh

This script:

• Downloads the official Quarto distribution.
• Installs it in a controlled manner.
• Can be verified with quarto --version and quarto check.

The complete installation sequence is documented below.

📦 Project Structure

• editor/ — Streamlit application for data entry, editing, querying, export/import, and PDF generation.
• editor/cuaderno_page.py — Notebook/Cuaderno workflow: diary notes, worklog, backlog, weekly reviews, deliverables, and Kanban.
• editor/utils/ — Database ZIP export/import helpers.
• mathdatabase/ — MongoDB connection, database management, and core classes.
• parsers/ — Functions for importing Markdown/YAML concept files into the database.
• exporters_latex/ — LaTeX/PDF export tools.
• exporters_quarto/ and scripts/export_quarto_book.py — Quarto book export tools.
• schemas/ — Pydantic schemas used to validate mathematical concept fields.
• visualizations/ — Interactive mathematical graph visualizations.

---

⚙️ Requirements

• Ubuntu 20.04, 22.04, or similar (recommended).
• Python 3.10+ (recommended: 3.10.14 or 3.11.6).
• MongoDB installed and running.
• Full LaTeX installation (texlive-full) for correct PDF export.
• ChkTeX (chktex) for static LaTeX analysis in notebook exports.
• make, Git, pip.

⚠️ Not yet intended for native Windows use; WSL is recommended.

---

🛠️ Installation

The application needs four things before running:

1. MongoDB running locally.
2. A Python virtual environment with the project dependencies.
3. LaTeX/Quarto if you want PDF and book exports.
4. MongoDB collections/indexes initialized for the database you will use.

1. Clone the project

git clone https://github.com/EnriqueDiazO/math-knowledge-base.git
cd math-knowledge-base

2. Install system dependencies

On Ubuntu/Debian, install MongoDB, Python tooling, Make, Git, and LaTeX. Package names may vary depending on your distro and MongoDB installation method.

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git make texlive-full

Start MongoDB:

make start

You can also check it directly:

sudo systemctl status mongod

3. Create the Python environment

The project convention is to use a virtual environment named mathdbmongo.

python3 -m venv mathdbmongo
source mathdbmongo/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install -e .

4. Install and verify Quarto and ChkTeX

Quarto is used for book-level exports. Install it with the project script:

bash scripts/install_quarto.sh
quarto --version
quarto check

ChkTeX is used for static LaTeX analysis in notebook exports. Install it with the project script:

./scripts/install_chktex.sh

Manual Ubuntu/Debian alternative:

sudo apt install -y chktex

Verify LaTeX and ChkTeX too:

pdflatex --version
command -v chktex
chktex --version

5. Initialize MongoDB collections and indexes

Run this for every database where you want the full GUI features. The app commonly uses mathmongo by default, and imported/active working databases often use names like MathV0.

python scripts/install_cuaderno_mode.py --mongo-uri mongodb://127.0.0.1:27017 --db mathmongo

For MathV0:

python scripts/install_cuaderno_mode.py --mongo-uri mongodb://127.0.0.1:27017 --db MathV0

This command is non-destructive. It creates missing Notebook/graph-map collections and indexes without deleting existing data. Core concept/relation indexes are also created automatically when the app opens a MathMongo connection.

Check the target database before running the installer:

python scripts/install_cuaderno_mode.py --status --mongo-uri mongodb://127.0.0.1:27017 --db MathV0

Use the same --db value selected in the Streamlit sidebar. The installer default is mathmongo, while active imported databases commonly use names such as MathV0.

Cornell math notes are stored in the existing latex_notes collection. There is no separate cornell_notes collection. Cornell notes are identified by:

note_format = "cornell_math_v1"

Their canonical Cornell payload is stored under:

cornell.schema_version
cornell.template_id
cornell.pages
cornell.attribution
cornell.watermark

The Cornell installer support is idempotent and keeps legacy notes valid. Expected Cornell indexes on latex_notes are:

• latex_note_format
• latex_note_format_date_desc
• latex_note_format_project
• latex_note_format_context

The full database flow uses:

• concepts
• relations
• latex_documents
• latex_notes
• worklog_entries
• backlog_items
• weekly_reviews
• deliverables
• knowledge_graph_maps
• media_assets

The installer also creates the portable media directory:

• media/images

Images uploaded from concepts or Cuaderno notes are stored as local files under media/images and referenced from MongoDB with relative paths such as media/images/figure.png. Database export/import includes both the media_assets collection and the media/ tree, so backups remain portable across machines and database names.

Cornell notes support per-region images, optional footer attribution, text or image watermarks, and editable multi-page export. The editable project export writes a self-contained LaTeX folder with:

• Notas.tex
• Izquierda.tex, Derecha.tex, Abajo.tex
• A.tex, B.tex, C.tex
• contenido/pagina_NNN/*.tex
• images/
• metadata.json
• README.md

Compile editable projects with:

pdflatex Izquierda.tex
pdflatex Derecha.tex
pdflatex Abajo.tex
pdflatex Notas.tex

Generated Cornell exports live under runtime/cornell_exports/. Safe cleanup should preserve sources, README.md, metadata.json, required images such as lineas.png, and the final Notas.pdf when present; remove only LaTeX auxiliary files and explicitly selected intermediate regional PDFs.

6. Run MathMongo locally

make run

This starts and supervises both Streamlit and the Advanced Reader in the foreground. Both default to MathV0; Streamlit listens on http://127.0.0.1:8501 and the reader on http://127.0.0.1:8766. Press Ctrl+C to stop only the services created by this launcher.

The services can still be run separately:

make run-streamlit
make advanced-reader DATABASE=MathV0

Use one-off Make overrides for another database or free ports, for example:

make run DATABASE=otra_base STREAMLIT_PORT=8502 ADVANCED_READER_PORT=8767

Both hosts remain loopback-only. An existing compatible Advanced Reader may be reused and will not be stopped; an unknown Streamlit listener or a reader bound to another database blocks startup without killing either process. If the database is changed later in the Streamlit sidebar, the reader remains bound to its startup database. See docs/UNIFIED_LOCAL_RUNTIME_S5B_1.md for health checks, port handling and troubleshooting.

Reading Space uses the fixed primary flow Biblioteca → Leer → Cuaderno → Conocimiento. Page Map, maintenance and diagnostics are available from the secondary Configuración menu. The Advanced Reader uses a single contextual inspector for selection, mark confirmation and concept association. See docs/SIMPLIFIED_READING_WORKFLOW.md.

7. Optional desktop shortcut

chmod +x scripts/make_desktop_shortcut.sh
./scripts/make_desktop_shortcut.sh

🔁 Updating a Database (MathV0)

To update a database, follow these steps:

1. In the database you want to update, go to Navigation → Settings.

2. Select Clear All Data.
   This will delete all existing content while keeping the database name MathV0.

3. Then go to Database Import and import the database using the name MathV0.
   Fill in all required fields, and make sure you use the name MathV0.

4. To enable notebook mode, run the following command in your terminal:

   python scripts/install_cuaderno_mode.py --mongo-uri mongodb://127.0.0.1:27017 --db MathV0

---

📚 Adding References

You can add references using standard BibTeX format:

@book{knuth1984texbook,
  author    = {Donald E. Knuth},
  title     = {The TeXbook},
  year      = {1984},
  publisher = {Addison-Wesley},
  edition   = {Revised},
  volume    = {A},
  pages     = {1--483},
  isbn      = {0-201-13448-9},
  doi       = {10.5555/53924},
  url       = {https://ctan.org/pkg/texbook}
}

🔁 Database Export & Import (Portability and Versioning)

Math Knowledge Base includes explicit database export and import capabilities, designed to support portability, versioning, backups, and long-term reproducibility.

These features are intentionally manual and explicit: no automatic synchronization or silent overwrites are performed.

---

📤 Database Export

The application allows exporting the entire MongoDB database used by Math Knowledge Base into a single ZIP archive.

Key characteristics:

• Export is read-only and does not modify the database.
• All collections are exported as JSON files, one file per collection.
• Expected project collections are included even when empty, including knowledge_graph_maps.
• MongoDB-specific types are safely normalized:
  • ObjectId → string
  • datetime → ISO 8601 strings
• A metadata.json file is included, containing:
  • Export timestamp
  • Collection names and document counts

This makes the export:

• Fully versionable (e.g. via Git or external storage),
• Portable across machines,
• Independent of the runtime environment.

🗺️ Knowledge graph maps

Concept maps edited from Knowledge Graph Visualization are stored in the knowledge_graph_maps collection and are included in full database exports/imports.

Each saved map keeps:

• generation filters (sources, concept types, relation types, max depth),
• nodes and edges,
• edited node positions and fixed-node state,
• physics, layout, and edge-control settings,
• node/edge text sizing,
• tags and descriptive metadata.

The graph_state payload is exported without trimming so restored maps preserve the visual editing state.

Typical use cases include:

• Creating snapshots before major refactors,
• Sharing datasets between machines,
• Long-term archival of research states.

---

📥 Database Import

Database Import has two explicit modes:

• Create a new database requires a name that does not exist and never writes over an existing database. The exact name MathV0 is allowed only when it is absent.
• Update an existing database selects an existing target, including MathV0, and performs a dry-run before enabling any write. admin, config, and local are never eligible.

The default Safe merge strategy inserts missing documents, skips byte-equivalent canonical documents, preserves local-only data, and reports identity conflicts without overwriting them. The advanced Backup wins strategy can replace an individual conflict only after an explicit decision. Keep current inserts new documents while retaining every current conflict.

Collections are discovered from both metadata.json and the JSON members under collections/. New collections are imported, collections found only in the destination are preserved, and an empty backup collection never empties its destination. Future collections can be merged as validated Extended JSON when each document has a safe _id; they remain unmanaged and receive no invented models or indexes.

Before an existing database is changed, MathMongo creates and validates a complete timestamped backup. PDF blobs and media are verified, copied only when missing, and published atomically. The update stops on validation, reference, index, or file conflicts and offers explicit recovery when a failure occurs after writes begin. This workflow never mirrors the archive and never deletes documents or collections missing from it.

See Database Import user guide for the complete workflow, conflict policies, backup behavior, and limitations.

---

🧠 Recommended Naming Convention

While MongoDB allows arbitrary database names, the following convention is recommended:

• MathV0 — primary active database
• MathV0_snapshot_YYYYMMDD — frozen snapshots
• MathV0_import_YYYYMMDD — imported states
• Math_exp_<topic> — experimental or research-specific databases

Adopting explicit naming conventions improves traceability and reduces cognitive overhead when working with multiple database versions.

---

🎯 Design Philosophy

Database export and import are treated as first-class operations, not hidden utilities.

The goal is to ensure that:

• Every database state is explainable,
• Transitions between states are intentional,
• Mathematical knowledge remains durable beyond a single machine or session.

This approach favors correctness, transparency, and reproducibility over automation.

🆕 Recent Additions to the Math Knowledge Base (January 21, 2026)

This section summarizes the most recent functional additions to the Math Knowledge Base, extending the core concept-management platform with structured workflow, planning, and traceability features.

---

🗒️ Notebook (Cuaderno) System

A new Notebook-oriented workflow has been introduced to complement concept capture with operational and reflective tooling. This subsystem is designed to record what was done, why it was done, and what comes next, while remaining tightly integrated with the mathematical knowledge base.

🧾 Worklog

• Daily chronological logging of work activities.
• Text-based entries with optional hour tracking.
• Filtering and querying by date ranges and keywords.
• CSV export with row selection.

📋 Backlog

• Structured task tracking linked to projects and objectives.
• Status-based workflow (e.g., To Do, In Progress, Done).
• Query and export capabilities consistent with Worklog.
• Acts as the primary source of truth for task completion metrics.

---

📅 Weekly Review (V5)

The Weekly Review module provides a structured, week-level synthesis layer that connects daily execution (Worklog) and task completion (Backlog) with narrative reflection and planning.

Core Capabilities

• Add Weekly Review

  • Create a weekly review indexed by ISO year and ISO week.

• Edit Weekly Review

  • Load any existing weekly review from recent weeks.
  • Editor fields are populated directly from persisted MongoDB documents.

• Delete Weekly Review

  • Safe deletion with explicit user confirmation.

• Export Weekly Reviews (CSV)

  • Same interaction model as Worklog and Backlog.
  • Selection from recent weeks or filtered queries.

Structured Narrative Fields

• Weekly objectives
• Wins and achievements
• Blockers and risks
• Plan for the following week

Integrated Metrics

Weekly Reviews are enriched with automatically derived metrics:

• Real hours worked (aggregated from Worklog entries).
• Tasks completed (derived from Backlog items marked as Done).
• Activity summary (preview of recent worklog tasks).

An optional manual override mechanism allows correcting these metrics when historical data is incomplete, while preserving derived values as the default.

---

📦 Deliverables Tracking

The Deliverables module has been expanded into a first-class, editable artifact type:

• Load and edit existing deliverables.
• Track deliverables by project, status, and type.
• Export deliverables to CSV using the same selection and filtering patterns used elsewhere in the system.

---

🔄 Unified User Experience

All Notebook-related modules (Worklog, Backlog, Weekly Review, Deliverables) now share a common interaction model:

• Recent items view
• Explicit load into editor
• Safe edit and save
• CSV export with row-level selection

This consistency reduces cognitive load and supports long-term, incremental knowledge accumulation.

---

🧠 Design Philosophy

• Mathematical concepts remain the core canonical objects of the system.
• Notebook artifacts provide context, traceability, and planning, not competing sources of truth.
• Quantitative metrics are derived from atomic records whenever possible.
• Narrative reflection and planning are stored explicitly and independently.

---

These additions position the Math Knowledge Base not only as a repository of mathematical knowledge, but also as a research and study companion capable of supporting sustained, multi-week intellectual work.