Getting Started

Get an account

• Sign up for a Reason AI account account

Try it Online

You can use Reason AI from the web console without any installation

Installation

Prerequisites

• Generate an API key under Settings
• Get a Node.js version 18 or higher
• A terminal to run CLI commands
• An IDE to edit IaC configuration

Reason AI is available as an npm package:

npm

npm install reasonai

yarn

yarn add reasonai

Setup

Reason AI can be used on its own or as part of an existing project. The setup will create a ./reason directory where everything related to Reason AI will be stored

npm

npx reasonai init

yarn

yarn reasonai init

You will be taken through a few setup questions:

That's it!, you are all set up.

Create Your First Integral

To create an Integral, simply pass in the required parameters and deploy your environment

Run this command and follow the prompts

reasonai add api

# Follow the wizard and provide the following responses
> Enter API name: # getStarSignAPI
> Write the main instruction for the model:
#   Given a person's birth month and year, you return their star sign as a json object containing {sign:string}
> Select a generative model to use:
#   gpt-4o-mini
> Response format: # JSON

When done, a new API will be created under ./reason/integrals/getStarSignAPI with JSON config similar to the following:

{
  "name": "getStarSignAPI",
  "instruction": "Given a person's birth month and year, you return their star sign as a json object containing {sign:string}",
  "model": "gpt-4o-mini",
  "responseFormat": "json_object"
}

Great! Now let's run this command to deploy the API so we can start using it:

reasonai api push

That's it. Your Integral is deployed and live

Testing your API

curl https://reasonai.dev/api/v1/request \
  -X POST \
  -H "Authorization: Bearer <your api key here>" \
  -d '{
    "apiId": "<copy from ./reason/.meta.json>",
    "messages": [
      {
        "role": "user",
        "content": "what is the starsign of a person born in April 1992"
      }
    ]
  }'

You should receive results similar to:

{
  "id": "<your-api-id>",
  "threadId": "thread_6zY61bNiZX08Yt15MVolgaue",
  "messages": {
    "id": "msg_54vENtcnHHojV8sBL7HkB7ol",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "{\"sign\":\"Aries\"}"
      }
    ]
  }
}

TIP

To learn more on effective prompt generations, click here
To see the full reference for creating an Integral, click here

Adding Function

Integrals can call external functions to perform specific requests. Ensure that your prompt includes instructions on when to call the Function First create the function

reasonai function add

Follow the wizard to create the function. The results will be available under ./reason/functions/yourFunctionName

{
  "name": "getCharacterByName",
  "description": "Gets a Futurama character by name and returns an object representing the character",
  "parameters": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      }
    }
  },
  "invocation": {
    "type": "rest_api",
    "rest_api": {
      "url": "https://sampleapis.com/futurama/api/characters?name.first={name}"
    }
  }
}

Modify the function as necessary and deploy when ready

reasonai function push

Once your function is ready, you can add it to the Integral by modifying the config ./reason/integrals/yourAPIName/yourAPIName.json

{
  "name": "charactersAPI",
  "instruction": "When asked to get a list of characters, you call the getCharacters function When given Futurama character name, you call the getcharacterbyname function return results in JSON format",
  "model": "gpt-4o-mini",
  "responseFormat": "json_object",
  "tools": [    
    {
      "name": "getCharacterByName",
      "type": "function"
    },
    {
      "name": "getCharacters",
      "type": "function"
    }
  ]
}

File Structure

After running the setup, the generated file structure should look like this if you chose JSON:

./reason/
│
├── .meta.json
└── config.json

This is an empty Reason project with no Functions or Integrals . To get started, add an Integral

npm

npx reasonai api add

yarn

yarn reasonai api add

All your configuration goes into separate sub directories under the main reason directory.

E.g after adding a few Functions and Integrals, you should have something similar to this:

./reason
├── integrals/
│   └── weatherAPI/
│       └── weatherAPI.json
└── functions/
    ├── getWeather/
    |   └── getWeather.json
    └── getHumidity/
        └── getHumidity.json

The Config File

The config file stores the Reason AI configuration as well as your API key login credentials

{
  "baseDir": "./reason",
  "metaDataFile": ".meta.json",
  "configFormat": "json",
  "auth": {
    "apiKey": "*******",
    "organizationId": "*********",
    "type": "apiKey",
    "id": "********",
    "createdAt": "2024-08-07T22:26:08.465Z",
    "expiresAt": null,
    "user": {
      "id": "**********",
      "email": "[email protected]",
      "firstName": "Jenny",
      "lastName": "Server"
    },
    "loginDate": "2024-08-08T00:57:07.286Z"
  }
}

What's Next?

Now that your environment is setup,

• Take a look at the Concepts page to better understand how Reason AI works
• You might also want to look at our CLI Documentation to learn how it works
• Or jump straight into our APIs to connect your services