Quickstart

The Modus CLI provides a set of commands to help you create, build, and run your Modus apps. Install the CLI using npm.

npm install -g @hypermode/modus-cli

To create a new Modus app, run the following command in your terminal:

modus new

This command prompts you to choose between Go and AssemblyScript as the language for your app. It then creates a new directory with the necessary files and folders for your app. You will also be asked if you would like to initialize a Git repository.

To build and run your app, navigate to the app directory and run the following command:

modus dev

This command runs your app locally in development mode and provides you with a URL to access your app’s generated API.

Once your app is running, you can access the graphical interface for your API at the URL located in your terminal.

View endpoint: http://localhost:8686/explorer

The API Explorer interface allows you to interact with your app’s API and test your functions.

Modus is a secure-by-default framework. To connect to external services, you need to add a connection in your app manifest.

Add the following code into your modus.json manifest file:

{
  "connections": {
    "zenquotes": {
      "type": "http",
      "baseUrl": "https://zenquotes.io/"
    }
  }
}

Modus also supports AI models. You can define new models in your modus.json file. Let’s add a new meta-llama model:

"models": {
    "text-generator": {
      "sourceModel": "meta-llama/Llama-3.2-3B-Instruct",
      "provider": "hugging-face",
      "connection": "hypermode"
    }
  },

Next, install the Hyp CLI. This allows you to access hosted models on the Hypermode platform.

npm install -g @hypermode/hyp-cli

You can now use the hyp login command to log in to the Hyp CLI. This links your project to the Hypermode platform, allowing you to leverage the model in your modus app.

Functions are the building blocks of your app. Let’s add a function that fetches a random quote from the ZenQuotes connection and uses AI to generate a summary for the quote.

package main

import (
  "errors"
  "fmt"
  "strings"

  "github.com/hypermodeinc/modus/sdk/go/pkg/http"
  "github.com/hypermodeinc/modus/sdk/go/pkg/models"
  "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai"
)

type Quote struct {
  Quote   string `json:"q"`
  Author  string `json:"a"`
  Summary string `json:"summary,omitempty"`
}

const modelName = "text-generator"

// this function makes a request to an API that returns data in JSON format,
// and returns a single quote with AI-generated summary
func GetRandomQuote() (*Quote, error) {
  request := http.NewRequest("https://zenquotes.io/api/random")

  response, err := http.Fetch(request)
  if err != nil {
    return nil, err
  }
  if !response.Ok() {
    return nil, fmt.Errorf("failed to fetch quote. Received: %d %s", response.Status, response.StatusText)
  }

  // the API returns an array of quotes, but we only need the first one
  var quotes []Quote
  response.JSON(&quotes)
  if len(quotes) == 0 {
    return nil, errors.New("expected at least one quote in the response, but none were found")
  }

  // Get the first (and only) quote
  quote := quotes[0]

  // Generate AI summary for the quote
  summary, err := summarizeQuote(quote.Quote, quote.Author)
  if err != nil {
    fmt.Printf("Warning: failed to summarize quote by %s: %v\n", quote.Author, err)
    quote.Summary = "Summary unavailable"
  } else {
    quote.Summary = summary
  }

  return &quote, nil
}

// summarizeQuote uses the AI model to generate a concise summary of the quote
func summarizeQuote(quote, author string) (string, error) {
  model, err := models.GetModel[openai.ChatModel](modelName)
  if err != nil {
    return "", err
  }

  instruction := "Provide a brief, insightful summary that captures the essence and meaning of the quote in 1-2 sentences."
  prompt := fmt.Sprintf("Quote: \"%s\" - %s", quote, author)

  input, err := model.CreateInput(
    openai.NewSystemMessage(instruction),
    openai.NewUserMessage(prompt),
  )
  if err != nil {
    return "", err
  }

  // Set temperature for consistent but creative responses
  input.Temperature = 0.7

  output, err := model.Invoke(input)
  if err != nil {
    return "", err
  }

  return strings.TrimSpace(output.Choices[0].Message.Content), nil
}

package main

import (
  "errors"
  "fmt"
  "strings"

  "github.com/hypermodeinc/modus/sdk/go/pkg/http"
  "github.com/hypermodeinc/modus/sdk/go/pkg/models"
  "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai"
)

type Quote struct {
  Quote   string `json:"q"`
  Author  string `json:"a"`
  Summary string `json:"summary,omitempty"`
}

const modelName = "text-generator"

// this function makes a request to an API that returns data in JSON format,
// and returns a single quote with AI-generated summary
func GetRandomQuote() (*Quote, error) {
  request := http.NewRequest("https://zenquotes.io/api/random")

  response, err := http.Fetch(request)
  if err != nil {
    return nil, err
  }
  if !response.Ok() {
    return nil, fmt.Errorf("failed to fetch quote. Received: %d %s", response.Status, response.StatusText)
  }

  // the API returns an array of quotes, but we only need the first one
  var quotes []Quote
  response.JSON(&quotes)
  if len(quotes) == 0 {
    return nil, errors.New("expected at least one quote in the response, but none were found")
  }

  // Get the first (and only) quote
  quote := quotes[0]

  // Generate AI summary for the quote
  summary, err := summarizeQuote(quote.Quote, quote.Author)
  if err != nil {
    fmt.Printf("Warning: failed to summarize quote by %s: %v\n", quote.Author, err)
    quote.Summary = "Summary unavailable"
  } else {
    quote.Summary = summary
  }

  return &quote, nil
}

// summarizeQuote uses the AI model to generate a concise summary of the quote
func summarizeQuote(quote, author string) (string, error) {
  model, err := models.GetModel[openai.ChatModel](modelName)
  if err != nil {
    return "", err
  }

  instruction := "Provide a brief, insightful summary that captures the essence and meaning of the quote in 1-2 sentences."
  prompt := fmt.Sprintf("Quote: \"%s\" - %s", quote, author)

  input, err := model.CreateInput(
    openai.NewSystemMessage(instruction),
    openai.NewUserMessage(prompt),
  )
  if err != nil {
    return "", err
  }

  // Set temperature for consistent but creative responses
  input.Temperature = 0.7

  output, err := model.Invoke(input)
  if err != nil {
    return "", err
  }

  return strings.TrimSpace(output.Choices[0].Message.Content), nil
}

import { http, models } from "@hypermode/modus-sdk-as";
import {
  OpenAIChatModel,
  SystemMessage,
  UserMessage,
} from "@hypermode/modus-sdk-as/models/openai/chat";

@json
class Quote {
  @alias("q")
  quote!: string;

  @alias("a")
  author!: string;

  summary?: string;
}

const modelName: string = "text-generator";

// this function makes a request to an API that returns data in JSON format,
// and returns a single quote with AI-generated summary
export function getRandomQuote(): Quote {
  const request = new http.Request("https://zenquotes.io/api/random");

  const response = http.fetch(request);
  if (!response.ok) {
    throw new Error(
      `Failed to fetch quote. Received: ${response.status} ${response.statusText}`,
    );
  }

  // the API returns an array of quotes, but we only need the first one
  const quotes = response.json<Quote[]>();
  if (quotes.length === 0) {
    throw new Error("Expected at least one quote in the response, but none were found");
  }

  // Get the first (and only) quote
  const quote = quotes[0];

  // Generate AI summary for the quote
  try {
    quote.summary = summarizeQuote(quote.quote, quote.author);
  } catch (error) {
    console.log(`Warning: failed to summarize quote by ${quote.author}: ${error}`);
    quote.summary = "Summary unavailable";
  }

  return quote;
}

// summarizeQuote uses the AI model to generate a concise summary of the quote
function summarizeQuote(quote: string, author: string): string {
  const model = models.getModel<OpenAIChatModel>(modelName);

  const instruction = "Provide a brief, insightful summary that captures the essence and meaning of the quote in 1-2 sentences.";
  const prompt = `Quote: "${quote}" - ${author}`;

  const input = model.createInput([
    new SystemMessage(instruction),
    new UserMessage(prompt),
  ]);

  // Set temperature for consistent but creative responses
  input.temperature = 0.7;

  const output = model.invoke(input);
  return output.choices[0].message.content.trim();
}

export * from "./quotes";

Now that you’ve integrated the AI model, let’s test it! After adding your function, restart your development server:

modus dev

Navigate to the API Explorer at http://localhost:8686/explorer and you’ll see your randomQuote function available to test.

When you call the function, you’ll notice that the quote includes three fields:

• quote: The original quote text
• author: The author’s name
• summary: An AI-generated summary that captures the essence of the quote

The AI model analyzes the quote and provides insightful context about its meaning, making your app more engaging and informative for users.

Try calling the function multiple times to see how the AI generates different summaries for various quotes!

When testing an AI app locally, Modus records the inference and related metadata in the View Inferences tab of the APIs explorer.

You can now see detailed information about each AI model call, including:

• Input prompts sent to the model
• Generated responses
• Performance metrics like response time
• Token usage and costs