Beginners guide to using the maiar-ai agentic framework

Maiar: Beginners guide


__Update: 12/31/2024__

__As of late 2024 Strava has decided to restict usage of their data by third parties. The restrictions are so strict I believe the graph that used to be on this blog is no longer allowed. I think this is a hostile move by Strava that damages third party applications that were only given 30 days to comply with the new terms__

I always like to explore the APIs available to websites and services that I use, in this spirit I wrote down my thoughts on the Strava API. Its uses, limitations and pain points I ran into when making a small React component to visualize my elevation and distance metrics over the last 6 months.

## Motivation

I wanted to explore the Strava API and this felt like a good way to figure out what you can and can't do with it. It also let me build more skills at data visualization in React using the `npm` package `Victory`. I would be interested ot see how Victory handles more complex plots but the ability to customize the look of the rendered graphs easily is a major advantage over other data visualization tools I have used. Note that this is really only needed when dynamically generating graphs, if you are using a static dataset just make a graph in Python or powerpoint or something and render it as an image, it will save you a lot of headache.

After exploring the API I will say that this use case is not really the intended use of the API. It is really intended for third-party applications that want to request strava data on behalf of a signed in user, whereas I am using it to only request a single individuals data.

## Use Case

As mentioned previously, my use case is not really a standard one for the strava API. I am building a simple React component to graph my distance and elevation data on a single line-chart. The actual data visualization has nothing to do with the strava API usage, but the data that is visualized on that graphic is delivered from the strava API. My use case is to pull data from strava to visualize but only when new data is available. A normal usage would probably be to let the client (the browser) request strava data on every request (with caching, but in general for each new user -> new strava API request), but for my use this is unnecessary as they would be requesting my data which is the same for every client. This means that instead of doing client side requests we need to do server side requests only once when new data is uploaded to strava. This leads me to the first limitation.

- _There is no way to watch for new data_ &rarr; Since there is no callback or anything to trigger an update on the server side when new data is uploaded to strava, we instead need to handle that ourselves

To handle this limitation I decided to use a cron job, this is kind of a _"hacky"_ solution, but I think it cuts down on unnecessary strava API requests in exchange for the data possibly being out of date at some points. For this use case that is not an issue because no one is relying on that data being accurate, in other cases where this data being updated on time was mission critical you would need to take another approach

## Authentication and Authorization

The strava API uses OAuth 2.0 for user authentication and authorization, you can find a detailed explanation of OAuth 2.0 [here](https://oauth.net/2/). I don't want to dive too deep into this, but know that ultimately to request data you need an authorization bearer token that corresponds to your user and has the proper permissions to access the requested data. However, these tokens will expire and you need to re-authenticate to get a new token, so your app needs to handle the case where your requests are rejected for an expired token.

## Available Data

There are a lot of data points displayed on the strava dashboard that are not directly available through the API. For instance the distance and elevation per week are not available, so to get these values you need to loop through all activities and add up the distance/elevation values based on the week that activity happened. Check out the [api docs](https://developers.strava.com/docs/reference/) for a complete set of available queries.

The other caveat about data is the `fitness/freshness/fatigue` values, which are not available via the API even when aggregating data from other requests. This is because these values are calculated in a way that strava does not give use information about, from what I understand it is the same calculation used by training peaks and other apps. My next blog will be about reimplementing this calculating on this blog so stay tuned for that!

## Conclusion

The strava API is mainly used by third-party applications to request data on the users behalf but it is possible to use it for more simple uses, like the strava graph on this blog. You just need to be careful to handle the weirdness of OAuth and client/server side requests so that you are not making unnecessary requests to the strava API or exposing your authentication tokens to the user (This would be bad so do not do this!!)

The other thing to keep in mind is that you may need to aggregate data from the list of activities if the strava API does not provide the data you want directly. And you won't be able to query or calculate (without a lot of knowledge) the `fitness/freshness/fatigue` values, if you are interested in those.


Limitations and Uses of the Strava API v3


The Cayon Grizl CF SL is Canyons entry level carbon "Adventure" gravel bike, in contrast to the Grail which is race oriented bike. The "Adventure" monicker means that the bikes geometry is less aggressive and the frame is packed with mounting points for bags and other accessories. The bike comes stock with GRX 11-speed mechanic groupset (in 2022, the newer version have the GRX 12 speed or SRAM Force AXS), an iridium dropper post, G1800 DT Swiss Alloy rims wrapped in Maxis Rambler EVO 45mm tires. As you can see from the image above, my bike is anything but stock, let me list the things I've upgraded and accessories I use on most of my rides.

## Upgrades

- GRX 12-speed mechanical groupset (SLX CS-M7100 Cassette 10-51)
- GRX RX810 Cranks (170mm vs 175mm that come stock)
- Reynolds ATRx Carbon Rims
- Fizik Argo Adaptive 3D printed saddle
- Zipp Service Course SL stem
- Ritchey Supercomp Alloy Handlebars
- Shimano XTR RT-MT900 Rotors
- Wolftooth Aero Chainring for GRX 800 cranks (50T)

## Accessories

- Silca Gravelero Mini-Pump
- Silca Mattone Seat Pack
- Lyzne Strip Drive Pro Rear Light
- KOM Stem Mount with GoPro Computer Mount
- Bontrager ION Pro RT Headlight

## The Good

There is a lot to like about this bike, first the price is very competitive compared to other similarly equipped gravel adventure bikes, but this is to be expected for a direct to consumer brand like Canyon (I'll touch more on this later). The frame is light, the components are good quality and the geometry of the bike seems to fit the style of riding I enjoy.

It seems, unlike other brands, that Canyon understands riding wider tires is just faster (blog post on this coming soon) and have given this bike 50mm of tire clearance. Currently I am running 50mm tires and you could actually go larger on the front, the rear would be close as any mud would lead to frame rubbing. This is a huge advantage, especially over some of the _"race"_ oriented bikes that sometimes only have clearance for 40mm tires or thinner.

The mounting points are a plus as well. I am sure that the have some aero penalty and including them most likely increase the weight of the bike, but being able to hold bags on the top tube, on the fork, under the bottom tube and running a rear pack means you can seriously pack this bike full, like any other modern adventure bike.

I've also found that while the geometry is not as aggressive as the Grail, you can set it up to still be very fast and put you into an aggressive position. Or you can stack spacers under the stems and get a nice, comfortable position for all day riding. There are times where I wish I could get even lower on the bike, but at this point I am pushing the geometry of the bike past what it was intended for so I can't really complain about this.

I also want to mention the stock groupset, the GRX 11-speed. By no means is it a bad groupset, as far as gravel specific groupsets go this is probably one of the best. That being said I did end up upgrading it to the new GPX 12-speed, mainly for the gear range. The 11-speed can only go up to a 42T cog and down to 11T, meaning that if you want to prevent spinning out you need to run like a 46-50T chainring which makes steep climbing on gravel a challenge. Moving to the new 12-speed groupset allows you to run a 10T low cog and 51T large cog which makes the gearing on a 46-50T cassette perfect, as you get a < 1:1 ratio for climbing. I should mention this is not the only reason I swapped groupsets, I crashed the bike and landed on the derailleur, which made shifting horrible for months. I replaced the derailleur hanger and tried to adjust the derailleur as well as I could but it never shifted properly again after that, most likely the derailleur itself was bent.

## The Bad

While I do enjoy this bike a lot, many of the pain points are simply a consequence of Canyons direct-to-consumer model. Specifically for me the 1-1/4" steerer tube diameter is a frustrating design decision that makes finding new stems, top caps, compressions plugs and headset spacers almost impossible. Couple this with the brittle plastic top cap and you have a recipe for disappointment if you are not paying very close attention.

For me when I was able to find a stem to fit the 1-1/4" steerer tube I did not realize it was about 1mm shorter than the stock stem and as such the spacers were not tall enough to make good contact with the headset top cap, meaning you could crank down on the plastic top cap and break it very easily (which is what I did). Then you are left with two options for replacements, one is to reach out to Canyon and pay them for the POS plastic cap or to find a third-party that sells them (there are not many of these, I suggest kapz.com).

The last issue I want to talk about is the wheels and tires. If you are trying to go fast on this bike the best thing you can do it replace these. The bike comes stock with DT Swiss Alloy rims and these are HEAVY, the difference between them and a _relatively_ inexpensive carbon rims is night and day. Combine the alloy rims with the slowest tires I've ever ridden, the Maxis Rambler EVO and you are in for a bad time. If you do have this bike do yourself a favor and spend the extra $200 to put a decent set of tires on it, even if you don't upgrade the rims. I would suggest the 45 Continental Terra Speed or the 50mm Continental Terra Hardpack. Check out [bicyclerollingresistance.com](https://www.bicyclerollingresistance.com/) if you want to know how I pick fast tires.

## The Ugly

I think the way Canyon has made some many parts proprietary is frustrating and not in the spirit of right-to-repair and as a consumer who works on their own bike this has been an eye opening experience. I know in the future if I do buy from a direct-to-consumer brand I will pay much more attention to the standards used and make sure it's something I can live with.

The only other negative on the bike for me has been the paint. I do not like the matte paint as it stains super easily. Everything from sealant, chain oil, dirt. Eventually it will come clean but it takes so much more effort to keep this type of paint clean than the gloss finished bikes I've owned.

## Should you buy this bike?

For a gravel adventure bike this is one of the best price-to-performance bikes you can purchase, but it's not without negatives. I would be very cautions if you are someone who likes to play around with different components on your bike, or if you are someone who is prone to loose/breaking parts on your bike. With Canyons direct-to-consume model all spare parts need to be purchased through them. So far I have had to buy two spare parts, in under a year of owning the bike, and it cost around ~$90 for both with shipping (and those were for cable grommets and the steerer tube top cap).


Long term review of the 2022 Canyon Grizl CF SL 7

Canyon Grizl CF SL 7 Review


## Note

*This article is from the BitPost 30 Day Challegne and was orignally posted there*

Yesterday I posted an article titled [No humans were harmed in the making of this article](https://www.bitpost.app/u/zachrobertson/no-humans-were-harmed-in-the-making-of-this-article-SL9kV8H) that was generated by an AI. If you read that post you will know that it was basically gibberish, and today I wanted to talk about how I created the program to do this and why the results are subpar. There is a lot to cover so today I am just going to go over the process at a very high level and the following days I will dig into more detail.

I uploaded the code I used to create this to a [GitHub](https://github.com/zachrobertson/article_transformer) repository if you would like to look at it.

To create the article I used a [GPT](https://en.wikipedia.org/wiki/OpenAI#GPT) like model to produce a sequence of words of a specific length given an input sentence, in my case this was the title of the article. GPT uses a method called [auto-regressive](https://jalammar.github.io/illustrated-gpt2/) language generation that assumes the probability distribution of a sequence of words can be decomposed into the product of conditional probabilities of the next word distribution. Which in plain english means that we can generate text by using a sequences of words to estimate the most probable next word for that sequence. A mathematical formulation of this is given below:

![Probability distribution](/blog/images/article_generator_probability_prod.png)

Where `W_0` is the initial context word sequence (for me the title), `T` is length of the word sequence and is usually determined *on-the-fly* (This is not the total length of the article just the length of the current sequence). The probabilities of words need to be learned by the model during training, but I will be talking about that in a later article.

Now that we have a basic idea of what the model is doing, how do we actually choose the words? The naive solution is to use a Greedy Search, which just uses the highest probability word as the next word in the sequence. The issue with this is that while you are always choosing the highest probability word, you will most likely not choose the highest probability *sequence of words*. Here is a good visualization of the Greedy Search algorithm.

![Greedy Search](/blog/images/greedy_search.png)

To give an explanation as to why this is not the best method lets look at a few paths on the tree. The path that the Greedy Search will take is highlighted in red and has an overall probability of `0.5 X 0.4 = 0.2` but if we look at the branch containing  `dog` and `has` we get a total probability `0.4 X 0.9 = 0.36` which is a higher total probability than the chosen path so we need to use a different searching method.

A variation on the Greedy Search called Beam Search is often used instead, this is were we choose a number of "beams" to do a Greedy Search. Meaning we search through the top `n` most probably paths before choosing the most probable one. An illustration for an `n=2` Beam Search is shown below for the same tree we used earlier.

![Beam Search](/blog/images/beam_search.png)

As you can tell this time we did actually get the most probable sequence, but if we used this for text generation we would run into a few issues. For starters let me show you the output of the same model using a Beam Search algorithm and the solution that I ended up using to create yesterdays article for the same input sequence. Given the sequence "I like to run", the Beam Search output was:

>I like to run, I like to run, I like to run, I like to run, I like to run, I like to >run, I like to run, I like to run, I like to run, I like to run,

And with the solution used yesterday the output is:

>I like to run my own station, and get them my way," Reeves said.
>
>Canarias (Round Rock) resident Jason James Cox said he's much happier with the >program he's gained as a result of her visit.

Clearly the output on the bottom seems much more human like (albeit still a bit incoherent), but the top has a major flaw in that it just keeps repeating the same sequence. This is because given a specific sequence the Beam Search has a deterministic output meaning there is only one possible output for a specific input. We could help this by introducing penalties to the probability of words and sequences that have already been used, a simple implementation of this is to use *n-gram* penalties which sets the probability of an *n-gram* to 0 after it has already been used.

Using the same Beam Search algorithm as before but adding *n-gram* penalties we get the output below.
*Note : an n-gram is a grouping of n number of words, so in the sequence "The dog walks" the 2-grams are "The dog" and "dog walks"*

>I like to run, but I don't know how to do it," he said. "I'm not sure if I'm going >to be able to get out of here."
>
>He said he has no idea if he'll ever get to

This is clearly a better output than what we had for the earlier Beam Search but there is still a big underlying issue with this method and that is when you want to produce an article that does have some repetition. Say for example you are writing an article on "The Supreme Court" and have decided that you will not repeat any 2-gram sequences then your article will only ever include the term "Supreme Court" once, which is obviously undesirable.

The solution I ended up using is something called *Top-p (nucleus) sampling*. This is the idea of sampling the top `n` number of words, where `n` will be decided *on-the-fly* such that the cumulative probability of all the words select is greater than or equal to some probability `p`. We then randomly select a word from the subset we just created with weighted likelihood based on the adjusted probabilities of each word in this subset (adjusted means that we keep the ratios of the probabilities for each word in the chosen subset the same but they are adjusted so that the cumulative probability of the subset will be 100%).

Tomorrow I will talk more about the actual model architecture to use for this kind of task and how we train a model like this.

Thanks for reading

Zach


How to generate articles with GPT - from the BitPost 30 Day Challenge

Article Generator - BitPost 30 Day Challenge Day 25


## Note

*This article is from the BitPost 30 Day Challegne and was orignally posted there*

A few days ago I wrote on article on [Deep Neural Networks](https://www.bitpost.app/u/zachrobertson/deep-neural-networks-9pB7Qun)(DNN) in which I explained the mathematics behind a [Perceptron](https://en.wikipedia.org/wiki/Perceptron), which is the most basic form of deep learning and the building block for more complex deep neural networks. In that article I promised to go into more detail on different kinds of neural networks and for the first one I wanted to cover [Convolutional Neural Networks](https://en.wikipedia.org/wiki/Convolutional_neural_network)(CNN), this is mainly because it is used in the [Computer Vision](https://en.wikipedia.org/wiki/Computer_vision) domain, which aims to use computers to obtain understanding from images and videos, this allows me to easily explain what the model is actual doing using visual representations.

A CNN is like a standard DNN in the fact that it has layers of neurons that are connect to each other and at each layer there is some mathematical operation taking place. With a standard neural network this is just a group of linear equations because each neuron is just multiplying the input by its weight value and adding a bias value (`y = W*x + b` were `x` is the input `y` is the output and `W, b` are the parameters of a neuron we are training). A CNN is different in that it needs to act on a 3-dimensional array of values instead of just a single value, this because of the way we represent images as data. Images cannot easily be understood by computers and we always need the input to our deep learning model to be a numeric representation of the data. To convert images to numeric values what we usually do is represent the red, blue and green intensity of each pixel on our display as a 2D array were the higher the value the more intense the color (with 8-bit color images this would be a value from 0 to 255) that are then stacked together into a 3D array (There can also be 4D arrays where a gamma value is added). Now that we have a 3D array we want to do some mathematical operation on it to produce meaningful information. The way a CNN does this is through the use of filters, a filter is a 2D array that is smaller than the image it is filtering and contains weights at each index of the array that can be trained (like the weight and bias value of the standard neuron). We use this filter by multiplying it against a subset of an image array that is the same size as the filter to obtain a new pixel value, we then move the filter over one pixel (or more if you want to compress the image) and do the same thing until we have produced a new image that hopefully maintains some important features (features could be anything the computer seems to think are important).

Here is a visual example.

![Ascent](/blog/images/ascent.png)

Say we want to find the edges of this image, a way to do this is to pass a very specific convolutional filter (`[[-1,0,1], [-2,0,2], [-1,0,1]]`) over the image. The reason this works is because of what we visually identify as an *edge*, they tend to have pretty high visual contrast between the sides the edge creates so this filter is a way of returning high pixel intensity values for the pixels with the highest contrast between their neighbors (this is just one way of doing [edge detection](https://en.wikipedia.org/wiki/Edge_detection)). The output of this convolution is show below, here the input image way actually a 2D array since it was black and white so the output will also a 2D array again show in black and white.

![Ascent Edge Detection](/blog/images/ascent_edges.png)

Another important idea in CNNs is the use of pooling, which is when we reduce the total number of pixels in the image while trying to retain the features highlighted during the convolution. We can also reduce the size of the output image during the convolutional filtering by increasing something called the stride, the number of pixels the filter is moved at each step, if we increase the stride the total number of pixels will be less. Pooling is different in that we are using some mathematical operation to combine blocks of pixels into a single pixel, this could be either taking the average of the pixels or only using the highest value, it all depends on the application it is being used in. For the example we have been using we want to increase the contrast on the edges as much as possible so to do this we can use a max pooling operation, which uses the max value from the block of pixels as the new pixel value. If we do this on 2 by 2 sections of the image this is the result.

![Ascent Edge Detection Max Pooling](/blog/images/ascent_edges_pooled.png)

So far we have talked about what a convolution is but I haven't yet explained how this is actually used for machine learning. Typically convolutional layers are not used by themselves, we still need a traditional DNN connected to our convolutional layers to make predictions, so the convolutional layers are more of a tool for extracting important information from the images (features) for the DNN to use. There are many different applications where you could use CNNs to do a task but I think the most common ones are object detection and image prediction. Object detection is identifying one or more objects in an image (including their location) while image predication is saying whether or not an image represents some class (cat/dog/pig/llama, pizza/not pizza, etc.), they do this by training on a dataset of images that have labels associated with them so that after the image has passed through the convolutional layers it is sent to a layer (can also be more than one) of standard neurons that then produce a prediction on the class of the image or the location of an object. We can then use the standard back propagation gradient descent algorithm I discussed in the [Deep Neural Networks](https://www.bitpost.app/u/zachrobertson/deep-neural-networks-9pB7Qun) article to train the model, which will also train the convolutional filter weights.

To give you an example I have made a quick model using a python library/framework called [TensorFlow](https://www.tensorflow.org/), the model will predict whether or not an image contains a dog or a cat (it assumes that one of the two will be present). Here is the model architecture :

![Dog or Cat Model Architecture](/blog/images/dog_or_cat.png)

This image shows the shape of the input and output of each layer in the model and I want to walk through these. The first layer is just an input which accepts 150 by 150 RGB encoded images (a 3D array), the next is a convolutional layer that takes in the image and applies 16 different filters to the image to produce a 3D array with depth 16. We then have a max pooling layer which reduces the number of pixels in each of the 16 2D arrays by half (using the max of the pixel blocks like discussed earlier). Then we have 3 more sets of a convolution layer followed by a max pooling layer, the first two convolutions will have 32 filters and the last one will have 64 filters. Then we flatten the output of the last max pooling layer so that we can feed it into the DNN, which only has two layers. The first is the hidden layer that will provided the prediction functionality, and the last is the output layer that tells use whether the image is of a cat or a dog. To see how the model is functioning, after I trained it I gave it the image of a dog shown below and wrote a script that would display the outputs from a specific convolution or max pooling layer.

![Dog](/blog/images/conv2d_input.png)

Here are some of the more interesting images produced after the first set of convolution and max pooling layers.

![Max Pooling Layer 1 Filter 2](/blog/images/max_pooling2d_2.png)
![Max Pooling Layer 1 Filter 12](/blog/images/max_pooling2d_12.png)

As you can see these are not quite as clear as the edge detection example, but this is to be expected. The computer is not trying to identify edges but instead trying to identify features it thinks are important for determining whether an image is of a cat or a dog and images are probably not the most important feature for that task.

Thanks for reading

Zach

PS Here is the code the recreate the model I used for this article and plot the outputs from each of the convolution or max pooling layers.

First download some data.

```bash
curl https://storage.googleapis.com/mledu-datasets/cats_and_dogs_filtered.zip -O cats_and_dogs_filtered.zip
```

```python

import os
import zipfile
import tensorflow as tf
import numpy as np
mport matplotlib.pyplot as plt
import matplotlib.image as mpimg

from PIL import Image
from tensorflow.keras.preprocessing.image import ImageDataGenerator 
from tensorflow.keras.optimizers import RMSprop

#Unzip file and save to /data subdirectory
local_zip = 'cats_and_dogs_filtered.zip'
zip_ref = zipfile.ZipFile(local_zip, 'r')
zip_ref.extractall('./data')
zip_ref.close()

base_dir = './data/cats_and_dogs_filtered'
train_dir = os.path.join(base_dir, 'train')
val_dir = os.path.join(base_dir, 'validation')

train_cat_dir = os.path.join(train_dir, 'cats')
train_dog_dir = os.path.join(train_dir, 'dogs')

val_cat_dir = os.path.join(val_dir, 'cats')
val_dog_dir = os.path.join(val_dir, 'dogs')


train_cat_len = len(os.listdir(train_cat_dir))
train_dog_len = len(os.listdir(train_dog_dir))

val_cat_len = len(os.listdir(val_cat_dir))
val_dog_len = len(os.listdir(val_dog_dir))

print(f'There are {train_cat_len + train_dog_len} training files, \n{train_cat_len} are cats, {train_dog_len} are dogs')
print(f'There are {val_cat_len + val_dog_len} training files, \n{val_cat_len} are cats, {val_dog_len} are dogs')

model = tf.keras.models.Sequential([
    tf.keras.layers.Conv2D(16, (3, 3), activation='relu', input_shape=(150, 150, 3)),
    tf.keras.layers.MaxPool2D(2, 2),
    tf.keras.layers.Conv2D(32, (3, 3), activation='relu'),
    tf.keras.layers.MaxPool2D(2, 2),
    tf.keras.layers.Conv2D(32, (3, 3), activation='relu'),
    tf.keras.layers.MaxPool2D(2, 2),
    tf.keras.layers.Conv2D(64, (3, 3), activation='relu'),
    tf.keras.layers.MaxPool2D(2, 2), 
    tf.keras.layers.Flatten(),
    tf.keras.layers.Dense(512, activation='relu'),
    tf.keras.layers.Dense(1, activation='sigmoid')
])

model.summary()

# Uncomment to save image of model
# tf.keras.utils.plot_model(model, to_file='dog_or_cat.png', show_shapes=True, show_dtype=True, show_layer_names=True)

model.compile(
    optimizer=RMSprop(learning_rate=0.001),
    loss='binary_crossentropy',
    metrics=['accuracy']
 )

train_datagen = ImageDataGenerator(rescale=1.0/255.0)
train_generator = train_datagen.flow_from_directory(
    train_dir,
    target_size=(150, 150),
    batch_size=128,
    class_mode='binary'
)
val_generator = train_datagen.flow_from_directory(
    val_dir,
    target_size=(150, 150),
    batch_size=80,
    class_mode='binary'
)

history = model.fit(
    train_generator,
    validation_data = val_generator,
    epochs = 10,
    steps_per_epoch=8,
    validation_steps=8
)


# Change index of output_layer to see the output from different convolution layers
input_layer = history.model.layers[0]
print(f'Using input layer {input_layer.name}')
output_layer = history.model.layers[3]
print(f'Using output layer {output_layer.name}')

  

first_convolution_layer_function = tf.keras.backend.function(
    [input_layer.input], 
    [output_layer.output]
)

  

img = Image.open('./path/to/image')
img = img.resize((150, 150))
img = np.array(img)
plt.imshow(img)
plt.show()

first_convolution_layer_output = first_convolution_layer_function(tf.constant([img]))
img_array = first_convolution_layer_output[0][0, :, :, :]
for i in range(img_array.shape[-1]):
    flat = img_array[:, :, i]
    plt.imshow(flat)
    plt.show()
```


An explanation of how convolution neural network work for computer vision - from the BitPost 30 Day Challenge