codeforge-dev 1.4.0

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/pydantic-ai/references/agents-and-tools.md

@@ -0,0 +1,271 @@
+# Agents and Tools -- Deep Dive
+
+## 1. Agent Constructor Details
+
+The `Agent` class is generic: `Agent[AgentDepsT, OutputDataT]`. The full constructor accepts:
+
+```python
+from pydantic_ai import Agent, Tool
+
+agent = Agent(
+    model="anthropic:claude-sonnet-4-20250514",  # or Model instance, or None
+    output_type=str,                    # BaseModel, dataclass, TypedDict, list, ToolOutput, etc.
+    instructions="Be concise.",         # static str or Callable[[RunContext], str]
+    system_prompt="Always respond in JSON.",  # static, preserved in history
+    deps_type=type(None),               # type of the deps object
+    name="my-agent",                    # optional display name
+    model_settings={"temperature": 0},  # default ModelSettings
+    retries=1,                          # default tool retry count
+    end_strategy="early",              # "early" or "exhaustive"
+    tools=[my_func, Tool(other_func, takes_ctx=False)],
+    tool_timeout=30.0,                  # global tool execution timeout in seconds
+)
+```
+
+### Dynamic Instructions
+
+Instructions can be a callable that receives `RunContext` and returns a string. This enables per-run customization based on dependencies:
+
+```python
+agent = Agent(
+    "openai:gpt-5",
+    deps_type=UserContext,
+    instructions=lambda ctx: f"The current user is {ctx.deps.username}. Respond in {ctx.deps.language}.",
+)
+```
+
+The `@agent.instructions` decorator is equivalent:
+
+```python
+@agent.instructions
+def build_instructions(ctx: RunContext[UserContext]) -> str:
+    return f"The current user is {ctx.deps.username}."
+```
+
+Instructions differ from `system_prompt` in one critical way: instructions are re-evaluated per run and excluded when `message_history` is provided. System prompts are static and always included.
+
+---
+
+## 2. Tool Registration via Constructor
+
+Tools can be registered via decorators or passed directly to the constructor. Constructor registration is useful when tools are defined in separate modules:
+
+```python
+from pydantic_ai import Agent, Tool
+
+async def search_docs(ctx: RunContext[Deps], query: str) -> str:
+    """Search the documentation."""
+    return await ctx.deps.search(query)
+
+def get_time() -> str:
+    """Get the current UTC time."""
+    return datetime.utcnow().isoformat()
+
+agent = Agent(
+    "openai:gpt-5",
+    deps_type=Deps,
+    tools=[
+        search_docs,                          # auto-detects RunContext
+        Tool(get_time, takes_ctx=False),       # explicit: no context
+        Tool(search_docs, name="doc_search"),  # custom name
+    ],
+)
+```
+
+The `Tool` wrapper accepts:
+- **`takes_ctx`**: Explicitly declare whether the function expects `RunContext` as its first parameter.
+- **`name`** / **`description`**: Override the function name or docstring.
+- **`retries`**: Override the agent-level retry count.
+- **`prepare`**: Dynamic preparation function.
+
+---
+
+## 3. Prepare Functions for Dynamic Tool Sets
+
+A `prepare` function runs before each model request, allowing tools to be included, excluded, or modified based on the current run state:
+
+```python
+from pydantic_ai import Agent, RunContext
+from pydantic_ai.tools import ToolDefinition
+
+async def filter_admin_tools(
+    ctx: RunContext[UserDeps], tool_def: ToolDefinition
+) -> ToolDefinition | None:
+    """Only include this tool if the user has admin role."""
+    if ctx.deps.user_role != "admin":
+        return None  # exclude tool from this run
+    return tool_def  # include unmodified
+
+@agent.tool(prepare=filter_admin_tools)
+async def delete_user(ctx: RunContext[UserDeps], user_id: int) -> str:
+    """Delete a user account permanently."""
+    await ctx.deps.db.execute("DELETE FROM users WHERE id = $1", user_id)
+    return f"Deleted user {user_id}"
+```
+
+Returning `None` removes the tool. Returning a modified `ToolDefinition` changes the schema or description sent to the model. The agent-level `prepare_tools` parameter applies a prepare function to all tools.
+
+---
+
+## 4. Result Types and Validators
+
+### Output Type Patterns
+
+**Single Pydantic model** -- the most common pattern:
+
+```python
+class WeatherReport(BaseModel):
+    city: str
+    temperature_c: float
+    conditions: str
+
+agent = Agent("openai:gpt-5", output_type=WeatherReport)
+```
+
+**Union of types** -- the model chooses which type to return:
+
+```python
+agent = Agent("openai:gpt-5", output_type=[WeatherReport, ErrorReport])
+```
+
+Each type becomes a separate tool the model can call. The first successful tool call ends the run (with `end_strategy="early"`).
+
+**Named tool outputs** -- control the tool names:
+
+```python
+from pydantic_ai import ToolOutput
+
+agent = Agent(
+    "openai:gpt-5",
+    output_type=[
+        ToolOutput(WeatherReport, name="return_weather", description="Return weather data"),
+        ToolOutput(ErrorReport, name="return_error", description="Report an error"),
+    ],
+)
+```
+
+**NativeOutput** -- use the model's built-in structured output (JSON mode):
+
+```python
+from pydantic_ai import NativeOutput
+
+agent = Agent("openai:gpt-5", output_type=NativeOutput(WeatherReport))
+```
+
+Not all models support native structured output. Falls back to tool-based output automatically.
+
+**PromptedOutput** -- inject the schema into the prompt instead of using tools:
+
+```python
+from pydantic_ai import PromptedOutput
+
+agent = Agent(
+    "openai:gpt-5",
+    output_type=PromptedOutput(WeatherReport, template="Respond with JSON matching: {schema}"),
+)
+```
+
+**TextOutput** -- process plain text through a function:
+
+```python
+from pydantic_ai import TextOutput
+
+def parse_csv(text: str) -> list[str]:
+    return [line.strip() for line in text.split(",")]
+
+agent = Agent("openai:gpt-5", output_type=TextOutput(parse_csv))
+```
+
+**Output functions** -- the model calls a function to produce the result:
+
+```python
+def save_report(title: str, content: str, priority: int) -> str:
+    """Save a report to the database."""
+    db.save(Report(title=title, content=content, priority=priority))
+    return f"Saved: {title}"
+
+agent = Agent("openai:gpt-5", output_type=[save_report])
+```
+
+### Result Validators
+
+Validators run after the model produces output. They can transform the output or reject it:
+
+```python
+@agent.output_validator
+async def validate_weather(ctx: RunContext[Deps], output: WeatherReport) -> WeatherReport:
+    if output.temperature_c < -90 or output.temperature_c > 60:
+        raise ModelRetry("Temperature is outside realistic range. Check the data.")
+    return output
+```
+
+Raising `ModelRetry` sends the error message back to the model for self-correction. The validator reruns up to `output_retries` times (defaults to `retries`).
+
+During streaming, `ctx.partial_output` is `True` for intermediate validations. Skip side effects when partial:
+
+```python
+@agent.output_validator
+async def validate_with_side_effect(ctx: RunContext[Deps], output: Report) -> Report:
+    if not ctx.partial_output:
+        await ctx.deps.audit_log.record(output)
+    return output
+```
+
+---
+
+## 5. AgentRunResult
+
+The return value of `agent.run()` and `agent.run_sync()`:
+
+```python
+result = await agent.run("prompt", deps=deps)
+
+result.output          # typed OutputDataT
+result.usage()         # RunUsage(requests=N, input_tokens=..., output_tokens=...)
+result.all_messages()  # full conversation history including system prompts
+result.new_messages()  # only messages from this run (for conversation continuation)
+result.run_id          # unique identifier for this run
+```
+
+### Conversation Continuation
+
+Pass `message_history` to continue a previous conversation:
+
+```python
+result1 = await agent.run("What's the weather in Paris?", deps=deps)
+result2 = await agent.run(
+    "What about London?",
+    deps=deps,
+    message_history=result1.all_messages(),
+)
+```
+
+When `message_history` is provided, `instructions` are not included (they were already in the history). `system_prompt` is always included.
+
+---
+
+## 6. ModelRetry Mechanics
+
+When a tool raises `ModelRetry(message)`:
+
+1. The framework sends the error message back to the model as a tool-call error response.
+2. The model generates a new tool call (presumably with corrected arguments).
+3. The tool runs again with the new arguments.
+4. This repeats up to `retries` times (per-tool or per-agent setting).
+5. If retries are exhausted, the underlying `ValidationError` or `ModelRetry` propagates as an exception.
+
+```python
+from pydantic_ai import ModelRetry
+
+@agent.tool(retries=3)
+async def query_api(ctx: RunContext[Deps], endpoint: str, params: dict) -> str:
+    """Query the external API."""
+    if not endpoint.startswith("/api/"):
+        raise ModelRetry("Endpoint must start with /api/. Available: /api/users, /api/orders")
+    response = await ctx.deps.http.get(endpoint, params=params)
+    if response.status_code == 404:
+        raise ModelRetry(f"Endpoint {endpoint} returned 404. Try a different endpoint.")
+    return response.text
+```
+
+`ModelRetry` is distinct from Python exceptions -- it signals a recoverable error that the model can fix by adjusting its tool-call arguments.

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/pydantic-ai/references/models-and-streaming.md

@@ -0,0 +1,422 @@
+# Models and Streaming -- Deep Dive
+
+## 1. Model Configuration
+
+### Model Identifiers
+
+PydanticAI uses string identifiers in the format `provider:model-name`:
+
+```python
+from pydantic_ai import Agent
+
+# Anthropic
+agent = Agent("anthropic:claude-sonnet-4-20250514")
+
+# OpenAI
+agent = Agent("openai:gpt-5")
+
+# Google Gemini
+agent = Agent("google-gla:gemini-2.0-flash")
+
+# Groq
+agent = Agent("groq:llama-3.3-70b-versatile")
+
+# OpenAI-compatible endpoints (Ollama, vLLM, etc.)
+from pydantic_ai.models.openai import OpenAIChatModel
+model = OpenAIChatModel("llama3", base_url="http://localhost:11434/v1")
+agent = Agent(model)
+```
+
+Override the model at run time without changing the agent definition:
+
+```python
+result = await agent.run("prompt", model="openai:gpt-5")
+```
+
+### ModelSettings
+
+`ModelSettings` is a `TypedDict` controlling generation parameters. All fields are optional:
+
+```python
+from pydantic_ai import Agent, ModelSettings
+
+agent = Agent(
+    "openai:gpt-5",
+    model_settings=ModelSettings(
+        temperature=0.0,
+        max_tokens=2000,
+        top_p=0.95,
+        seed=42,
+        timeout=30.0,
+        parallel_tool_calls=True,
+    ),
+)
+```
+
+Precedence (lowest to highest):
+1. Model defaults
+2. `Agent(model_settings=...)` -- agent-level
+3. `agent.run(model_settings=...)` -- per-run
+
+Available fields: `temperature`, `max_tokens`, `top_p`, `timeout`, `seed`, `parallel_tool_calls`, `presence_penalty`, `frequency_penalty`, `logit_bias`, `stop_sequences`, `extra_headers`, `extra_body`.
+
+---
+
+## 2. FallbackModel
+
+Sequence multiple models for resilience. The framework tries each model in order and switches on API errors:
+
+```python
+from pydantic_ai.models.fallback import FallbackModel
+
+fallback = FallbackModel(
+    "anthropic:claude-sonnet-4-20250514",
+    "openai:gpt-5",
+    "google-gla:gemini-2.0-flash",
+)
+agent = Agent(fallback)
+```
+
+Behavior:
+- Only `ModelHTTPError` and `ModelAPIError` trigger fallback by default.
+- Validation errors (bad tool arguments, output schema mismatch) use the retry mechanism, not fallback.
+- If all models fail, raises `FallbackExceptionGroup` containing all individual exceptions.
+- Custom trigger: pass `fallback_on` to specify which exception types trigger fallback.
+
+```python
+from pydantic_ai.exceptions import ModelHTTPError
+
+fallback = FallbackModel(
+    "anthropic:claude-sonnet-4-20250514",
+    "openai:gpt-5",
+    fallback_on=(ModelHTTPError, TimeoutError),
+)
+```
+
+---
+
+## 3. Streaming
+
+### Text Streaming
+
+```python
+async with agent.run_stream("Tell me a story") as result:
+    # Cumulative text (each iteration includes all previous text)
+    async for text in result.stream_text():
+        print(text)
+
+    # Delta mode (each iteration is only the new chunk)
+    async for delta in result.stream_text(delta=True):
+        print(delta, end="", flush=True)
+```
+
+### Structured Output Streaming
+
+When the agent has a Pydantic output type, stream partially-validated objects:
+
+```python
+from pydantic import BaseModel
+
+class Story(BaseModel):
+    title: str
+    chapters: list[str]
+
+agent = Agent("openai:gpt-5", output_type=Story)
+
+async with agent.run_stream("Write a story") as result:
+    async for partial_story in result.stream_output(debounce_by=0.1):
+        # partial_story is a Story instance with whatever fields have been parsed
+        print(partial_story.title if hasattr(partial_story, 'title') else "...")
+```
+
+The `debounce_by` parameter (default `0.1` seconds) batches rapid chunks to reduce Pydantic validation overhead. Set to `None` for maximum responsiveness.
+
+### Sync Streaming
+
+```python
+with agent.run_stream_sync("Tell me a story") as result:
+    for delta in result.stream_text(delta=True):
+        print(delta, end="", flush=True)
+```
+
+### StreamedRunResult API
+
+```python
+class StreamedRunResult:
+    # Streaming iterators
+    async def stream_text(delta: bool = False, debounce_by: float | None = 0.1) -> AsyncIterator[str]
+    async def stream_output(debounce_by: float | None = 0.1) -> AsyncIterator[OutputDataT]
+    async def get_output() -> OutputDataT          # consume stream, return final result
+
+    # State
+    is_complete: bool
+
+    # Messages and usage
+    def all_messages() -> list[ModelMessage]
+    def new_messages() -> list[ModelMessage]
+    def usage() -> RunUsage
+```
+
+---
+
+## 4. VercelAIAdapter
+
+`VercelAIAdapter` bridges PydanticAI agents to Vercel AI SDK frontends. It translates PydanticAI's streaming events into the Vercel AI Data Stream Protocol.
+
+### FastAPI Integration
+
+```python
+from fastapi import FastAPI, Request, Response
+from pydantic_ai import Agent
+from pydantic_ai.ui.vercel_ai import VercelAIAdapter
+
+app = FastAPI()
+agent = Agent("anthropic:claude-sonnet-4-20250514", instructions="Be helpful.")
+
+@app.post("/chat")
+async def chat(request: Request) -> Response:
+    return await VercelAIAdapter.dispatch_request(request, agent=agent)
+```
+
+`dispatch_request` handles the full lifecycle:
+1. Parses the Vercel AI SDK request body (messages, model settings).
+2. Converts frontend messages to PydanticAI's `ModelMessage` format.
+3. Runs the agent in streaming mode.
+4. Encodes PydanticAI events as Vercel AI Data Stream Protocol SSE.
+5. Returns a `StreamingResponse`.
+
+### With Dependencies
+
+```python
+@app.post("/chat")
+async def chat(request: Request, db: DB) -> Response:
+    return await VercelAIAdapter.dispatch_request(
+        request,
+        agent=agent,
+        deps=AppDeps(db=db),
+    )
+```
+
+### Manual Usage (Non-Starlette)
+
+```python
+adapter = VercelAIAdapter(agent=agent, run_input=request_data, accept="text/event-stream")
+event_stream = adapter.run_stream()          # AsyncIterator[VercelAIEvent]
+sse_stream = adapter.encode_stream(event_stream)  # AsyncIterator[str] (SSE-formatted)
+```
+
+### Message Conversion
+
+Convert between PydanticAI and Vercel AI message formats:
+
+```python
+# Frontend messages -> PydanticAI messages
+pydantic_messages = VercelAIAdapter.load_messages(ui_messages)
+
+# PydanticAI messages -> frontend messages
+ui_messages = VercelAIAdapter.dump_messages(pydantic_messages)
+```
+
+### Svelte Frontend
+
+```svelte
+<script>
+  import { useChat } from '@ai-sdk/svelte';
+  const { messages, input, handleSubmit, isLoading } = useChat({ api: '/chat' });
+</script>
+
+<div>
+  {#each $messages as message}
+    <p><strong>{message.role}:</strong> {message.content}</p>
+  {/each}
+</div>
+
+<form onsubmit={handleSubmit}>
+  <input bind:value={$input} placeholder="Type a message..." />
+  <button type="submit" disabled={$isLoading}>Send</button>
+</form>
+```
+
+The `useChat` hook manages conversation state, streaming, and message history automatically. The protocol translation is fully handled by `VercelAIAdapter` on the backend.
+
+---
+
+## 5. TestModel
+
+`TestModel` is a procedural model that calls all registered tools and generates data matching output schemas without making real API calls:
+
+```python
+from pydantic_ai.models.test import TestModel
+
+with agent.override(model=TestModel()):
+    result = agent.run_sync("test prompt")
+    assert isinstance(result.output, CityInfo)
+```
+
+`TestModel` behavior:
+- Calls each registered tool once with generated arguments matching the tool's parameter schema.
+- If the agent has a structured `output_type`, generates a response matching the output schema.
+- If the output type is `str`, returns `"Final response"` (or a custom string).
+
+Custom text output:
+
+```python
+with agent.override(model=TestModel(custom_output_text="Paris is beautiful")):
+    result = agent.run_sync("Tell me about Paris")
+    assert result.output == "Paris is beautiful"
+```
+
+### Override for Dependency Swapping
+
+`agent.override()` replaces both model and dependencies:
+
+```python
+mock_deps = AppDeps(db=FakeDB(), cache=FakeCache(), api_key="test")
+
+with agent.override(model=TestModel(), deps=mock_deps):
+    result = agent.run_sync("test")
+```
+
+---
+
+## 6. FunctionModel
+
+Full control over model responses via a callback function:
+
+```python
+from pydantic_ai.models.function import FunctionModel, AgentInfo
+from pydantic_ai.messages import ModelResponse, TextPart, ToolCallPart
+
+def my_model(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+    # info.function_tools lists available tools with their schemas
+    if info.function_tools:
+        tool = info.function_tools[0]
+        return ModelResponse(parts=[
+            ToolCallPart(tool_name=tool.name, args={"query": "test"})
+        ])
+    return ModelResponse(parts=[TextPart("mock response")])
+
+with agent.override(model=FunctionModel(my_model)):
+    result = await agent.run("test")
+```
+
+The callback receives:
+- **`messages`**: The full conversation history as `list[ModelMessage]`.
+- **`info`**: An `AgentInfo` object with `function_tools` (list of tool definitions), `output_tools` (output schema tools), `model_settings`, and `allow_text_output`.
+
+### Async FunctionModel
+
+```python
+async def async_model(messages, info: AgentInfo) -> ModelResponse:
+    await asyncio.sleep(0.1)  # simulate latency
+    return ModelResponse(parts=[TextPart("async mock")])
+
+with agent.override(model=FunctionModel(async_model)):
+    result = await agent.run("test")
+```
+
+### Streaming FunctionModel
+
+Return a `StreamedResponse` for streaming tests:
+
+```python
+from pydantic_ai.models.function import FunctionModel, StreamedResponse
+
+def streaming_model(messages, info):
+    return StreamedResponse(
+        model_name="test-model",
+        timestamp=datetime.now(),
+    )
+```
+
+---
+
+## 7. Usage Tracking
+
+### RunUsage
+
+Every run returns usage statistics:
+
+```python
+result = await agent.run("prompt")
+usage = result.usage()
+
+print(usage.requests)       # number of API round-trips
+print(usage.input_tokens)   # total input tokens across all requests
+print(usage.output_tokens)  # total output tokens
+print(usage.total_tokens)   # input + output
+print(usage.tool_calls)     # number of tool executions
+```
+
+### UsageLimits
+
+Enforce hard limits on resource consumption:
+
+```python
+from pydantic_ai import UsageLimits
+
+result = await agent.run(
+    "prompt",
+    usage_limits=UsageLimits(
+        request_limit=10,           # max API requests (default 50)
+        input_tokens_limit=10000,
+        output_tokens_limit=5000,
+        total_tokens_limit=15000,
+        tool_calls_limit=20,
+    ),
+)
+```
+
+Exceeding any limit raises `UsageLimitExceeded`. The default `request_limit` is 50 -- this prevents infinite tool-call loops.
+
+### Aggregating Usage Across Runs
+
+```python
+total_usage = RunUsage()
+
+for prompt in prompts:
+    result = await agent.run(prompt)
+    total_usage += result.usage()
+
+print(f"Total tokens: {total_usage.total_tokens}")
+print(f"Total requests: {total_usage.requests}")
+```
+
+---
+
+## 8. Capturing Messages for Assertions
+
+Use `capture_run_messages` to inspect the full message exchange in tests:
+
+```python
+from pydantic_ai import capture_run_messages
+
+with capture_run_messages() as messages:
+    result = await agent.run("What's the weather?", deps=deps)
+
+# messages is a list of ModelMessage objects
+assert any("weather" in str(m) for m in messages)
+```
+
+This captures all messages exchanged during the run, including system prompts, user messages, tool calls, tool responses, and the final output. Useful for verifying that the agent called the expected tools with the expected arguments.
+
+---
+
+## 9. Preventing Accidental Real Requests
+
+In test suites, set the global guard at the module or conftest level:
+
+```python
+# conftest.py
+import pydantic_ai.models
+pydantic_ai.models.ALLOW_MODEL_REQUESTS = False
+```
+
+Any attempt to use a real model (not `TestModel` or `FunctionModel`) raises an error immediately. Use `agent.override()` to swap in test models:
+
+```python
+def test_agent_behavior():
+    with agent.override(model=TestModel()):
+        result = agent.run_sync("test")
+        assert result.output is not None
+```