# allenai/alexafsm architecture

> Architecture diagram of the GitHub repository allenai/alexafsm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/allenai/alexafsm
- Repository: https://github.com/allenai/alexafsm

## Overview

alexafsm is a Python library for modeling Alexa conversations as finite-state machines. The main turn flow accepts an Alexa request in Policy, builds or updates session attributes, triggers a state transition, and produces an Alexa-formatted Response. States define the conversation states and transition declarations; Policy assembles and executes the machine. The library also provides validation, graph/printing and recorded-dialog analysis tools, plus optional VoiceLabs tracking. The example skill and server are excluded because they live under tests. Edges reflect README statements or shown source; unsampled implementations and unshown transition dispatch details are not inferred.

Main entry points: [`alexafsm/policy.py`](https://github.com/allenai/alexafsm/blob/master/alexafsm/policy.py) (Policy handler), [`alexafsm/response.py`](https://github.com/allenai/alexafsm/blob/master/alexafsm/response.py) (Alexa response), [`alexafsm/states.py`](https://github.com/allenai/alexafsm/blob/master/alexafsm/states.py) (State definitions), [`alexafsm/session_attributes.py`](https://github.com/allenai/alexafsm/blob/master/alexafsm/session_attributes.py) (Session attributes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation runtime"]
  node_policy["Policy handler<br/>[policy.py]"]
  node_states["State definitions<br/>[states.py]"]
  node_attributes["Session attributes"]
  node_response["Alexa response<br/>[response.py]"]
  node_intents["Alexa intent names<br/>[amazon_intent.py]"]
end

subgraph group_support["Inspection tools"]
  node_tools["FSM tools<br/>[utils.py]"]
  node_jsonhelper["JSON conversion"]
end

subgraph group_integrations["External services"]
  node_machine{{"FSM engine"}}
  node_voicelabs["VoiceLabs"]
end

node_alexa(("Alexa request"))

node_alexa -->|"sends request"| node_policy
node_policy -->|"builds from"| node_states
node_states -->|"creates from request"| node_attributes
node_policy -->|"configures transitions"| node_machine
node_policy -->|"generates response"| node_response
node_response -->|"serializes session"| node_attributes
node_policy -->|"returns response"| node_alexa
node_policy -->|"tracks intents"| node_voicelabs
node_tools -->|"validates and visualizes"| node_policy
node_jsonhelper -.->|"encodes objects"| node_response

click node_policy "https://github.com/allenai/alexafsm/blob/master/alexafsm/policy.py"
click node_states "https://github.com/allenai/alexafsm/blob/master/alexafsm/states.py"
click node_attributes "https://github.com/allenai/alexafsm/blob/master/alexafsm/session_attributes.py"
click node_response "https://github.com/allenai/alexafsm/blob/master/alexafsm/response.py"
click node_tools "https://github.com/allenai/alexafsm/blob/master/alexafsm/utils.py"
click node_jsonhelper "https://github.com/allenai/alexafsm/blob/master/alexafsm/make_json_serializable.py"
click node_intents "https://github.com/allenai/alexafsm/blob/master/alexafsm/amazon_intent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_policy,node_states,node_attributes,node_response,node_intents toneBlue
class node_tools,node_jsonhelper toneAmber
class node_machine,node_voicelabs,node_alexa toneMint
```

## Components

### Conversation runtime

- [Policy handler](https://github.com/allenai/alexafsm/blob/master/alexafsm/policy.py): `alexafsm/policy.py`
- [State definitions](https://github.com/allenai/alexafsm/blob/master/alexafsm/states.py): `alexafsm/states.py`
- [Session attributes](https://github.com/allenai/alexafsm/blob/master/alexafsm/session_attributes.py): `alexafsm/session_attributes.py`
- [Alexa response](https://github.com/allenai/alexafsm/blob/master/alexafsm/response.py): `alexafsm/response.py`
- [Alexa intent names](https://github.com/allenai/alexafsm/blob/master/alexafsm/amazon_intent.py): `alexafsm/amazon_intent.py`

### Inspection tools

- [FSM tools](https://github.com/allenai/alexafsm/blob/master/alexafsm/utils.py): `alexafsm/utils.py`
- [JSON conversion](https://github.com/allenai/alexafsm/blob/master/alexafsm/make_json_serializable.py): `alexafsm/make_json_serializable.py`

### External services

- **FSM engine**
- **VoiceLabs**

### Other components

- **Alexa request**

## Connections

- Alexa request → Policy handler: sends request (evidence: `README.md`)
- Policy handler → State definitions: builds from (evidence: `alexafsm/policy.py`)
- State definitions → Session attributes: creates from request (evidence: `alexafsm/states.py`)
- Policy handler → FSM engine: configures transitions (evidence: `alexafsm/policy.py`)
- Policy handler → Alexa response: generates response (evidence: `alexafsm/policy.py`)
- Alexa response → Session attributes: serializes session (evidence: `alexafsm/response.py`)
- Policy handler → Alexa request: returns response (evidence: `README.md`)
- Policy handler → VoiceLabs: tracks intents (evidence: `alexafsm/policy.py`)
- FSM tools → Policy handler: validates and visualizes (evidence: `alexafsm/utils.py`)
- JSON conversion → Alexa response: encodes objects
