feat: transform template to generic Python boilerplate v0.3.0

Major refactoring to create a clean, OpenAI-agnostic Python project template:

Dependencies:
- Upgrade to Python 3.13
- Remove openai-agents dependency entirely
- Update all packages to Oct 2025 versions (pydantic 2.11.10, structlog 25.4.0, ruff 0.13.3, etc.)

Code:
- Simplify src/main.py to basic Hello World with structlog
- Remove OpenAI-specific settings (openai_api_key, default_model)
- Update tests to validate LOG_LEVEL and LOG_FORMAT

Tooling:
- Upgrade pre-commit ruff to v0.13.3, add linting hook
- Remove pyrightconfig.strict.json, consolidate config to pyproject.toml
- Improve Makefile clean command to remove more cache directories
- Delete .cursor/rules/general.mdc (superseded by AGENTS.md)

Documentation:
- Create comprehensive AGENTS.md with architecture principles and code style guide
- Update README.md to reflect generic Python boilerplate usage
- Update .env.example to remove OpenAI variables, fix typo

All tests pass, linting clean, type checking passes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: abpai

.cursor/rules/general.mdc

@@ -1,13 +1,9 @@
 # Copy this file to .env and uncomment/modify values as needed
 
 # =============================================================================
-# Enviroment Variables
+# Environment Variables
 # =============================================================================
 
-# Required: Your OpenAI API key for the Agents SDK to function.
-OPENAI_API_KEY=sk-...
-DEFAULT_MODEL=gpt-5-nano
-
 # Optional: The logging level for the application.
 # Options: DEBUG, INFO, WARNING, ERROR
 # Default: INFO

.env.example

@@ -12,8 +12,10 @@ repos:
       - id: check-docstring-first
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.11
+    rev: v0.13.3
     hooks:
+      - id: ruff
+        args: [--fix]
       - id: ruff-format
 
   - repo: local

.pre-commit-config.yaml

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

.python-version

@@ -1,20 +1,64 @@
-# General Rules
+# AI Agent Code Guidelines
+
+This document provides coding guidelines for AI agents working on this Python project.
 
 ## Environment and Dependencies
-- **Tooling**: Use `uv` for all package management.
+
+- **Tooling**: Use `uv` for all package management
+- **Python Version**: 3.13+
+- **Package Manager**: uv (fast, modern dependency management)
 
 ## Code Style
 
-**Format**: 2-space indent, single quotes, `snake_case` vars/functions, `PascalCase` classes, `is_/has_/should_` booleans
+**Format**: 2-space indentation, single quotes, 88-character lines, `snake_case` variables/functions, `PascalCase` classes, boolean flags prefixed with `is_/has_/should_`. Pre-commit hooks ensure code quality on commit.
+
+**Docstrings**:
+- Use simple one-line docstrings for most functions - be concise and descriptive
+- Type hints replace Args/Returns documentation - don't duplicate what's in the signature
+- No Examples section - type hints + function name should be self-explanatory
+- Exception: Top-level user-facing APIs may include brief usage notes if necessary
+- Rationale: Modern Python with PEP 484 type hints makes verbose docstrings redundant
+
+## Architecture Principles
+
+**Classes for state and lifecycle**, pure functions for transformations. Use classes when managing resources, coordinating operations, or defining interfaces.
+
+**Protocols over inheritance**: Define interfaces with `typing.Protocol` for flexible, duck-typed implementations.
+
+**Immutable configs**: Frozen dataclasses with `__post_init__` validation and factory classmethods (`from_uri()`, `from_dict()`).
+
+**Factory functions**: Standalone functions (`get_backend()`, `resolve_config()`) that map configurations to implementations.
+
+**Resource management**:
+- Reference counting for expensive resources (connections, clients) with acquire/release semantics
+- Context managers (`__enter__`/`__exit__`) for automatic cleanup
+- Track ownership with boolean flags to avoid closing borrowed resources
+
+**Streaming over bulk**: Use `Iterator[T]` to yield chunks for large datasets. Implement retry logic within generators for resilience.
+
+**Separation by lifecycle**: Split read and write operations into distinct classes, even when working with the same backend (e.g., `SessionStoreReader`, `SessionStoreWriter`).
+
+**Domain exceptions**: Create specific exception types rather than generic `RuntimeError`.
+
+**Performance**: Use `@dataclass(slots=True)` for frequently-instantiated objects and `TypeVar` for type-safe generic protocols.
+
+**Resilience**: Exponential backoff for network operations, graceful empty returns over exceptions, debug logging for key metrics.
+
+## Best Practices
 
-**Architecture**:
-- Pure functions preferred; classes for stateful operations (3+ shared params), data structures, framework requirements
 - RORO pattern: service functions receive/return single Pydantic objects
-- Single responsibility: break 150+ line functions into focused 15-25 line methods, early returns, no magic values, explicit dependencies
-- DRY principle: extract utility functions to eliminate code duplication when applicable
+- Single responsibility: break 150+ line functions into focused 15-25 line methods
+- Early returns, no magic values, explicit dependencies
+- DRY principle: extract utility functions to eliminate duplication
 - Pipeline pattern: chain transformations with clear inputs/outputs
 - No excessive error handling or low-value comments
 
+## Pydantic Commitment
+
+- All interface models use Pydantic `BaseModel` (not dataclasses)
+- Validation, `.model_dump()`, JSON serialization built-in
+- Reserve `@dataclass(slots=True)` only for inner performance-critical helpers (graph traversal caches, etc.)
+
 ## Codex Commands
 
 Conventions:

AGENTS.md

@@ -37,14 +37,17 @@ format:
 	uv run ruff format .
 
 typecheck:
-		uv run pyright -p pyrightconfig.strict.json
+		uv run pyright
 
 test: ## Run Pytest
 	uv run pytest
 
 clean: ## Remove caches & pyc files
 	find . -type f -name "*.pyc" -delete
-	find . -type d -name "__pycache__" -exec rm -rf {} +
+	find . -type d -name "pycache" -exec rm -rf {} +
+	find . -type d -name ".pytest_cache" -exec rm -rf {} +
+	find . -type d -name ".ruff_cache" -exec rm -rf {} +
+	rm -rf .pytest_cache .ruff_cache .mypy_cache .coverage
 
 lock-check: ## Ensure uv.lock is up-to-date
 	uv sync --locked --extra dev

Makefile

@@ -6,6 +6,7 @@ This template is a **lean starting point** for Python projects that use:
 - 🧪 Pytest – testing
 - ⚙️ Pydantic Settings – typed environment configuration
 - 📦 uv – fast dependency management / locking
+- 📝 structlog – structured logging
 
 ---
 
@@ -30,7 +31,7 @@ This template is a **lean starting point** for Python projects that use:
     make setup
     ```
 
-3.  **Run the Quick-Start Agent Demo:**
+3.  **Run the Application:**
 
     ```bash
     # This will use your activated environment
@@ -42,7 +43,7 @@ This template is a **lean starting point** for Python projects that use:
     make format && make lint && make test
     ```
 
-`src/main.py` is a minimal script that spins up an assistant. Modify it to explore the SDK.
+`src/main.py` is a minimal script with structured logging. Modify it to build your application.
 
 ---
 
@@ -66,12 +67,10 @@ This template is a **lean starting point** for Python projects that use:
 
 `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-5-nano` | Default model for agents.           |
+| Variable     | Default   | Description                         |
+| ------------ | --------- | ----------------------------------- |
+| `LOG_LEVEL`  | `INFO`    | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `LOG_FORMAT` | `console` | `console` (colored) or `json`.      |
 
 See `.env.example` for a template.
 
@@ -83,7 +82,7 @@ Only what you need, nothing more:
 
 ```
 ├── src/
-│   └── main.py               # Minimal OpenAI Agents example
+│   └── main.py               # Main application entry point
 ├── utils/
 │   └── settings.py           # Pydantic Settings helper
 ├── tests/
@@ -96,6 +95,19 @@ Only what you need, nothing more:
 
 ---
 
+## Optional: ML Dependencies
+
+This template includes an optional ML dependency group for data science and machine learning projects:
+
+```bash
+# Install with ML dependencies
+uv sync --extra ml
+```
+
+Includes: PyTorch, scikit-learn, MLflow, matplotlib, numpy, pandas, and seaborn.
+
+---
+
 ## License
 
 MIT

README.md

@@ -1,39 +1,38 @@
 [project]
 name = "templates.python"
-version = "0.2.0"
+version = "0.3.0"
 description = "A boilerplate for Python projects."
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.13"
 license = {text = "MIT"}
 authors = [
     {name = "Andy Pai", email = "andy@r2pi.co"},
 ]
 
 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.11.10",
+    "pydantic-settings>=2.11.0",
+    "structlog>=25.4.0",
+    "tqdm>=4.67.1",
 ]
 
 [project.optional-dependencies]
 dev = [
     "ipykernel>=6.30.1",
-    "pre-commit>=4.2.0",
-    "pyright>=1.1.405",
-    "pytest>=8.4.1",
+    "pre-commit>=4.3.0",
+    "pyright>=1.1.406",
+    "pytest>=8.4.2",
     "pytest-cov>=6.2.1",
-    "ruff>=0.12.11",
+    "ruff>=0.13.3",
 ]
 
 ml = [
   "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",
+  "matplotlib>=3.10.6",
+  "numpy>=2.3.3",
+  "pandas>=2.3.3",
   "seaborn>=0.13.2",
 ]
 
@@ -63,7 +62,7 @@ line-ending = "auto"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-python_files = ["test_*.py", "*_test.py"]
+python_files = ["test_*.py"]
 addopts = ["-ra"]
 pythonpath = ["."]
 
@@ -75,5 +74,5 @@ typeCheckingMode = "off"
 reportMissingImports = true
 reportMissingTypeStubs = false
 
-pythonVersion = "3.12"
+pythonVersion = "3.13"
 pythonPlatform = "All"