Tutorial map (9 sections, one post)

For each section: understand why it matters, learn the core pattern, complete the exercise, then apply enterprise habits.

Recommended project structure while learning:

ai-pr-reviewer/
├── .venv/
├── pyproject.toml
├── src/
│   └── pr_reviewer/
│       ├── __init__.py
│       ├── main.py
│       ├── api/
│       ├── services/
│       ├── models/
│       └── utils/
└── tests/

Section 1: Virtual environments

Partition: environment isolation

Why it matters

Production teams never install packages globally. Isolated environments prevent dependency conflicts between projects—and between your laptop and CI.

Core commands

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

python -m pip install --upgrade pip

Enterprise habits

• One virtual environment per repository
• Never commit .venv/
• Always document Python version (e.g. 3.11)
• CI should recreate the same environment every run

Exercise

Create a new repo, initialize .venv, and verify python points inside .venv and pip list works.

Section 2: Dependency management

Partition: reproducible builds

Why it matters

AI projects depend on many libraries: FastAPI, httpx, pydantic, LLM SDKs, observability clients, etc. Without strict dependency control, “works on my machine” becomes normal.

Modern approach: pyproject.toml

[project]
name = "pr-reviewer"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "fastapi>=0.115.0",
  "httpx>=0.27.0",
  "pydantic>=2.8.0",
]

[project.optional-dependencies]
dev = [
  "pytest>=8.0.0",
  "ruff>=0.6.0",
  "mypy>=1.11.0",
]

Install:

pip install -e ".[dev]"

Enterprise habits

• Pin versions for production deployments
• Separate runtime vs dev dependencies
• Use a lock file strategy (pip-tools, uv, or Poetry—pick one per team)
• Scan dependencies for vulnerabilities in CI

Exercise

Add three dependencies and one dev dependency. Break the build intentionally (wrong version), then fix it.

Section 3: Modular architecture

Partition: scalable code organization

Why it matters

AI systems start small and explode in complexity: ingestion, retrieval, evaluators, orchestrators, APIs. One-file scripts do not scale.

Recommended layering

api/        → HTTP routes, request/response mapping
services/   → business logic, orchestration
models/     → typed schemas (Pydantic)
clients/    → external API integrations (LLM, GitHub, Jira)
utils/      → shared helpers

Example

# src/pr_reviewer/services/review_service.py
from pr_reviewer.models.review import ReviewRequest, ReviewResult
from pr_reviewer.clients.llm_client import LLMClient

class ReviewService:
    def __init__(self, llm_client: LLMClient) -> None:
        self._llm_client = llm_client

    async def review_pr(self, request: ReviewRequest) -> ReviewResult:
        context = self._build_context(request)
        response = await self._llm_client.generate(context)
        return ReviewResult.from_llm(response)

Enterprise habits

• Single responsibility per module
• No business logic inside route handlers
• Inject dependencies (constructor injection)
• Keep side effects at boundaries (DB, network, filesystem)

Exercise

Refactor a 200-line script into api, services, and clients.

Section 4: Classes

Partition: behavior and lifecycle

Why it matters

Classes encapsulate stateful workflows—review pipelines, agent runners, memory managers—without global variables.

Example

class DiffAnalyzer:
    def __init__(self, max_files: int = 50) -> None:
        self._max_files = max_files

    def extract_changed_modules(self, diff_text: str) -> list[str]:
        modules = self._parse(diff_text)
        return modules[: self._max_files]

    def _parse(self, diff_text: str) -> list[str]:
        ...

Enterprise habits

• Prefer composition over inheritance
• Keep methods small and testable
• Use @dataclass or Pydantic for pure data
• Use classes for behavior + lifecycle

Exercise

Create ReviewService, DiffAnalyzer, and ConfidenceScorer as separate classes.

Section 5: Typing

Partition: explicit contracts

Why it matters

AI systems pass complex structures everywhere. Typing makes contracts explicit and reduces silent failures.

Core patterns

from collections.abc import AsyncIterator

UserId = str

def normalize_paths(paths: list[str]) -> list[str]:
    return [p.strip() for p in paths if p]

async def stream_tokens(prompt: str) -> AsyncIterator[str]:
    ...

Pydantic at API boundaries

from pydantic import BaseModel, Field

class ReviewRequest(BaseModel):
    repo: str
    pr_number: int = Field(gt=0)
    diff: str

class ReviewResult(BaseModel):
    summary: str
    risk_score: float = Field(ge=0.0, le=1.0)

Enterprise habits

• Type all public functions
• Run mypy or pyright in CI
• Avoid Any unless truly necessary
• Prefer list[str] over List[str] (Python 3.9+)

Exercise

Add type hints to one service module and enforce with mypy.

Section 6: Decorators

Partition: cross-cutting concerns

Why it matters

Decorators add logging, retries, timing, auth, and rate limits without duplicating boilerplate.

Example

import functools
import time
import logging

logger = logging.getLogger(__name__)

def log_duration(func):
    @functools.wraps(func)
    async def wrapper(*args, **kwargs):
        start = time.perf_counter()
        try:
            return await func(*args, **kwargs)
        finally:
            elapsed = time.perf_counter() - start
            logger.info("%s finished in %.3fs", func.__name__, elapsed)
    return wrapper

Enterprise habits

• Always use functools.wraps
• Keep decorators thin; move heavy logic to utilities
• Document side effects clearly

Exercise

Build @retry_on_transient_error(max_attempts=3) for API calls.

Section 7: Generators

Partition: efficient data processing

Why it matters

PR diffs, logs, and model streams can be large. Generators process data lazily instead of loading everything into memory.

Sync generator

from collections.abc import Iterator

def chunk_text(text: str, size: int = 4000) -> Iterator[str]:
    for i in range(0, len(text), size):
        yield text[i : i + size]

Async generator (streaming)

from collections.abc import AsyncIterator

async def stream_llm_output(prompt: str) -> AsyncIterator[str]:
    async for token in llm_client.stream(prompt):
        yield token

Enterprise habits

• Use generators for file/log iteration
• Use async generators for token streaming endpoints
• Avoid materializing huge lists when not needed

Exercise

Implement chunked diff processing and send each chunk to an evaluator.

Section 8: Exception handling

Partition: reliable failure behavior

Why it matters

AI workflows fail often: rate limits, timeouts, malformed output, upstream outages. Poor handling creates hidden bugs.

Domain-specific exceptions

class ReviewError(Exception):
    """Base error for review pipeline."""

class LLMTimeoutError(ReviewError):
    pass

class InvalidModelOutputError(ReviewError):
    pass

Controlled handling

async def review_pr(request: ReviewRequest) -> ReviewResult:
    try:
        return await _review_internal(request)
    except LLMTimeoutError as exc:
        logger.warning("LLM timeout for PR %s: %s", request.pr_number, exc)
        raise
    except InvalidModelOutputError:
        logger.exception("Model output validation failed")
        return ReviewResult(summary="Review unavailable", risk_score=0.0)

Enterprise habits

• Catch specific exceptions, not bare except Exception
• Never swallow errors without logging
• Return structured error responses at API boundaries
• Add correlation IDs for traceability

Exercise

Define 3 custom exceptions and map each to a clear API response.

Section 9: Async/await

Partition: concurrent I/O for AI backends

Why it matters

AI systems are I/O heavy: multiple API calls, concurrent evaluators, streaming, background jobs. Blocking code becomes a bottleneck under load.

Basic async call

import httpx

async def fetch_pr_metadata(repo: str, pr_number: int) -> dict:
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(f"https://api.example.com/{repo}/pulls/{pr_number}")
        response.raise_for_status()
        return response.json()

Concurrent tasks

import asyncio

async def run_parallel_evaluators(diff: str) -> list[dict]:
    tasks = [
        security_evaluator.run(diff),
        quality_evaluator.run(diff),
        test_impact_evaluator.run(diff),
    ]
    return await asyncio.gather(*tasks)

Common mistakes

• blocking libraries inside async routes without offload
• new AsyncClient per request (reuse where possible)
• missing timeouts and retries
• unclear sync/async boundaries

Enterprise habits

• set timeouts everywhere
• limit concurrency (semaphores)
• instrument latency per step
• structured logging around each await

Exercise

Build an endpoint that fetches PR metadata, diff, and policy rules concurrently.

Wrap-up: production checklist (all sections)

• Section 1: isolated .venv
• Section 2: reproducible dependencies
• Section 3: modular api/services/models/clients
• Section 4: focused classes with clear responsibilities
• Section 5: typed interfaces (mypy passing)
• Section 6: decorators for retries/logging/timing
• Section 7: generators for large/streaming data
• Section 8: exception hierarchy + safe API fallbacks
• Section 9: async orchestration with timeouts and limits

Suggested 2-week plan

Week 1: Sections 1–5 (env → architecture → typing)
Week 2: Sections 6–9 (decorators → async), then one integrated FastAPI endpoint

Final thought

Coming from automation testing, these skills map cleanly: CI discipline → dependencies, framework structure → modules, test design → types and exceptions, parallel runs → async.

In AI engineering, the model is probabilistic—so your Python foundation must be deterministic and strong. That is why I am learning all nine areas as separate sections inside one production-focused tutorial, then implementing each in my AI PR Reviewer backend.