Getting Started

Welcome to the Quick Start Guide for STELLA! This guide will help you set up STELLA quickly and efficiently.

Prerequisites

Before you begin, ensure you have the following:

  • Python 3.9 – 3.12 installed.

  • Latest version of pip (23.3.2+)

  • Git installed for cloning the repository.

  • Basic familiarity with command-line operations.

Step 1: Clone the Repository

Clone the STELLA repository using your preferred method:

HTTPS:

git clone https://github.com/Norditech-AB/STELLA.git

SSH:

git clone git@github.com:Norditech-AB/STELLA.git

GitHub CLI:

gh repo clone Norditech-AB/STELLA

Step 2: Upgrade pip

Our framework is so modern that it needs the latest and greatest pip version (23.3.2) to keep up! If your pip isn’t this hip, it’s time for an upgrade party:

pip install --upgrade pip

Step 3: Install Dependencies

It is now time to install the dependencies.

Tip

Create a virtual environment to isolate the dependencies from other projects. Simply run

python -m venv venv

to create a virtual environment named venv in the current directory.

Then on MacOS/Unix run:

source venv/bin/activate

or on Windows:

venv\Scripts\activate

to activate the virtual environment.

Install dependencies by running the following command from the project directory:

pip install -e .

Note

make sure to use the -e flag to install the dependencies in editable mode. This will allow you to make changes to the code and have them reflected in the installed package.

Optional: Install Documentation Dependencies (for contributors)
pip install -e ".[dev]"

Step 4: Setup the Environment

Quickly Configure STELLA by running stella configure: This will walk you through the setup process and create a .env file in the app directory.

stella configure

Note

You need an api key from OpenAI to use the agent. Read more about how to get one here and paste it into the prompt.

Step 5: Start the Server

With the environment configured, start the server by running stella serve:

stella serve

Step 6: Explore and create in the CLI

Open a new terminal window and run stella to move into the CLI. This will open a Python shell with the STELLA environment loaded. You can now explore the framework and create your own agents.

stella

Step 7: Register an account and start chatting

Create and configure your workspace using the CLI:

  1. Register:

    /register

Enter your username and password to register an account.

Note

This data is stored in your local database and is not shared with anyone.

  1. Start chatting with STELLA:

Now you are ready to start chatting with STELLA. The default Weather agent is already installed so you can start chatting with it right away by adding it to your workspace:

/add demo_weather_agent

Let’s see what the weather is like in Stockholm:

What is the weather in Stockholm?

Tip

Add agents to your workspace (replace <agentid> with the actual agent ID):

/add <agentid>

Use the /help command to see all available commands:

/help

Step 7 (OPTIONAL): Configure the .env File

To customize your STELLA environment, you can update the .env file in the root directory. This file contains all the environment variables used by STELLA. Navigate to the STELLA directory and update the .env file with your information:

#
# Environment Variables for STELLA
#
# To get started, run setup.py and follow the instructions.
# For detailed information, visit https://docs.stellaframework.com/ and search for "Environment Variables"
#
# ================================
# STELLA Configuration
# ================================
HOST="0.0.0.0"                              # Host to run the server on
PORT="5001"                                 # Port to run the server on

BCRYPT_SALT=""                              # Generated by stella configure
JWT_SECRET_KEY=""                           # Generated by stella configure
JWT_ACCESS_TOKEN_EXPIRES="7"                # How long user access tokens will be valid (in days)

SOCK_SERVER_OPTIONS_PING_INTERVAL="150"     # time interval between each ping message (in seconds)
ASYNC_MODE="gevent"                         # gevent is recommended
FLASK_CONFIG="development"                  # development, production (development enables debug mode)

AGENT_MAX_DEPTH="999"                       # Max amount of calls for a single agent when solving a task
OVERALL_TASK_MAX_DEPTH="999"                # Maximum depth (agent calls) a task can have before it is stopped

# Dependencies
OPENAI_API_KEY=""                           # OpenAI API key can be found on your OpenAI profile page


# ================================
# Database Configuration
# ================================
DATABASE="sqlite"                           # sqlite, mongodb (default: sqlite, not recommended for production)

# >>> MongoDB Configuration (ignore if you are not using MongoDB) – note: MongoDB Atlas is recommended for production
MONGO_URI=""                                # URI to your MongoDB cluster
MONGO_DB_NAME=""                            # Name of the database to use

# >>> SQLite Configuration (ignore if you are not using SQLite)
SQLITE_DB_PATH="sqlite.db"                  # Path to the SQLite database file
# Note: If you change the database path, you should update .gitignore to ignore the new database path


# ================================
# Package Manager
# ================================
PACKAGE_MANAGER_URL="https://download-package-d6iaqsbjgq-uc.a.run.app"

Each placeholder should be replaced with your specific values. For instance, OPENAI_API_KEY requires a valid API key from OpenAI.

Tip

Visit the Environment Variables section for detailed guidance on setting up each variable.

Note

The FLASK_CONFIG variable is set to development by default. This is not recommended for production environments.

Next Steps

Congratulations on setting up STELLA! Now, you’re ready to dive deeper:

  • Explore more default agents provided in /app/agents/DefaultAgents to get a feel for STELLA’s capabilities.

  • Learn how to create your first agent in the Create a New Agent guide.