UACRAgent logo UACRAgent
Download
GitHub

v0.4.0 · desktop-first · local-trusted API

Study from course documents with a grounded academic assistant.

UACRAgent helps students chat over class materials, reuse persistent study sessions, and generate structured review artefacts only when they actually need them.

View Repository Quick Start
  • Persistent desktop sessions with saved history and workspace reuse
  • RAG-based retrieval with document-type-aware chunking
  • Review summaries, practice booklets, mock exams, and exam predictions

What it does

Built for studying first, generation second.

The current version is centered on guided course review through a persistent assistant workflow, with document generation available as a strong secondary tool.

Grounded study chat

Chat over uploaded course documents with task-aware retrieval and weighted document priorities.

Structured outputs

Generate review summaries, practice booklets, mock exams, and exam predictions when you ask for them.

Persistent workspaces

Desktop sessions, CLI runs, and API runs each keep their own predictable managed workspace roots.

Multiple providers

Use Gemini, OpenAI, or DeepSeek for chat and generation, with cloud or local embeddings depending on your setup.

Desktop-first controls

Attach files via the + button, paste (Cmd/Ctrl+V), or drag-and-drop. Choose effort level, reasoning mode, web search, export format, and session-specific settings from the GUI.

Local retrieval store

Chroma vector indexes stay on your machine, and unchanged workspaces can be reused across session reloads.

How it works

A course-material workflow that stays inspectable.

1

Collect

Add syllabi, lecture notes, textbooks, assignments, past exams, and other files in the interface that fits your workflow.

2

Split

Each document type uses a different chunking strategy so retrieval matches the structure of academic material more closely.

3

Retrieve

Chroma stores local vectors and the assistant retrieves weighted context for chat or study-document generation.

4

Study

Ask grounded questions, request study artefacts, reopen sessions later, and reuse existing indexes when files have not changed.

Interfaces

Three ways to use the same core pipeline.

Desktop GUI

The primary interface for most users.

  • Persistent sessions and saved workspaces
  • Chat, quick actions, export controls, and app settings
  • macOS, Windows, and Linux support

Interactive CLI

A terminal-first study assistant.

  • Indexes once, then enters a chat loop
  • Managed workspaces under cli_run/
  • Best for scriptable local workflows without the GUI

Local FastAPI API

Programmatic one-shot generation for trusted local use.

  • Managed workspaces under api_run/
  • Absolute local markdown_path response
  • Not intended for public or multi-user deployment

Privacy

Local-first working data, provider-dependent requests.

What stays local

  • Session state and chat history
  • Workspace uploads, outputs, and Chroma indexes
  • Local model cache under the app data directory
  • Logs under <app_data_dir>/logs/

What may leave the machine

  • Each chat message — including your text, recent conversation history sent as context, course metadata, and any chat attachments
  • Retrieved document excerpts used for grounded answers and generation
  • Cloud embedding requests when local embeddings are not used
  • Provider-backed web search or attachment processing

The current API is intended for local trusted use only. If you use the FastAPI layer, set UACRAGENT_ALLOWED_BASE_DIR when you want an extra local filesystem boundary.

Get started

Pick the setup path that matches how you want to use it.

Most users should start with the packaged desktop app. Use the source install only if you want development control, the CLI, or the local API.

Desktop app: macOS

  1. Open the Releases page and download the latest macOS build.
  2. Move the app to Applications if you want a normal installed location.
  3. Launch the app. If macOS blocks it because it is from an unidentified developer, open System Settings → Privacy & Security and choose Open Anyway.
  4. On first use, add your provider/API settings and create a session.

Desktop app: Windows

  1. Open the Releases page and download the latest Windows installer (.exe) or portable zip.
  2. Installer: run the setup wizard and follow the prompts. Portable zip: extract and keep the full app folder together.
  3. If Windows SmartScreen warns that the app is from an unknown publisher, click More info → Run anyway.
  4. On first use, add your provider/API settings and create a session.

Source install: macOS / Linux

  1. Clone the repository and open a terminal in the project root.
  2. Create and activate a virtual environment.
  3. Install dependencies and the editable package.
  4. Copy .env.sample to .env, then add your provider/API settings.
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
cp .env.sample .env

Source install: Windows PowerShell

  1. Clone the repository and open PowerShell in the project root.
  2. Create the virtual environment.
  3. If script execution is blocked, temporarily allow activation in the current PowerShell session.
  4. Activate the environment, install dependencies, then copy .env.sample to .env.
py -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .
copy .env.sample .env

After installation

  1. Desktop users: launch the GUI and create a session.
  2. Add course info and course files, then click Apply to index them.
  3. Ask grounded study questions or use the quick actions for Review Summary, Practice Booklet, Mock Exam, or Exam Prediction.
python -m uacragent --gui

CLI or local API

  1. Use the CLI if you want a terminal-first study loop after indexing.
  2. Use the FastAPI layer only for local trusted one-shot generation workflows.
python -m uacragent your_file.pdf --course-name "Your Course Name"

uvicorn uacragent.api.main:app --reload
Open Wiki Read README Downloads

API Keys

Get your API key in minutes.

UACRAgent needs an API key from at least one AI provider to power its chat and document generation. The key must be entered in App Settings each time you launch the app — it is only stored in memory while the app is running and is never written to disk. To skip this step on future launches, you can save the key in a .env file (see the optional guide below). Follow the steps for the provider you want to use.

💡 Not sure which provider to pick? Start with Google Gemini — it has a generous free tier, requires no credit card to try, and works well for all of UACRAgent's study features. Note that the free tier's rate limits are suitable for light, demo-scale tasks; for regular daily use or larger class loads, a paid plan is recommended.

Google Gemini

Free tier available

Accessed through Google AI Studio. No billing setup needed for the free tier. Sign in with any Google account.

  1. Open Google AI Studio in your browser: aistudio.google.com
  2. Sign in with your Google account. No separate account is needed.
  3. Click Get API key in the left sidebar.
    4. Google AI Studio left sidebar showing the Get API key button
  4. Click Create API key. If prompted to choose a Google Cloud project, select any existing project or let it create one automatically.
  5. Your key appears on screen — it starts with AIza. Click the copy icon to copy it.
Where to paste it in UACRAgent App Settings → Provider tab → set Provider to Gemini → paste the key into the API Key field → Save.
Open Google AI Studio →

OpenAI (ChatGPT)

Accessed through the OpenAI Platform. Requires adding billing credit before use. The same account used for ChatGPT can be used here.

  1. Go to the OpenAI Platform and sign in: platform.openai.com
  2. In the left sidebar, click API keys. If you do not see the sidebar, click the menu icon at the top left first.
    3. OpenAI Platform left sidebar showing the API keys navigation item
  3. Click + Create new secret key. Give it a name (e.g. UACRAgent) so you can recognise it later.
  4. Important: copy the key immediately using the copy button. OpenAI shows the full key only once — closing this dialog without copying means you will need to create a new key.
    5. OpenAI Save your key dialog showing the copy button and one-time display warning
  5. If you have not added billing yet, go to Settings → Billing → Add payment method and add a small amount of credit.
Where to paste it in UACRAgent App Settings → Provider tab → set Provider to OpenAI → paste the key into the API Key field → Save.
Open OpenAI Platform →

DeepSeek

Accessed through the DeepSeek Platform. Very low cost per token compared to other providers. Note: DeepSeek does not support image vision inputs — text-only chat and document generation only.

  1. Go to the DeepSeek Platform and sign in: platform.deepseek.com
  2. In the left sidebar, click API keys.
    3. DeepSeek Platform sidebar showing the API keys section
  3. Click Create new API key, give it a name (e.g. UACRAgent).
  4. Copy the key immediately — it is shown only once. Close the dialog and the full key will no longer be visible.
    5. DeepSeek key creation dialog showing the key and copy button
  5. Add credit to your account under Billing if you have not already done so.
Where to paste it in UACRAgent App Settings → Provider tab → set Provider to DeepSeek → paste the key into the API Key field → Save.
Open DeepSeek Platform →

Save your key so you don't have to re-enter it each launch Optional

This is optional — you can always enter your API key manually in App Settings → Provider tab each time you launch the app. If you prefer not to set this up, skip this section entirely.

If you do set it up: UACRAgent reads a configuration file called .env on startup and pre-fills your API key automatically. Set it up once and the app is ready every time you open it — no copy-pasting needed.

Where the file lives

The file goes inside a folder called .uacragent in your personal Home folder — the folder with your name on it. The full path looks like this: 

macOS  :  /Users/YourName/.uacragent/.env
Windows:  C:\Users\YourName\.uacragent\.env

Both the .uacragent folder and the .env file start with a dot (.), which makes them hidden by default on macOS and Windows. That is intentional — it keeps app files tidy and out of sight. The steps below show how to reach and create them without any developer tools.

What to write inside the file

# Google Gemini
GOOGLE_API_KEY=AIzaSy...your-key-here

# OpenAI
OPENAI_API_KEY=sk-...your-key-here

# DeepSeek
DEEPSEEK_API_KEY=sk-...your-key-here

Replace the placeholder with your actual key. Only add the line for the provider you use — you do not need all three.

macOS — step by step

  1. Launch UACRAgent once, then quit it. This creates the .uacragent folder automatically inside your Home folder.
  2. Open TextEdit. Click the magnifying glass 🔍 in the top-right corner of your screen, type TextEdit, and click it in the results.
  3. In TextEdit, click the Format menu in the menu bar → click Make Plain Text.
    ⚠️ This step is essential. Without it, TextEdit saves as rich-text (.rtf) and UACRAgent will not read the file.
  4. Enter your API key in the format shown below. Only include the line for the provider you use: 
    # Google Gemini
GOOGLE_API_KEY=AIzaSy...your-key-here

# OpenAI
OPENAI_API_KEY=sk-...your-key-here

# DeepSeek
DEEPSEEK_API_KEY=sk-...your-key-here
  5. Click File in the menu bar → Save As.
  6. Save the file to your Desktop. In the save dialog, click Desktop in the left sidebar. Change the filename to .env (delete the current name and type .env, starting with a dot).
    ⚠️ macOS will warn: "Are you sure you want to use a name beginning with a dot?" — click Use ".env". This is normal.
  7. Move the .env file into the .uacragent folder. Open a Finder window (click the smiley-face icon in your Dock). In the Finder menu bar, click Go → Go to Folder, then type the path below and click Go: 
    /Users/YourName/.uacragent

    Replace YourName with your Mac username. Don't know it? Click the Apple menu (top-left) → System Settings → click your name. Your username is the shorter name shown below your full name.

  8. The .uacragent folder is now open in Finder. Drag the .env file from your Desktop into this Finder window. (The Desktop is visible in the background — drag the .env icon from there directly into the open folder.)
  9. Launch UACRAgent. The key is loaded automatically — no need to type it in App Settings. ✅

Windows — step by step

  1. Launch UACRAgent once, then close it. This creates the .uacragent folder automatically inside your user folder.
  2. Open Notepad. Click the Start button (Windows logo in the taskbar), type Notepad, and click it in the results.
  3. Enter your API key in the format shown below. Only include the line for the provider you use: 
    # Google Gemini
GOOGLE_API_KEY=AIzaSy...your-key-here

# OpenAI
OPENAI_API_KEY=sk-...your-key-here

# DeepSeek
DEEPSEEK_API_KEY=sk-...your-key-here
  4. Click File → Save As.
  5. Save the file to your Desktop. In the Save As dialog, click Desktop in the left panel.
  6. Change the Save as type dropdown to All Files (*.*).
    ⚠️ This step is essential. Without it, Notepad silently adds .txt and UACRAgent will not read the file.
  7. In the File name box, delete the current name and type .env (starting with a dot, nothing after). Click Save.
  8. Move the .env file into the .uacragent folder. Open File Explorer (click the folder icon in your taskbar). Click the address bar at the top so it becomes editable, type the path below, and press Enter: 
    %USERPROFILE%\.uacragent

    %USERPROFILE% is Windows' built-in shortcut for your personal user folder — for example C:\Users\John if your username is John.

  9. The .uacragent folder is now open in File Explorer. Go back to your Desktop, right-click the .env file → Copy. Then click inside the File Explorer window and right-click an empty area → Paste.
  10. Launch UACRAgent. The key is loaded automatically — no need to type it in App Settings. ✅

🔒 Security reminder: treat your API key like a password. NEVER share it, NEVER paste it into a chat, and NEVER commit it to a public repository. If a key is accidentally exposed, delete it from the provider dashboard immediately and create a new one.

Credits

UACRAgent is an independent open-source project. Thanks to everyone who helped make it better.

Volunteer Testers

Thanks to the volunteer test users who helped exercise the desktop assistant, retrieval flow, workspace handling, and study-support UX during development. Their feedback helped shape the agent into what it is today.

  • Bob Bao

Built On Open Source

UACRAgent stands on the shoulders of many excellent open-source projects. Key components include:

AI Providers

The following providers power UACRAgent's language and embedding models:

  • Google Gemini — chat, planning, writing, and embeddings
  • OpenAI — chat, planning, writing, and embeddings
  • DeepSeek — chat, planning, and writing

UACRAgent is not affiliated with, endorsed by, or officially connected to any of these providers.