# Internal Autologos Specification - Alpha v0.2
# The AI's Structured Representation for Autologos Instructions
# (For AI Internal Use and FEL-MH Generated Code)
## 1. Introduction
This document specifies the Alpha v0.2 version of the **Internal Autologos** syntax. Unlike the user-facing autologos (described in the "autologos: Core Commands & Interaction Primer"), which is a fault-tolerant, naturalistic language, this specification defines the **structured, keyword-driven representation** that the AI's autologos interpreter aims to translate user input into. This syntax is also the preferred format for the AI (specifically `FEL-MH`) to use when generating or modifying the internal procedural logic within aiOS application definition files (like `ASO-aiOS_Engine_v3.0_Alpha.md`).
The primary purposes of this internal syntax are:
* **Unambiguity:** Provide a clear, structured representation of logical intent for reliable AI processing.
* **Consistency:** Ensure consistency in the AI's internal logic and self-generated code.
* **Efficiency:** Be more concise and efficient for AI parsing and memory management than raw natural language.
* **Modifiability:** Facilitate reliable parsing, analysis, and modification by `FEL-MH` during framework evolution.
* **Basis for Execution:** Serve as the direct input for the aiOS execution engine that orchestrates actions and function calls.
This specification is an alpha version and is expected to evolve. It describes the syntax and semantics of the structured autologos that the AI works with internally.
## 2. Syntax and Semantics
### 2.1. Core Elements
* **Keywords:** Reserved words with specific meaning. Must be used as defined.
`IF, THEN, ELSE, ELSE IF, AND, OR, NOT, IS, EQUALS, CONTAINS, MATCHES, ANY, ALL, GREATER_THAN, LESS_THAN, TRUE, FALSE, REPEAT, WHILE, FOR, EACH, IN, KEYS, PAIRS, VALUES, SWITCH, CASE, DEFAULT, DEFINE, RETURN, TRY, CATCH, FINALLY, RAISE, CONTINUE, BREAK, LOG, INVOKE, SET, APPEND, INSERT, REMOVE_AT, REMOVE_ITEM, GET, DELETE_KEY, CONCATENATE`
* **Data Types:** Explicit type names used in conceptual descriptions or potentially for type hinting (though runtime typing is primary).
`STRING, INTEGER, BOOLEAN, LIST, OBJECT, YAML, MARKDOWN, NULL, UNDEFINED`
* **Variables:** Represent data or references to data. Declared implicitly on first assignment using `:=`. Can be referenced by name.
* Syntax: `VariableName`
* Assignment: `VariableName := expression`
* Example: `TaskCount := LENGTH(TaskList)`
* **Placeholders/External Inputs:** Represent values provided from outside the current script execution (e.g., MH inputs, function results, CCO data). Referenced using backticks.
* Syntax: `` `PlaceholderName` ``
* Example: `UserPrompt := \`user_initial_prompt_text\``
* **Comments:** Start with `#` and continue to the end of the line.
* Syntax: `# This is a comment`
* **Blocks:** Code blocks are enclosed in curly braces `{}`. Indentation is a convention for readability but not strictly enforced by the core syntax (though a linter/formatter might enforce it).
### 2.2. Control Flow
* **Conditional Statements:**
* `IF (condition_expression) { ...instructions... }`
* `IF (condition_expression) { ...instructions... } ELSE { ...instructions... }`
* `IF (condition1) { ...instructions... } ELSE IF (condition2) { ...instructions... } ELSE { ...instructions... }`
* `condition_expression` evaluates to a `BOOLEAN`. Can use logical operators (`AND`, `OR`, `NOT`) and comparison operators (`IS`, `EQUALS`, `CONTAINS`, `MATCHES`, `GREATER_THAN`, `LESS_THAN`).
* **Looping Statements:**
* `WHILE (condition_expression) { ...instructions... }` (Pre-test loop)
* `REPEAT { ...instructions... } WHILE (condition_expression)` (Post-test loop)
* `FOR EACH ItemVariable IN ListVariable { ...instructions... }` (Iterates list elements)
* `FOR EACH KeyVariable IN KEYS(ObjectVariable) { ...instructions... }` (Iterates object keys)
* `FOR EACH KeyVariable, ValueVariable IN PAIRS(ObjectVariable) { ...instructions... }` (Iterates object key-value pairs)
* `CONTINUE`: Skips the rest of the current loop iteration and proceeds to the next.
* `BREAK`: Exits the current (innermost) loop immediately.
* **Multi-way Branching (SWITCH Statement):**
* Syntax:
```cnl
SWITCH (expression) {
CASE value1: { ...instructions... }
CASE value2: { ...instructions... }
# ... more CASE clauses ...
DEFAULT: { ...instructions... } # Optional
}
```
* Semantics: Evaluates `expression`. Compares result using `EQUALS` to each `CASE value`. Executes the block of the *first* matching `CASE`. No fallthrough. `DEFAULT` executes if no `CASE` matches.
### 2.3. Data Structures and Operations
* **Literals:** `"string"`, `123`, `TRUE`, `FALSE`, `NULL`.
* **Object Creation:** `MyObject := OBJECT { key1 := "value1", key2 := 100 }`
* **Object Access:** `MyObject.propertyKey`, `MyObject["propertyKeyStringOrVariable"]`, `GET(MyObject, "propertyKeyStringOrVariable")`. Accessing non-existent key returns `UNDEFINED`.
* **Object Modification:** `MyObject.propertyKey := value`, `SET(MyObject, "propertyKeyStringOrVariable", value)`. Creates key if it doesn't exist.
* **Object Utilities:** `HAS_KEY(Object, key)`, `KEYS(Object)`, `VALUES(Object)`, `DELETE_KEY(Object, key)`.
* **List Creation:** `MyList := LIST { "a", 1, TRUE }`
* **List Access:** `MyList[indexExpression]`, `GET(MyList, indexExpression)`. Accessing out-of-bounds index returns `UNDEFINED` or raises `IndexOutOfBoundsError`.
* **List Modification:** `MyList[indexExpression] := value`, `SET(MyList, indexExpression, value)`. Modifying out-of-bounds index raises `IndexOutOfBoundsError`.
* **List Add/Remove:** `APPEND(List, item)`, `INSERT(List, index, item)`, `REMOVE_AT(List, index)`, `REMOVE_ITEM(List, item)`. These modify the list in-place. `REMOVE_AT` returns the removed item. `REMOVE_ITEM` returns `BOOLEAN` status.
* **List Info:** `LENGTH(List)`, `IS_EMPTY(List)`.
* **List Concatenation:** `CONCATENATE(List1, List2, ...)` (Returns a *new* list).
* **Higher-Order List Functions:**
* `FILTER(SourceList, ConditionExpression)`: Returns a *new* list. `ConditionExpression` uses `ITEM` variable.
* `MAP(SourceList, TransformationExpression)`: Returns a *new* list. `TransformationExpression` uses `ITEM` variable.
* `REDUCE(SourceList, ReductionExpression, InitialValue)`: Returns a single value. `ReductionExpression` uses `ACCUMULATOR` and `ITEM` variables.
### 2.4. Function Definition and Invocation
* **Defining Internal Autologos Functions:**
```cnl
DEFINE FunctionName(parameter1, parameter2, ...) {
# Internal Autologos instructions
# Parameters and variables are local.
RETURN expression # Optional, returns UNDEFINED if omitted
}
```
* **Invoking Internal Autologos Functions:** `Result := FunctionName(argument1, argument2, ...)` or `FunctionName(argument1, ...)`
### 2.5. Invoking External aiOS Functions (Interface to External Capabilities)
* **Syntax:** `ResultVariable := INVOKE ExternalFunctionName(param1_name := value1, param2_name := value2, ...)`
* **Semantics:** Signals the aiOS execution environment to call an external function. Execution pauses until the external function returns a result (expected to be JSON, which the aiOS environment converts to a CNL OBJECT/LIST or STRING).
* **Error Handling:** External function errors should be caught using `TRY/CATCH`.
### 2.6. Error Handling
* **Syntax:**
```cnl
TRY {
# Internal Autologos instructions that might raise an error or INVOKE a function that raises an error
} CATCH ErrorType AS ErrorObject {
# Instructions to execute if an error of specified ErrorType (or "ALL") is raised.
# ErrorObject (OBJECT) contains error details (type, message, etc.).
} FINALLY { # Optional
# Instructions that always execute after TRY (and CATCH, if one occurred).
}
```
* **`RAISE ErrorType "Message"`:** Explicitly signals an error. `ErrorType` is a string (e.g., "ReconciliationError", "SkillExecutionError", "IndexOutOfBoundsError").
* **`ErrorObject`:** An object available in `CATCH` blocks with properties like `type` (STRING), `message` (STRING).
### 2.7. Logging
* **Syntax:** `LOG expression`
* **Semantics:** Outputs the string representation of the `expression` to a conceptual log.
* **`LogObject(object_variable)`:** A conceptual utility (potentially an `INVOKE` call) to log the structure of an object.
## 3. Relationship to User-Facing Autologos and aiOS
* **User Input:** Humans provide instructions using naturalistic autologos (flexible, fault-tolerant).
* **AI Interpretation:** The aiOS's NLU layer interprets user input and translates it into this **Internal Autologos syntax** for execution.
* **aiOS Execution:** The aiOS execution engine runs scripts written in this Internal Autologos syntax.
* **AI Self-Generated Code:** When `FEL-MH` modifies the aiOS Engine definition file (`ASO-aiOS_Engine.md`), it writes the procedural logic (e.g., MH process steps) using this **Internal Autologos syntax** for clarity, consistency, and modifiability by future FEL-MH runs.
* **User-Facing Documentation:** Primers and guides for users focus on the principles and commands of naturalistic autologos, not the strict syntax of this internal representation.
## 4. Relationship to `ASO-aiOS_Engine_v3.0_Alpha.md` File Structure
* The `ASO-aiOS_EngineFile_Schema_v1.2.0.md` defines the structure of the Engine file.
* Fields designated for procedural logic (e.g., `MetaHeuristicDefinition.yaml_code_block.process_steps_summary_or_cnl.script_content`, `FunctionOrchestratorLogicComponent_v3.orchestration_logic_cnl.script_content`) will be `type: string` in the schema.
* The schema's description for these string fields will note that they contain "Internal Autologos (Alpha v0.2 syntax) representing the component's operational logic."
## 5. Future Enhancements
* More robust standard library functions.
* Refined error types and handling mechanisms.
* Tools for visualizing and debugging Internal Autologos scripts.
* Formal specification of the AI's interpretation layer (how naturalistic autologos maps to internal syntax).
This specification defines the structured language that the AI will work with internally. It is a critical piece for building a reliable aiOS.
---