feat(ag-ui): example command line options

Add command line options to the Pydantic AI AG UI examples, allowing
users to specify:
- Listening port
- Adapter log level
- Reload

Author: stevenh

docs/ag-ui.md

@@ -289,10 +289,27 @@ installed with either of the following:
 pip/uv-add pydantic-ai-examples
 ```
 
-Direct:
+Direct, which supports command line flags:
 
 ```shell
-python -m pydantic_ai_ag_ui_examples.dojo_server
+python -m pydantic_ai_ag_ui_examples.dojo_server --help
+usage: dojo_server.py [-h] [--port PORT] [--reload] [--no-reload] [--log-level {critical,error,warning,info,debug,trace}]
+
+PydanticAI AG-UI Dojo server
+
+options:
+  -h, --help            show this help message and exit
+  --port PORT, -p PORT  Port to run the server on (default: 9000)
+  --reload              Enable auto-reload (default: True)
+  --no-reload           Disable auto-reload
+  --log-level {critical,error,warning,info,debug,trace}
+                        Agent log level (default: info)
+```
+
+Run with adapter debug logging:
+
+```shell
+python -m pydantic_ai_ag_ui_examples.dojo_server --log-level debug
 ```
 
 Using uvicorn:

examples/pydantic_ai_ag_ui_examples/basic.py

@@ -43,20 +43,16 @@ async def handler(
 
 
 if __name__ == '__main__':
-    import logging
-
     import uvicorn
 
-    logging.basicConfig(
-        format='%(levelname)s: %(message)s',
-        level=logging.INFO,
-        force=True,
-    )
+    from .cli import Args, parse_args
+
+    args: Args = parse_args()
 
     uvicorn.run(
         'pydantic_ai_ag_ui_examples.dojo_server:app',
-        host='127.0.0.1',
-        port=9000,
-        reload=True,
-        log_level='info',
+        port=args.port,
+        reload=args.reload,
+        log_level=args.log_level,
+        log_config=args.log_config(),
     )

examples/pydantic_ai_ag_ui_examples/cli/__init__.py

@@ -0,0 +1,8 @@
+"""Command line interface for the PydanticAI AG-UI servers."""
+
+from .args import Args, parse_args
+
+__all__ = [
+    'Args',
+    'parse_args',
+]

examples/pydantic_ai_ag_ui_examples/cli/args.py

@@ -0,0 +1,71 @@
+"""CLI argument parser for the PydanticAI AG-UI servers."""
+
+import argparse
+from typing import Any
+
+from uvicorn.config import LOGGING_CONFIG
+
+from pydantic_ai.models import dataclass
+
+
+@dataclass
+class Args:
+    """Custom namespace for command line arguments."""
+
+    port: int
+    reload: bool
+    log_level: str
+    loggers: tuple[str, ...]
+
+    def log_config(self) -> dict[str, Any]:
+        """Return the logging configuration based on the log level."""
+        log_config: dict[str, Any] = LOGGING_CONFIG.copy()
+        log_config['loggers']['pydantic_ai_ag_ui.adapter'] = {
+            'handlers': ['default'],
+            'level': self.log_level.upper(),
+            'propagate': False,
+        }
+        return log_config
+
+
+def parse_args(
+    loggers: tuple[str, ...] = tuple(
+        'pydantic_ai_ag_ui.adapter',
+    ),
+) -> Args:
+    """Parse command line arguments for the PydanticAI AG-UI servers.
+
+    Args:
+        loggers: A tuple of logger names to configure. Defaults to the adapter logger.
+
+    Returns:
+        Args: A dataclass containing the parsed command line arguments.
+    """
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
+        description='PydanticAI AG-UI Dojo server'
+    )
+    parser.add_argument(
+        '--port',
+        '-p',
+        type=int,
+        default=9000,
+        help='Port to run the server on (default: 9000)',
+    )
+    parser.add_argument(
+        '--reload',
+        action='store_true',
+        default=True,
+        help='Enable auto-reload (default: True)',
+    )
+    parser.add_argument(
+        '--no-reload', dest='reload', action='store_false', help='Disable auto-reload'
+    )
+    parser.add_argument(
+        '--log-level',
+        choices=['critical', 'error', 'warning', 'info', 'debug', 'trace'],
+        default='info',
+        help='Adapter log level (default: info)',
+    )
+
+    args: argparse.Namespace = parser.parse_args()
+    return Args(loggers=loggers, **vars(args))

examples/pydantic_ai_ag_ui_examples/dojo_server.py

@@ -13,8 +13,6 @@
 
 from __future__ import annotations
 
-import logging
-
 from fastapi import FastAPI
 
 from .api import (
@@ -36,19 +34,15 @@
 
 
 if __name__ == '__main__':
-    import logging
-
     import uvicorn
 
-    logging.basicConfig(
-        format='%(levelname)s: %(message)s',
-        level=logging.INFO,
-        force=True,
-    )
+    from .cli import Args, parse_args
+
+    args: Args = parse_args()
 
     uvicorn.run(
         'pydantic_ai_ag_ui_examples.dojo_server:app',
-        port=9000,
-        reload=True,
-        log_level='info',
+        port=args.port,
+        reload=args.reload,
+        log_config=args.log_config(),
     )