Add Providers API (#1013)

Co-authored-by: David Montague <[email protected]>

Author: Kludex

docs/api/models/vertexai.md

@@ -1,5 +1,10 @@
 # `pydantic_ai.models.vertexai`
 
+!!! warning "Deprecated"
+    The `VertexAIModel` is deprecated. You can use the
+    [`GoogleVertexProvider`][pydantic_ai.providers.google_vertex.GoogleVertexProvider] to authenticate with the Vertex AI API
+    and then use the [`GeminiModel`][pydantic_ai.models.gemini.GeminiModel] to use the Gemini API.
+
 Custom interface to the `*-aiplatform.googleapis.com` API for Gemini models.
 
 This model inherits from [`GeminiModel`][pydantic_ai.models.gemini.GeminiModel] with just the URL and auth method
@@ -19,24 +24,27 @@ see [model configuration for Gemini via VertexAI](../../models.md#gemini-via-ver
 
 With the default google project already configured in your environment using "application default credentials":
 
-```python {title="vertex_example_env.py"}
+```python {title="vertex_example_env.py", test="skip"}
 from pydantic_ai import Agent
 from pydantic_ai.models.vertexai import VertexAIModel
 
-model = VertexAIModel('gemini-1.5-flash')
+model = VertexAIModel('gemini-1.5-flash')  # (1)!
 agent = Agent(model)
 result = agent.run_sync('Tell me a joke.')
 print(result.data)
 #> Did you hear about the toothpaste scandal? They called it Colgate.
 ```
 
+1. The `VertexAIModel` is deprecated, you should use the [`GeminiModel`][pydantic_ai.models.gemini.GeminiModel]
+   with the [`GoogleVertexProvider`][pydantic_ai.providers.google_vertex.GoogleVertexProvider] instead.
+
 Or using a service account JSON file:
 
-```python {title="vertex_example_service_account.py"}
+```python {title="vertex_example_service_account.py" test="skip"}
 from pydantic_ai import Agent
 from pydantic_ai.models.vertexai import VertexAIModel
 
-model = VertexAIModel(
+model = VertexAIModel(  # (1)!
     'gemini-1.5-flash',
     service_account_file='path/to/service-account.json',
 )
@@ -46,4 +54,7 @@ print(result.data)
 #> Did you hear about the toothpaste scandal? They called it Colgate.
 ```
 
+1. The `VertexAIModel` is deprecated, you should use the [`GeminiModel`][pydantic_ai.models.gemini.GeminiModel]
+   with the [`GoogleVertexProvider`][pydantic_ai.providers.google_vertex.GoogleVertexProvider] instead.
+
 ::: pydantic_ai.models.vertexai

docs/api/providers.md

@@ -0,0 +1,9 @@
+# `pydantic_ai.providers`
+
+::: pydantic_ai.providers.Provider
+
+::: pydantic_ai.providers.google_vertex
+
+::: pydantic_ai.providers.openai
+
+::: pydantic_ai.providers.deepseek