Explain a snippet

Paste a piece of code or a shell one-liner. The model returns one short

README Try it Source

Showcase — Explain a snippet

Paste a piece of code or a shell one-liner. The model returns one short paragraph of plain-English explanation. One API call, useful from the first minute.

Run

bash bootstrap-secrets.sh              # reads ../../../../.env, writes secrets/
docker compose up --build              # default: PROVIDER=openai

Open http://localhost:3000.

To run against Gemini instead:

PROVIDER=gemini docker compose up --build

What's where

backend/ai_openai.py — the OpenAI call (this week's lesson, applied)
backend/ai_gemini.py — the Gemini call (same lesson, other SDK)
backend/main.py — FastAPI that loads ai_<PROVIDER> and exposes /api/ai
frontend/app/page.tsx — single form + result <pre>
docker-compose.yml — two services, secrets mounted from ./secrets/

Stop

docker compose down

Reclaim disk after a session (the Next.js image is ~150 MB):

docker compose down --rmi all -v

Run locally

Download the project as a ZIP and run it with Docker. Brings up a FastAPI backend + Next.js frontend on localhost:3000.

Download explain-snippet.zip

unzip explain-snippet.zip
cd explain-snippet
bash bootstrap-secrets.sh   # one-time: pulls API keys into ./secrets
docker compose up --build   # default provider: openai
# or:  PROVIDER=gemini docker compose up --build

Type some input, pick a provider, and run the same code shown in Source against the live API. Sign-in required.

Input

Provider

Output

The same modules the Run button hits. The whole project (frontend, Dockerfile, compose) is in the ZIP under README.

`backend/ai_openai.py`

"""Week 1 - Showcase 1 (OpenAI): explain a code or shell snippet.

Same one API call as the basic example, pointed at something useful.
"""
from openai import OpenAI

_client = OpenAI()  # reads OPENAI_API_KEY from the environment.


def run(snippet: str) -> str:
    prompt = (
        "Explain the following code or shell one-liner in one short paragraph. "
        "Be precise about what each non-obvious flag, operator, or function call "
        "means. Prose only; do not include code in your answer."
        f"\n\n---\n{snippet}\n---"
    )
    # max_output_tokens caps the response length so an unexpected
    # input can't run up the bill. 2048 tokens (~6k chars) is plenty
    # for a one-paragraph explanation.
    response = _client.responses.create(
        model="gpt-5.4-nano", input=prompt, max_output_tokens=2048,
    )
    return response.output_text

`backend/ai_gemini.py`

"""Week 1 - Showcase 1 (Gemini): explain a code or shell snippet."""
import os

from google import genai
from google.genai import types

_client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])


def run(snippet: str) -> str:
    prompt = (
        "Explain the following code or shell one-liner in one short paragraph. "
        "Be precise about what each non-obvious flag, operator, or function call "
        "means. Prose only; do not include code in your answer."
        f"\n\n---\n{snippet}\n---"
    )
    # Cap the response length so a pathological input can't make the
    # model write an essay. 2048 tokens (~6k chars) is plenty for a
    # one-paragraph explanation.
    response = _client.models.generate_content(
        model="gemini-3.1-flash-lite", contents=prompt,
        config=types.GenerateContentConfig(max_output_tokens=2048),
    )
    return response.text