Integration Examples

Real-world examples of integrating Perf into your application stack.

Next.js Integration
Python FastAPI
Express.js Backend
React Frontend (with Streaming)
LangChain Integration
Vercel AI SDK
Background Jobs
Slack Bot

Next.js Integration

API Route Handler

// app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server';

const PERF_API_KEY = process.env.PERF_API_KEY!;
const PERF_API_URL = 'https://api.withperf.pro/v1/chat';

export async function POST(request: NextRequest) {
  try {
    const { messages } = await request.json();

    // Call Perf API
    const response = await fetch(PERF_API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${PERF_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        messages,
        max_cost_per_call: 0.01,
      }),
    });

    if (!response.ok) {
      const error = await response.json();
      return NextResponse.json(
        { error: error.message },
        { status: response.status }
      );
    }

    const data = await response.json();
    return NextResponse.json(data);

  } catch (error) {
    console.error('Chat API error:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Client Component

// components/ChatInterface.tsx
'use client';

import { useState } from 'react';

interface Message {
  role: 'user' | 'assistant';
  content: string;
}

export default function ChatInterface() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [input, setInput] = useState('');
  const [loading, setLoading] = useState(false);

  const sendMessage = async () => {
    if (!input.trim()) return;

    const userMessage: Message = { role: 'user', content: input };
    setMessages(prev => [...prev, userMessage]);
    setInput('');
    setLoading(true);

    try {
      const response = await fetch('/api/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          messages: [...messages, userMessage],
        }),
      });

      const data = await response.json();

      if (data.error) {
        throw new Error(data.error);
      }

      // OpenAI-compatible response format
      const assistantMessage: Message = {
        role: 'assistant',
        content: data.choices[0].message.content,
      };

      setMessages(prev => [...prev, assistantMessage]);
    } catch (error) {
      console.error('Error:', error);
      alert('Failed to send message');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="flex flex-col h-screen">
      <div className="flex-1 overflow-y-auto p-4 space-y-4">
        {messages.map((msg, idx) => (
          <div
            key={idx}
            className={`p-3 rounded-lg ${
              msg.role === 'user'
                ? 'bg-blue-100 ml-12'
                : 'bg-gray-100 mr-12'
            }`}
          >
            {msg.content}
          </div>
        ))}
        {loading && <div className="text-gray-500">Thinking...</div>}
      </div>

      <div className="border-t p-4">
        <div className="flex gap-2">
          <input
            type="text"
            value={input}
            onChange={(e) => setInput(e.target.value)}
            onKeyPress={(e) => e.key === 'Enter' && sendMessage()}
            className="flex-1 border rounded px-3 py-2"
            placeholder="Type a message..."
            disabled={loading}
          />
          <button
            onClick={sendMessage}
            disabled={loading}
            className="bg-blue-500 text-white px-6 py-2 rounded disabled:opacity-50"
          >
            Send
          </button>
        </div>
      </div>
    </div>
  );
}

Python FastAPI

Main Application

# main.py
from fastapi import FastAPI, HTTPException, Depends
from fastapi.security import HTTPBearer, HTTPAuthCredentials
from pydantic import BaseModel
from typing import List, Optional
import httpx
import os

app = FastAPI()
security = HTTPBearer()

PERF_API_KEY = os.environ.get("PERF_API_KEY")
PERF_API_URL = "https://api.withperf.pro/v1/chat"

class Message(BaseModel):
    role: str
    content: str

class ChatRequest(BaseModel):
    messages: List[Message]
    max_cost_per_call: Optional[float] = 0.01

class ChatResponse(BaseModel):
    """OpenAI-compatible response model"""
    id: str
    model: str
    choices: list
    usage: dict

@app.post("/chat", response_model=ChatResponse)
async def chat(
    request: ChatRequest,
    credentials: HTTPAuthCredentials = Depends(security)
):
    """
    Chat endpoint that proxies to Perf API
    """
    # Validate user token (your own auth logic)
    if not await validate_user_token(credentials.credentials):
        raise HTTPException(status_code=401, detail="Invalid token")

    # Call Perf API
    async with httpx.AsyncClient() as client:
        try:
            response = await client.post(
                PERF_API_URL,
                json=request.dict(),
                headers={
                    "Authorization": f"Bearer {PERF_API_KEY}",
                    "Content-Type": "application/json"
                },
                timeout=30.0
            )
            response.raise_for_status()
            return response.json()

        except httpx.HTTPStatusError as e:
            raise HTTPException(
                status_code=e.response.status_code,
                detail=e.response.json().get("error", "Unknown error")
            )
        except httpx.TimeoutException:
            raise HTTPException(status_code=504, detail="Request timeout")

async def validate_user_token(token: str) -> bool:
    # Implement your user authentication logic
    return True

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Background Task Processing

# background_tasks.py
from celery import Celery
import httpx
import os

celery = Celery('tasks', broker='redis://localhost:6379/0')

PERF_API_KEY = os.environ.get("PERF_API_KEY")

@celery.task
def process_document_async(document_text: str, user_id: str):
    """
    Process documents in background using Perf
    """
    with httpx.Client() as client:
        response = client.post(
            "https://api.withperf.pro/v1/chat",
            json={
                "messages": [
                    {
                        "role": "user",
                        "content": f"Summarize this document:\n\n{document_text}"
                    }
                ],
                "max_cost_per_call": 0.02
            },
            headers={
                "Authorization": f"Bearer {PERF_API_KEY}",
                "Content-Type": "application/json"
            }
        )

        result = response.json()

        # Store result in database (OpenAI-compatible format)
        content = result['choices'][0]['message']['content']
        save_summary(user_id, content)

        return result

Express.js Backend

// server.js
const express = require('express');
const fetch = require('node-fetch');
require('dotenv').config();

const app = express();
app.use(express.json());

const PERF_API_KEY = process.env.PERF_API_KEY;
const PERF_API_URL = 'https://api.withperf.pro/v1/chat';

// Rate limiting per user
const userRateLimits = new Map();

function checkUserRateLimit(userId) {
  const now = Date.now();
  const userLimit = userRateLimits.get(userId) || { count: 0, resetAt: now + 60000 };

  if (now > userLimit.resetAt) {
    userLimit.count = 0;
    userLimit.resetAt = now + 60000;
  }

  if (userLimit.count >= 20) {
    return false;
  }

  userLimit.count++;
  userRateLimits.set(userId, userLimit);
  return true;
}

app.post('/api/chat', async (req, res) => {
  try {
    // Validate user session
    const userId = req.session?.userId;
    if (!userId) {
      return res.status(401).json({ error: 'Unauthorized' });
    }

    // Check rate limit
    if (!checkUserRateLimit(userId)) {
      return res.status(429).json({
        error: 'Too many requests',
        retryAfter: 60
      });
    }

    // Call Perf API
    const response = await fetch(PERF_API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${PERF_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        messages: req.body.messages,
        max_cost_per_call: 0.01
      })
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json(data);
    }

    // Log usage (OpenAI-compatible format)
    await logUsage(userId, data.usage.total_tokens);

    res.json(data);

  } catch (error) {
    console.error('Chat error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

React Frontend with Streaming

// hooks/useChat.ts
import { useState, useCallback } from 'react';

interface Message {
  role: 'user' | 'assistant';
  content: string;
}

export function useChat() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const [streamingContent, setStreamingContent] = useState('');

  const sendMessage = useCallback(async (content: string) => {
    const userMessage: Message = { role: 'user', content };
    setMessages(prev => [...prev, userMessage]);
    setIsLoading(true);
    setStreamingContent('');

    try {
      const response = await fetch('/api/chat/stream', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          messages: [...messages, userMessage],
        }),
      });

      const reader = response.body?.getReader();
      const decoder = new TextDecoder();
      let fullContent = '';

      while (true) {
        const { done, value } = await reader!.read();
        if (done) break;

        const chunk = decoder.decode(value);
        const lines = chunk.split('\n');

        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const payload = line.slice(6);

            // Check for [DONE] signal (OpenAI SSE format)
            if (payload === '[DONE]') {
              setMessages(prev => [
                ...prev,
                { role: 'assistant', content: fullContent }
              ]);
              setStreamingContent('');
              break;
            }

            const data = JSON.parse(payload);
            const deltaContent = data.choices?.[0]?.delta?.content || '';

            if (deltaContent) {
              fullContent += deltaContent;
              setStreamingContent(fullContent);
            }
          }
        }
      }
    } catch (error) {
      console.error('Streaming error:', error);
      alert('Failed to send message');
    } finally {
      setIsLoading(false);
    }
  }, [messages]);

  return {
    messages,
    isLoading,
    streamingContent,
    sendMessage,
  };
}

LangChain Integration

# perf_langchain.py
from langchain.llms.base import LLM
from typing import Any, List, Optional
import httpx
import os

class PerfLLM(LLM):
    """
    LangChain wrapper for Perf API
    """
    max_cost_per_call: float = 0.01
    perf_api_key: str = os.environ.get("PERF_API_KEY", "")

    @property
    def _llm_type(self) -> str:
        return "perf"

    def _call(
        self,
        prompt: str,
        stop: Optional[List[str]] = None
    ) -> str:
        with httpx.Client() as client:
            response = client.post(
                "https://api.withperf.pro/v1/chat",
                json={
                    "messages": [{"role": "user", "content": prompt}],
                    "max_cost_per_call": self.max_cost_per_call
                },
                headers={
                    "Authorization": f"Bearer {self.perf_api_key}",
                    "Content-Type": "application/json"
                }
            )
            response.raise_for_status()
            data = response.json()
            # OpenAI-compatible response format
            return data["choices"][0]["message"]["content"]

# Usage
from langchain.chains import LLMChain
from langchain.prompts import PromptTemplate

llm = PerfLLM(max_cost_per_call=0.005)

template = """
Extract the key information from this text:
{text}

Return JSON with: name, email, phone
"""

prompt = PromptTemplate(template=template, input_variables=["text"])
chain = LLMChain(llm=llm, prompt=prompt)

result = chain.run(text="Contact John Doe at john@example.com or 555-1234")
print(result)

Vercel AI SDK

// app/api/chat/route.ts
import { OpenAIStream, StreamingTextResponse } from 'ai';

export const runtime = 'edge';

export async function POST(req: Request) {
  const { messages } = await req.json();

  // Call Perf streaming endpoint
  const response = await fetch('https://api.withperf.pro/v1/chat/stream', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PERF_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ messages }),
  });

  // Convert OpenAI SSE format to Vercel AI SDK format
  const stream = new ReadableStream({
    async start(controller) {
      const reader = response.body?.getReader();
      const decoder = new TextDecoder();

      while (true) {
        const { done, value } = await reader!.read();
        if (done) break;

        const chunk = decoder.decode(value);
        const lines = chunk.split('\n');

        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const payload = line.slice(6);
            if (payload === '[DONE]') break;

            const data = JSON.parse(payload);
            const content = data.choices?.[0]?.delta?.content || '';
            if (content) {
              controller.enqueue(new TextEncoder().encode(content));
            }
          }
        }
      }
      controller.close();
    },
  });

  return new StreamingTextResponse(stream);
}

Background Jobs

# batch_processor.py
import asyncio
import httpx
from typing import List, Dict
import os

PERF_API_KEY = os.environ.get("PERF_API_KEY")

async def process_batch(items: List[str]) -> List[Dict]:
    """
    Process a batch of items using Perf API with concurrency control
    """
    async with httpx.AsyncClient() as client:
        semaphore = asyncio.Semaphore(10)  # Max 10 concurrent requests

        async def process_item(item: str):
            async with semaphore:
                response = await client.post(
                    "https://api.withperf.pro/v1/chat",
                    json={
                        "messages": [
                            {"role": "user", "content": f"Analyze: {item}"}
                        ],
                        "max_cost_per_call": 0.005
                    },
                    headers={
                        "Authorization": f"Bearer {PERF_API_KEY}",
                        "Content-Type": "application/json"
                    },
                    timeout=30.0
                )
                return response.json()

        results = await asyncio.gather(
            *[process_item(item) for item in items],
            return_exceptions=True
        )

        return results

# Usage
if __name__ == "__main__":
    items = ["item1", "item2", "item3", ...]
    results = asyncio.run(process_batch(items))

    # Count successful results (OpenAI-compatible format)
    successful = sum(1 for r in results if 'choices' in r)
    print(f"Processed {successful}/{len(results)} items successfully")

Slack Bot

# slack_bot.py
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler
import httpx
import os

app = App(token=os.environ.get("SLACK_BOT_TOKEN"))

PERF_API_KEY = os.environ.get("PERF_API_KEY")

@app.event("app_mention")
def handle_mention(event, say):
    """
    Respond to @mentions using Perf API
    """
    user_message = event['text']

    # Call Perf
    with httpx.Client() as client:
        response = client.post(
            "https://api.withperf.pro/v1/chat",
            json={
                "messages": [{"role": "user", "content": user_message}],
                "max_cost_per_call": 0.01
            },
            headers={
                "Authorization": f"Bearer {PERF_API_KEY}",
                "Content-Type": "application/json"
            }
        )

        data = response.json()

        # OpenAI-compatible response format
        content = data['choices'][0]['message']['content']
        model = data['model']

        say(
            text=content,
            thread_ts=event['ts'],
            blocks=[
                {
                    "type": "section",
                    "text": {"type": "mrkdwn", "text": content}
                },
                {
                    "type": "context",
                    "elements": [
                        {
                            "type": "mrkdwn",
                            "text": f"_Model: {model}_"
                        }
                    ]
                }
            ]
        )

if __name__ == "__main__":
    handler = SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"])
    handler.start()

Getting Started

Voice Agents

SDKs

API Documentation

Platform

Advanced

Resources

Integration Examples

Integration Examples

Table of Contents

Next.js Integration

API Route Handler

Client Component

Python FastAPI

Main Application

Background Task Processing

Express.js Backend

React Frontend with Streaming

LangChain Integration

Vercel AI SDK

Background Jobs

Slack Bot

Next Steps

​Integration Examples

​Table of Contents

​Next.js Integration

​API Route Handler

​Client Component

​Python FastAPI

​Main Application

​Background Task Processing

​Express.js Backend

​React Frontend with Streaming

​LangChain Integration

​Vercel AI SDK

​Background Jobs

​Slack Bot

​Next Steps

Integration Examples

Table of Contents

Next.js Integration

API Route Handler

Client Component

Python FastAPI

Main Application

Background Task Processing

Express.js Backend

React Frontend with Streaming

LangChain Integration

Vercel AI SDK

Background Jobs

Slack Bot

Next Steps