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
        })

[bbatha]

Independently this is a useful pr however you are including features we do not want such as the key validator and the cli. Please remove those unrelated additions and I will review the examples.

[LifeJiggy]

Thanks again for the quick feedback, @bbatha! 🙌
Totally agree—the key validator and CLI have no place here.
I’ll strip them out completely so this PR contains only the updated examples and nothing else.
Will push the clean version within the next 24–48 hours.
Really looking forward to your thoughts on the examples once they’re isolated!

[LifeJiggy]

PR FIXED: Simple Framework Integration Examples

Hi @bbatha! 👋

I've now completely cleaned it up:

• Removed all unwanted features - CLI tool, Streamlit/Gradio apps completely removed
• Only framework integration examples remain - Django, Flask, FastAPI
• Simple, focused examples - 290 lines total instead of 3,492
• Shows basic SDK usage with web frameworks
• Comprehensive tests included (9 tests)

PR Stats (Now Perfectly Clean):

• 5 files changed
• 744 lines added (no deletions)
• 100% focused on web framework SDK integration
• No CLI, no heavy UIs, no utilities

Current PR Contains Only:

• Django Integration - Simple views for chat completions, image generation, agent listing
• Flask Integration - Flask routes with proper error handling
• FastAPI Integration - FastAPI endpoints with Pydantic models
• Simple README - Basic setup and usage instructions
• Test Suite - 9 tests to verify example integrity

Examples Benefits:

• Production-ready code with error handling
• Best practices for each framework integration
• Simple and focused - exactly what you requested
• Easy to understand and modify
• Real-world usage patterns developers can immediately use

Usage Examples:

# Django
python manage.py runserver

# Flask  
python flask_integration.py

# FastAPI
python fastapi_integration.py

This PR now contains ONLY the simple framework integration examples you wanted to review. No CLI, no heavy UIs, no utilities - just clean, focused examples showing how to call the Gradient SDK from web frameworks.

Ready for your review of the framework integration examples!