feat: publish as mkdocs

Author: WojtAcht

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install mkdocs-material pymdown-extensions
+      - run: mkdocs build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -45,3 +45,4 @@ build/
 .ruff_cache
 ocr_parsing/files/results
 ocr_parsing/files/temp_files
+site/

docs/examples/basic-sentiment.md

@@ -0,0 +1,61 @@
+---
+title: Basic Sentiment
+---
+
+# Basic Sentiment Classification
+
+Simple sentiment analysis using PydanticAI with fixed classification classes.
+
+## Overview
+
+This example demonstrates:
+
+- Fixed `Literal` types for classification (`positive`, `negative`, `neutral`)
+- Structured output with Pydantic models
+- Field validation and descriptions
+- Basic accuracy evaluation
+
+## Structure
+
+```python
+class SentimentResult(BaseModel):
+    sentiment: Literal["positive", "negative", "neutral"]
+    reasoning: str
+```
+
+The agent is constrained to return exactly one of the three predefined sentiment classes.
+
+## Running
+
+```bash
+cd basic_sentiment
+uv run sentiment_classifier.py
+```
+
+## Output
+
+```
+Sentiment Analysis with PydanticAI
+======================================================================
+
+Review 1/10:
+Text: This product is absolutely amazing! Best purchase ever!
+
+Classification:
+  Sentiment: positive
+  Reasoning: Strong enthusiastic language indicates positive sentiment
+  Expected: positive
+  Status: Correct
+```
+
+## Key Concepts
+
+!!! info "Fixed Classes"
+    Classes are defined at design time in the `Literal` type. Pydantic ensures only valid sentiments are returned — the model **cannot** produce a value outside the allowed set.
+
+- **Type Safety** — Results are validated Pydantic models
+- **Structured Output** — The agent returns a `SentimentResult`, not raw text
+- **Evaluation** — Compare predictions against expected labels for accuracy measurement
+
+!!! tip "Next Step"
+    Want categories that change at runtime? See [Dynamic Classification](dynamic-classification.md).

docs/examples/bielik.md

@@ -0,0 +1,212 @@
+---
+title: Bielik (Local Models)
+---
+
+# Bielik Examples with PydanticAI
+
+An educational guide to using **Bielik**, a Polish language LLM model, with the PydanticAI framework. These examples show how to build AI agents with local language models served via Ollama.
+
+## What is Bielik?
+
+[Bielik](https://bielik.ai/) is a Polish language LLM, fine-tuned specifically for Polish language understanding and generation. It excels at:
+
+- Polish language comprehension and generation
+- Following instructions in Polish
+- Maintaining context in conversations
+- Tool calling (in supported versions)
+
+You can find the model on [Hugging Face](https://huggingface.co/speakleash/Bielik-11B-v3.0-Instruct) and learn more on the [official Bielik website](https://bielik.ai/).
+
+Running Bielik locally via Ollama gives you a private, cost-free alternative to cloud-based LLMs, with full control over your data.
+
+## Prerequisites
+
+### 1. Install Ollama
+
+Download and install from [ollama.com](https://ollama.com). Mac users can use Homebrew:
+
+```bash
+brew install ollama
+```
+
+### 2. Pull the Bielik Model
+
+```bash
+ollama pull SpeakLeash/bielik-11b-v3.0-instruct:Q8_0
+```
+
+!!! tip "Try Different Models"
+    You can try different versions of the model — just remember to update the name in the `Modelfile` as well. Browse available models at [ollama.com/search](https://ollama.com/search).
+
+### 3. Create a custom version with the provided Modelfile
+
+```bash
+ollama create bielik_v3_q8_tools -f Modelfile
+```
+
+### 4. Serve and run the model
+
+```bash
+# Start the Ollama server
+ollama serve
+
+# In another terminal — make model available
+ollama run bielik_v3_q8_tools
+
+# Leave the prompt input by writing /bye
+
+# Verify the model is being served
+ollama ps
+```
+
+This starts an OpenAI-compatible API server on `http://localhost:11434/v1`.
+
+### 5. Install dependencies
+
+From the project root:
+
+```bash
+uv sync
+```
+
+### 6. (Optional) Set up Weather API
+
+For the tools example, get a free API key from [weatherapi.com](https://www.weatherapi.com/) and create a `.env` file in the `bielik_example/` directory:
+
+```bash
+WEATHER_API_KEY=your_key_here
+```
+
+## Examples
+
+### Example 1: Basic Inference
+
+**File:** `bielik_basic_inference.py`
+
+The simplest example — setting up a connection to the local Bielik model, creating a PydanticAI Agent, making a synchronous inference request, and retrieving token usage statistics.
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.providers.ollama import OllamaProvider
+
+# Connect to the Bielik model served locally via Ollama
+ollama_model = OpenAIChatModel(
+    model_name="bielik_v3_q8_tools",
+    provider=OllamaProvider(base_url="http://localhost:11434/v1"),
+)
+
+# Create an agent with a Polish system prompt
+agent = Agent(ollama_model, system_prompt="Jesteś asystentem AI odpowiadającym krótko i zwięźle")
+
+
+async def main():
+    result = await agent.run("Cześć, kim jesteś?")  # "Hello, who are you?"
+    print(f"Response: {result.output}")
+    print(f"Token usage: {result.usage()}")
+```
+
+```bash
+cd bielik_example
+uv run python bielik_example/bielik_basic_inference.py
+```
+
+### Example 2: Tool Calling
+
+**File:** `bielik_basic_tools.py`
+
+Demonstrates custom tools with `@agent.tool`, multi-turn conversations with message history, async operations, and handling tool results.
+
+**Tools included:**
+
+1. **roll_dice** — Simulates rolling a 6-sided dice (no external dependencies)
+2. **check_weather** — Fetches real weather data via API (requires weather API key)
+
+```python
+import secrets
+from typing import Any
+
+import httpx
+from pydantic_ai import Agent, RunContext
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.providers.ollama import OllamaProvider
+
+ollama_model = OpenAIChatModel(
+    model_name="bielik_v3_q8_tools",
+    provider=OllamaProvider(base_url="http://localhost:11434/v1"),
+)
+
+agent = Agent(ollama_model, system_prompt="Jesteś pomocnym asystentem AI")
+
+
+@agent.tool
+async def roll_dice(ctx: RunContext[None]) -> int:
+    """Simulates rolling a standard 6-sided dice."""
+    return secrets.choice([1, 2, 3, 4, 5, 6])
+
+
+@agent.tool
+async def check_weather(ctx: RunContext[None], city: str) -> Any:
+    """Fetches real-time weather data for a specified city."""
+    url = "https://api.weatherapi.com/v1/current.json"
+    params = {"key": WEATHER_API_KEY, "q": city, "aqi": "no"}
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, params=params)
+        if response.status_code == 200:
+            data = response.json()
+            return {
+                "location": data["location"]["name"],
+                "temp_c": data["current"]["temp_c"],
+                "condition": data["current"]["condition"]["text"],
+            }
+        return f"Error: Could not find weather for {city}"
+
+
+async def main():
+    # Multi-turn conversation with message history
+    result_1 = await agent.run("Cześć, kim jesteś?")
+    result_2 = await agent.run("Rzuć kostką!", message_history=result_1.all_messages())
+    result_3 = await agent.run(
+        "Sprawdź pogodę w Warszawie!", message_history=result_2.all_messages()
+    )
+    print(f"Response: {result_3.output}")
+```
+
+```bash
+cd bielik_example
+uv run python bielik_example/bielik_basic_tools.py
+```
+
+## Key Concepts
+
+### Agent
+
+An `Agent` wraps the language model, manages conversation history, coordinates tool calling, and processes user requests.
+
+### Tools
+
+Tools are functions decorated with `@agent.tool` that extend an agent's capabilities. They can be synchronous or asynchronous, receive a `RunContext` parameter, and make external API calls.
+
+### Message History
+
+PydanticAI maintains full conversation history for multi-turn interactions, context preservation, and tool call tracking via `result.all_messages()`.
+
+## Troubleshooting
+
+!!! warning "Connection refused"
+    Make sure Ollama is running (`ollama serve` in a separate terminal) and listening on `http://localhost:11434`.
+
+!!! warning "Model not found"
+    Pull the model first: `ollama pull SpeakLeash/bielik-11b-v3.0-instruct:Q8_0`
+
+!!! warning "Model running slowly"
+    Bielik-11b is an 11 billion parameter model. Performance depends on your hardware — GPU is significantly faster than CPU. Consider smaller quantizations (Q4, Q5) if needed.
+
+## Further Resources
+
+- [PydanticAI Documentation](https://ai.pydantic.dev/)
+- [Ollama Documentation](https://github.com/ollama/ollama)
+- [Bielik Website](https://bielik.ai/)
+- [Bielik on Hugging Face](https://huggingface.co/speakleash/Bielik-11B-v3.0-Instruct)
+- [WeatherAPI Documentation](https://www.weatherapi.com/docs/)

docs/examples/direct-model-request.md

@@ -0,0 +1,64 @@
+---
+title: Direct Model Requests
+---
+
+# Direct Model Requests
+
+This example demonstrates how to use PydanticAI's **direct API** to make model requests without creating an Agent. The direct API is ideal when you need more control over model interactions or want to implement custom behavior.
+
+## When to Use Direct API vs Agent
+
+| Direct API | Agent API |
+|---|---|
+| More direct control over model interactions | Most application use cases |
+| Custom behavior around model requests | Built-in tool execution, retrying, structured output |
+| Building your own abstractions | Complex multi-turn conversations |
+
+## Running
+
+```bash
+cd direct_model_request
+uv run direct_request_demo.py
+```
+
+## Code Comparison: Direct API vs Agent
+
+Here's a side-by-side look at how you'd accomplish the same task using both approaches:
+
+=== "Direct API"
+
+    ```python
+    from pydantic_ai import ModelRequest
+    from pydantic_ai.direct import model_request_sync
+
+    prompt = "What is the capital of France? Answer briefly."
+
+    response = model_request_sync(
+        "openai:gpt-5.2",
+        [ModelRequest.user_text_prompt(prompt)],
+    )
+
+    print(response.parts[0].content)
+    ```
+
+=== "Agent"
+
+    ```python
+    from pydantic_ai import Agent
+
+    agent = Agent("openai:gpt-5.2")
+
+    result = agent.run_sync("What is the capital of France? Answer briefly.")
+
+    print(result.output)
+    ```
+
+The **Direct API** gives you raw access to the model request/response cycle — you construct `ModelRequest` objects yourself and work with response parts directly. The **Agent** wraps this in a higher-level interface that handles tool execution, retries, and structured output for you.
+
+!!! info "When to Choose Direct API"
+    The direct API gives you lower-level access when you need it. For most applications, the Agent API is the better choice — it handles retries, tool execution, and structured output parsing automatically.
+
+## Learn More
+
+- [PydanticAI Direct API Documentation](https://ai.pydantic.dev/direct/)
+- [Agent vs Direct API Comparison](https://ai.pydantic.dev/direct/#when-to-use-the-direct-api-vs-agent)