# 📚 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](#quick-start)
- [Requirements](#requirements)
- [Installation](#installation)
- [LLM Setup (Ollama)](#llm-setup-ollama)
- [Module Setup](#module-setup)
  - [GitHub](#github)
  - [Brightspace (UTRGV D2L)](#brightspace-utrgv-d2l)
  - [Outlook (@utrgv.edu)](#outlook-utrgvedu)
  - [Local Files](#local-files)
- [Running the Assistant](#running-the-assistant)
- [Daily Usage](#daily-usage)
- [Troubleshooting](#troubleshooting)
- [Using OpenAI Instead of Ollama](#using-openai-instead-of-ollama)
- [Architecture](#architecture)
- [Available Tools](#available-tools)

---

## Quick Start

```bash
# 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

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

### Step 2: Create a virtual environment

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

### Step 3: Install the package

```bash
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

```bash
cp .env.example .env
```

---

## LLM Setup (Ollama)

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

### Install Ollama

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

# On Intel Mac:
brew install ollama
```

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

### Start Ollama

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

# Or run in foreground to see logs:
ollama serve
```

### Download the model

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

Other model options:
```bash
# 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

```bash
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:

```bash
ollama serve &
```

Or set it to auto-start:
```bash
brew services start ollama
```

---

## Module Setup

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

```bash
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`:
```ini
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`:
```ini
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:

```ini
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:

```bash
# 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`:
```ini
ALLOWED_DIRECTORIES=~/Desktop,~/Documents,~/Downloads,~/projects
```

---

## Running the Assistant

```bash
# 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](#method-a-manual-cookie-copy-works-immediately) | Every ~24h (unless using auto-login) |

**One-liner to start everything:**
```bash
cd ~/path/to/academic-assistant && ollama serve & source .venv/bin/activate && academic-assistant
```

---

## Troubleshooting

### "Connection refused" or Ollama not responding
```bash
# 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:
```bash
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`:
   ```ini
   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