Getting Started

Getting Started

This page explains how to set up and run UACRAgent from source.

Requirements

• Python 3.10+
• One supported LLM provider for generation:
  • Gemini
  • OpenAI
  • DeepSeek
• One embedding option:
  • Gemini embeddings
  • OpenAI embeddings
  • Local embeddings

Install

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Windows PowerShell

py -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .

Windows cmd

py -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt
pip install -e .

If activation causes trouble on Windows, you can also run the virtual-environment Python directly:

.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e .

Configure

Copy the sample environment file.

macOS / Linux

cp .env.sample .env

Windows

copy .env.sample .env

Then edit .env and set your provider configuration.

Example:

LLM_PROVIDER=gemini
LLM_MODEL=gemini-2.5-flash
GOOGLE_API_KEY=your_key_here
EMBEDDING_PROVIDER=gemini
EMBEDDING_MODEL=gemini-embedding-001

Run

Desktop GUI

python -m uacragent --gui

CLI

python -m uacragent your_file.pdf --course-name "Your Course Name"

API

uvicorn uacragent.api.main:app --reload

Recommended First Use

1. Start the desktop GUI.
2. Create a session.
3. Add course information.
4. Add course files by document type.
5. Click Apply to index the files.
6. Ask study questions or request generated study materials.