✨ Add example applications for FastAPI, Starlette, and LLM integration patterns

Problem or Use Case

Users need practical, runnable example applications demonstrating how to integrate zae-limiter with popular web frameworks and LLM APIs. While basic code snippets exist in the examples/ folder, comprehensive example applications showing real-world patterns are missing:

• FastAPI: REST API with rate limiting middleware, dependencies, and decorators
• Starlette: Lightweight ASGI middleware integration for broader framework compatibility
• LLM Integration: Complete examples showing token estimation, streaming reconciliation, and provider-specific patterns (OpenAI, Anthropic)

Proposed Solution

Expand the examples/ directory with self-contained, runnable applications:

1. FastAPI Example (examples/fastapi-app/)

Complete REST API demonstrating:

• Global rate limiting middleware
• Route-specific limits via decorators
• Entity extraction from JWT/API keys
• Proper 429 response formatting with Retry-After
• Health check endpoints
• Swagger UI integration

2. Starlette Example (examples/starlette-app/)

Lightweight ASGI middleware showing:

• Pure Starlette rate limiting (no FastAPI dependency)
• Custom middleware implementation
• Works with any ASGI framework (Starlette, FastAPI, Quart)

3. LLM Integration Examples (examples/llm-patterns/)

Provider-specific patterns:

• OpenAI: Streaming with tiktoken estimation, function calling token accounting
• Anthropic: Claude API with prompt caching token handling
• Generic: Abstract patterns for any LLM with unknown upfront cost

Each example should:

• Be runnable with uvicorn or similar
• Work with LocalStack out of the box
• Include a README.md with setup instructions
• Have a docker-compose.yml for easy startup

Acceptance Criteria

• examples/fastapi-app/ exists with main.py, README.md, and docker-compose.yml
• FastAPI example demonstrates middleware, decorator, and dependency injection patterns
• examples/starlette-app/ exists with main.py, README.md, and docker-compose.yml
• Starlette example demonstrates pure ASGI middleware without FastAPI
• examples/llm-patterns/ exists with provider-specific subdirectories
• OpenAI example at examples/llm-patterns/openai/ demonstrates streaming token reconciliation
• Anthropic example at examples/llm-patterns/anthropic/ demonstrates prompt caching token handling
• All examples include inline comments explaining key integration points
• All examples tested with LocalStack and documented setup steps
• Each example has a pyproject.toml or requirements.txt for dependencies

Alternatives Considered

1. Add to existing fastapi-demo/: Rejected because the existing demo is already complex; separate focused examples are clearer for learning.

2. Documentation-only examples: Rejected because runnable code provides better developer experience than copy-paste snippets.

3. Single monolithic example: Rejected because separate examples allow users to pick the pattern most relevant to their use case.

Related

• #256 - FastAPI integration with decorator and dependency injection support (core library feature)
• #257 - WebSocket rate limiting support for streaming scenarios
• #164 - Document existing examples folder
• #163 - zae-limiter demo command for zero-friction exploration

Start by reading the existing examples/ directory and the related issues #256, #257, #164, and #163 to understand current integration and documentation patterns. Define the FastAPI, Starlette, and LLM example entry points from the stated acceptance criteria, then verify each application, dependency file, README, and docker-compose setup runs as documented with LocalStack.