homelab-frontend/WORKFLOWS_QUICK_START.md

# Workflows Quick Start Guide

## 🚀 Get Started in 2 Minutes

### Basic Request Format

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

### Using cURL

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

### Using Python

```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

```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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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):

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

Default: 30 seconds

### Async Execution

Get a response immediately instead of waiting for completion:

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

Default: `true` (wait for completion)

---

## 📊 Response Format

### Success Response (completed)

```json
{
  "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

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

### Pending Response (async)

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

---

## ❌ Error Messages

### Unknown Workflow

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

### Missing Required Parameter

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

### Invalid JSON

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

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

**No port forwarding needed** - accessible through nginx ingress.

### Via localhost (Development)

```bash
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

```python
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

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

### Check for errors

```python
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

```bash
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

```bash
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

```bash
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.