pydantic-ai-examples 0.0.6a1__tar.gz

pydantic_ai_examples-0.0.6a1/.gitignore

@@ -0,0 +1,15 @@
+site
+.python-version
+.venv
+dist
+__pycache__
+*.env
+/scratch/
+/.coverage
+env*/
+/TODO.md
+/postgres-data/
+.DS_Store
+/pydantic_ai_examples/.chat_app_messages.jsonl
+.cache/
+.docs-insiders-install

pydantic_ai_examples-0.0.6a1/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.3
+Name: pydantic-ai-examples
+Version: 0.0.6a1
+Summary: Agent Framework / shim to use Pydantic with LLMs
+Author-email: Samuel Colvin <samuel@pydantic.dev>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: fastapi>=0.115.4
+Requires-Dist: logfire[asyncpg,fastapi]>=2.3
+Requires-Dist: pydantic-ai-slim[groq,openai,vertexai]
+Requires-Dist: python-multipart>=0.0.17
+Requires-Dist: rich>=13.9.2
+Requires-Dist: uvicorn>=0.32.0
+Description-Content-Type: text/markdown
+
+# Pydantic AI Examples
+
+Examples of how to use Pydantic AI and what it can do.
+
+Full documentation of these examples and how to run them is available at [ai.pydantic.dev/examples/](https://ai.pydantic.dev/examples/).

pydantic_ai_examples-0.0.6a1/README.md

@@ -0,0 +1,5 @@
+# Pydantic AI Examples
+
+Examples of how to use Pydantic AI and what it can do.
+
+Full documentation of these examples and how to run them is available at [ai.pydantic.dev/examples/](https://ai.pydantic.dev/examples/).

pydantic_ai_examples-0.0.6a1/__main__.py

@@ -0,0 +1,55 @@
+"""Very simply CLI to aid in running the examples, and for copying examples code to a new directory.
+
+See README.md for more information.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def cli():
+    this_dir = Path(__file__).parent
+
+    parser = argparse.ArgumentParser(
+        prog='pydantic_ai_examples',
+        description=__doc__,
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    parser.add_argument(
+        '-v', '--version', action='store_true', help='show the version and exit'
+    )
+    parser.add_argument(
+        '--copy-to', dest='DEST', help='Copy all examples to a new directory'
+    )
+
+    args = parser.parse_args()
+    if args.version:
+        from pydantic_ai import __version__
+
+        print(f'pydantic_ai v{__version__}')
+    elif args.DEST:
+        copy_to(this_dir, Path(args.DEST))
+    else:
+        parser.print_help()
+
+
+def copy_to(this_dir: Path, dst: Path):
+    if dst.exists():
+        print(f'Error: destination path "{dst}" already exists', file=sys.stderr)
+        sys.exit(1)
+
+    dst.mkdir(parents=True)
+
+    count = 0
+    for file in this_dir.glob('*.*'):
+        with open(file, 'rb') as src_file:
+            with open(dst / file.name, 'wb') as dst_file:
+                dst_file.write(src_file.read())
+        count += 1
+
+    print(f'Copied {count} example files to "{dst}"')
+
+
+if __name__ == '__main__':
+    cli()

pydantic_ai_examples-0.0.6a1/bank_support.py

@@ -0,0 +1,88 @@
+"""Small but complete example of using PydanticAI to build a support agent for a bank.
+
+Run with:
+
+    uv run -m pydantic_ai_examples.bank_supports
+"""
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel, Field
+
+from pydantic_ai import Agent, CallContext
+
+
+class DatabaseConn:
+    """This is a fake database for example purposes.
+
+    In reality, you'd be connecting to an external database
+    (e.g. PostgreSQL) to get information about customers.
+    """
+
+    @classmethod
+    async def customer_name(cls, *, id: int) -> str | None:
+        if id == 123:
+            return 'John'
+
+    @classmethod
+    async def customer_balance(cls, *, id: int, include_pending: bool) -> float:
+        if id == 123:
+            return 123.45
+        else:
+            raise ValueError('Customer not found')
+
+
+@dataclass
+class SupportDependencies:
+    customer_id: int
+    db: DatabaseConn
+
+
+class SupportResult(BaseModel):
+    support_advice: str = Field(description='Advice returned to the customer')
+    block_card: bool = Field(description='Whether to block their')
+    risk: int = Field(description='Risk level of query', ge=0, le=10)
+
+
+support_agent = Agent(
+    'openai:gpt-4o',
+    deps_type=SupportDependencies,
+    result_type=SupportResult,
+    system_prompt=(
+        'You are a support agent in our bank, give the '
+        'customer support and judge the risk level of their query. '
+        "Reply using the customer's name."
+    ),
+)
+
+
+@support_agent.system_prompt
+async def add_customer_name(ctx: CallContext[SupportDependencies]) -> str:
+    customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id)
+    return f"The customer's name is {customer_name!r}"
+
+
+@support_agent.retriever
+async def customer_balance(
+    ctx: CallContext[SupportDependencies], include_pending: bool
+) -> str:
+    """Returns the customer's current account balance."""
+    balance = await ctx.deps.db.customer_balance(
+        id=ctx.deps.customer_id,
+        include_pending=include_pending,
+    )
+    return f'${balance:.2f}'
+
+
+deps = SupportDependencies(customer_id=123, db=DatabaseConn())
+result = support_agent.run_sync('What is my balance?', deps=deps)
+print(result.data)
+"""
+support_advice='Hello John, your current account balance, including pending transactions, is $123.45.' block_card=False risk=1
+"""
+
+result = support_agent.run_sync('I just lost my card!', deps=deps)
+print(result.data)
+"""
+support_advice="I'm sorry to hear that, John. We are temporarily blocking your card to prevent unauthorized transactions." block_card=True risk=8
+"""

pydantic_ai_examples-0.0.6a1/chat_app.html

@@ -0,0 +1,81 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Chat App</title>
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
+  <style>
+    main {
+      max-width: 700px;
+    }
+    #conversation .user::before {
+      content: 'You asked: ';
+      font-weight: bold;
+      display: block;
+    }
+    #conversation .llm-response::before {
+      content: 'AI Response: ';
+      font-weight: bold;
+      display: block;
+    }
+    #spinner {
+      opacity: 0;
+      transition: opacity 500ms ease-in;
+      width: 30px;
+      height: 30px;
+      border: 3px solid #222;
+      border-bottom-color: transparent;
+      border-radius: 50%;
+      animation: rotation 1s linear infinite;
+    }
+    @keyframes rotation {
+      0% { transform: rotate(0deg); }
+      100% { transform: rotate(360deg); }
+    }
+    #spinner.active {
+      opacity: 1;
+    }
+  </style>
+</head>
+<body>
+  <main class="border rounded mx-auto my-5 p-4">
+    <h1>Chat App</h1>
+    <p>Ask me anything...</p>
+    <div id="conversation" class="px-2"></div>
+    <div class="d-flex justify-content-center mb-3">
+      <div id="spinner"></div>
+    </div>
+    <form method="post">
+      <input id="prompt-input" name="prompt" class="form-control"/>
+      <div class="d-flex justify-content-end">
+        <button class="btn btn-primary mt-2">Send</button>
+      </div>
+    </form>
+    <div id="error" class="d-none text-danger">
+      Error occurred, check the console for more information.
+    </div>
+  </main>
+</body>
+</html>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/typescript/5.6.3/typescript.min.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+<script type="module">
+  // to let me write TypeScript, without adding the burden of npm we do a dirty, non-production-ready hack
+  // and transpile the TypeScript code in the browser
+  // this is (arguably) A neat demo trick, but not suitable for production!
+  async function loadTs() {
+    const response = await fetch('/chat_app.ts');
+    const tsCode = await response.text();
+    const jsCode = window.ts.transpile(tsCode, { target: "es2015" });
+    let script = document.createElement('script');
+    script.type = 'module';
+    script.text = jsCode;
+    document.body.appendChild(script);
+  }
+
+  loadTs().catch((e) => {
+    console.error(e);
+    document.getElementById('error').classList.remove('d-none');
+    document.getElementById('spinner').classList.remove('active');
+  });
+</script>

pydantic_ai_examples-0.0.6a1/chat_app.py

@@ -0,0 +1,109 @@
+"""Simple chat app example build with FastAPI.
+
+Run with:
+
+    uv run -m pydantic_ai_examples.chat_app
+"""
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated
+
+import fastapi
+import logfire
+from fastapi.responses import HTMLResponse, Response, StreamingResponse
+from pydantic import Field, TypeAdapter
+
+from pydantic_ai import Agent
+from pydantic_ai.messages import (
+    Message,
+    MessagesTypeAdapter,
+    ModelTextResponse,
+    UserPrompt,
+)
+
+# 'if-token-present' means nothing will be sent (and the example will work) if you don't have logfire configured
+logfire.configure(send_to_logfire='if-token-present')
+
+agent = Agent('openai:gpt-4o')
+
+app = fastapi.FastAPI()
+logfire.instrument_fastapi(app)
+
+
+@app.get('/')
+async def index() -> HTMLResponse:
+    return HTMLResponse((THIS_DIR / 'chat_app.html').read_bytes())
+
+
+@app.get('/chat_app.ts')
+async def main_ts() -> Response:
+    """Get the raw typescript code, it's compiled in the browser, forgive me."""
+    return Response((THIS_DIR / 'chat_app.ts').read_bytes(), media_type='text/plain')
+
+
+@app.get('/chat/')
+async def get_chat() -> Response:
+    msgs = database.get_messages()
+    return Response(
+        b'\n'.join(MessageTypeAdapter.dump_json(m) for m in msgs),
+        media_type='text/plain',
+    )
+
+
+@app.post('/chat/')
+async def post_chat(prompt: Annotated[str, fastapi.Form()]) -> StreamingResponse:
+    async def stream_messages():
+        """Streams new line delimited JSON `Message`s to the client."""
+        # stream the user prompt so that can be displayed straight away
+        yield MessageTypeAdapter.dump_json(UserPrompt(content=prompt)) + b'\n'
+        # get the chat history so far to pass as context to the agent
+        messages = list(database.get_messages())
+        # run the agent with the user prompt and the chat history
+        async with agent.run_stream(prompt, message_history=messages) as result:
+            async for text in result.stream(debounce_by=0.01):
+                # text here is a `str` and the frontend wants
+                # JSON encoded ModelTextResponse, so we create one
+                m = ModelTextResponse(content=text, timestamp=result.timestamp())
+                yield MessageTypeAdapter.dump_json(m) + b'\n'
+
+        # add new messages (e.g. the user prompt and the agent response in this case) to the database
+        database.add_messages(result.new_messages_json())
+
+    return StreamingResponse(stream_messages(), media_type='text/plain')
+
+
+THIS_DIR = Path(__file__).parent
+MessageTypeAdapter: TypeAdapter[Message] = TypeAdapter(
+    Annotated[Message, Field(discriminator='role')]
+)
+
+
+@dataclass
+class Database:
+    """Very rudimentary database to store chat messages in a JSON lines file."""
+
+    file: Path = THIS_DIR / '.chat_app_messages.jsonl'
+
+    def add_messages(self, messages: bytes):
+        with self.file.open('ab') as f:
+            f.write(messages + b'\n')
+
+    def get_messages(self) -> Iterator[Message]:
+        if self.file.exists():
+            with self.file.open('rb') as f:
+                for line in f:
+                    if line:
+                        yield from MessagesTypeAdapter.validate_json(line)
+
+
+database = Database()
+
+
+if __name__ == '__main__':
+    import uvicorn
+
+    uvicorn.run(
+        'pydantic_ai_examples.chat_app:app', reload=True, reload_dirs=[str(THIS_DIR)]
+    )

pydantic_ai_examples-0.0.6a1/chat_app.ts

@@ -0,0 +1,90 @@
+// BIG FAT WARNING: to avoid the complexity of npm, this typescript is compiled in the browser
+// there's currently no static type checking
+
+import { marked } from 'https://cdnjs.cloudflare.com/ajax/libs/marked/15.0.0/lib/marked.esm.js'
+const convElement = document.getElementById('conversation')
+
+const promptInput = document.getElementById('prompt-input') as HTMLInputElement
+const spinner = document.getElementById('spinner')
+
+// stream the response and render messages as each chunk is received
+// data is sent as newline-delimited JSON
+async function onFetchResponse(response: Response): Promise<void> {
+  let text = ''
+  let decoder = new TextDecoder()
+  if (response.ok) {
+    const reader = response.body.getReader()
+    while (true) {
+      const {done, value} = await reader.read()
+      if (done) {
+        break
+      }
+      text += decoder.decode(value)
+      addMessages(text)
+      spinner.classList.remove('active')
+    }
+    addMessages(text)
+    promptInput.disabled = false
+    promptInput.focus()
+  } else {
+    const text = await response.text()
+    console.error(`Unexpected response: ${response.status}`, {response, text})
+    throw new Error(`Unexpected response: ${response.status}`)
+  }
+}
+
+// The format of messages, this matches pydantic-ai both for brevity and understanding
+// in production, you might not want to keep this format all the way to the frontend
+interface Message {
+  role: string
+  content: string
+  timestamp: string
+}
+
+// take raw response text and render messages into the `#conversation` element
+// Message timestamp is assumed to be a unique identifier of a message, and is used to deduplicate
+// hence you can send data about the same message multiple times, and it will be updated
+// instead of creating a new message elements
+function addMessages(responseText: string) {
+  const lines = responseText.split('\n')
+  const messages: Message[] = lines.filter(line => line.length > 1).map(j => JSON.parse(j))
+  for (const message of messages) {
+    // we use the timestamp as a crude element id
+    const {timestamp, role, content} = message
+    const id = `msg-${timestamp}`
+    let msgDiv = document.getElementById(id)
+    if (!msgDiv) {
+      msgDiv = document.createElement('div')
+      msgDiv.id = id
+      msgDiv.title = `${role} at ${timestamp}`
+      msgDiv.classList.add('border-top', 'pt-2', role)
+      convElement.appendChild(msgDiv)
+    }
+    msgDiv.innerHTML = marked.parse(content)
+  }
+  window.scrollTo({ top: document.body.scrollHeight, behavior: 'smooth' })
+}
+
+function onError(error: any) {
+  console.error(error)
+  document.getElementById('error').classList.remove('d-none')
+  document.getElementById('spinner').classList.remove('active')
+}
+
+async function onSubmit(e: SubmitEvent): Promise<void> {
+  e.preventDefault()
+  spinner.classList.add('active')
+  const body = new FormData(e.target as HTMLFormElement)
+
+  promptInput.value = ''
+  promptInput.disabled = true
+
+  const response = await fetch('/chat/', {method: 'POST', body})
+  await onFetchResponse(response)
+}
+
+// call onSubmit when the form is submitted (e.g. user clicks the send button or hits Enter)
+document.querySelector('form').addEventListener('submit', (e) => onSubmit(e).catch(onError))
+
+// load messages on page load
+fetch('/chat/').then(onFetchResponse).catch(onError)

pydantic_ai_examples-0.0.6a1/pydantic_model.py

@@ -0,0 +1,33 @@
+"""Simple example of using Pydantic AI to construct a Pydantic model from a text input.
+
+Run with:
+
+    uv run -m pydantic_ai_examples.pydantic_model
+"""
+
+import os
+from typing import cast
+
+import logfire
+from pydantic import BaseModel
+
+from pydantic_ai import Agent
+from pydantic_ai.models import KnownModelName
+
+# 'if-token-present' means nothing will be sent (and the example will work) if you don't have logfire configured
+logfire.configure(send_to_logfire='if-token-present')
+
+
+class MyModel(BaseModel):
+    city: str
+    country: str
+
+
+model = cast(KnownModelName, os.getenv('PYDANTIC_AI_MODEL', 'openai:gpt-4o'))
+print(f'Using model: {model}')
+agent = Agent(model, result_type=MyModel)
+
+if __name__ == '__main__':
+    result = agent.run_sync('The windy city in the US of A.')
+    print(result.data)
+    print(result.cost())

pydantic_ai_examples-0.0.6a1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "../pyproject.toml"
+
+[project]
+name = "pydantic-ai-examples"
+description = "Agent Framework / shim to use Pydantic with LLMs"
+authors = [
+    { name = "Samuel Colvin", email = "samuel@pydantic.dev" },
+]
+license = "MIT"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Unix",
+    "Operating System :: POSIX :: Linux",
+    "Environment :: Console",
+    "Environment :: MacOS X",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet",
+]
+requires-python = ">=3.9"
+dynamic = ["version"]
+dependencies = [
+    "pydantic-ai-slim[openai,vertexai,groq]",
+    "asyncpg>=0.30.0",
+    "fastapi>=0.115.4",
+    "logfire[asyncpg,fastapi]>=2.3",
+    "python-multipart>=0.0.17",
+    "rich>=13.9.2",
+    "uvicorn>=0.32.0",
+]
+
+[tool.hatch.build]
+include = ["*.py", "*.html", "*.ts"]
+
+[tool.hatch.build.targets.wheel.sources]
+"" = "pydantic_ai_examples"
+
+[tool.uv.sources]
+pydantic-ai-slim = { workspace = true }
+
+[tool.ruff]
+extend = "../pyproject.toml"
+line-length = 88