​

Installation

Let’s begin by creating your first RΞASON application. Execute the following command:

npx use-reason

This will initialize a RΞASON project. Your project’s directory structure will be as follow:

​

Directory structure

Let’s understand how a RΞASON project is structured:

• src/entrypoints: Is where all your entrypoints (routes) are defined. We’ll talk more about entrypoints below.
• src/entrypoints/hello.ts: An accessible entrypoint (route/endpoint) at http://localhost:1704/hello.
• .eslintrc.json: ESLint configuration file used to configure the RΞASON ESLint plugin.
• .reason.config.js: Configuration file for RΞASON, to set your OpenAI Key and default model, amongst other things.
• src/actions: Is where all your actions are defined. We talk more about actions here.
• src/agents: Is where all your agents are defined. We talk more about agents here.

​

File-based system

RΞASON uses a file-based system that is heavily inspired by Next.js for defining three important pieces of your app:

• Entrypoints
• Agents
• Actions

This means that all .ts files created under /entrypoints, /agents and /actions will be respectively treated as entrypoints, agents or actions.

For instance, if you want to create a new entrypoint called qa-agent you just need to create the file /entrypoints/qa-agent.ts.

When you run npx use-reason, the project that is created for you has no agents & actions, but it has a single entrypoint /entrypoints/hello.ts — which is what we’ll explore now.

​

Running your app

​

Setting your API Key

If you didn’t add your OpenAI API key during the initial setup, you should do it now:

With your API Key added, go ahead and launch your RΞASON project using:

npm run dev

After executing the command, RΞASON will start and the RΞASON Playground will automatically open in your browser:

​

RΞASON Playground

The RΞASON Playground is a web tool for testing your entrypoints. You can make requests and see their outputs.

With the RΞASON Playground open, navigate to the hello entrypoint and send a request. You will see something like:

As you can see above, the POST /hello entrypoint returns a JSON object with some cool points of interest about the city you are located at. How does it work?

​

The basics

Whenever a request is made to POST http://localhost:1704/hello, the entrypoints/hello.ts file is called and the function POST() is executed. Here’s how the file looks:

import { reasonStream } from 'tryreason'

interface City {
  /** A two sentence description of the city */
  description: string;  
  points_of_interest: {
    name: string;
    description: string;
    address: string;
  }[];
}

export async function* POST(req: Request) {
  const res = await fetch(`http://ip-api.com/json/`)
  if (res.status !== 200) {
    return new Response('Error', { status: 500 })
  }
  const { city } = await res.json()

  return reasonStream<City>(`Tell me about ${city}`)
}

Let’s break it down:

• export async function* POST() {}
  1. POST(): We are defining that this function is responsible for handling POST requests;
  2. function*: By adding * we are telling RΞASON this function returns a streaming response;
• await fetch('http://ip-api.com/json/') fetches the user’s location from their IP address;
• reasonStream<City>('Tell me about ${city}')
  1. reasonStream() is a RΞASON function that prompts a LLM and streams the response;
  2. 'Tell me about ${city}' is the prompt passed to the LLM;
  3. reasonStream<City>: By passing an interface to reasonStream(), RΞASON ensures the response conforms to the City interface structure. More details here.
• JSDoc comment: The /** A two sentence description of the city */ comment is passed directly to the LLM along your prompt. You can think of it as the prompt for the property that the comment is above (in this case, the description property).

While this might seem complex, the core functionality lies in the reason() and reasonStream() functions, which we’ll explore more in-depth later.

Next, we’ll modify the hello entrypoint to enhance its functionality.

​

Spicing it up

Let’s imagine we are building a website that a user can acess and get cool places to visit in the city he’s currently in. Cool! We already have the backend for it in the /hello entrypoint.

However, what if we want to pin the points of interest in an actual map? Since the address property is just a string this would be a bit hard.

​

Extending City interface

But what if we extended the address property to have latitude & longitude as well?

interface City {
  // ...
  points_of_interest: {
    // ...
    address: { // 👈 now its an object (was a string)
      address_line: string;
      latitude: string;
      longitude: string;
    };
  }[];
}

export async function* POST() {
  // ...
  return reasonStream<City>(`Tell me about ${city}`)
}

Now if we make a request to POST /hello using the Playground we should see the new address property:

Awesome! As you can see, by just changing the interface we pass to reasonStream() we change the output as well.

​

Taking up a notch

Now let’s say we want to return the distance from the user to the point of interest — something like: “Golden Gate Bridge is 12km away from you”.

Since we already have the latitude & longitude of the points of interest, if we could just get the longitude & latitude from the user, calculing the distance would be trivial…

Luckly for us the HTTP request we’re already making to http://ip-api.com/json/ returns that as well!

{
  "status": "success",
  // ....
  "city": "San Francisco",
  "lat": 37.7739, // 👈 latitude here!
  "lon": -122.4312, // 👈 longitude here!
  // ...
}

Awesome! So we can get the latitude & longitude from the response of http://ip-api.com/json/:

import { reasonStream } from 'tryreason'

interface City {
  // ...
}

export async function* POST(req: Request) {
  const res = await fetch(`http://ip-api.com/json/`)
  if (res.status !== 200) {
    return new Response('Error', { status: 500 })
  }
  const { city, lat, lon } = await res.json() // 👈 getting the longitude & latitude

  // ...
}

Now it just a matter of calculing the distance from two pairs of latitude & longitude. To calculate it, we can use the Haversine formula.

Let’s create a new action at src/actions/getDistance.ts that will calculate the distance for us:

// 👇 Haversine formula (bunch of math stuff)
export default function getDistance(lat1: number, lon1: number, lat2: number, lon2: number) {
  const R = 6371e3
  const latRad1 = lat1 * Math.PI / 180
  const latRad2 = lat2 * Math.PI / 180
  const deltaLatRad = (lat2 - lat1) * Math.PI / 180
  const deltaLonRad = (lon2 - lon1) * Math.PI / 180

  const a = Math.sin(deltaLatRad / 2) * Math.sin(deltaLatRad / 2) +
            Math.cos(latRad1) * Math.cos(latRad2) *
            Math.sin(deltaLonRad / 2) * Math.sin(deltaLonRad / 2)
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))

  return R * c // Distance in meters
}

Cool! So far we have:

• the latitude & longitude of the user and points of interest;
• and a function that calculates the distance between two pairs of latitude/longitude (in meters).

What we need now to do is:

1. call the getDistance() function for each point of interest to get the distance of the user from that location;
2. somehow return the distance in the streaming response of the POST /hello entrypoint.

In order to do that, we’ll need to use reasonStream() as an actual generator — which is somewhat advanced and may look complicated, but we’ll over it step-by-step in the next page.

​

Iterating through reasonStream()

reasonStream() is an async generator — which means there is much more we can do with it othen than directly return it (which is what we are doing now).

We can, for instance:

interface City {
  description: string;
}

async function* POST() {
  for await (const city of reasonStream<City>('Tell me about New York')) {
    console.log(city)
  }
}

Which will log the following:

{ description: StreamableObject { value: null, done: false } }
{ description: StreamableObject { value: 'New', done: false } }
{ description: StreamableObject { value: 'New York', done: false } }
{ description: StreamableObject { value: 'New York is a state', done: false } }
{
  description: StreamableObject { 
    value: 'New York is a state in the northeastern',
    done: false
  }
}
{
  description: StreamableObject {
    value: 'New York is a state in the northeastern United States.',
    done: true
  }
}

As you can see, the description property was filled overtime.

Import to note that while we specified in our City interface a single description property that is a string, reasonStream returned a object that has done & value. These are called StreamableObject and we’ll go in-depth in them later.

For now, what is important to know is that every property that you specified in your interface will be wrapped in a { done: boolean, value: actualValue }.

For instance, description: string became an object with { done: boolean, value: string }.

​

Calling getDistance()

Now that we know how to iterate through reasonStream(), let’s take a step back and remember our current problem.

We now want to return the distance from the user to the point of interest — something like: “Golden Gate Bridge is 12km away from you”. For that we have:

• created a getDistance() function that uses the Haversine formula to calculate the distance between two pairs of latitude/longitude.
• got the user’s latitude/longitude from the ip-api API.
• got each point of interest’s latitude/longitude from the LLM itself.

What we need now to do is:

1. call the getDistance() function for each point of interest to get the distance of the user from that location;
   • by iterating through reasonStream(), we can check whenever a point_of_interest has had its latitude & longitude returned and then calculate the distance from that to the user’s latitude/longitude.
2. somehow return the distance in the streaming response of the POST /hello entrypoint.
   • each iteration of reasonSream(), we’ll stream back the value reasonStream() yielded to us — eventually, when we calculate the distance of each point_of_interest, we’ll stream that as well.

Let’s do it! Again, this may look complicated now, but we’ll go through each step in-depth in the following doc page.

import { reasonStream } from 'tryreason'
import getDistance from '../actions/getDistance'

interface City {
  /** A two sentence description of the city */
  description: string;  
  points_of_interest: {
    name: string;
    description: string;
    address: {
      address_line: string;
      latitude: number;
      longitude: number;
    };
  }[];
}

export async function* POST() {
  const res = await fetch(`http://ip-api.com/json/`)
  if (res.status !== 200) {
    return new Response('Error', { status: 500 })
  }
  const { city, lat, lon } = await res.json()

  // 👇 New code is all here
  for await (const cityInformation of reasonStream<City>(`Tell me about ${city}`)) {
    if (cityInformation.points_of_interest.value) {
      /* 👆 We need to first check if the LLM has started returning
      the points_of_interest (by checking if its not null) */

      for (let point_of_interest of cityInformation.points_of_interest.value) {
        // 👆 Loop through each point of interest

        if (point_of_interest?.value?.address?.done) {
          /* 👆 Check if the LLM has fully finished returning
           the address property.

           We do this because we only want to calculate the distance
           when the address has been fully returned from the LLM. */

          const poiLatitude = point_of_interest.value.address.value.latitude.value
          const poiLongitude = point_of_interest.value.address.value.longitude.value

          point_of_interest.value.distance = getDistance(lat, lon, poiLatitude, poiLongitude)
          /* 👆 We add a new property to the point_of_interest called `distance`
          that represents the distance from the user in meters */
        }
      }
    }

    yield cityInformation
    /* 👆 Whenever we yield a value in an entrypoint
      that value is immediatly streamed back to the client. 
      
      So here we're just streaming cityInformation. */
  }
}

And here’s the output:

​

Bonus section: Observability

If you are curious about how observability works in RΞASON, feel free to explore this section. However, if you’re not feeling going through observability now: no problem! We’ll be going through it in-depth later.

​

Conclusion

This was the RΞASON quickstart, in it you learnt the fundamentals behind RΞASON. There’s a lot more to learn though — agents & observability are two key features of RΞASON.

Be sure to save the code you created during this walkthrough as it will be utilized during the rest of RΞASON’s docs.

Next we’ll go in-depth about some of the fundamentals of RΞASON — starting with entrypoints.