README.md

---
title: Pak Angels AI Tutor
emoji: 🎓
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false
suggested_hardware: zero-a10g
---

# Pak Angels AI Tutor

Pak Angels AI Tutor is an AI-powered learning companion for the Pak Angels AI
Training Program. It helps students, faculty, researchers, professionals,
entrepreneurs, startup founders, AI developers, business leaders, and innovation
teams learn Artificial Intelligence, build practical applications, design
intelligent workflows, automate business processes, and develop AI-powered
startups.

The app is built with Gradio and the official OpenAI Python SDK. It is
prepared for functional testing and demonstration on Hugging Face Spaces.

## Features

- Clean blue-and-white Pak Angels visual identity
- Sidebar navigation with specialized learning modes
- Selected learning-mode label above the conversation area
- Streaming AI responses through the OpenAI Responses API
- Session-based chat history
- Suggested-question buttons for every learning mode
- New Conversation and Clear Chat controls
- Markdown rendering and syntax-highlighted code blocks
- Clear missing-key and OpenAI API error messages
- Privacy notice for sensitive information
- Hugging Face Spaces-compatible environment-variable configuration

## Learning Modules

- Home
- AI-101 Foundations
- Prompt Engineering
- Generative AI
- Agentic AI
- Retrieval-Augmented Generation (RAG)
- Multi-Agent Systems
- AI Workflow Design
- Business Process Automation
- Gradio Development
- AI Startup Mentor
- About Pak Angels

## Local Setup

Local setup is optional. Hugging Face Spaces can run the app directly from these
files.

1. Create a virtual environment:

   ```bash
   python -m venv .venv
   ```

2. Activate the virtual environment:

   ```bash
   source .venv/bin/activate
   ```

3. Install dependencies:

   ```bash
   pip install -r requirements.txt
   ```

4. Configure environment variables:

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

   Add your real key only to `.env` or your shell environment. Do not commit
   `.env`.

5. Run the app:

   ```bash
   python app.py
   ```

## Hugging Face Spaces Deployment

1. Create a Hugging Face account.
2. Create a new Space.
3. Select Gradio as the application SDK if available.
4. Choose the desired visibility.
5. Upload or push all project files from this folder.
6. Open the Space Settings.
7. Go to Variables and secrets.
8. Add a new secret named `OPENAI_API_KEY`.
9. Optionally add `OPENAI_MODEL`.
10. Allow Hugging Face to build the application.
11. Review build logs if deployment fails.
12. Open the Space URL and test all learning modes.

To update the Space, replace the files through the Hugging Face web interface or
push changes through Git. Hugging Face will rebuild the Space after new changes
are uploaded.

### Deploy With the Hugging Face Hub API

This project includes `deploy_to_huggingface.py`, which uploads the current
project folder to a Hugging Face Space using the Hugging Face Hub API.

Install the deployment helper dependency locally:

```bash
python3 -m pip install -r deploy_requirements.txt
```

Set the Hugging Face deployment credentials in your local environment:

```bash
export HF_TOKEN=your_hugging_face_write_token_here
export HF_SPACE_ID=your-username/your-space-name
```

Use your real Hugging Face username and Space name. Do not leave
`your-username/your-space-name` in the command.

Then upload the project to an existing Space:

```bash
python3 deploy_to_huggingface.py
```

If the Space does not exist yet, create it as a Gradio Space and upload in one
step:

```bash
python3 deploy_to_huggingface.py --create
```

You can also pass the Space id directly:

```bash
python3 deploy_to_huggingface.py --space-id your-username/your-space-name --create
```

The script excludes local-only files such as `.env`, `.venv/`, caches, logs, and
compiled Python files. It does not create or upload OpenAI secrets. Add
`OPENAI_API_KEY` separately in the Space settings.

## Required Hugging Face Secret

The required secret name is:

```text
OPENAI_API_KEY
```

Optional:

```text
OPENAI_MODEL
```

Never upload a `.env` file containing a real API key to Hugging Face Spaces.

## Troubleshooting

Missing API key: Add `OPENAI_API_KEY` under Hugging Face Space -> Settings ->
Variables and secrets -> New secret, then restart or rebuild the Space.

Quota exceeded or billing errors: Check OpenAI usage limits, billing settings,
and project access. The app will show a clear message for rate limits and quota
related API failures.

Dependency installation errors: Confirm `requirements.txt` is present in the
Space root folder and that the Space is using Python with Gradio support.

Python version problems: Use a current Hugging Face Gradio environment. The
code uses standard cross-platform Python and avoids Mac-specific paths.

Missing assets: The app does not require local image assets. Optional future
assets should use relative paths and should be committed with the app.

OpenAI API errors: Check the API key, selected model, quota, billing, and build
logs. If using `OPENAI_MODEL`, verify that the account has access to the model.

Gradio startup failures: Make sure `app.py` exists at the Space root. For local
testing, run `python app.py`.

Hugging Face build failures: Review the Space build logs, confirm all required
files are uploaded, and check that only necessary dependencies are listed.

ZeroGPU or GPU startup error: This app does not need GPU hardware. In the Space
Settings, set Hardware to a CPU option such as CPU Basic, then restart the Space.

## Security

- API keys must never be committed to Git.
- API keys must never be placed directly in `app.py`.
- Real secrets must not be placed in `.env.example`.
- Users should not enter confidential, proprietary, financial, medical,
  personal, or otherwise sensitive information into the tutor.

## Architecture

- `app.py`: Gradio interface, navigation, chat state, and page rendering
- `config.py`: environment-variable configuration
- `prompts.py`: learning modules, suggested questions, and specialized tutor instructions
- `openai_service.py`: OpenAI Responses API streaming integration and error handling
- `requirements.txt`: deployment dependencies
- `deploy_to_huggingface.py`: Hugging Face Hub API upload script
- `deploy_requirements.txt`: local-only dependency for the upload script
- `.env.example`: safe placeholder environment variables
- `.gitignore`: local secrets and development artifact exclusions