Integration Models

PraisonAI recipes can be integrated into your applications using six distinct models. Each model has specific use cases, trade-offs, and implementation patterns.

Model Overview

Model	Latency	Complexity	Best For
1. Embedded SDK	Lowest	Low	Python apps, notebooks
2. CLI Invocation	Low	Low	Scripts, CI/CD
3. Local HTTP Sidecar	Medium	Medium	Microservices, polyglot
4. Remote Managed Runner	Medium	High	Multi-tenant, cloud
5. Event-Driven	Variable	High	Async workflows
6. Plugin Mode	Low	Medium	IDE/CMS extensions

Model 1 — Embedded Python SDK (In-Process)

When to Use

Python application (backend, notebook, script)
Need lowest latency (no network hop)
Single-tenant or trusted environment
Direct access to recipe outputs

How It Works

Pros

Zero network latency
Direct memory access to results
Simplest integration
Full Python ecosystem available

Cons

Python-only
Recipe runs in same process (resource sharing)
No built-in multi-tenancy

Step-by-Step Tutorial

Install PraisonAI

pip install praisonai

Set API Keys

export OPENAI_API_KEY=your-key

Run a Recipe

from praisonai import recipe

# List available recipes
recipes = recipe.list_recipes()
print(f"Found {len(recipes)} recipes")

# Run a recipe
result = recipe.run(
    "my-recipe",
    input={"query": "Summarize this document"},
    options={"timeout_sec": 60}
)

if result.ok:
    print(f"Success: {result.output}")
else:
    print(f"Error: {result.error}")

Stream Results

for event in recipe.run_stream("my-recipe", input={"query": "Hello"}):
    print(f"[{event.event_type}] {event.data}")

Troubleshooting

ImportError: Ensure pip install praisonai completed
Recipe not found: Run praisonai recipe list to see available recipes
API key error: Verify OPENAI_API_KEY is set

Model 2 — CLI Invocation (Subprocess)

When to Use

Shell scripts, CI/CD pipelines
Language-agnostic invocation
Quick prototyping
Batch processing

How It Works

Pros

Works from any language
Simple JSON output parsing
No SDK dependency in calling app
Easy to debug

Cons

Process spawn overhead
Stdout/stderr parsing required
No streaming (unless using —stream)

Step-by-Step Tutorial

Verify CLI Installation

praisonai --help

List Recipes

praisonai recipe list --json

Run Recipe with JSON Output

praisonai recipe run my-recipe \
  --input '{"query": "Hello"}' \
  --json

Parse Output in Your App

import subprocess
import json

result = subprocess.run(
    ["praisonai", "recipe", "run", "my-recipe",
     "--input", '{"query": "Hello"}', "--json"],
    capture_output=True,
    text=True
)

data = json.loads(result.stdout)
print(f"Run ID: {data['run_id']}")
print(f"Output: {data['output']}")

Troubleshooting

Command not found: Add praisonai to PATH or use full path
JSON parse error: Ensure --json flag is used
Exit code non-zero: Check stderr for error details

Model 3 — Local HTTP “Recipe Runner” Sidecar

When to Use

Microservices architecture
Non-Python services need recipe access
Want HTTP API without cloud deployment
Development/staging environments

How It Works

Pros

Language-agnostic (HTTP)
Supports streaming (SSE)
Process isolation
Easy to scale horizontally

Cons

Network latency (localhost)
Need to manage server lifecycle
Port management

Step-by-Step Tutorial

Install Serve Dependencies

pip install praisonai[serve]

Start the Server

praisonai serve recipe --port 8765

Check Health

curl http://localhost:8765/health

List Recipes via HTTP

curl http://localhost:8765/v1/recipes

Run Recipe via HTTP

curl -X POST http://localhost:8765/v1/recipes/run \
  -H "Content-Type: application/json" \
  -d '{"recipe": "my-recipe", "input": {"query": "Hello"}}'

Use Endpoints CLI

# Health check
praisonai endpoints health

# List endpoints
praisonai endpoints list --format json

# Invoke endpoint
praisonai endpoints invoke my-recipe \
  --input-json '{"query": "Hello"}' \
  --json

Troubleshooting

Connection refused: Ensure server is running
Port in use: Use --port to specify different port
Missing deps: Run pip install praisonai[serve]

Model 4 — Remote Managed Runner (Self-Hosted or Cloud)

When to Use

Production multi-tenant deployments
Need authentication/authorization
Centralized recipe management
Cloud-native architecture

How It Works

Pros

Centralized management
Built-in auth/audit
Scalable infrastructure
Multi-tenant support

Cons

Network latency
Infrastructure complexity
Requires auth setup

Step-by-Step Tutorial

Start Server with Auth

# Set API key
export PRAISONAI_API_KEY=your-secret-key

# Start with auth enabled
praisonai serve recipe \
  --host 0.0.0.0 \
  --port 8765 \
  --auth api-key

Configure Client

export PRAISONAI_ENDPOINTS_URL=https://api.example.com
export PRAISONAI_ENDPOINTS_API_KEY=your-secret-key

Invoke with Auth

praisonai endpoints invoke my-recipe \
  --input-json '{"query": "Hello"}' \
  --api-key your-secret-key \
  --url https://api.example.com

HTTP with Auth Header

curl -X POST https://api.example.com/v1/recipes/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"recipe": "my-recipe", "input": {"query": "Hello"}}'

Troubleshooting

401 Unauthorized: Check API key header
Connection timeout: Verify network/firewall
TLS errors: Ensure valid certificates

Model 5 — Event-Driven Invocation (Queue/Stream)

When to Use

Asynchronous processing
High-volume batch jobs
Decoupled architectures
Long-running workflows

How It Works

Pros

Fully async
Handles backpressure
Retry/dead-letter support
Scales independently

Cons

Infrastructure complexity
Eventual consistency
Debugging harder

Step-by-Step Tutorial

Define Worker Script

# worker.py
import redis
import json
from praisonai import recipe

r = redis.Redis()
pubsub = r.pubsub()
pubsub.subscribe('recipe-jobs')

for message in pubsub.listen():
    if message['type'] == 'message':
        job = json.loads(message['data'])
        result = recipe.run(
            job['recipe'],
            input=job['input']
        )
        r.publish('recipe-results', json.dumps({
            'job_id': job['job_id'],
            'result': result.to_dict()
        }))

Publish Job

import redis
import json
import uuid

r = redis.Redis()
job_id = str(uuid.uuid4())

r.publish('recipe-jobs', json.dumps({
    'job_id': job_id,
    'recipe': 'my-recipe',
    'input': {'query': 'Process this'}
}))

Consume Results

pubsub = r.pubsub()
pubsub.subscribe('recipe-results')

for message in pubsub.listen():
    if message['type'] == 'message':
        result = json.loads(message['data'])
        print(f"Job {result['job_id']}: {result['result']}")

Model 6 — Plugin Mode (CMS/IDE/Chat Extensions)

When to Use

IDE extensions (VS Code, JetBrains)
CMS plugins (WordPress, Strapi)
Chat integrations (Slack, Discord)
Browser extensions

How It Works

Pros

Native UX integration
Leverages host app features
User-friendly
Context-aware

Cons

Platform-specific
Sandboxing limitations
Update management

Step-by-Step Tutorial

Create Plugin Manifest

{
  "name": "praisonai-plugin",
  "version": "1.0.0",
  "recipes": ["code-review", "doc-generator"],
  "endpoints": {
    "base_url": "http://localhost:8765"
  }
}

Implement Plugin Handler

// plugin.js
async function invokeRecipe(recipeName, input) {
  const response = await fetch(
    `${config.endpoints.base_url}/v1/recipes/run`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ recipe: recipeName, input })
    }
  );
  return response.json();
}

// Register command
registerCommand('praisonai.runRecipe', async () => {
  const result = await invokeRecipe('code-review', {
    code: getSelectedText()
  });
  showOutput(result.output);
});

Decision Guide

Use this flowchart to choose the right model:

Next Steps

Explore Use Cases for real-world patterns
Review Personas for role-specific guidance
Check the CLI Reference for command details

Getting Started

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Documentation Index

​Integration Models

​Model Overview

​Model 1 — Embedded Python SDK (In-Process)

​When to Use

​How It Works

​Pros

​Cons

​Step-by-Step Tutorial

​Troubleshooting

​Model 2 — CLI Invocation (Subprocess)

​When to Use

​How It Works

​Pros

​Cons

​Step-by-Step Tutorial

​Troubleshooting

​Model 3 — Local HTTP “Recipe Runner” Sidecar

​When to Use

​How It Works

​Pros

​Cons

​Step-by-Step Tutorial

​Troubleshooting

​Model 4 — Remote Managed Runner (Self-Hosted or Cloud)

​When to Use

​How It Works

​Pros

​Cons

​Step-by-Step Tutorial

​Troubleshooting

​Model 5 — Event-Driven Invocation (Queue/Stream)

​When to Use

​How It Works

​Pros

​Cons

​Step-by-Step Tutorial

​Model 6 — Plugin Mode (CMS/IDE/Chat Extensions)

​When to Use

​How It Works

​Pros

​Cons

​Step-by-Step Tutorial

​Decision Guide

​Next Steps

Integration Models

Model Overview

Model 1 — Embedded Python SDK (In-Process)

When to Use

How It Works

Pros

Cons

Step-by-Step Tutorial

Troubleshooting

Model 2 — CLI Invocation (Subprocess)

When to Use

How It Works

Pros

Cons

Step-by-Step Tutorial

Troubleshooting

Model 3 — Local HTTP “Recipe Runner” Sidecar

When to Use

How It Works

Pros

Cons

Step-by-Step Tutorial

Troubleshooting

Model 4 — Remote Managed Runner (Self-Hosted or Cloud)

When to Use

How It Works

Pros

Cons

Step-by-Step Tutorial

Troubleshooting

Model 5 — Event-Driven Invocation (Queue/Stream)

When to Use

How It Works

Pros

Cons

Step-by-Step Tutorial

Model 6 — Plugin Mode (CMS/IDE/Chat Extensions)

When to Use

How It Works

Pros

Cons

Step-by-Step Tutorial

Decision Guide

Next Steps