Contribution Guide

Contribution Guide

Run, test, and add features to useLLM and contribute to the project!

If you're interested in contributing to the useLLM project, that's fantastic! This guide will walk you through the setup process.

Step 1: Fork the useLLM Repository

Start by forking the repository. You can do this by visiting the useLLM repository and clicking on the 'Fork' button in the top-right corner. This will create a copy of the repository under your own GitHub account.

Keeping Your Fork Updated

It's important to regularly sync your fork with the main repository. The main repository will continue to receive updates as other contributors make changes.

You can sync your fork directly from GitHub:

  1. Navigate to your forked repository on GitHub.
  2. Click on Sync fork in the repository header.
  3. Click on Update Branch.

After you have synced your fork from GitHub, pull the updates to your local copy of the repository in your development environment:

git checkout main
git pull origin main
git checkout main
git pull origin main

Now, your local copy is in sync with the main repository and you're ready to start contributing!

Step 2: Develop in Codespaces

GitHub Codespaces provides a complete, configurable development environment in seconds.

To open the forked repository in Codespaces follow these steps:

  1. Navigate to your forked repository
  2. Click on the 'Code' button.
  3. Select 'Open with Codespaces'
  4. Finally, Create a new codespace.

example

Directory Structure

Here's a brief overview of the directory structure in the useLLM project:

  • Root Directory: The root directory contains the core files and folders of the project, including README.md, LICENSE, package.json, and .gitignore, among others.

  • /packages/usellm: This directory contains the npm package for the useLLM project. It includes the source code and tests for the React hooks that interface with LLM APIs like Open AI. The package.json in this directory lists the dependencies required for this package.

  • /usellm.org: This directory contains a Next.js application, which serves as the project's documentation site and demo application. Here, you'll find source files, components, pages, styles, and scripts required for the application. The package.json file in this directory lists the dependencies required for this application.

The Next.js application in the usellm.org directory directly copies over the useLLM package in real time during development, making it easy to test changes to the useLLM package.

Step 3: Install Dependencies

Once the codespace is ready and you're in the development environment, you will need to install the necessary dependencies for the project. Navigate to the usellm.org directory in the terminal and run npm install.

cd usellm.org
npm install
cd usellm.org
npm install

Also, navigate to packages/usellm directory in the terminal and run npm install.

cd ..
cd packages/usellm
npm install
cd ..
cd packages/usellm
npm install

Step 4: Add Environment Variables

Before starting the development server, you need to set up some environment variables. The usellm.org application requires your OpenAI API key, ElevenLabs API key and Upstash Redis REST URL and token (see below for details).

In the root directory of the usellm.org application, there's an .env.example file that lists these required variables. Here is what it looks like:

NEXT_PUBLIC_APP_URL=http://usellm.org
OPENAI_API_KEY=XXXX
ELVEN_LABS_API_KEY=xxxx
UPSTASH_REDIS_REST_URL=XXXX
UPSTASH_REDIS_REST_TOKEN=XXXX
NEXT_PUBLIC_APP_URL=http://usellm.org
OPENAI_API_KEY=XXXX
ELVEN_LABS_API_KEY=xxxx
UPSTASH_REDIS_REST_URL=XXXX
UPSTASH_REDIS_REST_TOKEN=XXXX

To set up your environment variables:

  1. Copy the .env.example file and rename the copied file to .env.local.
  2. Replace XXXX with the corresponding keys, token or URL.

Please note, your .env.local file should never be committed to the repository, as it contains sensitive information. Hence it is added to the .gitignore file.

Generating OpenAI API Key

The OpenAI API key is a unique identifier that authorizes and tracks API requests associated with your project. The useLLM project utilizes this key to interface with OpenAI's services and resources, such as the GPT-3.5 model. Without this key, your application wouldn't have the necessary permissions to access these services, thereby inhibiting functionalities associated with OpenAI's AI models.

Here are the steps to Generate OpenAI API Key:

  1. Navigate to OpenAI API Keys page: Start by visiting the OpenAI API Keys page.

  2. Create an Account or Sign In: If you don't already have an OpenAI account, you'll need to create one. If you already have an account, simply click on 'Sign In' and enter your credentials.

  3. Access API Keys Dashboard: Once you're signed in, you'll be directed to the API Keys dashboard. Here, you can manage your existing API keys and create new ones.

  4. Create a New API Key: To create a new API key, click on the 'Create new' or '+ New key' button (depending on the current UI). A new window will open prompting you to provide a description for the key. After filling in the details, click 'Create'.

  5. Copy the API Key: After creating the key, it will be listed in your API Keys dashboard. Make sure to copy the key (a long string of alphanumeric characters) immediately, as you won't be able to view it again once you leave the page or refresh.

example

Generating Eleven Labs API Key

The Eleven Labs API key is a unique identifier provided by Eleven Labs, which allows access to its services, including its text-to-speech feature. This key is essential in the useLLM GitHub Repository to facilitate communication between the user's local development environment and Eleven Labs' cloud-based text-to-speech services. By integrating this feature, users can transform text data into lifelike speech, enhancing the user experience and the overall functionality of the application.

The process of generating an Eleven Labs API key is properly documented in their API Reference Guide.

Here is a gist of how to generate the API key quickly:

  • Create an Elevenlabs Account: Sign up in Elevenlabs here.
  • Navigate to your Profile: After signing up click on your profile icon on the top right corner and select "Profile"
  • Copy the API Key: Your name and API key(hidden) will show up in a pop-up window, unhide the API key and copy it.

example

Generating Upstash Redis Token

The Upstash Redis token is required to connect to your Redis database hosted on Upstash. Redis is an in-memory data structure store used as a database, cache, and message broker. In the context of useLLM, Redis is used for managing session data and other caching needs. The token authenticates your application and ensures secure communication with your Upstash Redis database. Without this token, your application would be unable to interact with the data stored in your Redis database.

Here are the steps to Generate Upstash Redis URL and Token:

  1. Create an Upstash account: Start by creating an account on Upstash, if you don't already have one. Upstash offers a generous free tier that should be more than sufficient for development purposes.

  2. Create a new Redis database: After logging in, navigate to your Upstash dashboard and create a new Redis database by clicking on the 'Create Database' button.

  3. Database Configuration: Choose a name for your database and select the region closest to you. Then, click 'Create' to create the database.

  4. Get your REST URL and Token: Once the database is created, click on the 'REST' tab in the database dashboard. Here, you'll find your REST URL and Token. The URL will be in the format https://xxx.upstash.io, and the token will be a long string of alphanumeric characters.

example

Step 5: Run Development Server

Once the installation process is finished, you can run the development server. In the usellm.org directory, run:

npm run dev
npm run dev

This command starts the development server. Press the "Open in Browser" button or Cmd+Click the localhost URL to view the application in a new tab.

Step 6: Create Feature Branch

Before you start making changes, always create a new branch. Doing so helps isolate your changes and makes it easier to manage them. Avoid making changes directly to the main branch.

To create a new branch open a new terminal window and use the following command:

cd usellm.org
git checkout -b your-branch-name
cd usellm.org
git checkout -b your-branch-name

Replace "your-branch-name" with a descriptive name for your branch (E.x: add-feature or fix-api-error). This name should provide some indication of the changes you're making in the branch.

Step 7: Make Changes

Feel free to make changes to the codebase, either within the usellm.org NextJS app or within the usellm package! The usellm.org application is set up to copy over the usellm package in real time, so any modifications you make to the usellm package can be automatically tested on the usellm.org application.

Here are some good places to start:

  • Improve the documentation by making changes in the folder usellm.org/content/docs (edit the .mdx files)
  • Add or improve/modify demo applications within the usellm.org/app/demo folder
  • Fix bugs or add new features to the usellm package within the packages/usellm folder
  • Browse through open issues on the useLLM repository and see if you can help out!

Step 8: Submit a Pull Request

Once you're satisfied with your changes and they're thoroughly tested, commit them to your branch. Remember, it's a best practice to create a new branch for each feature or bugfix rather than working directly on your main branch.

Push your branch to your remote copy of repository:

git push origin your-branch-name
git push origin your-branch-name

Then, navigate to your original repository on GitHub, where you can create a new pull request by following this guide.

When creating your pull request, be sure to provide a thorough description of your changes, the motivation behind them, and any additional context that would aid the reviewers. Please note that all tests and checks must pass before your changes can be merged.

Thank you for your interest in contributing to useLLM! Your efforts help make this project better for everyone.