From 89e923679edc1cd3e06cfd7cfac156f8708f27d6 Mon Sep 17 00:00:00 2001
From: Robert Brennan <accounts@rbren.io>
Date: Wed, 27 Mar 2024 22:03:55 -0400
Subject: [PATCH] API schema draft (#189)

* add api schema draft

* Update README.md

* Update opendevin/server/README.md
---
 opendevin/server/README.md | 57 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/opendevin/server/README.md b/opendevin/server/README.md
index a6ac4459ab..07f4bdc705 100644
--- a/opendevin/server/README.md
+++ b/opendevin/server/README.md
@@ -40,3 +40,60 @@ OPENAI_API_KEY=sk-... # Your OpenAI API Key
 LLM_MODEL=gpt-4-0125-preview # Default model for the agent to use
 WORKSPACE_DIR=/path/to/your/workspace # Default path to model's workspace
 ```
+
+## API Schema
+There are two types of messages that can be sent to, or recieved from, the server:
+* Actions
+* Observations
+
+### Actions
+An action has three parts:
+* `action`: The action to be taken
+* `args`: The arguments for the action
+* `message`: A friendly message that can be put in the chat log
+
+There are several kinds of actions. Their arguments are listed below.
+This list may grow over time.
+* `initialize` - initializes the agent. Only sent by client.
+  * `model` - the name of the model to use
+  * `directory` - the path to the workspace
+  * `agent_cls` - the class of the agent to use
+* `start` - starts a new development task. Only sent by the client.
+  * `task` - the task to start
+* `read` - reads the contents of a file.
+  * `path` - the path of the file to read
+* `write` - writes the contents to a file.
+  * `path` - the path of the file to write
+  * `contents` - the contents to write to the file
+* `run` - runs a command.
+  * `command` - the command to run
+  * `background` - if true, run the command in the background
+* `kill` - kills a background command
+  * `id` - the ID of the background command to kill
+* `browse` - opens a web page.
+  * `url` - the URL to open
+* `recall` - searches long-term memory
+  * `query` - the query to search for
+* `think` - Allows the agent to make a plan, set a goal, or record thoughts
+  * `thought` - the thought to record
+* `finish` - agent signals that the task is completed
+
+### Observations
+An observation has four parts:
+* `observation`: The observation type
+* `content`: A string representing the observed data
+* `extras`: additional structured data
+* `message`: A friendly message that can be put in the chat log
+
+There are several kinds of observations. Their extras are listed below.
+This list may grow over time.
+* `read` - the contents of a file
+  * `path` - the path of the file read
+* `browse` - the HTML contents of a url
+  * `url` - the URL opened
+* `run` - the output of a command
+  * `command` - the command run
+  * `exit_code` - the exit code of the command
+* `recall` - the result of a search
+  * `query` - the query searched for
+* `chat` - a message from the user