Upload 2 files

app (1).py

@@ -0,0 +1,754 @@
+import textwrap
+import gradio as gr
+
+
+def md(text: str) -> str:
+    """
+    Utility helper:
+    - Lets us write long multi-line markdown strings with indentation in the code
+    - Removes the extra left-side whitespace before Gradio renders it
+
+    This makes the file much easier to read and maintain.
+    """
+    return textwrap.dedent(text).strip()
+
+
+# ============================================================
+# KNOWLEDGE BASE
+# ------------------------------------------------------------
+# This dictionary is the heart of the teaching app.
+# The key is what appears in the dropdown.
+# The value is the markdown shown to the user.
+#
+# This pattern is important to understand:
+# - UI asks for a topic
+# - Python uses that topic as a dictionary key
+# - App returns the matching explanation
+#
+# That is a very common software pattern:
+# "user selection -> lookup -> render result"
+# ============================================================
+TOPIC_DB = {
+    "Git & GitHub": md("""
+    ## Git & GitHub
+
+    **What this is:** Git is version control. GitHub is a remote home for your code, history, branches, pull requests, and automation.
+
+    **Mental model:**
+    - Your laptop is your working lab bench.
+    - Git is the notebook that records exactly what changed and when.
+    - GitHub is the shared lab vault where other people and automation can see the notebook.
+
+    **Why it matters for AI builders:**
+    - You cannot do CI/CD cleanly without a repository.
+    - You cannot safely experiment without branches.
+    - You cannot collaborate well without pull requests and commit history.
+
+    **Core commands to understand:**
+    ```bash
+    git clone <repo-url>
+    git status
+    git add .
+    git commit -m "Describe the change"
+    git push origin main
+    git checkout -b feature/my-new-idea
+    ```
+
+    **What you should know cold:**
+    1. `clone` brings a remote repo to your machine.
+    2. `status` tells you what changed.
+    3. `add` stages changes.
+    4. `commit` saves a checkpoint in history.
+    5. `push` sends commits to GitHub.
+    6. Branches let you experiment without breaking main.
+
+    **Common mistakes:**
+    - Editing directly on `main` for risky changes.
+    - Committing secrets like API keys.
+    - Waiting too long between commits.
+
+    **Mini-project:**
+    Make a repo called `ml-platform-lab`, add one `README.md`, one `app.py`, and commit three times as you refine it.
+
+    **Free references:**
+    - Pro Git: https://git-scm.com/book/en/v2
+    - GitHub Actions docs: https://docs.github.com/actions
+    """),
+
+    "HTTP, APIs, and Requests": md("""
+    ## HTTP, APIs, and Requests
+
+    **What this is:** An API is a contract for how software talks to software. Most modern app integrations happen over HTTP.
+
+    **Mental model:**
+    - A client sends a request.
+    - A server receives it.
+    - The server returns a response, often JSON.
+
+    **The verbs that matter:**
+    - `GET` = read data
+    - `POST` = create or trigger something
+    - `PUT` / `PATCH` = update
+    - `DELETE` = remove
+
+    **Python example:**
+    ```python
+    import requests
+
+    response = requests.get("https://example.com/api/health", timeout=15)
+    print(response.status_code)
+    print(response.text)
+    ```
+
+    **What good API thinking looks like:**
+    - Clear inputs
+    - Clear outputs
+    - Explicit status codes
+    - Validation before work happens
+    - Logging when things fail
+
+    **Why this matters for ML engineers:**
+    Models are rarely used by calling Python functions directly in production. They are usually wrapped behind APIs.
+
+    **Mini-project:**
+    Call a public API, parse JSON, and render a simplified result in a Gradio textbox.
+
+    **Free references:**
+    - Requests docs: https://requests.readthedocs.io/
+    - FastAPI tutorial: https://fastapi.tiangolo.com/tutorial/
+    """),
+
+    "FastAPI & Pydantic": md("""
+    ## FastAPI & Pydantic
+
+    **What this is:** FastAPI is a Python web framework for building APIs quickly. Pydantic gives you structured, validated input and output models.
+
+    **Mental model:**
+    - FastAPI turns functions into web endpoints.
+    - Pydantic defines what valid data looks like.
+
+    **Very small example:**
+    ```python
+    from fastapi import FastAPI
+    from pydantic import BaseModel
+
+    app = FastAPI()
+
+    class PredictionRequest(BaseModel):
+        age: int
+        income: float
+
+    @app.post("/predict")
+    def predict(payload: PredictionRequest):
+        score = 0.6 if payload.income > 50000 else 0.3
+        return {"score": score}
+    ```
+
+    **Why it matters:**
+    - You already know Python.
+    - Type hints and schemas reduce ambiguity.
+    - The framework auto-generates docs, which is great for learning and debugging.
+
+    **What to understand deeply:**
+    1. Path operation decorators like `@app.get` and `@app.post`
+    2. Request body vs query parameters
+    3. Validation errors
+    4. JSON in, JSON out
+    5. Separation of app layer from model layer
+
+    **Mini-project:**
+    Put a toy model or even a rules engine behind `/predict`, then call it from a notebook or another Python script.
+
+    **Free references:**
+    - FastAPI main docs: https://fastapi.tiangolo.com/
+    - FastAPI tutorial: https://fastapi.tiangolo.com/tutorial/
+    """),
+
+    "Docker": md("""
+    ## Docker
+
+    **What this is:** Docker packages your app and its runtime into a container so it runs more consistently across machines.
+
+    **Mental model:**
+    - Your code alone is not enough.
+    - You also need the right Python version, packages, and startup command.
+    - A container bundles those together.
+
+    **Useful distinction:**
+    - **Image** = blueprint
+    - **Container** = running instance from the blueprint
+
+    **Tiny Dockerfile example:**
+    ```dockerfile
+    FROM python:3.10-slim
+    WORKDIR /app
+    COPY requirements.txt .
+    RUN pip install --no-cache-dir -r requirements.txt
+    COPY . .
+    CMD ["python", "app.py"]
+    ```
+
+    **Why it matters for you:**
+    Docker is the bridge between "it works on my laptop" and "it works in a deployment target."
+
+    **Mini-project:**
+    Containerize a FastAPI hello-world app and run it locally.
+
+    **Free references:**
+    - Docker overview: https://docs.docker.com/get-started/docker-overview/
+    - Docker getting started: https://docs.docker.com/get-started/
+    """),
+
+    "CI/CD with GitHub Actions": md("""
+    ## CI/CD with GitHub Actions
+
+    **What this is:** CI/CD automates build, test, and deployment workflows. GitHub Actions runs those workflows from your repository.
+
+    **Mental model:**
+    - A code change happens.
+    - Automation wakes up.
+    - Tests run.
+    - Optional deployment happens only if checks pass.
+
+    **Minimal workflow example:**
+    ```yaml
+    name: ci
+    on: [push, pull_request]
+    jobs:
+      test:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - uses: actions/setup-python@v5
+            with:
+              python-version: '3.10'
+          - run: python -m pip install --upgrade pip
+          - run: pip install -r requirements.txt
+          - run: python -m py_compile app.py
+    ```
+
+    **Why it matters:**
+    - Catch issues before deployment.
+    - Standardize checks.
+    - Create trust in main branch.
+
+    **Mini-project:**
+    Add the above workflow to a repo and make sure every push at least syntax-checks your app.
+
+    **Free references:**
+    - GitHub Actions quickstart: https://docs.github.com/actions/quickstart
+    - GitHub Actions docs: https://docs.github.com/actions
+    """),
+
+    "Kubernetes": md("""
+    ## Kubernetes
+
+    **What this is:** Kubernetes orchestrates containers across machines. It helps with scaling, rolling updates, service discovery, health checks, and resilience.
+
+    **Mental model:**
+    Docker gives you one packaged app. Kubernetes manages many running containers in a controlled cluster environment.
+
+    **What not to do:**
+    Do not start here unless you already understand local Python apps, APIs, Git, containers, and one simple deployment target.
+
+    **Terms you should recognize:**
+    - Pod
+    - Deployment
+    - Service
+    - Ingress
+    - ConfigMap
+    - Secret
+
+    **Why it matters:**
+    Even if you are not the platform engineer, you need to be able to read deployment conversations and debug the shape of a service.
+
+    **Mini-project:**
+    Read one minimal deployment YAML and explain it line by line. That is enough for a first pass.
+
+    **Free references:**
+    - Kubernetes docs: https://kubernetes.io/docs/home/
+    """),
+
+    "MCP": md("""
+    ## MCP (Model Context Protocol)
+
+    **What this is:** MCP is a standard for connecting AI applications to tools, resources, and prompts.
+
+    **Mental model:**
+    - A normal REST API exposes endpoints for software-to-software use.
+    - An MCP server exposes capabilities that an AI client can discover and use more natively.
+
+    **Three ideas to know:**
+    - **Resources**: readable context, like files or database-derived information
+    - **Tools**: callable actions
+    - **Prompts**: pre-defined reusable instructions
+
+    **Why it matters:**
+    As AI products become more tool-using and context-rich, MCP gives a cleaner interoperability model than one-off custom glue code.
+
+    **Mini-project:**
+    Read the architecture overview and build one mental map showing client, server, tools, and resources.
+
+    **Free references:**
+    - MCP home: https://modelcontextprotocol.io/
+    - Architecture overview: https://modelcontextprotocol.io/docs/learn/architecture
+    - Build a server: https://modelcontextprotocol.io/docs/develop/build-server
+    """),
+
+    "MLOps & Deployment Thinking": md("""
+    ## MLOps & Deployment Thinking
+
+    **What this is:** MLOps is the set of practices for getting models and AI systems into reliable operation.
+
+    **Mental model:**
+    Training a model is only one stage. Real systems need:
+    1. data ingestion
+    2. feature logic
+    3. model or prompting layer
+    4. validation
+    5. serving
+    6. logging
+    7. monitoring
+    8. iteration
+
+    **For your background:**
+    You already have the quantitative side. The gap is usually on packaging, interfaces, environments, and lifecycle reliability.
+
+    **Your shortest path to competence:**
+    - build a toy rule-based service
+    - convert it to a FastAPI endpoint
+    - wrap it in Docker
+    - add CI
+    - deploy it
+    - explain the architecture in plain English
+
+    **Free references:**
+    - Full Stack Deep Learning: https://fullstackdeeplearning.com/
+    - Hugging Face Learn: https://huggingface.co/learn
+    """)
+}
+
+
+REFERENCE_LIBRARY = md("""
+# Free references inside this app
+
+## Official docs and free learning resources
+- Git / Pro Git: https://git-scm.com/book/en/v2
+- Requests: https://requests.readthedocs.io/
+- FastAPI: https://fastapi.tiangolo.com/
+- Docker Get Started: https://docs.docker.com/get-started/
+- GitHub Actions: https://docs.github.com/actions
+- Kubernetes docs: https://kubernetes.io/docs/home/
+- Model Context Protocol: https://modelcontextprotocol.io/
+- Hugging Face Learn: https://huggingface.co/learn
+- Full Stack Deep Learning: https://fullstackdeeplearning.com/
+
+## Suggested order for you
+1. Git basics
+2. HTTP + requests
+3. FastAPI + Pydantic
+4. Docker
+5. GitHub Actions
+6. Deploy a Space or small web service
+7. Kubernetes fundamentals
+8. MCP fundamentals
+""")
+
+
+DEPLOY_GUIDE = md("""
+# How to deploy this app to a Gradio Space
+
+1. Create a new Hugging Face Space.
+2. Pick **Gradio** as the SDK.
+3. Replace the repo's `README.md` with a metadata block that includes `sdk: gradio` and `app_file: app.py`.
+4. Add this `app.py` file.
+5. Add the `requirements.txt` file provided with this package.
+6. Commit the files.
+7. Open the Space once the build finishes.
+
+## Why the files matter
+- `README.md` contains the Space metadata block.
+- `app.py` is the main application file.
+- `requirements.txt` lists the Python dependencies.
+
+## Next level
+Once you understand this app, create a second repo where you replace the pure-Python recommendation functions with a real FastAPI backend or a model-serving layer.
+""")
+
+
+def render_topic(topic: str) -> str:
+    return TOPIC_DB.get(topic, "Select a topic.")
+
+
+def recommend_stack(primary_goal, deployment_target, data_type, team_size, hours_per_week):
+    if primary_goal == "Ship ML/AI demos reliably":
+        order = [
+            "Gradio app -> Git -> GitHub -> Docker basics -> GitHub Actions -> hosted deployment",
+            "Then repeat the same project as a FastAPI service.",
+            "Only after that, learn Kubernetes vocabulary and deployment anatomy.",
+        ]
+        first_project = "Build one demo that takes input, returns a decision, and logs edge cases."
+
+    elif primary_goal == "Build real APIs for models":
+        order = [
+            "HTTP fundamentals -> requests -> FastAPI -> Pydantic -> local testing",
+            "Then containerize with Docker and add CI.",
+            "Deploy after the local and container versions both work cleanly.",
+        ]
+        first_project = "Create `/health` and `/predict` endpoints for a toy model or rules engine."
+
+    elif primary_goal == "Understand platform / DevOps conversations":
+        order = [
+            "Git and CI/CD language first.",
+            "Docker concepts second.",
+            "Kubernetes objects third: pod, deployment, service, ingress, secret.",
+            "MCP after you already understand tools, services, and interfaces.",
+        ]
+        first_project = "Take one deployment diagram and explain every box, arrow, and environment variable."
+
+    else:
+        order = [
+            "Git -> APIs -> FastAPI -> Docker -> CI/CD -> deployment -> Kubernetes basics -> MCP",
+            "Do not split attention across five stacks at once.",
+            "Use one project as the backbone for every new concept.",
+        ]
+        first_project = "Build a single project repeatedly in deeper forms instead of many unrelated mini-projects."
+
+    complexity = "solo-friendly" if team_size == "Solo / 1-2 people" else "team-process aware"
+
+    time_note = (
+        "You have enough time each week to make real progress; prioritize shipping one working artifact weekly."
+        if hours_per_week >= 8
+        else "Keep the scope tiny and focus on one working deliverable per week."
+    )
+
+    if deployment_target == "Hugging Face Space":
+        deploy_note = "Start with Gradio Spaces for speed and confidence, then graduate to Dockerized apps."
+    elif deployment_target == "Cloud VM / simple host":
+        deploy_note = "Bias toward FastAPI + Docker because that stack transfers better to generic hosting."
+    else:
+        deploy_note = "Learn Docker deeply before touching cluster-level concepts."
+
+    data_note = {
+        "Mostly tabular / structured": "Tabular data makes it easy to prototype small prediction or scoring services.",
+        "Mostly text / documents": "Text workflows pair naturally with LLM-style apps, extraction, routing, and summarization.",
+        "Mixed / multimodal": "Mixed inputs are powerful but easier to overcomplicate. Start with one narrow slice.",
+    }[data_type]
+
+    bullets = "\n".join([f"- {line}" for line in order])
+
+    return md(f"""
+    ## Recommended pathway
+
+    **Primary goal:** {primary_goal}
+
+    **Recommended learning/build order:**
+    {bullets}
+
+    **First project:** {first_project}
+
+    **Deployment note:** {deploy_note}
+
+    **Data note:** {data_note}
+
+    **Process note:** You are working in a **{complexity}** mode.
+
+    **Time note:** {time_note}
+
+    ## What success looks like after 30 days
+    1. You can explain the difference between a script, an API, a container, CI/CD, and orchestration.
+    2. You can deploy one Gradio app and one FastAPI-style service prototype.
+    3. You can read a Dockerfile and a GitHub Actions workflow without feeling lost.
+    4. You can follow an MCP tutorial without the terminology feeling alien.
+    """)
+
+
+SCAFFOLDS = {
+    "Gradio teaching app": md("""
+    ## Blueprint: Gradio teaching app
+
+    ```text
+    project/
+    ├── README.md
+    ├── app.py
+    └── assets/                # optional images or data files
+    ```
+
+    **Purpose:** Best first deployment target when speed matters more than backend purity.
+
+    **What to practice:**
+    - UI layout
+    - Python functions as app logic
+    - deployment flow on Hugging Face Spaces
+    - simple input/output design
+
+    **Good first extension:**
+    Add a logging area, examples, or a quiz tab.
+    """),
+
+    "FastAPI microservice": md("""
+    ## Blueprint: FastAPI microservice
+
+    ```text
+    project/
+    ├── README.md
+    ├── requirements.txt
+    ├── app/
+    │   ├── main.py
+    │   ├── schemas.py
+    │   ├── services.py
+    │   └── utils.py
+    └── tests/
+        └── test_smoke.py
+    ```
+
+    **Purpose:** Best when you need explicit API endpoints and cleaner production migration.
+
+    **What to practice:**
+    - request/response models
+    - validation
+    - separation of business logic from web layer
+    - testability
+
+    **Good first extension:**
+    Add `/health` and `/predict`, then call the service from a notebook or a Gradio front end.
+    """),
+
+    "Dockerized ML service": md("""
+    ## Blueprint: Dockerized ML service
+
+    ```text
+    project/
+    ├── README.md
+    ├── requirements.txt
+    ├── Dockerfile
+    ├── .dockerignore
+    ├── app/
+    │   ├── main.py
+    │   ├── model_logic.py
+    │   └── schemas.py
+    └── tests/
+        └── test_api.py
+    ```
+
+    **Purpose:** Best bridge from local development to reliable deployment.
+
+    **What to practice:**
+    - image creation
+    - environment management
+    - startup commands
+    - reproducibility
+
+    **Good first extension:**
+    Add CI that syntax-checks and builds the container automatically.
+    """),
+
+    "CI/CD-ready repo": md("""
+    ## Blueprint: CI/CD-ready repo
+
+    ```text
+    project/
+    ├── README.md
+    ├── requirements.txt
+    ├── app.py
+    └── .github/
+        └── workflows/
+            └── ci.yml
+    ```
+
+    **Purpose:** Best for learning automated quality gates early.
+
+    **What to practice:**
+    - event triggers on push and pull request
+    - deterministic install steps
+    - automated syntax checks or tests
+
+    **Good first extension:**
+    Add Docker build or deployment steps after the basic checks pass.
+    """)
+}
+
+
+def render_scaffold(name: str) -> str:
+    return SCAFFOLDS.get(name, "Select a blueprint.")
+
+
+QUIZ_KEY = {
+    "q1": "An app contract for software-to-software communication",
+    "q2": "A package blueprint used to create running containers",
+    "q3": "Automating build, test, and deployment workflows",
+    "q4": "A Python framework for building APIs",
+    "q5": "The main file path for the Space app",
+    "q6": "A standard for exposing AI tools, resources, and prompts",
+}
+
+
+def grade_quiz(q1, q2, q3, q4, q5, q6):
+    answers = {"q1": q1, "q2": q2, "q3": q3, "q4": q4, "q5": q5, "q6": q6}
+    score = sum(1 for key, value in answers.items() if value == QUIZ_KEY[key])
+
+    feedback = []
+    for key, expected in QUIZ_KEY.items():
+        status = "✅" if answers[key] == expected else "❌"
+        feedback.append(f"{status} {key.upper()}: {expected}")
+
+    feedback_md = "\n".join([f"- {item}" for item in feedback])
+
+    if score == 6:
+        verdict = "Excellent. You are reading the platform vocabulary correctly."
+    elif score >= 4:
+        verdict = "Good. You are close, but a few terms still need repetition."
+    else:
+        verdict = "This is normal early on. Revisit the Concept Explorer and do one small build step next."
+
+    return md(f"""
+    ## Score: {score}/6
+
+    **Verdict:** {verdict}
+
+    **Answer key:**
+    {feedback_md}
+    """)
+
+
+INTRO = md("""
+# AI Platform Engineering Accelerator
+
+This Space is built for a technically strong ML/physics person who wants to close the gap on software engineering, APIs, deployment, CI/CD, containers, Kubernetes, and MCP.
+
+## How to use this app
+1. Start in **Concept Explorer** and read one topic at a time.
+2. Go to **Architecture Lab** and let the app recommend an order of operations.
+3. Use **Repo Blueprint** to understand what a minimal project should look like.
+4. Use **Self-Check** to make sure the vocabulary is sticking.
+5. Read **Deploy This Space** so you understand how the app itself is hosted.
+
+## Important learning philosophy
+Do not try to become a Kubernetes wizard first.
+Become the person who can reliably ship one small Python service end to end.
+""")
+
+
+with gr.Blocks(title="AI Platform Engineering Accelerator") as demo:
+    gr.Markdown(INTRO)
+
+    with gr.Tab("Concept Explorer"):
+        topic = gr.Dropdown(list(TOPIC_DB.keys()), value="Git & GitHub", label="Pick a topic")
+        topic_btn = gr.Button("Explain this topic")
+        topic_out = gr.Markdown(value=render_topic("Git & GitHub"))
+        topic_btn.click(render_topic, inputs=topic, outputs=topic_out)
+
+    with gr.Tab("Architecture Lab"):
+        primary_goal = gr.Radio(
+            [
+                "Ship ML/AI demos reliably",
+                "Build real APIs for models",
+                "Understand platform / DevOps conversations",
+                "Become end-to-end technical as fast as possible",
+            ],
+            value="Become end-to-end technical as fast as possible",
+            label="What is your main goal right now?",
+        )
+
+        deployment_target = gr.Radio(
+            ["Hugging Face Space", "Cloud VM / simple host", "Kubernetes later"],
+            value="Hugging Face Space",
+            label="What deployment target feels most realistic first?",
+        )
+
+        data_type = gr.Radio(
+            ["Mostly tabular / structured", "Mostly text / documents", "Mixed / multimodal"],
+            value="Mostly text / documents",
+            label="What kind of AI work are you most likely to build first?",
+        )
+
+        team_size = gr.Radio(
+            ["Solo / 1-2 people", "Small team / cross-functional"],
+            value="Solo / 1-2 people",
+            label="What is your current working mode?",
+        )
+
+        hours_per_week = gr.Slider(2, 20, value=8, step=1, label="Hours per week you can seriously invest")
+
+        plan_btn = gr.Button("Generate my pathway")
+        plan_out = gr.Markdown()
+
+        plan_btn.click(
+            recommend_stack,
+            inputs=[primary_goal, deployment_target, data_type, team_size, hours_per_week],
+            outputs=plan_out,
+        )
+
+    with gr.Tab("Repo Blueprint"):
+        scaffold = gr.Radio(list(SCAFFOLDS.keys()), value="Gradio teaching app", label="Choose a project blueprint")
+        scaffold_btn = gr.Button("Show blueprint")
+        scaffold_out = gr.Markdown(value=render_scaffold("Gradio teaching app"))
+        scaffold_btn.click(render_scaffold, inputs=scaffold, outputs=scaffold_out)
+
+    with gr.Tab("Self-Check"):
+        q1 = gr.Radio(
+            [
+                "A database schema",
+                "An app contract for software-to-software communication",
+                "A container orchestrator",
+            ],
+            label="1) What is an API?",
+        )
+
+        q2 = gr.Radio(
+            [
+                "A package blueprint used to create running containers",
+                "A live cluster node",
+                "A Git branch",
+            ],
+            label="2) What is a Docker image?",
+        )
+
+        q3 = gr.Radio(
+            [
+                "A way to label datasets",
+                "Automating build, test, and deployment workflows",
+                "A Python package manager",
+            ],
+            label="3) What is CI/CD?",
+        )
+
+        q4 = gr.Radio(
+            [
+                "A Python framework for building APIs",
+                "A GPU runtime",
+                "A GitHub feature for branches",
+            ],
+            label="4) What is FastAPI?",
+        )
+
+        q5 = gr.Radio(
+            [
+                "The name of the Space owner",
+                "The main file path for the Space app",
+                "A private token",
+            ],
+            label="5) In a Hugging Face Space README metadata block, what is `app_file` for?",
+        )
+
+        q6 = gr.Radio(
+            [
+                "A standard for exposing AI tools, resources, and prompts",
+                "A Linux package manager",
+                "A database migration strategy",
+            ],
+            label="6) What is MCP?",
+        )
+
+        quiz_btn = gr.Button("Grade quiz")
+        quiz_out = gr.Markdown()
+        quiz_btn.click(grade_quiz, inputs=[q1, q2, q3, q4, q5, q6], outputs=quiz_out)
+
+    with gr.Tab("Deploy This Space"):
+        gr.Markdown(DEPLOY_GUIDE)
+
+    with gr.Tab("References"):
+        gr.Markdown(REFERENCE_LIBRARY)
+
+
+demo.launch()

requirements (1).txt

@@ -0,0 +1 @@
+gradio>=5.0