Python: added poe setup and docs (#131)

* added poe setup and docs

* smaller bandit exclude

* updated poe

* updated naming

* added something in samples

* exclude docs from bandit

* updated readme

* removed ds_store

* updated readme

python/README.md

@@ -1,8 +1,159 @@
 # Python
 
-## Checks
+This project uses [poethepoet](https://github.com/nat-n/poethepoet) for task management and [uv](https://github.com/astral-sh/uv) for dependency management.
 
-Run all checks using pre-commit:
+## Available Poe Tasks
+
+### Setup and Installation
+
+Once uv is installed, and you do not yet have a virtual environment setup:
+
+```bash
+uv venv
+```
+
+and then you can run the following tasks:
+```bash
+uv sync --all-extras --dev
+```
+
+After this initial setup, you can use the following tasks to manage your development environment, it is adviced to use the following setup command since that also installs the pre-commit hooks.
+
+#### `setup`
+Set up the development environment with a virtual environment, install dependencies and pre-commit hooks:
+```bash
+uv run poe setup
+# or with specific Python version
+uv run poe setup --python 3.12
+```
+
+#### `install`
+Install all dependencies including extras and dev dependencies, including updates:
+```bash
+uv run poe install
+```
+
+#### `venv`
+Create a virtual environment with specified Python version or switch python version:
+```bash
+uv run poe venv
+# or with specific Python version
+uv run poe venv --python 3.12
+```
+
+#### `pre-commit-install`
+Install pre-commit hooks:
+```bash
+uv run poe pre-commit-install
+```
+
+### Code Quality and Formatting
+
+Each of the following tasks are designed to run against both the main `agent-framework` package and the extension packages, ensuring consistent code quality across the project.
+
+#### `fmt` (format)
+Format code using ruff:
+```bash
+uv run poe fmt
+```
+
+#### `lint`
+Run linting checks and fix issues:
+```bash
+uv run poe lint
+```
+
+#### `pyright`
+Run Pyright type checking:
+```bash
+uv run poe pyright
+```
+
+#### `mypy`
+Run MyPy type checking:
+```bash
+uv run poe mypy
+```
+
+### Testing
+
+#### `test`
+Run unit tests with coverage:
+```bash
+uv run poe test
+```
+
+### Documentation
+
+#### `docs-clean`
+Remove the docs build directory:
+```bash
+uv run poe docs-clean
+```
+
+#### `docs-build`
+Build the documentation:
+```bash
+uv run poe docs-build
+```
+
+#### `docs-serve`
+Serve documentation locally with auto-reload:
+```bash
+uv run poe docs-serve
+```
+
+#### `docs-check`
+Build documentation and fail on warnings:
+```bash
+uv run poe docs-check
+```
+
+#### `docs-check-examples`
+Check documentation examples for code correctness:
+```bash
+uv run poe docs-check-examples
+```
+
+### Code Validation
+
+#### `markdown-code-lint`
+Lint markdown code blocks:
+```bash
+uv run poe markdown-code-lint
+```
+
+#### `samples-code-check`
+Run type checking on samples:
+```bash
+uv run poe samples-code-check
+```
+
+### Comprehensive Checks
+
+#### `check`
+Run all quality checks (format, lint, pyright, mypy, test, markdown lint, samples check):
+```bash
+uv run poe check
+```
+
+#### `pre-commit-check`
+Run pre-commit specific checks (all of the above, excluding `mypy`):
+```bash
+uv run poe pre-commit-check
+```
+
+### Building
+
+#### `build`
+Build the package:
+```bash
+uv run poe build
+```
+
+## Pre-commit Hooks
+
+You can also run all checks using pre-commit directly:
 
 ```bash
 uv run pre-commit run -a