> # New Readme Evo.Ninja 2

# evo.ninja


[Discord](https://discord.gg/X7ystzGcf5) | [Website](https://evo.ninja)
Give this repo a star if you use it! :star:

## Welcome to evo.ninja
TODO: UPDATE THIS SECTION

**The AI that evolves in real-time.**

Evo executes scripts to achieve a goal. It is capable of using fuzzy search to find and execute any script in its library. Scripts are namespaced JavaScript functions with typed arguments and a description.

Before you can run evo.ninja, ensure you have Node.js and yarn installed.

## Usecases

- Retrieve relevant data and links from https://en.wikipedia.org/wiki/LK-99
- Develop simple click counter program with a GUI
- Create a TicTacToe game in the CLI with Python
- Write an article on french toast
- More TODO?
- Wrangle with CSV data

# Overview

-------

## Agent Functions vs Agent Scripts

As an agent that's able to execute on any task, Evo uses a set of tools which is comprised of more than 60 scripts and functions. Below is a brief disctiction between these two tool categories:

### Functions
Functions make the reference to [ChatGPT Functions](https://openai.com/blog/function-calling-and-other-api-updates) which allow the LLM to execute arbitrary logic.

These functions can return a fixed value (like the constant for the speed of light) or a variable respose (like the time of the day).
Functions can also take arguments, like when you need to query a specific `url`, all Evo needs to do is to call the [web scrape text function](https://github.com/polywrap/evo.ninja/blob/dev/packages/agents/src/functions/ScrapeText.ts) and pass that `url` as an argument.

All functions can be found here LINK

### Scripts
Scripts can be invoked by specific functions. These scripts have been pre-built by the EvoNinja Team.

Scripts are composed of a JSON schema and its javascript implementation. For example:

math.divide.json

{
  "name": "math.divide",
  "description": "This script divides two numbers and returns the result.",
  "arguments": "{ numerator: number, denominator: number }",
  "code": "./math.divide.js"
}

math.divide.js

if (denominator === 0) {
  throw new Error('Cannot divide by zero');
}
return numerator / denominator;

Other scripts include Adding a column to a CSV, Reading a File, Scraping the links of a website an more. A full list of prebuilt scripts can be found [Here](https://github.com/polywrap/evo.ninja/tree/dev/scripts)

----

## Variables and summarization
Evo creates new variables to handle long responses from the functions it executes. So if a response from a function call is too big to fit the context window of the model (based on the number of the tokens) the data of the response is stored locally within that new variable, and separately from the chat history so it doesnt overflow the context window.

Once these variables are created, a shorter preview version of the variable can be injected as necessary to other function's prompts to achieve the goal at hand, while still having the full variable available for complex operations.

Responses that are small enough to fit the context window are not stored as variables and processed directly.

For example, if we query the content of a website, and the response is too long to fix the context window of the model, the variable will be created. When that content is needed again, Evo will pick a preview of the variable and with that generate a new response.

-----

## RAG (Retrieval Augmented Generation)

RAG is a 3 step process where the agent finds information, improves it, and then passes that to the LLM to generate a response with that improved context. This is a very useful technique that is used across Evo, for example:

### Websites data
When Evo needs to query a website, the data is first queried and then filtered, before feeding it to the LLM, essentially utilizing the RAG technique.

### Contextualized chat
Evo's Chat History is dynamic. The most Relevant information is retrieved/filtered on each step thanks to the RAG technique. This allows Evo to stay closer to a given goal and to have the ability to adapt its strategy to answer a wide arrange of topics.

### Chameleon Agent

The Chameleon is a special kind of agent that adapts to a given task by picking for it's available list of "Personas".

The way this works, is by always prepending the most relevant agent persona at the begining of the chat history. This change in architecture has proven to allow Evo to resolve tasks more quickly and also helped with keeping the user's goal in context.

---

## Multiple Agents

| Agent | Description |
|---------------------------------------------------------------------|-------------|
|  🥷 [Evo](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/Evo) | An expert assistant designed to achieve user goals. It has multiple agents it can delegate tasks to by calling the relevant "delegate" functions. Each agent has its own specialization and capabilities. |
| 🦎 [Chameleon](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/Chameleon) | An expert evolving assistant that achieves user goals. Capable of accomplishing a multitude of tasks using functions that use external tools (like internet, file system, etc.). |
| #️⃣ [Csv Analyst](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/CsvAnalyst) | An expert analyzing and modifying CSV datasets. |
| 💻 [Developer](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/Developer) | An expert developer assistant that excels at coding related tasks with access to the file system. It plans and writes clean and effective code to files. |
| 🎖️ [Goal Verifier](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/GoalVerifier) | Verifies that the assistant has correctly achieved the users' goal by reading the files. When the agent can't achieve the goal it calls the OnGoalFailed function, otherwise it calls the OnGoalAchieved function. |
| 🗺️ [Planner](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/Planner) | An expert planner that must create a concise plan for the user's goal goal. |
| 🌐 [Researcher](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/Researcher) | Advanced web information retriever that Decomposes queries into sequential steps and always respects user-defined formatting. |
| ⚙️ [Scripter](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/Scripter) | An expert assistant designed to achieve goals through the use of scripts. |
| 📝[Synthesizer](https://github.com/polywrap/evo.ninja/tree/dev/packages/agents/src/agents/Synthesizer) | Reads text files, analyzing and gathering data and information from text files, generating summaries and reports, and analyzing text. |

---

# Using Evo

## Pre-Requisites
Please install the following:
- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [nodejs & npm](https://nodejs.org/en/download/package-manager#alpine-linux)
- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable)
- [nvm](https://github.com/nvm-sh/nvm#installing-and-updating)

## Setup
1. Clone the repository
`git clone https://github.com/polywrap/evo.ninja`
2. Copy the `.env.template` file and rename it to `.env`
`cp .env.template .env`
3. Find the line that says OPENAI_API_KEY=, and add your unique OpenAI API Key
`OPENAI_API_KEY=sk-...`
4. Find the line that says SERP_API_KEY=, and add your unique SERP API Key. *Get it from https://serpapi.com
`SERP_API_KEY=b071...`
4. Use the correct version of Node.JS
`nvm install && nvm use`
5. Install all dependencies
`yarn install`
6. Build all packages
`yarn build`
7. Run evo.ninja!
`yarn start`

#### Optional: You can also pass a goal on startup:
`yarn start '<your main goal here>'`

#### Optional: Custom session data

To allow evo to access custom data such as an instructions.txt, or a script you created, go to the `sessions` folder and create a new directory with your custom session name. Then add to this new directory all the files you want Evo to be able to access.

Finally run
`yarn start '<your main goal here>' -s '<your session name>'`

## WINDOWS INSTALL?

## UI

To begin using the UI, go to [evo.ninja](https://evo.ninja) enter your OpenAI Private key, and continue by inputting your prompt.


To run evo's front end locally, follow the same steps as the CLI setup, but run `yarn start:browser` instead of `yarn start`

---

# Contributing

We are eager to work with the community to continue improving this agent, and building more wraps. If you're interested in contributing, we welcome pull-requests! Here are some ways you can contribute:

- **Bug Fixes:** If you spot a bug or an error, feel free to fix it and submit a PR. Please include a description of the bug and how your code fixes it.
- **Feature Additions:** We are open to new features, functions, agents, and scripts! If you have an idea, please share it on our [discord](https://discord.com/invite/Z5m88a5qWu), or make an issue in this repo.
- **Documentation:** Good documentation makes for a good project. If you spot areas in our docs that can be improved, or if something is not documented and should be, feel free to make these changes.

Remember, the best way to submit these changes is via a pull-request. If you're new to Github, you can learn about PRs [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).

Also, please feel free to join our [discord](https://discord.com/invite/Z5m88a5qWu) and discuss your ideas or ask any questions. We are an open, welcoming community and we'd love to hear from you!