doc: audit README.mdHEADmain

1 files changed, 35 insertions, 31 deletions

diff --git a/README.md b/README.md
index 0b39f0a..385af92 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,39 @@
-# 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.
+# Coding Agent
+
+I use this as a wrapper for agentic tasks around the [Local LLM Gateway](https://www.aalto.fi/en/services/local-llm-gateway) provided by Aalto University.
+The wrapper should be general enough to work with any OpenAI compliant API endpoint, though.
+
+It seems that the API endpoint provided by Aalto does not support server-side chat history or chat history compaction or agentic tools, so the API is used just as a dumb endpoint for getting textual LLM responses.
 
 ## 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.
-- **Context Management**: Estimates the token count of the conversation and automatically squashes (summarizes) older history when it approaches the model's context size limit, keeping the most recent messages intact.
-- **SOCKS5 Proxy Support**: API queries (and `webgrep` fetches) can be routed through a SOCKS5 proxy.
-- **Logging**: Logs interactions to `thoughts.log` for debugging and analysis.
+The agent can call the following tools, given it has the required permissions.
+- `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.
+
+If you want to add actions, just create an instance of class `Action` as in `actions.py`, and then include it in the action list passed to `query_agent` in the main function in `llm.py`.
+
+The agent manages its context size somewhat automatically, though this functionality could be refined.
+
+There is support for routing the queries through a SOCKS5 proxy.
+
 
 ## Requirements
 
 - Python 3.x
 - `openai` Python library
-- `tldr` CLI installed on the system
+- `httpx2` Python library
+- `socksio` Python library, if you want to proxy your connections to the API endpoint
+- `tldr` if you want the agent to be able to view `tldr` documentations
+- `pandoc` if you want the agent to be able to query websites
+- `mypy` if you want the agent to be able to run static type checking
 - An API key for the Aalto LLM Gateway (or a compatible OpenAI-style API)
-- `socksio` Python package (only needed when using a SOCKS5 proxy)
 
 ## Setup
 
@@ -46,7 +55,7 @@ This project implements a simple autonomous coding agent that can interact with
    python3 llm.py
    ```
 
-### CLI Arguments
+### Configuration
 
 - `--workdir PATH`: Specify the directory the agent has access to. If not provided, it defaults to the current working directory.
   ```bash
@@ -64,24 +73,19 @@ This project implements a simple autonomous coding agent that can interact with
   ```
   Use `socks5h://` as the scheme to also resolve DNS hostnames through the proxy. This requires the `socksio` package to be installed in the virtualenv (`pip install socksio`).
 
-## 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.
-3. **History Squashing**: When the estimated token count of the conversation exceeds a threshold of the model's context size, the older history is summarized by the LLM into a compact "Previous history summary" message, while the most recent `--min-history` messages are preserved.
 
 ## 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.
+To prevent unauthorized file system access, all file operations are restricted to the specified `--workdir` and its subdirectories. This does obviously not work for arbitrary shell commands.
+
+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 before execution (`Perform [action]? [y/N]`). The trust levels are provided below, but you can edit them yourself quite easily in llm.py.
 
-### Trust Level Mappings
 - `ls`, `read`, `tldr`, `mypy`: Level 0
 - `webgrep`: Level 1
 - `write`: Level 2
 - `shell`: Level 3
+
+
+## Use of AI
+
+I have used this agent heavily in developing this agent, but I have manually maintained code quality and personal style.