feat(filters): add RelationshipFilter for relationship-based queries

[cofin]

Summary

Adds RelationshipFilter class enabling efficient filtering across SQLAlchemy relationships using EXISTS subqueries. This addresses:

• Issue Enhancement: Add StatementFilters for relationships & association object patterns #364: Add StatementFilters for relationships & association object patterns
• Issue MultiFilter with Many-to-Many relationships #505: Fix MultiFilter with Many-to-Many generating incorrect SQL

Features

• Support for one-to-many, many-to-one, many-to-many relationships
• Nested relationship filtering (3+ levels)
• negate parameter for NOT EXISTS queries
• CollectionFilter auto-detection of relationship attributes
• MultiFilter JSON API integration

Example Usage

# Filter orders by customer country (one-to-many)
RelationshipFilter(
    relationship="customer",
    filters=[CollectionFilter("country", ["USA", "Canada"])]
)

# Filter users by tags (many-to-many)
RelationshipFilter(
    relationship="tags",
    filters=[CollectionFilter("name", ["admin", "moderator"])]
)

# Nested filtering (Order -> Customer -> Tier)
RelationshipFilter(
    relationship="customer",
    filters=[
        RelationshipFilter(
            relationship="tier",
            filters=[ComparisonFilter("level", "ge", 3)]
        )
    ]
)

Test plan

• Unit tests for RelationshipFilter class
• Many-to-many relationship tests
• Many-to-one relationship tests
• Negative filtering (NOT EXISTS) tests
• MultiFilter JSON API integration tests
• Type checking passes (mypy, pyright)
• Linting passes (ruff)

Closes #364
Closes #505

[codecov-commenter]

Codecov Report

❌ Patch coverage is 79.52756% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.31%. Comparing base (ba77b1e) to head (f09cae2).

Files with missing lines	Patch %	Lines
advanced_alchemy/filters.py	79.52%	16 Missing and 10 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #639      +/-   ##
==========================================
- Coverage   80.34%   80.31%   -0.03%     
==========================================
  Files          87       87              
  Lines        6431     6534     +103     
  Branches      838      859      +21     
==========================================
+ Hits         5167     5248      +81     
- Misses       1000     1016      +16     
- Partials      264      270       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.