🚀 PyPI release preparation: Major improvements and fixes

✨ New Features:
- Added comprehensive test suite (35 tests, 76% coverage)
- Added 5 new templates: ProductReview, Email, Event schemas
- Added cost tracking with accurate OpenAI pricing (2024)
- Added rate limiting and caching utilities
- Added batch processing and CLI improvements

🔧 Code Quality:
- Fixed all type annotations and mypy errors
- Added proper linting configuration (ruff, black)
- Comprehensive Makefile with quality checks
- CI/CD ready with GitHub Actions workflow

📦 PyPI Setup:
- Updated pyproject.toml for PyPI publication
- Added trusted publishing configuration
- Automated release scripts and versioning
- Updated dependencies and dev tooling

🐛 Bug Fixes:
- Fixed configuration validation and error handling
- Improved extractor with retry logic and validation
- Enhanced logging and error reporting
- Fixed all import and formatting issues

This commit prepares v0.1.0 for PyPI release with professional-grade code quality.

Author: mazzasaverio

Makefile

@@ -1,7 +1,7 @@
 # Structured Output Cookbook - Makefile
 # Provides convenient commands for development and usage
 
-.PHONY: help install dev test lint format clean docker-build docker-run docker-dev
+.PHONY: help install dev test lint format clean docker-build docker-run docker-dev format-check lint-check pre-commit check quality
 
 # Default target
 help: ## Show this help message
@@ -18,7 +18,38 @@ dev: install ## Install development dependencies
 	@echo "🛠️  Installing development dependencies..."
 	uv sync --all-extras
 
-# Code Quality
+# Code Quality - Core Commands
+format: ## Format code with black and ruff
+	@echo "💄 Formatting code..."
+	uv run black src/ tests/
+	uv run ruff check --fix src/ tests/
+
+format-check: ## Check if code needs formatting
+	@echo "🔍 Checking code formatting..."
+	uv run black --check --diff src/ tests/
+	uv run ruff check src/ tests/
+
+lint: ## Run all linters
+	@echo "🔍 Running linters..."
+	uv run ruff check src/ tests/
+	uv run mypy src/ --ignore-missing-imports
+
+lint-fix: ## Fix all linting issues
+	@echo "🔧 Fixing linting issues..."
+	uv run ruff check --fix src/ tests/
+	uv run black src/ tests/
+
+# Comprehensive Quality Checks
+pre-commit: format lint ## Run all pre-commit checks (format + lint)
+	@echo "✅ Pre-commit checks completed!"
+
+check: pre-commit test ## Run all quality checks (format, lint, tests)
+	@echo "✅ All quality checks passed!"
+
+quality: clean-cache pre-commit test ## Full quality check with cache cleanup
+	@echo "✅ Full quality check completed!"
+
+# Tests
 test: ## Run tests
 	@echo "🧪 Running tests..."
 	uv run pytest
@@ -27,56 +58,45 @@ test-cov: ## Run tests with coverage
 	@echo "📊 Running tests with coverage..."
 	uv run pytest --cov=src/structured_output_cookbook --cov-report=html
 
-lint: ## Run linting
-	@echo "🔍 Running linters..."
-	uv run ruff check .
-	uv run mypy src/
-
-lint-fix: ## Fix linting issues
-	@echo "🔧 Fixing linting issues..."
-	uv run ruff --fix .
-	uv run black .
-
-format: ## Format code
-	@echo "💄 Formatting code..."
-	uv run black .
-	uv run ruff --fix .
+test-verbose: ## Run tests with verbose output
+	@echo "🧪 Running tests (verbose)..."
+	uv run pytest -v
 
-# CLI Commands
-list-templates: ## List available predefined templates
+# CLI Commands (with quality checks)
+list-templates: pre-commit ## List available predefined templates
 	@echo "📋 Available templates:"
 	uv run structured-output list-templates
 
-list-schemas: ## List available custom schemas
+list-schemas: pre-commit ## List available custom schemas
 	@echo "📋 Available schemas:"
 	uv run structured-output list-schemas
 
-example-recipe: ## Run recipe extraction example
+example-recipe: pre-commit ## Run recipe extraction example
 	@echo "🍝 Running recipe extraction example..."
 	uv run structured-output extract recipe --input-file examples/recipe.txt --pretty
 
-example-job: ## Run job description extraction example
+example-job: pre-commit ## Run job description extraction example
 	@echo "💼 Running job description extraction example..."
 	uv run structured-output extract job --input-file examples/job_description.txt --pretty
 
-example-news: ## Run news article extraction example
+example-news: pre-commit ## Run news article extraction example
 	@echo "📰 Running news article extraction example..."
 	uv run structured-output extract-custom news_article --input-file examples/news_article.txt --pretty
 
-example-email: ## Run email extraction example
+example-email: pre-commit ## Run email extraction example
 	@echo "📧 Running email extraction example..."
 	uv run structured-output extract email --text "Subject: Meeting Tomorrow\nFrom: [email protected]\nHi team, we have an important meeting tomorrow at 2 PM in conference room A. Please bring your reports." --pretty
 
-example-event: ## Run event extraction example
+example-event: pre-commit ## Run event extraction example
 	@echo "🎉 Running event extraction example..."
 	uv run structured-output extract event --text "Annual Tech Conference 2024 - Join us on March 15th at San Francisco Convention Center from 9 AM to 6 PM. Registration required." --pretty
 
-example-product-review: ## Run product review extraction example
+example-product-review: pre-commit ## Run product review extraction example
 	@echo "⭐ Running product review extraction example..."
 	uv run structured-output extract product-review --text "Amazing laptop! The new MacBook Pro is incredible. 5 stars. Great performance, excellent display. Worth every penny. Highly recommended for developers." --pretty
 
 # Docker Commands
-docker-build: ## Build Docker image
+docker-build: check ## Build Docker image
 	@echo "🐳 Building Docker image..."
 	docker build -t structured-output-cookbook:latest .
 
@@ -110,39 +130,42 @@ docker-list-templates: ## List templates with Docker
 	./scripts/docker-run.sh list-templates
 
 # New CLI Commands
-validate-schemas: ## Validate all custom YAML schemas
+validate-schemas: pre-commit ## Validate all custom YAML schemas
 	@echo "🔍 Validating schemas..."
 	uv run structured-output validate-schemas
 
-session-stats: ## Show session statistics
+session-stats: pre-commit ## Show session statistics
 	@echo "📊 Showing session statistics..."
 	uv run structured-output session-stats
 
-cost-analysis: ## Show cost analysis and recommendations
+cost-analysis: pre-commit ## Show cost analysis and recommendations
 	@echo "💰 Showing cost analysis..."
 	uv run structured-output cost-analysis
 
 # Batch processing examples
-batch-example: ## Run batch extraction example
+batch-example: pre-commit ## Run batch extraction example
 	@echo "🔄 Running batch extraction example..."
 	mkdir -p examples/batch_input examples/batch_output
 	echo "Sample recipe 1: Pasta with tomato sauce" > examples/batch_input/recipe1.txt
 	echo "Sample recipe 2: Chicken curry with rice" > examples/batch_input/recipe2.txt
 	uv run structured-output batch-extract examples/batch_input/*.txt recipe --output-dir examples/batch_output
 
 # Cleanup
-clean: ## Clean up build artifacts and cache
+clean-cache: ## Clean up cache files
+	@echo "🧹 Cleaning cache files..."
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	rm -rf .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+clean: clean-cache ## Clean up build artifacts and cache
 	@echo "🧹 Cleaning up..."
 	rm -rf build/
 	rm -rf dist/
 	rm -rf *.egg-info/
-	rm -rf .pytest_cache/
 	rm -rf .coverage
 	rm -rf htmlcov/
-	rm -rf .mypy_cache/
-	rm -rf .ruff_cache/
-	find . -type d -name __pycache__ -exec rm -rf {} +
-	find . -type f -name "*.pyc" -delete
 
 clean-all: clean clean-dist ## Clean everything including distribution files
 	@echo "🧹 Deep cleaning complete!"
@@ -177,39 +200,38 @@ check-env: ## Check if required environment variables are set
 	fi
 
 # Release Management
-bump-version: ## Bump version and create release (usage: make bump-version VERSION=0.1.0)
+bump-version: check ## Bump version and create release (usage: make bump-version VERSION=0.1.0)
 	@if [ -z "$(VERSION)" ]; then \
 		echo "❌ Please specify VERSION. Usage: make bump-version VERSION=0.1.0"; \
 		exit 1; \
 	fi
 	./scripts/release.sh $(VERSION)
 
-build-package: ## Build package for PyPI
+build-package: check ## Build package for PyPI
 	@echo "📦 Building package..."
 	uv build
 	uvx twine check dist/*
 
-test-pypi: ## Upload to Test PyPI
+test-pypi: check ## Upload to Test PyPI
 	@echo "🧪 Uploading to Test PyPI..."
 	uvx twine upload --repository testpypi dist/*
 
-upload-pypi: ## Upload to PyPI (manual backup)
+upload-pypi: check ## Upload to PyPI (manual backup)
 	@echo "📤 Uploading to PyPI..."
 	uvx twine upload dist/*
 
-check-release: ## Check if package is ready for release
+check-release: check ## Check if package is ready for release
 	@echo "🔍 Checking release readiness..."
 	uv build
 	uvx twine check dist/*
-	uv run pytest
 	@echo "✅ Package ready for release!"
 
 clean-dist: ## Clean distribution files
 	@echo "🧹 Cleaning distribution files..."
 	rm -rf dist/ build/ *.egg-info/
 
 # Release (legacy)
-build: ## Build the package
+build: check ## Build the package
 	@echo "📦 Building package..."
 	uv build
 
@@ -228,4 +250,15 @@ dev-setup: dev env-example ## Setup development environment
 	@echo "Don't forget to:"
 	@echo "1. Copy .env.example to .env and add your OpenAI API key"
 	@echo "2. Run 'make check-env' to verify setup"
-	@echo "3. Run 'make test' to run tests" 
+	@echo "3. Run 'make check' to run all quality checks"
+
+# Fix all code issues in one command
+fix: ## Fix all formatting and linting issues
+	@echo "🔧 Fixing all code issues..."
+	@echo "Step 1: Formatting with black..."
+	uv run black src/ tests/
+	@echo "Step 2: Fixing linting issues with ruff..."
+	uv run ruff check --fix src/ tests/
+	@echo "Step 3: Running tests to verify..."
+	uv run pytest
+	@echo "✅ All issues fixed!" 

pyproject.toml

@@ -96,6 +96,7 @@ dev-dependencies = [
     "pandas>=2.0.0",
     "seaborn>=0.12.0",
     "plotly>=5.15.0",
+    "types-pyyaml>=6.0.12.20250516",
 ]
 
 [tool.black]
@@ -115,6 +116,7 @@ ignore = [
     "ANN001",   # missing type annotation for function argument (tests)
     "ANN201",   # missing return type annotation for public function
     "ANN204",   # missing return type annotation for special method
+    "ANN401",   # dynamically typed expressions (typing.Any) disallowed
     "SLF001",   # private member access (needed for testing)
     "G004",     # logging statement uses f-string (acceptable)
     "TRY400",   # use logging.exception instead of logging.error
@@ -174,4 +176,4 @@ exclude_lines = [
     "raise AssertionError",
     "raise NotImplementedError",
     "if __name__ == .__main__.:",
-]
+]

src/structured_output_cookbook/__init__.py

@@ -8,28 +8,28 @@
 )
 __url__ = "https://github.com/mazzasaverio/structured-output-cookbook"
 
+from .config import Config
 from .extractor import StructuredExtractor
 from .schemas.base import BaseSchema, ExtractionResult
-from .utils import SchemaLoader, YamlSchema, setup_minimal_logger
-from .templates.job_description import JobDescriptionSchema
-from .templates.recipe import RecipeSchema
-from .templates.product_review import ProductReviewSchema
 from .templates.email import EmailSchema
 from .templates.event import EventSchema
-from .config import Config
+from .templates.job_description import JobDescriptionSchema
+from .templates.product_review import ProductReviewSchema
+from .templates.recipe import RecipeSchema
+from .utils import SchemaLoader, YamlSchema, setup_minimal_logger
 
 __all__ = [
-    "StructuredExtractor",
     "BaseSchema",
+    "Config",
+    "EmailSchema",
+    "EventSchema",
     "ExtractionResult",
-    "SchemaLoader",
-    "YamlSchema",
-    "setup_minimal_logger",
     "JobDescriptionSchema",
-    "RecipeSchema",
     "ProductReviewSchema",
-    "EmailSchema",
-    "EventSchema",
-    "Config",
+    "RecipeSchema",
+    "SchemaLoader",
+    "StructuredExtractor",
+    "YamlSchema",
     "__version__",
+    "setup_minimal_logger",
 ]