Add honest baseline validation for examples

[josephsenior]

What changed

• adds CI on Python 3.10 and 3.12
• validates that all 21 documented patterns have a README, dependency manifest, and Python implementation
• compiles every example to catch syntax errors
• adds the missing root .env.example
• documents the repository as educational references rather than production-ready systems
• updates the quick start to use the actual environment template

Why

The repository promised 21 runnable examples but had no automated validation and instructed users to copy an environment template that did not exist. This establishes a credential-free baseline without pretending external LLM calls are tested end to end.

Validation

• python scripts/validate_repository.py
• python -m compileall across all 21 pattern directories
• git diff --check

Summary by Sourcery

Add automated validation and CI to ensure all documented LLM pattern examples meet a minimal runnable contract and compile under supported Python versions.

New Features:

• Introduce a repository validation script that checks each documented pattern for required files and a Python implementation.
• Add a root .env.example template to support consistent environment setup.

Enhancements:

• Clarify project status in the README as educational reference implementations with syntax-level CI rather than full end-to-end testing.
• Update quick start instructions to use the root environment template instead of per-pattern copies.

CI:

• Add a GitHub Actions CI workflow that runs repository validation and compiles all pattern examples on Python 3.10 and 3.12.
• Expose CI status and updated Python version support via badges in the README.

[sourcery-ai]

Reviewer's Guide

Establishes automated validation and CI to ensure all 21 documented pattern examples meet a minimal structural contract and compile under Python 3.10 and 3.12, while aligning documentation and quick start instructions with the new baseline.

Sequence diagram for CI validation and example compilation

sequenceDiagram
    actor Developer
    participant GitHubActions
    participant validate_repository_py as validate_repository.py
    participant compileall as python_compileall

    Developer->>GitHubActions: push or pull_request to master
    GitHubActions->>GitHubActions: actions/checkout@v4
    GitHubActions->>GitHubActions: actions/setup-python@v5 (3.10, 3.12)
    GitHubActions->>validate_repository_py: python scripts/validate_repository.py
    validate_repository_py->>validate_repository_py: validate_pattern(root, name)
    validate_repository_py-->>GitHubActions: exit_code (0 or 1)
    GitHubActions->>compileall: python -m compileall pattern_directories
    compileall-->>GitHubActions: syntax_check_result
    GitHubActions-->>Developer: CI status badge update

Loading

File-Level Changes

Change	Details	Files
Introduce a repository validation script that enforces a minimal contract for each documented pattern and the root environment template.	Define a fixed list of 21 pattern directories and validate each for existence, README, requirements manifest, and at least one Python file. Add a check that the validator itself enumerates exactly 21 patterns to stay in sync with documentation promises. Require the presence of a root .env.example file and fail validation if it is missing. Provide a main entry point that aggregates errors, prints a structured failure report, and exits with a non-zero status when validation fails.	scripts/validate_repository.py
Add GitHub Actions CI to run structural validation and compilation of all examples across supported Python versions.	Create a CI workflow triggered on pushes and pull requests to the master branch. Run the workflow on ubuntu-latest with a matrix over Python 3.10 and 3.12. Install the selected Python version using actions/setup-python and then execute the repository validation script. Compile all pattern example directories with python -m compileall to catch syntax errors without executing the examples.	.github/workflows/ci.yml
Align top-level documentation with the new validation baseline and simplify quick start instructions to use a single environment template.	Replace the old Python 3.8+ badge with a CI status badge and a Python 3.10+ badge to reflect tested versions. Clarify project status as educational reference implementations with CI limited to structure and syntax, not end-to-end external API calls. Update quick start instructions to copy the root .env.example once after cloning instead of per-pattern copies. Remove the per-pattern .env copy instruction from the example run snippet to avoid redundant or incorrect guidance.	README.md
Provide a root environment template used by the quick start and enforced by validation.	Add a new .env.example file at the repository root to serve as a shared environment configuration template for all patterns. Make this file a required artifact via the validation script so future changes cannot remove it silently.	.env.example

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[sourcery-ai]

Hey - I've left some high level feedback:

• The list of pattern directories is hard-coded both in PATTERN_DIRECTORIES and in the compileall command; consider deriving a single source of truth (e.g., from PATTERN_DIRECTORIES or the README) to avoid drift when patterns are added or renamed.
• The validation script enforces exactly 21 patterns via a magic number; if the set of patterns is expected to evolve, it may be clearer to assert against a derived count (e.g., from a patterns table in the README) rather than a literal constant.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The list of pattern directories is hard-coded both in `PATTERN_DIRECTORIES` and in the `compileall` command; consider deriving a single source of truth (e.g., from `PATTERN_DIRECTORIES` or the README) to avoid drift when patterns are added or renamed.
- The validation script enforces exactly 21 patterns via a magic number; if the set of patterns is expected to evolve, it may be clearer to assert against a derived count (e.g., from a patterns table in the README) rather than a literal constant.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}