OpenSymbolic
Book a pilot
← All tutorials

Track 15 · Blueprints

expanded_intent

Describe a decomposition's approach, not just its intent. The expanded_intent renders as an Approach line in the prompt so the planner reads the reasoning before the steps.

Intermediate10 min
Video coming soon
Project codeBrowse this tutorial's folder in tutorials-py →github.com/OpenSymbolicAI/tutorials-py/tree/main/15-expanded-intent

Before you start

Track 14 gave the planner a worked example: an intent and a body. A decomposition takes one more field, expanded_intent: a sentence describing the approach the example uses. It renders as an Approach: line in the prompt, right above the code, so the planner reads the reasoning before the steps.

1. A finance acronym glossary

Finance is full of acronyms that are impossible to look up directly: KIKO, TARN, VOMMA, CDXIG. This agent has 34 of them, each with an expansion and a plain-English definition. It supports both directions: given an acronym, explain it; given a full term, find its acronym.

python
expand(acronym: str) -> str      # "CVA" -> "credit valuation adjustment"
abbreviate(term: str) -> str     # "Carr-Geman-Madan-Yor model" -> "CGMY"
define(term: str) -> str         # full form -> plain-English sentence
phrase(acronym, full, meaning)   # combines all three into one line

abbreviate uses fuzzy matching so the model does not need to pass the exact string.

2. Two decompositions, two approaches

The forward decomposition teaches the planner to expand an acronym first, then define the expansion:

python
@decomposition(
    intent="what does CVA mean?",
    expanded_intent=(
        "A finance acronym can't be defined directly. Expand it to its full "
        "form first, then define that full form, then phrase the acronym, "
        "full form, and meaning together into one answer."
    ),
)
def _example_cva(self) -> str:
    full = self.expand("CVA")
    meaning = self.define(full)
    cva_result = self.phrase("CVA", full, meaning)
    return cva_result

The reverse decomposition teaches the planner to abbreviate a full term, then define it:

python
@decomposition(
    intent="what is the acronym for Carr-Geman-Madan-Yor model?",
    expanded_intent=(
        "When given a full term rather than an acronym, the lookup runs in "
        "reverse. Abbreviate the full term to find its acronym, define the "
        "full term directly, then phrase the acronym, full form, and meaning "
        "together."
    ),
)
def _example_cgmy_reverse(self) -> str:
    acronym = self.abbreviate("Carr-Geman-Madan-Yor model")
    meaning = self.define("Carr-Geman-Madan-Yor model")
    cgmy_result = self.phrase(acronym, "Carr-Geman-Madan-Yor model", meaning)
    return cgmy_result

3. What the planner sees

The library renders both as prompt examples, each with an Approach: line:

text
### Example 1
Intent: what does CVA mean?
Approach: A finance acronym can't be defined directly. Expand it to its full form first, ...
Python:
full = expand('CVA')
meaning = define(full)
cva_result = phrase('CVA', full, meaning)
return cva_result

The Approach: line is your expanded_intent, verbatim. Without it the planner sees only the code and has to infer the order; with it the reasoning is explicit.

4. Run it

python
QUERIES = [
    "what does KIKO mean?",
    "what does TARN mean?",
    "what does CDXIG mean?",
    "what is the acronym for Carr-Geman-Madan-Yor model?",
    "what is the acronym for vega-gamma sensitivity?",
]
bash
uv run main.py

Sample output:

text
KIKO (knock-in knock-out): an exotic option that activates only if the
underlying hits one barrier and cancels if it hits another

VOMMA (vega-gamma sensitivity): a second-order derivative measuring how
a position's vega changes as implied volatility moves

When to use expanded_intent

Use it when the approach is non-obvious from the code alone. Here the order matters: you cannot define an acronym directly, so you must expand it first. The expanded_intent makes that constraint explicit to the planner before it sees the steps.

For simple examples where the code is self-explanatory, intent alone is enough.