Merge branch 'main' into revise_few_shot_docs

.github/workflows/pyright.yml

@@ -45,3 +45,5 @@ jobs:
         run: echo "$(poetry env info --path)/bin" >> $GITHUB_PATH
 
       - uses: jakebailey/pyright-action@v2
+        with:
+          version: 1.1.373

README.md

@@ -133,9 +133,10 @@ assert resp.age == 25
 ### Using Gemini Models
 
 Make sure you [install](https://ai.google.dev/api/python/google/generativeai#setup) the Google AI Python SDK. You should set a `GOOGLE_API_KEY` environment variable with your API key.
+Gemini tool calling also requires `jsonref` to be installed.
 
 ```
-pip install google-generativeai
+pip install google-generativeai jsonref
 ```
 
 ```python

docs/blog/.authors.yml

@@ -7,7 +7,7 @@ authors:
   ivanleomk:
     name: Ivan Leo
     description: Contributor
-    avatar: https://pbs.twimg.com/profile_images/1524186822389026816/sWRHRIkY_400x400.jpg
+    avatar: https://pbs.twimg.com/profile_images/1817176209484402688/coeHXGDR_400x400.jpg
     url: https://twitter.com/intent/follow?screen_name=ivanleomk
   anmol:
     name: Anmol Jawandha

docs/blog/posts/announcing-gemini-tool-calling-support.md

@@ -0,0 +1,115 @@
+---
+draft: False
+date: 2024-09-03
+authors:
+  - ivanleomk
+---
+
+# Structured Outputs for Gemini now supported
+
+We're excited to announce that `instructor` now supports structured outputs using tool calling for both the Gemini SDK and the VertexAI SDK.
+
+A special shoutout to [Sonal](https://x.com/sonalsaldanha) for his contributions to the Gemini Tool Calling support.
+
+Let's walk through a simple example of how to use these new features
+
+## Installation
+
+To get started, install the latest version of `instructor`. Depending on whether you're using Gemini or VertexAI, you should install the following:
+
+=== "Gemini"
+
+    ```bash
+    pip install "instructor[google-generativeai]"
+    ```
+
+=== "VertexAI"
+
+    ```bash
+    pip install "instructor[vertexai]"
+    ```
+
+This ensures that you have the necessary dependencies to use the Gemini or VertexAI SDKs with instructor.
+
+We recommend using the Gemini SDK over the VertexAI SDK for two main reasons.
+
+1. Compared to the VertexAI SDK, the Gemini SDK comes with a free daily quota of 1.5 billion tokens to use for developers.
+2. The Gemini SDK is significantly easier to setup, all you need is a `GOOGLE_API_KEY` that you can generate in your GCP console. THe VertexAI SDK on the other hand requires a credentials.json file or an OAuth integration to use.
+
+## Getting Started
+
+With our provider agnostic API, you can use the same interface to interact with both SDKs, the only thing that changes here is how we initialise the client itself.
+
+Before running the following code, you'll need to make sure that you have your Gemini API Key set in your shell under the alias `GOOGLE_API_KEY`.
+
+```python
+import instructor
+import google.generativeai as genai
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    name: str
+    age: int
+
+
+client = instructor.from_gemini(
+    client=genai.GenerativeModel(
+        model_name="models/gemini-1.5-flash-latest", # (1)!
+    )
+)
+
+resp = client.chat.completions.create(
+    messages=[
+        {
+            "role": "user",
+            "content": "Extract Jason is 25 years old.",
+        }
+    ],
+    response_model=User,
+)
+
+print(resp)
+#> name='Jason' age=25
+```
+
+1. Current Gemini models that support tool calling are `gemini-1.5-flash-latest` and `gemini-1.5-pro-latest`.
+
+We can achieve a similar thing with the VertexAI SDK. For this to work, you'll need to authenticate to VertexAI.
+
+There are some instructions [here](https://cloud.google.com/vertex-ai/docs/authentication) but the easiest way I found was to simply download the GCloud cli and run `gcloud auth application-default login`.
+
+```python
+import instructor
+import vertexai  # type: ignore
+from vertexai.generative_models import GenerativeModel  # type: ignore
+from pydantic import BaseModel
+
+vertexai.init()
+
+
+class User(BaseModel):
+    name: str
+    age: int
+
+
+client = instructor.from_vertexai(
+    client=GenerativeModel("gemini-1.5-pro-preview-0409"), # (1)!
+)
+
+
+resp = client.chat.completions.create(
+    messages=[
+        {
+            "role": "user",
+            "content": "Extract Jason is 25 years old.",
+        }
+    ],
+    response_model=User,
+)
+
+print(resp)
+#> name='Jason' age=25
+```
+
+1. Current Gemini models that support tool calling are `gemini-1.5-flash-latest` and `gemini-1.5-pro-latest`.