===== docs-imported/AEON FILE.md =====
# AEON FILE

Owner: Durga Sai
Tags: aeon

An `.aeon` file defines the behavior of an agent.

Each agent:

- stores some data
- performs tasks
- shares results with other agents

---

### Basic Structure

Every agent file follows this structure:

```
Include Library

Private {
    // variables
}

Task <task_name> {
    // logic
}

Route {
    // execution flow
}
```

---

This section explains the structure of an agent using the **EmergencyAgent.aeon** file as an example

### 1. Include (Optional)

You can include Python libraries at the top:

```
Include time
Include datetime
```

These can be used inside tasks.

---

### 2. Variables (Private & Public)

All variables are defined inside the `Private` block.

```
Private {
    int count;
    string status = "idle";
    Public int result;
}
```

- `Private` → only this agent can use
- `Public` → shared with other agents

---

### 3. Tasks (Core Logic)

Tasks define what the agent does.

```
Task process {
    result = count * 2
}
```

You can also use conditions:

```
Task check {
    IF count > 10 {
        result = 1
    } ELSE {
        result = 0
    }
}
```

---

### 4. Using Python in Tasks

You can directly call Python functions:

```
Task report {
    log("Result:", result)
    time.sleep(1)
}
```

[Functions](LIB FILE/Functions.md) 

---

### 5. Route Block (Execution Flow)

The `Route` block controls which task runs.

```
Route {
    on_start : process
    count > 10 : check
    on_end : report
}
```

- `on_start` → runs first
- conditions → decide next tasks
- `on_end` → runs at the end

---

### 6. Complete Example

```
Include time

Private {
    int count = 5
    Public int result = 0
}

Task process {
    result = count * 2
}

Task report {
    log("Final result:", result)
    time.sleep(1)
}

Route {
    on_start : process
    on_end : report
}
```

---

### Understanding the Agent Structure

- Variables → what information the agent keeps track of
- Tasks → the actions the agent performs
- Route → decides when each action should run

Together, this helps the agent work step-by-step and interact smoothly with other agents in the system.

[AEON Memory](AEON FILE/AEON Memory.md)

[AEON Includes](AEON FILE/AEON Includes.md)

[TASKS](AEON FILE/TASKS.md)

===== docs-imported/AEON FILE/AEON Includes.md =====
# AEON Includes

Owner: Durga Sai
Verification: Verified
Tags: aeon

# Feature Deep-Dive: Agent Includes (`.aeon`)

Inside the Agent Definition context (`.aeon` files), the `Include` keyword serves a fundamentally different purpose compared to the global orchestrator.

In an `.aeon` file, `Include` is used to import reusable modules, shared functions, or native Python libraries directly into the agent’s internal logic.

## Resolution Order

When you use `Include my_module` inside an `.aeon` file, the transpiler follows a specific fallback order to resolve the import:

1. **Local `.lib` Files**: First, it checks if a file named `my_module.lib` exists within your project directory.
2. **Inbuilt Libraries**: Second, it checks against ORCH’s default native library system (Note: There are currently no inbuilt libraries available).
3. **Python Libraries & Scripts**: Finally, if both checks fail, it assumes `my_module` is either an installed Python package or an external `.py` script and uses the Python runtime to import it.

***Important Constraint:** You cannot use relative imports pathing for Python scripts yet (e.g., `Include ../utils`), you can only provide the absolute module name.*

## Usage Examples

Below are clean examples demonstrating how the compiler resolves different scenarios based on the fallback order. Unlike the orchestrator, you **cannot** instantiate arrays of objects `{N}` here.

### 1. Including a Local `.lib` File

If you have a file named `math_logic.lib` in your folder, this pulls its shared functional logic cleanly into the agent.

```
Include math_logic
```

### 2. Including Native Python Libraries

If no local `.lib` file or ORCH inbuilt module matches, the system naturally delegates to Python’s execution space. This is how you quickly bring powerful ecosystem libraries into your agent’s `Func` scopes.

```
# Automatically resolved as standard Python libraries!
Include math
Include json
```

### 3. Including External Python Scripts

Identical to a library, you can seamlessly import your own local `.py` scripts (for example, `utils.py`). Just remember, relative paths (e.g., `../utils`) are strictly forbidden.

```
# Resolves the external 'utils.py' script located in your root environment
Include utils
```

By supporting library includes at the agent level natively across all three fallback contexts, agents are empowered to freely share complex algorithmic logic securely without redundantly rewriting functional blocks.

===== docs-imported/AEON FILE/AEON Memory.md =====
# AEON Memory

Owner: Durga Sai

# Feature Deep-Dive: Agent Sandbox Memory (`.aeon`)

Within an Agent Definition (`.aeon` file), memory requires explicit scoping constraints. All variables for an agent must be declared tightly within its `Private { ... }` block to instruct the runtime how exposed the internal data is allowed to be.

The available variable types in ORCH are: `int`, `float`, `char`, `string`, `list`, `tuple`.

## Defining Memory Scopes

### 1. `Private` (Explicit Constraint)

Variables explicitly prefixed with `Private` remain strictly protected from the rest of the graph. No other agent can access them.

```
Private {
    Private int internal_counter = 0;
}
```

### 2. Not Specifying Anything (Implicit Private)

If you declare variables with normal types *without* utilizing the `Public` or `Private` prefix, **it defaults to Private automatically**. This is the standard shorthand for writing agent structures.

```
Private {
    # Implicitly private. Identical behavior to 'Private string key = "abc";'
    string key = "abc";
}
```

### 3. `Public` (Graph-Exposed)

By prefixing a declaration with the `Public` keyword, the system manages the variable structure inside the agent’s memory layout, but deliberately pushes an accessible alias pointing directly to the **Graph Level Memory**, broadcasting it natively to the rest of the application.

```
Private {
    # Any other agent in the system can read this variable natively!
    Public float satisfaction = 1.0;
}
```

## How to Use Your Own Memory

Inside your `Task` blocks, you manipulate these variables dynamically:
- **Using Private State:** You can call `Private.internal_counter` explicitly, or just `internal_counter` inherently since it defaults to the local agent tracking scope.
- **Using Public State:** You can call `Public.satisfaction`.

## How to Access Other Agents’ Variables

If another agent (e.g., `DataCollector.aeon`) declares a `Public list raw_data = [];`, it puts that data into the central graph-level memory under that specific agent’s namespace.

To read and use that variable inside *this* agent, you query it from the global pool using the `Public` accessor **followed by the target Agent’s name**.

**Inside Agent B’s Task block:**

```
Task analyze {
    # Fetches 'raw_data' exported publicly from the DataCollector agent specifically
    my_local_list = Public.DataCollector.raw_data;

    # If DataCollector was cloned as an array (e.g. Include DataCollector{3})
    # You must specify the index of the clone!
    my_clone_list = Public.DataCollector[1].raw_data;
}
```

===== docs-imported/AEON FILE/TASKS.md =====
# TASKS

Owner: Durga Sai
Verification: Verified
Tags: aeon

# Feature Deep-Dive: Tasks

A `Task` block is where an agent mutates state. Think of `Task`s as the distinct “actions” an agent knows how to perform. However, **Tasks are entirely passive**—they don’t choose when to run. Only the agent’s `Route` block decides which Task fires.

## The Mathematics Sub-Language

To ensure security and keep state manipulation clean, Tasks do not run arbitrary Python. They run inside ORCH’s constrained expression-based sub-language.

Operations supported in a Task body:
- **Variable Assignments:** E.g., `score = score + 1;`
- **Conditional Branches:** `IF { ... } ELSE { ... }`
- **Logic Statements:** `AND`, `OR`
- **Mathematical Operators:** `<`, `>`, `<=`, `>=`, `==`, `!=`, `+`, `-`, `/`, `*`

## Example

```
Task evaluate_data {
    # Basic math and assignment
    confidence = confidence * 0.95;

    # Conditional checks
    IF error_rate > 5.0 {
        # Inter-agent public mutation
        Public.status = "failure";
    } ELSE {
        # Invoking an internal Func block or library
        Public.status = format_success_msg(confidence);
    }
}
```

## Characteristics

- **Strict Logic Constraint:** By restricting exactly what a Task can do, ORCH keeps state mutations clearly defined without getting bogged down in boilerplate API calls or complex logic nested at the wrong layer.
- **Delegation:** When a Task finds something too complex to calculate mathematically, it pushes that calculation to a `Func` block using `CALL`.

===== docs-imported/index.md =====
# DSL USER GUIDE

# ORCH Agent Graph Orchestration Language

ORCH is a domain-specific language for building and orchestrating systems made up of multiple intelligent agents. You write agents, give them tasks and memory, and use a central Route block to control which agent runs when.

Programs in ORCH are structured as a **graph of agents**. Each agent is an independent unit with its own private state and task logic. A single orchestrator file ties them all together, defining which agents exist and how execution flows between them.

---

## Features of the ORCH System

ORCH is not just another agent-chaining framework; it is a purpose-built Domain-Specific Language integrated closely with a Python execution engine (`orch-lib`). The combination of this domain-specific grammar and robust routing runtime yields several standout features:

### 1. Centrally Controlled Execution Automation

Unlike implicit state-machine or message-bus setups where agents call each other, ORCH centralizes the orchestrator flow.
- At the **Graph** level, the `Route` block decides which node/agent operates.
- At the **Agent** level, the `Route` block restricts agent scope to simple execution of Tasks.
- **Result:** You can view a project and immediately trace its state evolution and path without reading deeply into execution details.

### 2. Distributed Compilation

The ORCH execution flow introduces a compiler pipeline composed of two layers:
- **Fast OCaml Build:** A statically typed `main.exe` executable guarantees the stability and structural soundness of the written DSL. It parses AST structures at high speed.
- **Generative Automation:** Instead of running the DSL line-by-line via interpreter, the architecture transpiles the tree into native Python bindings (via `converter.py`), resulting in highly integrated and performant executable code.

### 3. Sandboxed Python Escapes (`Func` blocks)

You are not constrained to an obscure declarative language’s limits. The `Func` block directly surfaces **unrestricted, native Python**.
If your agent needs to perform an API call or run a Machine Learning model, the logic lives securely inside a `Func {}`.

### 4. Simplified Memory Scoping

You do not need to deal with event queues to get memory working between agents.
- Need graph-wide visibility? Prefix with `Public`.
- Need isolated safety? Prefix with `Private`.
`orch-lib` translates this behind the scenes directly into structured contexts for every single agent and task.

### 5. Parallel/Multi-Agent Cloning Support

Through the simple array syntax `Include AgentB{5}`, ORCH will silently duplicate, register, and provision 5 totally disjoint instances of `AgentB`, handling all the memory initialization.

### 6. Built-in Math and Expression Evaluation Sub-language

ORCH’s `Task` body behaves identically to basic `Python` expression assignments with complete support for conditional checks (`IF / ELSE`), logic bindings (`AND`, `OR`), and math operations (`+`, `-`, `/`, `*`), without needing the verbosity of a full language.

---

[Usage and Structure](Usage and Structure.md)

[ORCH FILES](ORCH FILES.md)

[AEON FILE](AEON FILE.md)

[LIB FILE](LIB FILE.md)

[Routing](Routing.md)

===== docs-imported/LIB FILE.md =====
# LIB FILE

Owner: Durga Sai

A `.lib` file is used to define reusable functions that can be used inside agent files.

It helps you:

- avoid repeating logic
- write complex operations in Python
- reuse functions across multiple agents

---

### Example (math.lib)

```
Func add {
    result = a + b
    return result;
}

Func multiply {
    result = a * b
    return result;
}
```

---

### Explanation

- `Func` → defines a function
- Inside the block → you can write Python code
- `return` → specifies the output of the function

---

### Using Library Functions in Agents

First, include the library in your agent file:

```
Include math
```

Then call the function inside a task:

```
Task compute {
    result = add(a, b)
}
```

---

### Key Points

- `.lib` files only contain functions
- Functions use Python syntax
- Must end with `return <variable>;`
- Can be reused across multiple agents

---

[Functions](LIB FILE/Functions.md)

===== docs-imported/LIB FILE/Functions.md =====
# Functions

Owner: Durga Sai
Verification: Verified
Tags: aeon

# Funcs

While ORCH utilizes a custom syntactical sub-language for mathematical assignments inside `Task` blocks, Multi-Agent systems routinely require calling APIs, performing heavy machine learning inference, interacting with databases, or parsing complex text.

The `Func` block is the ultimate escape hatch: **The body of a Func block is unrestricted Python.**

## Defining a Func

A `Func` lets you write standard Python precisely where you need computational payload without cluttering the declarative nature of the agent’s routing structure.

The only rule is that a `Func` must conclude by returning a variable to pass back to the DSL environment.

### Syntax Example

```
Func validate_database {
    # Pure python is accepted here natively
    import sqlite3
    import pandas as pd

    # You can access agent memory natively by reading the mapped objects
    threshold = Private.error_threshold

    try:
        conn = sqlite3.connect('local.db')
        data = pd.read_sql("SELECT * FROM metrics", conn)
        conn.close()

        if len(data) > threshold:
            result_code = 1
        else:
            result_code = 0
    except Exception as e:
        result_code = -1

    # The block must export a returned variable to hand back to the task
    return result_code;
}
```

## How to use a Func

You invoke a `Func` from within a `Task` block utilizing the `CALL` operator.

```
Task handle_db {
    # Calling the Python escape hatch logic
    db_status = validate_database();

    IF db_status == 1 {
        alert_flag = true;
    }
}
```

## Why it works this way

By isolating Python inside `Func` blocks and isolating Mathematics/State inside `Task` blocks, the system inherently forces developers to separate execution heavy-lifting from standard agent orchestration logic. It combines the readability of a DSL with the limitless ecosystem of the Python language.

===== docs-imported/ORCH FILES.md =====
# ORCH FILES

Owner: Durga Sai
Verification: Verified
Tags: orch

An `.orch` file is used to define a workflow using your DSL.

It describes a sequence of tasks, what each task does, and how they are connected.

You can think of it as a script that controls how different steps are executed.

---

## ORCH File Structure

An ORCH file follows a fixed structure:

---

### 1. Include Section

We first include all required files.

- Agent files are included using `Include AgentName`
- Multiple instances can be created using `{n}`

```
Include IntersectionAgent {4}
Include ReportAgent
```

This is where we load all agents that will be used in the system.

[Orch Includes](ORCH FILES/Orch Includes.md)

---

### 2. Global Variables

After including agents, we define global variables.

- These variables control the execution flow
- Example: `trafficStage`, `responseMode`

```
int trafficStage = 0
int responseMode = 0
```

They are mainly used inside the Route block for decision making.

---

### 3. Route Block

The Route block defines the execution logic.

- It decides which agent runs based on conditions
- Each rule follows: `condition : Agent {instance}`
- Conditions are checked from top to bottom

#### on_start and on_end

- `on_start : Agent` → runs once at the beginning of execution
- `on_end : Agent` → runs once at the end of execution

They are special rules inside the `Route` block used to:

- initialize the system (`on_start`)
- perform final tasks like reporting or cleanup (`on_end`)

This is the core part of the ORCH file where the entire system flow is controlled.

```
Route {
		on_start : SetupAgent
    trafficStage == 0 : IntersectionAgent {1}
    trafficStage == 1 : ZoneAgent {1}
    trafficStage == 1 : ZoneAgent {2}
    trafficStage == 2 AND responseMode == 2 : EmergencyAgent {1}
    on_end : LogAgent
}
```

---

[ORCH MEMORY](ORCH FILES/ORCH MEMORY.md)

===== docs-imported/ORCH FILES/Orch Includes.md =====
# Orch Includes

Owner: Durga Sai
Verification: Verified
Tags: orch

# Feature Deep-Dive: Orchfile Includes (`.orch`)

In the Global Dispatcher context (`.orch` files), the `Include` keyword is structurally responsible for **instantiating agents into the execution graph**.

You use `Include` in an `.orch` file to bind `.aeon` agent definitions to the project runtime. If an agent is not explicitly included via an `Include` statement, it will not be created or executed, even if its definition file exists in the directory.

## Basic Includes

To pull a single instance of an agent into the runtime graph, use the keyword followed by the agent name.

```
# Include a single instance of an agent
# Assuming 'DataCollector.aeon' exists in the folder
Include DataCollector
```

Once included, the `DataCollector` can be targeted by the Global `Route` block.

## Instantiating Parallel Agent Clones

A uniquely powerful feature of the ORCH engine is its ability to instantly clone agent configurations to create multiple parallel processors.
You can spin up `N` identical agents that share the same `.aeon` instructions but maintain their own completely isolated memory scopes.

You do this by adding bracketed instantiation sizes `{N}`.

```
# Automatically create 5 separate instances of ProcessingAgent
Include ProcessingAgent{5}
```

*Behind the scenes, `orch-lib` handles provisioning 5 parallel instances and registering them dynamically.*

# Environment Variables (`.env`)

The ORCH compiler contains a natively integrated pipeline specifically to load environmental secrets safely directly into the running graph.

```python
# Automatically load all variables from `.env` directly into Global Graph Memory
Include env
```

[Environment (.env)](Orch%20Includes/Environment%20(%20env)%20338fa88181fa8075b49fd11f282d3369.md)

===== docs-imported/ORCH FILES/Orch Includes/Environment ( env).md =====
# Environment (.env)

Owner: Durga Sai
Verification: Verified
Tags: orch

## Sourcing Environment Variables

By declaring the specific reserved phrase `Include env` in your global orchestrator (`.orch`), the transpiler hooks directly to the backend to automatically load and parse a `.env` file from the runtime directory.

```
# Automatically load all variables from `.env` directly into Global Graph Memory
Include env
```

All key-value pairs established in the `.env` file are seamlessly unpacked and bundled into the overarching **Graph Memory** layer as explicitly public variables.

## 1. Example `.env` File

```
API_KEY=YOUR_SECRET_KEY
DB_HOST=localhost
```

## 2. Accessing From Inside an Agent (`Task` block)

Because the environment pairs map entirely into the graph’s public memory structure, any initialized agent can freely read those variables in their `Task` blocks by specifically reaching into the global scope using the `Public` accessor.

```
Task check_connection {
    # Natively fetches the variable loaded from the .env into Graph Memory
    current_key = Public.API_KEY;
}
```

## 3. Accessing From Python (`Func` block)

Because the ORCH compilation engine utilizes standard `dotenv` libraries under the hood during the script’s execution phase, `.env` variables are completely simultaneously injected straight into the operating system shell environment.

This means any pure Python script running within an agent’s `Func` escape hatch can use standard Python `os` modules to fetch them natively, completely sidestepping standard Graph Memory:

```
Func check_native_env {
    import os
    # Fetch natively from the underlying OS environment
    python_key = os.environ.get("API_KEY")
    return python_key;
}
```

===== docs-imported/ORCH FILES/ORCH MEMORY.md =====
# ORCH MEMORY

Owner: Durga Sai
Verification: Verified
Tags: orch

# Feature Deep-Dive: Global Memory (`.orch`)

Memory handling inside the Global Dispatcher (`.orch` file) establishes overarching state that is inherently **public** to the entire project.

The available variable types in ORCH are: `int`, `float`, `char`, `string`, `list`, `tuple`.

## How to Define Global Memory

Global memory is defined freely at the top level of the `.orch` file (they are not enclosed within any `Private` or functional block). You simply declare a type and a variable name.

```
Include ProcessingAgent

# Defining global memory
int totalRounds = 10
string currentMode = "competitive"
```

## How to Use Global Memory in `.orch` Files

Within the `.orch` file itself, these variables are primarily used to direct the Global `Route` block. They act as the state conditions determining which Agent gets to run next.

```
Route {
   # Using global variables natively without prefixes in the orchestrator
   totalRounds > 0 : ProcessingAgent
}
```

## How to Use Global Memory in `.aeon` Files

Because any variable defined in the `.orch` file is implicitly placed into the **Graph/Global Memory**, they are universally accessible to all `.aeon` agents connected to the graph.

Inside any agent’s `Task` blocks, you can securely access these variables by using the `Public` accessor prefix.

```
Task evaluate_mode {
    # Accessing 'currentMode' globally defined in the .orch file
    IF Public.currentMode == "competitive" {
        # Perform action
        Public.totalRounds = Public.totalRounds - 1
    }
}
```

Global memory variables act as the system-wide static glue binding agent logic. They track the overarching progress, whereas agent-specific logic states belong strictly nested within the agents themselves.

===== docs-imported/Routing.md =====
# Routing

Owner: Durga Sai
Verification: Verified
Tags: Design

# Feature Deep-Dive: Routing

The `Route` block represents the central authority of any ORCH project. In ORCH, agents and tasks **never** trigger each other directly. Instead, all transitions and control flows are centralized inside `Route` blocks.

`Route` blocks are evaluated top-down. The first condition that evaluates to `true` is chosen to execute next.

There are exactly two variations of the `Route` block: **Global Routing** and **Agent Routing**.

---

## 1. Global Routing (in `.orch`)

Located in the Global Dispatcher, this route block decides *which Agent* gets to run.

### Reserved Keywords

- `on_start`: (Optional) Triggered exactly once when the program officially begins.
- `on_end`: (Optional) Triggered when the graph concludes.

### Example

```
int errors = 0

Route {
    # The first condition to match will trigger the corresponding Agent
    errors > 5 : AlertAgent          # Triggers AlertAgent if critical error
    on_start : InitAgent             # Always kicks off here first
}
```

---

## 2. Routing to Specific Clones (`{i}`)

When dealing with an array of cloned agents initialized in your global orchestrator (e.g., `Include WorkerAgent{3}`), you can explicitly route to a specific instance of that agent class by using the zero-indexed `{i}` syntax.

```
# Correct targeted deterministic routing for clones
Route {
    condition_A : WorkerAgent{0}    # Triggers the first clone explicitly
    condition_B : WorkerAgent{1}    # Triggers the second clone explicitly
}
```

### Warning: Non-Deterministic Execution Order

A critical detail when designing routes is ensuring conditions are mutually exclusive if exact execution order matters.

If you map the **exact same trigger condition** to multiple different targets inside the exact same `Route` block (or if you map a condition to an unindexed class of initialized clones), the ORCH compiler does not guarantee which one will execute first. Order will be highly variable and non-deterministic on every run.

**Avoid duplicate triggers** unless the sequence of execution does not matter to your logic.

---

## 3. Agent Routing (in `.aeon`)

Located inside every Agent Definition, this route block decides *which internal Task* is executed when the global route gives control to the Agent.

### Example

```
Route {
    health < 30 : heal       # If low health, agent focuses on healing
    on_start : fight         # Otherwise, agent defaults to fighting
}
```

===== docs-imported/Usage and Structure.md =====
# Usage and Structure

Owner: Durga Sai
Verification: Verified
Tags: Usage

# ORCH DSL: Usage and Project Structure

The ORCH DSL provides a distributed compilation pipeline. The front-end compiler, `main.exe` (written in OCaml), parses your ORCH project, generates a JSON representation (AST), and then invokes a Python script (`converter.py`) to transpile the project into a runnable Python application leveraging `orch-lib`.

## Usage

You can run the compiler using the following syntax:

```bash
./main.exe [--dryrun] [--verbose] [--no-delete] <project_directory>
```

### Options

- `<project_directory>` : **(Required)** Specifies the path to the directory containing your project.
- `-dryrun` : **(Optional)** Generates the Python file without executing it.
- `-verbose` : **(Optional)** Enables verbose logging.
- `-no-delete` : **(Optional)** Prevents automatic cleanup of the generated `.json` and `.py` files.

### Internal Workflow

1. **Parsing:** `main.exe` reads the project in `<project_directory>`.
2. **JSON Generation:** Constructs an AST and outputs it as JSON.
3. **Transpilation:** Converts the JSON file to a Python execution file (`<project_name>.py`).
4. **Execution:** Automatically runs the Python file.
5. **Cleanup:** Deletes intermediate generated `.json` and `.py` files.

---

## Project Structure

Your project should exist within a single directory. The ORCH DSL is designed to cleanly separate global orchestration logic from agent-specific task logic.

### Directory Components

Your directory can contain the following:
- **The Global Dispatcher (`.orch` files):** The main entry point for the entire project.
- **Agent Definitions (`.aeon` files):** The individual files or blocks implementing your specific agents.
- **`*.lib`:** (Optional) Sub-library files containing shared functions.
- **`*.py`:** (Optional) External Python scripts for direct absolute imports. Note: relative imports are NOT accepted.

### The Global Dispatcher (`.orch` files)

The orchestrator handles overall global routing logic and configures which agents exist. Core blocks that can be there:
- **Includes:** Defines the agents to be pulled in.
- **Global Variables:** Top-level state accessible across the entire structure.
- **Global Route:** Central authority deciding which agent runs next.

### The Agent Definition (`.aeon` files)

An agent defines its own memory, executable actions, internal routing logic, and python bindings. Component blocks that can be there:
- **`Private`:** Defines the agent memory and internal state variables (both private scope and public scope).
- **`Task`:** Defines executable actions intended to mutate state.
- **`Func`:** Defines custom inline native Python extensions for complex capability.
- **`Route`:** Defines the internal, agent-specific routing rules dictating which task executes.

### The Library Definition (`.lib` files)

A Library file is just a list of functions in a file that needed to be imported in `.aeon` files

===== docs/AEON FILE.md =====
# AEON FILE

Owner: Durga Sai
Tags: aeon

An `.aeon` file defines the behavior of an agent.

Each agent:

- stores some data
- performs tasks
- shares results with other agents

---

### Basic Structure

Every agent file follows this structure:

```
Include Library

Private {
    // variables
}

Task <task_name> {
    // logic
}

Route {
    // execution flow
}
```

---

This section explains the structure of an agent using the **EmergencyAgent.aeon** file as an example

### 1. Include (Optional)

You can include Python libraries at the top:

```
Include time
Include datetime
```

These can be used inside tasks.

---

### 2. Variables (Private & Public)

All variables are defined inside the `Private` block.

```
Private {
    int count;
    string status = "idle";
    Public int result;
}
```

- `Private` → only this agent can use
- `Public` → shared with other agents

---

### 3. Tasks (Core Logic)

Tasks define what the agent does.

```
Task process {
    result = count * 2
}
```

You can also use conditions:

```
Task check {
    IF count > 10 {
        result = 1
    } ELSE {
        result = 0
    }
}
```

---

### 4. Using Python in Tasks

You can directly call Python functions:

```
Task report {
    log("Result:", result)
    time.sleep(1)
}
```

[Functions](LIB FILE/Functions.md) 

---

### 5. Route Block (Execution Flow)

The `Route` block controls which task runs.

```
Route {
    on_start : process
    count > 10 : check
    on_end : report
}
```

- `on_start` → runs first
- conditions → decide next tasks
- `on_end` → runs at the end

---

### 6. Complete Example

```
Include time

Private {
    int count = 5
    Public int result = 0
}

Task process {
    result = count * 2
}

Task report {
    log("Final result:", result)
    time.sleep(1)
}

Route {
    on_start : process
    on_end : report
}
```

---

### Understanding the Agent Structure

- Variables → what information the agent keeps track of
- Tasks → the actions the agent performs
- Route → decides when each action should run

Together, this helps the agent work step-by-step and interact smoothly with other agents in the system.

[AEON Memory](AEON FILE/AEON Memory.md)

[AEON Includes](AEON FILE/AEON Includes.md)

[TASKS](AEON FILE/TASKS.md)

===== docs/AEON FILE/AEON Includes.md =====
# AEON Includes

Owner: Durga Sai
Verification: Verified
Tags: aeon

# Feature Deep-Dive: Agent Includes (`.aeon`)

Inside the Agent Definition context (`.aeon` files), the `Include` keyword serves a fundamentally different purpose compared to the global orchestrator.

In an `.aeon` file, `Include` is used to import reusable modules, shared functions, or native Python libraries directly into the agent’s internal logic.

## Resolution Order

When you use `Include my_module` inside an `.aeon` file, the transpiler follows a specific fallback order to resolve the import:

1. **Local `.lib` Files**: First, it checks if a file named `my_module.lib` exists within your project directory.
2. **Inbuilt Libraries**: Second, it checks against ORCH’s default native library system (Note: There are currently no inbuilt libraries available).
3. **Python Libraries & Scripts**: Finally, if both checks fail, it assumes `my_module` is either an installed Python package or an external `.py` script and uses the Python runtime to import it.

***Important Constraint:** You cannot use relative imports pathing for Python scripts yet (e.g., `Include ../utils`), you can only provide the absolute module name.*

## Usage Examples

Below are clean examples demonstrating how the compiler resolves different scenarios based on the fallback order. Unlike the orchestrator, you **cannot** instantiate arrays of objects `{N}` here.

### 1. Including a Local `.lib` File

If you have a file named `math_logic.lib` in your folder, this pulls its shared functional logic cleanly into the agent.

```
Include math_logic
```

### 2. Including Native Python Libraries

If no local `.lib` file or ORCH inbuilt module matches, the system naturally delegates to Python’s execution space. This is how you quickly bring powerful ecosystem libraries into your agent’s `Func` scopes.

```
# Automatically resolved as standard Python libraries!
Include math
Include json
```

### 3. Including External Python Scripts

Identical to a library, you can seamlessly import your own local `.py` scripts (for example, `utils.py`). Just remember, relative paths (e.g., `../utils`) are strictly forbidden.

```
# Resolves the external 'utils.py' script located in your root environment
Include utils
```

By supporting library includes at the agent level natively across all three fallback contexts, agents are empowered to freely share complex algorithmic logic securely without redundantly rewriting functional blocks.

===== docs/AEON FILE/AEON Memory.md =====
# AEON Memory

Owner: Durga Sai

# Feature Deep-Dive: Agent Sandbox Memory (`.aeon`)

Within an Agent Definition (`.aeon` file), memory requires explicit scoping constraints. All variables for an agent must be declared tightly within its `Private { ... }` block to instruct the runtime how exposed the internal data is allowed to be.

The available variable types in ORCH are: `int`, `float`, `char`, `string`, `list`, `tuple`.

## Defining Memory Scopes

### 1. `Private` (Explicit Constraint)

Variables explicitly prefixed with `Private` remain strictly protected from the rest of the graph. No other agent can access them.

```
Private {
    Private int internal_counter = 0;
}
```

### 2. Not Specifying Anything (Implicit Private)

If you declare variables with normal types *without* utilizing the `Public` or `Private` prefix, **it defaults to Private automatically**. This is the standard shorthand for writing agent structures.

```
Private {
    # Implicitly private. Identical behavior to 'Private string key = "abc";'
    string key = "abc";
}
```

### 3. `Public` (Graph-Exposed)

By prefixing a declaration with the `Public` keyword, the system manages the variable structure inside the agent’s memory layout, but deliberately pushes an accessible alias pointing directly to the **Graph Level Memory**, broadcasting it natively to the rest of the application.

```
Private {
    # Any other agent in the system can read this variable natively!
    Public float satisfaction = 1.0;
}
```

## How to Use Your Own Memory

Inside your `Task` blocks, you manipulate these variables dynamically:
- **Using Private State:** You can call `Private.internal_counter` explicitly, or just `internal_counter` inherently since it defaults to the local agent tracking scope.
- **Using Public State:** You can call `Public.satisfaction`.

## How to Access Other Agents’ Variables

If another agent (e.g., `DataCollector.aeon`) declares a `Public list raw_data = [];`, it puts that data into the central graph-level memory under that specific agent’s namespace.

To read and use that variable inside *this* agent, you query it from the global pool using the `Public` accessor **followed by the target Agent’s name**.

**Inside Agent B’s Task block:**

```
Task analyze {
    # Fetches 'raw_data' exported publicly from the DataCollector agent specifically
    my_local_list = Public.DataCollector.raw_data;

    # If DataCollector was cloned as an array (e.g. Include DataCollector{3})
    # You must specify the index of the clone!
    my_clone_list = Public.DataCollector[1].raw_data;
}
```

===== docs/AEON FILE/TASKS.md =====
# TASKS

Owner: Durga Sai
Verification: Verified
Tags: aeon

# Feature Deep-Dive: Tasks

A `Task` block is where an agent mutates state. Think of `Task`s as the distinct “actions” an agent knows how to perform. However, **Tasks are entirely passive**—they don’t choose when to run. Only the agent’s `Route` block decides which Task fires.

## The Mathematics Sub-Language

To ensure security and keep state manipulation clean, Tasks do not run arbitrary Python. They run inside ORCH’s constrained expression-based sub-language.

Operations supported in a Task body:
- **Variable Assignments:** E.g., `score = score + 1;`
- **Conditional Branches:** `IF { ... } ELSE { ... }`
- **Logic Statements:** `AND`, `OR`
- **Mathematical Operators:** `<`, `>`, `<=`, `>=`, `==`, `!=`, `+`, `-`, `/`, `*`

## Example

```
Task evaluate_data {
    # Basic math and assignment
    confidence = confidence * 0.95;

    # Conditional checks
    IF error_rate > 5.0 {
        # Inter-agent public mutation
        Public.status = "failure";
    } ELSE {
        # Invoking an internal Func block or library
        Public.status = format_success_msg(confidence);
    }
}
```

## Characteristics

- **Strict Logic Constraint:** By restricting exactly what a Task can do, ORCH keeps state mutations clearly defined without getting bogged down in boilerplate API calls or complex logic nested at the wrong layer.
- **Delegation:** When a Task finds something too complex to calculate mathematically, it pushes that calculation to a `Func` block using `CALL`.

===== docs/index.md =====
# DSL USER GUIDE

# ORCH Agent Graph Orchestration Language

ORCH is a domain-specific language for building and orchestrating systems made up of multiple intelligent agents. You write agents, give them tasks and memory, and use a central Route block to control which agent runs when.

Programs in ORCH are structured as a **graph of agents**. Each agent is an independent unit with its own private state and task logic. A single orchestrator file ties them all together, defining which agents exist and how execution flows between them.

---

## Features of the ORCH System

ORCH is not just another agent-chaining framework; it is a purpose-built Domain-Specific Language integrated closely with a Python execution engine (`orch-lib`). The combination of this domain-specific grammar and robust routing runtime yields several standout features:

### 1. Centrally Controlled Execution Automation

Unlike implicit state-machine or message-bus setups where agents call each other, ORCH centralizes the orchestrator flow.
- At the **Graph** level, the `Route` block decides which node/agent operates.
- At the **Agent** level, the `Route` block restricts agent scope to simple execution of Tasks.
- **Result:** You can view a project and immediately trace its state evolution and path without reading deeply into execution details.

### 2. Distributed Compilation

The ORCH execution flow introduces a compiler pipeline composed of two layers:
- **Fast OCaml Build:** A statically typed `main.exe` executable guarantees the stability and structural soundness of the written DSL. It parses AST structures at high speed.
- **Generative Automation:** Instead of running the DSL line-by-line via interpreter, the architecture transpiles the tree into native Python bindings (via `converter.py`), resulting in highly integrated and performant executable code.

### 3. Sandboxed Python Escapes (`Func` blocks)

You are not constrained to an obscure declarative language’s limits. The `Func` block directly surfaces **unrestricted, native Python**.
If your agent needs to perform an API call or run a Machine Learning model, the logic lives securely inside a `Func {}`.

### 4. Simplified Memory Scoping

You do not need to deal with event queues to get memory working between agents.
- Need graph-wide visibility? Prefix with `Public`.
- Need isolated safety? Prefix with `Private`.
`orch-lib` translates this behind the scenes directly into structured contexts for every single agent and task.

### 5. Parallel/Multi-Agent Cloning Support

Through the simple array syntax `Include AgentB{5}`, ORCH will silently duplicate, register, and provision 5 totally disjoint instances of `AgentB`, handling all the memory initialization.

### 6. Built-in Math and Expression Evaluation Sub-language

ORCH’s `Task` body behaves identically to basic `Python` expression assignments with complete support for conditional checks (`IF / ELSE`), logic bindings (`AND`, `OR`), and math operations (`+`, `-`, `/`, `*`), without needing the verbosity of a full language.

---

[Usage and Structure](Usage and Structure.md)

[ORCH FILES](ORCH FILES.md)

[AEON FILE](AEON FILE.md)

[LIB FILE](LIB FILE.md)

[Routing](Routing.md)

===== docs/LIB FILE.md =====
# LIB FILE

Owner: Durga Sai

A `.lib` file is used to define reusable functions that can be used inside agent files.

It helps you:

- avoid repeating logic
- write complex operations in Python
- reuse functions across multiple agents

---

### Example (math.lib)

```
Func add {
    result = a + b
    return result;
}

Func multiply {
    result = a * b
    return result;
}
```

---

### Explanation

- `Func` → defines a function
- Inside the block → you can write Python code
- `return` → specifies the output of the function

---

### Using Library Functions in Agents

First, include the library in your agent file:

```
Include math
```

Then call the function inside a task:

```
Task compute {
    result = add(a, b)
}
```

---

### Key Points

- `.lib` files only contain functions
- Functions use Python syntax
- Must end with `return <variable>;`
- Can be reused across multiple agents

---

[Functions](LIB FILE/Functions.md)

===== docs/LIB FILE/Functions.md =====
# Functions

Owner: Durga Sai
Verification: Verified
Tags: aeon

# Funcs

While ORCH utilizes a custom syntactical sub-language for mathematical assignments inside `Task` blocks, Multi-Agent systems routinely require calling APIs, performing heavy machine learning inference, interacting with databases, or parsing complex text.

The `Func` block is the ultimate escape hatch: **The body of a Func block is unrestricted Python.**

## Defining a Func

A `Func` lets you write standard Python precisely where you need computational payload without cluttering the declarative nature of the agent’s routing structure.

The only rule is that a `Func` must conclude by returning a variable to pass back to the DSL environment.

### Syntax Example

```
Func validate_database {
    # Pure python is accepted here natively
    import sqlite3
    import pandas as pd

    # You can access agent memory natively by reading the mapped objects
    threshold = Private.error_threshold

    try:
        conn = sqlite3.connect('local.db')
        data = pd.read_sql("SELECT * FROM metrics", conn)
        conn.close()

        if len(data) > threshold:
            result_code = 1
        else:
            result_code = 0
    except Exception as e:
        result_code = -1

    # The block must export a returned variable to hand back to the task
    return result_code;
}
```

## How to use a Func

You invoke a `Func` from within a `Task` block utilizing the `CALL` operator.

```
Task handle_db {
    # Calling the Python escape hatch logic
    db_status = validate_database();

    IF db_status == 1 {
        alert_flag = true;
    }
}
```

## Why it works this way

By isolating Python inside `Func` blocks and isolating Mathematics/State inside `Task` blocks, the system inherently forces developers to separate execution heavy-lifting from standard agent orchestration logic. It combines the readability of a DSL with the limitless ecosystem of the Python language.

===== docs/ORCH FILES.md =====
# ORCH FILES

Owner: Durga Sai
Verification: Verified
Tags: orch

An `.orch` file is used to define a workflow using your DSL.

It describes a sequence of tasks, what each task does, and how they are connected.

You can think of it as a script that controls how different steps are executed.

---

## ORCH File Structure

An ORCH file follows a fixed structure:

---

### 1. Include Section

We first include all required files.

- Agent files are included using `Include AgentName`
- Multiple instances can be created using `{n}`

```
Include IntersectionAgent {4}
Include ReportAgent
```

This is where we load all agents that will be used in the system.

[Orch Includes](ORCH FILES/Orch Includes.md)

---

### 2. Global Variables

After including agents, we define global variables.

- These variables control the execution flow
- Example: `trafficStage`, `responseMode`

```
int trafficStage = 0
int responseMode = 0
```

They are mainly used inside the Route block for decision making.

---

### 3. Route Block

The Route block defines the execution logic.

- It decides which agent runs based on conditions
- Each rule follows: `condition : Agent {instance}`
- Conditions are checked from top to bottom

#### on_start and on_end

- `on_start : Agent` → runs once at the beginning of execution
- `on_end : Agent` → runs once at the end of execution

They are special rules inside the `Route` block used to:

- initialize the system (`on_start`)
- perform final tasks like reporting or cleanup (`on_end`)

This is the core part of the ORCH file where the entire system flow is controlled.

```
Route {
		on_start : SetupAgent
    trafficStage == 0 : IntersectionAgent {1}
    trafficStage == 1 : ZoneAgent {1}
    trafficStage == 1 : ZoneAgent {2}
    trafficStage == 2 AND responseMode == 2 : EmergencyAgent {1}
    on_end : LogAgent
}
```

---

[ORCH MEMORY](ORCH FILES/ORCH MEMORY.md)

===== docs/ORCH FILES/Orch Includes.md =====
# Orch Includes

Owner: Durga Sai
Verification: Verified
Tags: orch

# Feature Deep-Dive: Orchfile Includes (`.orch`)

In the Global Dispatcher context (`.orch` files), the `Include` keyword is structurally responsible for **instantiating agents into the execution graph**.

You use `Include` in an `.orch` file to bind `.aeon` agent definitions to the project runtime. If an agent is not explicitly included via an `Include` statement, it will not be created or executed, even if its definition file exists in the directory.

## Basic Includes

To pull a single instance of an agent into the runtime graph, use the keyword followed by the agent name.

```
# Include a single instance of an agent
# Assuming 'DataCollector.aeon' exists in the folder
Include DataCollector
```

Once included, the `DataCollector` can be targeted by the Global `Route` block.

## Instantiating Parallel Agent Clones

A uniquely powerful feature of the ORCH engine is its ability to instantly clone agent configurations to create multiple parallel processors.
You can spin up `N` identical agents that share the same `.aeon` instructions but maintain their own completely isolated memory scopes.

You do this by adding bracketed instantiation sizes `{N}`.

```
# Automatically create 5 separate instances of ProcessingAgent
Include ProcessingAgent{5}
```

*Behind the scenes, `orch-lib` handles provisioning 5 parallel instances and registering them dynamically.*

# Environment Variables (`.env`)

The ORCH compiler contains a natively integrated pipeline specifically to load environmental secrets safely directly into the running graph.

```python
# Automatically load all variables from `.env` directly into Global Graph Memory
Include env
```

[Environment (.env)](Orch Includes/Environment ( env).md)

===== docs/ORCH FILES/Orch Includes/Environment ( env).md =====
# Environment (.env)

Owner: Durga Sai
Verification: Verified
Tags: orch

## Sourcing Environment Variables

By declaring the specific reserved phrase `Include env` in your global orchestrator (`.orch`), the transpiler hooks directly to the backend to automatically load and parse a `.env` file from the runtime directory.

```
# Automatically load all variables from `.env` directly into Global Graph Memory
Include env
```

All key-value pairs established in the `.env` file are seamlessly unpacked and bundled into the overarching **Graph Memory** layer as explicitly public variables.

## 1. Example `.env` File

```
API_KEY=YOUR_SECRET_KEY
DB_HOST=localhost
```

## 2. Accessing From Inside an Agent (`Task` block)

Because the environment pairs map entirely into the graph’s public memory structure, any initialized agent can freely read those variables in their `Task` blocks by specifically reaching into the global scope using the `Public` accessor.

```
Task check_connection {
    # Natively fetches the variable loaded from the .env into Graph Memory
    current_key = Public.API_KEY;
}
```

## 3. Accessing From Python (`Func` block)

Because the ORCH compilation engine utilizes standard `dotenv` libraries under the hood during the script’s execution phase, `.env` variables are completely simultaneously injected straight into the operating system shell environment.

This means any pure Python script running within an agent’s `Func` escape hatch can use standard Python `os` modules to fetch them natively, completely sidestepping standard Graph Memory:

```
Func check_native_env {
    import os
    # Fetch natively from the underlying OS environment
    python_key = os.environ.get("API_KEY")
    return python_key;
}
```

===== docs/ORCH FILES/ORCH MEMORY.md =====
# ORCH MEMORY

Owner: Durga Sai
Verification: Verified
Tags: orch

# Feature Deep-Dive: Global Memory (`.orch`)

Memory handling inside the Global Dispatcher (`.orch` file) establishes overarching state that is inherently **public** to the entire project.

The available variable types in ORCH are: `int`, `float`, `char`, `string`, `list`, `tuple`.

## How to Define Global Memory

Global memory is defined freely at the top level of the `.orch` file (they are not enclosed within any `Private` or functional block). You simply declare a type and a variable name.

```
Include ProcessingAgent

# Defining global memory
int totalRounds = 10
string currentMode = "competitive"
```

## How to Use Global Memory in `.orch` Files

Within the `.orch` file itself, these variables are primarily used to direct the Global `Route` block. They act as the state conditions determining which Agent gets to run next.

```
Route {
   # Using global variables natively without prefixes in the orchestrator
   totalRounds > 0 : ProcessingAgent
}
```

## How to Use Global Memory in `.aeon` Files

Because any variable defined in the `.orch` file is implicitly placed into the **Graph/Global Memory**, they are universally accessible to all `.aeon` agents connected to the graph.

Inside any agent’s `Task` blocks, you can securely access these variables by using the `Public` accessor prefix.

```
Task evaluate_mode {
    # Accessing 'currentMode' globally defined in the .orch file
    IF Public.currentMode == "competitive" {
        # Perform action
        Public.totalRounds = Public.totalRounds - 1
    }
}
```

Global memory variables act as the system-wide static glue binding agent logic. They track the overarching progress, whereas agent-specific logic states belong strictly nested within the agents themselves.

===== docs/Routing.md =====
# Routing

Owner: Durga Sai
Verification: Verified
Tags: Design

# Feature Deep-Dive: Routing

The `Route` block represents the central authority of any ORCH project. In ORCH, agents and tasks **never** trigger each other directly. Instead, all transitions and control flows are centralized inside `Route` blocks.

`Route` blocks are evaluated top-down. The first condition that evaluates to `true` is chosen to execute next.

There are exactly two variations of the `Route` block: **Global Routing** and **Agent Routing**.

---

## 1. Global Routing (in `.orch`)

Located in the Global Dispatcher, this route block decides *which Agent* gets to run.

### Reserved Keywords

- `on_start`: (Optional) Triggered exactly once when the program officially begins.
- `on_end`: (Optional) Triggered when the graph concludes.

### Example

```
int errors = 0

Route {
    # The first condition to match will trigger the corresponding Agent
    errors > 5 : AlertAgent          # Triggers AlertAgent if critical error
    on_start : InitAgent             # Always kicks off here first
}
```

---

## 2. Routing to Specific Clones (`{i}`)

When dealing with an array of cloned agents initialized in your global orchestrator (e.g., `Include WorkerAgent{3}`), you can explicitly route to a specific instance of that agent class by using the zero-indexed `{i}` syntax.

```
# Correct targeted deterministic routing for clones
Route {
    condition_A : WorkerAgent{0}    # Triggers the first clone explicitly
    condition_B : WorkerAgent{1}    # Triggers the second clone explicitly
}
```

### Warning: Non-Deterministic Execution Order

A critical detail when designing routes is ensuring conditions are mutually exclusive if exact execution order matters.

If you map the **exact same trigger condition** to multiple different targets inside the exact same `Route` block (or if you map a condition to an unindexed class of initialized clones), the ORCH compiler does not guarantee which one will execute first. Order will be highly variable and non-deterministic on every run.

**Avoid duplicate triggers** unless the sequence of execution does not matter to your logic.

---

## 3. Agent Routing (in `.aeon`)

Located inside every Agent Definition, this route block decides *which internal Task* is executed when the global route gives control to the Agent.

### Example

```
Route {
    health < 30 : heal       # If low health, agent focuses on healing
    on_start : fight         # Otherwise, agent defaults to fighting
}
```

===== docs/Usage and Structure.md =====
# Usage and Structure

Owner: Durga Sai
Verification: Verified
Tags: Usage

# ORCH DSL: Usage and Project Structure

The ORCH DSL provides a distributed compilation pipeline. The front-end compiler, `main.exe` (written in OCaml), parses your ORCH project, generates a JSON representation (AST), and then invokes a Python script (`converter.py`) to transpile the project into a runnable Python application leveraging `orch-lib`.

## Usage

You can run the compiler using the following syntax:

```bash
./main.exe [--dryrun] [--verbose] [--no-delete] <project_directory>
```

### Options

- `<project_directory>` : **(Required)** Specifies the path to the directory containing your project.
- `-dryrun` : **(Optional)** Generates the Python file without executing it.
- `-verbose` : **(Optional)** Enables verbose logging.
- `-no-delete` : **(Optional)** Prevents automatic cleanup of the generated `.json` and `.py` files.

### Internal Workflow

1. **Parsing:** `main.exe` reads the project in `<project_directory>`.
2. **JSON Generation:** Constructs an AST and outputs it as JSON.
3. **Transpilation:** Converts the JSON file to a Python execution file (`<project_name>.py`).
4. **Execution:** Automatically runs the Python file.
5. **Cleanup:** Deletes intermediate generated `.json` and `.py` files.

---

## Project Structure

Your project should exist within a single directory. The ORCH DSL is designed to cleanly separate global orchestration logic from agent-specific task logic.

### Directory Components

Your directory can contain the following:
- **The Global Dispatcher (`.orch` files):** The main entry point for the entire project.
- **Agent Definitions (`.aeon` files):** The individual files or blocks implementing your specific agents.
- **`*.lib`:** (Optional) Sub-library files containing shared functions.
- **`*.py`:** (Optional) External Python scripts for direct absolute imports. Note: relative imports are NOT accepted.

### The Global Dispatcher (`.orch` files)

The orchestrator handles overall global routing logic and configures which agents exist. Core blocks that can be there:
- **Includes:** Defines the agents to be pulled in.
- **Global Variables:** Top-level state accessible across the entire structure.
- **Global Route:** Central authority deciding which agent runs next.

### The Agent Definition (`.aeon` files)

An agent defines its own memory, executable actions, internal routing logic, and python bindings. Component blocks that can be there:
- **`Private`:** Defines the agent memory and internal state variables (both private scope and public scope).
- **`Task`:** Defines executable actions intended to mutate state.
- **`Func`:** Defines custom inline native Python extensions for complex capability.
- **`Route`:** Defines the internal, agent-specific routing rules dictating which task executes.

### The Library Definition (`.lib` files)

A Library file is just a list of functions in a file that needed to be imported in `.aeon` files