03_intent_inference_engine

Intent Inference Engine

The Intent Inference Engine (IIE)

Purpose

The Intent Inference Engine (IIE) is the "brain" of the ARES compiler. Most compilers simply translate exactly what you write, but the IIE goes one step further. It analyzes the goal of your code and understands what you are trying to achieve. It then ensures that all the necessary preparations are made automatically, so you don't have to worry about the small details of every algorithm.

Why it exists

When you use a complex algorithm, there are often rules you must follow for it to work. For example, if you want to perform a "binary search" on a list of numbers, that list must be sorted first. If you forget to sort it, your program will fail or give you the wrong answer. The IIE exists to prevent these mistakes. It understands that a search requires a sorted list and will automatically add the "sort" step for you if it is missing. This allows you to focus on your logic rather than the low-level rules of every tool.

How it works

The engine acts as a smart inspector that scans your code tree before it is sent to the emitters.

  1. Consulting the registry. The system looks at a database of algorithmic rules. For every tool (like binary_search), the database lists what is required for it to work.
  2. Tracking variable states. The engine keeps a record of every variable in your program. It tracks whether a list is currently "sorted" or "empty" based on the commands you have already given.
  3. Injecting missing steps. If the engine sees you using a search command on a list that isn't marked as "sorted," it automatically inserts a hidden "sort" command immediately before the search.
  4. Expanding macros. When you use the "magic" Ares() command, the engine expands it into a sequence of several different steps (like sorting, searching, and printing) based on what you provided inside the parentheses.

Intuition

Think of the IIE like a very helpful co-pilot in an airplane. You are the captain, and you give the command to "prepare for landing" (your logic). You don't need to tell the co-pilot every small step, like lowering the landing gear or checking the fuel. The co-pilot understands your intent and handles those necessary preparations for you automatically, making sure the landing (your program execution) is safe and successful.

Implementation details

The core logic for the IIE is found in src/semantics/analyzer.ts. It visits every statement in your program and performs "Node Injection" (adding new steps) when it detects a missing prerequisite.

  • Mapping Intent: The system maps a single use binary_search to a sequence of [sort, binary_search].
  • Safety Checks: It also validates that you aren't trying to use a tool on the wrong kind of data, like trying to find the "prefix sum" of a single number.

Trace example

This is what happens when you write use binary_search on my_list:

  1. Analysis: The engine sees you want to use a search algorithm.
  2. Check: It checks the state of my_list in its internal record.
  3. Action: If the record says isSorted: false, the engine inserts a new command: use sort on my_list.
  4. Result: The final code will have both the sort and the search, even though you only wrote the search.

Related entities

  • 01_pipeline.md: Phase 3 of the pipeline is where the IIE performs its analysis.
  • src/semantics/analyzer.ts: The actual code that implements this semantic intelligence.
ARES