README.md

metadata

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:

   python -m venv .venv
   

2. Activate the virtual environment:

   source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure environment variables:

   cp .env.example .env
   

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

5. Run the app:

   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:

python3 -m pip install -r deploy_requirements.txt

Set the Hugging Face deployment credentials in your local environment:

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:

python3 deploy_to_huggingface.py

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

python3 deploy_to_huggingface.py --create

You can also pass the Space id directly:

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:

OPENAI_API_KEY

Optional:

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