refactor: migrate to Python 3.13 and enhance type safety

.python-version

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

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "python.languageServer": "None",
+  "windsurfPyright.analysis.typeCheckingMode": "basedpyright",
+  "editor.defaultFormatter": "Codeium.windsurfPyright",
+  "windsurfPyright.analysis.autoSearchPaths": true,
+  "windsurfPyright.analysis.useLibraryCodeForTypes": true,
+  "python.terminal.shellIntegration.enabled": true,
+  "windsurfPyright.analysis.inlayHints.callArgumentNames": false,
+  "windsurfPyright.analysis.inlayHints.functionReturnTypes": false,
+  "windsurfPyright.analysis.inlayHints.genericTypes": false,
+  "windsurfPyright.analysis.inlayHints.variableTypes": false,
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  }
+}

.windsurf/rules/python-guidelines.md

@@ -0,0 +1,59 @@
+---
+trigger: glob
+globs: **/*.py, src/**/*.py, tests/**/*.py
+---
+
+# Python Best Practices
+
+## Project Structure
+
+- Use src-layout with `src/your_package_name/`
+- Place tests in `tests/` directory parallel to `src/`
+- Keep configuration in `config/`
+- Store requirements in `pyproject.toml`
+- Place static files in `static/` directory
+- Use `templates/` for Jinja2 templates
+
+## Code Style
+
+- Follow Black code formatting
+- Use isort for import sorting
+- Follow PEP 8 naming conventions:
+  - snake_case for functions and variables
+  - PascalCase for classes
+  - UPPER_CASE for constants
+- Maximum line length of 88 characters (Black default)
+- Use absolute imports over relative imports
+
+## Type Hints
+
+- Use type hints for all function parameters and returns
+- Import types from `typing` module
+- Use `Optional[Type]` instead of `Type | None`
+- Define custom types in `types.py`
+- Use `Protocol` for duck typing
+
+## Documentation
+
+- Use Google-style docstrings
+- Document all public APIs
+- Use proper inline comments
+- Generate API documentation
+- Document environment setup
+
+## Development Workflow
+
+- Use virtual environments (venv)
+- Implement pre-commit hooks
+- Use proper Git workflow
+- Follow semantic versioning
+- Use proper CI/CD practices
+- Implement proper logging
+
+## Dependencies
+
+- Pin dependency versions
+- Separate dev dependencies
+- Use proper package versions
+- Regularly update dependencies
+- Check for security vulnerabilities

.windsurfrules

@@ -0,0 +1,92 @@
+# Robofactor Quick-Start
+
+## 1. Write Pure Functions Whenever Possible
+
+- **No side effects** → wrap I/O in `IO[T]` or `IOResult[T, E]`
+- **No mutation** → return new values
+- **No exceptions** → return `Result[T, E]` or `Maybe[T]`
+
+Push all side effects to CLI entrypoint.
+
+## 2. Type System (PEP 695)
+
+```python
+type UserId = int
+type Result[T, E] = Success[T] | Failure[E]
+
+@dataclass(frozen=True, slots=True)
+class User: ...
+```
+
+## 3. Function Rules
+
+- ≤ 20 lines, ≤ 4 params
+- Keyword-only after `*`
+- Use `flow` to compose:
+
+```python
+from returns.pipeline import flow
+from returns.pointfree import bind
+
+result = flow(
+    data,
+    validate,
+    bind(process),
+    bind(save),
+)
+```
+
+## 4. CLI (Typer)
+
+```python
+def cmd(
+    file: Annotated[Path, typer.Argument()],
+    out: Annotated[str, typer.Option("-o")] = "out.txt",
+) -> None:
+    ...
+```
+
+- Defaults live in the signature, **not** in `typer.Option`.
+- Use `rich` for output, `typer.Exit(code)` to quit.
+
+## 5. Error Handling
+
+```python
+def parse_int(s: str) -> Result[int, ValueError]:
+    try:
+        return Success(int(s))
+    except ValueError as e:
+        return Failure(e)
+
+match parse_int("42"):
+    case Success(n): ...
+    case Failure(e): ...
+```
+
+## 6. Testing
+
+- **pytest + hypothesis**
+- One assertion per test
+- Property tests for pure functions
+
+## 7. Tooling
+
+```bash
+uv run basedpyright --pythonversion 3.13
+uv run ruff check
+uv run ruff format
+```
+
+## 8. Forbidden
+
+- `Any`, `cast`, `# type: ignore`, `Optional`, `print`, `sys.exit`, mutable globals, `list`/`dict` in signatures.
+
+## 9. Project Skeleton
+
+```bash
+src/
+  robofactor/  # project source
+tests/
+  test_*.py    # property tests
+pyproject.toml # uv + ruff + basedpyright
+```

Makefile

@@ -1,18 +1,16 @@
-.PHONY: help install install-dev clean test test-unit test-integration lint format type-check check build docs serve-docs readme
+.PHONY: help install install-dev clean test lint format type-check check readme
 
 # Default target
 help:
 	@echo "Available commands:"
 	@echo "  install       Install the package in production mode"
-	@echo "  install-dev   Install the package in development mode"
+	@echo "  install-dev   Install the package in development mode with all groups"
 	@echo "  clean         Remove build artifacts and caches"
-	@echo "  test          Run all tests"
-	@echo "  test-unit     Run unit tests only"
-	@echo "  test-integration Run integration tests only"
-	@echo "  lint          Run linting checks"
-	@echo "  format        Format code with black and isort"
-	@echo "  type-check    Run mypy type checking"
-	@echo "  check         Run all checks (lint, type-check, test)"
+	@echo "  test          Run all tests with pytest"
+	@echo "  lint          Run ruff linting checks with auto-fix"
+	@echo "  format        Format code with ruff"
+	@echo "  type-check    Run basedpyright type checking"
+	@echo "  check         Run all checks (type-check, lint, test)"
 	@echo "  readme        Generate README.md using DSPy"
 
 # Installation targets
@@ -22,34 +20,36 @@ install:
 install-dev:
 	uv sync --all-groups
 
+# Cleaning
+clean:
+	rm -rf build dist .eggs *.egg-info
+	rm -rf .pytest_cache .ruff_cache .mypy_cache
+	rm -rf htmlcov .coverage coverage.xml
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	find . -type f -name "*.pyo" -delete
+
 # Testing
 test:
-	uv run pytest
-
-test-unit:
-	uv run pytest tests/unit
-
-test-integration:
-	uv run pytest tests/integration
-
-test-coverage:
-	uv run pytest --cov-report=html
-	@echo "Coverage report generated in htmlcov/index.html"
+	@if [ -n "$$(find tests -name '*.py' 2>/dev/null)" ]; then \
+		uv run pytest; \
+	else \
+		echo "No tests found in tests directory"; \
+	fi
 
 # Code quality
 lint:
 	uv run ruff check src tests --fix
 
 format:
 	uv run ruff format src tests
-	uv run isort src tests
 
 type-check:
-	uv run mypy src
+	uv run basedpyright --pythonversion 3.13 src
 
 # Combined checks
-check: lint type-check test
+check: type-check lint test
 
 # Documentation
 readme:
-	uv run scripts/generate_readme.py
+	uv run python scripts/generate_readme.py