Update project configuration and main application logic

- Change default model in .env.example from 'gpt-4o-mini' to 'gpt-5-nano'.
- Upgrade pre-commit hooks to newer versions in .pre-commit-config.yaml.
- Downgrade Python version requirement in .python-version and pyproject.toml from 3.13 to 3.12.
- Refactor Makefile to streamline setup process and improve command descriptions.
- Add new pyright configuration file for type checking.
- Introduce main application logic in src/main.py, including agent definitions and execution flow.

Author: abpai

.env.example

@@ -6,7 +6,7 @@
 
 # Required: Your OpenAI API key for the Agents SDK to function.
 OPENAI_API_KEY=sk-...
-DEFAULT_MODEL=gpt-4o-mini
+DEFAULT_MODEL=gpt-5-nano
 
 # Optional: The logging level for the application.
 # Options: DEBUG, INFO, WARNING, ERROR

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -12,31 +12,15 @@ repos:
       - id: check-docstring-first
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.8
+    rev: v0.12.11
     hooks:
-      - id: ruff
-        args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
-    hooks:
-      - id: mypy
-        files: ^topics/
-        args: [--ignore-missing-imports]
-        additional_dependencies: [types-requests]
-
-  - repo: https://github.com/nbQA-dev/nbQA
-    rev: 1.7.1
-    hooks:
-      - id: nbqa-ruff
-        files: \.ipynb$
-
   - repo: local
     hooks:
       - id: pytest-check
         name: pytest-check
-        entry: uv run pytest --co -q
+        entry: bash -c "PYTHONPATH=. uv run pytest --co -q -m \"not integration\""
         language: system
         pass_filenames: false
         always_run: true

.python-version

@@ -1 +1 @@
-3.13
+3.12

Makefile

@@ -1,33 +1,43 @@
-.PHONY: help install install-dev test lint format format-check clean setup pre-commit-install pre-commit-run lock-check run
+.PHONY: help install install-dev setup pre-commit-install pre-commit-run lint format typecheck test clean lock-check run
 
 export PYTHONPATH := .
+VENV_DIR = .venv
 
 help:
-	@echo "Available commands:"
+	@echo 'Available commands:'
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
 
-install: ## Install core dependencies
+install:
 	uv sync
 
-install-dev: ## Install core + dev dependencies
+install-dev:
 	uv sync --extra dev
 
-setup: install-dev pre-commit-install ## Full dev setup
-
-pre-commit-install: ## Install pre-commit hooks
+setup:
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo 'Creating virtual environment in $(VENV_DIR)...'; \
+		uv venv; \
+	fi
+	@echo 'Installing dependencies...'
+	@uv sync --extra dev
+	@echo 'Installing pre-commit hooks...'
+	@uv run pre-commit install
+	@echo '\n✅ Setup complete. To activate the environment, run:\nsource .venv/bin/activate'
+
+pre-commit-install:
 	uv run pre-commit install
 
-pre-commit-run: ## Run pre-commit on all files
+pre-commit-run:
 	uv run pre-commit run --all-files
 
-lint: ## Run Ruff linter
-	uv run ruff check .
+lint:
+	uv run ruff check . --fix
 
-format: ## Format code with Ruff
+format:
 	uv run ruff format .
 
-format-check: ## Check formatting (CI)
-	uv run ruff format --check .
+typecheck:
+		uv run pyright -p pyrightconfig.strict.json
 
 test: ## Run Pytest
 	uv run pytest
@@ -40,4 +50,4 @@ lock-check: ## Ensure uv.lock is up-to-date
 	uv sync --locked --extra dev
 
 run: ## Run the main application
-	uv run python main.py
+	uv run python src/main.py

README.md

@@ -1,72 +1,77 @@
-# Python Boilerplate with OpenAI Agents
+# Python Boilerplate
 
 This template is a **lean starting point** for Python projects that use:
 
-* ✅ Ruff – formatting & linting
-* 🧪 Pytest – testing
-* ⚙️ Pydantic Settings – typed environment configuration
-* 📦 uv – fast dependency management / locking
+- ✅ Ruff – formatting & linting
+- 🧪 Pytest – testing
+- ⚙️ Pydantic Settings – typed environment configuration
+- 📦 uv – fast dependency management / locking
 
 ---
 
 ## Quick Start
 
 1.  **Create & Activate Virtual Environment:**
+
     ```bash
     # Create the virtual environment using uv
     uv venv
     # Activate it (on macOS/Linux)
     source .venv/bin/activate
     # On Windows, use: .venv\Scripts\activate
     ```
-    *This creates a `.venv` directory in your project.*
+
+    _This creates a `.venv` directory in your project._
 
 2.  **Install Dependencies:**
+
     ```bash
     # Installs core + dev dependencies into your active venv
     make setup
     ```
 
 3.  **Run the Quick-Start Agent Demo:**
+
     ```bash
     # This will use your activated environment
     make run
     ```
 
 4.  **Run Quality Checks:**
     ```bash
-    make format-check && make lint && make test
+    make format && make lint && make test
     ```
 
-`main.py` is a minimal script that spins up an assistant. Modify it to explore the SDK.
+`src/main.py` is a minimal script that spins up an assistant. Modify it to explore the SDK.
 
 ---
 
 ## Make Commands
 
-| Command            | Description                          |
-| ------------------ | ------------------------------------ |
-| `make install`     | Install core dependencies            |
-| `make install-dev` | Install core + dev dependencies      |
-| `make format`      | Format code with Ruff                |
-| `make format-check`| Check formatting (CI mode)           |
-| `make lint`        | Run Ruff linter                      |
-| `make test`        | Run Pytest                           |
-| `make clean`       | Remove *.pyc & cache directories     |
-| `make lock-check`  | Assert `uv.lock` is in sync          |
+| Command            | Description                             |
+| ------------------ | --------------------------------------- |
+| `make install`     | Install core dependencies               |
+| `make install-dev` | Install core + dev dependencies         |
+| `make setup`       | Install dependencies + pre-commit hooks |
+| `make format`      | Format code with Ruff                   |
+| `make lint`        | Run Ruff linter                         |
+| `make typecheck`   | Run Pyright type checker                |
+| `make test`        | Run Pytest                              |
+| `make clean`       | Remove \*.pyc & cache directories       |
+| `make lock-check`  | Assert `uv.lock` is in sync             |
 
 ---
 
 ## Environment Variables
 
 `utils/settings.py` reads variables from a `.env` file or the environment.
 
-| Variable          | Default       | Description                          |
-| ----------------- | ------------- | ------------------------------------ |
-| `OPENAI_API_KEY`  | (required)    | Your OpenAI API key.                 |
-| `LOG_LEVEL`       | `INFO`        | `DEBUG`, `INFO`, `WARNING`, `ERROR`  |
-| `LOG_FORMAT`      | `console`     | `console` (colored) or `json`.       |
-| `DEFAULT_MODEL`   | `gpt-4o-mini` | Default model for agents.            |
+| Variable         | Default      | Description                         |
+| ---------------- | ------------ | ----------------------------------- |
+| `OPENAI_API_KEY` | (required)   | Your OpenAI API key.                |
+| `LOG_LEVEL`      | `INFO`       | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `LOG_FORMAT`     | `console`    | `console` (colored) or `json`.      |
+| `DEFAULT_MODEL`  | `gpt-5-nano` | Default model for agents.           |
 
 See `.env.example` for a template.
 
@@ -77,7 +82,8 @@ See `.env.example` for a template.
 Only what you need, nothing more:
 
 ```
-├── main.py                   # Minimal OpenAI Agents example
+├── src/
+│   └── main.py               # Minimal OpenAI Agents example
 ├── utils/
 │   └── settings.py           # Pydantic Settings helper
 ├── tests/

pyproject.toml

@@ -1,49 +1,40 @@
 [project]
 name = "templates.python"
-version = "0.1.0"
+version = "0.2.0"
 description = "A boilerplate for Python projects."
 readme = "README.md"
-requires-python = ">=3.13"
+requires-python = ">=3.12"
 license = {text = "MIT"}
 authors = [
     {name = "Andy Pai", email = "andy@r2pi.co"},
 ]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: Developers",
-    "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.13",
-    "Topic :: Scientific/Engineering :: Artificial Intelligence",
-]
 
 dependencies = [
+    "openai-agents>=0.2.2",
+    "pydantic>=2.11.7",
+    "pydantic-settings>=2.10.1",
     "structlog>=24.0.0",
     "tqdm>=4.65.0",
-    "pydantic>=2.0.0",
-    "pydantic-settings>=2.0.0",
-    "openai-agents>=0.2.2",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=7.4.0",
-    "pytest-cov>=4.1.0",
-    "ruff>=0.1.0",
-    "pre-commit>=3.0.0",
-    "mypy>=1.0.0",
-    "types-requests>=2.31.0",
+    "ipykernel>=6.30.1",
+    "pre-commit>=4.2.0",
+    "pyright>=1.1.404",
+    "pytest>=8.4.1",
+    "pytest-cov>=6.2.1",
+    "ruff>=0.12.11",
 ]
 
 ml = [
-  "torch>=2.0.0",
-  "scikit-learn>=1.3.0",
-  "mlflow>=2.0.0",
-  "matplotlib>=3.7.0",
-  "numpy>=1.24.0",
-  "pandas>=2.0.0",
-  "seaborn>=0.12.0",
+  "torch>=2.7.1",
+  "scikit-learn>=1.7.1",
+  "mlflow>=3.1.1",
+  "matplotlib>=3.10.3",
+  "numpy>=2.3.1",
+  "pandas>=2.3.1",
+  "seaborn>=0.13.2",
 ]
 
 [tool.ruff]
@@ -62,7 +53,7 @@ select = [
     "N",   # pep8-naming
     "RUF", # ruff-specific rules
 ]
-ignore = ["E501", "B008", "C901", "N812"]
+ignore = ["E501", "B008", "C901", "N812", "N803", "N806"]
 
 [tool.ruff.format]
 quote-style = "single"
@@ -77,10 +68,12 @@ addopts = ["-ra"]
 pythonpath = ["."]
 
 [tool.pyright]
-include = ["*.py", "models", "tests"]
-exclude = ["**/__pycache__", "config"]
-typeCheckingMode = "strict"
+include = ["*.py", "tests"]
+exclude = ["**/__pycache__"]
+typeCheckingMode = "off"
+
 reportMissingImports = true
 reportMissingTypeStubs = false
-pythonVersion = "3.13"
+
+pythonVersion = "3.12"
 pythonPlatform = "All"

pyrightconfig.strict.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/pyright/main/packages/pyright/dist/pyright.schema.json",
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "**/__pycache__",
+    "**/typings"
+  ],
+  "typeCheckingMode": "basic",
+  "reportMissingImports": true,
+  "useLibraryCodeForTypes": true
+}