This project includes an educational chatbot interface that visualizes the compilation pipeline (Lexer, Parser, Interpreter).

1. Install dependencies:

   pip install -r requirements.txt

2. Run the Streamlit app:

   python -m streamlit run streamlit_app.py

3. Open the link displayed in the terminal (usually http://localhost:8501).

SpeakMath is a math-focused natural language mini-programming language that interprets expressions like "find the mean of these values" into verified computations. The LLM suggests operator meanings, while our grammar verifies expressions before evaluation.

University of Malaya | Faculty of Computer Science & Information Technology
WIF3010: Programming Language Concepts | Project Brief 2025

• About the Project
• System Architecture
• Grammar Design (Week 8)
• Team Roles
• Current Progress
• Next Steps

Project Title: SpeakMath (Topic #3 from WIF3010 Brief)

Core Concept:
Create a math-focused natural mini-language where:

• Users write commands like "find the mean of these values"
• LLM suggests operator meanings (e.g., "average" → mean)
• Our grammar verifies expressions before evaluation
• Execution is handled by our own interpreter

Paradigm Extension: Functional Programming (map/reduce/composition)

• Makes mathematical operations accessible through natural language
• Combines formal grammar verification with LLM flexibility
• Perfect for demonstrating functional programming concepts
• Clear scope for proof of correctness

graph TB
    A[User Input] --> B[Lexer]
    B --> C[Parser]
    C --> D{Token Known?}
    D -- "MAP/REDUCE<br/>(Grammar-First)" --> E[Parse Map/Reduce]
    D -- "Known Op<br/>(SUM/MEAN/etc)" --> F[Semantic Map]
    D -- "Unknown Verb" --> G[Build Phrase]

    E --> H[AST Builder]
    F --> H
    G --> I{LLM Resolver}

    I -- "SEMANTIC_MAP" --> J[Return Operator]
    I -- "SYNONYM_MAP" --> J
    I -- "Heuristics" --> J
    I -- "LLM API" --> K{Found?}

    K -- "Yes + Metadata" --> J
    K -- "UNKNOWN" --> L[Structured Error]

    J --> H
    L --> M[Error Output]

    H --> N[Interpreter]
    N --> O{Is LLM Resolved?}
    O -- "Yes" --> P[Log Metadata]
    O -- "No" --> Q[Direct Execute]
    P --> Q
    Q --> R[Output]

    style E fill:#90EE90
    style F fill:#90EE90
    style I fill:#FFD700
    style L fill:#FF6B6B
    style P fill:#87CEEB

Legend:

• 🟢 Green: Grammar-First (No LLM)
• 🟡 Yellow: LLM Fallback Layer
• 🔴 Red: Error Handling
• 🔵 Blue: Metadata Logging

Flow Summary:

1. Lexer: Tokenizes input (MAP/REDUCE = keywords)
2. Parser: Matches grammar or builds phrase for unknown verbs
3. LLM Resolver: 4-layer strategy (Map→Synonym→Heuristic→API)
4. AST Builder: Creates nodes with LLM metadata
5. Interpreter: Executes and logs LLM resolutions

See: Complete Architecture Diagram

• Map unknown verb phrases to canonical operators
• Provide reasoning for operator choices
• Return "UNKNOWN" for unsupported operations
• Resolve operation names within map/reduce

• Override grammar rules
• Change token types or syntax structure
• Generate AST nodes
• Handle MAP/REDUCE keywords (always grammar-first)
• Execute code

See: LLM Fallback Design

The formal BNF/EBNF syntax definition is available in docs/syntax_definition.md.

Implemented Extensions:

• ✅ Variable assignment: set x to 5
• ✅ Conditionals: if x > 10 then print x
• ✅ Functional ops: map add 2 over [1, 2, 3]

NEW: SpeakMath now includes a sophisticated LLM fallback system that supplements the grammar without overriding it.

Key Features:

• 🎯 Grammar-First: MAP/REDUCE and known operations always use grammar
• 🤖 LLM Supplement: Unknown verbs resolved via AI (e.g., "tally up" → sum)
• 📊 Structured Errors: Detailed failure objects with suggestions
• 📝 Metadata Tracking: All LLM resolutions logged with reasoning

Documentation:

• 📘 LLM Fallback Design - Complete design document
• 📊 Architecture Diagram - System flow diagrams
• ⚡ Quick Reference - Fast lookup guide
• 📋 Implementation Summary - Task completion summary

Example:

# Grammar-First (No LLM):
Input: "sum [1, 2, 3]"
Output: 6

# LLM Fallback (AI Resolves Unknown Verb):
Input: "tally up [1, 2, 3]"
LLM: "tally up" → OP_SUM (Reasoning: "tally implies summation")
Output: 6 (with log: "ℹ️ LLM Resolution: 'tally up' → SUM")

# Grammar-First Guarantee (MAP always parsed by grammar):
Input: "map add 2 over [1, 2, 3]"
Grammar: Handles structure, LLM only resolves "add" if needed
Output: [3, 4, 5]

sum 1, 2, 3, 4, 5
mean 10, 20, 30, 40
multiply 5 and 6
tally up [10, 20, 30]        # LLM-resolved
map increment 2 over [1,2,3]  # Grammar-first structure
reduce product on [2,3,4]     # Grammar-first

Command: "sum 1, 2, 3"

    <command>
        |
    ____|____
   |         |
<operation> <expression>
   |            |
  "sum"    1, 2, 3

• Team formation
• Project proposal submitted
• Group contract signed
• Selected "SpeakMath" as project title

• Finalize BNF/EBNF grammar
• Create sample parse trees
• Design semantic mapping table
• Implement LLM fallback system
• Create comprehensive architecture diagrams
• Deliverable 2: Presentation 1 (Grammar + Architecture)

• Implement structured failure objects
• Update AST with LLM-resolved nodes
• Create grammar-first enforcement tests
• Document LLM intervention rules
• Build 4-layer resolution strategy

1. Complete formal grammar definition
2. Design 3-5 parse tree examples
3. Create high-level architecture diagram
4. Prepare Presentation 1

1. Start implementing lexer
2. Build basic parser
3. Test with simple commands

1. Integrate LLM API
2. Implement functional features (map/reduce)
3. Prepare Presentation 2

Required for Week 8:

• BNF/EBNF grammar specification
• 3-5 example parse trees
• High-level system architecture
• Semantic mapping plan
• LLM integration strategy

Tools We'll Use:

• Python 3.8+ (interpreter)
• OpenAI API or Gemini (LLM layer)
• PLY or recursive-descent parser
• GitHub (collaboration)

University of Malaya | FCSIT
Last Updated: Week 10, 2025