arc-agents/README.md

A library for creating and deploying gaming agents at scale

<a id="readme-top"></a>


<!-- PROJECT LOGO -->
<br />
<div align="center">
  <a href="https://arcagents.ai">
    <img src="images/arc-logo--purple.png" alt="Logo" height="80">
  </a>
</div>

<br />

<!-- BADGES -->
<div align="center">

  <!-- [![Stargazers][stars-shield]][stars-url]
  [![Unlicense License][license-shield]][license-url] -->
  [![install size][install-size-shield]][install-size-url]
  [![Twitter][twitter-shield]][twitter-url]
  [![LinkedIn][linkedin-shield]][linkedin-url]

</div>

<!-- INTRODUCTION -->
This is the main package for <a href="https://arcagents.ai"><strong>ARC Agents</strong></a>, it 
is focused on creating agents that learn via imitation or reinforcement learning. The primary 
use case for `arc-agents` is creating intelligent agents that game learn how to play games.

### Useful Links

<a href="https://sdk-docs.arcagents.ai"><strong>Documentation</strong></a>

Demos coming soon!

### Installation

You can install the package using NPM as follows:

```sh
npm install arc-agents
```

<!-- GETTING STARTED -->
## Agent Creation

In order to create an agent, we have to import the `AgentFactory` and call either the `createDemoAgent`
or `createAgent` methods. In either case, we have the ability to create a randomly initialized model
or load in a pre-trained model. More details are provided in the <a href="https://sdk-docs.arcagents.ai"><strong>docs</strong></a>.

### Demo

To get the full capabilities of ARC, we require developers to onboard on our platform. However, 
if a developer just wants to test out ARC, we allow them to create a demo agent for quick prototyping. 
This way developers can see how to incorporate ARC into their game loop before onboarding and registering
a model architecture.

```js
const { AgentFactory } = require("arc-agents");

const modelData = {
  config: {
    inputDim: 5,
    neurons: [12, 6],
    actionOrder: ["action 1", "action 2"],
    modelType: "neural-network"
  }
}

const agent = AgentFactory.createDemoAgent(modelData)
```

### Production

With the demo agent, we defined some hyperparameters for the neural network, but in the production
agents, developers first have to register their architecture on our <a href="https://arcagents.ai"><strong>dashboard</strong></a>.
The registration process involves defining all the architecture hyperparameters. Once registered, 
we simply provide the architecture id, and it will create the model scaffolding using the hyperparemeters
that were defined. This allows for the easy creation of many models using the same set of 
hyperparams.

```js
const { AgentFactory } = require("arc-agents")

AgentFactory.setGameId("game-id")
AgentFactory.setApiKey("training-api-key")

const architectureId = "perfect-architecture-id"
const agentName = "Agent A.G.N.E.S."

const agent = AgentFactory.createAgent("reinforcement", architectureId, agentName)
await agent.initialize()
```

## Basic Usage

The most basic methods that are called when incorporating ARC agents into a gameloop is `selectAction`
and `collect`.

### Take an Action

In order to take an action in the game, call the `selectAction` method, where the input is
a 2D array.

```js
const action = agent.selectAction(state)
```

### Collect Data

To collect data, call the `collect` method. At a minimum, the data object must have the current 
state and the action selected (as a one-hot encoded vector). Additionally, you can provide more 
`info` which can be useful for reward shaping.

```js
agent.collect({ state, action, info })
```

## Registration

Before creating an agent, we must register its architecture. It's easier to register via our 
<a href="https://arcagents.ai"><strong>dashboard</strong></a>, but we also allow developers to 
register model architectures through code as well.

```js
const { Registry } =  require("arc-agents")

Registry.setApiKey("admin-api-key")

const registry = new Registry("game-id")

const registryInputs = {
  modelType: "neural-network",
  architectureId: "perfect-architecture-id",
  numberOfStates: 10,
  possibleActions: { direction: ["up", "down", "idle"] }
}

await registry.register(registryInputs)
```


<!-- MARKDOWN LINKS & IMAGES -->
<!-- [stars-shield]: https://img.shields.io/github/stars/ArenaX-Labs/arc-agents--npm.svg?style=for-the-badge -->
[stars-shield]: https://img.shields.io/github/stars/ArenaX-Labs/arc-agents--npm.svg
[stars-url]: https://github.com/ArenaX-Labs/arc-agents--npm/stargazers
<!-- [license-shield]: https://img.shields.io/github/license/ArenaX-Labs/arc-agents--npm.svg?style=for-the-badge -->
[license-shield]: https://img.shields.io/github/license/ArenaX-Labs/arc-agents--npm.svg
[license-url]: LICENSE.txt
<!-- [linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555 -->
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-blue.svg?logo=linkedin
[linkedin-url]: https://www.linkedin.com/company/arc-agents/

[twitter-shield]: https://img.shields.io/badge/-Twitter-black.svg?logo=twitter
[twitter-url]: https://www.x.com/ARCAgents

[install-size-shield]: https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=arc-agents&query=$.install.pretty&label=install%20size&style=flat-square
[install-size-url]: https://packagephobia.now.sh/result?p=arc-agents