diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..9843230 --- /dev/null +++ b/.env.example @@ -0,0 +1,4 @@ +# RunPod API Key for development and testing +# Copy this file to .env and add your actual API key +# Get your API key from: https://www.runpod.io/console/user/settings +RUNPOD_API_KEY=your_api_key_here diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..d305842 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,92 @@ +## Description + +Brief description of what this PR adds or fixes. + +## Type of Change + +- [ ] New example +- [ ] Bug fix +- [ ] Enhancement to existing example +- [ ] Documentation update +- [ ] Other (please describe): + +## Example Category + +If adding a new example, which category does it belong to? + +- [ ] 01 - Getting Started +- [ ] 02 - ML Inference +- [ ] 03 - Advanced Workers +- [ ] 04 - Scaling & Performance +- [ ] 05 - Data Workflows +- [ ] 06 - Real World Applications +- [ ] misc - Miscellaneous + +## Checklist + +### Functionality +- [ ] Example runs successfully with `flash run` +- [ ] All endpoints return correct responses +- [ ] Tested locally +- [ ] Error handling implemented + +### Code Quality +- [ ] Code follows project style guidelines +- [ ] Type hints added for function signatures +- [ ] Async functions used where appropriate +- [ ] No hardcoded credentials +- [ ] Proper logging (not print statements) + +### Documentation +- [ ] README.md included with all required sections +- [ ] Code comments added for complex logic +- [ ] API endpoints documented +- [ ] Deployment instructions included +- [ ] `.env.example` file provided + +### Dependencies +- [ ] All dependencies listed in `requirements.txt` +- [ ] Dependencies are pinned to specific versions +- [ ] `pyproject.toml` included with project metadata + +### Testing +- [ ] Manually tested all endpoints +- [ ] Unit tests added (if applicable) +- [ ] No syntax errors (`python -m py_compile`) +- [ ] Linting passes (if configured) + +### Security +- [ ] No secrets or API keys committed +- [ ] Input validation implemented +- [ ] Security best practices followed + +## What This Example Demonstrates + +List the key concepts or patterns this example demonstrates: + +1. +2. +3. + +## Testing Instructions + +How should reviewers test this example? + +```bash +# Steps to test +cd path/to/example +pip install -r requirements.txt +# Add your test steps here +``` + +## Screenshots/Output (if applicable) + +Add screenshots or example output if relevant. + +## Additional Context + +Any additional information reviewers should know about this PR. + +## Related Issues + +Closes #(issue number) diff --git a/.gitignore b/.gitignore index 93ff84a..e30da25 100644 --- a/.gitignore +++ b/.gitignore @@ -205,3 +205,4 @@ cython_debug/ marimo/_static/ marimo/_lsp/ __marimo__/ +*.pkl diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..ec7fba7 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,22 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "Python Debugger: Current File", + "type": "debugpy", + "request": "launch", + "program": "${file}", + "console": "integratedTerminal", + "python": "${workspaceFolder}/.venv/bin/python", + "cwd": "${workspaceFolder}", + "envFile": "${workspaceFolder}/.env", + "env": { + "PYTHONPATH": "${workspaceFolder}" + }, + "justMyCode": false + } + ] +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ace1a55..da862f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -173,7 +173,7 @@ if __name__ == "__main__": import uvicorn import os - port = int(os.getenv("PORT", 8000)) + port = int(os.getenv("PORT", 8888)) uvicorn.run(app, host="0.0.0.0", port=port) ``` @@ -295,17 +295,51 @@ Test your example thoroughly: flash run # Test health endpoint -curl http://localhost:8000/health +curl http://localhost:8888/health # Test your endpoints -curl -X POST http://localhost:8000/your/endpoint \ +curl -X POST http://localhost:8888/your/endpoint \ -H "Content-Type: application/json" \ -d '{"test": "data"}' # Check API docs -open http://localhost:8000/docs +open http://localhost:8888/docs ``` +### VS Code Debugging + +The repository includes VS Code debug configurations for endpoint development: + +**Setup:** + +1. Copy the root `.env.example` to `.env`: + ```bash + cp .env.example .env + ``` + +2. Add your RunPod API key to `.env`: + ```bash + RUNPOD_API_KEY=your_actual_api_key_here + ``` + +3. Ensure you have the Python extension installed in VS Code + +**Debugging:** + +Two debug configurations are available: + +- **Python Debugger: Current File** - Debug any Python file +- **Flash Worker: Debug Endpoint** - Debug worker endpoint files with async support + +To debug an endpoint: +1. Open any `endpoint.py` file (e.g., `01_getting_started/01_hello_world/workers/gpu/endpoint.py`) +2. Set breakpoints in your worker functions +3. Press F5 or select "Debug: Start Debugging" +4. Choose the appropriate debug configuration +5. The debugger will execute the `if __name__ == "__main__"` test block + +The `.env` file is automatically loaded, so your `RUNPOD_API_KEY` is available during debugging. + ### Unit Tests (Recommended) Add tests for your worker functions: diff --git a/README.md b/README.md index 1ad0f7d..35dfead 100644 --- a/README.md +++ b/README.md @@ -23,21 +23,24 @@ cd flash-examples # Install dependencies (works with uv, pip, poetry, conda, or pipenv) make dev -# Navigate to an example -cd 01_getting_started/01_hello_world +# Set your API key (choose one method): -# Install example dependencies -pip install -r requirements.txt +# Option A: Export in shell (recommended for trying multiple examples) +export RUNPOD_API_KEY=your_key_here -# Set your API key -echo "RUNPOD_API_KEY=your_key_here" > .env +# Option B: Create .env file per example (if you prefer per-example config) +# cd 01_getting_started/01_hello_world +# echo "RUNPOD_API_KEY=your_key_here" > .env -# Run locally +# Try any example +cd 01_getting_started/01_hello_world flash run -# Visit http://localhost:8000/docs +# Visit http://localhost:8888/docs ``` +**Note**: After running `make dev`, all example dependencies are installed. You can navigate to any example directory and run `flash run` immediately. The exported API key persists in your shell session across all examples. + **Alternative Setup Methods:** - **With Makefile**: `make dev` (auto-detects your package manager) - **With uv**: `uv sync && uv pip install -e .` @@ -115,12 +118,34 @@ Flash is FastAPI-centric for building production applications, while Modal focus ```bash flash init # Create new Flash project -flash run # Run development server (default: localhost:8000) +flash run # Run development server (default: localhost:8888) flash build # Build application for deployment flash deploy new # Create deployment environment flash deploy send # Deploy to Runpod ``` +## Testing Your Application + +After running `flash run`, you can test your API in two ways: + +**Option A: Using the Interactive UI** + +Visit **http://localhost:8888/docs** to use FastAPI's built-in Swagger UI where you can: +- See all available endpoints +- Test requests directly in your browser +- View request/response schemas + +**Option B: Using curl** + +Test endpoints from the command line: +```bash +curl -X POST http://localhost:8888/endpoint \ + -H "Content-Type: application/json" \ + -d '{"key": "value"}' +``` + +See individual example READMEs for specific endpoint examples. + ## Example Structure Each example follows this structure: