LinguaFlow is a grammar-first natural command interpreter that combines formal grammar with LLM semantic assistance. It allows you to write mathematical expressions in 7 different ways - from traditional symbols to natural language phrases, with built-in exception handling.
Key Features:
- Grammar-first design: The grammar handles ALL structure
- LLM semantic assistance: Resolves operation words and corrects typos
- 7 flexible input formats: From symbolic to natural language
- Mixed rules: Combine different patterns in one expression
- Try-catch exception handling: Language-level error recovery
- Install dependencies:
pip install -r requirements.txt- Set up your Gemini API key (for LLM features):
# Create .env file
echo "GEMINI_API_KEY=your_api_key_here" > .envGet a free API key at: https://makersuite.google.com/app/apikey
python main.pyYou'll see a welcome screen with rule examples, then the calc > prompt.
calc > 5 + 3
Result: 8
calc > (5 + 3) * 2
Result: 16
calc > 10.5 / 2
Result: 5.25
calc > 5 add 3
[LLM Resolution] 'add' → '+'
Result: 8
calc > 10 multiply 2
[LLM Resolution] 'multiply' → '*'
Result: 20
calc > 15 divide 3
[LLM Resolution] 'divide' → '/'
Result: 5.0
calc > sum these numbers: [5, 3, 7]
[LLM Resolution] 'sum' → '+'
Result: 15
calc > multiply these numbers: [2, 4, 3]
[LLM Resolution] 'multiply' → '*'
Result: 24
calc > sum of 5 and 3
[LLM Resolution] 'sum' → '+'
Result: 8
calc > product of 10 and 2.5
[LLM Resolution] 'product' → '*'
Result: 25.0
calc > difference of 20 and 5
[LLM Resolution] 'difference' → '-'
Result: 15
Combine Rules 1 and 2 (symbolic and infix worded operations):
calc > 5 + 4 subtract 2
[LLM Resolution] 'subtract' → '-'
Result: 7
calc > 10 * 2 add 5
[LLM Resolution] 'add' → '+'
Result: 25
calc > 2 add 3 times 4
[LLM Resolution] 'add' → '+'
Result: 14
calc > 5 multiply sum of 2 and 3
[LLM Resolution] 'multiply' → '*'
[LLM Resolution] 'sum' → '+'
Result: 25
Note: Rule 4 (natural phrasing) can be used as the right operand in worded operations. To use Rules 3 or 4 with other operators, wrap them in parentheses:
calc > (sum of 5 and 3) - 2
Result: 6
Handle runtime errors gracefully with try-catch blocks:
calc > try 10 / 0 catch 999
Result: 999
calc > try 5 add 3 catch 0
[LLM Resolution] 'add' → '+'
Result: 8
calc > try 10 divide 0 catch 100
[LLM Resolution] 'divide' → '/'
Result: 100
calc > try sum these numbers: [10, 0] catch product of 2 and 5
[LLM Resolution] 'sum' → '+'
Result: 10
Try-catch expressions evaluate the try block first. If it succeeds, the result is returned. If a runtime error occurs (like division by zero), the catch block is evaluated instead.
Use the "calc" prefix for complete natural language questions:
calc > calc what is answer of 10 divided by 2
[Natural Language Conversion] 'what is answer of 10 divided by 2' → '10 / 2'
Result: 5.0
calc > calc what is 5 plus 3
[Natural Language Conversion] 'what is 5 plus 3' → '5 + 3'
Result: 8
calc > calc calculate 5 times 3 minus 2
[Natural Language Conversion] 'calculate 5 times 3 minus 2' → '5 * 3 - 2'
Result: 13
LinguaFlow automatically detects and corrects typos:
calc > sam of 5 and 3
[LLM Resolution] 'sam' → '+'
Result: 8
calc > 5 multipy 3
[LLM Resolution] 'multipy' → '*'
Result: 15
But rejects complete gibberish:
calc > asdfas of 5 and 3
Error: Unknown operation word: 'asdfas'
calc > help # Show detailed help
calc > rules # Show rule summary
calc > exit # Quit the interpreter
When you use operation words (add, sum, multiply, etc.), LinguaFlow:
- Recognizes the grammar pattern (e.g., "5 add 3" matches Rule 2)
- Asks LLM: "Is 'add' a synonym for +, -, *, or /?"
- LLM responds: "+"
- Displays resolution:
[LLM Resolution] 'add' → '+' - Continues parsing with the resolved symbol
The LLM understands many synonyms:
- Addition: add, sum, plus, total, accumulate, combine, etc.
- Subtraction: subtract, minus, difference, take away, etc.
- Multiplication: multiply, times, product, etc.
- Division: divide, split, quotient, etc.
LinguaFlow shows verbose execution steps:
calc > 5 add 3
============================================================
INTERPRETATION STEPS
============================================================
1. LEXER (Tokenization):
----------------------------------------
[INT:5, WORD_OP:add, INT:3, EOF]
[LLM Resolution] 'add' → '+'
2. PARSER (Abstract Syntax Tree):
----------------------------------------
BinOp(+)
|
+-+-+
| |
5 3
3. INTERPRETER (Execution):
----------------------------------------
- Add operation (+):
- Evaluate left operand: 5
- Evaluate right operand: 3
- Result: 5 + 3 = 8
4. RESULT:
----------------------------------------
8
============================================================
This helps you understand:
- How input is tokenized (Lexer)
- How the syntax tree is built (Parser)
- When LLM resolution occurs
- How the expression is evaluated (Interpreter)
- Make sure you have a
.envfile in the project directory - The file should contain:
GEMINI_API_KEY=your_actual_api_key - Get a free key at https://makersuite.google.com/app/apikey
- The LLM couldn't recognize the word as a math operation
- Try using a clearer synonym (e.g., "add" instead of "xadd")
- Or use symbolic notation:
+,-,*,/
- Check the pattern matches one of the 4 rules
- For Rule 3 (functional), use exact syntax:
sum these numbers: [1, 2, 3] - For Rule 4 (natural), use exact syntax:
sum of 5 and 3
calc > 5 + 3
Result: 8
calc > 5 add 3
[LLM Resolution] 'add' → '+'
Result: 8
calc > sum these numbers: [5, 3, 7]
[LLM Resolution] 'sum' → '+'
Result: 15
calc > product of 10 and 2.5
[LLM Resolution] 'product' → '*'
Result: 25.0
calc > help
[Shows detailed help documentation]
calc > exit
Goodbye!
- Grammar-First Design: Structure is defined by formal grammar, not AI guesswork
- LLM as Helper: AI only validates word meanings, doesn't generate code (except for natural language conversion)
- Explainable: You see exactly when and how LLM is used
- Flexible: 6 different ways to express the same operation
- Educational: Shows compiler pipeline stages (Lexer → Parser → Interpreter)
- Compiler Principles: Follows academic compiler design patterns
- Typo Tolerance: Automatically corrects common typos while rejecting gibberish
- Mixed Patterns: Combine different grammar rules freely in one expression
- SUMMARY.md: Complete feature documentation
- ARCHITECTURE.md: How the interpreter works internally
- grammar.txt: Formal grammar specification (Extended BNF)