---

name: airalogy_protocol description: Expert guide for creating Airalogy Protocols (AIMD), Assigners (Python logic), and Validation Models. Use this to design digital workflows and experiments. input_schema: type: object properties: topic: type: string description: Specific area of the protocol to query. enum: [concepts, syntax, assigners, validation, templates] required: - topic

Airalogy Protocol Guide

Airalogy is a framework for data digitization. This skill teaches you how to build Protocols using AIMD (marked-up markdown) and Assigners (auto-computation logic).

1. Core Concepts

What is a Protocol? A document that defines a data collection workflow. It combines:

• UI/Content: Defined in .aimd files.
• Logic: Defined in Python "Assigners".
• Validation: Defined in Pydantic "Models".

Read more about Concepts

Read more about Concepts

2. Directory Structure

Airalogy protocols can be structured in two ways.

Standard Package (Recommended)

Atomic unit containing layout, logic, validation, and metadata.

Copymy_protocol/
├── protocol.toml       # Manifest: ID, version, name, description
├── protocol.aimd       # UI layout and content
├── model.py            # Pydantic models (validation)
├── assigner.py         # Python logic (calculations)
├── requirements.txt    # Python dependencies (optional)
├── README.md           # Documentation for users
└── assets/             # Static resources (images, banner, logo)

Single File (Simple)

For simple tools without complex logic.

Copymy_simple_protocol/
└── protocol.aimd
protocol.toml

Protocol Manifest (protocol.toml)

This file is mandatory for Standard Packages. It defines the protocol's identity and visual assets.

Copy[airalogy_protocol]
id = "my_protocol_id"       # Unique identifier (snake_case)
version = "1.0.0"           # Semantic versioning
name = "My Protocol Name"   # Human-readable title
description = "Brief description of what this protocol does."
logo = "assets/logo.png"    # Path to square logo
banner = "assets/banner.png"# Path to rectangular banner

3. Consistency Rules (Naming Conventions)

To ensure your protocol works, variable names MUST match across files.

[!IMPORTANT] The id you define in {{var|id...}} is the single source of truth. It must be identical in your Pydantic model field name and your Assigner's assigned_fields/dependent_fields.

4. AIMD Syntax (Practical Rules)

How to define variables, fields, and steps in markdown.

• {{var|name: type, ...}} defines inputs.
• {{step}} and {{check}} define workflow and checks.
• Tables use subvars inside var(...) blocks (do not use {{subvars}}).

✅ Correct variable definitions

Use title and description for all user-facing inputs.

Copy{{var|sample_id: str, title="Sample ID", description="Unique identifier for the sample"}}

✅ Correct table (subvars) definitions

Define table rows using subvars=[var(...), var(...)] inside a parent var.

Copy{{var|reaction_components,
    title="Reaction Components",
    description="PCR reaction mixture components",
    subvars=[
        var(
            component: str,
            title="Component",
            description="Reagent name"
        ),
        var(
            volume: float,
            title="Volume (µL)",
            description="Volume to add (µL)",
            ge=0
        )
    ]
}}

✅ Constrained numeric inputs

Always apply sensible constraints to numeric inputs.

Copy{{var|volume: float, ge=0, title="Volume (µL)", description="Volume to add in µL"}}

Read detailed Syntax Guide

5. Assigners (Logic)

How to write Python functions to automate calculations.

• @assigner decorator.
• Dependency graphs.
• Trigger modes (auto, manual).

Read Assigner Guide

6. Validation Models

How to ensure data integrity using Pydantic.

• Constraining inputs (min/max).
• Custom validators.

Read Validation Guide

7. Templates

Start with a template:

• Single File Protocol (Best for simple tools)
• Classic 3-File Protocol (Best for complex workflows)

8. Common Errors & Fixes (Based on Field Usage)

These are frequent issues observed when building protocols.

❌ Wrong variable definition syntax

Copy{{var|sample_id: str}}
{{subvars|reaction_components:
- component: "5X Phusion™ Plus Buffer"
}}

✅ Fix: Use full var definition and subvars on the parent var.

Copy{{var|sample_id: str, title="Sample ID", description="Unique identifier for the sample"}}
{{var|reaction_components, subvars=[var(component: str), var(volume: float)]}}

❌ Using {{subvars}}

{{subvars}} is not a valid AIMD tag. Use subvars=[...] inside a var.

❌ Missing metadata

All input variables should include title and description.

Copy{{var|reaction_volume: str, options=["20 µL", "50 µL"],
    default="20 µL",
    title="Reaction Volume",
    description="Total PCR reaction volume"}}

❌ Missing numeric constraints

Always constrain numeric inputs using ge, le, or other validators.

9. Validation & Quick Tests

Use these checks after editing a protocol:

AIMD syntax validation

Copypython -c "
from airalogy.markdown import validate_aimd
with open('protocol.aimd', 'r') as f:
    is_valid, errors = validate_aimd(f.read())
    print('Valid:', is_valid)
    print('Errors:', errors)
"

Model import validation

Copypython -c "
from your_protocol.model import ProtocolModel
model = ProtocolModel()
print('Model created successfully')
"

Assigner smoke test

Copypython -c "
from your_protocol.assigner import calculate_total_volume
# Mock standard reaction components
data = {
    'reaction_components': [
        {'component': 'Buffer', 'volume': 10.0},
        {'component': 'Water', 'volume': 40.0}
    ]
}
result = calculate_total_volume(data)
print('Result:', result.assigned_fields)
"

10. Authoring Checklist

• All var fields include title and description
• Tables use subvars inside a parent var (no {{subvars}})
• Numeric fields include constraints (ge, le, etc.)
• AIMD validation passes with no errors
• Model loads successfully
• Assigner outputs are as expected