# vic-a-j/kairo-engine architecture

> Architecture diagram of the GitHub repository vic-a-j/kairo-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vic-a-j/kairo-engine
- Repository: https://github.com/vic-a-j/kairo-engine

## Overview

Kairo is a configuration-driven Python library for conditionally mutating incoming payloads. The main workflow loads YAML or JSON configuration, builds Canary rules, then evaluates them against a request: matching conditions gate mutations, and optional config is applied before the updated payload is returned. The graph covers the documented configuration and evaluation capabilities. Relationships are based on the README and shown source; no unsampled runtime modules are assumed.

Main entry points: [`kairo/main.py`](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/main.py) (Kairo engine), [`kairo/canary.py`](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/canary.py) (Canary evaluator), [`kairo/utils.py`](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/utils.py) (Config parsers), [`kairo/mutation.py`](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/mutation.py) (Payload mutation)

## Diagram (Mermaid)

```mermaid
flowchart TD

node_user(("Library caller"))
node_config_input["YAML / JSON config"]
node_request["Payload request"]
node_kairo["Kairo engine<br/>[main.py]"]
node_parsers["Config parsers<br/>[utils.py]"]
node_canary["Canary evaluator<br/>[canary.py]"]
node_condition["Condition matcher<br/>[condition.py]"]
node_mutation["Payload mutation<br/>[mutation.py]"]
node_jmespath["JMESPath library"]

node_user -->|"configures and runs"| node_kairo
node_config_input -->|"provides config"| node_parsers
node_kairo -->|"loads YAML or JSON"| node_parsers
node_parsers -->|"returns parsed data"| node_kairo
node_kairo -->|"creates and evaluates"| node_canary
node_kairo -->|"constructs condition"| node_condition
node_kairo -->|"constructs mutation"| node_mutation
node_request -->|"provides payload"| node_kairo
node_canary -->|"checks match"| node_condition
node_canary -->|"applies mutations"| node_mutation
node_mutation -->|"searches payload"| node_jmespath
node_kairo -->|"returns payload"| node_user

click node_kairo "https://github.com/vic-a-j/kairo-engine/blob/main/kairo/main.py"
click node_parsers "https://github.com/vic-a-j/kairo-engine/blob/main/kairo/utils.py"
click node_canary "https://github.com/vic-a-j/kairo-engine/blob/main/kairo/canary.py"
click node_condition "https://github.com/vic-a-j/kairo-engine/blob/main/kairo/condition.py"
click node_mutation "https://github.com/vic-a-j/kairo-engine/blob/main/kairo/mutation.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_user,node_config_input,node_jmespath toneIndigo
class node_request toneMint
class node_kairo,node_parsers,node_canary,node_condition,node_mutation toneTeal
```

## Components

### Other components

- **Library caller**
- **YAML / JSON config**
- **Payload request**
- [Kairo engine](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/main.py): `kairo/main.py`
- [Config parsers](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/utils.py): `kairo/utils.py`
- [Canary evaluator](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/canary.py): `kairo/canary.py`
- [Condition matcher](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/condition.py): `kairo/condition.py`
- [Payload mutation](https://github.com/vic-a-j/kairo-engine/blob/main/kairo/mutation.py): `kairo/mutation.py`
- **JMESPath library**

## Connections

- Library caller → Kairo engine: configures and runs (evidence: `README.md`)
- YAML / JSON config → Config parsers: provides config (evidence: `kairo/utils.py`)
- Kairo engine → Config parsers: loads YAML or JSON (evidence: `kairo/main.py`)
- Config parsers → Kairo engine: returns parsed data (evidence: `kairo/main.py`)
- Kairo engine → Canary evaluator: creates and evaluates (evidence: `kairo/main.py`)
- Kairo engine → Condition matcher: constructs condition (evidence: `kairo/main.py`)
- Kairo engine → Payload mutation: constructs mutation (evidence: `kairo/main.py`)
- Payload request → Kairo engine: provides payload (evidence: `README.md`)
- Canary evaluator → Condition matcher: checks match (evidence: `kairo/canary.py`)
- Canary evaluator → Payload mutation: applies mutations (evidence: `kairo/canary.py`)
- Payload mutation → JMESPath library: searches payload (evidence: `kairo/mutation.py`)
- Kairo engine → Library caller: returns payload (evidence: `kairo/main.py`)
