From e34a8ec5aa8a22704082c52203aef8f8382503a1 Mon Sep 17 00:00:00 2001
From: Connor Adams <connorads@users.noreply.github.com>
Date: Tue, 2 Dec 2025 08:36:07 +0000
Subject: [PATCH] Update README

---
 README.md | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index af75844..ff2af34 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,44 @@
-# Demo of the Pydantic Stack
+# Pydantic Stack Demos
+
+A collection of small, focused examples showing how to use PydanticAI, Logfire, and related tools together.
+
+## Demos
+
+### `distributed-frontend-example/`
+
+React + FastAPI image generator with distributed tracing from browser to backend via Logfire. Shows how to proxy client traces safely and trace calls into OpenAI and file I/O.
+
+### `durable-exec/`
+
+Deep‑research and “Twenty Questions” agents implemented with plain asyncio, DBOS workflows, and Temporal workflows. Includes an evaluation script using pydantic‑evals to compare different base models.
+
+### `fastapi-example/`
+
+Minimal FastAPI app that generates images with OpenAI, stores them, and serves a simple HTML page. Demonstrates FastAPI + Logfire + HTTPX instrumentation.
+
+### `logfire-hello-world/`
+
+Smallest possible Logfire example: configure a service and emit a single structured log line.
+
+### `pai-hello/`
+
+“Hello world” for PydanticAI: a single agent call with a short system prompt, optionally instrumented with Logfire.
+
+### `pai-mcp-sampling/`
+
+MCP sampling demo with PydanticAI acting as both MCP client and MCP server. The client calls an MCP tool that runs another agent via `MCPSamplingModel` to generate SVG images.
+
+### `pai-memory/`
+
+Two Postgres‑backed memory patterns:
+
+- storing full message history per user, and  
+- storing and retrieving explicit “facts” through agent tools.
+
+### `pai-pydantic/`
+
+Structured extraction into Pydantic models. Shows how `output_type` works and how validation errors trigger retries when domain rules are enforced.
+
+### `pai-weather/`
+
+Tool‑using agent that resolves locations and fetches (randomised) weather data via HTTP endpoints, with typed tool outputs, dependency injection, and concurrent HTTP requests.