adding readme with intructions

README.md

@@ -11,4 +11,70 @@ license: mit
 short_description: using-external-apis
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Using external APIs (OpenAI) on Hugging Face Spaces
+
+This Space runs a small [Gradio](https://www.gradio.app/) app with **two tabs** that both call **OpenAI Chat Completions** the same way a student would in a notebook—once with plain HTTP (`requests`) and once with Hugging Face’s client (`huggingface_hub.InferenceClient`).
+
+Official Space configuration reference: [Spaces config reference](https://huggingface.co/docs/hub/spaces-config-reference).
+
+## How to use the app
+
+1. **Set your API key** (see [Secrets](#secrets-openai_api_key) below). Without `OPENAI_API_KEY`, the app will raise when it reads the environment variable.
+2. Open the Space and pick a tab:
+   - **`requests`** — builds a `POST` to `https://api.openai.com/v1/chat/completions` with JSON `model` + `messages` and a `Bearer` token header. Useful when you are teaching REST, curl, or reading OpenAI’s HTTP docs side by side with the code.
+   - **`huggingface_hub`** — creates an `InferenceClient` aimed at OpenAI’s `/v1` base URL and calls `chat.completions.create(...)`. The request shape matches the “OpenAI-style” chat API described in the [huggingface_hub inference guide](https://huggingface.co/docs/huggingface_hub/guides/inference).
+3. Type a question, submit, and read the answer in the output box. Both tabs use the same model name (`MODEL` in [`app.py`](app.py)).
+
+## Secrets: `OPENAI_API_KEY`
+
+- In the Space: **Settings → Variables and secrets** (or **Repository secrets** depending on UI), add a **secret** named exactly **`OPENAI_API_KEY`** with your OpenAI API key as the value.
+- Hugging Face exposes repository secrets to the running app as **environment variables** with the same name. The code uses `os.environ["OPENAI_API_KEY"]`—no key files, no pasting keys into the README or `app.py`.
+- **Do not** commit keys to git or put them in this README’s YAML frontmatter. If a key ever leaks, rotate it in the OpenAI dashboard.
+
+### Gotchas with secrets
+
+- **Name must match**: `OPENAI_API_KEY` (case-sensitive) must match what [`app.py`](app.py) expects.
+- **Restart**: After adding or changing a secret, **restart the Space** (or trigger a new build) if the app still behaves as if the variable were missing.
+- **Local runs**: On your laptop, export the variable yourself, for example:
+  - macOS/Linux: `export OPENAI_API_KEY="sk-..."` then run the app.
+  - Never check a `.env` file with real keys into version control.
+
+## `requirements.txt` on Hugging Face Spaces
+
+This repo’s [`requirements.txt`](requirements.txt) lists **one Python package per line**. Spaces use it to `pip install` dependencies before starting the app.
+
+- **Blank lines** are usually fine; avoid stray text that is not a valid `pip` requirement.
+- **Pinning** (e.g. `gradio==6.14.0`) improves reproducibility so a future `gradio` major release does not surprise your class. The README frontmatter’s `sdk_version` should stay compatible with the Gradio version you install (see below).
+- **Order** does not matter for `pip`, but keeping standard library–heavy teachers first (`requests`, `huggingface_hub`) can make the file easier to read.
+
+## README formatting for Hugging Face Spaces
+
+Spaces treat the top of this file specially:
+
+- The block between the **first** `---` and the **second** `---` is **YAML frontmatter**. Hugging Face reads fields like `sdk`, `sdk_version`, `app_file`, and `title` from it.
+- **Do not remove** that block unless you know how you will configure the Space elsewhere.
+- **Common gotchas**:
+  - **`app_file`** must point to the file that calls `launch()` (here: `app.py`).
+  - **`sdk_version`** should match the Gradio major/minor you rely on; a mismatch with `requirements.txt` can produce confusing import or layout errors.
+  - **Indentation** in YAML matters; keep values simple strings without unquoted colons that break parsing.
+- **Content below the closing `---`** is normal Markdown for humans (this section). You can edit it freely without changing how the Space boots, as long as the frontmatter stays valid.
+
+## Other setup gotchas
+
+- **Model name**: `MODEL` in [`app.py`](app.py) must be a model your OpenAI **account** and **billing** can access. If OpenAI returns an error, the simplified app does not catch it—you will see the raw exception in the Space logs, which is fine for teaching debugging.
+- **Network**: The Space runtime must reach `api.openai.com`. Corporate or restricted networks are rare on HF but worth knowing for local copies.
+- **`huggingface_hub` vs Hub login**: This app sends your **OpenAI** key to **OpenAI** (`base_url="https://api.openai.com/v1"`). You do **not** need a Hugging Face user token for these two tabs unless you change the code to call HF Inference Providers or the HF router instead.
+
+## Local quick start (optional)
+
+From this directory, with Python 3 and a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+export OPENAI_API_KEY="sk-..."   # use your real key; do not commit it
+python app.py
+```
+
+Then open the URL Gradio prints (often `http://127.0.0.1:7860`).