📚 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

---

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:

Step	Command	When needed
Start Ollama	ollama serve &	Every new terminal session
Activate env	source .venv/bin/activate	Every new terminal session
Run assistant	academic-assistant	When you want to chat
Refresh Brightspace cookies	See Method A	Every ~24h (unless using auto-login)

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)

Tool	Description
github_list_repos	List your repositories
github_get_repo	Get repo details + recent commits
github_create_repo	Create a new repository
github_push_file	Create/update a file in a repo
github_list_commits	List recent commits

Brightspace (6 tools)

Tool	Description
brightspace_list_courses	List enrolled courses
brightspace_list_assignments	List assignments for a course
brightspace_get_assignment	Full assignment details + rubric
brightspace_get_grades	Current grades for a course
brightspace_get_announcements	Course announcements
brightspace_get_upcoming	All upcoming due dates across courses

Outlook (5 tools)

Tool	Description
outlook_list_emails	List emails (with filtering)
outlook_get_email	Full email content
outlook_send_email	Send an email
outlook_list_events	Upcoming calendar events
outlook_create_event	Create a calendar event

Local Files (5 tools)

Tool	Description
fs_list_directory	List files in a folder
fs_read_file	Read a text file
fs_write_file	Write/create a file
fs_search_files	Search files by name pattern
fs_file_info	Get file size, date, type

---

License

MIT