Automatic Model Selection

Upsonic Agent Framework includes an intelligent model selection system that automatically recommends the most appropriate AI model for your specific task. This feature helps you optimize performance, cost, and speed by selecting the best model based on task requirements and constraints.

Model selection system may recommend models from various providers (OpenAI, Anthropic, Google, etc.). Ensure you have the required API keys configured for the recommended model’s provider before using it. If authentication is not set up for the recommended model, the agent will fail at runtime. Always verify you have the necessary credentials, or use the preferred_provider criteria to limit recommendations to providers you have configured.

Overview

Automatic model selection system analyzes your task description and selection criteria to recommend the most suitable model from a comprehensive registry of leading AI models including OpenAI, Anthropic, Google, Meta, DeepSeek, Qwen, Mistral, Cohere, and Grok models.

Key Features

Intelligent Analysis: Automatically detects task requirements (reasoning, coding, math, vision, etc.)
Dual Selection Methods: Choose between fast rule-based or advanced LLM-based selection
Comprehensive Model Registry: Access to 15+ top-tier AI models with detailed metadata
Flexible Criteria: Specify constraints like cost, speed, context window, and capabilities
Confidence Scoring: Get confidence scores and alternative recommendations
Seamless Integration: Use recommendations directly with your agent

Selection Methods

The framework provides two approaches to model selection:

Rule-Based Selection (Default)

Fast, deterministic selection using keyword analysis and scoring algorithms. Ideal for most use cases.

✅ Fast: No additional API calls required
✅ Cost-Effective: No LLM usage for selection
✅ Predictable: Consistent results based on rules
❌ Limited Context: May miss nuanced requirements

LLM-Based Selection (Advanced)

Uses GPT-4o to analyze your task and intelligently select the best model. Recommended for complex or ambiguous tasks.

✅ Intelligent: Deep understanding of task nuances
✅ Context-Aware: Considers subtle requirements
✅ Adaptive: Better handling of complex scenarios
❌ Slower: Requires additional API call
❌ Cost: Uses tokens for selection process

Basic Usage

Simple Recommendation

Get a model recommendation for any task description:

from upsonic import Agent

agent = Agent()

# Get recommendation (rule-based by default)
recommendation = agent.recommend_model_for_task(
    "Write a complex sorting algorithm in Python with detailed explanations"
)

print(f"Recommended: {recommendation.model_name}")
print(f"Reason: {recommendation.reason}")
print(f"Confidence: {recommendation.confidence_score:.2f}")
print(f"Alternatives: {recommendation.alternative_models}")

Using the Recommendation

Once you have a recommendation, use it to execute your task:

from upsonic import Agent, Task

agent = Agent()
task = Task("Solve this complex mathematical proof: prove that sqrt(2) is irrational")

# Get recommendation
recommendation = agent.recommend_model_for_task(task)
print(f"Recommended model: {recommendation.model_name}")

# Use recommended model
result = agent.do(task, model=recommendation.model_name)
print(result)

Advanced Usage with Criteria

Specifying Selection Criteria

Use SelectionCriteria to define specific requirements and constraints:

from upsonic import Agent, Task

agent = Agent()

# Define specific criteria
criteria = {
    "requires_code_generation": True,
    "requires_math": True,
    "prioritize_quality": True,
    "max_cost_tier": 7,
    "min_context_window": 100000
}

recommendation = agent.recommend_model_for_task(
    task="Implement a machine learning algorithm with mathematical proofs",
    criteria=criteria
)

print(f"Selected: {recommendation.model_name}")
print(f"Cost Tier: {recommendation.estimated_cost_tier}/10")
print(f"Speed Tier: {recommendation.estimated_speed_tier}/10")

# Use the recommended model
task = Task("Implement a machine learning algorithm with mathematical proofs")
result = agent.do(task, model=recommendation.model_name)
print(result)

LLM-Based Selection

Enable LLM-based selection for more intelligent recommendations:

from upsonic import Agent, Task

agent = Agent()

# Use LLM for intelligent selection
recommendation = agent.recommend_model_for_task(
    task="Analyze customer sentiment in multilingual support tickets",
    use_llm=True  # Enable LLM-based selection
)

print(f"Method: {recommendation.selection_method}")  # "llm"
print(f"Selected: {recommendation.model_name}")

# Use the recommended model
task = Task("Analyze customer sentiment in multilingual support tickets")
result = agent.do(task, model=recommendation.model_name)
print(result)

Async Model Recommendation

For async workflows, use the async version:

from upsonic import Agent, Task
import asyncio

async def main():
    agent = Agent()
    
    recommendation = await agent.recommend_model_for_task_async(
        task="Process and analyze 500 page legal document",
        criteria={"requires_long_context": True, "min_context_window": 200000}
    )
    
    print(f"For long documents: {recommendation.model_name}")
    
    # Use the recommended model
    task = Task("Summarize the key legal provisions in this document")
    result = agent.do(task, model=recommendation.model_name)
    print(result)

asyncio.run(main())

Selection Criteria Reference

Configure model selection with these criteria parameters:

Criteria	Type	Default	Description
requires_reasoning	bool \| None	None	Task needs advanced reasoning capabilities
requires_code_generation	bool \| None	None	Task involves writing or analyzing code
requires_math	bool \| None	None	Task requires mathematical problem solving
requires_creative_writing	bool \| None	None	Task needs creative content generation
requires_vision	bool \| None	None	Task processes images or visual content
requires_audio	bool \| None	None	Task processes audio content
requires_long_context	bool \| None	None	Task needs large context window
prioritize_speed	bool	False	Optimize for fast inference
prioritize_cost	bool	False	Optimize for cost-effectiveness
prioritize_quality	bool	False	Optimize for output quality
max_cost_tier	int \| None	None	Maximum acceptable cost (1-10, where 10=expensive)
min_context_window	int \| None	None	Minimum required context window in tokens
preferred_provider	str \| None	None	Preferred provider (e.g., “openai”, “anthropic”)
require_open_source	bool	False	Require open-source model
require_production_ready	bool	False	Require production-ready model

Model Recommendation Output

The ModelRecommendation object provides comprehensive information:

from upsonic import Agent, Task

agent = Agent()

recommendation = agent.recommend_model_for_task("Analyze financial data and create investment recommendations")

# Access recommendation properties
print(f"Model: {recommendation.model_name}")           # e.g., "openai/gpt-4o"
print(f"Reason: {recommendation.reason}")               # Explanation for selection
print(f"Confidence: {recommendation.confidence_score}")     # 0.0 to 1.0
print(f"Alternatives: {recommendation.alternative_models}")   # List of alternatives
print(f"Cost Tier: {recommendation.estimated_cost_tier}")  # 1-10 scale
print(f"Speed Tier: {recommendation.estimated_speed_tier}") # 1-10 scale
print(f"Method: {recommendation.selection_method}")     # "rule_based" or "llm"

# Use the recommendation
task = Task("Analyze financial data and create investment recommendations")
result = agent.do(task, model=recommendation.model_name)
print(result)

Complete Example: Multi-Task Workflow

Here’s a comprehensive example showing model selection for different task types:

from upsonic import Agent, Task

# Create agent with default model selection settings
agent = Agent(
    model="openai/gpt-4o-mini",  # Default model
    debug=True
)

# Task 1: Complex reasoning task
reasoning_task = Task(
    "Analyze this complex business scenario and provide strategic recommendations..."
)

reasoning_rec = agent.recommend_model_for_task(
    reasoning_task,
    criteria={
        "requires_reasoning": True,
        "prioritize_quality": True
    }
)
print(f"For reasoning: {reasoning_rec.model_name}")
result1 = agent.do(reasoning_task, model=reasoning_rec.model_name)
print(f"Result: {result1}")

# Task 2: Cost-sensitive chatbot
chatbot_task = Task("Generate a friendly greeting for our banking app users")

chatbot_rec = agent.recommend_model_for_task(
    chatbot_task,
    criteria={
        "prioritize_cost": True,
        "prioritize_speed": True,
        "max_cost_tier": 3
    }
)
print(f"For chatbot: {chatbot_rec.model_name}")
result2 = agent.do(chatbot_task, model=chatbot_rec.model_name)
print(f"Result: {result2}")

# Task 3: Code generation
code_task = Task("Write a high-performance sorting algorithm in Python")

code_rec = agent.recommend_model_for_task(
    code_task,
    criteria={"requires_code_generation": True},
    use_llm=True  # Use LLM for better understanding
)
print(f"For coding: {code_rec.model_name}")
result3 = agent.do(code_task, model=code_rec.model_name)
print(f"Result: {result3}")

# Task 4: Long document analysis
document_task = Task("Analyze and summarize this 300-page financial report")

document_rec = agent.recommend_model_for_task(
    document_task,
    criteria={
        "requires_long_context": True,
        "min_context_window": 200000,
        "requires_reasoning": True
    }
)
print(f"For documents: {document_rec.model_name}")
result4 = agent.do(document_task, model=document_rec.model_name)
print(f"Result: {result4}")

Agent-Level Configuration

Configure default selection behavior at agent initialization:

from upsonic import Agent, Task

# Agent with default selection criteria
agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    model_selection_criteria={
        "prioritize_cost": True,
        "max_cost_tier": 5,
        "require_production_ready": True
    },
    use_llm_for_selection=False  # Use rule-based by default
)

# Now recommendations use these defaults
task_description = "Generate a summary of quarterly sales data"
recommendation = agent.recommend_model_for_task(task_description)
print(f"Recommended (with cost constraints): {recommendation.model_name}")

# Execute with recommended model
task = Task(task_description)
result = agent.do(task, model=recommendation.model_name)
print(result)

Best Practices

Start with Rule-Based: Use rule-based selection for most tasks - it’s fast and effective
Use LLM for Ambiguity: Enable LLM-based selection for complex or ambiguous requirements
Set Cost Limits: Always specify max_cost_tier for production applications
Check Alternatives: Review alternative models for flexibility and fallback options
Monitor Confidence: Low confidence scores (< 0.7) suggest reviewing criteria or task description
Context Windows: For long documents, always check min_context_window requirements
Production Safety: Use require_production_ready=True for business-critical applications
Provider Preferences: Specify preferred_provider if you have existing infrastructure
Test Recommendations: Validate model performance with your specific use cases
Cache Recommendations: Store recommendations for similar tasks to avoid repeated selection

Supported Models

The framework includes comprehensive metadata for:

OpenAI: GPT-4o, GPT-4o-mini, O1-Pro, O1-mini
Anthropic: Claude 4 Opus, Claude 3.7 Sonnet, Claude 3.5 Haiku
Google: Gemini 2.5 Pro, Gemini 2.5 Flash
Meta: Llama 3.3 70B
DeepSeek: DeepSeek-Reasoner, DeepSeek-Chat
Qwen: Qwen 3 235B
Mistral: Mistral Large, Mistral Small
Cohere: Command R+
Grok: Grok 4

Each model includes benchmark scores (MMLU, HumanEval, MATH, etc.), capabilities, cost/speed tiers, and use case recommendations.

Common Use Cases

Banking & Finance

from upsonic import Agent, Task

agent = Agent(model="openai/gpt-4o-mini")

recommendation = agent.recommend_model_for_task(
    "Perform risk assessment and regulatory compliance analysis",
    criteria={
        "requires_reasoning": True,
        "requires_math": True,
        "prioritize_quality": True,
        "require_production_ready": True
    }
)

print(f"Recommended model for banking: {recommendation.model_name}")
print(f"Reason: {recommendation.reason}")

# Use the recommended model
task = Task("Analyze the risk profile of a mortgage portfolio")
result = agent.do(task, model=recommendation.model_name)
print(result)

Customer Support

from upsonic import Agent, Task

agent = Agent(model="openai/gpt-4o-mini")

recommendation = agent.recommend_model_for_task(
    "Handle customer inquiries in real-time chat",
    criteria={
        "prioritize_speed": True,
        "prioritize_cost": True,
        "max_cost_tier": 3
    }
)

print(f"Recommended model for support: {recommendation.model_name}")
print(f"Reason: {recommendation.reason}")

# Use the recommended model
task = Task("Respond to a customer asking about account balance")
result = agent.do(task, model=recommendation.model_name)
print(result)

Research & Development

from upsonic import Agent, Task

agent = Agent(model="openai/gpt-4o-mini")

recommendation = agent.recommend_model_for_task(
    "Solve complex mathematical proofs",
    criteria={
        "requires_reasoning": True,
        "requires_math": True,
        "prioritize_quality": True
    },
    use_llm=True
)

print(f"Recommended model for R&D: {recommendation.model_name}")
print(f"Reason: {recommendation.reason}")

# Use the recommended model
task = Task("Prove that the sum of angles in a triangle equals 180 degrees")
result = agent.do(task, model=recommendation.model_name)
print(result)

The automatic model selection system empowers your AI agent framework to dynamically optimize model usage based on task requirements, delivering the best balance of performance, cost, and speed for your specific banking and fintech applications.

GET STARTED

CONCEPTS

STARTING AN AGENT PROJECT

READY TO USE SNIPPETS

DEPLOYMENT

FURTHER READINGS

Automatic Model Selection

Overview

Key Features

Selection Methods

Rule-Based Selection (Default)

LLM-Based Selection (Advanced)

Basic Usage

Simple Recommendation

Using the Recommendation

Advanced Usage with Criteria

Specifying Selection Criteria

LLM-Based Selection

Async Model Recommendation

Selection Criteria Reference

Model Recommendation Output

Complete Example: Multi-Task Workflow

Agent-Level Configuration

Best Practices

Supported Models

Common Use Cases

Banking & Finance

Customer Support

Research & Development

​Overview

​Key Features

​Selection Methods

​Rule-Based Selection (Default)

​LLM-Based Selection (Advanced)

​Basic Usage

​Simple Recommendation

​Using the Recommendation

​Advanced Usage with Criteria

​Specifying Selection Criteria

​LLM-Based Selection

​Async Model Recommendation

​Selection Criteria Reference

​Model Recommendation Output

​Complete Example: Multi-Task Workflow

​Agent-Level Configuration

​Best Practices

​Supported Models

​Common Use Cases

​Banking & Finance

​Customer Support

​Research & Development

Overview

Key Features

Selection Methods

Rule-Based Selection (Default)

LLM-Based Selection (Advanced)

Basic Usage

Simple Recommendation

Using the Recommendation

Advanced Usage with Criteria

Specifying Selection Criteria

LLM-Based Selection

Async Model Recommendation

Selection Criteria Reference

Model Recommendation Output

Complete Example: Multi-Task Workflow

Agent-Level Configuration

Best Practices

Supported Models

Common Use Cases

Banking & Finance

Customer Support

Research & Development