Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

This page describes features extending the AI Gateway, which provides a unified API for accessing multiple AI providers. To learn more, see AI Gateway.

Replace variables in prompt messages using {{variableName}} syntax for dynamic content injection.

Quick Start

const response = await openai.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{
    role: "user",
    content: "Hello {{customer_name}}, your {{product_name}} subscription expires soon."
  }],
  orq: {
    inputs: {
      customer_name: "John Smith",
      product_name: "Premium Plan"
    }
  }
});

Result: "Hello John Smith, your Premium Plan subscription expires soon."

Configuration

Parameter	Type	Required	Description
`inputs`	object	No	Key-value pairs to replace `{{key}}` variables in messages

Variable Format: {{variableName}} (case-sensitive, alphanumeric + underscore)

Use Cases

Scenario	Variables	Example Input
Customer Support	`{{customer_name}}`, `{{issue_type}}`	`{customer_name: "Alice", issue_type: "billing"}`
Product Recommendations	`{{user_preferences}}`, `{{budget}}`	`{user_preferences: "eco-friendly", budget: "$500"}`
Onboarding	`{{user_name}}`, `{{plan_type}}`	`{user_name: "Bob", plan_type: "Enterprise"}`
Content Generation	`{{topic}}`, `{{audience}}`	`{topic: "AI trends", audience: "developers"}`

Implementation Examples

Customer Support Automation

const supportTicket = {
  customerName: "Sarah Johnson",
  issueType: "billing",
  accountType: "premium",
  ticketId: "TICKET-001"
};

const response = await openai.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{
    role: "system",
    content: "You are a helpful customer support agent for {{company_name}}."
  }, {
    role: "user",
    content: "Hi, I'm {{customer_name}} and I have a {{issue_type}} issue with my {{account_type}} account. Ticket: {{ticket_id}}"
  }],
  orq: {
    inputs: {
      company_name: "Acme Corp",
      customer_name: supportTicket.customerName,
      issue_type: supportTicket.issueType,
      account_type: supportTicket.accountType,
      ticket_id: supportTicket.ticketId
    }
  }
});

Personalized Email Generation

const emailTemplate = {
  recipient: "Marketing Team",
  campaign: "Q4 Product Launch",
  metrics: "25% increase in engagement"
};

const response = await openai.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{
    role: "user",
    content: `Create a performance report email for {{recipient}} about the {{campaign}} campaign.
    Highlight that we achieved {{metrics}} and include actionable next steps.`
  }],
  orq: {
    inputs: {
      recipient: emailTemplate.recipient,
      campaign: emailTemplate.campaign,
      metrics: emailTemplate.metrics
    }
  }
});

Multi-Language Support

curl -X POST https://api.orq.ai/v2/proxy/chat/completions \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{
      "role": "user",
      "content": "Generate a {{content_type}} about {{topic}} for {{target_audience}}"
    }],
    "orq": {
      "inputs": {
        "content_type": "blog post",
        "topic": "sustainable technology",
        "target_audience": "enterprise decision makers"
      }
    }
  }'

Advanced Patterns

Dynamic Template Loading

interface TemplateConfig {
  template: string;
  requiredInputs: string[];
  defaultInputs?: Record<string, string>;
}

const templates: Record<string, TemplateConfig> = {
  welcome: {
    template: "Welcome {{user_name}}! Your {{plan_type}} account is now active.",
    requiredInputs: ["user_name", "plan_type"]
  },
  reminder: {
    template: "Hi {{user_name}}, your {{service}} subscription expires in {{days}} days.",
    requiredInputs: ["user_name", "service", "days"],
    defaultInputs: { service: "Premium Plan" }
  }
};

async function generateFromTemplate(
  templateKey: string,
  inputs: Record<string, string>
) {
  const template = templates[templateKey];

  if (!template) {
    throw new Error(`Template ${templateKey} not found`);
  }

  // Validate required inputs
  const missing = template.requiredInputs.filter(key => !inputs[key]);
  if (missing.length > 0) {
    throw new Error(`Missing required inputs: ${missing.join(", ")}`);
  }

  // Merge with defaults
  const finalInputs = { ...template.defaultInputs, ...inputs };

  return await openai.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{
      role: "user",
      content: template.template
    }],
    orq: { inputs: finalInputs }
  });
}

// Usage
const response = await generateFromTemplate("welcome", {
  user_name: "Alice Johnson",
  plan_type: "Enterprise"
});

Conditional Content Generation

// Generate content based on user tier
const generateTieredContent = async (userTier, baseContent, inputs) => {
  const tierSpecificPrompts = {
    free: "Keep the response brief and mention premium features are available.",
    premium: "Provide detailed information and include premium tips.",
    enterprise: "Include advanced strategies and enterprise-specific recommendations."
  };

  const enhancedInputs = {
    ...inputs,
    user_tier: userTier,
    tier_instruction: tierSpecificPrompts[userTier]
  };

  return await openai.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{
      role: "system",
      content: "{{tier_instruction}}"
    }, {
      role: "user",
      content: baseContent
    }],
    orq: { inputs: enhancedInputs }
  });
};

Batch Input Processing

const batchInputs = [
  { customer_name: "John Doe", product: "Analytics Pro", status: "trial_ending" },
  { customer_name: "Jane Smith", product: "CRM Plus", status: "payment_failed" },
  { customer_name: "Bob Wilson", product: "Marketing Suite", status: "renewal_due" }
];

const template = "Hi {{customer_name}}, your {{product}} account has status: {{status}}. Please take action.";

const responses = await Promise.all(
  batchInputs.map(async (inputs) => {
    return openai.chat.completions.create({
      model: "openai/gpt-4o",
      messages: [{ role: "user", content: template }],
      orq: { inputs }
    });
  })
);

Input Validation

Type Safety with TypeScript

interface EmailInputs {
  recipient_name: string;
  company_name: string;
  meeting_date: string;
  meeting_time: string;
}

interface ProductInputs {
  product_name: string;
  price: string;
  features: string;
  target_audience: string;
}

function validateInputs<T>(inputs: T, required: (keyof T)[]): void {
  const missing = required.filter(key => !inputs[key]);
  if (missing.length > 0) {
    throw new Error(`Missing required inputs: ${missing.join(", ")}`);
  }
}

// Usage
const emailInputs: EmailInputs = {
  recipient_name: "John Smith",
  company_name: "Acme Inc",
  meeting_date: "December 15",
  meeting_time: "2:00 PM"
};

validateInputs(emailInputs, ["recipient_name", "company_name", "meeting_date"]);

Runtime Validation

// Validate input format and constraints
function validateInputValue(key, value) {
  const validators = {
    email: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
    phone: (v) => /^\+?[\d\s-()]+$/.test(v),
    date: (v) => !isNaN(Date.parse(v)),
    price: (v) => /^\$?\d+(\.\d{2})?$/.test(v),
    name: (v) => v.length >= 2 && v.length <= 50
  };

  const validator = validators[key];
  if (validator && !validator(value)) {
    throw new Error(`Invalid ${key} format: ${value}`);
  }
}

// Sanitize inputs
function sanitizeInputs(inputs) {
  const sanitized = {};

  for (const [key, value] of Object.entries(inputs)) {
    // Remove HTML tags and trim whitespace
    const cleanValue = String(value)
      .replace(/<[^>]*>/g, '')
      .trim()
      .substring(0, 1000); // Limit length

    validateInputValue(key, cleanValue);
    sanitized[key] = cleanValue;
  }

  return sanitized;
}

Error Handling

Template Variable Detection

// Extract variables from template
function extractVariables(template) {
  const matches = template.match(/\{\{([^}]+)\}\}/g) || [];
  return matches.map(match => match.slice(2, -2).trim());
}

// Validate all variables have inputs
function validateTemplate(template, inputs) {
  const variables = extractVariables(template);
  const missing = variables.filter(variable => !inputs.hasOwnProperty(variable));

  if (missing.length > 0) {
    throw new Error(`Missing inputs for variables: ${missing.join(", ")}`);
  }

  return true;
}

// Usage
const template = "Hello {{name}}, your {{product}} expires on {{date}}";
const inputs = { name: "John", product: "Premium Plan" }; // Missing 'date'

try {
  validateTemplate(template, inputs);
} catch (error) {
  console.error(error.message); // "Missing inputs for variables: date"
}

Safe Input Substitution

// Preview substitution without making API call
function previewSubstitution(template, inputs) {
  let result = template;

  // Replace known variables
  for (const [key, value] of Object.entries(inputs)) {
    const regex = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
    result = result.replace(regex, value);
  }

  // Highlight missing variables
  const remaining = result.match(/\{\{[^}]+\}\}/g) || [];

  return {
    preview: result,
    missingVariables: remaining.map(v => v.slice(2, -2)),
    isComplete: remaining.length === 0
  };
}

// Usage
const preview = previewSubstitution(
  "Hi {{name}}, your {{product}} status is {{status}}",
  { name: "Alice", product: "Pro Plan" }
);

console.log(preview.preview); // "Hi Alice, your Pro Plan status is {{status}}"
console.log(preview.missingVariables); // ["status"]
console.log(preview.isComplete); // false

Performance Optimization

Input Caching

// Cache frequently used input combinations
const inputCache = new Map();

function getCachedInputs(cacheKey, inputGenerator) {
  if (inputCache.has(cacheKey)) {
    return inputCache.get(cacheKey);
  }

  const inputs = inputGenerator();
  inputCache.set(cacheKey, inputs);

  // Auto-expire cache entries
  setTimeout(() => inputCache.delete(cacheKey), 5 * 60 * 1000); // 5 minutes

  return inputs;
}

// Usage
const userInputs = getCachedInputs(`user-${userId}`, () => ({
  user_name: user.name,
  user_tier: user.subscription.tier,
  last_login: user.lastLogin.toDateString()
}));

Template Compilation

// Pre-compile templates for better performance
class TemplateCompiler {
  constructor() {
    this.compiledTemplates = new Map();
  }

  compile(templateId, template) {
    const variables = extractVariables(template);
    this.compiledTemplates.set(templateId, {
      template,
      variables,
      requiredInputs: variables
    });
  }

  async execute(templateId, inputs, model = "openai/gpt-4o") {
    const compiled = this.compiledTemplates.get(templateId);
    if (!compiled) {
      throw new Error(`Template ${templateId} not found`);
    }

    validateTemplate(compiled.template, inputs);

    return await openai.chat.completions.create({
      model,
      messages: [{ role: "user", content: compiled.template }],
      orq: { inputs }
    });
  }
}

// Usage
const compiler = new TemplateCompiler();
compiler.compile("welcome", "Welcome {{user_name}} to {{service_name}}!");

const response = await compiler.execute("welcome", {
  user_name: "John",
  service_name: "AI Assistant"
});

Best Practices

Variable Naming: Use descriptive, snake_case variable names
Input Validation: Always validate inputs before sending requests
Template Testing: Test templates with sample data before production
Security: Sanitize user inputs to prevent injection attacks
Performance: Cache frequently used input combinations
Documentation: Document required inputs for each template

Troubleshooting

**Variables not replaced

Cause: Typo in variable name or syntax
Solution: Check {{variableName}} format matches input keys

**Missing content

Cause: Required inputs not provided
Solution: Validate all template variables have corresponding inputs

**Unexpected output

Cause: HTML/special characters in inputs
Solution: Sanitize inputs before sending

**Performance issues

Cause: Large input objects
Solution: Limit input size and cache frequently used values

Limitations

Limitation	Description	Workaround
Variable Syntax	Only `{{variableName}}` format supported	Use consistent naming convention
Nested Objects	No support for `{{user.name}}` syntax	Flatten object structure
Input Size	Large inputs increase token usage	Keep inputs concise and relevant
Special Characters	Some characters may need escaping	Sanitize inputs appropriately
Case Sensitivity	Variable names are case-sensitive	Use consistent casing throughout

Integration Examples

CMS Integration

// Integrate with content management systems
const cmsContent = await cms.getTemplate("product-announcement");

const response = await openai.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: cmsContent.template }],
  orq: {
    inputs: {
      product_name: "AI Analytics Pro",
      release_date: "January 2024",
      key_features: "Advanced reporting, Real-time insights, Custom dashboards",
      target_audience: "Enterprise customers"
    }
  }
});

Database Integration

// Pull dynamic content from database
async function generatePersonalizedContent(userId, templateId) {
  const [user, template] = await Promise.all([
    database.users.findById(userId),
    database.templates.findById(templateId)
  ]);

  const inputs = {
    user_name: user.fullName,
    account_type: user.subscription.type,
    usage_stats: await getUserUsageStats(userId),
    recommendations: await getPersonalizedRecommendations(userId)
  };

  return await openai.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: template.content }],
    orq: { inputs }
  });
}

Getting Started

Reference

Administer

Tutorials

Inputs

Quick Start

Configuration

Use Cases

Implementation Examples

Customer Support Automation

Personalized Email Generation

Multi-Language Support

Advanced Patterns

Dynamic Template Loading

Conditional Content Generation

Batch Input Processing

Input Validation

Type Safety with TypeScript

Runtime Validation

Error Handling

Template Variable Detection

Safe Input Substitution

Performance Optimization

Input Caching

Template Compilation

Best Practices

Troubleshooting

Limitations

Integration Examples

CMS Integration

Database Integration

Getting Started

Reference

Administer

Tutorials

​Quick Start

​Configuration

​Use Cases

​Implementation Examples

​Customer Support Automation

​Personalized Email Generation

​Multi-Language Support

​Advanced Patterns

​Dynamic Template Loading

​Conditional Content Generation

​Batch Input Processing

​Input Validation

​Type Safety with TypeScript

​Runtime Validation

​Error Handling

​Template Variable Detection

​Safe Input Substitution

​Performance Optimization

​Input Caching

​Template Compilation

​Best Practices

​Troubleshooting

​Limitations

​Integration Examples

​CMS Integration

​Database Integration

Quick Start

Configuration

Use Cases

Implementation Examples

Customer Support Automation

Personalized Email Generation

Multi-Language Support

Advanced Patterns

Dynamic Template Loading

Conditional Content Generation

Batch Input Processing

Input Validation

Type Safety with TypeScript

Runtime Validation

Error Handling

Template Variable Detection

Safe Input Substitution

Performance Optimization

Input Caching

Template Compilation

Best Practices

Troubleshooting

Limitations

Integration Examples

CMS Integration

Database Integration