# Simorg Reference Book (genesis-0-1-0)

> Auto-generated merge of all reference-book chapters. Generated at 2026-07-30T10:41:21.475Z.

## Table of contents

- [Introduction](#introduction)
- [Simorg In 10 Minutes](#simorg-in-10-minutes)
- [Variables](#variables)
- [Gates](#gates)
- [Eventflow](#eventflow)
- [Wrappers](#wrappers)
- [Artifacts](#artifacts)
- [Logos](#logos)

---

<!-- source: reference-book/introduction.md -->

## What is Simorg? 

Simorg is a Programming Language as a Platform — a lightweight, high-level scripting language built for the next generation of AI-native applications, not as a generic replacement for classical languages.

Its core model is event-driven: everything exists as an Event that flows through the system; Data leads processing instead of being passively operated on by separate logic.

Code is interpreted into mathematical entities in a runtime engine; execution routes events through Shells, scoped spaces that wrap events and shape how data flows.

Simorg deliberately omits familiar constructs from classical languages (null/undefined, garbage collection, traditional functions/arrays); low-level capabilities are supplied via artifacts from Logos, our pacakge manager.

In short: you write code to create shells and pathways through which events flow.

$$$AlertBox type=WARNING title=Not Production Ready Yet message=Please keep in mind, Simorg is currently in PoC mode! So avoid using existing tools and technology in production environment and wait for the first official LTS version. $$$

---

<!-- source: reference-book/simorg-in-10-minutes.md -->

This is a quick start section, focusing on core functionalities of simorg.
You need to setup your local environment before starting this quick tour. You can follow the instructions in 
$$$ToPageLinker keyword=Getting Started toRoute=/docs/getting-started/introduction$$$ section.


We are going to discover simorg using a simple guessing game. Our application receives user's input from terminal and checks it against a target number. Guessing right leads to a success message, otherwise user needs to enter a new number.

Create a new file and call it <<<guessing-game.art>>>, we will add our simorg code inside this file.

Let's start from the core functionalities by creating two variables.

Using <<<$>>> before an identifier, marks that identifier as variable.

```
$TARGET
$guess
```

Using capital letters we mark <<<TARGET>>> as being a const variable that is being set only once during the lifecycle of our app. Let's give it a default value by replacing line 1 by,

```
3 $TARGET
$guess
```

Simorg doesn't have classical assignment operator <<<=>>> instead it uses eventflows. As soon as our application starts value 3 is vibrated and starts an eventflow. When value reaches <<<TARGET>>> it again vibrates but this time using a new identity. An event simply is marking the availability of data in a specific moment in time.

We can keep adding operators in our eventflow pipeline. Let's add a logger operator so we can see the value in terminal,

```
3 $TARGET ?
$guess
```

By running our app,
"""
sim -f guessing-game.art
"""
3
!!!!

Cool! Let's now add a basic condition and test it. 

```
3 $TARGET ?
$guess

guess = TARGET  "Congratulations! You successfully guess the number!" ?
```
Simorg doesn't have any reserved keywords! So no more <<<if>>>, <<<else>>>, <<<while>>>, etc..!

Line 4 is again an eventflow pipeline which starts by the variable <<<guess>>>. if the value is equal to <<<TARGET>>> then it passes the event forward. In this case the incoming event will trigger our string value literal and cause it to vibrate. The incoming value is not used anymore. It will cause this value literal to pass it's value to logger operator.



Let's give the same value to <<<guess>>> and test our application,
```
3 $TARGET ?
3 $guess

guess = TARGET  "Congratulations! You successfully guess the number!" ?
```

By running our app,
"""
sim -f guessing-game.art
"""
Congratulations! You successfully guess the number!
!!!!


Let's add more conditions to cover other cases,
```
3 $TARGET ?
3 $guess

guess = TARGET  "Congratulations! You successfully guess the number!" ?
guess > TARGET  "Target is smaller than your guess" ?
guess < TARGET  "Target is bigger than your guess" ?
```

Now we have the core functionality of our app. Let's complete it by importing two blueprints. Simorg like any modern programming language has its own package manager called 
$$$ToPageLinker keyword=Logos toRoute=https://logos.simorg.art$$$.

Let's use a random number generator. Using <<<#>>> before an identifier will help us instantiate our blueprint and have an identifier to call it,
```
"@stl/random0.1.7" #random

9 random.integer $TARGET ?
3 $guess

guess = TARGET  "Congratulations! You successfully guess the number!" ?
guess > TARGET  "Target is smaller than your guess" ?
guess < TARGET  "Target is bigger than your guess" ?
```

By pushing <<<9>>> into <<<random.integer>>>, we will create a random number between <<<0>>> and <<<9>>>, inclusive. Then this value will be set as our target.

Next blueprint is <<<terminal-input>>>. It will help us read a value from terminal,

```
"@stl/random0.1.7" #random
"@stl/terminal-input0.1.6" #terminal

9 random.integer $TARGET ?
"Enter Your Guess: " terminal.promptAndReadLine $guess

guess = TARGET  "Congratulations! You successfully guess the number!" ?
guess > TARGET  "Target is smaller than your guess" ?
guess < TARGET  "Target is bigger than your guess" ?

```

Our application is almost complete. Line 5 will prompt and read a value from terminal. This will then vibrate guess. 

As you noticed Simorg doesn't use any type definitions. Engine tries to convert types automatically. In case of failure a log message will be logged by engine. Simorg doesn't throw any exception at runtime. If something fails, the expected event will not happen.

Finally, let's re-arrange a few things to fulfill the requirement of our application and keep asking the user when the guess is not right, 

```
"@stl/random0.1.7" #random
"@stl/terminal-input0.1.6" #terminal

:terminal.promptAndReadLine $guess 

9 random.integer $TARGET "Enter your guess: " guess

guess = TARGET "Congratulations! You guessed right!" ?
guess > TARGET "Target is smaller, Guess again: " guess
guess < TARGET "Target is bigger, Guess again: " guess
```

Line 4, is using an open pipe and helps us re-vibrate this pipeline when we need to receive a new guess.
We use the natural logger capability of <<<promptAndReadLine>>> to ask user for new inputs.

On lines 9 and 10, when user needs to guess again, the event is re-directed back into <<<guess>>>. The act of prompting and asking user to enter a number is now part of the declation of <<<guess>>> so whenever something is pushed into <<<guess>>> have to pass through all these pre-processors.

Awesome! Now you have a basic understanding about core aspects of Simorg. The event-driven nature of the language is helping us create a new declarative form of solutions.
Also, every single token that we use is referring to an equivalent data entity, in other words we are writing code from data's point of view not from a third-party observer's point of view. This is contributing to the simplicity of the language as we don't need extra unnecessary tokens. This is how Simorg achieves a solution using zero reserved keywords.


To gain a deeper knowledge about simorg, please continue reading our reference book. Happy Coding!

---

<!-- source: reference-book/01-Variables.md -->

Variables are **event markers**, not memory owners.
They only become active when **event** reaches them. variables are fixed parts of your program's structure.

Use <<<$>>> before an identifier to make it a variable, 

```
"Hello World!" $myFirstVar
myFirstVar ?
```
In the above example the value literal <<<Hello World!>>> is representing our initializer event and it is triggered as soon as our application starts. Events always flow left to right.

### Value Literals

Simorg's runtime infers the type and runtime doesn't need any type definition. 

| Form | Example | Meaning |
|------|---------|---------|
| Buffer | <<<0x01>>> | raw bytes (hex) |
| Number | <<<10>>> | integer or decimal |
| String | <<<"Hello">>> | text |

Empty Values are valid Events — they represent emptiness, not null or void,

```
0      // empty number
0.0    // empty decimal
0x     // empty buffer
""     // empty string
```
Emptiness can be checked using <<<Truthy Operator &>>>. It will be discussed later under <<<Event Flow>>> section.

Simorg doesn't have any concept related to nullity e.g. <<<undefined>>>, <<<null>>>, <<<nil>>>, <<<Option>>>, <<<Maybe>>> and others.

Escape sequences including, <<<\n>>> (newline), <<<\r>>> (carriage return), <<<\t>>> (tab) are supported inside String values.

It's also possible to insert a value into a string using <<<{}>>> placeholder

```
100 "number {} is now embedded" ?
```

Using <<<\>>> before <<<{}>>> will disable this behavior.

---

<!-- source: reference-book/02-Gates.md -->

When a single variable is not enough, **Gates** combine multiple events into a more complex structure or logic.

A **Gate** is a Shell type that acts as an event aggregator — it collects events from multiple slots and releases them according to a condition. After a Gate releases, it is cleared.

Simorg provides two Gate types, each with its own syntax and behavior:

| Gate | Syntax | Releases when |
|------|--------|---------------|
| OR | <<<[ ]>>> | at least one slot has an event |
| AND | <<<( )>>> | every slot has an event |

### OR

Use <<<[ ]>>> to define an OR gate. It releases when **at least one** slot receives an event.

```
[1,2,3] ? // [1,2,3]
```

Three value literals fire at startup; the OR gate receives them and releases because at least one slot is active. The logger prints the result in gate form.

The engine aggregates events when possible — all three values appear together in one release.

Empty values (<<<0>>>, <<<"">>>, <<<0x>>>, <<<0.0>>>) are valid events. Gates respond to **event presence**, not truthy/falsy checks. Guards for empty values are covered later in the Event Flow chapter.

### XOR

Same bracket syntax, but separate slots with <<<;>>> instead of <<<,>>> to get **sequential** release — one event per processing cycle.

```
[1;2;3] ? // 1
          // 2
          // 3
```

Unlike OR, XOR does not batch: each slot releases one at a time. This makes XOR useful when events must flow in sequence.

Simorg is fully async — events decide what goes next, not line order.

### AND

Use <<<( )>>> to define an AND gate. It releases only when **all** slots have an event.

```
100 $var1
"hello" $var2
0.0 $var3

(var1, var2, var3) $myAndGate
myAndGate ? // (100, hello, 0.0)
```

If any slot is missing an event, the gate does not release:

```
100 $var1
"hello" $var2
$var3

(var1, var2, var3) $myAndGate
myAndGate ? // nothing logged
```

Use <<<,>>> to separate slots in an AND gate. <<<;>>> has no effect here.

### Key Takeaways

Gates behave like logical gates in software and electronics. What matters is whether a slot has an event, not whether its value is <<<truthy>>>. Values like <<<"">>>, <<<0>>>, and <<<0x00>>> are valid events.

Beyond holding data, an AND gate binds the slots together:

```
"Jacob" $name
21 $age
"Istanbul" $city

(name, age, city) $userInformation
```

Whenever <<<userInformation>>> releases, <<<name>>>, <<<age>>>, and <<<city>>> are guaranteed to be present together.

### Scope

variables declared inside a gate belong to that gate's scope. Access named slots with the <<<.>>> operator:

```
(
  "HELLO" $hello,
  "BYE" $bye
) $message

message.hello ? // HELLO
```

Gates blend object and array behavior: named slots are accessed like object fields; reading the gate as a whole treats it like a collection. More on this in the Wrapper Shells chapter.

---

<!-- source: reference-book/03-Eventflow.md -->

Eventflow operators are the glue between Shells. They create **pathways** in which events stream from left to right, forming an **Eventflow pipe**.

A pipe shapes when operators chain together. A pipe does not release events outside itself unless you explicitly route them out using variables.

These operators are quite intoivite and easy to remember.

## Opener
Use <<<:>>> to make an event flow dependent to future events.

When a pipe doesn't have a head operator, it is called **Closed**. the leading value self-triggers at startup:

```
200 $myConst200
```

Use <<<:>>> as head operator to open up the pipe to future events. Open pipe is dependent to an exteranal event:

```
:200 $myConst200 ? // nothing logged
```

Push data into another pipe through a variable:

```
// passing event into myConst200 and receiving event back
100 myConst200 ? 
```

Combine both behaviors with a gate, auto-init at startup and accept events later:

```
// notice how : is used as a gate slot
// this way we receive incoming event into a slot
:[ 200, :] $myConst200

100 myConst200
myConst200 ? // 200
             // 100
```

## Arithmetic

Binary operators consume their **right-hand operand**: <<<+>>>, <<<->>>, <<<*>>>, <<</>>>, <<<%>>>.

```
19 $numA
 2 $numB

numA + numB $add
add ? // 21
```

<<<++>>> and <<<-->>> are Unary operators and they do not need an operand.

```
19++ ? // 20
```

<<<+>>> can be used also to join string or buffers.

```
strA + strB $strC       // Hello World!
strC + 100 + 20 $strD   // Hello World!10020
```

**No operator precedence**, evaluation is strictly left to right:

```
1 + 2 * 5 / 15 ? // 1
```

Parentheses in calculations create a **gate**, not grouping.

When using <<<->>> as a subtraction operator, do not forget to put a space after it, otherwise it will be considered a negative sign for the next token.

## Relational

Relational operators do not return booleans. On success, the **subject** (left side) passes through unchanged. The **object** (right side) is what it is checked against.

```
20 = 20 $x
x ? // 20

20 = 10 $y
y ? // never releases
```

| Operator | Meaning |
|----------|---------|
| <<<=>>> | equal |
| <<<!>>> | not equal |
| $$$KeywordSnippet keyword=> $$$  <<<>=>>> | greater / greater-or-equal |
| $$$KeywordSnippet keyword=< $$$ <<<<=>>> | less / less-or-equal |

Empty values of different types are not equal (<<<0x>>> ≠ <<<"">>>).
Type coercion is automatically happening between numbers and strings so <<<"1">>> is equal to <<<1>>>.

Please note, <<<=>>> is equality check and simorg doesn't have classical assignment operator anymore as the whole system is naturally communicating using events.

Subject drives execution — with XOR gates, which operand is the subject changes what gets logged:

```
[1;2;3] $x
2 $y

x > y ? // logs only 3
y > x ? // logs only 2
```

## Truthy

Unary operator <<<&>>> passes the event through only if the value is truthy.

Truthy: any non-zero number, non-empty string, non-empty buffer.

```
1 & "will pass" ?
0 & "will never release" ?
```

For gates: AND is truthy when all slots are truthy; OR when at least one is.

**Not truthy** <<<!&>>> is the inverse. Use both branches explicitly instead of a classical <<<else>>>:

```
"" $userInput
userInput &
userInput !& "Invalid Empty Value Received!" ?
```

## Declaration

<<<$>>> marks the next token as a variable identifier. Definition happens at runtime when data arrives.

**Prefix**: expressions before <<<$>>> are part of the variable's essence:

```
% 3 $var
100 var ? // 1
```

**Suffix**: expressions after the identifier run as a side effect when the variable releases:

```
($x, $y, 0 $z) $point

1 point.x
2 point.y

point.x ? // 1
point ?   // (x: 1, y: 2, z: 0)
```

Prefix shapes what the variable holds; suffix shapes what happens when it releases.

## Logger

<<<?>>> logs the value and passes it through (newline appended).

```
"Hello World!" ?
```

<<<??>>> logs without a trailing newline. Useful for streaming output.

## Do Not Care

<<<|>>> skips the data and keeps only the **act of the event**. Useful for syncing without carrying values.

```
$x

(x, 1, 2) ? // (Trigger, 1, 2)
(x |, 20, 30) ? // (20, 30)

"Trigger" x
```

Gates exclude Do Not Care slots from their output. Use as a signal beacon:

```
| $trigger

100 trigger
"Start" trigger
```

Do Not Care events do not appear in logs.

## Filter

<<<@>>> passes an event only if it carries a specific frequency (identity layer). Still evolving.

```
$x
$y

(10 x, 20 y) $pointA

pointA @x ? // 10
```

## Collector

<<<..>>> batches streaming events into a **collection** <<<{ }>>> — Simorg's answer to arrays, without index-based access.

```
:[0, :] $data <10 ++data

data ..10 ?
// {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}
```

Chain collectors to batch then release one by one:

```
data ..10..2 ?
```

Design size-dependent logic **while** the collector fills — not after. Data should stream naturally; collectors are temporary holding points, not storage.

## Include

<<<#>>> brings in external resources inside runtime.

### Artifacts
Passing artifact identifier like, 
```
"@simorg/delay0.1.0" #delay
"Waiting for 3 Seconds..." ? 3 delay.sec "Done!" ?
```


### Local files

To include another source file inside current file,
```
"../my-artifact/main.art" #localArtifact
```

### Agentic Runtime
Code will be generated by runtime manager,

First include a runtime manager, for example,
```
"@runtime/runtime-manager0.1.0" #openAi
```
Now you can send prompts!

In an agentic runtime a standalone String value is considered an anonymous prompt,
```
// a standalone string value
"Create a web application on port 3000 with an empty layout" #appLayout

// not a prompt as it is used in a pipe
"Hello World!" ?
```

You can name your prompt and use the result later,
```
// this creates an artifact named chatComponent
"Create an agentic chatComponet, place it inside appLayout" #chatComponent

chatComponent.userPrompt ?
```

If you need to use an anonymous conditional prompt, simply use <<<#>>> without an identifier,

```
// this is a conditional prompt
chatComponent.onClose "Exit this application" #
```

Please join our pilot program to access Agentic Runtime feature.

## Conclusion

**Binary** — needs a right-hand operand:

| Category | Operators |
|----------|-----------|
| Arithmetic | <<<+>>> <<<->>> <<<*>>> <<</>>> <<<%>>> |
| Relational | <<<=>>> <<<!>>>  $$$KeywordSnippet keyword=> $$$  $$$KeywordSnippet keyword=>= $$$  $$$KeywordSnippet keyword=< $$$ $$$KeywordSnippet keyword=<= $$$  |
| Variable | <<<$>>> |
| Collector | <<<..>>> |
| Filter |  <<<@>>> | 


**Optional** - using operand is optional

| Category | Operators |
|----------|-----------|
| Include | <<<#>>> |


**Unary** — no operand needed:

| Category | Operators |
|----------|-----------|
| Opener | <<<:>>> |
| Truthy | <<<&>>> <<<!&>>> |
| Logger | <<<?>>> <<<??>>> |
| Do Not Care | <<<\|>>>  |
| Arithmetics | <<<++>>> <<<-->>> |

---

<!-- source: reference-book/04-Wrappers.md -->

A **Wrapper** is a Shell that limits the scope of events — the Simorg equivalent of a **scope** in classical languages. Events exist only inside the Shell that wraps them.

Use curly braces <<<{}>>> to create a wrapper. Simorg provides three kinds:

| Wrapper | Behavior |
|---------|----------|
| Isolator | Closed space — events cannot exit |
| Conditional | Activated by an external event |
| IO | Bidirectional — events flow in and out |

## Isolator

An isolator is a closed Shell. Events inside it cannot leave. Outer variables remain readable unless shadowed by a local declaration.

```
"Outside the Shell" $myVariable
myVariable ?

{
  "Inside the shell" $myVariable
  myVariable ?
}
// Outside the Shell
// Inside the shell
```

Reuse an outer variable when it is not redeclared inside:

```
"Outside the Shell" $myVariable
{
  myVariable ?
}
```

An isolator is active when its parent is active. Nothing outside can access its internal elements.

## Conditional

A conditional is an isolator with an explicit **activator** — an event that opens the Shell so internals can run.

```
1 {
  "Hello World!" ?
}
```

Any expression can activate a Shell: variables, calculations, gates, pipelines. A classic if-style pattern uses an AND gate:

```
100 $a
200 $b

(a > 50, b > 50) {
  "'a' and 'b' are greater than 50" ?
}
```

There is no <<<else>>>. Pathways must be explicit — use <<<&>>> and <<<!&>>> (or separate conditions) so every branch is a real channel for data.

You can declare a variable as part of a wrapper statement — either to receive external data, or to give the Shell a name and dedicated space:

```
$externalData {
  externalData ?
}
"External Event" externalData
```

```
$myVar {
  "Dedicated space for complex suffix logic" ?
}
"External Event" myVar
```

The activator is a hole: external events pass through it into the Shell. Prefer a plain eventflow when the side effect is a single action — wrappers shine when you need a real space.

### Layer Operator

The layer operator <<<.>>> walks through nested identity layers to reach a specific field — similar to member access in classical languages, but driven by Shell layers.

```
(
  "Hello!" $hello,
  "Bye!" $bye
) $message

message.hello ?
```

Push into a named slot:

```
(
  $hello,
  $bye
) $message

"Hello" message.hello
"Bye" message.bye

message ?
// (hello: Hello, bye: Bye)
```

Or structure and destructure in one step:

```
(
  $hello,
  $bye
) $message

("Hello", "Bye") message

message ?
```

Named gate slots behave like object fields. Destructuring into an AND gate requires matching length; an OR gate accepts whatever is available. A length mismatch on AND logs <<<INVALID_DESTRUCTION_PATTERN>>> and discards the event.

## IO

An IO wrapper uses the same <<<{}>>> syntax as a conditional. The difference is setup: data flows **in** from outside and **out** from inside — bidirectional event flow.

A simple adder:

```
$sum {
  ($a, $b) $args
  sum args
  args.a + args.b sum
}

(10, 20) sum ? // 30
```

- Declare the argument shape with an AND gate.
- Destructure the incoming event into <<<args>>>.
- Push the result back into <<<sum>>> — the Shell knows this is an internal event, so it does not re-activate.

IO looks like a function on the surface, but it is a data-driven mathematical structure — no program counter, no return address.

For multiple inputs and outputs, declare them in the activator with an OR gate:

```
[$arg1, $arg2, $add, $sub, $mul, $div] $calculate {
  calculate.arg1 + calculate.arg2 calculate.add
  calculate.arg1 - calculate.arg2 calculate.sub
  calculate.arg1 * calculate.arg2 calculate.mul
  calculate.arg1 / calculate.arg2 calculate.div
}

(10, 5) calculate ?
// [add: 15, sub: 5, mul: 50, div: 2]
```

When a declaration owns its wrapper, only events that originate **inside** the Shell become the identifier's value. Using that identifier as a pipeline head receives those internal results — not the raw input arguments.

## Conclusion

Wrappers are spaces. Isolators close them; conditionals open them with an activator; IO shells make the flow bidirectional.

Combine wrappers with gates and eventflows for rich patterns — but do not force classical OOP shapes onto Simorg. Prefer pathways that event can follow naturally.

---

<!-- source: reference-book/05-Artifacts.md -->

Let's now talk about the **platform** side of the Simorg. The language creates pathways for events and the platform creates an ecosystem on top of it.
Language defines how events flow. Artifacts expand what those events can do.

<<<Logos>>> is the collaboration layer: a repository where Artifacts are published and shared.

Artifacts come in different forms and shapes.

A <<<Machine>>> is the device that runs Simorg applications — hardware that provides processing power.
At a higher level it is still a Shell because it wraps your events.

An <<<Application>>> is a program written in Simorg. Applications run on the engine, can be published to <<<Logos>>>, and can include agents for higher-level behavior. You can run multiple applications in a machine.

Other artifacts may include <<<Plugins>>>, <<<Binaries>>>, <<<AI Agents>>>, <<<Web>>> or <<<3D>>> components...any digital element that can talk to the engine can become an Artifact.

Artifacts are wrapped in a mathematical shell to join the engine's event flow naturally. Reusability is the key! Ship complex capability once, plug it into many Applications.

For example,
```
"@simorg/time0.1.0" #delay
"Waiting for 3 Seconds..." ? 3 delay.sec "Done!" ?
```

Browse published Artifacts on $$$ToPageLinker keyword=Logos toRoute=https://logos.simorg.art$$$.

Simorg also ships a Standard Library of basic plugin Artifacts — start there for everyday utilities.

### Agentic Runtime

Instantiate a runtime manager, then create Artifacts from natural language:

```
"@runtime/openai-runtime-manager0.1.0" #openAi
"your-openai-token" openAi.initialize

"Create a web application and serve it on port 3000" #myApp
```

The runtime manager builds the Artifact; your code continues to treat it as a Shell in the pipeline.

---

<!-- source: reference-book/06-Logos.md -->

Logos is Simorg's artifact repository.

This document will be updated once logos is available.

---