(bug) Harden OCI tool schema conversion for cross-model tool-calling reliability

[fede-kamel]

Summary

Harden OCI tool schema conversion before provider-specific tool conversion.

Closes #156.

Why this change exists

OCI tool calling is only as reliable as the schema we send to the backend. The shared conversion path already resolves some schema features, but it still allows a few invalid or noisy constructs through.

That creates two practical problems:

• correctness risk, where OCI receives an internally inconsistent schema
• reliability risk, where models see extra schema noise or underspecified shapes and produce worse tool-call arguments

This shows up most clearly with stricter models such as Gemini, but it is not a Gemini-only problem. Meta, Cohere, Grok, and GPT-family models also benefit when the tool schema is smaller, internally consistent, and OCI-safe.

Fixing this in the common OCI conversion layer is higher-value than leaving downstream applications to patch tool schemas individually.

What changed

• add a shared schema sanitization step in langchain_oci.common.utils
• prune required entries that no longer exist in properties
• remove recursive title and default: null metadata
• normalize type: any and nullable type arrays
• ensure arrays always declare an items schema
• handle circular $ref chains defensively
• apply the sanitizer in both Generic and Cohere tool conversion paths

Value

This improves the shared OCI integration across model families:

• fewer invalid schemas at the OCI boundary
• less schema noise sent to the model
• more consistent tool definitions across Gemini, Meta, Cohere, Grok, and GPT-family models
• less need for downstream application-level schema cleanup shims

Validation

Unit coverage:

• python -m pytest tests/unit_tests/chat_models/test_tool_schema_constraints.py

Integration coverage:

• python -m pytest tests/integration_tests/chat_models/test_tool_schema_constraints.py

Live OCI validation:

• Gemini: schema conversion and tool-calling constraints verified
• Meta: schema conversion and tool-calling constraints verified
• Cohere: schema conversion and tool-calling constraints verified
• Grok: schema conversion and tool-calling constraints verified
• GPT-family: schema conversion and tool-calling constraints verified

Non-goals

This PR does not change:

• ToolMessage handling
• message ordering rules
• model-specific runtime behavior

Those should stay in follow-up PRs.