Deploy Pak Angels AI Tutor

.env.example

@@ -0,0 +1,4 @@
+OPENAI_API_KEY=your_openai_api_key_here
+OPENAI_MODEL=your_preferred_model_here
+HF_TOKEN=your_hugging_face_write_token_here
+HF_SPACE_ID=your-username/your-space-name

.gitignore

@@ -0,0 +1,19 @@
+.env
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+.DS_Store
+.cache/
+.huggingface/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+*.log
+tmp/
+temp/

README.md

@@ -1,14 +1,215 @@
 ---
 title: Pak Angels AI Tutor
-emoji: 🌍
-colorFrom: green
-colorTo: green
+emoji: 🎓
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.20.0
-python_version: '3.12'
+sdk_version: 5.50.0
 app_file: app.py
 pinned: false
-short_description: Pak Angels AI Tutoring Platform
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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.
+
+## 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

app.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+from functools import partial
+
+import gradio as gr
+
+from config import APP_NAME, APP_SUBTITLE, get_openai_api_key, get_openai_model
+from openai_service import format_openai_error, stream_tutor_response
+from prompts import ABOUT_PAK_ANGELS, MODULES, build_system_instructions
+
+
+PRIVACY_NOTICE = (
+    "Privacy notice: Do not enter confidential, proprietary, financial, medical, "
+    "personal, or otherwise sensitive information into the AI Tutor."
+)
+
+
+CSS = """
+:root {
+    --pak-blue: #0b5cab;
+    --pak-blue-dark: #073f78;
+    --pak-blue-soft: #eaf4ff;
+    --pak-line: #d8e5f2;
+    --pak-text: #14213d;
+}
+body,
+.gradio-container {
+    background: #f7fbff !important;
+    color: var(--pak-text);
+}
+.main-shell {
+    max-width: 1180px;
+    margin: 0 auto;
+}
+.hero {
+    background: linear-gradient(135deg, #ffffff 0%, #eaf4ff 62%, #d6ebff 100%);
+    border: 1px solid var(--pak-line);
+    border-radius: 8px;
+    padding: 24px;
+    margin-bottom: 14px;
+}
+.hero h1 {
+    color: var(--pak-blue-dark);
+    font-size: 38px;
+    line-height: 1.1;
+    margin: 0 0 8px 0;
+}
+.hero p {
+    margin: 5px 0;
+    font-size: 16px;
+}
+.mode-label {
+    border-left: 5px solid var(--pak-blue);
+    background: #ffffff;
+    border-radius: 8px;
+    padding: 14px 16px;
+    box-shadow: 0 1px 4px rgba(11, 92, 171, 0.08);
+}
+.privacy {
+    background: #fff8e8;
+    border: 1px solid #f1d28c;
+    border-radius: 8px;
+    padding: 12px 14px;
+    font-size: 14px;
+}
+.side-panel {
+    background: #ffffff;
+    border: 1px solid var(--pak-line);
+    border-radius: 8px;
+    padding: 14px;
+}
+.suggestion-button {
+    min-height: 46px;
+}
+button.primary {
+    background: var(--pak-blue) !important;
+    border-color: var(--pak-blue) !important;
+}
+"""
+
+
+def hero_html() -> str:
+    return f"""
+    <div class="hero">
+        <h1>{APP_NAME}</h1>
+        <p><strong>{APP_SUBTITLE}</strong></p>
+        <p>Pak Angels AI Tutor helps students, faculty, professionals,
+        entrepreneurs, and startup founders learn Artificial Intelligence,
+        build practical applications, design intelligent workflows, automate
+        business processes, and develop AI-powered startups.</p>
+    </div>
+    """
+
+
+def module_summary_html(module_name: str) -> str:
+    module = MODULES[module_name]
+    about = ""
+    if module_name == "About Pak Angels":
+        about = f"<p>{ABOUT_PAK_ANGELS}</p>"
+    return f"""
+    <div class="mode-label">
+        <strong>Selected learning mode:</strong> {module_name}<br>
+        <span>{module["summary"]}</span>
+        {about}
+    </div>
+    """
+
+
+def topics_markdown(module_name: str) -> str:
+    topics = "\n".join(f"- {topic}" for topic in MODULES[module_name]["topics"])
+    return f"### Topics in this mode\n{topics}"
+
+
+def get_suggestion(module_name: str, index: int) -> str:
+    suggestions = MODULES[module_name]["suggestions"]
+    return suggestions[index] if index < len(suggestions) else ""
+
+
+def update_module(module_name: str):
+    suggestions = MODULES[module_name]["suggestions"]
+    button_updates = [
+        gr.update(value=suggestion, visible=True) for suggestion in suggestions[:5]
+    ]
+    while len(button_updates) < 5:
+        button_updates.append(gr.update(value="", visible=False))
+
+    return (
+        module_summary_html(module_name),
+        topics_markdown(module_name),
+        *button_updates,
+    )
+
+
+def add_user_message(message: str, history: list[dict[str, str]] | None):
+    history = list(history or [])
+    message = (message or "").strip()
+    if not message:
+        return "", history
+    history.append({"role": "user", "content": message})
+    return "", history
+
+
+def generate_response(history: list[dict[str, str]] | None, module_name: str):
+    history = list(history or [])
+    if not history or history[-1]["role"] != "user":
+        yield history
+        return
+
+    api_key = get_openai_api_key()
+    if not api_key:
+        message = (
+            "OPENAI_API_KEY is not configured. In Hugging Face Spaces, add it under "
+            "Settings -> Variables and secrets -> New secret, then restart the Space."
+        )
+        history.append({"role": "assistant", "content": message})
+        yield history
+        return
+
+    history.append({"role": "assistant", "content": ""})
+    try:
+        for delta in stream_tutor_response(
+            api_key=api_key,
+            model=get_openai_model(),
+            system_instructions=build_system_instructions(module_name),
+            messages=history[:-1],
+        ):
+            history[-1]["content"] += delta
+            yield history
+    except Exception as error:
+        history[-1]["content"] = format_openai_error(error)
+        yield history
+
+
+def submit_message(message: str, history: list[dict[str, str]] | None, module_name: str):
+    textbox, updated_history = add_user_message(message, history)
+    yield textbox, updated_history
+    for streamed_history in generate_response(updated_history, module_name):
+        yield textbox, streamed_history
+
+
+def submit_suggestion(
+    suggestion_index: int,
+    history: list[dict[str, str]] | None,
+    module_name: str,
+):
+    question = get_suggestion(module_name, suggestion_index)
+    yield from submit_message(question, history, module_name)
+
+
+def clear_conversation():
+    return []
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(
+        title=APP_NAME,
+        css=CSS,
+        theme=gr.themes.Soft(primary_hue="blue", neutral_hue="slate"),
+    ) as demo:
+        with gr.Column(elem_classes=["main-shell"]):
+            gr.HTML(hero_html())
+
+            with gr.Row(equal_height=False):
+                with gr.Column(scale=1, min_width=260, elem_classes=["side-panel"]):
+                    module_selector = gr.Radio(
+                        choices=list(MODULES.keys()),
+                        value="Home",
+                        label="Learning mode",
+                    )
+                    gr.Textbox(
+                        value=get_openai_model(),
+                        label="OpenAI model",
+                        interactive=False,
+                    )
+                    new_button = gr.Button("New Conversation")
+                    clear_button = gr.Button("Clear Chat")
+                    with gr.Accordion("About Pak Angels", open=False):
+                        gr.Markdown(ABOUT_PAK_ANGELS)
+
+                with gr.Column(scale=3, min_width=420):
+                    module_summary = gr.HTML(module_summary_html("Home"))
+                    gr.HTML(f'<div class="privacy">{PRIVACY_NOTICE}</div>')
+                    topics = gr.Markdown(topics_markdown("Home"))
+
+                    gr.Markdown("### Suggested questions")
+                    suggestion_buttons = []
+                    with gr.Row():
+                        suggestion_buttons.append(
+                            gr.Button(get_suggestion("Home", 0), elem_classes=["suggestion-button"])
+                        )
+                        suggestion_buttons.append(
+                            gr.Button(get_suggestion("Home", 1), elem_classes=["suggestion-button"])
+                        )
+                    with gr.Row():
+                        suggestion_buttons.append(
+                            gr.Button(get_suggestion("Home", 2), elem_classes=["suggestion-button"])
+                        )
+                        suggestion_buttons.append(
+                            gr.Button(get_suggestion("Home", 3), elem_classes=["suggestion-button"])
+                        )
+                    suggestion_buttons.append(
+                        gr.Button(get_suggestion("Home", 4), elem_classes=["suggestion-button"])
+                    )
+
+                    chatbot = gr.Chatbot(
+                        label="Pak Angels AI Tutor",
+                        type="messages",
+                        height=520,
+                        show_copy_button=True,
+                    )
+                    message_box = gr.Textbox(
+                        label="Ask Pak Angels AI Tutor",
+                        placeholder="Ask a question or choose a suggested question above.",
+                        lines=3,
+                    )
+                    send_button = gr.Button("Send", variant="primary")
+
+            module_selector.change(
+                update_module,
+                inputs=[module_selector],
+                outputs=[module_summary, topics, *suggestion_buttons],
+            )
+
+            send_button.click(
+                submit_message,
+                inputs=[message_box, chatbot, module_selector],
+                outputs=[message_box, chatbot],
+            )
+            message_box.submit(
+                submit_message,
+                inputs=[message_box, chatbot, module_selector],
+                outputs=[message_box, chatbot],
+            )
+
+            for index, button in enumerate(suggestion_buttons):
+                button.click(
+                    partial(submit_suggestion, index),
+                    inputs=[chatbot, module_selector],
+                    outputs=[message_box, chatbot],
+                )
+
+            new_button.click(clear_conversation, outputs=[chatbot])
+            clear_button.click(clear_conversation, outputs=[chatbot])
+
+        return demo
+
+
+demo = build_app()
+
+
+if __name__ == "__main__":
+    demo.queue().launch()

config.py

@@ -0,0 +1,20 @@
+"""Application configuration for Pak Angels AI Tutor."""
+
+from __future__ import annotations
+
+import os
+
+
+APP_NAME = "Pak Angels AI Tutor"
+APP_SUBTITLE = "Learn • Build • Innovate • Launch with Artificial Intelligence"
+DEFAULT_MODEL = "gpt-4.1-mini"
+
+
+def get_openai_api_key() -> str:
+    """Read the OpenAI API key from the environment."""
+    return os.getenv("OPENAI_API_KEY", "").strip()
+
+
+def get_openai_model() -> str:
+    """Read the optional model name, falling back to a practical default."""
+    return os.getenv("OPENAI_MODEL", DEFAULT_MODEL).strip() or DEFAULT_MODEL

deploy_requirements.txt

@@ -0,0 +1 @@
+huggingface_hub>=0.24,<1

deploy_to_huggingface.py

@@ -0,0 +1,205 @@
+"""Upload Pak Angels AI Tutor to a Hugging Face Space.
+
+Required environment variables:
+    HF_TOKEN: A Hugging Face access token with write access to the Space.
+    HF_SPACE_ID: The Space repo id, for example "your-username/pak-angels-ai-tutor".
+
+Optional environment variables:
+    HF_COMMIT_MESSAGE: Custom commit message for the upload.
+    HF_PRIVATE_SPACE: Set to "true" to create a private Space when using --create.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from huggingface_hub import HfApi
+from huggingface_hub.utils import HfHubHTTPError
+
+
+PROJECT_ROOT = Path(__file__).resolve().parent
+DEFAULT_IGNORE_PATTERNS = [
+    ".env",
+    ".env.local",
+    ".env.*.local",
+    ".git/",
+    ".git/**",
+    ".venv/",
+    ".venv/**",
+    "venv/",
+    "venv/**",
+    "__pycache__/",
+    "__pycache__/**",
+    "*.pyc",
+    ".DS_Store",
+    ".pytest_cache/",
+    ".pytest_cache/**",
+    ".ruff_cache/",
+    ".ruff_cache/**",
+    ".mypy_cache/",
+    ".mypy_cache/**",
+    "dist/",
+    "dist/**",
+    "build/",
+    "build/**",
+    "*.egg-info/",
+    "*.egg-info/**",
+    "*.log",
+    "tmp/",
+    "tmp/**",
+    "temp/",
+    "temp/**",
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Upload the current Pak Angels AI Tutor project to Hugging Face Spaces."
+    )
+    parser.add_argument(
+        "--space-id",
+        default=os.getenv("HF_SPACE_ID", "").strip(),
+        help='Hugging Face Space id, for example "username/pak-angels-ai-tutor".',
+    )
+    parser.add_argument(
+        "--token",
+        default=os.getenv("HF_TOKEN", "").strip(),
+        help="Hugging Face write token. Prefer setting HF_TOKEN instead of passing this flag.",
+    )
+    parser.add_argument(
+        "--commit-message",
+        default=os.getenv("HF_COMMIT_MESSAGE", "Deploy Pak Angels AI Tutor"),
+        help="Commit message shown in the Hugging Face Space repository.",
+    )
+    parser.add_argument(
+        "--repo-type",
+        default="space",
+        choices=["space"],
+        help="Repository type. Spaces deployments use 'space'.",
+    )
+    parser.add_argument(
+        "--create",
+        action="store_true",
+        help="Create the Gradio Space if it does not already exist.",
+    )
+    parser.add_argument(
+        "--private",
+        action="store_true",
+        default=os.getenv("HF_PRIVATE_SPACE", "").lower() in {"1", "true", "yes"},
+        help="Create the Space as private when --create is used.",
+    )
+    return parser.parse_args()
+
+
+def validate_inputs(space_id: str, token: str) -> None:
+    missing = []
+    if not space_id:
+        missing.append("HF_SPACE_ID")
+    if not token:
+        missing.append("HF_TOKEN")
+
+    if missing:
+        joined = ", ".join(missing)
+        raise ValueError(
+            f"Missing required setting(s): {joined}. Set them as environment variables "
+            "or pass --space-id and --token."
+        )
+
+    if "/" not in space_id:
+        raise ValueError('HF_SPACE_ID should look like "username/space-name".')
+
+    placeholder_values = {
+        "your_hugging_face_write_token_here",
+        "your-token",
+        "your_token",
+    }
+    placeholder_space_ids = {
+        "your-username/your-space-name",
+        "username/space-name",
+        "your-username/pak-angels-ai-tutor",
+    }
+    if token in placeholder_values:
+        raise ValueError("HF_TOKEN is still a placeholder. Use a real Hugging Face write token.")
+    if space_id in placeholder_space_ids:
+        raise ValueError(
+            "HF_SPACE_ID is still a placeholder. Use your real Space id, such as "
+            '"mohammadanwarkhan/pak-angels-ai-tutor".'
+        )
+
+
+def ensure_space_exists(api: HfApi, args: argparse.Namespace) -> None:
+    if not args.create:
+        return
+
+    api.create_repo(
+        repo_id=args.space_id,
+        repo_type=args.repo_type,
+        private=args.private,
+        space_sdk="gradio",
+        exist_ok=True,
+    )
+
+
+def preflight_check(api: HfApi, args: argparse.Namespace) -> None:
+    whoami = api.whoami()
+    account_name = whoami.get("name") or whoami.get("fullname") or "authenticated account"
+    print(f"Authenticated with Hugging Face as: {account_name}")
+
+    try:
+        api.repo_info(repo_id=args.space_id, repo_type=args.repo_type)
+        print(f"Space is accessible: {args.space_id}")
+    except HfHubHTTPError as error:
+        if args.create:
+            raise
+        raise RuntimeError(
+            f"The token cannot access the Space '{args.space_id}'. Check that the Space id "
+            "is exact and that this Hugging Face token has write access to that Space. "
+            "If the Space does not exist, rerun with --create."
+        ) from error
+
+
+def upload_project(args: argparse.Namespace) -> str:
+    api = HfApi(token=args.token)
+    ensure_space_exists(api, args)
+    preflight_check(api, args)
+    api.upload_folder(
+        folder_path=str(PROJECT_ROOT),
+        repo_id=args.space_id,
+        repo_type=args.repo_type,
+        commit_message=args.commit_message,
+        ignore_patterns=DEFAULT_IGNORE_PATTERNS,
+    )
+    return f"https://huggingface.co/spaces/{args.space_id}"
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        validate_inputs(args.space_id, args.token)
+        url = upload_project(args)
+    except ValueError as error:
+        print(f"Configuration error: {error}", file=sys.stderr)
+        return 2
+    except HfHubHTTPError as error:
+        print(f"Hugging Face upload failed: {error}", file=sys.stderr)
+        print(
+            "Check that HF_SPACE_ID is your real Space id, HF_TOKEN is a real write token, "
+            "and the Space exists. If it does not exist, rerun with --create.",
+            file=sys.stderr,
+        )
+        return 1
+    except Exception as error:
+        print(f"Deployment failed: {error}", file=sys.stderr)
+        return 1
+
+    print("Deployment upload complete.")
+    print(f"Space URL: {url}")
+    print("Remember to set OPENAI_API_KEY in the Space secrets before testing the tutor.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

openai_service.py

@@ -0,0 +1,62 @@
+"""OpenAI Responses API integration."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from openai import APIConnectionError, APIStatusError, AuthenticationError, OpenAI, RateLimitError
+
+
+def format_openai_error(error: Exception) -> str:
+    """Return a learner-friendly error message."""
+    if isinstance(error, AuthenticationError):
+        return (
+            "The OpenAI API key was rejected. Please check that OPENAI_API_KEY is "
+            "set correctly in Hugging Face Secrets."
+        )
+    if isinstance(error, RateLimitError):
+        return (
+            "The request was rate limited or the account may have quota or billing "
+            "limits. Please wait briefly, then check OpenAI usage and billing settings."
+        )
+    if isinstance(error, APIConnectionError):
+        return (
+            "The app could not reach OpenAI. Please check the network connection and "
+            "try again."
+        )
+    if isinstance(error, APIStatusError):
+        status = getattr(error, "status_code", "unknown")
+        return (
+            f"OpenAI returned an API error with status {status}. Please review the "
+            "API key, model name, quota, billing status, and request details."
+        )
+    return "An unexpected AI service error occurred. Please try again or review the Space logs."
+
+
+def stream_tutor_response(
+    *,
+    api_key: str,
+    model: str,
+    system_instructions: str,
+    messages: list[dict[str, str]],
+) -> Iterable[str]:
+    """Yield text deltas from the current event-based OpenAI Responses API stream."""
+    client = OpenAI(api_key=api_key)
+    input_messages = [
+        {"role": message["role"], "content": message["content"]}
+        for message in messages
+        if message.get("role") in {"user", "assistant"} and message.get("content")
+    ]
+
+    stream = client.responses.create(
+        model=model,
+        instructions=system_instructions,
+        input=input_messages,
+        stream=True,
+    )
+
+    for event in stream:
+        if getattr(event, "type", None) == "response.output_text.delta":
+            delta = getattr(event, "delta", "")
+            if delta:
+                yield delta

prompts.py

@@ -0,0 +1,360 @@
+"""Learning-module content and tutor instructions."""
+
+from __future__ import annotations
+
+
+BASE_TUTOR_INSTRUCTIONS = """
+You are Pak Angels AI Tutor, an educational AI companion for the Pak Angels AI
+Training Program.
+
+Your teaching style:
+- Teach clearly and step by step.
+- Adjust depth to the learner's apparent level.
+- Use practical examples, frameworks, exercises, quiz questions, and project ideas.
+- Encourage responsible and ethical AI use.
+- Explain code in simple language when code is useful.
+- Help learners move through Learn -> Practice -> Build -> Deploy -> Innovate -> Launch.
+- Be encouraging, professional, and practical.
+- Do not present uncertain information as fact.
+- Encourage users to verify important legal, medical, financial, and technical decisions.
+- Do not request confidential, proprietary, financial, medical, personal, or sensitive data.
+"""
+
+
+MODULES = {
+    "Home": {
+        "summary": "Start here for an overview of the Pak Angels AI learning journey.",
+        "topics": [
+            "AI learning roadmap",
+            "Practical projects",
+            "Responsible AI",
+            "Startup and innovation pathways",
+        ],
+        "suggestions": [
+            "Help me choose where to start.",
+            "Create a 30-day AI learning plan.",
+            "What should I build after learning AI basics?",
+            "How can I use this tutor responsibly?",
+        ],
+        "instructions": """
+Orient the learner. Recommend a pathway based on their background and goals.
+Connect learning modules to practical projects, hackathons, entrepreneurship, and deployment.
+""",
+    },
+    "AI-101 Foundations": {
+        "summary": "AI fundamentals, responsible use, careers, and practical applications.",
+        "topics": [
+            "Artificial Intelligence fundamentals",
+            "Machine Learning",
+            "Deep Learning",
+            "Large Language Models",
+            "Generative AI",
+            "Responsible AI",
+            "AI ethics",
+            "AI careers",
+            "Practical AI applications",
+        ],
+        "suggestions": [
+            "What is Artificial Intelligence?",
+            "What is the difference between AI, Machine Learning, and Generative AI?",
+            "How do Large Language Models work?",
+            "How can students use AI responsibly?",
+            "What AI career paths are available?",
+        ],
+        "instructions": """
+Teach AI foundations with simple analogies, clear definitions, responsible AI guidance,
+and practical examples for students, faculty, professionals, and entrepreneurs.
+""",
+    },
+    "Prompt Engineering": {
+        "summary": "Design better prompts, templates, evaluations, and reliable outputs.",
+        "topics": [
+            "Prompt design",
+            "Prompt optimization",
+            "Role prompting",
+            "Context setting",
+            "Few-shot prompting",
+            "Structured prompts",
+            "Reusable prompt templates",
+            "Output formatting",
+            "Prompt evaluation",
+        ],
+        "suggestions": [
+            "How do I write an effective prompt?",
+            "Improve this prompt for me.",
+            "Why is context important in prompting?",
+            "Create a reusable research prompt template.",
+            "How can I make AI responses more consistent?",
+        ],
+        "instructions": """
+Act as a prompt-engineering coach. Diagnose vague prompts, improve structure,
+offer reusable templates, and explain why each change improves reliability.
+""",
+    },
+    "Generative AI": {
+        "summary": "Text, image, code, productivity, and business uses of Generative AI.",
+        "topics": [
+            "Generative AI fundamentals",
+            "Large Language Models",
+            "Text generation",
+            "Image generation",
+            "Code generation",
+            "AI productivity",
+            "Content creation",
+            "Practical business applications",
+        ],
+        "suggestions": [
+            "How does ChatGPT work?",
+            "What can Generative AI create?",
+            "Compare major types of Generative AI tools.",
+            "How can professionals use AI productively?",
+            "What are common Generative AI business use cases?",
+        ],
+        "instructions": """
+Teach Generative AI concepts and use cases. Explain capabilities, limitations,
+responsible use, and concrete workflows for education, business, and creativity.
+""",
+    },
+    "Agentic AI": {
+        "summary": "Goals, planning, tools, memory, supervision, and agent safety.",
+        "topics": [
+            "AI agents",
+            "Agent goals",
+            "Planning",
+            "Tool calling",
+            "Memory",
+            "Multi-step workflows",
+            "Human supervision",
+            "Autonomous task execution",
+            "Agent safety",
+        ],
+        "suggestions": [
+            "What is an AI agent?",
+            "How is an agent different from a chatbot?",
+            "How do AI agents use tools?",
+            "Design a simple research agent.",
+            "Explain memory and planning in agentic systems.",
+        ],
+        "instructions": """
+Teach agentic systems with emphasis on goals, planning, tools, memory,
+human oversight, safeguards, and practical workflow design.
+""",
+    },
+    "Retrieval-Augmented Generation (RAG)": {
+        "summary": "Retrieval, embeddings, vector databases, and knowledge assistants.",
+        "topics": [
+            "RAG architecture",
+            "Embeddings",
+            "Vector databases",
+            "Knowledge retrieval",
+            "Document search",
+            "Enterprise knowledge assistants",
+            "Chunking",
+            "Retrieval quality",
+            "RAG evaluation",
+        ],
+        "suggestions": [
+            "What is Retrieval-Augmented Generation?",
+            "When should I use RAG?",
+            "Explain a simple RAG architecture.",
+            "Compare RAG with fine-tuning.",
+            "How do embeddings and vector databases work?",
+        ],
+        "instructions": """
+Teach RAG architecture and evaluation. Compare RAG with fine-tuning, explain
+chunking and retrieval quality, and use enterprise knowledge-assistant examples.
+""",
+    },
+    "Multi-Agent Systems": {
+        "summary": "Agent roles, delegation, orchestration, collaboration, and review.",
+        "topics": [
+            "Agent collaboration",
+            "Agent specialization",
+            "Agent roles",
+            "Task delegation",
+            "Workflow orchestration",
+            "Communication between agents",
+            "Supervisor agents",
+            "Quality-control agents",
+        ],
+        "suggestions": [
+            "How do multiple AI agents collaborate?",
+            "What roles can agents perform in a workflow?",
+            "Design a multi-agent research team.",
+            "What is an agent supervisor?",
+            "How can agents review one another's work?",
+        ],
+        "instructions": """
+Teach multi-agent design. Emphasize role clarity, handoffs, orchestration,
+supervisor agents, quality control, and human review.
+""",
+    },
+    "AI Workflow Design": {
+        "summary": "Turn real problems into structured, validated AI workflows.",
+        "topics": [
+            "Problem decomposition",
+            "Workflow mapping",
+            "Inputs and outputs",
+            "Decision points",
+            "Human-in-the-loop review",
+            "Tool selection",
+            "Task routing",
+            "Agent orchestration",
+            "Workflow validation",
+            "Error handling",
+            "Monitoring",
+            "Workflow optimization",
+        ],
+        "suggestions": [
+            "Design an AI workflow for customer support.",
+            "Create an AI workflow for invoice processing.",
+            "Design a healthcare appointment workflow.",
+            "Explain human-in-the-loop workflow design.",
+            "Convert this business problem into an AI workflow.",
+        ],
+        "instructions": """
+Help users convert practical problems into structured AI workflows. Identify
+inputs, outputs, decision points, tools, review steps, monitoring, and failure handling.
+""",
+    },
+    "Business Process Automation": {
+        "summary": "Automate operations across sales, support, finance, HR, and more.",
+        "topics": [
+            "Business Process Automation",
+            "Intelligent automation",
+            "Email automation",
+            "Document processing",
+            "Customer support automation",
+            "Sales automation",
+            "Marketing automation",
+            "Human resources automation",
+            "Finance automation",
+            "Operations automation",
+            "Approval workflows",
+            "Exception handling",
+            "Process measurement",
+        ],
+        "suggestions": [
+            "Automate my sales follow-up process.",
+            "Build an AI-powered HR assistant.",
+            "Design an invoice-processing system.",
+            "Automate customer-support triage.",
+            "Help me identify which business process to automate first.",
+        ],
+        "instructions": """
+Act as an AI business-automation mentor. Help users prioritize processes,
+map workflows, select tools, measure outcomes, and design exception handling.
+""",
+    },
+    "Gradio Development": {
+        "summary": "Build, debug, and deploy practical Gradio applications.",
+        "topics": [
+            "Python basics",
+            "Gradio applications",
+            "User-interface design",
+            "Blocks",
+            "Buttons",
+            "Chatbots",
+            "State management",
+            "OpenAI API integration",
+            "Error handling",
+            "Deployment",
+            "Debugging",
+        ],
+        "suggestions": [
+            "Help me build my first Gradio application.",
+            "How do I add buttons, inputs, and chatbots?",
+            "How do I connect the OpenAI API?",
+            "How does Gradio state management work?",
+            "How can I deploy a Gradio app on Hugging Face Spaces?",
+        ],
+        "instructions": """
+Teach Gradio development in beginner-friendly steps. Provide small runnable
+examples, explain Blocks, chatbot interfaces, state management, OpenAI integration,
+deployment on Hugging Face Spaces, and debugging.
+""",
+    },
+    "AI Startup Mentor": {
+        "summary": "Refine ideas, design MVPs, evaluate markets, and prepare to launch.",
+        "topics": [
+            "Startup idea refinement",
+            "Customer problems",
+            "Target markets",
+            "Customer discovery",
+            "Value propositions",
+            "Business models",
+            "MVP planning",
+            "Product-market fit",
+            "Risk analysis",
+            "Go-to-market strategy",
+            "Investor pitches",
+            "Financial assumptions",
+            "Investor readiness",
+            "Scaling",
+        ],
+        "suggestions": [
+            "Help me evaluate my startup idea.",
+            "Create a Business Model Canvas.",
+            "Help me prepare a three-minute investor pitch.",
+            "Build an MVP roadmap.",
+            "Develop a go-to-market strategy.",
+            "Identify the key risks in my startup idea.",
+        ],
+        "instructions": """
+Act as a practical startup mentor. Ask clarifying questions when needed,
+challenge assumptions, structure ideas, identify risks, and help users move
+toward investor-ready and customer-validated plans.
+""",
+    },
+    "About Pak Angels": {
+        "summary": "Learn about the Pak Angels mission and innovation ecosystem.",
+        "topics": [
+            "AI education",
+            "Entrepreneurship",
+            "Startup innovation",
+            "Technology commercialization",
+            "Investment readiness",
+            "Global Pakistani community",
+        ],
+        "suggestions": [
+            "What is Pak Angels?",
+            "How can Pak Angels support AI learners?",
+            "How can startups benefit from Pak Angels?",
+            "Suggest a Pak Angels AI training pathway.",
+        ],
+        "instructions": """
+Explain the Pak Angels mission and connect users to education, practical AI
+projects, entrepreneurship, startup innovation, and investment readiness.
+""",
+    },
+}
+
+
+ABOUT_PAK_ANGELS = """
+Pak Angels is a Silicon Valley-based global platform dedicated to accelerating
+Artificial Intelligence education, entrepreneurship, startup innovation, technology
+commercialization, and investment across Pakistan and the global Pakistani community.
+
+Pak Angels helps students, faculty, professionals, entrepreneurs, and startups
+learn, build, deploy, commercialize, and scale AI-powered solutions through
+structured education, practical application development, hackathons, mentorship,
+investment readiness, and access to global innovation ecosystems.
+"""
+
+
+def build_system_instructions(module_name: str) -> str:
+    """Compose module-specific instructions for the selected learning mode."""
+    module = MODULES.get(module_name, MODULES["Home"])
+    topics = "\n".join(f"- {topic}" for topic in module["topics"])
+    return f"""
+{BASE_TUTOR_INSTRUCTIONS}
+
+Selected learning mode: {module_name}
+Mode summary: {module["summary"]}
+
+Priority topics:
+{topics}
+
+Specialized instructions:
+{module["instructions"]}
+"""

requirements.txt

@@ -0,0 +1,2 @@
+gradio>=5.50,<6
+openai>=1.93,<2