# Adeptus Insights - User Guide

## Getting Started

### Accessing the Plugin
1. Log in to your Moodle site
2. Navigate to **Site administration > Reports > Adeptus Insights**
   - Or find it in your user menu under **Adeptus Insights**

### Main Features
- **AI Assistant**: Ask questions in plain English to generate reports
- **Report Wizard**: Create reports using pre-built templates
- **Generated Reports**: View and manage your saved reports
- **Subscription**: View your plan and usage

---

## AI Assistant

The AI Assistant lets you create reports by typing questions in natural language.

### How to Use

1. Click the **AI Assistant** tab
2. Type your question in the chat box
3. Press Enter or click Send
4. Review the generated report
5. Save or export as needed

### Example Questions

```
"Show me all users who logged in this week"
"List courses with less than 50% completion rate"
"Find students who haven't submitted assignment X"
"Show the most active users by login count"
"List all courses without any teachers assigned"
```

### Tips for Better Results

- Be specific: "users in Course ABC" instead of just "users"
- Include timeframes: "in the last 30 days"
- Specify what you want to see: "show name, email, and last login"

### Understanding Results

After your query runs:
- **Table View**: Interactive table with sorting and search
- **Chart View**: Visual representation (if applicable)
- **Save**: Store for later access
- **Export**: Download in your preferred format

---

## Report Wizard

The Report Wizard guides you through creating reports step-by-step.

### Step 1: Choose Category

Select a report category:
- User & Enrollment
- Course Reports
- Grades & Assessment
- System Usage
- Completion
- And many more...

### Step 2: Select Report

Browse available reports in your chosen category. Each shows:
- Report name and description
- Premium badge (if upgrade required)

### Step 3: Configure

Set parameters for your report:
- **Date ranges**: Start and end dates
- **Courses**: Select specific courses
- **Users**: Filter by user type
- **Thresholds**: Set minimum/maximum values

### Step 4: View Results

Your report displays with:
- Interactive data table
- Chart visualisation (toggle view)
- Export options
- Save button

---

## Generated Reports

Manage all your saved reports in one place.

### Viewing Reports

1. Click **Generated Reports** tab
2. Select a report from the list
3. View in table or chart format

### Actions

| Action | Description |
|--------|-------------|
| **Preview** | View report data |
| **Re-run** | Refresh with latest data |
| **Export** | Download to file |
| **Delete** | Remove report |

### Categories

Organise reports with colour-coded categories:
1. Click the category dropdown on a report
2. Select existing or create new category
3. Reports group by category for easy finding

---

## Exporting Reports

### Available Formats

| Format | Best For | Availability |
|--------|----------|--------------|
| **PDF** | Printing, presentations | All plans |
| **CSV** | Spreadsheet analysis | Pro+ |
| **Excel** | Advanced spreadsheets | Pro+ |
| **JSON** | Technical/API use | Pro+ |

### How to Export

1. Generate or open a report
2. Click **Export** dropdown
3. Select format
4. File downloads automatically

### Export Tips

- PDF limited to 5,000 rows - use CSV for larger data
- Charts included in PDF exports
- Filename includes report name and date

---

## Understanding Limits

### AI Credits

- Used each time you ask the AI a question
- Reset monthly (based on plan)
- When exhausted: Wait for reset or upgrade

### Report Limits

- Maximum saved reports varies by plan
- Free plan: 10 reports
- Delete old reports to free space

### Export Limits

- Monthly export allowance
- Varies by subscription plan
- PDF available on all plans

---

## Troubleshooting

### "Credit limit reached"

**Cause**: Monthly AI credits used up

**Solutions**:
- Wait for monthly reset (1st of month or billing date)
- Upgrade your plan

### "Report limit reached"

**Cause**: Maximum saved reports reached

**Solutions**:
- Delete unused reports
- Upgrade for higher limit

### Report won't generate

**Try**:
1. Simplify your question
2. Add specific filters (date range, course)
3. Refresh the page
4. Contact your administrator

### Export not working

**Check**:
- Format available on your plan (CSV/Excel/JSON need Pro+)
- Report size under 5,000 rows for PDF
- Browser popup blocker disabled

---

## Tips & Best Practices

### For Better AI Results
- Start simple, then add detail
- Use specific course/user names
- Include date ranges when relevant
- Ask follow-up questions to refine

### For Organisation
- Use categories to group related reports
- Delete reports you no longer need
- Save frequently-used reports

### For Performance
- Filter by specific courses rather than site-wide
- Use date ranges to limit data
- Export large reports to CSV rather than PDF

---

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| Enter | Send message (AI Assistant) |
| Shift+Enter | New line in message |

---

## Getting Help

### Self-Service
- Check this user guide
- Review error messages for specific guidance
- Try the suggested recovery actions

### Contact Support
- Email: support@adeptus360.com
- Include: Error message, what you were trying to do

### Contact Your Administrator
- For permission issues
- For subscription questions
- For plugin configuration

---

*Adeptus Insights v1.0.0 | Need help? support@adeptus360.com*
