codeforge-dev 1.4.0

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/fastapi/references/sse-and-streaming.md

@@ -0,0 +1,318 @@
+# Server-Sent Events and Streaming -- Deep Dive
+
+## 1. SSE Protocol Fundamentals
+
+Server-Sent Events use a persistent HTTP connection with `Content-Type: text/event-stream`. The server writes UTF-8 text frames separated by double newlines. Each frame contains one or more fields:
+
+```
+event: message
+id: 42
+retry: 5000
+data: {"text": "hello"}
+
+```
+
+| Field | Purpose | Default |
+|-------|---------|---------|
+| `data` | Event payload (required) | -- |
+| `event` | Event type name | `"message"` |
+| `id` | Last-event ID for reconnection | none |
+| `retry` | Client reconnection interval (ms) | browser default (~3s) |
+
+Multiple `data` lines in one frame are concatenated with newlines. A line starting with `:` is a comment -- browsers ignore it, but it serves as a keep-alive heartbeat.
+
+---
+
+## 2. sse-starlette API
+
+`sse-starlette` wraps an async iterable into a compliant `EventSourceResponse`. Install with `pip install sse-starlette`.
+
+### Basic Configuration
+
+```python
+from sse_starlette.sse import EventSourceResponse
+
+@app.get("/events")
+async def stream():
+    return EventSourceResponse(
+        content=event_generator(),
+        media_type="text/event-stream",
+        ping=30,           # heartbeat interval in seconds
+        ping_message_factory=lambda: {"comment": "keep-alive"},
+    )
+```
+
+### Yielding Events
+
+The generator can yield several formats:
+
+```python
+async def event_generator():
+    # Dict with SSE fields
+    yield {"event": "status", "data": "connected", "id": "1"}
+
+    # Plain string -- becomes a data-only event
+    yield "simple message"
+
+    # Dict with just data
+    yield {"data": '{"count": 42}'}
+
+    # ServerSentEvent object for full control
+    from sse_starlette.sse import ServerSentEvent
+    yield ServerSentEvent(data="precise", event="custom", id="2", retry=10000)
+```
+
+---
+
+## 3. Reconnection with Last-Event-ID
+
+Browsers automatically reconnect when an SSE connection drops. They send the last received `id` in the `Last-Event-ID` header. Use this to resume the stream without replaying events the client already received:
+
+```python
+from fastapi import Request
+
+async def resumable_stream(request: Request):
+    last_id = request.headers.get("last-event-id")
+    cursor = int(last_id) + 1 if last_id else 0
+
+    async for event in fetch_events_from(cursor):
+        yield {
+            "event": "update",
+            "data": event.to_json(),
+            "id": str(event.sequence_id),
+        }
+```
+
+### Designing for Resumability
+
+- Assign monotonically increasing IDs (database sequence, timestamp, or counter).
+- Store events in a bounded buffer or persistent log so the server can replay from any recent ID.
+- Set `retry` to control how quickly clients reconnect (default is ~3 seconds).
+- Send an initial "snapshot" event on reconnection if the gap is too large to replay individual events.
+
+---
+
+## 4. Backpressure with Bounded Queues
+
+When an event source produces faster than clients consume, unbounded buffering causes memory growth. Use `asyncio.Queue` with a maximum size to apply backpressure:
+
+```python
+import asyncio
+
+class EventBus:
+    def __init__(self):
+        self.subscribers: list[asyncio.Queue] = []
+
+    def subscribe(self, maxsize: int = 100) -> asyncio.Queue:
+        queue = asyncio.Queue(maxsize=maxsize)
+        self.subscribers.append(queue)
+        return queue
+
+    def unsubscribe(self, queue: asyncio.Queue):
+        self.subscribers.remove(queue)
+
+    async def publish(self, event: dict):
+        for queue in self.subscribers:
+            try:
+                queue.put_nowait(event)
+            except asyncio.QueueFull:
+                # Drop oldest event to make room
+                try:
+                    queue.get_nowait()
+                except asyncio.QueueEmpty:
+                    pass
+                queue.put_nowait(event)
+
+bus = EventBus()
+```
+
+```python
+async def subscriber_generator(request: Request):
+    queue = bus.subscribe(maxsize=100)
+    try:
+        while True:
+            if await request.is_disconnected():
+                break
+            try:
+                event = await asyncio.wait_for(queue.get(), timeout=30)
+                yield {"data": json.dumps(event)}
+            except asyncio.TimeoutError:
+                yield {"comment": "keep-alive"}
+    finally:
+        bus.unsubscribe(queue)
+```
+
+The drop-oldest strategy keeps the client close to real-time. Alternative strategies: block the producer (`await queue.put()`), drop the newest event, or disconnect slow clients.
+
+---
+
+## 5. Heartbeats and Keep-Alive
+
+Proxies, load balancers, and CDNs may close idle connections. Send periodic heartbeat comments to keep the connection alive:
+
+```python
+async def heartbeat_generator():
+    event_iter = aiter(fetch_events())
+    while True:
+        try:
+            event = await asyncio.wait_for(anext(event_iter), timeout=15)
+            yield {"data": event.json(), "id": str(event.id)}
+        except asyncio.TimeoutError:
+            yield {"comment": "heartbeat"}
+        except StopAsyncIteration:
+            break
+```
+
+`sse-starlette` provides built-in ping support via the `ping` parameter (interval in seconds). Use the built-in ping for simple cases; implement custom heartbeats when the heartbeat needs to carry data (e.g., server timestamp, queue depth).
+
+---
+
+## 6. Disconnect Detection
+
+Detect client disconnection to stop generating events and release resources:
+
+```python
+from fastapi import Request
+
+async def safe_generator(request: Request):
+    try:
+        async for chunk in data_source():
+            if await request.is_disconnected():
+                break
+            yield {"data": chunk}
+    finally:
+        await cleanup_resources()
+```
+
+`request.is_disconnected()` is an async check -- call it between yields, not inside tight loops. For generators driven by a queue, the `finally` block handles cleanup when the client disconnects and `EventSourceResponse` cancels the generator.
+
+---
+
+## 7. LLM Streaming with Tool Calls
+
+Stream LLM responses that may include interleaved text and tool-use events. Structure events by type so the client can render text incrementally while handling tool calls separately:
+
+```python
+import json
+
+async def stream_with_tools(messages: list[dict]):
+    response = await client.messages.create(
+        model="claude-sonnet-4-20250514",
+        messages=messages,
+        tools=tool_definitions,
+        stream=True,
+    )
+
+    async for event in response:
+        if event.type == "content_block_start":
+            if event.content_block.type == "text":
+                yield {"event": "text_start", "data": ""}
+            elif event.content_block.type == "tool_use":
+                yield {
+                    "event": "tool_start",
+                    "data": json.dumps({
+                        "id": event.content_block.id,
+                        "name": event.content_block.name,
+                    }),
+                }
+        elif event.type == "content_block_delta":
+            if event.delta.type == "text_delta":
+                yield {"event": "text_delta", "data": event.delta.text}
+            elif event.delta.type == "input_json_delta":
+                yield {"event": "tool_delta", "data": event.delta.partial_json}
+        elif event.type == "message_stop":
+            yield {"event": "done", "data": ""}
+```
+
+### Client-Side Handling (JavaScript)
+
+```javascript
+const source = new EventSource("/chat");
+
+source.addEventListener("text_delta", (e) => {
+  appendToOutput(e.data);
+});
+
+source.addEventListener("tool_start", (e) => {
+  const { id, name } = JSON.parse(e.data);
+  startToolIndicator(id, name);
+});
+
+source.addEventListener("done", () => {
+  source.close();
+});
+```
+
+---
+
+## 8. Testing SSE Endpoints
+
+### Unit Testing with httpx
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+@pytest.mark.anyio
+async def test_sse_stream():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        async with client.stream("GET", "/events") as response:
+            assert response.headers["content-type"] == "text/event-stream"
+            events = []
+            async for line in response.aiter_lines():
+                if line.startswith("data:"):
+                    events.append(line[5:].strip())
+                if len(events) >= 3:
+                    break
+            assert len(events) == 3
+```
+
+### Parsing SSE Lines
+
+```python
+def parse_sse_events(raw_lines: list[str]) -> list[dict]:
+    events = []
+    current = {}
+    for line in raw_lines:
+        if line == "":
+            if current:
+                events.append(current)
+                current = {}
+        elif line.startswith("event:"):
+            current["event"] = line[6:].strip()
+        elif line.startswith("data:"):
+            data = line[5:].strip()
+            current["data"] = current.get("data", "") + data
+        elif line.startswith("id:"):
+            current["id"] = line[3:].strip()
+    if current:
+        events.append(current)
+    return events
+```
+
+### Testing Reconnection
+
+```python
+@pytest.mark.anyio
+async def test_sse_reconnection():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        # First connection -- collect some events
+        headers = {}
+        async with client.stream("GET", "/events", headers=headers) as resp:
+            last_id = None
+            async for line in resp.aiter_lines():
+                if line.startswith("id:"):
+                    last_id = line[3:].strip()
+                    break
+
+        # Reconnect with Last-Event-ID
+        headers = {"Last-Event-ID": last_id}
+        async with client.stream("GET", "/events", headers=headers) as resp:
+            async for line in resp.aiter_lines():
+                if line.startswith("data:"):
+                    event = json.loads(line[5:].strip())
+                    assert event["sequence"] > int(last_id)
+                    break
+```

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/pydantic-ai/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: pydantic-ai
+description: >-
+  This skill should be used when the user asks to "build a PydanticAI agent",
+  "create an AI agent with PydanticAI", "add tools to a PydanticAI agent",
+  "stream responses with PydanticAI", "test a PydanticAI agent",
+  "connect PydanticAI to a Svelte frontend", "use RunContext for dependency injection",
+  "configure model fallbacks in PydanticAI", or discusses PydanticAI agents,
+  tool decorators, structured output, agent testing, or VercelAIAdapter.
+version: 0.1.0
+---
+
+# PydanticAI Agent Development
+
+## Mental Model
+
+PydanticAI is a Python agent framework where **the `Agent` class is the single orchestration primitive**. An agent binds a model, a set of tools, and a typed output contract into one object. Tools are plain Python functions decorated onto the agent; the framework generates JSON schemas from their type annotations and docstrings, sends them to the model, and validates the model's tool-call arguments with Pydantic before invoking the function. This means type annotations are the contract -- there is no separate schema definition layer.
+
+Dependency injection flows through `RunContext[DepsT]`. The caller passes a `deps` object at run time; every tool and validator receives it via `RunContext.deps`. This keeps tools pure (no global state, no module-level singletons) and makes testing straightforward -- swap the deps object, swap the behavior.
+
+Streaming and structured output are first-class. An agent can stream raw text deltas, partially-validated Pydantic models, or both. The `VercelAIAdapter` bridges PydanticAI's streaming protocol to the Vercel AI Data Stream Protocol, enabling direct consumption by `@ai-sdk/svelte` on the frontend without a custom SSE layer.
+
+Assume `pydantic-ai>=0.1` with Pydantic v2 for all new code.
+
+---
+
+## Agent Definition
+
+The `Agent` class is generic over dependencies and output type: `Agent[DepsT, OutputT]`. The constructor wires together model, tools, output contract, and defaults:
+
+```python
+from pydantic_ai import Agent
+from pydantic import BaseModel
+
+class CityInfo(BaseModel):
+    name: str
+    country: str
+    population: int
+
+agent = Agent(
+    "anthropic:claude-sonnet-4-20250514",
+    output_type=CityInfo,
+    instructions="Extract structured city information from user queries.",
+    deps_type=type(None),
+    retries=2,
+    end_strategy="early",
+)
+```
+
+Key constructor parameters:
+
+- **`model`**: String identifier like `"openai:gpt-5"` or `"anthropic:claude-sonnet-4-20250514"`, or a `Model` instance. Overridable per-run.
+- **`output_type`**: Defaults to `str`. Accepts a Pydantic `BaseModel`, dataclass, `TypedDict`, list of types (union), `ToolOutput`, `NativeOutput`, or `PromptedOutput`.
+- **`instructions`**: Static string or dynamic callable returning a string. Re-evaluated each run. Not included when `message_history` is provided.
+- **`system_prompt`**: Static string(s) included in every request, preserved in conversation history.
+- **`deps_type`**: The type of the dependency object passed at run time.
+- **`retries`**: Default retry count for tools when the model sends invalid arguments (default 1).
+- **`end_strategy`**: `"early"` stops on first valid output; `"exhaustive"` runs all pending tool calls first.
+
+### Running an Agent
+
+```python
+# Async (preferred)
+result = await agent.run("Tell me about Paris", deps=my_deps)
+print(result.output)        # CityInfo(name='Paris', country='France', population=2161000)
+print(result.usage())       # RunUsage(requests=1, input_tokens=..., output_tokens=...)
+
+# Sync convenience
+result = agent.run_sync("Tell me about Paris")
+
+# With overrides
+result = await agent.run(
+    "Tell me about Paris",
+    model="openai:gpt-5",
+    model_settings={"temperature": 0.0},
+    usage_limits=UsageLimits(request_limit=5),
+)
+```
+
+The `AgentRunResult` exposes `.output` (typed), `.usage()`, `.all_messages()`, and `.new_messages()` for conversation continuation.
+
+---
+
+## Tools
+
+Tools give the agent the ability to take actions and retrieve information. There are two decorator forms based on whether the tool needs access to dependencies:
+
+### Context-Aware Tools
+
+```python
+from pydantic_ai import Agent, RunContext
+
+agent = Agent("openai:gpt-5", deps_type=DatabasePool)
+
+@agent.tool(retries=3)
+async def lookup_user(ctx: RunContext[DatabasePool], user_id: int) -> str:
+    """Find a user by their ID. Returns the user's name and email."""
+    row = await ctx.deps.fetchrow("SELECT name, email FROM users WHERE id = $1", user_id)
+    if not row:
+        raise ModelRetry("No user found with that ID, try a different one")
+    return f"{row['name']} ({row['email']})"
+```
+
+The first parameter **must** be `RunContext[DepsT]`. All subsequent parameters become the tool's JSON schema. The docstring becomes the tool description sent to the model.
+
+### Plain Tools
+
+```python
+@agent.tool_plain
+def roll_dice(sides: int = 6) -> str:
+    """Roll a die with the specified number of sides."""
+    return str(random.randint(1, sides))
+```
+
+No `RunContext` parameter. Use for stateless utilities that need no dependencies.
+
+### Tool Decorator Options
+
+Both `@agent.tool` and `@agent.tool_plain` accept:
+
+- **`retries`**: Override the agent-level retry count for this tool.
+- **`prepare`**: A `ToolsPrepareFunc` to dynamically include/exclude the tool or modify its schema per run.
+- **`name`** / **`description`**: Override the function name or docstring.
+
+### Error Handling with ModelRetry
+
+```python
+from pydantic_ai import ModelRetry
+
+@agent.tool
+async def search(ctx: RunContext[SearchClient], query: str) -> str:
+    """Search the knowledge base."""
+    results = await ctx.deps.search(query)
+    if not results:
+        raise ModelRetry("No results found. Try broader or different search terms.")
+    return "\n".join(r.summary for r in results[:5])
+```
+
+Raising `ModelRetry(message)` sends the error back to the model as a tool-call error, letting it self-correct its arguments.
+
+> **Deep dive:** See `references/agents-and-tools.md` for tool registration via constructor, `prepare` functions for dynamic tool filtering, result types and validators, and advanced output type patterns (unions, `ToolOutput`, `NativeOutput`).
+
+---
+
+## Dependency Injection with RunContext
+
+The dependency system is explicit: define a deps type, pass it at run time, access it in tools and validators through `RunContext.deps`:
+
+```python
+from dataclasses import dataclass
+from pydantic_ai import Agent, RunContext
+
+@dataclass
+class AppDeps:
+    db: DatabasePool
+    cache: RedisClient
+    api_key: str
+
+agent = Agent("anthropic:claude-sonnet-4-20250514", deps_type=AppDeps)
+
+@agent.tool
+async def fetch_order(ctx: RunContext[AppDeps], order_id: str) -> str:
+    """Retrieve order details by ID."""
+    cached = await ctx.deps.cache.get(f"order:{order_id}")
+    if cached:
+        return cached
+    row = await ctx.deps.db.fetchrow("SELECT * FROM orders WHERE id = $1", order_id)
+    return json.dumps(dict(row))
+
+# At call site
+deps = AppDeps(db=pool, cache=redis, api_key=os.environ["API_KEY"])
+result = await agent.run("What's the status of order ORD-123?", deps=deps)
+```
+
+Dependencies can be any object -- a dataclass, a named tuple, a plain class, or even a single value. The `deps_type` annotation enables type checking throughout the tool chain.
+
+---
+
+## Model Configuration
+
+### Model Selection
+
+```python
+# By string identifier (most common)
+agent = Agent("anthropic:claude-sonnet-4-20250514")
+agent = Agent("openai:gpt-5")
+agent = Agent("google-gla:gemini-2.0-flash")
+
+# Override at run time
+result = await agent.run("prompt", model="openai:gpt-5")
+```
+
+### FallbackModel
+
+Sequence multiple models; the framework switches to the next on API errors:
+
+```python
+from pydantic_ai.models.fallback import FallbackModel
+
+fallback = FallbackModel("anthropic:claude-sonnet-4-20250514", "openai:gpt-5")
+agent = Agent(fallback)
+```
+
+On failure of all models, raises `FallbackExceptionGroup`. By default only `ModelHTTPError` triggers fallback; validation errors use the retry mechanism instead.
+
+### ModelSettings
+
+Control generation parameters per-agent or per-run:
+
+```python
+from pydantic_ai import ModelSettings
+
+agent = Agent(
+    "openai:gpt-5",
+    model_settings=ModelSettings(temperature=0.0, max_tokens=1000),
+)
+
+# Override per-run
+result = await agent.run("prompt", model_settings={"temperature": 0.7})
+```
+
+Available settings: `temperature`, `max_tokens`, `top_p`, `timeout`, `seed`, `parallel_tool_calls`, `presence_penalty`, `frequency_penalty`, `stop_sequences`.
+
+> **Deep dive:** See `references/models-and-streaming.md` for streaming patterns (text, structured, deltas), `VercelAIAdapter` for Svelte integration, `TestModel` and `FunctionModel` for testing, and usage tracking with `UsageLimits`.
+
+---
+
+## Streaming
+
+### Text Streaming
+
+```python
+async with agent.run_stream("Tell me a story") as result:
+    async for delta in result.stream_text(delta=True):
+        print(delta, end="", flush=True)
+```
+
+`stream_text()` yields cumulative text by default. Pass `delta=True` for incremental chunks. The `debounce_by` parameter (default `0.1s`) batches rapid chunks to reduce overhead.
+
+### Structured Output Streaming
+
+```python
+agent = Agent("openai:gpt-5", output_type=Story)
+
+async with agent.run_stream("Write a story") as result:
+    async for partial in result.stream_output(debounce_by=0.1):
+        print(partial)  # Partially-validated Story objects
+```
+
+Each yielded object is a `Story` instance with whatever fields have been parsed so far. Validators with side effects should check `ctx.partial_output` to avoid running during intermediate validations.
+
+---
+
+## Testing
+
+PydanticAI provides two test models that avoid real API calls:
+
+### TestModel
+
+Calls all registered tools and generates data matching output schemas procedurally:
+
+```python
+from pydantic_ai.models.test import TestModel
+
+with agent.override(model=TestModel()):
+    result = agent.run_sync("test prompt")
+    assert isinstance(result.output, CityInfo)
+```
+
+### FunctionModel
+
+Full control over model responses via a callback:
+
+```python
+from pydantic_ai.models.function import FunctionModel, AgentInfo
+from pydantic_ai.messages import ModelResponse, TextPart
+
+def mock_model(messages, info: AgentInfo) -> ModelResponse:
+    return ModelResponse(parts=[TextPart("mocked response")])
+
+with agent.override(model=FunctionModel(mock_model)):
+    result = agent.run_sync("test")
+    assert result.output == "mocked response"
+```
+
+### Safety Guard
+
+Prevent accidental real API calls in test suites:
+
+```python
+from pydantic_ai import models
+models.ALLOW_MODEL_REQUESTS = False  # Raises error if a non-test model is used
+```
+
+---
+
+## VercelAIAdapter (Svelte Integration)
+
+Bridge a PydanticAI agent to a Vercel AI SDK frontend with a single endpoint:
+
+```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)
+```
+
+On the Svelte side, consume with `@ai-sdk/svelte`:
+
+```svelte
+<script>
+  import { useChat } from '@ai-sdk/svelte';
+  const { messages, input, handleSubmit } = useChat({ api: '/chat' });
+</script>
+```
+
+`VercelAIAdapter` translates PydanticAI's event format to the Vercel AI Data Stream Protocol automatically -- no custom SSE parsing needed.
+
+---
+
+## Ambiguity Policy
+
+These defaults apply when the user does not specify a preference. State the assumption when making a choice so the user can override:
+
+- **Model selection:** Default to `"anthropic:claude-sonnet-4-20250514"` for agents requiring tool use. Use `"openai:gpt-5"` only when the user specifies OpenAI.
+- **Output type:** Default to `str` for conversational agents. Use a Pydantic model when the caller needs structured data.
+- **Dependency injection:** Default to a dataclass for `deps_type` when multiple resources are needed. Use a single value when only one resource is injected.
+- **Streaming:** Default to `run_stream()` when output is displayed to a user. Use `run()` for background/batch processing.
+- **Testing:** Default to `TestModel` for unit tests. Use `FunctionModel` when specific response sequences are needed.
+- **Frontend bridge:** Default to `VercelAIAdapter` when the frontend uses `@ai-sdk/svelte` or any Vercel AI SDK client.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/agents-and-tools.md` | Agent constructor details, tool registration via constructor, `prepare` functions for dynamic tool sets, result types and validators, output type patterns (unions, ToolOutput, NativeOutput, PromptedOutput), ModelRetry mechanics |
+| `references/models-and-streaming.md` | Model configuration, FallbackModel, streaming (text, structured, deltas), StreamedRunResult API, VercelAIAdapter integration, TestModel and FunctionModel for testing, usage tracking with UsageLimits, capture_run_messages |