Feat/integration examples

[LifeJiggy]

Summary

This PR adds comprehensive integration examples showing how to use the Gradient SDK with popular Python web frameworks (FastAPI, Flask, Django), providing production-ready patterns for building AI-powered applications.

Problem

Developers need clear examples of how to integrate Gradient SDK into real-world applications, but existing documentation lacks comprehensive framework-specific integration guides. This creates barriers for developers wanting to build AI-powered web applications.

Solution

Add complete integration examples for three major Python web frameworks:

FastAPI Integration

• REST API endpoints for all Gradient SDK features
• Streaming responses with Server-Sent Events
• Pydantic models for request/response validation
• Automatic API documentation generation
• Pagination support for large datasets

Flask Integration

• RESTful endpoints with proper error handling
• Response caching (5-minute TTL)
• Rate limiting (60 requests/minute)
• Streaming responses for real-time chat
• Comprehensive logging and monitoring

Django Integration

• Django view functions following framework patterns
• URL configuration examples
• StreamingHttpResponse for real-time features
• Django JSON encoder compatibility
• Settings-based configuration

Key Features Demonstrated

Core Gradient SDK Features

• Chat completions with streaming support
• Image generation
• Agent interactions
• Model management and listing

Advanced Utilities

• Pagination for large datasets
• Response caching to reduce API calls
• Rate limiting to prevent quota exhaustion
• Error handling and logging
• Request/response validation

Production Patterns

• Environment variable management
• Health check endpoints
• Usage statistics and monitoring
• Proper HTTP status codes
• Request validation and sanitization

Benefits

• Accelerates Development: Ready-to-use integration patterns
• Framework Familiarity: Examples in developers' preferred frameworks
• Production Ready: Includes error handling, caching, rate limiting
• Comprehensive Coverage: All major Gradient SDK features demonstrated
• Educational Value: Clear documentation and best practices

Documentation

Includes comprehensive README with:

• Setup instructions for each framework
• Environment variable configuration
• API endpoint documentation
• Best practices and security considerations
• Troubleshooting guide

Usage Examples

FastAPI

from fastapi import FastAPI
from gradient import Gradient

app = FastAPI()
client = Gradient(access_token="token", model_access_key="key")

@app.post("/chat")
async def chat(request: ChatRequest):
    response = client.chat.completions.create(
        messages=[{"role": "user", "content": request.message}],
        model=request.model
    )
    return {"response": response.choices[0].message.content}


#### Flask
from flask import Flask, request, jsonify
from gradient import Gradient
from gradient._utils import ResponseCache, RateLimiter

app = Flask(__name__)
client = Gradient(access_token="token", model_access_key="key")
cache = ResponseCache(ttl_seconds=300)
rate_limiter = RateLimiter(requests_per_minute=60)

@app.route("/chat", methods=["POST"])
def chat():
    if not rate_limiter.allow_request():
        return jsonify({"error": "Rate limit exceeded"}), 429
    
    data = request.get_json()
    # ... implementation

### Django

from django.http import JsonResponse
from gradient import Gradient

client = Gradient(access_token="token", model_access_key="key")

def chat_completion(request):
    if request.method == "POST":
        data = json.loads(request.body)
        response = client.chat.completions.create(
            messages=[{"role": "user", "content": data["message"]}],
            model=data.get("model", "llama3.3-70b-instruct")
        )
        return JsonResponse({
            "response": response.choices[0].message.content
        })