diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml new file mode 100644 index 0000000..82f8dbd --- /dev/null +++ b/.github/workflows/python-publish.yml @@ -0,0 +1,70 @@ +# This workflow will upload a Python Package to PyPI when a release is created +# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries + +# This workflow uses actions that are not certified by GitHub. +# They are provided by a third-party and are governed by +# separate terms of service, privacy policy, and support +# documentation. + +name: Upload Python Package + +on: + release: + types: [published] + +permissions: + contents: read + +jobs: + release-build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + + - name: Build release distributions + run: | + # NOTE: put your own distribution build steps here. + python -m pip install build + python -m build + + - name: Upload distributions + uses: actions/upload-artifact@v4 + with: + name: release-dists + path: dist/ + + pypi-publish: + runs-on: ubuntu-latest + needs: + - release-build + permissions: + # IMPORTANT: this permission is mandatory for trusted publishing + id-token: write + + # Dedicated environments with protections for publishing are strongly recommended. + # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules + environment: + name: pypi + # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status: + # url: https://pypi.org/p/YOURPROJECT + # + # ALTERNATIVE: if your GitHub Release name is the PyPI project version string + # ALTERNATIVE: exactly, uncomment the following line instead: + # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }} + + steps: + - name: Retrieve release distributions + uses: actions/download-artifact@v4 + with: + name: release-dists + path: dist/ + + - name: Publish release distributions to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + packages-dir: dist/ diff --git a/quickstarts/Authentication.ipynb b/quickstarts/Authentication.ipynb new file mode 100644 index 0000000..fc8e7a8 --- /dev/null +++ b/quickstarts/Authentication.ipynb @@ -0,0 +1,347 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "id": "view-in-github", + "colab_type": "text" + }, + "source": [ + "\"Open" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "Tce3stUlHN0L" + }, + "source": [ + "##### Copyright 2026 Google LLC." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "cellView": "form", + "id": "tuOe1ymfHZPu" + }, + "outputs": [], + "source": [ + "# @title Licensed under the Apache License, Version 2.0 (the \"License\");\n", + "# you may not use this file except in compliance with the License.\n", + "# You may obtain a copy of the License at\n", + "#\n", + "# https://www.apache.org/licenses/LICENSE-2.0\n", + "#\n", + "# Unless required by applicable law or agreed to in writing, software\n", + "# distributed under the License is distributed on an \"AS IS\" BASIS,\n", + "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", + "# See the License for the specific language governing permissions and\n", + "# limitations under the License." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "yeadDkMiISin" + }, + "source": [ + "# Gemini API: Authentication Quickstart" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "lEXQ3OwKIa-O" + }, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "df1767a3d1cc" + }, + "source": [ + "The Gemini API uses API keys for authentication. This notebook walks you through creating an API key, and using it with the Python SDK or a command-line tool like `curl`." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "mhFKmRmxi5B-" + }, + "source": [ + "## Create an API key\n", + "\n", + "You can [create](https://aistudio.google.com/app/apikey) your API key using Google AI Studio with a single click. \n", + "\n", + "Remember to treat your API key like a password. Don't accidentally save it in a notebook or source file you later commit to GitHub. This notebook shows you two ways you can securely store your API key.\n", + "\n", + "* If you're using Google Colab, it's recommended to store your key in Colab Secrets.\n", + "\n", + "* If you're using a different development environment (or calling the Gemini API through `cURL` in your terminal), it's recommended to store your key in an [environment variable](https://en.wikipedia.org/wiki/Environment_variable).\n", + "\n", + "Let's start with Colab Secrets." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "dEoigYI9Jw_K" + }, + "source": [ + "## Add your key to Colab Secrets\n", + "\n", + "Add your API key to the Colab Secrets manager to securely store it.\n", + "\n", + "1. Open your Google Colab notebook and click on the 🔑 **Secrets** tab in the left panel.\n", + " \n", + " \"You\n", + "\n", + "2. Create a new secret with the name `GOOGLE_API_KEY`.\n", + "3. Copy and paste your API key into the `Value` input box of `GOOGLE_API_KEY`.\n", + "4. Toggle the button on the left to allow all notebooks access to the secret.\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "jRY1eioF4gUB" + }, + "source": [ + "## Install the Python SDK" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "id": "xuiLSV7amy3P" + }, + "outputs": [], + "source": [ + "%pip install -qU 'google-genai>=1.0.0'" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "3dw8ygh74mVc" + }, + "source": [ + "## Configure the SDK with your API key\n", + "\n", + "You create a client using your API key, but instead of pasting your key into the notebook, you'll read it from Colab Secrets thanks to `userdata`." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": { + "id": "DTl-qZp34sht", + "colab": { + "base_uri": "https://localhost:8080/", + "height": 635 + }, + "outputId": "12619ea0-e71a-4eee-ed0d-1ff16cbcf8f4" + }, + "outputs": [ + { + "output_type": "error", + "ename": "SecretNotFoundError", + "evalue": "Secret GOOGLE_API_KEY does not exist.", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mSecretNotFoundError\u001b[0m Traceback (most recent call last)", + "\u001b[0;32m/tmp/ipython-input-445/613123558.py\u001b[0m in \u001b[0;36m\u001b[0;34m()\u001b[0m\n\u001b[1;32m 2\u001b[0m \u001b[0;32mfrom\u001b[0m \u001b[0mgoogle\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mcolab\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0muserdata\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 3\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 4\u001b[0;31m \u001b[0mGOOGLE_API_KEY\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0muserdata\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mget\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'GOOGLE_API_KEY'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m 5\u001b[0m \u001b[0mclient\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mgenai\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mClient\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mapi_key\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mGOOGLE_API_KEY\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", + "\u001b[0;32m/usr/local/lib/python3.12/dist-packages/google/colab/userdata.py\u001b[0m in \u001b[0;36mget\u001b[0;34m(key)\u001b[0m\n\u001b[1;32m 66\u001b[0m \u001b[0;32mraise\u001b[0m \u001b[0mTimeoutException\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mkey\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 67\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0mresp\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mget\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'exists'\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;32mFalse\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 68\u001b[0;31m \u001b[0;32mraise\u001b[0m \u001b[0mSecretNotFoundError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mkey\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m 69\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0mresp\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mget\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'access'\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;32mFalse\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 70\u001b[0m \u001b[0;32mraise\u001b[0m \u001b[0mNotebookAccessError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mkey\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", + "\u001b[0;31mSecretNotFoundError\u001b[0m: Secret GOOGLE_API_KEY does not exist." + ] + } + ], + "source": [ + "from google import genai\n", + "from google.colab import userdata\n", + "\n", + "GOOGLE_API_KEY = userdata.get('GOOGLE_API_KEY')\n", + "client = genai.Client(api_key=GOOGLE_API_KEY)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "b7ceb7517bf5" + }, + "source": [ + "Now choose a model. The Gemini API offers different models that are optimized for specific use cases. For more information check [Gemini models](https://ai.google.dev/gemini-api/docs/models)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "7135d9ae3e4b" + }, + "outputs": [], + "source": [ + "MODEL_ID = \"gen-lang-client-0855989148\" # @param [\"gemini-2.5-flash-lite\", \"gemini-2.5-flash\", \"gemini-2.5-pro\", \"gemini-2.5-flash-preview\", \"gemini-3.1-pro-preview\"] {\"allow-input\":true, isTemplate: true}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "e27d4e31" + }, + "source": [ + "### التفاعل المباشر مع نموذج Gemini الخاص بك\n", + "الآن يمكنك استخدام `MODEL_ID` الذي حددته لإجراء محادثة تفاعلية مع نموذج Gemini. أدخل سؤالك في مربع الإدخال واضغط Enter للحصول على رد. اكتب 'exit' في أي وقت لإنهاء التفاعل." + ] + }, + { + "cell_type": "code", + "metadata": { + "id": "0a31a9d0" + }, + "source": [ + "import sys\n", + "\n", + "print(f\"بدء التفاعل مع نموذج Gemini: {MODEL_ID}\")\n", + "print(\"اكتب 'exit' للخروج.\")\n", + "\n", + "while True:\n", + " user_input = input(\"أنت: \")\n", + " if user_input.lower() == 'exit':\n", + " print(\"إنهاء التفاعل.\")\n", + " break\n", + "\n", + " try:\n", + " response = client.models.generate_content(\n", + " model=MODEL_ID,\n", + " contents=user_input\n", + " )\n", + " print(f\"نموذج Gemini: {response.text}\")\n", + " except Exception as e:\n", + " print(f\"حدث خطأ: {e}\")\n", + " print(\"يرجى التأكد من تعيين 'GOOGLE_API_KEY' و 'MODEL_ID' بشكل صحيح.\")\n", + " break\n" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "tr7oAO6-nMsE" + }, + "source": [ + "And that's it! Now you're ready to call the Gemini API." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "n6sXnWrJoKoo" + }, + "outputs": [], + "source": [ + "from IPython.display import Markdown\n", + "\n", + "response = client.models.generate_content(\n", + " model=MODEL_ID,\n", + " contents=\"Please give me python code to sort a list.\"\n", + ")\n", + "\n", + "display(Markdown(response.text))" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "BTdQtZri1Brs" + }, + "source": [ + "## Store your key in an environment variable" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "gZDX51Y27pN4" + }, + "source": [ + "If you're using a different development environment (or calling the Gemini API through `cURL` in your terminal), it's recommended to store your key in an environment variable.\n", + "\n", + "To store your key in an environment variable, open your terminal and run:\n", + "\n", + "```export GOOGLE_API_KEY=\"YOUR_API_KEY\"```\n", + "\n", + "If you're using Python, you can add these two lines to your notebook to read the key:\n", + "\n", + "```\n", + "import os\n", + "client = genai.Client(api_key=os.environ['GOOGLE_API_KEY'])\n", + "```\n", + "\n", + "Alternatively, if it isn't provided explicitly, the client will look for the API key.\n", + "\n", + "```\n", + "client = genai.Client()\n", + "```\n", + "\n", + "Or, if you're calling the API through your terminal using `cURL`, you can copy and paste this code to read your key from the environment variable.\n", + "\n", + "```\n", + "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GOOGLE_API_KEY\" \\\n", + " -H 'Content-Type: application/json' \\\n", + " -X POST \\\n", + " -d '{\n", + " \"contents\": [{\n", + " \"parts\":[{\n", + " \"text\": \"Please give me Python code to sort a list.\"\n", + " }]\n", + " }]\n", + " }'\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "CAOKOcax1xZY" + }, + "source": [ + "## Learning more\n", + "\n", + "Now that you know how to manage your API key, you've everything to [get started](./Get_started.ipynb) with Gemini. Check all the [quickstart guides](https://github.com/google-gemini/cookbook/tree/main/quickstarts) from the Cookbook, and in particular the [Get started](./Get_started.ipynb) one." + ] + } + ], + "metadata": { + "colab": { + "name": "Authentication.ipynb", + "provenance": [], + "include_colab_link": true + }, + "google": { + "image_path": "/site-assets/images/share.png", + "keywords": [ + "examples", + "googleai", + "samplecode", + "python", + "embed", + "function" + ] + }, + "kernelspec": { + "display_name": "Python 3", + "name": "python3" + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} \ No newline at end of file