<script src="https://rawcdn.githack.com/oscarmorrison/md-page/master/md-page.js"></script><noscript>


# Welcome to Genius DevCamp!

## Build the Future of AI-Powered Recommendations

**Genius DevCamp** is your chance to push the boundaries of self-learning AI and create applications that evolve with user interactions. Over the next **48 hours**, you'll gain exclusive access to the **Genius Platform**, a cutting-edge system designed to continuously learn, adapt, and improve in real time.

Whether you're building a **smart music discovery engine**, a **personalized news feed**, or a **next-gen shopping experience**, this event is all about harnessing AI to deliver truly intuitive recommendations. Instead of relying on static rules, your project will dynamically adjust based on user behavior—leading to smarter suggestions, deeper engagement, and more impactful experiences.

This guide will walk you through everything you need to get started with the **[Genius DevCamp Hackathon API](https://app.productgenius.io/hackathon/docs)**—so you can bring your vision to life and build something game-changing.

Check out the [Discord server](https://discord.gg/pfmWbuaf) for more information!

Video tutorials of each step are available [here](https://drive.google.com/drive/folders/1yV7cj4hBk0XtD9yOCev9oDxAwTRmXGXR?usp=drive_link).

---

## 🔑 Brass Tacks

You'll be leveraging the **Genius Platform** to build your project. That means that we'll take care of the infrastructure, DB management, etc. You'll just need to 
upload some quality Genius Items and define some high-level instructions for the AI to follow. From there, you can choose to extend our [existing client code](https://github.com/gamalon/genius-hackathon-skeleton) to build your UI or you can leverage the available endpoints to build your own. In past hackathons we've seen some really creative projects so we're excited to see what you all come up with!

<details>
<summary><strong>🔒 Authentication</strong></summary>

All requests to the Genius Platform need to be authenticated. To start, you'll be given basic auth credentials that allow you to access the API documentation and 
to create a project.

```
curl -X 'POST' \
'https://app.productgenius.io/hackathon/project/create?project_name=fly_finder' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-u 'USERNAME':'PASSWORD' \
-d '{
"hacker_email": "jamie.lovette@productgenius.io",
"project_name": "fly_finder",
"project_summary": "Fly Finder is an AI-powered recommendation system that helps anglers discover the perfect fly-fishing flies based on their unique fishing style, target species, and local conditions. This self-learning feed evolves with each interaction, refining recommendations based on user preferences—whether they favor dry flies, nymphs, streamers, or emergers. By analyzing behavior, such as flies previously used, water conditions, and fishing locations, Fly Finder dynamically suggests the most effective patterns, materials, and techniques. Whether you'\''re fishing for trout in mountain streams, bass in warm water, or steelhead in the Pacific Northwest, this AI-driven system ensures you'\''re always casting with the best fly for the job."
}'
```

Upon creating a project, you'll receive an access token that will be used for all subsequent requests to the API:

```json
{
    "project_name": "fly_finder",
    "project_summary": "Fly Finder is an AI-powered recommendation system that helps anglers discover the perfect fly-fishing flies based on their unique fishing style, target species, and local conditions. This self-learning feed evolves with each interaction, refining recommendations based on user preferences—whether they favor dry flies, nymphs, streamers, or emergers. By analyzing behavior, such as flies previously used, water conditions, and fishing locations, Fly Finder dynamically suggests the most effective patterns, materials, and techniques. Whether you're fishing for trout in mountain streams, bass in warm water, or steelhead in the Pacific Northwest, this AI-driven system ensures you're always casting with the best fly for the job.",
    "hacker_email": "jamie.lovette@productgenius.io",
    "access_token": "8f5a1279-086d-4ad6-b4de-3245f16e4bdf"
}
```

Submit this access token in the `Authorization` header for all subsequent requests to the API:

```
curl -X 'GET' \
  'https://app.productgenius.io/hackathon/project/fly_finder' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 8f5a1279-086d-4ad6-b4de-3245f16e4bdf'
```

If you lose your access token, you can always retrieve it by making a request to the `GET /hackathon/project/{project_name}/token` endpoint which will send an email to the project owner.


✨ Tip: Using a GUI like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/) is a great way to test out the endpoints before you start building your own client!

</details>

<details>
<summary><strong>🌐 Domain</strong></summary>

The domain for the Genius Platform is `https://app.productgenius.io`

</details>

---

## 🚀 Getting Started

Before you can start serving **self-learning feeds**, we'll need to set up a few things...

<details>
<summary><strong>Step 1: Create Your Project</strong></summary>

Every team must start by creating a project. This will serve as your workspace for defining AI-driven recommendations. The project name you submit will be the unique identifier for your project, make sure it's something meaningful to you and your team! All additional data will be associated with the project you create here.

✨ Tip: You can create multiple projects if you have multiple ideas. Each project will be a new "blank slate" so to speak. They will all be owned by your hacker email address.

✨ Tip: The more information you can provide the better. Make your project summary descriptive and helpful, something that will help your AI model understand your project and your future feed visitors!

```
POST /hackathon/project/create
```

#### Example Request Body:
```json
{
  "project_name": "sound_scout_ai",
  "project_summary": "SoundScout AI is an intelligent local band recommendation system designed to connect music lovers with live performances in their area. By leveraging self-learning AI, SoundScout dynamically adapts to user preferences, surfacing the best upcoming concerts, emerging artists, and hidden gems in the local music scene. Whether a user is into indie rock, jazz, electronic, or folk, SoundScout analyzes listening history, venue preferences, and artist similarities to curate personalized show recommendations. The platform ensures music fans never miss out on great performances while helping local artists reach the right audience.",
  "hacker_email": "jamie.lovette@productgenius.io"
}
```

Video tutorial [here](https://drive.google.com/file/d/129GVVN7o18WLpZV75FpLqp96qbfEtJ-M/view?usp=drive_link).

</details>

---

<details>
<summary><strong>Step 2: Upload Genius Items</strong></summary>

Genius Items are the core components that your recommendation system will serve. Think restaurants for a foodie, news articles for a politics junkie, etc. In our example we are using bands and upcoming concerts that will be shown to someone scrolling through a feed of music recommendations. In order for the AI to make recommendations, it needs to know about the items in your system, so load up on the descriptions and metadata.

✨ Tip: Upload as many items as you can. You'll be able to easier discern the impacts of the self learning model if you have a broader dataset that can be honed.


`id` - A unique identifier for the genius item. If you are referencing external sources, this might help you link the genius item response back to the original. If you don't submit an `id`, a UUID will be generated for you.


```
POST /hackathon/project/{project_name}/items/create
```

#### Example Request Body:
```json
[
    {
        "title": "The Midnight Echo",
        "description": "A high-energy indie rock band known for their electrifying live performances and catchy hooks.",
        "image_url": "https://example.com/images/the-midnight-echo.jpg",
        "external_url": "https://bandsite.com/the-midnight-echo",
        "id": "band_001",
        "metadata": [
            {"name": "genre", "value": "indie rock"},
            {"name": "event type", "value": "live music"},
            {"name": "style", "value": "alternative"},
            {"name": "energy level", "value": "high energy"}
        ]
    },
    {
        "title": "Jazz & The City",
        "description": "A soulful jazz quartet featuring smooth saxophone solos and laid-back grooves, perfect for a relaxed evening.",
        "image_url": "https://example.com/images/jazz-and-the-city.jpg",
        "external_url": "https://bandsite.com/jazz-and-the-city",
        "id": "band_002",
        "metadata": [
            {"name": "genre", "value": "jazz"},
            {"name": "type", "value": "instrumental"},
            {"name": "event type", "value": "live performance"},
            {"name": "mood", "value": "soulful"}
        ]
    }
]
```

Once you've uploaded some items, you can validate that they've been uploaded successfully or update their details using the unique `id`.

```
GET /hackathon/{project_name}/items/{item_id}
PUT /hackathon/{project_name}/items/{item_id}/update
```

Video tutorial [here](https://drive.google.com/file/d/1hZmWsB0cx-0XECoy_5UtE_C2Na84flqW/view?usp=drive_link).

</details>

---

<details>
<summary><strong>Step 3: Define Model Instructions</strong></summary>

Define the high-level instructions that guide how your model will serve recommendations. While the model will learn about your visitors as they scroll and adapt to their reactions, it is important to seed some baseline guidance.

#### API Endpoint:
```
POST /hackathon/{project_name}/model/instruction/create
```

#### Example Request Body:
```json
[
    {
        "promptlet": "People who like Guns and Roses like quality music, recommend concerts and venues that have a crunchy, classical rock sound"
    },
    {
        "promptlet": "If someone likes EDM, broaden their recommendations to house and electro, but don't recommend anything with a country or R&B sound"
    }
]
```

Once you've defined your instructions, you can fetch or update them accordingly:

```
GET /hackathon/{project_name}/model/instruction
```

#### Example Response Body:
```json
[
    {
        "promptlet_id": "8a29547a-0a10-4560-ac6e-8b24325c120d",
        "created_at": "2024-01-01T00:00:00Z",
        "promptlet": "People who like Guns and Roses like quality music, recommend concerts and venues that have a crunchy, classical rock sound"
    }
]
```

Video tutorial [here](https://drive.google.com/file/d/1RYSzVJh9HPaFu1ICcxJmrFfksZze-_z7/view?usp=drive_link).

</details>

---

<details>
<summary><strong>Step 4: Train & Deploy Your Model</strong></summary>

Once your **items** and **rules** are in place, trigger your genius model generation. This can take up to a few hours; now would be a good time to grab a coffee or stretch the legs. 

✨ Tip: If you've entered an email address we'll send you a notification when your model is ready.

#### API Endpoint:
```
POST /hackathon/{project_name}/model/create
```

Beyond training, we leverage extensive constitutional modeling and internal testing to ensure that your model is ready for prime time. Those results get all wrapped up into the accuracy field attached to the model object. We expect good results out of the box, but you can always generate new models you need to add additional genius items, rewrite the global instructions, etc. 


After training, you'll need to promote your chosen model to serve live recommendations.

#### API Endpoint:
```
POST /hackathon/{project_name}/model/{model_id}/promote
```

Video tutorial [here](https://drive.google.com/file/d/1n6ZvC0pv5qHxWJPrWTrhJUnwTB1XDcbQ/view?usp=drive_link).

</details>

---

<details>
<summary><strong>Step 5: Innovate!</strong></summary>

Now you are ready to serve recommendations! To start, you may want to consult the [client code skeleton](https://github.com/gamalon/genius-hackathon-skeleton) which provides much of the overhead described below out-of-the-box. If you want to build your own client, you can use the same endpoints!

In the API documentation you'll find a section on [Feeds](https://app.productgenius.io/hackathon/docs#/Feed) with two endpoints: `/feed/{session_id}` and `/batch/{session_id}`. These two endpoints are the core way to leverage the Genius model to serve recommendations to your visitors. The underlying mechanics of these endpoints are the same, but the return types are different. `/feed` returns a list of `Card` objects which can be used by our client skeleton for easy display, while `/batch` returns a the equivalent list of `GeniusItem` identifiers. Same recommendation engine, different format.

```
POST /hackathon/{project_name}/feed/{session_id}  -> List[Card]
POST /hackathon/{project_name}/batch/{session_id} -> List[Genius Item IDs]
```

Every visitor session must be assigned a unique `session_id`. This `session_id` will be used to serve personalized recommendations based on what the visitor has been previously shown and their subsequent interactions.

Now, let's suppose you are going to be using the client skeleton. Off the bat, the displayed feed will be seeded with an initial batch of recommendations:

```
POST /hackathon/fly_finder/feed/d9a510fb-10a9-4c76-981e-9988559142f8

Payload:
{
    "page": 1,  // The page number of the feed to serve
    "page_size": 10 // The number of recommendations to serve in the next batch
}
```

For there, the visitor may linger on a few specific cards. Once they've scrolled through the initial batch, they'll be shown a new batch of recommendations. The next query will include linger events for the cards they interacted with:

```
POST /hackathon/fly_finder/feed/d9a510fb-10a9-4c76-981e-9988559142f8

Payload:
{
    "page": 2,
    "page_size": 10
    {
        "event": "feed linger metrics",                             // Event type - static `feed linger metrics` leave unchanged
        "properties": {
            "organization_id": "fly_finder",                        // project_name
            "visitor_id": "6ee0e958-adb0-49b4-8415-31556bef71e9",   // visitor_id - client generated and managed
            "session_id": "d9a510fb-10a9-4c76-981e-9988559142f8",   // session_id - client generated and managed
            "payload": {
                "9bc3bfb0-5ef8-4594-aa85-93c36afd1188": {           // Unique payload ID - client generated and managed
                    "time": 6.8,                                    // The time the visitor spent on this Genius Item
                    "id": "27Y0",                                   // The unique identifier of the Genius Item
                    "type": "product_detail_card",                  // Card type - static `product_detail_card` leave unchanged
                    "enter_count": 1,                               // Number of times the Genius Item has entered the viewport in this session
                },
                "2f48fa05-3089-483a-bd2e-a75bc4d1ba40": {
                    "time": 6.84,
                    "id": "3MS8",
                    "type": "product_detail_card",
                    "enter_count": 1,
                },
                "ba54faeb-040b-4227-a052-8983242b02bd": {
                    "time": 6.88,
                    "id": "96AH",
                    "type": "product_detail_card",
                    "enter_count": 1,
                },
            },
        },
    },
}
```

As the visitor continues to scroll, the feed will continue to update with new recommendations based on their interactions...

If you want to implement your own interaction mechanics, you can use the `abstract interest` event to drive recommendations, ie.

```
POST /hackathon/fly_finder/feed/d9a510fb-10a9-4c76-981e-9988559142f8

Payload:
{
    "page": 2,
    "page_size": 10,
    "events": [
        {
            "event": "abstract interest",                               // Event type - static `abstract interest` leave unchanged
            "properties": {
                "organization_id": "fly_finder",                        // project_name
                "visitor_id": "6ee0e958-adb0-49b4-8415-31556bef71e9",   // visitor_id - client generated and managed
                "session_id": "d9a510fb-10a9-4c76-981e-9988559142f8",   // session_id - client generated and managed
                "id": "02J0",                                           // genius_item_id
                "weight": 4,                                            // weight - negative values indicate disinterest while positive values indicate interest
            }
        },
        {
            "event": "abstract interest",
            "properties": {
                "organization_id": "fly_finder",
                "visitor_id": "6ee0e958-adb0-49b4-8415-31556bef71e9",
                "session_id": "d9a510fb-10a9-4c76-981e-9988559142f8",
                "id": "96AH",
                "weight": -1,
            }
        }
    ]
}
```

In the example above, the visitor has shown interest in the fly "02J0" and disinterest in the fly "96AH". The hacker is responsible for establishing their own scale - in this case, the value of 4 denotes a signficantly stronger interest in 02J0 than they are disinterested in 96AH. Weights are unbounded and are scaled to the range of project-associated events. The model will use this information to update the recommendations it serves to the visitor. Using this mechanism, you could implement your own interaction mechanics, such as a "thumbs up/down" or "like/dislike" button, swipes, etc. 

Positive weights demonstrate interest in the shown item, while negative weights demonstrate disinterest. 

Finally, you can also seed the next batch of recommendations with a search prompt. Suppose that you have a search bar on your page, you can use the `search` event to drive recommendations based on the search query. Here's an example:

```
POST /hackathon/fly_finder/feed/d9a510fb-10a9-4c76-981e-9988559142f8

Payload:
{
    "page": 1,
    "page_size": 10,
    "search_prompt": "Show me flies that are good for a trip to the Florida Keys"  // search_prompt - string
}
```

As we say every day after our morning meeting, **happy coding!**

Video tutorial [here](https://drive.google.com/file/d/1UrZ5NF9xplIvDbbQoVJyBoMfXjACM9Xf/view?usp=drive_link).

</details>

---

## ❓ Need Help?

📖 View the **full API documentation** [here](https://app.productgenius.io/hackathon/docs).  
💬 If you need assistance, jump into our **Discord** and chat with our team!

---