feat: Add parallel tool calling support for Meta/Llama models

[fede-kamel]

Summary

Add support for parallel tool calling to enable models to execute multiple tools simultaneously, improving performance for multi-tool workflows.

Problem

The langchain-oracle SDK did not expose the OCI API's is_parallel_tool_calls parameter, forcing sequential tool execution even when tools could run in parallel.

Solution

Implemented hybrid approach allowing both class-level defaults and per-binding overrides:

# Option 1: Class-level default
llm = ChatOCIGenAI(
    model_id="meta.llama-3.3-70b-instruct",  # Works with Meta, Llama, Grok, OpenAI, Mistral
    parallel_tool_calls=True
)

# Option 2: Per-binding override
llm_with_tools = llm.bind_tools(
    [tool1, tool2, tool3],
    parallel_tool_calls=True
)

Changes

• Add parallel_tool_calls parameter to OCIGenAIBase (default: False)
• Update bind_tools() method to accept parallel_tool_calls parameter
• Update GenericProvider to pass is_parallel_tool_calls to OCI API
• Add validation for Cohere models (raises clear error)
• Add comprehensive documentation and examples

Testing

Unit Tests (9/9 passing)

• Class-level parameter setting
• Default behavior verification
• Explicit True/False in bind_tools
• Class default usage and override
• Parameter passed to OCI API
• Cohere model validation

Integration Tests (4/4 passing)

• Parallel tool calling enabled
• Sequential tool calling (baseline)
• bind_tools override functionality
• Cohere model error handling

All tests verified with live OCI GenAI API.

Backward Compatibility

✅ Fully backward compatible

• Default value is False (existing behavior)
• Opt-in feature
• No changes required to existing code

Benefits

• Performance: Faster execution for multi-tool workflows
• Flexibility: Both global defaults and per-binding control
• Safety: Clear validation and error messages
• Consistency: Follows existing parameter patterns

Model Support

Supported (GenericChatRequest models):

• Meta Llama 3.1, 3.2, 3.3, 4.x
• xAI Grok 3, 3 Mini, 4, 4 Fast
• OpenAI gpt-oss models
• Mistral models
• Any model using GenericChatRequest

Unsupported:

• Cohere models (CohereChatRequest - clear error message provided)

[fede-kamel]

🔍 Verification: is_parallel_tool_calls is Meta/Llama Only

Verified through OCI API documentation that is_parallel_tool_calls is only available for Meta/Llama models, not Cohere.

API Documentation Findings

GenericChatRequest (Meta/Llama models):

• ✅ Has is_parallel_tool_calls parameter
• Type: bool
• Description: "Whether to enable parallel function calling during tool use"
• Used by: Meta Llama models (e.g., meta.llama-3.3-70b-instruct)
• Reference: https://docs.oracle.com/en-us/iaas/tools/python/2.162.0/api/generative_ai_inference/models/oci.generative_ai_inference.models.GenericChatRequest.html

CohereChatRequest (Cohere models):

• ❌ Does NOT have is_parallel_tool_calls parameter
• Has different tool parameters: tools, tool_results, is_force_single_step
• is_force_single_step: Makes model issue (potentially multiple) tool calls in single step (different concept)
• Used by: Cohere Command models (e.g., cohere.command-r-plus)
• Reference: https://docs.oracle.com/en-us/iaas/tools/python/2.160.2/api/generative_ai_inference/models/oci.generative_ai_inference.models.CohereChatRequest.html

Conclusion

The implementation correctly restricts parallel_tool_calls to Meta/Llama models because:

1. OCI API limitation - Parameter doesn't exist in CohereChatRequest
2. Clear error handling - Our code raises ValueError when attempted with Cohere
3. Accurate documentation - README and docstrings note "Meta/Llama models only"

This is an OCI platform limitation, not a langchain-oracle implementation choice.

Future Support

If OCI adds is_parallel_tool_calls to CohereChatRequest in the future, we can extend support by:

1. Removing the Cohere validation check
2. Adding parameter passing in CohereProvider
3. Updating documentation

For now, Meta/Llama only is correct and properly documented.