Update Smart RAG Configuration

Update the configuration of a smart RAG node within a specific flow in your Graphor project. Smart RAG nodes combine intelligent document processing, chunking, and retrieval operations, and their primary configuration parameter controls the number of top results to retrieve during query processing.

Overview

The Update Smart RAG Configuration endpoint allows you to modify the settings of smart RAG nodes within a flow. Smart RAG nodes are comprehensive RAG components that automatically handle document processing and retrieval, with the main configurable parameter being the number of top results to return during query execution.

Method: PATCH
URL: https://{flow_name}.flows.graphorlm.com/smart-rag/{node_id}
Authentication: Required (API Token)

Authentication

All requests must include a valid API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Learn how to generate API tokens in the API Tokens guide.

Request Format

Headers

Header	Value	Required
`Authorization`	`Bearer YOUR_API_TOKEN`	Yes
`Content-Type`	`application/json`	Yes

Path Parameters

Parameter	Type	Description	Required
`flow_name`	string	Name of the flow containing the smart RAG node	Yes
`node_id`	string	Unique identifier of the smart RAG node to update	Yes

Request Body

The request body must contain a configuration object with smart RAG settings:

{
  "config": {
    "topK": 10
  }
}

Configuration Parameters

Parameter	Type	Description	Default	Required
`topK`	integer	Number of top results to retrieve during query processing. Set to `null` for unlimited results	5	No

Example Request

PATCH https://my-rag-pipeline.flows.graphorlm.com/smart-rag/smart-rag-1748287628685
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "config": {
    "topK": 15
  }
}

Response Format

Success Response (200 OK)

{
  "success": true,
  "message": "Smart rag node 'smart-rag-1748287628685' updated successfully",
  "node_id": "smart-rag-1748287628685"
}

Response Fields

Field	Type	Description
`success`	boolean	Whether the update operation was successful
`message`	string	Human-readable message describing the result
`node_id`	string	The ID of the updated smart RAG node

Configuration Strategies

Precision-Focused Strategy

Top K: 3-5 results
Best for: High-precision applications where quality is critical
Characteristics: Returns fewer, highly relevant results
Use cases: Critical decision support, expert systems, factual Q&A

Balanced Strategy

Top K: 8-12 results
Best for: General-purpose applications balancing quality and coverage
Characteristics: Good mix of precision and recall
Use cases: Customer support, knowledge management, general Q&A

Comprehensive Strategy

Top K: 15-25 results
Best for: Research applications requiring thorough coverage
Characteristics: Maximum coverage with acceptable processing overhead
Use cases: Research assistance, discovery applications, content exploration

Unlimited Strategy

Top K: null (unlimited)
Best for: Complete analysis, no result limits
Characteristics: Process all retrieved documents
Trade-offs: Higher resource usage and processing time
Use cases: Research projects, complete document analysis

Code Examples

JavaScript/Node.js

async function updateSmartRagConfiguration(flowName, nodeId, config, apiToken) {
  const response = await fetch(`https://${flowName}.flows.graphorlm.com/smart-rag/${nodeId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ config })
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

// Usage Examples
async function demonstrateSmartRagUpdates() {
  const apiToken = 'YOUR_API_TOKEN';
  const flowName = 'my-rag-pipeline';
  const nodeId = 'smart-rag-1748287628685';

  // High-precision configuration
  await updateSmartRagConfiguration(flowName, nodeId, {
    topK: 5
  }, apiToken);
  console.log('✅ Updated to high-precision mode (Top K = 5)');

  // Balanced configuration
  await updateSmartRagConfiguration(flowName, nodeId, {
    topK: 10
  }, apiToken);
  console.log('✅ Updated to balanced mode (Top K = 10)');

  // Comprehensive configuration
  await updateSmartRagConfiguration(flowName, nodeId, {
    topK: 20
  }, apiToken);
  console.log('✅ Updated to comprehensive mode (Top K = 20)');

  // Unlimited configuration
  await updateSmartRagConfiguration(flowName, nodeId, {
    topK: null
  }, apiToken);
  console.log('✅ Updated to unlimited mode (Top K = unlimited)');
}

demonstrateSmartRagUpdates().catch(console.error);

Advanced JavaScript Example

class SmartRagConfigurationManager {
  constructor(flowName, apiToken) {
    this.flowName = flowName;
    this.apiToken = apiToken;
  }

  async updateConfiguration(nodeId, config) {
    const response = await fetch(`https://${this.flowName}.flows.graphorlm.com/smart-rag/${nodeId}`, {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${this.apiToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ config })
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  }

  async performTopKAnalysis(nodeId, testValues = [3, 5, 10, 15, 20]) {
    console.log(`🔬 Performing Top K analysis for node ${nodeId}`);
    const analysisResults = [];

    for (const topK of testValues) {
      try {
        console.log(`\n📊 Testing Top K = ${topK}`);
        
        const result = await this.updateConfiguration(nodeId, { topK });
        
        const analysis = {
          topK,
          success: true,
          resourceEstimate: this.estimateResourceUsage(topK),
          performanceEstimate: this.estimatePerformance(topK),
          qualityEstimate: this.estimateQuality(topK),
          recommendedFor: this.getRecommendation(topK)
        };
        
        console.log(`   ⚡ Resources: ${analysis.resourceEstimate}`);
        console.log(`   ⚡ Performance: ${analysis.performanceEstimate}`);
        console.log(`   🎯 Quality: ${analysis.qualityEstimate}`);
        console.log(`   💡 Recommended for: ${analysis.recommendedFor}`);
        
        analysisResults.push(analysis);
        
        // Small delay to avoid overwhelming the API
        await new Promise(resolve => setTimeout(resolve, 1000));
        
      } catch (error) {
        console.log(`   ❌ Failed: ${error.message}`);
        analysisResults.push({
          topK,
          success: false,
          error: error.message
        });
      }
    }

    this.generateAnalysisReport(analysisResults);
    return analysisResults;
  }

  estimateResourceUsage(topK) {
    if (topK === null) return 'Very High';
    if (topK <= 5) return 'Low';
    if (topK <= 15) return 'Medium';
    if (topK <= 25) return 'High';
    return 'Very High';
  }

  estimatePerformance(topK) {
    if (topK === null) return 'Slow';
    if (topK <= 5) return 'Fast';
    if (topK <= 15) return 'Good';
    if (topK <= 25) return 'Moderate';
    return 'Slow';
  }

  estimateQuality(topK) {
    if (topK === null) return 'Comprehensive';
    if (topK <= 3) return 'Precise';
    if (topK <= 10) return 'High';
    if (topK <= 20) return 'Good';
    return 'Comprehensive';
  }

  getRecommendation(topK) {
    if (topK === null) return 'Research and comprehensive analysis';
    if (topK <= 3) return 'High-precision applications';
    if (topK <= 10) return 'Balanced applications';
    if (topK <= 20) return 'Comprehensive coverage needs';
    return 'Extensive research applications';
  }

  generateAnalysisReport(results) {
    console.log('\n📋 Smart RAG Top K Analysis Report');
    console.log('==================================');
    
    const successful = results.filter(r => r.success);
    const failed = results.filter(r => !r.success);
    
    console.log(`Total tests: ${results.length}`);
    console.log(`Successful: ${successful.length}`);
    console.log(`Failed: ${failed.length}`);
    
    if (successful.length > 0) {
      console.log('\n🎯 Recommendations:');
      
      // Find optimal configurations
      const lowResource = successful.filter(r => ['Low', 'Medium'].includes(r.resourceEstimate));
      const highPerformance = successful.filter(r => ['Fast', 'Good'].includes(r.performanceEstimate));
      const highQuality = successful.filter(r => ['High', 'Precise', 'Comprehensive'].includes(r.qualityEstimate));
      
      if (lowResource.length > 0) {
        const optimal = lowResource.find(r => highPerformance.includes(r) && highQuality.includes(r));
        if (optimal) {
          console.log(`🎯 Optimal Configuration: Top K = ${optimal.topK}`);
          console.log(`   Balances resource usage, performance, and quality\n`);
        }
      }
    }
    
    if (failed.length > 0) {
      console.log('\n❌ Failed Configurations:');
      failed.forEach(f => {
        console.log(`   Top K = ${f.topK}: ${f.error}`);
      });
    }
  }
}

// Usage
const manager = new SmartRagConfigurationManager('my-rag-pipeline', 'YOUR_API_TOKEN');
manager.performTopKAnalysis('smart-rag-1748287628685').catch(console.error);

Python

import requests
import json
from typing import Optional, Dict, Any, List

def update_smart_rag_configuration(
    flow_name: str, 
    node_id: str, 
    config: Dict[str, Any], 
    api_token: str
) -> Dict[str, Any]:
    url = f"https://{flow_name}.flows.graphorlm.com/smart-rag/{node_id}"
    
    headers = {
        "Authorization": f"Bearer {api_token}",
        "Content-Type": "application/json"
    }
    
    payload = {"config": config}
    
    response = requests.patch(url, headers=headers, json=payload)
    response.raise_for_status()
    
    return response.json()

# Configuration examples
def demonstrate_smart_rag_configurations():
    api_token = "YOUR_API_TOKEN"
    flow_name = "my-rag-pipeline"
    node_id = "smart-rag-1748287628685"
    
    configurations = [
        {"name": "High Precision", "config": {"topK": 3}},
        {"name": "Balanced", "config": {"topK": 10}},
        {"name": "Comprehensive", "config": {"topK": 20}},
        {"name": "Unlimited", "config": {"topK": None}},
    ]
    
    for config_info in configurations:
        try:
            result = update_smart_rag_configuration(
                flow_name, node_id, config_info["config"], api_token
            )
            print(f"✅ {config_info['name']} configuration applied successfully")
            print(f"   Message: {result['message']}")
        except requests.exceptions.HTTPError as e:
            print(f"❌ Failed to apply {config_info['name']} configuration: {e}")

# Advanced configuration validator
class SmartRagConfigValidator:
    def __init__(self, flow_name: str, api_token: str):
        self.flow_name = flow_name
        self.api_token = api_token
        self.base_url = f"https://{flow_name}.flows.graphorlm.com"
    
    def validate_configuration(self, config: Dict[str, Any]) -> Dict[str, Any]:
        """Validate smart RAG configuration and provide recommendations"""
        validation_result = {
            "is_valid": True,
            "errors": [],
            "warnings": [],
            "recommendations": [],
            "resource_analysis": {},
            "performance_analysis": {}
        }
        
        top_k = config.get('topK')
        
        # Validate topK parameter
        if top_k is not None:
            if not isinstance(top_k, int):
                validation_result["errors"].append("topK must be an integer or null")
                validation_result["is_valid"] = False
            elif top_k <= 0:
                validation_result["errors"].append("topK must be greater than 0")
                validation_result["is_valid"] = False
            elif top_k == 1:
                validation_result["warnings"].append("topK = 1 may be too restrictive for most use cases")
            elif top_k > 50:
                validation_result["warnings"].append("topK > 50 may significantly impact performance and resource usage")
            elif top_k > 100:
                validation_result["errors"].append("topK > 100 is not recommended due to performance constraints")
                validation_result["is_valid"] = False
        
        # Resource analysis
        validation_result["resource_analysis"] = self._analyze_resource_usage(top_k)
        
        # Performance analysis  
        validation_result["performance_analysis"] = self._analyze_performance(top_k)
        
        # Generate recommendations
        validation_result["recommendations"] = self._generate_recommendations(top_k)
        
        return validation_result
    
    def _analyze_resource_usage(self, top_k: Optional[int]) -> dict:
        """Analyze resource usage implications of Top K setting"""
        if top_k is None:
            return {
                "level": "very_high",
                "description": "Unlimited processing - highest resource consumption",
                "relative_usage": "5x baseline"
            }
        elif top_k <= 5:
            return {
                "level": "low",
                "description": "Minimal resource consumption",
                "relative_usage": "1x baseline"
            }
        elif top_k <= 15:
            return {
                "level": "medium",
                "description": "Moderate resource consumption",
                "relative_usage": f"{top_k/5:.1f}x baseline"
            }
        elif top_k <= 30:
            return {
                "level": "high",
                "description": "High resource consumption",
                "relative_usage": f"{top_k/5:.1f}x baseline"
            }
        else:
            return {
                "level": "very_high",
                "description": "Very high resource consumption",
                "relative_usage": f"{top_k/5:.1f}x baseline"
            }
    
    def _analyze_performance(self, top_k: Optional[int]) -> dict:
        """Analyze performance implications of Top K setting"""
        if top_k is None:
            return {
                "speed": "slowest",
                "description": "Processes all documents - longest processing time",
                "estimated_time": "high"
            }
        elif top_k <= 5:
            return {
                "speed": "fastest",
                "description": "Minimal processing overhead",
                "estimated_time": "low"
            }
        elif top_k <= 15:
            return {
                "speed": "good",
                "description": "Balanced processing time",
                "estimated_time": "medium"
            }
        elif top_k <= 30:
            return {
                "speed": "moderate",
                "description": "Higher processing overhead",
                "estimated_time": "medium-high"
            }
        else:
            return {
                "speed": "slow",
                "description": "Significant processing overhead",
                "estimated_time": "high"
            }
    
    def _generate_recommendations(self, top_k: Optional[int]) -> List[str]:
        """Generate configuration recommendations based on Top K value"""
        recommendations = []
        
        if top_k is None:
            recommendations.extend([
                "Consider setting a specific Top K limit to control resource usage",
                "Use unlimited only for comprehensive research applications",
                "Monitor processing time and resource usage closely"
            ])
        elif top_k <= 3:
            recommendations.extend([
                "Excellent for high-precision applications",
                "Consider increasing if recall is important",
                "Monitor result completeness"
            ])
        elif top_k <= 10:
            recommendations.extend([
                "Good balance of precision and coverage",
                "Suitable for most general applications",
                "Monitor quality metrics for optimization"
            ])
        elif top_k <= 20:
            recommendations.extend([
                "Good for comprehensive coverage",
                "Monitor resource implications",
                "Consider if all results are actually needed"
            ])
        else:
            recommendations.extend([
                "Very high Top K - ensure this is necessary",
                "Consider breaking into multiple queries",
                "Monitor processing resource usage and time carefully"
            ])
        
        return recommendations
    
    def update_with_validation(self, node_id: str, config: Dict[str, Any]) -> Dict[str, Any]:
        """Update configuration with validation and confirmation"""
        # Validate configuration
        validation = self.validate_configuration(config)
        
        print("🔍 Configuration Validation Results:")
        print("=" * 40)
        
        if validation["errors"]:
            print("❌ Errors found:")
            for error in validation["errors"]:
                print(f"   • {error}")
            return {"success": False, "validation": validation}
        
        if validation["warnings"]:
            print("⚠️  Warnings:")
            for warning in validation["warnings"]:
                print(f"   • {warning}")
        
        print(f"\n⚡ Resource Analysis:")
        resource = validation["resource_analysis"]
        print(f"   Level: {resource['level']}")
        print(f"   Impact: {resource['description']}")
        print(f"   Relative Usage: {resource['relative_usage']}")
        
        print(f"\n⚡ Performance Analysis:")
        performance = validation["performance_analysis"]
        print(f"   Speed: {performance['speed']}")
        print(f"   Description: {performance['description']}")
        print(f"   Processing Time: {performance['estimated_time']}")
        
        # Ask for confirmation for high-impact configurations
        top_k = config.get('topK')
        if top_k is None or top_k > 20:
            response = input(f"\n⚠️  This configuration may have significant resource/performance impact. Continue? (y/N): ")
            if response.lower() != 'y':
                print("Configuration update cancelled.")
                return {"success": False, "cancelled": True}
        
        # Apply configuration
        try:
            result = update_smart_rag_configuration(
                self.flow_name, node_id, config, self.api_token
            )
            print(f"\n✅ Configuration updated successfully!")
            print(f"Message: {result['message']}")
            return {"success": True, "result": result, "validation": validation}
        except Exception as e:
            print(f"\n❌ Failed to update configuration: {e}")
            return {"success": False, "error": str(e)}
    
    def print_validation_summary(self, validation: Dict[str, Any]):
        """Print a summary of validation results"""
        print("\n📊 Configuration Summary:")
        print("-" * 25)
        
        if validation["is_valid"]:
            print("✅ Configuration is valid")
            print(f"⚡ Resources: {validation['resource_analysis']['level']}")
            print(f"⚡ Performance: {validation['performance_analysis']['speed']}")
        else:
            print("❌ Configuration has errors")
        
        if validation["recommendations"]:
            print(f"\n💡 Recommendations:")
            for rec in validation["recommendations"]:
                print(f"   • {rec}")

# Usage example
validator = SmartRagConfigValidator("my-rag-pipeline", "YOUR_API_TOKEN")

# Test different configurations
test_configs = [
    {"topK": 5},
    {"topK": 15},
    {"topK": 25},
    {"topK": None}
]

for config in test_configs:
    print(f"\n{'='*50}")
    print(f"Testing configuration: {config}")
    validation = validator.validate_configuration(config)
    validator.print_validation_summary(validation)

cURL

# Update smart RAG to high-precision mode
curl -X PATCH https://my-rag-pipeline.flows.graphorlm.com/smart-rag/smart-rag-1748287628685 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "topK": 5
    }
  }'

# Update smart RAG to balanced mode
curl -X PATCH https://my-rag-pipeline.flows.graphorlm.com/smart-rag/smart-rag-1748287628685 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "topK": 10
    }
  }'

# Update smart RAG to comprehensive mode
curl -X PATCH https://my-rag-pipeline.flows.graphorlm.com/smart-rag/smart-rag-1748287628685 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "topK": 20
    }
  }'

# Update smart RAG to unlimited mode
curl -X PATCH https://my-rag-pipeline.flows.graphorlm.com/smart-rag/smart-rag-1748287628685 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "topK": null
    }
  }'

# With response formatting using jq
curl -X PATCH https://my-rag-pipeline.flows.graphorlm.com/smart-rag/smart-rag-1748287628685 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "topK": 15
    }
  }' | jq '.'

Error Responses

Common Error Codes

Status Code	Description	Example Response
400	Bad Request - Invalid configuration parameters	`{"detail": "topK must be a positive integer or null"}`
401	Unauthorized - Invalid or missing API token	`{"detail": "Invalid authentication credentials"}`
404	Not Found - Flow or node not found	`{"detail": "Smart rag node with id 'invalid-id' not found in flow 'my-flow'"}`
422	Unprocessable Entity - Validation error	`{"detail": "Invalid configuration format"}`
500	Internal Server Error - Server error	`{"detail": "Failed to update smart rag node"}`

Error Response Format

{
  "detail": "Error message describing what went wrong"
}

Example Error Responses

Invalid Top K Value

{
  "detail": "topK must be a positive integer or null"
}

Node Not Found

{
  "detail": "Smart rag node with id 'invalid-node-id' not found in flow 'my-rag-pipeline'"
}

Invalid API Token

{
  "detail": "Invalid authentication credentials"
}

Best Practices

Configuration Guidelines

Start Conservative: Begin with lower Top K values (5-10) and adjust based on quality needs
Test Systematically: Use A/B testing to compare different Top K values
Monitor Impact: Track both quality improvements and resource implications
Document Rationale: Keep records of configuration decisions and their outcomes

Performance Considerations

Resource Optimization

Lower Top K: Reduces processing resource usage
Higher Top K: Increases quality but requires more resources
Unlimited: Maximum resource usage for complete analysis

Processing Time

Lower Top K: Faster processing, reduced latency
Higher Top K: Longer processing time, higher latency
Unlimited: Slowest processing, highest latency

Performance Optimization

Balance Quality vs Resources: Higher Top K improves quality but increases resource usage
Consider Use Case: Critical applications need fewer, higher-quality results
Monitor Processing Time: Higher Top K values increase processing time
Plan for Scale: Consider resource implications when scaling to high query volumes

Quality Assurance

Measure Impact: Compare result quality before and after reranking
User Feedback: Collect feedback on result relevance and usefulness
Regular Review: Periodically assess if Top K settings remain optimal
Context Matters: Adjust Top K based on query complexity and domain

Resource Management

Set Limits: Establish resource usage limits for processing
Monitor Usage: Track resource consumption across different Top K settings
Optimize Strategically: Use higher Top K only where quality impact justifies resource usage
Consider Alternatives: Evaluate if similar quality can be achieved with lower Top K

Troubleshooting

Invalid Configuration Parameters

Solution: Verify that:

topK is a positive integer or null
Value is reasonable for your use case (typically 1-50)
Configuration follows the correct JSON structure

Poor Quality After Update

Solution: If retrieval quality decreased:

Increase topK to include more diverse results
Check if input quality is sufficient
Monitor retrieval scores and positions
Consider if the change was too aggressive

Slow Processing After Update

Solution: If processing is too slow:

Reduce topK to process fewer documents
Check system performance metrics
Monitor system resource usage
Consider if unlimited processing is necessary

Configuration Not Taking Effect

Solution: After updating configuration:

Re-run the flow to apply new settings
Check that the node status shows updated: false
Verify configuration was saved correctly
Allow time for reprocessing to complete

High Resource Usage

Solution: For resource optimization:

Review topK settings across all smart RAG nodes
Monitor processing resource metrics
Consider reducing topK for less critical applications
Implement resource usage alerts and limits

Next Steps

After updating smart RAG configuration, you might want to:

List Smart RAG Nodes

View updated smart RAG node configurations and status

Run Flow

Execute your flow with the new smart RAG configuration

Monitor Performance

Track the impact of your configuration changes

Smart RAG Overview

Learn more about smart RAG node management

Get Started

Data API Options

RAG Pipelines API

​Overview

​Authentication

​Request Format

​Headers

​Path Parameters

​Request Body

​Configuration Parameters

​Example Request

​Response Format

​Success Response (200 OK)

​Response Fields

​Configuration Strategies

​Precision-Focused Strategy

​Balanced Strategy

​Comprehensive Strategy

​Unlimited Strategy

​Code Examples

​JavaScript/Node.js

​Advanced JavaScript Example

​Python

​cURL

​Error Responses

​Common Error Codes

​Error Response Format

​Example Error Responses

​Invalid Top K Value

​Node Not Found

​Invalid API Token

​Best Practices

​Configuration Guidelines

​Performance Considerations

​Resource Optimization

​Processing Time

​Performance Optimization

​Quality Assurance

​Resource Management

​Troubleshooting

​Next Steps

List Smart RAG Nodes

Run Flow

Monitor Performance

Smart RAG Overview

Overview

Authentication

Request Format

Headers

Path Parameters

Request Body

Configuration Parameters

Example Request

Response Format

Success Response (200 OK)

Response Fields

Configuration Strategies

Precision-Focused Strategy

Balanced Strategy

Comprehensive Strategy

Unlimited Strategy

Code Examples

JavaScript/Node.js

Advanced JavaScript Example

Python

cURL

Error Responses

Common Error Codes

Error Response Format

Example Error Responses

Invalid Top K Value

Node Not Found

Invalid API Token

Best Practices

Configuration Guidelines

Performance Considerations

Resource Optimization

Processing Time

Performance Optimization

Quality Assurance

Resource Management

Troubleshooting

Next Steps