faculty_config_guide.md

# Faculty Configuration Guide

## Overview

The config.json file serves as a stable reference point for customizing your deployed AI assistant on Hugging Face Spaces. This guide explains how to securely manage and iterate on your assistant's configuration.

## Security Model

### Faculty-Only Access
- Configuration editing is restricted to faculty members only
- Students can use the chatbot but cannot modify settings
- Access is controlled via a faculty password set in environment variables

### Setting Up Faculty Access

1. **In your Hugging Face Space Settings:**
   ```
   Settings → Variables and secrets → New secret
   
   Name: FACULTY_CONFIG_PASSWORD
   Value: [your-secure-password]
   ```

2. **Alternative Token-Based Access:**
   ```
   Name: CONFIG_EDIT_TOKEN
   Value: [generated-secure-token]
   ```

## Configuration Workflow

### Initial Deployment

1. **Generate deployment package** using ChatUI Helper
2. **Upload to Hugging Face:**
   - app.py
   - config.json
   - requirements.txt

3. **Set environment variables:**
   - `OPENROUTER_API_KEY`: Your API key
   - `FACULTY_CONFIG_PASSWORD`: Faculty access code
   - `SPACE_ACCESS_CODE`: (Optional) General access control

### Iterative Customization

1. **Access Configuration Tab:**
   - Navigate to your deployed space
   - Click "⚙️ Configuration" tab
   - Enter faculty access code

2. **Edit Settings:**
   - **System Prompt**: Refine assistant behavior
   - **Temperature**: Adjust response creativity
   - **Max Tokens**: Control response length
   - **Examples**: Update sample prompts
   - **Grounding URLs**: Add/remove reference sites

3. **Save and Test:**
   - Click "💾 Save Configuration"
   - Refresh page to apply changes
   - Test with students before finalizing

## config.json Structure

```json
{
  "name": "AI Assistant",
  "description": "A customizable AI assistant",
  "system_prompt": "You are a helpful teaching assistant...",
  "model": "gemini/gemini-2.0-flash-thinking-exp-1219",
  "temperature": 0.7,
  "max_tokens": 500,
  "examples": "['What is machine learning?', 'Explain neural networks']",
  "grounding_urls": "[\"https://course-website.edu\"]",
  "api_key_var": "OPENROUTER_API_KEY",
  "enable_dynamic_urls": false,
  "locked": false,
  "lock_reason": "",
  "last_modified_by": "faculty",
  "last_modified_at": "2024-01-15 10:30:00"
}
```

## Best Practices

### 1. Iterative Refinement
- Start with a basic configuration
- Test with sample student queries
- Refine based on actual usage
- Document changes for other faculty

### 2. System Prompt Engineering
```
You are a teaching assistant for [Course Name].
Your role is to:
- Answer questions about course material
- Guide students without giving direct answers
- Encourage critical thinking
- Reference course materials when relevant

Important guidelines:
- Do not provide solutions to assignments
- Redirect homework questions to office hours
- Maintain academic integrity
```

### 3. Configuration Locking
- Lock configuration during exams
- Prevents accidental changes
- Clear communication with lock reason

### 4. Backup Strategy
- Export configuration before major changes
- Share configurations between courses
- Version control for semester changes

## Advanced Features

### Configuration Import/Export
1. **Export current config:**
   - Click "📥 Export Config"
   - Save for backup or sharing

2. **Import configuration:**
   - Click "📤 Import Config"
   - Select JSON file
   - Review changes before saving

### Grounding URLs
- Add course websites
- Include syllabus links
- Reference documentation
- Limit to trusted sources

### Access Control Hierarchy
1. **Space Access Code**: Controls who can use the chatbot
2. **Faculty Password**: Controls who can edit configuration
3. **Configuration Lock**: Temporary edit prevention

## Troubleshooting

### Common Issues

**Cannot save configuration:**
- Verify faculty password is correct
- Check if configuration is locked
- Ensure proper JSON formatting

**Changes not taking effect:**
- Refresh the page after saving
- Clear browser cache if needed
- Check browser console for errors

**Students report access issues:**
- Verify SPACE_ACCESS_CODE if set
- Check API key configuration
- Review recent configuration changes

### Configuration Recovery

If configuration becomes corrupted:
1. Access Space Files directly
2. Download config_backup_*.json
3. Rename to config.json
4. Restart space

## Security Considerations

1. **Never share faculty password with students**
2. **Rotate passwords each semester**
3. **Monitor configuration changes**
4. **Use environment variables for sensitive data**
5. **Review grounding URLs regularly**

## Support

For additional help:
- Check the ChatUI Helper documentation
- Contact your institution's IT support
- Review Hugging Face Spaces documentation