add model documentation (#250)

Co-authored-by: Sydney Runkle <[email protected]>

Author: samuelcolvin

Makefile

@@ -114,13 +114,13 @@ all: format lint typecheck testcov ## Run code formatting, linting, static type
 
 .PHONY: help
 help: ## Show this help (usage: make help)
-	@echo "Usage: make [target]"
-	@echo "Targets:"
+	@echo "Usage: make [recipe]"
+	@echo "Recipes:"
 	@awk '/^[a-zA-Z0-9_-]+:.*?##/ { \
 		helpMessage = match($$0, /## (.*)/); \
 		if (helpMessage) { \
-			target = $$1; \
-			sub(/:/, "", target); \
-			printf "  \033[36m%-20s\033[0m %s\n", target, substr($$0, RSTART + 3, RLENGTH); \
+			recipe = $$1; \
+			sub(/:/, "", recipe); \
+			printf "  \033[36m%-20s\033[0m %s\n", recipe, substr($$0, RSTART + 3, RLENGTH); \
 		} \
 	}' $(MAKEFILE_LIST)

docs/api/models/anthropic.md

@@ -2,6 +2,6 @@
 
 ## Setup
 
-For details on how to set up authentication with this model, see [model configuration for Anthropic](../../install.md#anthropic).
+For details on how to set up authentication with this model, see [model configuration for Anthropic](../../models.md#anthropic).
 
 ::: pydantic_ai.models.anthropic

docs/api/models/function.md

@@ -2,9 +2,49 @@
 
 A model controlled by a local function.
 
-[`FunctionModel`][pydantic_ai.models.function.FunctionModel] is similar to [`TestModel`][pydantic_ai.models.test.TestModel],
+[`FunctionModel`][pydantic_ai.models.function.FunctionModel] is similar to [`TestModel`](test.md),
 but allows greater control over the model's behavior.
 
 Its primary use case is for more advanced unit testing than is possible with `TestModel`.
 
+Here's a minimal example:
+
+```py {title="function_model_usage.py" call_name="test_my_agent" lint="not-imports"}
+from pydantic_ai import Agent
+from pydantic_ai.messages import Message, ModelResponse
+from pydantic_ai.models.function import FunctionModel, AgentInfo
+
+my_agent = Agent('openai:gpt-4o')
+
+
+async def model_function(messages: list[Message], info: AgentInfo) -> ModelResponse:
+    print(messages)
+    """
+    [
+        UserPrompt(
+            content='Testing my agent...',
+            timestamp=datetime.datetime(...),
+            role='user',
+            message_kind='user-prompt',
+        )
+    ]
+    """
+    print(info)
+    """
+    AgentInfo(
+        function_tools=[], allow_text_result=True, result_tools=[], model_settings=None
+    )
+    """
+    return ModelResponse.from_text('hello world')
+
+
+async def test_my_agent():
+    """Unit test for my_agent, to be run by pytest."""
+    with my_agent.override(model=FunctionModel(model_function)):
+        result = await my_agent.run('Testing my agent...')
+        assert result.data == 'hello world'
+```
+
+See [Unit testing with `FunctionModel`](../../testing-evals.md#unit-testing-with-functionmodel) for detailed documentation.
+
 ::: pydantic_ai.models.function

docs/api/models/gemini.md

@@ -15,6 +15,6 @@ Despite these shortcomings, the Gemini model is actually quite powerful and very
 
 ## Setup
 
-For details on how to set up authentication with this model, see [model configuration for Gemini](../../install.md#gemini).
+For details on how to set up authentication with this model, see [model configuration for Gemini](../../models.md#gemini).
 
 ::: pydantic_ai.models.gemini

docs/api/models/groq.md

@@ -2,6 +2,6 @@
 
 ## Setup
 
-For details on how to set up authentication with this model, see [model configuration for Groq](../../install.md#groq).
+For details on how to set up authentication with this model, see [model configuration for Groq](../../models.md#groq).
 
 ::: pydantic_ai.models.groq

docs/api/models/mistral.md

@@ -1,3 +1,7 @@
 # `pydantic_ai.models.mistral`
 
+## Setup
+
+For details on how to set up authentication with this model, see [model configuration for Mistral](../../models.md#mistral).
+
 ::: pydantic_ai.models.mistral

docs/api/models/ollama.md

@@ -2,7 +2,7 @@
 
 ## Setup
 
-For details on how to set up authentication with this model, see [model configuration for Ollama](../../install.md#ollama).
+For details on how to set up authentication with this model, see [model configuration for Ollama](../../models.md#ollama).
 
 ## Example local usage
 

docs/api/models/openai.md

@@ -2,6 +2,6 @@
 
 ## Setup
 
-For details on how to set up authentication with this model, see [model configuration for OpenAI](../../install.md#openai).
+For details on how to set up authentication with this model, see [model configuration for OpenAI](../../models.md#openai).
 
 ::: pydantic_ai.models.openai

docs/api/models/test.md

@@ -2,4 +2,24 @@
 
 Utility model for quickly testing apps built with PydanticAI.
 
+Here's a minimal example:
+
+```py {title="test_model_usage.py" call_name="test_my_agent" lint="not-imports"}
+from pydantic_ai import Agent
+from pydantic_ai.models.test import TestModel
+
+my_agent = Agent('openai:gpt-4o', system_prompt='...')
+
+
+async def test_my_agent():
+    """Unit test for my_agent, to be run by pytest."""
+    m = TestModel()
+    with my_agent.override(model=m):
+        result = await my_agent.run('Testing my agent...')
+        assert result.data == 'success (no tool calls)'
+    assert m.agent_model_function_tools == []
+```
+
+See [Unit testing with `TestModel`](../../testing-evals.md#unit-testing-with-testmodel) for detailed documentation.
+
 ::: pydantic_ai.models.test

docs/api/models/vertexai.md

@@ -13,7 +13,7 @@ having the same schemas as the equivalent [Gemini endpoints][pydantic_ai.models.
 ## Setup
 
 For details on how to set up authentication with this model as well as a comparison with the `generativelanguage.googleapis.com` API used by [`GeminiModel`][pydantic_ai.models.gemini.GeminiModel],
-see [model configuration for Gemini via VertexAI](../../install.md#gemini-via-vertexai).
+see [model configuration for Gemini via VertexAI](../../models.md#gemini-via-vertexai).
 
 ## Example Usage