homelab-frontend/WORKFLOWS_QUICK_START.md

Workflows Quick Start Guide

🚀 Get Started in 2 Minutes

Basic Request Format

{
  "workflow": "batch-embeddings",
  "input": {
    "texts": ["hello world", "machine learning"]
  }
}

Using cURL

curl -X POST https://api.riotpiao.com/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "batch-embeddings",
    "input": {
      "texts": ["hello", "world"]
    }
  }'

Using Python

import requests

response = requests.post(
    "https://api.riotpiao.com/workflows",
    json={
        "workflow": "batch-embeddings",
        "input": {"texts": ["hello", "world"]}
    }
)
result = response.json()
print(result["id"])      # Workflow execution ID
print(result["status"])  # "completed" or "failed"
print(result["output"])  # The actual result

Using JavaScript

const response = await fetch("https://api.riotpiao.com/workflows", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    workflow: "batch-embeddings",
    input: { texts: ["hello", "world"] }
  })
});
const result = await response.json();
console.log(result.id);     // Workflow execution ID
console.log(result.status); // "completed" or "failed"
console.log(result.output); // The actual result

---

📋 Available Workflows

1. chat-and-embed

Chat with a model and embed the response.

Minimal Example:

curl -X POST https://api.riotpiao.com/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "chat-and-embed",
    "input": {
      "model": "reasoning",
      "messages": [{"role": "user", "content": "What is AI?"}]
    }
  }'

Parameters:

• model (required): Chat model name
• messages (required): Array of message objects
• embed_model (optional): Embedding model (default: nomic-ai/nomic-embed-text-v2-moe)

---

2. multi-model-chat

Chat with multiple models and compare responses.

Minimal Example:

curl -X POST https://api.riotpiao.com/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "multi-model-chat",
    "input": {
      "models": ["reasoning", "ornith:35b"],
      "messages": [{"role": "user", "content": "What is Python?"}]
    }
  }'

Parameters:

• models (required): Array of model names
• messages (required): Array of message objects

---

3. rag-pipeline

RAG workflow: rerank documents, then answer based on the best results.

Minimal Example:

curl -X POST https://api.riotpiao.com/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "rag-pipeline",
    "input": {
      "query": "How does ML work?",
      "documents": [
        "Machine learning is...",
        "Python is a language...",
        "Deep learning is..."
      ]
    }
  }'

Parameters:

• query (required): Question or search query
• documents (required): Array of document texts
• model (optional): Chat model (default: "reasoning")
• rerank_model (optional): Reranker model (default: "BAAI/bge-reranker-base")
• top_k (optional): Number of documents to use (default: 3)

---

4. batch-embeddings

Generate embeddings for multiple texts efficiently.

Minimal Example:

curl -X POST https://api.riotpiao.com/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "batch-embeddings",
    "input": {
      "texts": ["text 1", "text 2", "text 3"]
    }
  }'

Parameters:

• texts (required): Array of text strings
• model (optional): Embedding model (default: nomic-ai/nomic-embed-text-v2-moe)

---

⚙️ Optional Parameters

Timeout

Specify how long to wait for the workflow (in seconds):

{
  "workflow": "chat-and-embed",
  "input": {...},
  "timeout": 60
}

Default: 30 seconds

Async Execution

Get a response immediately instead of waiting for completion:

{
  "workflow": "batch-embeddings",
  "input": {...},
  "wait": false
}

Default: true (wait for completion)

---

📊 Response Format

Success Response (completed)

{
  "id": "wf_1692172800123456789",
  "workflow": "batch-embeddings",
  "status": "completed",
  "output": {
    "object": "list",
    "data": [...]
  },
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:02Z"
}

Failure Response

{
  "id": "wf_1692172800123456789",
  "workflow": "chat-and-embed",
  "status": "failed",
  "error": "missing required parameter: model",
  "created_at": "2024-01-15T10:30:00Z"
}

Pending Response (async)

{
  "id": "wf_1692172800123456789",
  "workflow": "batch-embeddings",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

---

❌ Error Messages

Unknown Workflow

{
  "type": "https://api.example.com/problems/unknown-workflow",
  "title": "Unknown Workflow",
  "status": 400,
  "detail": "Workflow \"foo\" is not available"
}

Missing Required Parameter

{
  "id": "wf_...",
  "workflow": "chat-and-embed",
  "status": "failed",
  "error": "missing required parameter: model"
}

Invalid JSON

{
  "type": "https://api.example.com/problems/invalid-workflow-request",
  "title": "Invalid Workflow Request",
  "status": 400,
  "detail": "Failed to parse workflow request: ..."
}

---

🔗 Access Methods

Via api.riotpiao.com (Production)

curl https://api.riotpiao.com/workflows ...

No port forwarding needed - accessible through nginx ingress.

Via localhost (Development)

curl http://127.0.0.1:8080/workflows ...

---

📚 Learn More

For complete documentation:

• See WORKFLOWS.md for full API reference
• See examples/workflows.sh for cURL examples
• See examples/workflows.py for Python examples
• See IMPLEMENTATION_SUMMARY.md for architecture details

---

💡 Common Patterns

Extract chat response from workflow

response = requests.post("https://api.riotpiao.com/workflows", json={...})
if response.status_code == 200:
    result = response.json()
    if result["status"] == "completed":
        # For chat-and-embed
        content = result["output"]["chat_response"]["choices"][0]["message"]["content"]
        print(content)

Extract embeddings from workflow

result = response.json()
if result["status"] == "completed":
    embeddings = result["output"]["data"][0]["embedding"]
    print(len(embeddings), "dimensional vector")

Check for errors

result = response.json()
if result["status"] == "failed":
    print("Error:", result.get("error"))

---

🎯 Performance Tips

1. Batch operations - Use batch-embeddings instead of individual embedding calls
2. Longer timeout for complex queries - RAG pipelines may take 5-10 seconds
3. Reuse embeddings - Cache embedding results for repeated texts
4. Async mode - Use wait: false for non-blocking operations

---

🆘 Troubleshooting

Q: Getting "connection refused" error?

• Ensure gateway is running: go run ./cmd/gateway/main.go
• Check listen address: curl http://localhost:8080/healthz

Q: Getting "unknown workflow" error?

• Check spelling of workflow name (case-sensitive)
• Available workflows: chat-and-embed, multi-model-chat, rag-pipeline, batch-embeddings

Q: Getting model-related errors?

• Ensure the model is configured in your gateway setup
• Check available models: curl https://api.riotpiao.com/v1/models

Q: Workflow timing out?

• Increase timeout: "timeout": 120
• Check upstream services are responsive

---

📖 Full Examples

Example 1: Question Answering with RAG

curl -X POST https://api.riotpiao.com/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "rag-pipeline",
    "timeout": 30,
    "input": {
      "query": "What is machine learning?",
      "documents": [
        "Machine learning is a type of AI...",
        "Deep learning uses neural networks...",
        "Python is great for ML...",
        "Statistics is important..."
      ],
      "top_k": 2
    }
  }' | jq '.output.chat_response.choices[0].message.content'

Example 2: Model Comparison

curl -X POST https://api.riotpiao.com/workflows \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": "multi-model-chat",
    "input": {
      "models": ["reasoning", "ornith:35b"],
      "messages": [
        {"role": "user", "content": "Explain blockchain"}
      ]
    }
  }' | jq '.output[] | {model: .model, answer: .result.choices[0].message.content}'

Example 3: Batch Vector Processing

python3 << 'EOF'
import requests

response = requests.post(
    "https://api.riotpiao.com/workflows",
    json={
        "workflow": "batch-embeddings",
        "input": {
            "texts": [
                "Alice in Wonderland",
                "Python Programming",
                "Machine Learning Basics",
                "Web Development"
            ]
        }
    }
)

result = response.json()
for i, embedding in enumerate(result["output"]["data"]):
    print(f"{i}: {embedding['embedding'][:3]}...")  # Print first 3 dims
EOF

---

That's it! You now have everything you need to use workflows. Start with the examples above and refer to WORKFLOWS.md for more details.