Skip to main content

HML Diagram Conventions

Overview​

HML Diagram Conventions define how HML visual symbols should be composed into readable architectural diagrams.

The HML Visual Dictionary defines the symbols.
This page defines the composition rules.

In short:

Visual Dictionary = what each symbol means
Diagram Conventions = how symbols are connected into diagrams

The goal is to make HML diagrams consistent across documentation, design patterns, implementation notes, and future academic publications.

A reader should be able to look at an HML diagram and quickly understand:

  • what information flows through the system
  • which cells process the flow
  • which policies govern the flow
  • which experts are invoked
  • where memory or state is consulted
  • where decisions, gates, or validation branches occur
  • where semantic information becomes embodied or external action

1. Basic Reading Direction

The default reading direction of an HML diagram is:

left → right

The main horizontal flow usually represents a HIF or a stream of HIFs.

Policies, experts, and semantic operators usually enter from above.
State, memory, queues, caches, and context structures usually appear as side structures.
External or embodied effects usually appear after a HIF Executor.

Basic HML Reading DirectionA HIF flows from left to right through a Semantic Cell. Policy and lambda enter from above. State may support the cell from below. The output may later become an external effect.Input HIFSemanticCellOutput HIFPolicyλExpertState / Memory

This convention means that the reader should first follow the HIF flow, then inspect policy, expert, and state dependencies.

2. Cell Composition Convention

A Semantic Cell is the architectural unit that binds:

  • incoming HIFs
  • a policy artifact
  • one or more semantic operators
  • selected context or state, when needed
  • routing and failure behavior

The policy and the operator should enter the cell independently.

Do not draw:

Policy → λ → Cell

Prefer:

Policy      λ
  ↓         ↓
Semantic Cell
Cell Composition ConventionPolicy and lambda enter the semantic cell independently from above. HIFs flow horizontally through the cell.Input HIFSemanticCellOutput HIFPolicyλExpert

This convention is important because policy and expertise are separate concerns.

The operator provides capability.
The cell decides how and when that capability is invoked under policy.

3. Operator vs Cell Convention

A semantic operator is not the same thing as a Semantic Cell.

λ = replaceable semantic expert / computation
Semantic Cell = policy-aware invocation boundary

The operator should not implicitly own the system policy or global context.

Instead:

  • the cell selects the relevant operator
  • the cell applies the relevant policy
  • the cell selects or prepares context
  • the cell passes explicit inputs or parameters
  • the cell routes the result
  • the cell records provenance and failure behavior

This convention keeps HML aligned with modular engineering practice.

For example, a person detector should remain a replaceable expert:

λperson_detector(frame, threshold?) → persons[]

It should not need to know why the frame was selected, which ROS node invoked it, which social task is active, or which downstream pattern will use the result.

Those responsibilities belong to the cell or pattern that invokes it.

4. Gate and Decision Conventions

A gate is a semantic decision role.

It is not necessarily a separate primitive cell.

A gate may be implemented by a Semantic Transformer, Sync Gate, Escalation Switch, HIF Executor, or a larger pattern.

Use a diamond when a diagram needs to show branching outcomes.

Common branch labels include:

pass / block
ready / pending
hit / miss
consistent / inconsistent
safe / unsafe
valid / invalid
clarify / execute
escalate / continue
Gate and Decision ConventionA HIF enters a gate-like semantic role and branches through a decision diamond into pass, modify, or block outcomes.HIFGate-likeCell / RoleDecisionpassmodifyblockPolicyλEvaluator

The diamond shows the branching outcome.
The gate role explains why a transition was allowed, modified, delayed, escalated, or blocked.

5. State and Memory Placement

State and memory structures should not usually be drawn as if they are ordinary HIF flow elements.

They may appear as:

  • side inputs to a Semantic Cell
  • side outputs from a Semantic Cell
  • stores updated by a Semantic Cell
  • triggers that create new HIFs
  • persistent structures that influence later reasoning

Typical state structures include:

  • HRI_DB
  • Semantic Cache
  • Session Context
  • Buffer
  • Queue
  • Prioritized Queue
  • Pending Queue
  • Time-Series Window
State and Memory PlacementState structures such as HRI_DB, cache, and pending queues are shown as side structures that support or receive updates from a semantic cell.Input HIFSemanticCellOutput HIFHRI_DBCachePending Queue

This convention keeps the main HIF flow readable while still showing that persistent or temporary state participates in the architecture.

6. Arrow Semantics

Different arrows should communicate different kinds of architectural relationships.

Arrow StyleMeaningTypical Use
Solid arrowMain semantic flowHIF flow, HIF stream, effect flow
Top-down solid arrowCell inputPolicy or λ entering a Semantic Cell
Dashed arrowBinding, invocation, non-HIF dependency, or optional relationExternal operator binding, configuration dependency
Branch arrowOutcome of a decisionpass, block, hit, miss, ready, pending
Bidirectional arrowsRead/write relationHRI_DB query/update, cache lookup/update
Return arrowReprocessing or resumptionpending queue recheck, fact-triggered task promotion

Use bidirectional arrows carefully.
If a relationship has different read and write semantics, prefer two separate arrows with labels.

7. Pattern Diagram Levels

HRI Design Patterns should usually be shown at two levels.

Abstract HML Pattern​

The abstract diagram shows the reusable architectural structure.

Example:

HIF → ST₁ / ST₂ / ST₃ → SG → enriched HIF

This level should avoid robot-specific implementation details.

Concrete Example​

The concrete diagram shows a specific instantiation.

Example:

VideoFrame HIF
  → Person Detector ST
  → Skeleton Detector ST
  → Gaze Detector ST
  → Aggregator SG
  → HumanState HIF

This level may include:

  • concrete input types
  • concrete experts
  • concrete policies
  • domain-specific state structures
  • robot-specific output effects

The pattern page should make clear which part is generic and which part is an example.

8. Abstract vs Runtime Diagrams

HML diagrams are architectural diagrams, not necessarily runtime graphs.

A single Semantic Cell may correspond to:

  • one ROS node
  • multiple ROS nodes
  • a Python class
  • a service call
  • an agent tool
  • a model endpoint
  • a configuration binding
  • a set of cooperating modules

Conversely, one runtime component may implement several HML roles.

Therefore, avoid interpreting an HML diagram as a one-to-one deployment diagram.

HML answers:

What semantic role is being performed?

not necessarily:

Which process, container, or node performs it?

Runtime binding may be documented separately.

9. Recommended Layout Rules

For readable diagrams:

  • Keep the main HIF flow horizontal whenever possible.
  • Place policy and expert inputs above the cell.
  • Place state structures below or beside the cell.
  • Use diamonds only when an actual branch is shown.
  • Use labels on non-obvious arrows.
  • Avoid long crossing arrows.
  • Use two-row layouts for long pipelines.
  • Prefer short diagrams on documentation pages and larger diagrams for slides.
  • Keep abstract diagrams technology-neutral.
  • Put implementation-specific details in examples or implementation notes.

10. Anti-Patterns

Avoid the following diagrammatic anti-patterns.

Policy Hidden Inside an Operator​

Avoid:

Policy → λ → Cell

Prefer independent inputs:

Policy      λ
  ↓         ↓
Cell

Global State Everywhere​

Avoid diagrams where every component reads and writes a global state store.

Prefer bounded state access through explicit cells or handlers.

LLM Directly to Action​

Avoid:

LLM → Robot Action

Prefer:

LLM candidate → validation gates → executable HIF → HE → effect

Mermaid-Only Box Diagrams​

Mermaid is useful for early sketches, but final documentation diagrams should use the HML visual grammar when possible.

Unlabeled Branches​

Avoid diamonds whose outputs are not labeled.

A gate should expose what decision was made and why the branch was selected.

11. Minimal Pattern Diagram Template

Most HRI Design Pattern diagrams can follow this abstract structure:

Minimal HML Pattern Diagram TemplateA reusable pattern diagram template showing input HIF, semantic cell, decision, optional state, and output HIF or effect.Input HIFSemanticCellDecisionOutput HIF / EffectPolicyλExpertOptional State

A pattern-specific diagram should modify this template only as needed.

Examples:

  • remove the decision diamond if there is no branching
  • replace HRI_DB with cache, queue, or time-series window
  • use multiple STs when the pattern performs parallel extraction
  • use an ES when the pattern selects among experts
  • use an SG when the pattern synchronizes multiple HIFs
  • use an HE when the pattern commits to an external or embodied effect

Conclusion

HML Diagram Conventions define how the visual symbols should be composed into readable architectural diagrams.

The most important conventions are:

HIFs flow left to right.
Policies and λ operators enter cells from above.
Cells bind policy, operator, context, and HIF flow.
State and memory are explicit supporting structures.
Diamonds represent decision outcomes, not primitive cells.
Design pattern diagrams should separate abstract structure from concrete examples.

These conventions make HML diagrams consistent, auditable, and reusable across the SOCIAL framework and the HRI Design Patterns.