diff --git a/readme.md b/readme.md
index d32cac9..1f45c3e 100644
--- a/readme.md
+++ b/readme.md
@@ -9,7 +9,8 @@ The system implements reinforcement learning by analyzing past iterations to imp
SIA can also modify its own source code, allowing it to adapt to new challenges.
## Working principles
-This section gives a high-level overview of the main components of SIA and how they work together.
+
+High-level overview of the main components of SIA and how they work together.
### LLM-Powered Reasoning
@@ -190,6 +191,7 @@ The pre and post files are optional.
To do an actual training round, a sia:latest container is started.
This is an example action that trains on two datasets with learning rate 0.1:
+
```xml
@@ -198,15 +200,15 @@ This is an example action that trains on two datasets with learning rate 0.1:
/datasets/description_of_nother_problem/:/datasets/description_of_nother_problem/
sia
- train
- --learning-rate
- 0.1
- --model
- /models/2024_10_19_08_21_41
- --out
- /models/2024_10_19_15_03_52
- /datasets/description_of_a_problem/
- /datasets/description_of_nother_problem/
+ train
+ --learning-rate
+ 0.1
+ --model
+ /models/2024_10_19_08_21_41
+ --out
+ /models/2024_10_19_15_03_52
+ /datasets/description_of_a_problem/
+ /datasets/description_of_nother_problem/
```
@@ -222,12 +224,616 @@ The web interface takes over standard input and output.
It each time the LLM generates a response, the web interface will display it.
The user can modify the response before the actions are executed.
+## Actions
+
+A list of all available core actions.
+Indicating how they are implemented and how SIA can use them.
+
+### Read standard input
+
+Module: Process
+
+#### Function declaration
+```python
+def read_stdin(n: int = -1) -> str:
+ ''' Read n bytes from standard input.
+
+ Args:
+ n: int, The number of bytes to read; -1 for all available bytes (default: -1)
+ '''
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+
+```
+
+#### Results
+
+An attribute `actual` is added with the amount of bytes read.
+A text node is added with the data as `CDATA`.
+
+### Write to standard output
+
+Module: Process
+
+Function declaration
+```python
+def write_stdout(text: str) -> None:
+ ''' Write text to standard output. '''
+ pass
+```
+
+Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+```
+
+ Example
+```xml
+ Hello world!
+```
+
+#### Results
+
+No information is added.
+
+### Monitor file
+
+Module: Process
+
+#### Function declaration
+```python
+def monitor_file(path: str, offset: int = 0, length: int = -1, unit: str = 'bytes') -> None:
+ ''' Monitor a file for changes.
+
+ Parameters:
+ - path: str, the path to the file to monitor
+ - offset: int, the starting point for reading (default: 0)
+ - length: int, the amount to read; -1 means read to end (default: -1)
+ - unit: str, 'bytes' or 'lines' (default: 'bytes')
+ '''
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+
+ /context_history/2024_10_20/13_43_51.56
+
+```
+
+#### Results
+
+No information is added.
+The monitored files are added to the context separately with an id.
+
+### Unmonitor file
+
+Module: Process
+
+#### Function declaration
+```python
+def unmonitor_file(path: str = None, id: int = None) -> None:
+ ''' Unmonitor a file.
+
+ Parameters:
+ - path: str, the path to the file
+ - id: int, the id of the file as indicated in the context
+
+ Either path or id must be provided.
+ '''
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+
+
+ /context_history/2024_10_20/13_43_51.56
+
+```
+
+#### Results
+
+No information is added.
+
+### Start container
+
+Module: Docker
+
+#### Function declaration
+```python
+def start_container(
+ image: str,
+ name: str = None,
+ timeout: int = -1,
+ command: str = None,
+ arguments: List[str] = None,
+ volumes: Dict[str, str] = None, # host_path: container_path
+ ports: Dict[str, str] = None, # host_port: container_port
+ environment: Dict[str, str] = None, # key: value
+) -> None:
+ """Start a new Docker container with the specified configuration.
+
+ Args:
+ image: Docker image to use
+ name: Unique container name for long running containers
+ timeout: Timeout in milliseconds for short running containers
+ command: Main command to run in container
+ arguments: List of command line arguments
+ volumes: Dictionary mapping host paths to container paths
+ ports: Dictionary mapping host ports to container ports
+ environment: Dictionary of environment variables and values
+
+ name or timeout must be provided.
+
+ Example:
+ start_container(
+ image="busybox:latest",
+ timeout=1000,
+ command="sh",
+ arguments=["-c", "echo 'Hello' > /data/output.txt"],
+ volumes={
+ "/host/data": "/data",
+ "/host/config": "/config"
+ },
+ ports={
+ "8080": "80",
+ "2222": "22"
+ },
+ environment={
+ "DEBUG": "1",
+ "API_KEY": "secret123"
+ }
+ )
+ """
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+
+ sh
+ -c
+ /data/output.txt]]>
+
+ /host/data:/data
+ /host/config:/config
+
+
+
+
+
+
+ 1
+ secret123
+
+
+```
+
+#### Results
+
+For short running containers, the exit status is added as attribute.
+Standard output and standard error are merged and added as `CDATA` text node.
+
+For long running containers, no information is added.
+The container is started and represented in the containers section of the main context.
+
+### Stop container
+
+Module: Docker
+
+#### Function declaration
+```python
+def stop_container(name: str) -> None:
+ """Stop a Docker container by name.
+
+ Args:
+ name: Name of the container to stop
+ """
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+my-long-running-container
+```
+
+#### Results
+
+No information is added.
+The container will be removed from the containers section of the main context.
+
+### Write to container standard input
+
+Module: Docker
+
+#### Function declaration
+```python
+def write_container_stdin(name: str, data: str) -> None:
+ """Write data to a container's standard input.
+
+ Args:
+ name: Name of the target container
+ data: Data to write to stdin
+ """
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+ls -la
+```
+
+#### Results
+
+No information is added.
+The data will be written to the container's stdin buffer.
+
+### Read from container standard output
+
+Module: Docker
+
+#### Function declaration
+```python
+def read_container_stdout(name: str, n: int = -1) -> str:
+ """Read from a container's standard output buffer.
+
+ Args:
+ name: Name of the container
+ n: Number of bytes to read; -1 means read all available (default: -1)
+
+ Returns:
+ Data read from stdout
+ """
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+
+```
+
+#### Results
+
+An attribute `actual` is added with the amount of bytes read.
+A text node is added with the data as `CDATA`.
+
+### Read from container standard error
+
+Module: Docker
+
+#### Function declaration
+```python
+def read_container_stderr(name: str, n: int = -1) -> str:
+ """Read from a container's standard error buffer.
+
+ Args:
+ name: Name of the container
+ n: Number of bytes to read; -1 means read all available (default: -1)
+
+ Returns:
+ Data read from stderr
+ """
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+
+```
+
+#### Results
+An attribute `actual` is added with the amount of bytes read.
+A text node is added with the data as `CDATA`.
+
+### Wait for container to finish
+
+Module: Docker
+
+#### Function declaration
+```python
+def wait_container(name: str, timeout: int):
+ """Wait for a container to finish execution.
+
+ Args:
+ name: Name of the container to wait for
+ timeout: Time to wait in milliseconds
+ """
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+background-task
+```
+
+#### Results
+The exit status is added as an attribute.
+All remaining data on stdout and stderr is merged and added as `CDATA` text node.
+
+### Select LLM by file name
+
+Module: Reinforcement Learning
+
+#### Function declaration
+```python
+def select_llm(path: str) -> None:
+ """Switch to a different LLM model file.
+
+ Args:
+ path: Path to the model file to load
+ """
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+/models/2024_10_19_15_03_52
+```
+
+#### Results
+
+No information is added.
+The new model will be used starting from the next iteration.
+
+### Update to commit id
+
+Module: Process
+
+#### Function declaration
+```python
+def update_to_commit(commit_id: str) -> None:
+ """Update the running SIA process to a different version.
+ This will terminate the current process immediately.
+ Make sure the git commit is well tested and there is plenty of clear documentation for the new SIA instance to start.
+
+ Args:
+ commit_id: The git commit ID to update to
+ """
+ pass
+```
+
+#### Schema
+```xml
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Example
+```xml
+0015e27
+```
+
+#### Results
+
+No information is added.
+The process will be replaced by the new version.
+
## Example iterations
### Clarifying a task
+
This example shows how to work with standard IO, run simple scripts and monitor files.
#### Context
+
```xml
- Remind me to feed the cat tomorrow morning
+
+
+
-Name: John (I don't know his last name)
+
```
#### LLM response
+
```xml
John did not specify an exact time. I'll suggest 9am. He also did not specify how to be reminded. I'll ask but if he doesn't respond I'll assume a text message on standard output is fine. I'll write down this task in a file so I can keep it in context. I can write simple files with busybox:latest and echo but I will need to use sh -c to do the redirect.
sh
- -c
- /tasks/reminder.txt]]>
+ -c
+ /tasks/reminder.txt]]>
-```
\ No newline at end of file
+```