Skip to content

Commit

Permalink
new use cases added for the assistant.
Browse files Browse the repository at this point in the history
  • Loading branch information
@kedarchandrayan
kedarchandrayan committed Jul 9, 2024
1 parent 4d7c1a2 commit 0617783
Showing 1 changed file with 84 additions and 185 deletions.
269 changes: 84 additions & 185 deletions docs/How to Write Agent Pseudocode.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ An agent in the Sirji framework is a modular AI component designed to perform sp

Think of the custom agent as a new team member. You need to provide it with your understanding of the existing architecture, design patterns, and code conventions used in the repository where you plan to use the custom agent to solve a problem. This understanding is conveyed through the agent's pseudocode.

This guide will explain the terminology involved, provide example pseudocode snippets with their corresponding messages generated according to the [messaging protocol](./Messaging%20Protocol.md), and outline best practices for writing pseudocode.
This guide will explain the terminology involved, provide example pseudocode snippets for various use cases, and outline best practices for writing pseudocode.

[Here](../sirji/vscode-extension/src/defaults/agents/NODE_JS_CREATE_API_PLANNER.yml) is an example of an agent pseudocode.

Expand All @@ -16,268 +16,167 @@ This guide will explain the terminology involved, provide example pseudocode sni

- **SIRJI_USER**: The developer using Sirji.
- **Agent**: A modular AI component in the Sirji framework that performs a specific task based on custom pseudocode.
- **Sub Agent**: An agent can optionally invoke other agents for performing a sub-task. These other agents are called sub-agents.
- **Recipe**: A file listing prescribed tasks for solving a particular problem, indicating which agent should perform each task.
- **Project Folder**: The primary directory for all user-specific project files, including code files, documentation, and other relevant resources.
- **Agent Output Folder**: The designated folder for storing the results and data outputs generated by the agents.

## Agent YML
The agent pseudocode is written in a YML file. [Here](../sirji/vscode-extension/src/defaults/agents/NODE_JS_CREATE_API_PLANNER.yml) is an example agent YML file.

This YML file has these mandatory fields:
- **id**: Uppercased unique identified for the agent.
- **name**: Human readable name of the agent.
- **llm**: This key maps to an object with these keys:
- **provider**: Specifies which company's model will be used for inference. Possible values: openai, anthropic and deepseek.
- **model**: Specifies the model to be used for inference. Possible values: gpt-4o, deepseek-coder, etc.
- **sub_agents**: Optional list of sub_agent objects each having these keys:
- **id**: ID of the sub agent.
- **skills**: Array of skill objects, each having these keys:
- **skill**: Specifies the skill of the agent.
- **pseudo_code**: Specifies the point-wise pseudo-code which the agent follows to work on the task.

## Pseudocode Use Cases

In this section, we will go over different use cases encountered while writing pseudocode, providing example pseudocode snippets and their corresponding messages generated by LLM, as per the Sirji messaging protocol.
In this section, we will go over different use cases encountered while writing pseudocode, providing example pseudocode snippets.

### Interact with User

### Use Case 1: Ask SIRJI_USER a Question
#### Ask question to User

Example pseudocode snippet:
Example pseudocode step:

```
Ask SIRJI_USER to provide the route of the new API and the file path of the sequence diagram.
Ask SIRJI_USER to provide {{Write the question here}}.
```

Corresponding message generated by LLM:
### RAG Assistant

You can create a RAG assistant to facilitate in embeddings powered search over the project files.

#### Creare Assistant

In a single Sirji run, only one RAG assistant can be created and the same gets re-used over the entire run.

Example pseudocode step:

```
***
FROM: RECIPE_SELECTOR
TO: SIRJI_USER
ACTION: QUESTION
SUMMARY: Empty
BODY:
Please provide the route of the new API and the file path of the sequence diagram.
***
Create an assistant with the following instructions:
{{Write the instructions here}}
```

### Use Case 2: Create Project File
#### Syncing Project Files with the Assistant

Example pseudocode snippet:
Example pseudocode step:

```
Under the services folder in the project, create a service file for the API, following the conventions used in the inspiration service file.
Sync project files with the assistant.
```

Corresponding message generated by LLM:
#### Querying the Assistant

Example pseudocode step:

```
***
FROM: IMPLEMENTATION_GUIDE_CODE_WRITER
TO: EXECUTOR
ACTION: CREATE_PROJECT_FILE
SUMMARY: Creating a new service file to handle the business logic for updating a todo.
BODY:
File path: src/services/updateTodoService.js
---
const todoStorage = require('../storage/todoStorage');
const updateTodo = (id, data) => {
return todoStorage.updateTodo(id, data);
};
module.exports = updateTodo;
***
Infer from the assistant with the following query:
{{Write the query here}}
```

### Use Case 3: Read Project Files
### Project folder Operation

#### Read Files

Example pseudocode snippet:
Example pseudocode step:

```
Using the project folder structure, determine the file paths for the following core codebase files and read them for the specified purposes:
- OpenAPI file: Understand the input parameter and response specifications for the API.
- Sequence diagram relevant to the Target API: Understand the logic to be implemented.
```

Corresponding message generated by LLM:
#### Create a File

Example pseudocode step:

```
***
FROM: NODE_JS_CREATE_API_PLANNER
TO: EXECUTOR
ACTION: READ_PROJECT_FILES
SUMMARY: Reading core codebase files to understand the conventions and requirements for the new API route.
BODY:
File paths: ["docs/openapi.yaml", "docs/sequenceDiagrams/updateTodo.mermaid"]
***
Under the services folder in the project, create a service file for the API, following the conventions used in the inspiration service file.
```

### Use Case 4: Make Edits to File
#### Update a File

Example pseudocode snippet:
Example pseudocode step:

```
Make the necessary changes to the storage file.
Change the version in setup.py to 3.0.0.
```

Corresponding message generated by LLM:

```
***
FROM: IMPLEMENTATION_GUIDE_CODE_WRITER
TO: EXECUTOR
ACTION: INSERT_BELOW
SUMMARY: Adding the new method `updateTodo` to the storage management file.
BODY:
FILE_PATH:
src/storage/todoStorage.js
---
NEW_CHANGES:
const updateTodo = (id, data) => {
const todo = todos.find(t => t.id === id);
if (!todo) return null;
todo.title = data.title !== undefined ? data.title : todo.title;
todo.description = data.description !== undefined ? data.description : todo.description;
todo.completed = data.completed !== undefined ? data.completed : todo.completed;
return todo;
};
---
INSERT_BELOW:
const addTodo = (data) => {
const todo = { id: uuidv4(), title: data.title, description: data.description, completed: false, created_at: new Date() };
todos.push(todo);
return todo;
};
---
***
```
### Agent Output Folder Operations

### Use Case 5: Writing File to Agent Output Folder
#### Read a File

Example pseudocode snippet:
Example pseudocode step:

```
Store the problem statement (mentioning your understanding) in the Agent Output Folder.
Read the problem statement from the Agent Output Folder.
```

Corresponding message generated by LLM:
The pseudo code snippet gets converted into the following message:
#### Create a File

Example pseudocode step:

```
***
FROM: NODE_JS_CREATE_API_CODER
TO: EXECUTOR
ACTION: STORE_IN_AGENT_OUTPUT
SUMMARY: Storing the problem statement file for the new API route and sequence diagram.
BODY:
File path: NODE_JS_CREATE_API_CODER/problem_statement.json
---
File content: {
"route": "PUT /todos/{id}",
"sequence_diagram": "docs/sequenceDiagrams/updateTodo.mermaid"
}
---
File content description: Problem statement for creating a new API route and sequence diagram.
***
Store the problem statement in the Agent Output Folder.
```

### Use Case 6: Read from Agent Output Folder
### Invoke Other Agents

Example pseudocode snippet:
An agent can be invoked in a fresh session or an existing session. If invoked in an existing session the agent continues on the earlier conversation which it already had with the LLM. When invoked in a fresh session, a fresh LLM conversation is started.

```
Read the problem statement from the Agent Output Folder.
```
#### Fresh Session

Corresponding message generated by LLM:
Example pseudocode step:

```
***
FROM: NODE_JS_CREATE_API_PLANNER
TO: EXECUTOR
ACTION: READ_AGENT_OUTPUT_FILES
SUMMARY: Reading the problem statement to identify the Target API route and sequence diagram file path.
BODY:
File paths: ["NODE_JS_CREATE_API_CODER/problem_statement.json"]
***
Invoke agent NODE_JS_CREATE_API_PLANNER to {{write the purpose of invocation here}}.
```

### Use Case 7: Write to Scratchpad
#### Existing Session

Example pseudocode snippet:
Example pseudocode step:

```
Understand the code conventions followed in the existing code which you have read and store your understanding in the scratchpad.
Invoke agent NODE_JS_CREATE_API_PLANNER in the existing session to {{write the purpose of invocation here}}.
```

Corresponding message generated by LLM:
### Terminal Operations

```
***
FROM: NODE_JS_CREATE_API_PLANNER
TO: EXECUTOR
ACTION: STORE_IN_SCRATCH_PAD
SUMMARY: Storing understanding of the code conventions and requirements in the scratchpad.
BODY:
Understanding of the code conventions and requirements:
1. **OpenAPI Specification**:
- The `PUT /todos/{id}` route is defined to update a todo by ID.
- It requires a path parameter `id` (string) and a request body containing `title`, `description`, and `completed` fields.
- The response is a 200 OK with the updated todo object or a 404 if the todo is not found.
2. **Sequence Diagram**:
- The sequence diagram outlines the flow for updating a todo.
- The client sends a PUT request to the server with the todo ID and data.
- The server calls the service layer's `updateTodo` method.
- The service layer calls the storage layer's `updateTodo` method.
- The storage layer returns the updated todo to the service layer.
- The service layer returns the updated todo to the server.
- The server responds to the client with the updated todo.
3. **Route File (src/routes/todoRoutes.js)**:
- The route file uses Express.js to define routes.
- Existing routes include `GET /todos`, `GET /todos/{id}`, `POST /todos`, and `DELETE /todos/{id}`.
- Each route handler calls a corresponding service method and sends the response to the client.
4. **Storage File (src/storage/todoStorage.js)**:
- The storage file manages the in-memory storage of todos.
- It includes methods for getting all todos, getting a todo by ID, adding a todo, and deleting a todo.
- The `updateTodo` method needs to be implemented to update a todo by ID.
5. **Service File (src/services/getTodoByIdService.js)**:
- The service file follows a simple pattern of requiring the storage module and exporting a function that calls a storage method.
- The `updateTodoService` file will follow a similar pattern, calling the `updateTodo` method from the storage module.
6. **Main Index File (src/server.js)**:
- The `package.json` file indicates that the main index file is `src/server.js`.
- This file acts as the primary routing file that includes all other sub-routers and defines top-level routes.
7. **Inspiration Service File (src/services/getTodoByIdService.js)**:
- The service file for getting a todo by ID is straightforward, requiring the storage module and exporting a function that calls a storage method.
- The new service file for updating a todo will follow a similar pattern.
***
```

### Use Case 8: Invoke Other Agents
#### Run a Command

Example pseudocode snippet:
Example pseudocode step:

```
Invoke agent NODE_JS_CREATE_API_PLANNER to create a comprehensive implementation guide for the new API to be implemented.
Run `npm install`
```

Corresponding message generated by LLM:
#### Start a Server Process

Example pseudocode step:

```
***
FROM: NODE_JS_CREATE_API_CODER
TO: NODE_JS_CREATE_API_PLANNER
ACTION: INVOKE_AGENT
SUMMARY: Invoking the Node.js API Planner to create an implementation guide for the new API.
BODY:
Create a comprehensive implementation guide for the new API route "PUT /todos/{id}" using the sequence diagram at "docs/sequenceDiagrams/updateTodo.mermaid".
***
Start the server using command: `npm start`
```

TODO: add examples for INVOKE_AGENT_EXISTING_SESSION
### Misc

### Use Case 9: Run Commands
#### Write to Scratchpad

TODO: add examples for EXECUTE_COMMAND
Scratchpad is a personal note taking place for the agent. You can ask the agent to store it's understanding, etc over here.

### Use Case 10: Run Server
Example pseudocode step:

TODO: add examples for RUN_SERVER
```
Understand the code conventions followed in the existing code which you have read and store your understanding in the scratchpad.
```

## Best Practices

Expand Down

0 comments on commit 0617783

Please sign in to comment.