Package Installation Guide

Quick Start

If you want a quick start we recommend starting with the Quick Start Guide to set up your first project quickly.

This guide walks you through installing the aurite Python package and setting up your first Aurite project. This is the recommended path for users who want to build applications using the Aurite framework.

Need to install from the repository?

For instructions on setting up the framework from the main repository (e.g., if you plan to contribute to Aurite's framework), please see the Repository Installation Guide. If this question confuses you, you probably do not need it.

Setup Steps

Environment SetupInitialize Your ProjectStart Building

Before installing, ensure your environment is ready.

Python >= 3.11: The Aurite framework requires Python 3.11 or higher. Check your version with python --version.
Create a Workspace Directory: Choose a location on your computer for your Aurite projects.
```
mkdir my-aurite-workspace
cd my-aurite-workspace
```

Activate a Virtual Environment: It is highly recommended to use a virtual environment.

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install the aurite package:
```
pip install aurite
```
Install Optional Dependencies (Extras): The core aurite package is lightweight. Additional functionality is available through "extras," which can be installed as needed.
- Storage: To use database integrations like Redis or PostgreSQL for session and cache management, install the storage extra:
```
pip install "aurite[storage]"
```
- Machine Learning: For features requiring ML libraries like Pandas or Sentence Transformers, install the ml extra:
```
pip install "aurite[ml]"
```
  You can also install multiple extras at once:
```
pip install "aurite[storage,ml]"
```
Verify the installation:
```
aurite --version
```
This should display the installed version of Aurite (e.g., aurite 0.3.28).

The aurite init command is the easiest way to get started. It runs an interactive wizard to create your workspace and first project.

Run the Interactive Wizard: From your workspace directory (my-aurite-workspace), run:
```
aurite init
```
Follow the Prompts: The wizard will guide you through:
- Creating a .aurite file to define your workspace.
- Creating your first project directory (e.g., my-first-project).
- Generating a default config directory inside your project with example component configurations.
- Creating a .env file in your workspace root for your API keys.
Add Your API Key: Open the newly created .env file in your workspace root and add your LLM API key(s), for example:
```
OPENAI_API_KEY="your-key-here"
ANTHROPIC_API_KEY="your-key-here"
```
If you want to use the built-in Aurite API, you need to add an API_KEY to your .env file. You can set the value for this key to be anything you want, for example:
```
API_KEY=my_api_key
```

Your directory structure should now look like this:

my-aurite-workspace/
├── .aurite                   # Defines the workspace
├── .env                      # Your secret API keys
├── .venv/
└── my-first-project/
    ├── .aurite               # Defines the project
    ├── config/               # Your project's component configs
    │   ├── agents/
    │   ├── llms/
    │   └── ...
    ├── custom_workflows/     # Python source for custom workflows
    │   └── example_workflow.py
    ├── mcp_servers/          # Python source for MCP servers
    │   └── weather_server.py
    └── run_example_project.py  # Script to run an example

The init command populates your project with a rich set of examples, including multiple agent, LLM, and workflow configurations located in the config/ directory. It also provides runnable Python source code for custom workflows and MCP servers.

For a deeper understanding of how projects and workspaces function, see the Projects and Workspaces guide.

With your project initialized, you're ready to start building and running components.

Use the CLI

The Aurite CLI provides commands to manage your project, run agents, and workflows. For example, to run an agent, you can use:

aurite run "Weather Agent" "What is the weather in London?"

For a list of all available commands, you can run:

aurite --help

For more details on using the CLI, see the CLI Reference.

Start the API Server

To interact with your project programmatically or via a UI, start the FastAPI server. From anywhere inside your workspace, run:

aurite api

The API will be available at http://localhost:8000.

For more details on the API endpoints, see the API Reference.

Launch Aurite Studio (Web UI)

For the best development experience, use Aurite Studio - an integrated development environment that provides a web-based UI for managing your agents, workflows, and configurations. From anywhere inside your workspace, run:

aurite studio

This command will: - Automatically start the API server (if not already running) - Launch the React-based web interface at http://localhost:8000/studio (or the port you configured in your .env file) - Handle all frontend dependencies and build processes automatically - Open your default browser to the Studio interface

Aurite Studio provides: - Visual agent configuration and testing - Workflow management and execution - LLM provider setup and testing - MCP server integration - Real-time execution monitoring

System Requirements

Aurite Studio requires Node.js >= 18.0.0 and npm >= 8.0.0. The command will automatically check and try to install if these are missing.

For advanced options like fresh rebuilds, see the CLI Reference.

Edit Configurations

You can edit your component configurations using the aurite edit command, which opens a text editor for the specified component type. For example, to edit agents:

aurite edit agents

You can also edit these configurations directly in the config/ directory using your preferred text editor. See the Component Configurations guide for more details on the configuration structure.