0:00 Introduction & The Problem

0:00 Hello and welcome back to the Rawkode Academy. As always, I'm your host David Flanagan, also known across the internet as Rawkode. I'm excited to be sharing with you today a new project that no one has ever heard of because it's not public yet. So if you want to see a pretty sweet project that can help you be more productive and a happier developer, you're at the right place. Building applications on the dawn of cloud native has meant that we don't just focus on our business logic because our time is spread thin across ops, DevOps, containers and message brokers, contracts, gRPC, GraphQL

0:37 and a myriad of a thousand other concerns. But what if there was another way? What if you could just focus on your business logic and not have to worry about the platform and just get shit done? Well, let me introduce you to Guidepad. Guidepad is a framework that can get in your face or get out your way. You get to decide and what do I mean by get in your face or get out your way? Well, by get in your face I mean that Guidepad can be opinionated. It can provide tracks that you just put your code on and

0:50 Introducing Guidepad

1:10 it run. You write a simple Python function and ship it to prod with a git push but if you want it to get out your way you can use it as a framework for deploying your code in your applications to Kubernetes or even with Ansible. The choice is yours. Today I'm going to show you a small application that I built on top of Guidepad the Guidepad way using their type system, their services, their data stores. Let's take a look. Okay, so here we have my terminal with two pins. The two pins aren't important right now but they will be soon.

1:37 Demo Application Overview (Pocket Clone)

1:43 I built an application to resemble Pocket. If you're not familiar with Pocket, it's an application where you can save web pages and URLs that you will never ever read again. I wanted to build the exact same thing on top of Guidepad using Guidepad as the framework. So the first thing we're going to do is create a bookmark. For this, I'm going to use the Guidepad CLI. Remember, we're doing this the Guidepad way with only the Guidepad tooling, where I can say entity create bookmark. This command will allow me to take standard n as a description of our bookmark.

2:00 Demo: Creating and Listing Bookmarks (CLI)

2:16 We denote this with a dash and a here dot. If you're familiar with Linux, you have seen this syntax before. I can now add our bookmark or I'm just going to add the Rawkode Academy website. We can then end our here doc like so. Now Guidepad here it does the plug in stuff behind the scenes and we'll talk about that as we progress through this video. But all you need to know is right now it's about to create a bookmark. We can then use the Guidepad CLI to list all of the bookmarks within the system.

2:47 So now I can do a Guidepad entity list bookmark and I'm going to pass in an empty selector because we have the ability to filter the bookmarks if we wish. However, right now we should only have one and my font's a bit big but you can see we have a whole bunch of information here, more than the information that we provided on the command line. Our Guidepad system has taken the URL that we provided, it has scraped the endpoint for metadata and found us a title, a description, the language of the web page, it's tried

3:21 to find an author and an image but that's not important and then there's a summary on the end. So what happened here? Well we have deployed a plugin to Guidepad or the bookmark service that tells it whenever you save and you bookmark go and fetch all this information and update the entity, even use an OpenAI to generate a summary of the web page. So let's try that one more time with another URL. With the Guidepad entity create, click for, here doc URL and a story from the BBC. End our here doc and let our entity be created

3:29 Understanding Automatic Data Enrichment

3:59 by the Guidepad system. And done. Now we can run Guidepad entity list bookmark, and we can even filter this now if we wish. Let's say that we only want to see the URL that we just added. Let's scroll up. This article has Elon Musk and Mark Zuckerberg agree to hold a cage fight. We have the description. We have the language. And because this was an article from the BBC, we do have an author. However, there's still no image. And we have our summary from ChatGPT. Perfect. Let's take a look at how we built a system on top of Guidepad. Let's

4:31 Under the Hood: Guidepad Plugin Structure

4:37 head over to my IDE where we have a directory called Guidepad Rawkode. This is my Guidepad plugin. A Guidepad plugin is a bunch of Python code which you store and get and register with the Guidepad system. You may have noticed that every time I ran the Guidepad CLI, it was fetching the plugins and the types doing constant reconciliation or looking for changes within the Git repository. You get to define your own requirements dot text for each of your plugins. So here, it was very easy for me just to add in the OpenAI package as well as b print to make

5:10 my debugging life a little bit easier. Then we have another directory again called Guidepad Rawkode where we can define and work with a type system provided to us by Guidepad. In order to provide my plugin, I had to tell it the operations, the services, and the types that my plugin is going to register. What you'll see here is I actually have two systems being deployed by a single plugin. I haven't just written a pocket bookmark API, I've also written a URL shortener which maybe we'll take a look at in another video, but right now let's take a look

5:41 Defining the Bookmark Type

5:41 at our bookmark type. This is a very simple Python class that extends the Guidepad base type system. Not important that you understand how this works right now, so let's just go over the high levels. We define the properties for our bookmarks. One we need a URL, then all of the additional fields that we're going to try to extract from the URL itself such as the title, description, the language and so forth. All of the columns that you seen on the CLI. We then have a bunch of functions that I provided to make my life a little

6:12 bit easier. One, a function which will get the body for the URL. This is just using the Python request module where we do a get on the URL that was provided. If it doesn't return us to a hundred, we don't allow you to save your URL. Let's check that out. Let's do Guidepad entity, create bookmark where we have a URL google.com/fatepage and end. And there we have our exception. Now is this the best way to block the saving of the bookmark? No, not really, however it does work and in the future we'll take a look at

6:52 how to handle errors properly within the Guidepad system. We then have our summarize function which will grab the first twelve thousand characters of the web page and send them to chat GPT for a completion and a summary. In order to enrich our bookmarks with metadata we're using the micro link API. We send it the URL and request the metadata. From here we can just set the properties on our class title, description, language and so forth and the way that we make this work is to override the save function on the base type. So here we just say if there is no

7:26 title meaning we haven't fetched any metadata before or perhaps it failed, then we grab the body, enrich with metadata and summarize. Nice and simple. So there's a lot to like about this file. One, I haven't really had to use any of the Guidepad APIs. I just wrote Python code. The one time I did use the Guidepad API was to handle something that I really don't wanna have to worry about, that I really don't want to have to handle myself which is secrets. If we scroll up you'll see here on line 31 that we used secret dot list single to request an OpenAI

7:57 Secrets Management and the Core Type System Concept

8:05 token. This reveals something about Guidepad that may not have been obvious at first. Everything in Guidepad is built on the type system including secrets, bookmarks or types, short URLs or types, services or types, ingress or types, everything is built on the system. So when you buy into that opinionated system, building applications can almost become trivial. You get to focus on your business logic and none of the surrounding platform infrastructure or operating needs. Okay, but let's assume we don't want to have to rely on the Guidepad entity list bookmarks to see the bookmarks within our system.

8:38 Exposing Bookmarks via an API Service

8:46 It's likely that you want to be able to consume them from external services, third party systems or even applications on your mobile phone or your desktop. Well, we can do that too. If I run curl and grab this last command, you can see that we can curl Rawkode launchpads dev or dw tech blah blah blah bookmark API two. This is a domain provided by the Guidepad service that exposes my bookmark API, and this is the second time I've done it. Go figure. But if we run this, we can now see the two bookmarks that I created at the start of this

9:21 video. You can see the Rawkode Academy and Mark Zuckerberg and Elon Musk agreeing to fight. So in order to make this work, we had to define a service. Let's pop open our plug in and open our plug in dot py. Here you can see that we expose the Bitmark API as a service on this plug in. This Bitmark API extends the operations API within Guidepad. The operations API allows you to define operations available to query data within the Guidepad system. Here we're extending that remove a whole bunch of boilerplate that would otherwise be required to

9:27 Examining the Service and Operations Code

9:53 expose a flask application on the Guidepad framework. Again, buying in to the Guidepad tracks so that we don't have to do everything ourselves. The only thing that's important in this file is that we give a service type a name, something that uniquely identifies it within the Guidepad system. We then tell it that the endpoints for this API are provided by my plugin operations bookmark. Let's head over there. We open the operations directory and we go to the bookmarks file. Here we're using the blueprint flask functionality to provide new endpoints on our API. Here we can see that on slash we are

10:29 going to list bookmark and we're using the Guidepad base type APIs to fetch those resources. Here we call bookmark dot list with no filters, we use a comprehension to loop over them and we serialize them giving us back the bookmarks object, which we can then turn into JSON and return. It's just that simple. So as a bit of an experiment why don't we add a new piece of functionality to this application. Let's copy our list function like so and this time we're gonna add a to do endpoint which is going to return all of the bookmarks that we haven't

10:51 Adding a Filtered 'To Do' Endpoint

11:05 read yet. We'll call this to do bookmarks. So we don't want to return all bookmarks here, we only want to return the ones where red equals false. So we can add a search like so. However, we want to do no. We want red as false. Now this property doesn't exist on our type yet, so let's make that change. Okay, so let's add a red property to our bookmark type. Here we can set the default equals false, meaning that by default, if there is no property, we assume it is unread or no value at least. So let's deploy this change

11:48 Deploying the Changes (Git Push)

11:48 to the Guidepad system. To do that, we go back to our terminal where we could do git add Guidepad Rawkode and git commit beat add to do endpoint and push. Okay. Now that we've pushed that up, we can run Guidepad, entity, list, bookmark, all bookmarks. However, this time we're only gonna request a few of the attribute. First, the URL, whether it's been read, and then the summary, like so. Now because we pushed our plug in to a remote repository and now we're running the Guidepad CLI, it's going to notice that we need to update the plug in. Do we get pull, check

12:28 the requirements and then we'll have our plug in up to date. So we also added with the latest change our new endpoint pull down any bookmarks that we haven't read yet. We can run a curl pasting in the URL for our service and add our new to do endpoint and pipe it through a JQ. This returns both of our bookmarks because both are currently set to false and unread. So let's go up to this top pane. Now I could do a Guidepad entity edit bookmark and drop in this ID, but I'm just going to create a new

12:33 Testing the Filtered API

13:02 one from a file so you can see that flow and then that'll show us that we have a working filtered API endpoint on the bottom tab too. So we could do entity create bookmark and instead of using the hair dot, we're gonna pull this in from our plugin bookmark dot JSON like so. We can pop over into my editor and you'll see that this bookmark.JSON just has a URL and the red status set to true. So let's run our summary one more time. Nice and if we query our to do endpoint we still have two bookmarks even though above

13:41 we have google.com read true. So that's Guidepad. Guidepad is an extremely flexible, powerful, opinionated tool all at the same time. You get to opt in to the behaviors that you want. If you just want to write some code, have it deployed and exposed to your customers, don't have to worry about databases, you could do that. Join us for the next video where we take a slightly different approach to Guidepad. We'll see you then. Have a great day.