Metadata-Version: 2.4
Name: aif-parser
Version: 0.1.0a0
Summary: Reference parser for the Agent Instruction Format (AIF)
Author-email: Skydope <augusto.natiello@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# AIF — Agent Instruction Format

[![CI](https://github.com/Skydope/aif/actions/workflows/ci.yml/badge.svg)](https://github.com/Skydope/aif/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/aif-parser)](https://www.npmjs.com/package/aif-parser)
[![PyPI](https://img.shields.io/pypi/v/aif-parser)](https://pypi.org/project/aif-parser/)
[![Spec v1.0](https://img.shields.io/badge/spec-v1.0.0-orange)](https://github.com/Skydope/aif/blob/main/docs/AIF-Specification-v1.0.0.md)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![License: CC BY 4.0](https://img.shields.io/badge/license-CC%20BY%204.0-green.svg)](https://creativecommons.org/licenses/by/4.0/)

> 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](https://skydope.github.io/aif/playground) — no install needed.

**Install a parser:**

```bash
# Python
pip install aif-parser

# TypeScript / Node.js
npm install aif-parser
```

**Parse a document:**

```python
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)
```

```typescript
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:**

```bash
python -m aif_parser pipeline.aif
```

---

## Example

```aif
---
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](./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](https://skydope.github.io/aif/playground) |

---

## Project Status

AIF is a **v1.0 draft**, open for community review. See [SPEC.md](./SPEC.md) for implementation status.

**Spec changes** follow the [RFC process](./CONTRIBUTING.md#specification-change-process) — open a GitHub Discussion before proposing changes to block types, field syntax, or the AST.

---

## Resources

- [Full Specification](./docs/AIF-Specification-v1.0.0.md) — complete grammar, AST schema, operator reference
- [CONTRIBUTING.md](./CONTRIBUTING.md) — how to contribute, RFC process
- [GOVERNANCE.md](./GOVERNANCE.md) — project governance
- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) — community standards
- [CHANGELOG.md](./CHANGELOG.md) — version history

---

## License

Format specification: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)

Reference implementations: [MIT](./LICENSE)