Skip to content

Desktop Guide

Jump to bottom
Joe Xu edited this page May 29, 2026 · 3 revisions

Desktop Guide

The desktop GUI is the main interactive interface for UACRAgent.

Use the desktop app when you want:

  • persistent study sessions
  • chat over course materials
  • quick actions for study-document generation
  • session history and saved workspaces
  • richer controls than the CLI or API

Launch

You can start the desktop app in any of these ways:

python -m uacragent --gui
python -m uacragent
python -m uacragent.ui.desktop.app

What the Desktop App Can Do

  • create, rename, delete, and reopen study sessions
  • choose an LLM provider and model per session
  • choose an embedding provider
  • use free local embeddings
  • classify course files by document type
  • index course materials into a local Chroma database
  • chat over the indexed materials
  • generate review summaries, practice booklets, mock exams, and exam predictions
  • open generated outputs from the chat transcript
  • manage shared app settings such as theme, font size, language, and app data folder

Recommended Workflow

  1. Launch the desktop app.
  2. Accept the privacy notice on first launch.
  3. Create a new session from the sidebar.
  4. Open Settings.
  5. Enter a course name.
  6. Choose your LLM provider and model.
  7. Add the matching API key if it is not already loaded from .env.
  8. Choose an embedding provider.
  9. Add course files into the correct document buckets.
  10. Optionally fill in exam settings and course details.
  11. Optionally choose a custom workspace folder before the first Apply.
  12. Click Apply.
  13. Wait for indexing to finish.
  14. Ask questions in chat or use quick actions to generate study documents.

What Apply Does

When you click Apply, the app:

  • commits the current session settings
  • saves the session to disk
  • locks in the workspace folder for that session
  • copies uploaded files into the workspace when needed
  • copies the exam-info sheet into the workspace when used
  • removes old copied exam-info files when that setting is changed or cleared later
  • builds or refreshes the local Chroma index
  • makes the current provider, embedding, and model settings take effect

Course Files and Document Types

The desktop app lets you organize files into these buckets:

  • syllabus
  • lecture_note
  • textbook
  • assignment
  • past_exam
  • other

Using the most accurate bucket improves retrieval quality.

Chat and Generation

After indexing, you can:

  • ask grounded study questions
  • request explanations of topics from the uploaded material
  • ask what to focus on for an exam
  • generate study documents from quick actions or natural-language requests

Examples:

  • Explain the most important topics from these lecture notes.
  • What should I focus on for the final?
  • Generate a review summary for this course.
  • Generate a mock exam for this course.

Key Controls

Effort Level

Effort level changes retrieval and context depth for each turn.

Supported values:

  • low
  • medium
  • high

Reasoning Mode

Reasoning mode changes the generation pipeline depth used for study-document tasks.

Supported modes:

  • Quick Review
  • Deep Analysis

Quick Review is faster and cheaper.

Deep Analysis uses a deeper generation path with topic extraction and refinement, which can improve quality at the cost of time and tokens.

Web Search

Some providers and models support web search. When supported, the desktop app lets you toggle web search for the next message.

File Attachments

Some providers and models support file attachments in desktop chat.

If the current provider or model does not support attachments, the UI disables unsupported uploads.

Cancel

Use Cancel to stop an in-flight indexing or chat request.

Reopening Sessions

When you reopen a saved session:

  • the app tries a fast attach path first
  • if the saved Chroma index still matches the saved file set, it reuses the existing retriever
  • if files changed, or if you click Apply, the app performs a full re-index

This helps the desktop app avoid unnecessary re-embedding work.

Best Practices

  • put files into the most accurate document type bucket you can
  • add past exams when available
  • reuse the same session for the same course
  • use Quick Review when you want faster output
  • use Deep Analysis when quality matters more than speed
  • use local embeddings if you want to reduce cloud embedding costs

Drag and Drop

The desktop app supports file drag-and-drop into the chat area when the optional tkinterdnd2 support is available.

If that extension is not available, the app still works normally. Only drag-and-drop is unavailable.

Language Support

The desktop app supports:

  • Auto
  • English
  • Simplified Chinese

The selected language steers desktop UI language and generated output headings where supported.

Related Pages

UACRAgent Wiki

Start Here

Usage

Reference

Clone this wiki locally