📚 Academic Assistant

AI-powered academic assistant that connects your university tools in one chat interface. Ask questions in plain English and it pulls data from GitHub, Brightspace, Outlook, and your local files.

Built for UTRGV students — works with UTRGV Brightspace (D2L) and @utrgv.edu Office 365 email.

Table of Contents

• Quick Start

• Requirements

• Installation

• LLM Setup (Ollama)

• Module Setup

  • GitHub

  • Brightspace (UTRGV D2L)

  • Outlook (@utrgv.edu)

  • Local Files

• Running the Assistant

• Daily Usage

• Troubleshooting

• Using OpenAI Instead of Ollama

• Architecture

• Available Tools

Related MCP server: AI Personal Hub

Quick Start

# 1. Clone the repo
git clone https://github.com/Miguel121699/academic-assistant.git
cd academic-assistant

# 2. Install Python dependencies
python -m venv .venv
source .venv/bin/activate
pip install -e .

# 3. Install Ollama (free local LLM)
brew install ollama
ollama serve &
ollama pull llama3.1:8b

# 4. Configure credentials
cp .env.example .env
# Edit .env with your API keys (see Module Setup below)

# 5. Run
academic-assistant

Requirements

• macOS (tested on Apple Silicon)

• Python 3.11+

• Ollama (free) OR an OpenAI API key ($)

• ~5GB disk space for the LLM model

Installation

Step 1: Clone the repository

git clone https://github.com/Miguel121699/academic-assistant.git
cd academic-assistant

Step 2: Create a virtual environment

python -m venv .venv
source .venv/bin/activate

Step 3: Install the package

pip install -e .

This installs four commands:

• academic-assistant — Interactive chat agent

• academic-server — Standalone MCP server (for use with Claude, Kiro, etc.)

• academic-oauth — Microsoft OAuth helper (personal accounts)

• academic-oauth-utrgv — UTRGV Outlook login (device code flow)

Step 4: Create your config file

cp .env.example .env

LLM Setup (Ollama)

Ollama runs AI models locally on your Mac — completely free, no API key needed.

Install Ollama

# On Apple Silicon Mac:
arch -arm64 brew install ollama

# On Intel Mac:
brew install ollama

Or download from: https://ollama.com/download

Start Ollama

# Start the server (runs in background)
ollama serve &

# Or run in foreground to see logs:
ollama serve

Download the model

# Recommended: Llama 3.1 8B (~5GB download, good tool-calling support)
ollama pull llama3.1:8b

Other model options:

# Smaller/faster (3.8GB, less accurate):
ollama pull llama3.2:3b

# Larger/smarter (requires 48GB+ RAM):
ollama pull llama3.1:70b

# Good at coding tasks:
ollama pull deepseek-coder-v2:16b

Verify it's working

ollama list
# Should show: llama3.1:8b

That's it! The assistant auto-detects Ollama at http://localhost:11434 and uses it.

Starting Ollama on each session

Ollama doesn't auto-start on boot. Each time you open a new terminal:

ollama serve &

Or set it to auto-start:

brew services start ollama

Module Setup

Edit your .env file for each service you want to connect:

nano .env

GitHub

What you get: List repos, view commits, create repos, push code files.

1. Go to https://github.com/settings/tokens?type=beta

2. Click "Generate new token"

3. Name it academic-assistant

4. Set expiration: 90 days (or no expiry)

5. Repository access: Select "All repositories"

6. Permissions → Repository permissions:

   • Administration: Read and write (to create repos)

   • Contents: Read and write (to push files)

   • Metadata: Read-only (default)

7. Click Generate token

8. Copy the token (starts with github_pat_...)

Add to .env:

GITHUB_TOKEN=github_pat_your-token-here
GITHUB_USERNAME=your-github-username

Token lasts: 90 days (or forever if you chose no expiry). No refresh needed.

Brightspace (UTRGV D2L)

What you get: List courses, view assignments/due dates, check grades, read announcements, see upcoming deadlines.

There are two authentication methods:

Method A: Manual Cookie Copy (works immediately)

1. Open https://utrgv.brightspace.com in Chrome and log in

2. Press Cmd+Option+I to open DevTools

3. Click the Application tab

4. In the left sidebar: Cookies → https://utrgv.brightspace.com

5. Find and copy the Value of these two cookies:

   • d2lSessionVal

   • d2lSecureSessionVal

Add to .env:

BRIGHTSPACE_SESSION_VAL=paste-d2lSessionVal-here
BRIGHTSPACE_SECURE_SESSION_VAL=paste-d2lSecureSessionVal-here

⚠️ Cookies expire every ~24 hours. You'll need to repeat this daily.

Method B: Auto-Login (set and forget)

To skip daily cookie refresh, add your UTRGV credentials:

UTRGV_USERNAME=your.utrgv.username
UTRGV_PASSWORD=your-utrgv-password

The assistant will automatically log in via UTRGV Shibboleth SSO when cookies expire and refresh them in .env.

Note: If UTRGV uses Duo MFA, auto-login may require an additional approval step on your phone.

⚠️ Your password is stored in plaintext in .env. The .gitignore ensures it's never committed to git.

Outlook (@utrgv.edu)

What you get: Read/send emails, view/create calendar events — all from your @utrgv.edu account.

This uses Microsoft's device code flow — no Azure app registration needed.

One-time setup:

# Make sure you're in the project with venv active:
cd academic-assistant
source .venv/bin/activate

# Run the login command:
academic-oauth-utrgv

You'll see:

============================================================
  To sign in with your UTRGV email:
  1. Open: https://login.microsoft.com/device
  2. Enter code: ABC123XYZ
  3. Log in with your @utrgv.edu account
============================================================

Steps:

1. Open https://login.microsoft.com/device in your browser

2. Type the code shown in your terminal (NOT sent to email — it's displayed in the terminal)

3. Sign in with your @utrgv.edu Microsoft account

4. Approve the permissions

5. Terminal will say "✅ Login successful! Outlook connected."

The tokens are saved to .env automatically.

Token lasts: ~90 days. Auto-refreshes silently each time you use it. Only need to redo academic-oauth-utrgv if you don't use it for 90+ days.

Local Files

What you get: Read, write, list, and search files on your computer.

No configuration needed! The first time the assistant tries to access a folder, you'll see a permission prompt:

🔒 File access requested:
   Path: /Users/you/Desktop/homework.py
   Allow access to /Users/you/Desktop?
   (y)es / (n)o / (a)lways:

• y — Allow for this session only

• n — Deny access

• a — Allow permanently (saved to .env, never asks again)

To pre-approve directories without prompts, add to .env:

ALLOWED_DIRECTORIES=~/Desktop,~/Documents,~/Downloads,~/projects

Running the Assistant

# 1. Make sure Ollama is running
ollama serve &

# 2. Activate the environment
cd /path/to/academic-assistant
source .venv/bin/activate

# 3. Start chatting
academic-assistant

You'll see:

╭──────────────────────────────────────────────────────────────╮
│ 📚 Academic Assistant                                        │
│ LLM: Ollama llama3.1:8b (local)                              │
│ Services: ✓ GitHub | ✓ Brightspace | ✓ Outlook (@utrgv.edu)  │
│                                                              │
│ Commands: /reset (new conversation)  /quit (exit)  /help     │
╰──────────────────────────────────────────────────────────────╯

Commands

• /help — Show all available tools

• /reset — Clear conversation history (start fresh)

• /quit or /exit — Exit the assistant

Example prompts

• "What assignments are due this week?"

• "List my courses"

• "Show my unread emails"

• "What's on my calendar tomorrow?"

• "List my GitHub repos"

• "Create a private repo called homework-6"

• "Find all PDF files on my Desktop"

• "Read the file at ~/Documents/CS3340/lab1.py"

Daily Usage

Here's what you need each day:

One-liner to start everything:

cd ~/path/to/academic-assistant && ollama serve & source .venv/bin/activate && academic-assistant

Troubleshooting

"Connection refused" or Ollama not responding

# Check if Ollama is running:
curl http://localhost:11434/api/tags

# If not, start it:
ollama serve &

# Verify model is downloaded:
ollama list

Brightspace says "Session expired"

Your cookies expired. Either:

• Re-copy cookies from browser (Method A)

• Or add UTRGV_USERNAME/UTRGV_PASSWORD to .env for auto-refresh

Outlook says "Token refresh failed"

Re-run the device code flow:

academic-oauth-utrgv

GitHub shows "401 Unauthorized"

Your token expired or lacks permissions. Generate a new one at https://github.com/settings/tokens

LLM makes up fake data

Known issue with small local models. The assistant has guardrails to catch most hallucinations. If you see clearly fake data (fictional course names, made-up assignments), just ignore it and rephrase your question. Upgrading to a larger model or OpenAI fixes this.

Agent asks for my password in chat

Never type credentials into the chat. This is the local LLM hallucinating an auth prompt. Hit Enter to skip it or Ctrl+C and restart. The CLI has filters to catch these, but small models occasionally get through.

Using OpenAI Instead of Ollama

If you have an OpenAI API key, the assistant uses GPT-4o which is significantly better at tool-calling and never hallucinates fake data.

1. Get a key at https://platform.openai.com/api-keys

2. Add to .env:

   OPENAI_API_KEY=sk-your-key-here

3. Restart academic-assistant

The banner will show LLM: OpenAI gpt-4o and you don't need Ollama running.

Cost: ~$0.01-0.05 per conversation (very cheap for personal use).

Priority: If both are configured, OpenAI is used over Ollama.

Architecture

┌─────────────────────────────────────────────────────────┐
│  Academic Assistant                                      │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Agent Loop (OpenAI or Ollama)                   │   │
│  │  - Receives user message                        │   │
│  │  - Decides which tools to call                  │   │
│  │  - Feeds results back to LLM                    │   │
│  │  - Returns final answer                         │   │
│  └──────────────────────┬──────────────────────────┘   │
│                         │                               │
│  ┌──────────┐ ┌────────┴───┐ ┌──────────┐ ┌────────┐  │
│  │ GitHub   │ │Brightspace │ │ Outlook  │ │  Files │  │
│  │ Tools    │ │  Tools     │ │  Tools   │ │  Tools │  │
│  └──────────┘ └────────────┘ └──────────┘ └────────┘  │
│       │              │              │            │      │
└───────┼──────────────┼──────────────┼────────────┼─────┘
        │              │              │            │
   GitHub API    D2L Valence    MS Graph API   Local FS
                  (cookies)    (device code)

Available Tools (21 total)

GitHub (5 tools)

Brightspace (6 tools)

Outlook (5 tools)

Local Files (5 tools)

License

MIT