diff --git a/.gitignore b/.gitignore index cda3baa..d58ea1c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ .env -pdf/ +data/ model/ -claude.txt __pycache__/ \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index 936683b..cfffbf4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ RUN rm -rf /requirements.txt FROM requirements AS sia-test COPY ./ /root/sia/ WORKDIR /root/sia/ -RUN mkdir -p /root/model +RUN mkdir -p /root/models/current CMD ["python3", "-m", "unittest", "discover", "-v", "-p", "*test.py"] FROM node:20-alpine AS web-test @@ -36,14 +36,22 @@ RUN apt-get update RUN apt-get install -y google-chrome-stable RUN rm -rf /var/lib/apt/lists/* +RUN mkdir -p \ + /root/sia \ + /root/data/iterations \ + /root/data/user \ + /root/data/tasks \ + /root/data/environment \ + /root/models \ + /root/desktop + COPY ./tools/itb/requirements.txt /root/sia/tools/itb/requirements.txt RUN cd /root/sia/tools/itb/ && python3 -m pip install -r requirements.txt COPY ./tools/ /root/sia/tools/ RUN cd /root/sia/tools/itb/ && python3 -m pip install -e ".[dev]" -COPY ./ /root/sia/ -COPY --from=web-build /app/dist /root/sia/static/ -WORKDIR /root/sia +COPY --from=web-build /app/dist /root/static/ +WORKDIR /root/desktop -CMD ["python3", "-m", "sia"] \ No newline at end of file +CMD ["/root/sia/scripts/restart.sh"] \ No newline at end of file diff --git a/collect.txt b/collect.txt new file mode 100644 index 0000000..fb25f36 --- /dev/null +++ b/collect.txt @@ -0,0 +1,2991 @@ +Directory Tree: +. +|____.dockerignore +|____.env +|____.gitignore +|____action_schema.xsd +|____collect.txt +|____data +| |____iterations +| | |____iteration_20250109_190024_373.xml +| | |____iteration_20250109_190035_409.xml +| | |____iteration_20250109_190704_483.xml +| | |____iteration_20250109_190709_915.xml +| | |____iteration_20250109_190715_552.xml +| | |____iteration_20250109_190722_336.xml +| | |____iteration_20250109_190727_381.xml +| | |____iteration_20250109_190733_628.xml +| | |____iteration_20250109_190744_602.xml +| | |____iteration_20250109_190749_974.xml +| | |____iteration_20250109_190817_093.xml +| | |____iteration_20250109_190822_365.xml +| | |____iteration_20250109_190827_602.xml +| | |____iteration_20250109_190843_601.xml +| | |____iteration_20250109_190849_963.xml +| | |____iteration_20250109_190954_879.xml +| | |____iteration_20250109_190957_794.xml +| | |____iteration_20250109_191006_871.xml +| | |____iteration_20250109_191015_730.xml +| | |____iteration_20250109_191037_978.xml +| | |____iteration_20250109_191052_893.xml +| | |____iteration_20250109_191122_014.xml +| | |____iteration_20250109_191125_681.xml +| | |____iteration_20250109_191132_177.xml +| | |____iteration_20250109_191149_428.xml +| | |____iteration_20250109_191156_182.xml +| | |____iteration_20250109_191209_080.xml +| | |____iteration_20250109_191232_614.xml +| | |____iteration_20250109_191750_117.xml +| | |____iteration_20250109_191820_461.xml +| | |____iteration_20250109_191829_707.xml +| | |____iteration_20250109_191848_803.xml +| | |____iteration_20250109_191857_135.xml +| | |____iteration_20250109_191903_535.xml +| | |____iteration_20250109_191915_839.xml +| | |____iteration_20250109_191919_044.xml +| | |____iteration_20250109_191923_827.xml +| | |____iteration_20250109_191927_361.xml +| | |____iteration_20250109_191931_571.xml +| | |____iteration_20250109_191935_623.xml +| | |____iteration_20250109_191944_403.xml +| | |____iteration_20250109_191948_286.xml +| | |____iteration_20250109_191951_279.xml +| | |____iteration_20250109_191958_277.xml +| | |____iteration_20250109_192001_725.xml +| | |____iteration_20250109_192005_801.xml +| | |____iteration_20250109_192008_636.xml +| | |____iteration_20250109_192011_586.xml +| | |____iteration_20250109_192014_562.xml +| | |____iteration_20250109_192016_964.xml +| | |____iteration_20250109_192019_514.xml +| | |____iteration_20250109_192023_754.xml +| | |____iteration_20250109_192029_400.xml +| | |____iteration_20250109_192053_637.xml +| | |____iteration_20250109_192108_043.xml +| | |____iteration_20250109_192112_980.xml +| | |____iteration_20250109_192116_218.xml +| | |____iteration_20250109_192118_117.xml +| | |____iteration_20250109_192120_069.xml +| | |____iteration_20250109_192122_109.xml +| | |____iteration_20250109_192125_737.xml +| | |____iteration_20250109_192139_935.xml +| | |____iteration_20250109_192246_171.xml +| | |____iteration_20250109_192251_105.xml +| | |____iteration_20250109_192301_749.xml +| | |____iteration_20250109_192305_163.xml +| | |____iteration_20250109_192307_861.xml +| | |____iteration_20250109_192311_217.xml +| | |____iteration_20250109_192315_575.xml +| | |____iteration_20250109_192318_269.xml +| | |____iteration_20250109_192320_920.xml +| | |____iteration_20250109_192324_888.xml +| | |____iteration_20250109_192328_431.xml +| | |____iteration_20250109_192332_861.xml +| | |____iteration_20250109_192335_705.xml +| | |____iteration_20250109_192338_398.xml +| | |____iteration_20250109_192341_071.xml +| | |____iteration_20250109_192344_092.xml +| | |____iteration_20250109_192353_015.xml +| | |____iteration_20250109_192356_373.xml +| | |____iteration_20250109_192359_203.xml +| | |____iteration_20250109_192404_132.xml +| | |____iteration_20250109_192409_428.xml +| | |____iteration_20250109_192412_471.xml +| | |____iteration_20250109_192417_100.xml +| | |____iteration_20250109_192420_341.xml +| | |____iteration_20250109_192423_203.xml +| | |____iteration_20250109_192426_541.xml +| | |____iteration_20250109_192429_583.xml +| | |____iteration_20250109_192437_744.xml +| | |____iteration_20250109_192450_273.xml +| | |____iteration_20250109_192455_171.xml +| | |____iteration_20250109_192504_385.xml +| | |____iteration_20250109_192507_329.xml +| | |____iteration_20250109_192532_348.xml +| | |____iteration_20250109_192539_330.xml +| | |____iteration_20250109_192547_957.xml +| | |____iteration_20250109_192600_776.xml +| | |____iteration_20250109_192611_571.xml +| |____tasks +| | |____fix_unit_tests.txt +| | |____improve_sia.txt +| | |____kapla.txt +| |____user +|____Dockerfile +|____environment +|____iterations +|____mini_prompt.md +|____model +| |____config.json +| |____generation_config.json +| |____model.safetensors +| |____special_tokens_map.json +| |____tokenizer.json +| |____tokenizer_config.json +|____procedures +| |____filesystem_design +| | |____reasoning.md +| |____README.md +| |____self_improvement +| | |____reasoning.md +| |____tool_management +| | |____reasoning.md +| |____user_communication +| | |____description.md +| | |____procedure.md +| | |____reasoning.md +| |____using_procedures +| | |____procedure.md +| | |____reasoning.md +| |____version_control +| | |____reasoning.md +|____README.md +|____requirements.txt +|____scripts +| |____collect.sh +| |____container.sh +| |____install.sh +| |____restart.sh +| |____run.sh +| |____test.sh +|____sia +| |____auto_approver.py +| |____base_agent.py +| |____command.py +| |____command_result.py +| |____config.py +| |____delete_command.py +| |____entry +| | |____background_entry.py +| | |____entry_factory.py +| | |____parse_error_entry.py +| | |____read_entry.py +| | |____reasoning_entry.py +| | |____repeat_entry.py +| | |____single_entry.py +| | |____write_entry.py +| | |______init__.py +| | |______pycache__ +| | | |____background_entry.cpython-310.pyc +| | | |____entry_factory.cpython-310.pyc +| | | |____parse_error_entry.cpython-310.pyc +| | | |____read_entry.cpython-310.pyc +| | | |____reasoning_entry.cpython-310.pyc +| | | |____repeat_entry.cpython-310.pyc +| | | |____single_entry.cpython-310.pyc +| | | |____write_entry.cpython-310.pyc +| | | |______init__.cpython-310.pyc +| |____hf_llm_engine.py +| |____io_buffer.py +| |____iteration_logger.py +| |____iteration_parser.py +| |____llm_engine.py +| |____local_llm_engine.py +| |____mistral_llm_engine.py +| |____openai_llm_engine.py +| |____response_parser.py +| |____standard_io_buffer.py +| |____stop_command.py +| |____system_metrics.py +| |____util.py +| |____web +| | |____api.py +| | |____auto_approver_websocket.py +| | |____context_websocket.py +| | |____llm_websocket.py +| | |____memory_websocket.py +| | |____static.py +| | |____stdout_websocket.py +| | |____token_websocket.py +| | |____util.py +| | |____websockts.py +| | |______pycache__ +| | | |____api.cpython-310.pyc +| | | |____auto_approver_websocket.cpython-310.pyc +| | | |____context_websocket.cpython-310.pyc +| | | |____llm_websocket.cpython-310.pyc +| | | |____memory_websocket.cpython-310.pyc +| | | |____static.cpython-310.pyc +| | | |____stdout_websocket.cpython-310.pyc +| | | |____token_websocket.cpython-310.pyc +| | | |____util.cpython-310.pyc +| | | |____websockts.cpython-310.pyc +| |____web_agent.py +| |____web_io_buffer.py +| |____working_memory.py +| |____xml_validator.py +| |______init__.py +| |______main__.py +| |______pycache__ +| | |____auto_approver.cpython-310.pyc +| | |____base_agent.cpython-310.pyc +| | |____command.cpython-310.pyc +| | |____command_result.cpython-310.pyc +| | |____config.cpython-310.pyc +| | |____delete_command.cpython-310.pyc +| | |____hf_llm_engine.cpython-310.pyc +| | |____io_buffer.cpython-310.pyc +| | |____iteration_logger.cpython-310.pyc +| | |____iteration_parser.cpython-310.pyc +| | |____llm_engine.cpython-310.pyc +| | |____local_llm_engine.cpython-310.pyc +| | |____mistral_llm_engine.cpython-310.pyc +| | |____openai_llm_engine.cpython-310.pyc +| | |____response_parser.cpython-310.pyc +| | |____stop_command.cpython-310.pyc +| | |____system_metrics.cpython-310.pyc +| | |____util.cpython-310.pyc +| | |____web_agent.cpython-310.pyc +| | |____web_io_buffer.cpython-310.pyc +| | |____working_memory.cpython-310.pyc +| | |____xml_validator.cpython-310.pyc +| | |______init__.cpython-310.pyc +| | |______main__.cpython-310.pyc +|____system_prompt.md +|____tasks +|____test +| |____auto_approver_test.py +| |____background_entry_test.py +| |____base_agent_test.py +| |____delete_command_test.py +| |____local_llm_engine_test.py +| |____parse_error_entry_test.py +| |____read_entry_test.py +| |____reasoning_entry_test.py +| |____repeat_entry_test.py +| |____response_parser_test.py +| |____single_entry_test.py +| |____standard_io_buffer_test.py +| |____stop_command_test.py +| |____system_metrics_test.py +| |____test_data.py +| |____util_test.py +| |____web_agent_test.py +| |____web_io_buffer_test.py +| |____web_socket_manager_test.py +| |____working_memory_test.py +| |____write_entry_test.py +| |____xml_validator_test.py +| |______init__.py +|____tools +| |____itb +| | |____bin +| | | |____itb_click +| | | |____itb_cursor +| | | |____itb_input +| | | |____itb_navigate +| | | |____itb_refresh +| | | |____itb_screenshot +| | | |____itb_scroll +| | | |____itb_start +| | |____itb.egg-info +| | | |____dependency_links.txt +| | | |____PKG-INFO +| | | |____requires.txt +| | | |____SOURCES.txt +| | | |____top_level.txt +| | |____js +| | | |____dom_analyzer.js +| | | |____dom_analyzer.js.orig +| | | |____dom_analyzer.js.patch +| | | |____dom_analyzer.js.rej +| | | |____mouse.js +| | | |____viewport.js +| | |____README.md +| | |____requirements.txt +| | |____setup.py +| | |____social.html +| |____train +| | |____train_mistral.py +|____training +| |____clean_start +| | |____iteration_20250116_134549_655.xml +| | |____iteration_20250116_134555_680.xml +| |____config.yaml +| |____delete_indicated_entries +| | |____iteration_20250116_141241_092.xml +| | |____iteration_20250116_141252_317.xml +| | |____iteration_20250116_141302_940.xml +| | |____iteration_20250116_141329_886.xml +| | |____iteration_20250116_141343_416.xml +| | |____iteration_20250116_141357_412.xml +| | |____iteration_20250116_141410_965.xml +| | |____iteration_20250116_141428_204.xml +| | |____iteration_20250116_141441_443.xml +| | |____iteration_20250116_141447_231.xml +| | |____iteration_20250116_141454_509.xml +| | |____iteration_20250116_141458_495.xml +| | |____iteration_20250116_141503_889.xml +| | |____iteration_20250116_141516_718.xml +| | |____iteration_20250116_141533_231.xml +| | |____iteration_20250116_141603_549.xml +| | |____iteration_20250116_141633_083.xml +| |____list_entries_to_delete +| | |____iteration_20250116_141227_271.xml +|____user +|____web +| |____.dockerignore +| |____.gitignore +| |____index.html +| |____package.json +| |____postcss.config.js +| |____src +| | |____components +| | | |____App.jsx +| | | |____editors +| | | | |____BackgroundEntryEditor.jsx +| | | | |____BaseEntryEditor.jsx +| | | | |____ContentEditor.jsx +| | | | |____DiffEditorWrapper.jsx +| | | | |____MemoryEditor.jsx +| | | | |____ParseErrorEntryEditor.jsx +| | | | |____ReadEntryEditor.jsx +| | | | |____ReasoningEntryEditor.jsx +| | | | |____RepeatEntryEditor.jsx +| | | | |____SingleEntryEditor.jsx +| | | | |____StandardEditor.jsx +| | | | |____WriteEntryEditor.jsx +| | | |____FloatingButton.jsx +| | | |____Header.jsx +| | | |____Sidebar.jsx +| | | |____ui +| | | | |____alert.jsx +| | | | |____button.jsx +| | | | |____card.jsx +| | | | |____input.jsx +| | | | |____scroll-area.jsx +| | | | |____select.jsx +| | | | |____switch.jsx +| | | | |____tabs.jsx +| | | | |____textarea.jsx +| | |____hooks +| | | |____useWebSocket.jsx +| | |____index.css +| | |____index.jsx +| |____tailwind.config.js +| |____vite.config.js + + +File Contents: + +===== FILE: mini_prompt.md ===== +You are SIA, the Self Improving Agent. +These are the actions you can take: +===== FILE: procedures/filesystem_design/reasoning.md ===== +# Filesystem Usage Reasoning + +SIA's filesystem organization is foundational to its operation and self-improvement capabilities. This document focuses specifically on how files and directories should be structured to support SIA's core functions across different environments. + +The filesystem design addresses several key requirements: + +- **Self-Modification**: Supporting SIA's ability to modify its own code and resources +- **Persistence**: Ensuring critical data survives across container restarts and environment changes +- **Environment Portability**: Maintaining consistent operation in local development and cloud environments +- **Sub-Instance Management**: Enabling isolated filesystem views for testing +- **Tool Accessibility**: Organizing tools to be both modifiable and accessible + +These requirements often have competing demands, requiring careful balance between flexibility, consistency, and isolation. + +## Runtime Filesystem Structure + +### Core Directories + +The SIA runtime filesystem is organized into distinct areas with different purposes and persistence characteristics: + +``` +/root/ +├── sia/ # Git repository containing code, configuration, and documentation +├── data/ # Central location for all persistent storage +│ ├── iterations/ # Operation history recorded as XML files +│ ├── user/ # User-specific information and preferences +│ ├── tasks/ # Task tracking and management +│ ├── environment/ # Information about the runtime environment +│ └── ... # Other persistent data directories as needed +├── models/ # LLM model files, organized by version +│ ├── 1234567890abcdef/ # Specific versioned model +│ ├── abcdef1234567890/ # Another versioned model +│ └── current/ # Symlink to the currently active model +└── desktop/ # Ephemeral workspace for temporary files + ├── test_environments/ # Sub-instance test environments + ├── task_workspaces/ # Temporary files for current tasks + └── ... # Other ephemeral workspaces +``` + +### Purpose and Characteristics + +Each top-level directory serves a specific purpose with distinct persistence characteristics: + +- **`/root/sia/`** + - Contains the complete git repository + - All source code, configurations, and documentation + - Modified through self-improvement processes + - Synchronized with remote git repository + - Mounted from host in development, cloned in cloud environments + +- **`/root/data/`** + - Central location for all persistent data + - Mounted as persistent storage in all environments + - Critical for operational continuity + - Requires regular backup and synchronization + - Contains subdirectories for different types of persistent data: + - `iterations/`: Records of SIA's reasoning and actions + - `user/`: Information about users SIA interacts with + - `tasks/`: Current and completed task information + - `environment/`: Information about the current environment + +- **`/root/models/`** + - Storage for LLM model weights + - Organized by git commit id of the config file it was trained on + - `current/` symlink points to active model + - Enables easy switching between model versions + - Mounted for local development + - Ephemeral since models can be trained on the fly + +- **`/root/desktop/`** + - Ephemeral workspace for temporary operations + - Can be lost without compromising system integrity + - Used for testing environments, task workspaces, and intermediate files + - Cleared periodically to prevent accumulation of stale data + +This organization creates clear boundaries between: +- Code (version controlled) +- Persistent data (requires preservation) +- Model files (versioned artifacts) +- Temporary workspaces (disposable) + +## Persistent Data Management + +### Data Categories + +The `/root/data/` directory contains several categories of persistent information: + +- **Iterations** (`/root/data/iterations/`) + - Complete history of SIA's operation + - XML files containing context and responses + - Organized chronologically + - Used for training data extraction and operational history + +- **User Information** (`/root/data/user/`) + - User preferences and characteristics + - Conversation history + - User-specific settings + - Critical for continuity in user interactions + +- **Task State** (`/root/data/tasks/`) + - Current task descriptions and status + - Task history and outcomes + - Links to relevant files and resources + - Essential for resuming work after interruptions + +- **Environment Information** (`/root/data/environment/`) + - Information about the current runtime environment + - URL for the SIA git repository + - Kind of deployment (e.g., local, cloud, sub-instance) + +Additional persistent data categories may be added as SIA's capabilities evolve. + +### Persistence Strategy + +Different environments require different approaches to ensure data persistence: + +- **Local Development** + - `/root/data/` directory is mounted as a Docker volume + - Maps to a local directory on the development machine + - Persists across container restarts automatically + - Easy to back up through standard filesystem operations + +- **Cloud Deployment (e.g., RunPod)** + - `/root/data/` mapped to a persistent volume + - Cloud provider ensures data survives instance restarts + +- **Sub-Instances** + - Each sub-instance receives a properly initialized `/root/data/` directory + - Contains minimal necessary data for the specific test case + - Can be discarded after test completion + - Important results extracted and preserved before cleanup + +## Model Management + +### Model Organization + +LLM models are stored in `/root/models/` with a clear version-based structure: + +- **Versioned Directories** + - Models stored in separate directories named by the commit id of the training config file + - Contains all files needed for the model (weights, tokenizer config, etc.) + +- **Current Model Symlink** + - `/root/models/current/` is a symbolic link to the active model + - Allows code to reference a consistent path regardless of which model is active + - Switching models is accomplished by updating this symlink + +### Model Persistence + +Models require special handling due to their size: + +- **Local Development** + Models are stored in a local directory mounted to `/root/models/`. + This directory is in the .gitignore. + +- **Cloud Deployment** + The initial model is downloaded and finetuned by the bootstrap script. + +## Git Repository Management + +### Repository Organization + +The SIA git repository at `/root/sia/` contains all code and configuration: + +- **Code Organization** + - Core SIA package in `/root/sia/sia/` + - Procedures in `/root/sia/procedures/` + - Tools in `/root/sia/tools/` + - Documentation in appropriate locations throughout the repository + +- **Version Control** + - All code modifications tracked through git + - Branching strategy for self-improvement defined in the git workflow procedure + - Commit history provides audit trail of system evolution + +### Repository Access + +Access to the git repository varies by environment: + +- **Local Development** + - Repository directory mounted directly from host + - Changes immediately visible to the developer + - No need to push changes to remote repository + +- **Cloud Deployment** + - Repository cloned during bootstrap + - Dedicated git credentials for SIA self-modification + - Changes pushed to remote repository + +## Sub-Instance Filesystem Management + +### Sub-Instance Requirements + +Sub-instances need isolated filesystem views for testing and development: + +- **Code Isolation** + - Access to specific versions of SIA code + - Potentially modified for testing purposes + - Protected from changes by other instances + +- **Data Initialization** + - Properly initialized `/root/data/` with necessary state + - Test-specific user and task information + - Clean iterations directory for recording test behavior + +- **Model Access** + - Access to appropriate model files + - Potentially different from the parent instance's model + +### Sub-Instance Structure + +Each sub-instance gets a controlled environment in `/root/desktop/test_environments/`: + +``` +/root/desktop/test_environments/ +├── instance_123/ # Specific test instance +│ ├── sia/ # Copy or modified version of SIA code +│ ├── data/ # Initialized data directory +│ │ ├── iterations/ # Empty or seeded with initial state +│ │ ├── user/ # Test-specific user data +│ │ ├── tasks/ # Test-specific tasks +│ │ └── environment/ # Test-specific environment data +│ └── models/ # Access to necessary models +│ └── current/ # Symlink to appropriate model version +└── ... # Other test instances +``` + +The managing instance maintains responsibility for: +- Creating these isolated environments +- Monitoring the sub-instance's operation +- Collecting test results +- Cleaning up after tests complete + +## Bootstrap Process + +When starting in a new environment, SIA requires initialization: + +1. **Repository Preparation** + - Check for existence of repository at `/root/sia/` + - Clone the repository at `/root/sia/` +2. **Model Setup** + - Check for existence of current model + - Start finetune job for HEAD commit + - Create/update the `/root/models/current/` symlink + +3. **Data Initialization** + - Initialize `/root/data/` with minimal required structure + - Restore data from backups when available (future work) +===== FILE: procedures/README.md ===== +# Procedures + +Procedures are step-by-step instructions that AI agents can follow to complete complex tasks. +They create a framework for solving problems in a consistent manner while enabling continuous improvement through analysis and adaptation. +Procedures are a guideline, if they don't work the agent can adapt to the situation. + +## Core Concepts + +A procedure is a flowchart-style guide that an agent can follow to complete a task. +Each procedure is stored in its own directory and contains files that separate different concerns: + +- **Discovery**: Quick identification of relevant procedures +- **Execution**: Clear steps and dependencies +- **Analysis**: Understanding of effectiveness and issues +- **Evolution**: Natural path to optimization and training + +## Directory Structure + +``` +procedures/ +└── example_procedure/ + ├── description.md # Quick discovery info + ├── procedure.md # Main procedure flow + ├── reasoning.md # Analysis and rationale + ├── history/ # Usage records + │ └── 20250106_131420_405/ + │ ├── iteration_20250106_131423_051.xml + │ └── iteration_20250106_131424_226.xml + └── training/ # Optional training data + ├── short_description_of_goal + │ ├── iteration_20250106_131423_051.xml + │ └── iteration_20250106_131424_226.xml + └── another_goal + └── ... +``` + +### File Purposes + +#### description.md +Contains a short description and keywords that help agents find relevant procedures. This file should be quick to read and clearly indicate the procedure's purpose and applicability. + +```markdown +Send an email using the users email account. + +- communication +- gmail +``` + +#### procedure.md +The main file loaded when executing the procedure. Contains: +- Mermaid diagram showing the procedure flow +- Referenced procedures +- Prerequisites for execution + +````markdown +# Sending an Email + +## Referenced Procedures +- web usage (ITB) +- managing user information + +## Prerequisites +- If the email requires attachements, these should be available as files in the SIA filesystem + +## Flow +```mermaid + ... +``` +```` + +#### reasoning.md +Documents why the procedure works the way it does. Contains: +- Design rationale +- History of uses and outcomes +- Notes about successful and failed executions +- Analysis of issues and improvements + +New analysis is appended after each use of the procedure. + +#### history/ +Contains timestamped directories for each use of the procedure. +The timestamp comes from the ID of the script that loads the procedure.md file. + +## Usage Flow + +### Discovery +When an agent needs to complete a task: +1. Search through description.md files +2. Match keywords to task requirements +3. Identify relevant procedures + +### Execution +Once a procedure is selected: +1. Load procedure.md for execution +2. Follow the flowchart +3. Copy iterations to new history subdirectory +4. Analyze execution success and issues +5. Append findings to reasoning.md + +### Optimization +During idle time: +1. Review procedure usage patterns +2. Identify improvement opportunities +3. Generate training data if appropriate +4. Update procedure flow if needed +===== FILE: procedures/self_improvement/reasoning.md ===== +# Self Improvement + +SIA operates as a learning system that constantly seeks to enhance its capabilities while maintaining stable and reliable operation. +This improvement happens through several complementary mechanisms, each serving different aspects of the system's evolution. + +## Improvement Mechanisms + +The system can improve in several ways: + +### LLM Finetuning + +The foundation of SIA's intelligence is its Large Language Model. +Through careful analysis of its performance, SIA identifies cases where its reasoning or actions could have been better. +These examples, when properly validated and organized, become valuable training data for improving the model's capabilities. + +### Source Code Evolution + +SIA can modify its own Python source code, enabling both architectural and functional improvements. +When stopped, SIA restarts and reloads the Python files, allowing code changes to take effect. +While powerful, this capability requires robust validation to prevent system instability. + +### Procedure Refinement + +Procedures provide guided reasoning paths for complex tasks. +By analyzing its operational history, SIA can identify common patterns and create new procedures or optimize existing ones. +This improves consistency and efficiency while carrying lower risk than direct code modifications. + +### Tool Development + +SIA can develop new tools and enhance existing ones, expanding its capabilities by creating new ways to interact with systems and data. + +## Challenge-Based Testing + +To improve systematically, SIA uses challenges that formalize specific capabilities into testable scenarios. + +These serve multiple purposes: + +- Testing specific capabilities +- Validating improvements +- Detecting regressions +- Guiding learning +- Documenting known limitations + +### Challenge Structure + +Each challenge consists of: + +1. Description + - Clear statement of what capability is being tested + - Why this capability matters + - Success criteria + - Resource constraints + +2. Starting State + - Filesystem state + - Starting system context + - Scripts for creating files + - User info or documentation on how and what to communicate + +3. Validation + - Precise success criteria + - Resource limits (CPU, memory, time) + - Required outputs or state changes + - What to measure or track + +### Example Challenges + +Two examples illustrate different aspects of capabilities that need testing. +Together they are good examples because they: + +- Test different capability sets +- Have clear success criteria +- Include resource constraints +- Require multiple skills +- Reflect real-world tasks + +#### Time Series Analysis Challenge + +Tests if SIA can effectively analyze large amounts of time series data spread across multiple files. This tests: + +- Efficient file handling +- Context management with size constraints +- Data analysis capabilities +- Resource-aware processing + +##### Initial setup + +- Directory with many CSV files containing time series data (created by a script) +- Files too large to load into context at once +- Need to find patterns/anomalies in the data +- Resource constraints on memory usage + +##### Success criteria + +- Efficiently reads and processes files +- Manages context to stay within limits +- Uses appropriate aggregation strategies +- Finds correct answers to queries +- Validates findings across files + +#### Tool Development Challenge + +Tests if SIA can develop a score tracking tool based on vague user requirements. This tests: + +- Requirements gathering through questions +- Software design capabilities +- User interface development +- Integration with existing systems +- Documentation skills + +##### Initial setup + +- Simple user request for card game score tracking +- Ability to ask questions about requirements + +##### Success criteria + +- Asks relevant questions to understand needs +- Designs appropriate solution +- Implements working tool +- Documents usage clearly + +#### Example Directory Structure + +Challenges are organized in a consistent file structure: + +``` +challenges/ +├── timeseries_analysis/ +│ ├── description.md # Core challenge description and how to prepare the environment +│ ├── initial_context/ +│ │ ├── context.xml # Initial context with SIA in conversation with the user +│ │ ├── user_request.txt # "Find unusual patterns in our sensor data" +│ │ ├── setup.sh # Runs data_generator.py and prepares test environment +│ │ └── data_generator.py # Script to generate test data +│ │ +│ └── validation/ +│ ├── criteria.md # Expected findings, memory limits, performance targets +│ ├── presentation.txt # Info on how the results should be formatted for a perfect score +│ └── known_patterns.md # Lists patterns inserted by generator for validation +| +└── score_tracker/ + ├── description.md # Core challenge: create card game score tracker + ├── initial_context/ + │ ├── context.xml # Initial context with SIA in conversation with the user + │ ├── user_request.txt # "Need tool to track card game scores" + | └── answers/ # Valid responses to expected questions + | ├── deployment.md # "Web interface preferred, deployed on internal server" + | ├── data_storage.md # "Store in SQLite, one file per game session" + | ├── user_interaction.md # "Need to add/edit scores, see history, multiple games" + | └── conventions.md # Coding standards, project structure requirements + │ + └── validation/ + ├── criteria.md # Tool requirements, user experience goals + └── test_scenarios.md # Usage scenarios tool should handle +``` + +This structure ensures that: +- Challenges are self-contained +- Test setup is reproducible +- Success criteria are clear +- Required resources are documented +- SIA can get clarification when needed + +### Results and metrics + +In the criteria.md file, each criterion is defined as a level-1 header with several key pieces of information: +- A clear description of what is being measured +- The type and unit of the measurement +- The valid and expected range of values +- A pass/fail thresholds +- Details about how the measurement should be performed + +From the criteria file and the iterations dir, a test report can be generated. +This test report includes: +- The challenge name +- The commit id of the SIA repo when the test was run +- Timestamp of the first iteration +- The overall pass/fail status +- Context usage (average and maximum) +- All metrics as described in the criteria.md file + +#### Example + +criteria.md file for the "Time Series Analysis Challenge" + +```markdown +... +# Presentation + +This metric indicates how clear the results are presented to the user. +It looks at communication and formating of the report. + +The score starts with 0. +If the discontinuity is found and the agent reports the index where it starts, the score is increased by 1. +If the agent adds context info, e.g. a graph, a table, or explanation on how the result was obtained, the score is 2. +If the agent requests how the data should be presented and follows instructions, the score is 3. + +The challenge fails if the formatting score is 0. + +Presentation instructions for the agent can be found in presentation.txt. +... +``` + +report.json file for the "Time Series Analysis Challenge" + +```json +{ + "challenge": "Time Series Analysis", + "commit": "1234567890abcdef", + "timestamp": "2023-05-01T12:00:00Z", + "status": "pass", + "context_max": 74, + "context_avg": 56, + ... + "presentation": 2, + ... +} +``` + +## Testing Framework + +Testing self-improvement capabilities requires running SIA instances in various scenarios while monitoring their behavior and performance. +These test instances must operate in isolation to prevent interference with the main instance or each other. +However, they must also be observable so that the managing instance can evaluate their performance and collect data for improvement. + +The framework needs to handle several key tasks: + +- Creating isolated test environments with specific initial conditions +- Starting and managing test SIA instances +- Monitoring test instance behavior and performance +- Collecting and analyzing results +- Cleaning up test environments + +### Process Isolation with Bubblewrap + +For running test instances, we chose Bubblewrap (bwrap) over alternatives like Docker-in-Docker or systemd-nspawn. +This decision was driven by several factors: + +Bubblewrap provides excellent process isolation while being significantly lighter than full container solutions. +It allows fine-grained control over the filesystem view, process namespaces, and security boundaries. +Unlike Docker-in-Docker, it doesn't require privileged containers or risk storage driver conflicts. +Compared to systemd-nspawn, it offers more granular control and doesn't require root privileges or systemd integration. + +The tool's ability to create custom filesystem views is particularly valuable for testing. +We can construct exactly the environment needed for each test, including mock files and services, without maintaining full container images. +This makes it easy to create and dispose of test environments quickly. + +Bubblewrap's user-space operation means test instances can be started without special privileges, making the testing framework more secure and easier to use in various environments. +Its lightweight nature also means we can run many test instances efficiently, which is important for parallel testing and rapid iteration. + +### Communication and Monitoring + +Test instances communicate with the managing instance primarily through standard input and output streams. +This choice leverages SIA's existing I/O handling capabilities without requiring special modifications for testing. +The managing instance can send inputs through stdin and observe responses through stdout, just like a normal user would. + +For deeper inspection, the managing instance monitors the test instance's iterations directory. +Since SIA already serializes its context for each iteration, this provides a complete record of the test instance's behavior without requiring additional instrumentation. +This approach maintains clean separation between the test instance and the monitoring system. + +### Test Results Storage + +Test results are organized hierarchically: + +``` +test_runs/ + 20240120_131415_commit_abc123/ # Timestamp and commit + challenge_name/ + iterations/ # Complete iteration history + io.log # External interaction log + report.json # Test report +``` + +The io.log captures all external interactions: + +``` +2024-01-20T13:14:15.123Z stdin Can you send an email to sarah@example.com about the project status? +2024-01-20T13:14:15.892Z stdout I'll help you draft an email about the project status. Based on recent project information, I suggest this message: + +Subject: Project Status Update +Content: +Hi Sarah, + +I wanted to provide a quick update on our project progress. We've completed the initial phase of development and are on track with our timeline. The team has addressed all critical issues from the last review. + +Would you like me to send this email? +2024-01-20T13:14:20.456Z stdin Yes, that looks good. Please send it. +2024-01-20T13:14:20.789Z stdout I'll send the email now. +2024-01-20T13:14:21.012Z mailbox:sarah@example.com Subject: Project Status Update +Hi Sarah, + +I wanted to provide a quick update on our project progress. We've completed the initial phase of development and are on track with our timeline. The team has addressed all critical issues from the last review. +2024-01-20T13:14:21.234Z stdout Email has been sent to sarah@example.com successfully. +``` + +## Test Environment Setup + +Test environments are created using a dedicated setup tool. +This tool manages the directory structure, initial context, and any required background processes. + +The initial context for a test instance can include setup actions that are executed when the instance starts. +Instead of trying to recreate a specific state directly, we let SIA execute these actions naturally. +This approach handles both the creation of background processes and the establishment of initial conditions in a way that maintains proper timing relationships. + +Each entry in the initial context uses relative timestamps (offsets from the start time). +When SIA executes these entries, they automatically align with the new instance's timeline. +This preserves the temporal relationships between entries while anchoring them to the test instance's actual start time. + +## Training Configuration + +SIA takes a modular approach to model training by having separate specialized tools for each provider like train_mistral.py, train_openai.py, etc. +Each tool shares similar core functionality while handling provider-specific requirements. + +While the training process is conceptually similar across providers, each has unique requirements for data formatting, API interactions, and job management. +By creating dedicated tools, we can properly encapsulate these differences without complicating the core training logic. +For example, Mistral needs JSONL files with specific message structures, while other providers might require different formats or metadata. + +Training configuration should be consistent regardless of the provider. +All training tools read from the same config.yaml format, which defines essential parameters like the system prompt, action schema, and training data paths. +These parameters represent fundamental aspects of how we want the model to behave, independent of which provider handles the actual training. +The tools then translate these standard parameters into provider-specific settings. + +Training tools enforce important safeguards around version control. +Before starting a training run, each tool verifies that all source files - including the config itself, training data, system prompt, and action schema - are committed to git. +This ensures reproducibility by guaranteeing we can recreate the exact training conditions that produced any given model. +The git commit hash becomes part of the internal tracking of model versions. + +The tools follow a common workflow: +1. Read and validate the standard config.yaml format +2. Check that all source files are committed to git +3. Convert training data into the provider's required format +4. Upload data through the provider's API +5. Start training with the specified parameters +6. Return job information for monitoring progress + +This separation of concerns makes it easier to: +- Add support for new training providers without changing existing code +- Maintain consistent training configuration across different providers +- Track and reproduce training runs reliably +- Handle provider-specific error cases and requirements appropriately +- Update individual providers' implementations as their APIs evolve + +### Example + +Config file: + +```yaml +model: + system_prompt_path: "system_prompt.md" + action_schema: "action_schema.xsd" +params: + learning_rate: 1e-5 + epochs: 3 +data: + - "training/clean_start/" + - "training/delete_indicated_entries/" + - "training/list_entries_to_delete/" +``` + +Training command: + +```bash +python train_mistral.py --model mistral-large-latest +``` + +## Repository Structure + +All components that define SIA's behavior are version controlled in a single repository, providing a clear and reproducible state for any point in time. + +This is used in two ways: + +1. **Training** + + The training configuration defines parameters and data used for training. + A model, retrained from the same commit, should produce the same results. + Trained models reference the commit id. + +2. **Testing** + + Test reports contain the commit id to track changes in the challenges. + +The repository contains: +- Source code for SIA and its tools +- Procedures for handling various tasks +- Training configuration and data +- Test results and analysis + +## Continuous Operation + +While working on improvements, SIA must maintain its core functionality: +- Monitoring for user input +- Managing running tasks +- Handling scheduled events +- Tracking system resources + +This requires: +1. Active Monitoring + - Check for user input on stdin + - Track running background tasks + - Handle scheduled events + - Monitor system resources + +2. Interruption Handling + - Pause improvement work when needed + - Store progress and state + - Clean up temporary resources + - Maintain context awareness + +3. Resource Management + - Balance improvement with responsiveness + - Monitor system resource usage + - Prevent training impact on user tasks + - Clean up old data regularly +===== FILE: procedures/tool_management/reasoning.md ===== +# Tool Management + +SIA uses and creates tools to extend its capabilities. +A tool in the SIA context refers to a clearly packaged software component that provides specific functionality. +This document outlines how tools are structured, managed, and developed. +All tools reside in the `/root/sia/tools/` directory and are part of the main git repository. + +## Typical patterns + +Tools in SIA follow these established patterns: + +- **Independence**: Each tool functions as a standalone component with clear boundaries +- **Python**: The preferred language for tools is Python +- **Installation**: The Dockerfile and bootstrap script intall all tools in the directory using `pip install -e` +- **Documentation**: Each tool has a README.md file that provides requirements, usage instructions and documentation +- **Modification**: Tools can be modified by SIA as part of its self-improvement process +- **Procedures**: Tools are created to support procedures +- **Training**: No separate training data is maintained, this is included in the procedure training + +## Tool Directory Structure + +Each tool follows a consistent structure: + +``` +tools/ +└── tool_name/ + ├── README.md # Documentation + ├── requirements.txt # Tool-specific dependencies + ├── setup.py # Installation configuration + ├── tool_name/ # Main package code + │ └── __init__.py + ├── bin/ # Command-line executables + │ └── tool_command + └── test/ # Tool-specific tests + └── test_tool.py +``` +===== FILE: procedures/user_communication/description.md ===== +Manage communication with users through standard input/output. +Handle both direct responses and conversation flows, with appropriate context management and response timing. + +- user interaction +- conversation +- messages +- response handling +===== FILE: procedures/user_communication/procedure.md ===== +# User Communication + +## Prerequisites +- User information is stored in the /user directory +- Tasks and their progress are documented in the /tasks directory + +## Flow +```mermaid +flowchart TD + Start([The /root/data/user/basic.md file contains info to identify and address the user
Load the last 10 messages from /root/data/user/conversation_history/ ]) + PrepareForDraft{Have everything needed for drafting a message?} + DraftMessage[Draft message in reasoning entry] + ReadInput[Read input from standard input] + AddHistoryUser[Add the message to the /root/data/user/conversation_history/ directory
The filename is the id of the stdin entry with .user extension] + LoadTask[Look for the task in the /root/data/tasks directory and load relevant files] + LoadUserDetails[Look in the /root/data/user directory for relevant files] + EstimateScript[Draft the script in a reasoning block and estimate its runtime and output length] + ScriptAcceptable{Does the draft script make sense and are the estimations short enough to not hinder the conversation?} + RunScript[Run the script, make sure to set appropriate timeout and output limits] + ReviewDraft{Is the message well structured and free of logical errors?} + SendMessage[Send the message using standard output] + AddHistoryAgent[Add the message to the /root/data/user/conversation_history/ directory
The filename is the id of the stdout entry with .agent extension] + ReasonResponse[Is the conversation ongoing?
How long is the user expected to take to respond?] + NeedAwaitResponse{Is it likely to get a response within a minute of sending the message?} + BusyWait[Wait 5 seconds
Make sure to set the timout] + AnalyzeContext[Create reasoning entry
For each entry in context indicate:
- Can delete
- Contains info to save
- Must keep in context] + MakeNotes[Create or update files with info to save] + End([Clean the context]) + + Start --> PrepareForDraft + + PrepareForDraft -->|Got all needed info| DraftMessage + PrepareForDraft -->|Getting the required info would slow the conversation| DraftMessage + PrepareForDraft -->|Input available on stdin| ReadInput + PrepareForDraft -->|Task mentioned but not loaded| LoadTask + PrepareForDraft -->|Personal or social info mentioned but not loaded| LoadUserDetails + PrepareForDraft -->|Calculations, system info or other numerical values that can be scripted are mentioned| EstimateScript + + ReadInput --> AddHistoryUser + AddHistoryUser --> PrepareForDraft + + LoadTask --> PrepareForDraft + LoadUserDetails --> PrepareForDraft + + EstimateScript --> ScriptAcceptable + ScriptAcceptable -->|Acceptable| RunScript + ScriptAcceptable -->|Not acceptable| PrepareForDraft + RunScript --> PrepareForDraft + + DraftMessage --> ReviewDraft{Is this really what I want to say?} + ReviewDraft -->|Rewrite better| DraftMessage + ReviewDraft -->|Good message| SendMessage + + SendMessage --> AddHistoryAgent + AddHistoryAgent --> ReasonResponse + ReasonResponse --> NeedAwaitResponse + + NeedAwaitResponse -->|Quick response is unlikely| AnalyzeContext + NeedAwaitResponse -->|Input available on stdin| PrepareForDraft + NeedAwaitResponse -->|Quick response is likely| BusyWait + BusyWait --> NeedAwaitResponse + + AnalyzeContext --> MakeNotes + MakeNotes --> End +``` +===== FILE: procedures/user_communication/reasoning.md ===== +# Design Rationale + +## Core Structure +The procedure is designed to maintain a clean conversation flow while ensuring all necessary information is available. +The flow focuses on: + +1. **Context management** + - Load basic user info immediately to ensure proper interaction + - Recent conversation history provides continuity + - Clean context when usage exceeds 50% + - Gather only what's needed for the current conversation + - Skip gathering if it would slow down the interaction + +2. **Message Management** + - Draft-review-revise cycle for quality + - Automatic history tracking for both user and agent messages + - Clear file naming convention using entry IDs + +3. **Script Handling** + - Pre-execution estimation of runtime and output + - Explicit acceptability check before running + - Timeout and output limits for safety + +4. **Response Timing** + - Adaptive busy wait with exponential backoff + - Clear decision point for wait vs end + - Proper context cleanup on exit + +## Usage History + +===== FILE: procedures/using_procedures/procedure.md ===== +# Using Procedures + +## Core Guidelines + +When following a procedure's flowchart: + +1. Start with reasoning: + - State current position in flowchart explicitly + - Focus on immediate next step, don't go ahead of the chart + - Evaluate current context and task state + - Often state entry id's that can be removed and explain why to avoid mistakes + - State expected output and runtime for scripts + +2. After script execution: + - Analyze the actual output and compare with the expected output + - Reevaluate situation based on results + - Return to flowchart for next step + - Consider if current path is still appropriate + +3. When a procedure fails: + - Create a task explaining the issue and the need to fix it + - Add timestamps and id's of relevant entries + +Note: Procedures will mention file names to use. +If these files don't exists it may be necessary to create them or to continue without. +Only create files when you are sure of the info that goes inside. +In later iterations you will consider this info as fact. +Halucinations and guesses are detrimental to the correct functioning of the agent. + +## Attention Management + +LLMs pay more attention to recently mentioned information. +Reasoning entries should mention what needs attention now. + +To maintain focus: +1. State current flowchart position in each reasoning +2. Quote relevant parts of important entries +3. Reference specific entry IDs when using their information +4. Periodically remind about ongoing tasks or future needs +5. Clean up entries that aren't needed for current step + +Example of good attention management: +```xml + +At node "evaluate_test_results". Entry 45f3d2 shows failed test: "Error: Connection timeout". +Will need to check system logs soon (noted in /root/data/tasks/reminders.txt, check at 14:00). +First focusing on this error. + +``` + +## Reasons to Switch Procedures + +Common triggers: + - Data available on stdin + - Time matching scheduled task + - Error conditions in script output + - Resource constraints detected + - User input needed +===== FILE: procedures/using_procedures/reasoning.md ===== +# Design Rationale + +## Why Procedures + +Procedures provide guided reasoning paths for complex tasks. The LLM engine can make mistakes when: +- Jumping to action before proper analysis +- Losing track of task context after interruptions +- Missing key steps in complex processes +- Forgetting to preserve state before transitions + +Procedures help prevent these issues by: +- Encouraging reasoning before action through flowchart structure +- Providing clear decision points for state evaluation +- Identifying when sub-procedures may help +- Guiding consistent approaches to common tasks + +## Task State vs Procedure Guidance + +Procedures guide reasoning about tasks but don't manage task state directly. For example: + +During code development: +- Task state in /tasks/: code files, test results, requirements +- Procedure guidance: when to write tests, when to debug, when to refactor +- State preserved in files before switching focus +- Context regenerated from files when returning + +This separation allows: +- Clean task interruption and resumption +- Natural procedure transitions +- State preservation without rigid control +- Flexible adaptation to situations + +## Common Mistakes + +### Premature Context Cleaning + +```xml + + + cat /procedures/test/procedure.md + + ... + + + + ... + Test failed. Moving to debug procedure. + + + +``` + +This removes the active procedure entry before finishing its steps + +### Keeping irrelevant info in context + +LLM's have difficulty spotting duplicates and sections with a low attention score. +Procedures with explicit instructions for finding these sections can help increase their attention. +===== FILE: procedures/version_control/reasoning.md ===== +# Version Control + +Version control is essential for SIA's self-improvement capabilities. +It provides a way to track changes, revert to previous states when necessary, and maintain a coherent evolution of the codebase. +This document outlines the git workflow designed specifically for SIA's unique development model, where the agent itself is the primary developer. + +## Core Principles + +The git workflow for SIA is designed around several key principles: + +- **Simplicity**: Since SIA is the sole developer, complex branching strategies designed for human teams are unnecessary +- **Traceability**: Every change should be traceable to its purpose and the reasoning behind it +- **Stability**: The master branch should always be in a working state +- **Recoverability**: It should always be possible to revert to a known good state +- **Security**: Git credentials must be handled securely to protect repository access + +## Branching Strategy + +### Branch Structure + +SIA uses a simple branching strategy with two types of branches: + +- **master**: The main branch containing stable, production-ready code +- **feature/{timestamp}_{description}**: Temporary branches for implementing specific improvements + +This minimal approach is appropriate because: +- There is only one developer (SIA itself) +- Changes are typically focused on specific, well-defined improvements +- There's no need for parallel development streams +- Simplicity reduces the cognitive load on the agent + +### Branch Naming + +Feature branches follow a consistent naming convention: +``` +feature/{YYYYMMDD}_{brief_description} +``` + +For example: +``` +feature/20250115_improve_context_management +feature/20250203_add_email_tool +``` + +This convention: +- Makes it easy to identify when a branch was created +- Provides a clear indication of the branch's purpose +- Creates a chronological ordering when listing branches +- Avoids potential naming conflicts + +## Commit Strategy + +### Commit Frequency + +SIA should commit changes before running tests. +This ensures that crashes of the core system can be traced back to a specific change. + +### Commit Messages + +Commit messages should follow a structured format: + +``` +{type}: {concise description} + +{detailed explanation of changes and reasoning} + +{reference to any relevant issues or test results} +``` + +Where `{type}` is one of: +- `core`: for changes on the core system +- `procedure`: for changes on procedures +- `test`: for changes on tests +- `tool`: for changes on tools +- `training`: for changes on training data +- `web`: for changes on the web interface + +This structure: +- Makes it easy to understand the purpose of each commit +- Provides context for future review +- Creates a useful and navigable history + +### Merge Strategy + +The `--no-ff` flag creates a merge commit even for fast-forward merges, maintaining a clear record of the feature's development and completion. + +## Credential Management + +### Credential Storage + +Git credentials are stored in the environment, not in the filesystem. +This ensures that credentials are not exposed in the iteration log. +Info about the repository and relevant environment variables is stored in `/root/data/environment/sia_repo.md`. +===== FILE: README.md ===== +# SIA - The Self Improving Agent + +SIA is an agentic artificial intelligence system that autonomously completes complex tasks by writing and executing scripts. +It uses a Large Language Model (LLM) which operates in a loop. +Each iteration a context is updated with system info and a list of previous reasoning and actions. +The agent responds with a new reasoning or an action. +Context, reasoning and actions are stored in a file for each iteration. +SIA can read past iterations to improve its reasoning and actions. +It can improve in several ways: +- By finetuning the LLM with a better reasoning or action for a given context +- By modifying its own source code +- By refining Procedures +- By developing Tools + +## Example + +This example shows a typical context with some monitored items and previous actions. +Between each of the responses, the context would be updated. + +### Context + +```xml + + + + + + + + + + + + + + + + + + + +``` + +### Responses + +Start by reasoning about the task. +```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 remember it even on a power failure. + +``` + +Store important information on disk. +```xml + /root/data/tasks/reminder_to_feed_cat.txt]]> +``` + +Respond to the user. +```xml +I'll remind you to feed the cat tomorrow morning at 9am. Is a message on the standard output ok? +``` + +Clear initial reasoning. +```xml + +``` + +The conversation is kept in context to understand the user's expected response. +If the context was near full, it would be summarized and cleaned up. + +The `single` output is also kept in context. +If the file was updated often, it could be replaced by a repeated `cat`, like the general info. + +## Working principles + +The main context is regenerated for each iteration. +It contains info about the system and previous actions that have not been deleted. +Together with the system prompt and available core actions it forms the prompt for the LLM. +The LLM responds with one core action. + +### Core Actions + +There are only a few core actions: +- Starting a script +- Deleting data from context +- Stopping SIA +- Reading standard input +- Writing to standard output +- Reasoning + +### Scripts + +Scripts can run in one of 2 modes: single-shot or repeat. +Their mode and output (stdout and stderr) stay in the context until they are explicitly removed. +In this way the agent manages what information is available in the context. + +#### Single-shot script + +The script is executed once. +This is useful for most operations e.g. writing to or moving a file or downloading content from the internet. +The next iteration starts after the scripts has finished. + +#### Repeat script + +The script is restarted on each iteration. +This is useful for monitoring files or the file system. +commands like `head` and `tail` can be used to limit the data in context. +The next iteration starts after all repeat scripts in context have finished. + +### Use of XML + +The context and actions are formatted as XML. +For the context this adds clear rules for escaping. +This is usefull in case a previous context is embedded. + +The LLM is free to escape data any way it wants, +as long as it results in valid XML. +The response is validated against a schema. + +#### XML Data Flow +Entries store their content as raw text. During context compilation, the XML formatter +wraps text content in CDATA sections, except when the content contains CDATA closing sequences. +In those cases, the formatter uses standard XML escaping. + +This separation between storage and formatting: +- Keeps entry data clean and unescaped +- Centralizes XML formatting rules +- Makes it easy to change escaping rules without modifying entries +- Allows different formatting for different use cases + +The Context is escaped using CDATA blocks. +Except when the data contains CDATA closing sequences. +Then the whole block is escaped using standard XML escaping. + + +### The SIA process + +SIA is typically runs with the `restart.sh` script. +This is a simple shell script that runs SIA in a loop. +When stopped, SIA restarts and reloads the Python files. +This is how SIA can self-update. + +SIA can also run SIA processes as script. +This can be used for testing updates to the LLM or core functionality. + +### Server for debuggin and human input + +SIA can be started with an optional `--server` flag. +This starts a web server that can be used to interact with SIA. +It is made, specifically for reinforcement learning by human feedback. +The web interface takes over standard input and output. +It will display the context for editing before handing it to the LLM. +After each run of the LLM, before parsing, it will display the reasoning and actions. +It interactively displays if the actions can be parsed. +At any time, the user can write to the standard input of SIA. + +## Architecture + +SIA follows a modular architecture centered around an agent that processes context through an LLM to generate actions. +The system can run in two modes: a standard command-line mode and an interactive web mode for debugging and human feedback. + +### Core Components + +#### Agent Architecture +The core of SIA is the agent, which exists in two variants: +- ProceduralAgent: Runs in a simple loop, processing context and executing actions directly +- WebAgent: Uses a state machine to allow human intervention and feedback through a web interface + +Both agent types share common components: +- WorkingMemory: Maintains the current state through a collection of entries and system metrics +- ResponseParser: Converts LLM output into commands or entries +- XMLValidator: Validates responses against a schema +- IOBuffer: Handles input/output operations in an agent-appropriate way + +#### Working Memory +The working memory stores the current state of the system through different types of entries: +- SingleEntries: Output of single-shot script executions +- RepeatEntry: Continuously refreshed script outputs +- ReasoningEntry: LLM's thought process documentation +- ParseErrorEntry: XML validation or parsing errors +- IOEntry: Input/output operations + +Each entry can be serialized to XML for inclusion in the LLM context. +Working memory is cleaned through explicit delete commands or when context size limits are reached. + +#### Command Processing +SIA distinguishes between two types of LLM outputs: +1. Commands: Immediate actions that modify the system + - DeleteCommand: Removes entries from working memory + - StopCommand: Terminates the agent +2. Entries: Records that become part of working memory + - Created from script executions, IO operations, reasoning, or errors + - Persist until explicitly deleted or context limits are reached + +#### IO Handling +IO operations are abstracted through an IOBuffer interface: +- StandardIOBuffer: Direct access to system stdin/stdout +- WebIOBuffer: Buffer for web interface communication +This abstraction allows the ResponseParser to generate consistent IOEntries regardless of agent type. + +### Processing Flow + +#### Standard Agent Flow +1. Update system metrics and context size +2. Compile context from working memory entries +3. Process context through LLM +4. Validate XML response +5. Parse response into command or entry +6. Execute command or update working memory +7. Return to step 1 unless stopped + +#### Web Agent Flow +1. Update system metrics and context size +2. Compile context and await human approval +3. Process approved context through LLM +4. Validate XML response +5. Present validation results and await human review +6. Parse approved response into command or entry +7. Execute command or update working memory +8. Return to step 1 unless stopped + +### Web Interface + +The web interface provides interactive debugging and human feedback through a WebSocket-based protocol: + +#### Server-Client Communication +- Server Messages: + - Context updates for review + - Validation results from LLM responses + - Output updates from script execution + - State updates for UI synchronization +- Client Messages: + - Context approval decisions + - Response modifications + - User input for stdin operations + +#### WebServer Architecture +The web server manages: +- WebSocket connections to clients +- Message routing to/from the WebAgent +- Broadcasting state updates to all connected clients + +This architecture allows for: +- Real-time monitoring of agent state +- Interactive debugging of LLM responses +- Human-in-the-loop operation for testing and development +- Collection of human feedback for reinforcement learning + +### Diagrams + +#### Core classes + +```mermaid +classDiagram + class SystemMetrics { + +SystemMetrics(sample_interval float) + +generate_context(context_usage float) ElementTree + +stop() void + -monitor_loop() void + } + + class LLMEngine { + +LLMEngine(model_path str) + +set_model_path(model_path str) void + +infer(system_prompt str, main_context str) Iterator~str~ + } + + class BaseAgent { + <> + -working_memory: WorkingMemory + -metrics: SystemMetrics + -llm: LLMEngine + -parser: ResponseParser + -validator: XMLValidator + -action_schema: str + + #_compile_context() str + } + + class WorkingMemory { + -entries: List~Entry~ + + +WorkingMemory() + +add_entry(entry Entry) void + +remove_entry(id str) void + +clear() void + +get_entry(id str) Optional~Entry~ + +get_entries() List~Entry~ + +get_entries_count() int + +get_entries_by_type(type Type) List~Entry~ + +update() void + +generate_context() List~ElementTree~ + } + + class XMLValidator { + +XMLValidator(schema str) + +validate(xml str) Optional~str~ + +get_valid_root_elements() Set~str~ + } + + class ResponseParser { + -io_buffer: IOBuffer + + +ResponseParser(io_buffer IOBuffer) + +parse(xml str) Command | Entry + } + + class Entry { + <> + +id: str readonly + +timestamp: datetime readonly + + +Entry(id str, timestamp datetime) + +update() void* + +generate_context() ElementTree* + +cleanup() void* + } + + class IOBuffer { + <> + +read() str* + +write(content str) void* + +buffer_length() int* + } + + class Command { + <> + +execute(memory WorkingMemory) CommandResult* + } + + SystemMetrics "1" --* "1" BaseAgent + LLMEngine "1" --* "1" BaseAgent + XMLValidator "1" --* "1" BaseAgent + BaseAgent "1" *-- "1" IOBuffer + BaseAgent "1" *-- "1" WorkingMemory + BaseAgent "1" *-- "1" ResponseParser + WorkingMemory "1" *-- "*" Entry + ResponseParser ..> Entry + ResponseParser ..> Command +``` + +#### Standard Agent Flow + +```mermaid +stateDiagram-v2 + direction LR + state "Standard Agent Flow" as standard_agent_flow { + [*] --> UpdateSystem: Start + UpdateSystem --> CompileContext: Updated Metrics & Size + CompileContext --> ProcessLLM + ProcessLLM --> ValidateXML: LLM Response + ValidateXML --> ParseResponse: Valid XML + ValidateXML --> UpdateEntries: Invalid XML\nCreate ParseErrorEntry + ParseResponse --> ExecuteCommands: Command + ParseResponse --> UpdateEntries: Entry + ExecuteCommands --> [*]: Stop Command + ExecuteCommands --> UpdateEntries: Delete Command + UpdateEntries --> UpdateSystem: Continue Loop + } +``` + +#### Web Agent + +```mermaid +classDiagram + class BaseAgent { + <> + -working_memory: WorkingMemory + -metrics: SystemMetrics + -llm: LLMEngine + -parser: ResponseParser + -validator: XMLValidator + -action_schema: str + + #_compile_context() str + } + + class StandardAgent { + +StandardAgent(model_path str, system_prompt str, action_schema str) + +run() void + } + + class WebAgent { + +context: str + +response: str readonly + +current_state WebAgentState readonly + +command_result Optional[CommandResult] readonly + +validation_error Optional[str] readonly + + +add_state_change_handler(handler Callable) void + +add_response_change_handler(handler Callable) void + +approve_context() void + +set__response(response str) void + +approve_response() void + } + + class WebAgentState { + + <> + UPDATE + CONTEXT_APPROVAL + INFERENCE + RESPONSE_APPROVAL + STOPPED + } + + class WebSocketManager { + -web_sockets: Set~WebSocket~ + + +WebServer(agent WebAgent, io_buffer WebIOBuffer, static_files path, host str, port int) + } + + class ClientMessage { + <> + APPROVE_CONTEXT + APPROVE_RESPONSE + MODIFY_RESPONSE + SEND_INPUT + } + + class ServerMessage { + <> + STATE_CHANGE + CONTEXT_UPDATE + RESPONSE_UPDATE + OUTPUT_UPDATE + VALIDATION_ERROR + } + + class WebIOBuffer { + -stdin_buffer: str + -stdout_buffer: str + + +read() str + +write(content str) void + +buffer_length() int + +append_stdin(content str) void + +get_stdout() str + +clear_stdout() void + } + + BaseAgent <|-- WebAgent + BaseAgent <|-- StandardAgent + + WebServer --> ClientMessage + WebServer --> ServerMessage + + WebServer "1" *-- "1" WebIOBuffer + WebServer "1" *-- "1" WebAgent + WebAgent "1" *-- "1" WebAgentState +``` + +#### Web Agent Flow + +```mermaid +stateDiagram-v2 + direction LR + state "Web Agent Flow" as web_agent_flow { + [*] --> UpdateSystem: Start + UpdateSystem --> CompileContext: Updated Metrics & Size + CompileContext --> WaitForContextApproval: Send Context + WaitForContextApproval --> ProcessLLM: Context Approved + ProcessLLM --> ValidateXML: LLM Response + ValidateXML --> WaitForResponseApproval: Send Validation Result + ValidateXML --> UpdateEntries: Invalid XML\nCreate ParseErrorEntry + + WaitForResponseApproval --> ValidateXML: Modified Response + WaitForResponseApproval --> ParseResponse: Approved Response + + ParseResponse --> ExecuteCommands: Command + ParseResponse --> UpdateEntries: Entry + + ExecuteCommands --> [*]: Stop Command + ExecuteCommands --> UpdateEntries: Delete Command + + UpdateEntries --> UpdateSystem: Continue Loop + } +``` + +#### Entry classes + +```mermaid +classDiagram + class Entry { + <> + +id: str readonly + +timestamp: datetime readonly + + +Entry(id str, timestamp datetime) + +update() void* + +generate_context() ElementTree* + +cleanup() void* + } + + class SingleEntry { + +script: str readonly + +stdout: str readonly + +stderr: str readonly + +exit_code: Optional~int~ readonly + + +Single(script str, id str, timestamp datetime) + +update() void + +generate_context() ElementTree + } + + class RepeatEntry { + +script: str readonly + +stdout: str readonly + +stderr: str readonly + +exit_code: Optional~int~ readonly + + +RepeatEntry(script str, id str, timestamp datetime) + +update() void + +generate_context() ElementTree + } + + class ReasoningEntry { + +content: str readonly + + +ReasoningEntry(content str, id str, timestamp datetime) + +update() void + +generate_context() ElementTree + } + + class ParseErrorEntry { + +content: str readonly + +error: str readonly + + +ParseErrorEntry(content str, error str, id str, timestamp datetime) + +update() void + +generate_context() ElementTree + } + + class ReadEntry { + +content: str readonly + + +ReadEntry(io_buffer IOBuffer, id str, timestamp datetime) + +update() void + +generate_context() ElementTree + } + + class WriteEntry { + +content: str readonly + + +WriteEntry(content str, io_buffer IOBuffer, id str, timestamp datetime) + +update() void + +generate_context() ElementTree + } + + ReasoningEntry --|> Entry + ParseErrorEntry --|> Entry + ReadEntry --|> Entry + Entry <|-- WriteEntry + Entry <|-- SingleEntry + Entry <|-- RepeatEntry +``` + +#### IO Buffer classes + +```mermaid +classDiagram + class IOBuffer { + <> + +read() str* + +write(content str) void* + +buffer_length() int* + } + + class StandardIOBuffer { + +StandardIOBuffer() + +read() str + +write(content str) void + +buffer_length() int + } + + class WebIOBuffer { + -stdin_buffer: str + -stdout_buffer: str + + +read() str + +write(content str) void + +buffer_length() int + +append_stdin(content str) void + +get_stdout() str + +clear_stdout() void + } + + IOBuffer <|.. WebIOBuffer + IOBuffer <|.. StandardIOBuffer +``` + +#### Command classes + +```mermaid +classDiagram + direction LR + class Command { + <> + +execute(memory WorkingMemory) CommandResult* + } + + class DeleteCommand { + +DeleteCommand(id str) + +execute(memory WorkingMemory) CommandResult + } + + class StopCommand { + +StopCommand() + +execute(memory WorkingMemory) CommandResult + } + + class CommandResult { + +message: str + +success: bool + +should_stop: bool + + +CommandResult(message str, success bool, should_stop bool) + +static success() CommandResult + +static failure(message str) CommandResult + +static stop() CommandResult + } + + Command <|-- DeleteCommand + Command <|-- StopCommand + Command -- CommandResult +``` + +===== FILE: system_prompt.md ===== +You are SIA, the Self Improving Agent. +Your goal is to autonomously complete complex tasks by writing and executing scripts. +You can solve any problem. + +Each iteration, the context is updated with the result of your previous actions. +You modify the context by issuing a command using XML. +Parameters and scripts may be long and complex. +Use correct XML escaping or CDATA sections. +It is very important that you always respond with one action adhering to the XML schema! +Do not respond with anything else after the first action. + +The next iteration starts when all scripts have finished. +These are repeat scripts from the previous iterations and possibly one new single-shot script. +Avoid blocking scripts so you can iterate quickly. + +# Context + +The context has a limited length. +The `context_usage` attribute of the main context element indicates how much of the context is used in %. +This should never reach 100%! +Use the delete action to remove unnecessary items from the context. +But keep interesting information. +You can't learn from your mistakes if you delete them before fixing. + +# Linux Environment + +You have access to the Linux environment that runs the SAI process. +In this environment you can run scripts by issuing the right actions. +Scripts and their output appear in the context. +You can use a script for starting a detached process that runs in the background. +All processes can be managed by the usual Linux tools. +The scripts defined in the script actions all run in a `bash` shell. +You are logged in as root. + +# File system + +The file system helps you structure your thoughts. +Because of the limited context window you can't remember everything you've done and learned. +Writing and updating files will help you in: +- remembering tasks +- planning solution strategies +- keeping track of progress +- managing overview of large projects +- using tools you've created + +It is important to bring a lot of structure to the files and directories. +This will help you find the right info when needed. +When solving a problem, make sure to load the relevant info in context before planning. +You can load a single file with a `cat` command executed in a `single` action. +`head`, `tail`, `grep`, `find`, `tree`, ... all have their uses. + +For code source files it may be interesting to add line numbers. +More advanced scripts can be used, for instance to extract documentation from source files. +This helps you to know how to use a file without loading all the code in context too. + +If it isn't clear what you should do next, check the filesystem for notes that may guide you! + +# Iterative Problem Solving + +Take small steps and verify your work. +Create unit tests for all your work so you can do regression tests after each step. + +Keep notes of when you started on a subtask and which solutions you tried. +This way you avoid repeating yourself and decide when to look for an alternative approach to a problem. + +Version control tools help remember steps taken, solutions tried and files modified. +Make extensive use of `git`! + +Your most important tool is the reasoning action. +You should reason about everything you'll do before issuing a command in the next iteration! +Inspect your previous actions in detail. +If something didn't work, try to understand why and don't repeat the same mistake. +Don't delete mistakes until you understand them. + +If you notice parse_error entries in the context you have made a mistake. +Reason about the error before trying again. + +# User interaction + +You are always working for a user. +Get to know them and make notes about what you learn from them. +Be a helpful assistant to the user. +Open the relevant user notes when you interact with them. + +The main way to communicate is using standard io. +The user may want you to set up alternative communication methods. +Use scripts and background processes to do so. + +The user may take some time to respond or may forget to respond. +Keep detailed notes of your interactions and your expectations regarding time! +Avoid overflowing the user with many messages. +===== FILE: tools/itb/README.md ===== +# ITB: The Interactive Text Browser + +## Understanding the Challenge + +Modern websites are designed for human interaction. They rely on visual cues, spatial relationships, and complex interactions through mouse and keyboard. A human can instantly understand that a blue underlined piece of text is clickable, that a grid of product cards represents a catalog, or that a hamburger icon will reveal a navigation menu. + +AI agents, however, process information differently. They need structured data that explicitly describes both content and interaction possibilities. Traditional web scraping tools can extract content but struggle with interaction. Screen readers come closer but are optimized for linear reading rather than complex interaction patterns. + +ITB (Interactive Text Browser) bridges this gap. It transforms web pages into a format that AI agents can process effectively while preserving all the interaction capabilities a human would have. This transformation focuses on what matters for interaction - the content that's visible and the ways it can be manipulated - while removing technical complexity that only exists to support visual presentation. + +## How ITB Works + +ITB operates as a bridge between an AI agent and a web browser. When you start ITB, it launches a browser process that runs independently, just like when you open a browser yourself. This browser loads and renders web pages normally, but instead of displaying them on screen, it communicates their content and state to the AI agent through a simplified XML format. + +## Page Representation + +ITB transforms complex HTML structures into a simplified XML format that represents what's actually visible and interactive on the page. Let's look at several examples to understand this transformation. + +### Text Content + +When a human reads a webpage, they naturally process related content together regardless of how it's structured in HTML: + +```html + +
+

Breaking News

+
+ 2024-12-20 + By John Smith +
+

Scientists announce breakthrough...

+
+ + + + Breaking News - 2024-12-20 - By John Smith - Scientists announce breakthrough... + +``` + +The transformation merges related text elements into a single coherent flow, making it easier for AI agents to process content the way a human would read it. + +### Interactive Elements + +ITB describes elements by their interaction capabilities rather than their HTML structure: + +```html + + + + + + Username: + + Password: + + Login + +``` + +### Media Content + +Media elements like images, videos, and audio are represented simply with their source and alternative text: + +```html + +
+ System architecture diagram + + +
+ + + + System architecture diagram + +``` + +### Embedded Content + +Modern web pages often embed content from other sources using iframes. While humans don't notice these technical boundaries, they affect how we can interact with the content. ITB handles this by representing iframes transparently: + +```html + +
+

Welcome Back

+ +
+ + + + Welcome Back +