doc: LLM-generated README

1 files changed, 70 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9c30af7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# LLM Autonomous Coding Agent
+
+This project implements a simple autonomous coding agent that can interact with the local file system and the web to help with programming tasks. It leverages a Large Language Model (LLM) via an OpenAI-compatible API to reason about tasks, execute operations, and iteratively work towards a solution.
+
+## Features
+
+- **Autonomous Execution**: The agent can decide which actions to take based on the current state of the project.
+- **Toolbox**: Supports the following actions:
+  - `ls`: List files at a specified path.
+  - `read`: Read the contents of a file.
+  - `write`: Write content to a file.
+  - `tldr`: Read simplified man pages (`tldr`) for a program.
+  - `shell`: Execute a shell command.
+  - `mypy`: Run static type checking on a Python file.
+  - `webgrep`: Search for keywords within the markdownified content of a URL.
+- **Reasoning Loop**: Uses a recursive loop to process tasks, analyze results, and determine the next step until a final response is reached.
+- **Logging**: Logs interactions to `thoughts.log` for debugging and analysis.
+
+## Requirements
+
+- Python 3.x
+- `openai` Python library
+- `tldr` CLI installed on the system
+- An API key for the Aalto LLM Gateway (or a compatible OpenAI-style API)
+
+## Setup
+
+1. **Set the API Key**:
+   The agent expects the API key to be stored in an environment variable:
+   ```bash
+   export LLM_API_KEY="your_api_key_here"
+   ```
+
+2. **Run the Agent**:
+   Execute the script using Python:
+   ```bash
+   python3 llm.py
+   ```
+
+### CLI Arguments
+
+- `--workdir PATH`: Specify the directory the agent has access to. If not provided, it defaults to the current working directory.
+  ```bash
+  python3 llm.py --workdir /path/to/your/project
+  ```
+- `--endpoint URL`: The API endpoint for the LLM (defaults to `https://llm-gateway.k8s.aalto.fi/api/v1`).
+- `--key KEY`: The API key for the LLM endpoint (defaults to `LLM_API_KEY` environment variable).
+- `--model MODEL`: The model name to use (defaults to `RedHatAI/gemma-4-31B-it-FP8-Dynamic`).
+- `--trust-level LEVEL`: The trust level of the agent (defaults to 2). Determines which actions require manual approval.
+
+## How it Works
+
+1. **System Prompt**: The agent is initialized with a system prompt defining its identity as a coding agent and providing the available tools.
+2. **Action-Observation Loop**: 
+   - The user provides a task.
+   - The agent analyzes the task and returns a JSON action.
+   - The script executes the action (interacting with the file system, shell, or web).
+   - The result of the action is fed back into the LLM as a new observation.
+   - This repeats until the agent provides a final natural language response.
+
+## Security and Permissions
+
+- **Path Restriction**: To prevent unauthorized file system access, all file operations are restricted to the specified `--workdir` (or CWD) and its subdirectories.
+- **Trust Level System**: Actions are assigned trust levels. If an action's required trust level exceeds the agent's current trust level, the system will explicitly prompt the user for permission (`Perform [action]? [y/N]`) before execution. This provides a safety layer for high-risk operations like `write` or `shell` commands.
+
+### Trust Level Mappings
+- `ls`, `read`, `tldr`, `mypy`: Level 0
+- `webgrep`: Level 1
+- `write`: Level 2
+- `shell`: Level 3