aif-parser 0.1.0a0

Reference parser for the Agent Instruction Format (AIF)

AIF — Agent Instruction Format

A plain-text format for expressing executable instructions to autonomous agents, orchestration systems, and automated pipelines — with unambiguous syntax, explicit typing, and deterministic parse semantics.

Get Started

Try it live: AIF Playground — no install needed.

Install a parser:

# Python
pip install aif-parser

# TypeScript / Node.js
npm install aif-parser

Parse a document:

from aif_parser import parse_aif

result = parse_aif(open("pipeline.aif").read())
if result.valid:
    print(result.ast)
else:
    for err in result.errors:
        print(err)

import { parseAIF } from 'aif-parser'

const result = parseAIF(document)
if (result.valid) {
    console.log(result.ast)
} else {
    result.errors.forEach(e => console.error(e))
}

Validate any document:

python -m aif_parser pipeline.aif

---

Example

---
aif-version: 1.0
id:          deploy-pipeline-v1
title:       Production Deployment Pipeline
author:      platform-team
---

@Agent[test-runner] {
    name:        "Test Runner Agent"
    capabilities: [ test, coverage ]
    timeout:     10m
    on-error:    @ErrorPolicy::stop
}

@Task[run-tests] {
    title:     "Run test suite with coverage"
    agent:     test-runner
    priority:  @Priority::high
    input {
        branch:   String
        coverage: Boolean = true
    }
    output {
        passed:   Boolean
        coverage: Number
    }
}

@Rule[require-coverage] {
    title:    "Minimum 80% test coverage"
    severity: @Severity::error
    assert:   "output.coverage >= 80"
    message:  "Coverage below required threshold."
}

@Workflow[deploy-production] {
    title:   "Full Production Deployment"
    trigger: @Trigger::manual
    steps:   [ run-tests ]
    timeout: 60m
}

---

Why AIF?

Markdown was designed to convert plain text to HTML for humans. When repurposed as an agent instruction medium, its structural ambiguity becomes operational risk.

Capability	Markdown / AGENTS.md	AIF
Deterministic parsing	Parser-dependent	Guaranteed
Block addressing	None	Every block has a stable ID
Typed fields	None	Full primitive type system
Two-phase validation	None	Structural + semantic
Conditional logic	None	@Branch + AEL expressions
Secret handling	None	@Secret with vault refs
Canonical AST	Not standardised	JSON AST spec included

---

Block Types

Block	Executable	Purpose
@Agent	Yes	Declare an agent and its capabilities
@Task	Yes	Executable unit of work
@Step	Yes	Sequential instruction within a task
@Rule	Yes	Declarative constraint / policy
@Branch	Yes	Conditional flow routing
@Workflow	Yes	Orchestration graph (entry point)
@Schema	No	Reusable type declaration
@Param	No	Runtime variable with type and constraints
@Secret	No	Credential reference (vault path, not plaintext)
@Note	No	Human annotation (non-executable)

Full syntax reference in docs/AIF-Specification-v1.0.0.md.

---

Interoperability

Target	How AIF maps
LLM Agents (Claude, GPT, Gemini)	Parse plain text. @Workflow is the entry point. Block IDs enable precise execution logs.
Automation Platforms (n8n, Make, Zapier)	@Task → workflow nodes. input/output blocks → typed data contracts.
Multi-Agent Orchestrators (CrewAI, AutoGen, LangGraph)	@Agent → agent registry. depends-on → task assignment. @Rule → guardrails.
Embedded / IoT	Minimal grammar parses in C or Rust. @Secret → hardware security modules.

---

Packages

Package	Language	Status	Install
aif-parser	Python	Reference impl	pip install aif-parser
aif-parser	TypeScript	Reference impl	npm install aif-parser
aif-playground	React	Interactive editor	Try online

---

Project Status

AIF is a v1.0 draft, open for community review. See SPEC.md for implementation status.

Spec changes follow the RFC process — open a GitHub Discussion before proposing changes to block types, field syntax, or the AST.

---

Resources

• Full Specification — complete grammar, AST schema, operator reference
• CONTRIBUTING.md — how to contribute, RFC process
• GOVERNANCE.md — project governance
• CODE_OF_CONDUCT.md — community standards
• CHANGELOG.md — version history

---

License

Format specification: CC BY 4.0

Reference implementations: MIT