Skip to content

api.md

Latest commit

 

History

History
631 lines (535 loc) · 13.9 KB

api.md

File metadata and controls

631 lines (535 loc) · 13.9 KB

BotForge RAG - API Reference

Base URL

http://localhost:8000

Authentication

Currently, the API uses simple client identification. Future versions will implement JWT-based authentication.

Response Format

All API responses follow a consistent format:

{
  "status": "success|error",
  "data": {...},
  "message": "string",
  "timestamp": "2025-07-04T20:15:00Z"
}

Core Query Endpoints

1. Dynamic Query (Intent-Based Routing)

Endpoint: POST /vector/query-dynamic

Description: Intelligent endpoint that automatically detects query intent and routes to either RAG or MCP agent pipeline.

Request Body:

{
  "user_id": "string (required)",
  "bot_id": "string (required)", 
  "client_id": "string (required)",
  "query": "string (required)",
  "model": "string (optional, default: gpt-3.5-turbo)",
  "temperature": "number (optional, default: 0.0)",
  "max_tokens": "number (optional, default: 1000)"
}

Response:

{
  "user_id": "f7006937-c292-49c7-bed5-23a99a6b6eb2",
  "bot_id": "7e57e5b1-994a-44e4-973e-ed83ffa0ea51",
  "query": "calculate 25 * 17 + 100",
  "model": "gpt-3.5-turbo",
  "response": "525",
  "intent": "execution|information_retrieval",
  "processing_type": "mcp_agent_execution|rag_information_retrieval",
  "execution_time": 2.34,
  "sources": [...],  // Only for RAG queries
  "total_chunks_found": 5,  // Only for RAG queries
  "mcp_tools_used": ["calculator"],  // Only for MCP queries
  "agent_reasoning": "I need to calculate..."  // Only for MCP queries
}

Example Requests:

Information Retrieval:

curl -X POST "http://localhost:8000/vector/query-dynamic" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "bot_id": "bot-456",
    "client_id": "web-app",
    "query": "What is machine learning?",
    "model": "gpt-3.5-turbo"
  }'

Tool Execution:

curl -X POST "http://localhost:8000/vector/query-dynamic" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123", 
    "bot_id": "bot-456",
    "client_id": "web-app",
    "query": "calculate the square root of 144",
    "model": "gpt-3.5-turbo"
  }'

2. Direct RAG Query

Endpoint: POST /vector/query

Description: Forces RAG pipeline regardless of query intent. Returns document sources and relevance scores.

Request Body:

{
  "user_id": "string (required)",
  "bot_id": "string (required)",
  "client_id": "string (required)",
  "namespace": "string (optional)",
  "query": "string (required)",
  "model": "string (optional)",
  "max_chunks": "number (optional, default: 5)",
  "similarity_threshold": "number (optional, default: 0.7)"
}

Response:

{
  "user_id": "user-123",
  "bot_id": "bot-456",
  "query": "machine learning algorithms",
  "response": "Machine learning algorithms are...",
  "sources": [
    {
      "source": "ml-guide.pdf",
      "chunk_index": 0,
      "relevance_score": 0.89,
      "content_preview": "Machine learning is a subset of..."
    }
  ],
  "total_chunks_found": 5,
  "execution_time": 1.23
}

3. Direct MCP Query

Endpoint: POST /vector/mcp-query

Description: Forces MCP agent execution regardless of query intent. Uses bot's registered MCP tools.

Request Body:

{
  "user_id": "string (required)",
  "bot_id": "string (required)",
  "client_id": "string (required)",
  "query": "string (required)",
  "model": "string (optional)",
  "temperature": "number (optional, default: 0.0)"
}

Response:

{
  "user_id": "user-123",
  "bot_id": "bot-456", 
  "query": "convert hello to uppercase",
  "response": "HELLO",
  "mcp_tools_used": ["string_operations"],
  "agent_reasoning": "I'll use the string_operations tool...",
  "execution_time": 0.95
}

MCP Management Endpoints

1. Register MCP Server

Endpoint: POST /api/mcp/register

Description: Register an external MCP server for a specific bot.

Request Body:

{
  "bot_id": "string (required)",
  "name": "string (required)",
  "endpoint_url": "string (required)",
  "description": "string (optional)",
  "api_key": "string (optional)",
  "timeout_seconds": "number (optional, default: 30)",
  "retry_attempts": "number (optional, default: 3)",
  "config": "object (optional)"
}

Response:

{
  "success": true,
  "mcp_server_id": "8c1a34e6-858a-497b-900c-7a069546c35a",
  "tools_registered": 3,
  "server_info": {
    "id": "8c1a34e6-858a-497b-900c-7a069546c35a",
    "name": "Calculator Server",
    "description": "Mathematical calculations",
    "endpoint_url": "http://localhost:3001",
    "is_active": true,
    "timeout_seconds": 30,
    "retry_attempts": 3,
    "config": {},
    "created_at": "2025-07-04T14:34:29.691493",
    "tools_count": 3
  },
  "message": "MCP server 'Calculator Server' registered successfully"
}

Example:

curl -X POST "http://localhost:8000/api/mcp/register" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Calculator Server",
    "endpoint_url": "http://localhost:3001",
    "description": "Mathematical calculations and string operations"
  }'

2. List Bot MCP Servers

Endpoint: GET /api/mcp/servers/{bot_id}

Description: List all MCP servers registered for a specific bot.

Response:

{
  "bot_id": "550e8400-e29b-41d4-a716-446655440000",
  "servers": [
    {
      "id": "8c1a34e6-858a-497b-900c-7a069546c35a",
      "name": "Calculator Server",
      "endpoint_url": "http://localhost:3001",
      "is_active": true,
      "tools_count": 3,
      "created_at": "2025-07-04T14:34:29.691493"
    }
  ]
}

3. List Bot MCP Tools

Endpoint: GET /api/mcp/tools/{bot_id}

Description: List all available tools for a specific bot across all registered MCP servers.

Response:

{
  "bot_id": "550e8400-e29b-41d4-a716-446655440000",
  "tools": [
    {
      "name": "calculator",
      "description": "Perform basic mathematical calculations",
      "schema": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "Mathematical expression to evaluate"
          }
        },
        "required": ["expression"]
      },
      "server_name": "Calculator Server",
      "server_id": "8c1a34e6-858a-497b-900c-7a069546c35a",
      "is_active": true
    }
  ]
}

4. List All MCP Tools

Endpoint: GET /api/mcp/tools

Description: List all tools across all bots and servers (admin endpoint).

Response:

{
  "tools": [
    {
      "bot_id": "550e8400-e29b-41d4-a716-446655440000",
      "tool_name": "calculator",
      "server_name": "Calculator Server",
      "server_url": "http://localhost:3001",
      "is_active": true
    }
  ]
}

Document Management Endpoints

1. Upload Documents

Endpoint: POST /upload/documents

Description: Upload documents for RAG indexing.

Request: Multipart form data

  • files: Document files (PDF, TXT, etc.)
  • namespace: Target namespace (optional)
  • bot_id: Bot ID for document association

Response:

{
  "uploaded_files": ["document1.pdf", "document2.txt"],
  "namespace": "docs",
  "total_chunks": 45,
  "processing_time": 12.34
}

2. List Namespaces

Endpoint: GET /upload/namespaces

Description: List available document namespaces.

Response:

{
  "namespaces": [
    {
      "name": "docs",
      "document_count": 15,
      "chunk_count": 450,
      "created_at": "2025-07-04T10:00:00Z"
    }
  ]
}

System Endpoints

1. Health Check

Endpoint: GET /health

Description: Basic system health check.

Response:

{
  "status": "ok",
  "timestamp": "2025-07-04T20:15:00Z",
  "version": "1.0.0"
}

2. Detailed Health Check

Endpoint: GET /health/detailed

Description: Comprehensive system health with component status.

Response:

{
  "status": "ok",
  "components": {
    "database": {
      "status": "healthy",
      "response_time": 0.05
    },
    "redis": {
      "status": "healthy", 
      "response_time": 0.02
    },
    "openai": {
      "status": "healthy",
      "response_time": 0.15
    },
    "vector_model": {
      "status": "healthy",
      "model": "all-MiniLM-L6-v2"
    }
  },
  "timestamp": "2025-07-04T20:15:00Z"
}

3. Query Statistics

Endpoint: GET /vector/stats/{user_id}/{bot_id}

Description: Get query statistics and metrics for a user/bot combination.

Query Parameters:

  • period: Time period (day, week, month)
  • limit: Number of recent queries to include

Response:

{
  "user_id": "user-123",
  "bot_id": "bot-456",
  "stats": {
    "total_queries": 156,
    "rag_queries": 89,
    "mcp_queries": 67,
    "avg_response_time": 2.34,
    "success_rate": 0.98
  },
  "recent_queries": [
    {
      "query": "What is machine learning?",
      "intent": "information_retrieval",
      "execution_time": 1.23,
      "timestamp": "2025-07-04T19:30:00Z"
    }
  ]
}

Error Responses

Standard Error Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: bot_id",
    "details": {
      "field": "bot_id",
      "type": "missing_field"
    }
  },
  "timestamp": "2025-07-04T20:15:00Z"
}

Common Error Codes

Code HTTP Status Description
INVALID_REQUEST 400 Malformed request or missing fields
BOT_NOT_FOUND 404 Bot ID not found
MCP_SERVER_ERROR 502 External MCP server unreachable
RATE_LIMIT_EXCEEDED 429 Too many requests
INTERNAL_ERROR 500 Server error
OPENAI_ERROR 502 OpenAI API error
DATABASE_ERROR 503 Database connectivity issue

Error Examples

Missing Required Field:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: bot_id"
  }
}

Bot Not Found:

{
  "error": {
    "code": "BOT_NOT_FOUND", 
    "message": "Bot with ID '123' not found"
  }
}

MCP Server Error:

{
  "error": {
    "code": "MCP_SERVER_ERROR",
    "message": "Failed to connect to MCP server at http://localhost:3001"
  }
}

Rate Limiting

Limits

  • Per User: 100 requests per minute
  • Per Bot: 1000 requests per hour
  • Global: 10,000 requests per hour

Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1625097600

Webhook Events

MCP Tool Execution Events

{
  "event": "mcp.tool.executed",
  "data": {
    "bot_id": "bot-456",
    "tool_name": "calculator",
    "execution_time": 0.15,
    "success": true,
    "timestamp": "2025-07-04T20:15:00Z"
  }
}

Query Completion Events

{
  "event": "query.completed",
  "data": {
    "user_id": "user-123",
    "bot_id": "bot-456",
    "query_type": "execution",
    "execution_time": 2.34,
    "success": true,
    "timestamp": "2025-07-04T20:15:00Z"
  }
}

SDK Examples

Python SDK

import requests

class BotForgeClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
    
    def query_dynamic(self, user_id, bot_id, query, client_id="python-sdk"):
        response = requests.post(
            f"{self.base_url}/vector/query-dynamic",
            json={
                "user_id": user_id,
                "bot_id": bot_id,
                "client_id": client_id,
                "query": query
            }
        )
        return response.json()
    
    def register_mcp_server(self, bot_id, name, endpoint_url, description=None):
        response = requests.post(
            f"{self.base_url}/api/mcp/register",
            json={
                "bot_id": bot_id,
                "name": name,
                "endpoint_url": endpoint_url,
                "description": description
            }
        )
        return response.json()

# Usage
client = BotForgeClient()
result = client.query_dynamic("user-123", "bot-456", "What is AI?")
print(result["response"])

JavaScript SDK

class BotForgeClient {
    constructor(baseUrl = "http://localhost:8000") {
        this.baseUrl = baseUrl;
    }
    
    async queryDynamic(userId, botId, query, clientId = "js-sdk") {
        const response = await fetch(`${this.baseUrl}/vector/query-dynamic`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                user_id: userId,
                bot_id: botId,
                client_id: clientId,
                query: query
            })
        });
        return response.json();
    }
    
    async registerMcpServer(botId, name, endpointUrl, description = null) {
        const response = await fetch(`${this.baseUrl}/api/mcp/register`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                bot_id: botId,
                name: name,
                endpoint_url: endpointUrl,
                description: description
            })
        });
        return response.json();
    }
}

// Usage
const client = new BotForgeClient();
const result = await client.queryDynamic("user-123", "bot-456", "Calculate 5 + 3");
console.log(result.response);

Testing

Test Endpoints

# Test intent detection
curl -X POST "http://localhost:8000/vector/query-dynamic" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test", "bot_id": "test", "client_id": "test", "query": "calculate 2+2"}'

# Test RAG
curl -X POST "http://localhost:8000/vector/query" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test", "bot_id": "test", "client_id": "test", "query": "machine learning"}'

# Test health
curl "http://localhost:8000/health"

Performance Testing

# Load test with Apache Bench
ab -n 1000 -c 10 -p query.json -T application/json http://localhost:8000/vector/query-dynamic

# Stress test with wrk
wrk -t12 -c400 -d30s --script=load_test.lua http://localhost:8000/vector/query-dynamic