fix(oci): sanitize tool JSON Schema for Gemini Proto validator

[fede-kamel]

Summary

OCI's V1 OpenAI-compat transport (OCIChatCompletionsModel) serves every non-Cohere-R / non-DAC model on OCI, including google.gemini-*. Pydantic emits type: ["string", "null"] for Optional[str] and type: "any" for Any — both rejected by Gemini's Proto schema validator with a hard 400 before the model gets a turn:

400 Bad Request: Unknown name 'type' at
'tools[0].function_declarations[N].parameters.properties[M].value...':
Proto field is not repeating, cannot start list.

This PR ports the validated sanitisation pattern from Oracle's own langchain-oci (OCIUtils.sanitize_schema in libs/oci/langchain_oci/common/utils.py) into Locus, so every tool's function.parameters schema is normalised before the V1 call leaves Locus.

Fixes #281.

What changed (commit 88c4d79)

New helper — locus.core.structured.sanitize_oci_tool_schema():

• Collapses type: ["string", "null"] → first non-null type (Gemini's Proto requires a single string).
• Remaps type: "any" → "object" (Gemini doesn't know "any").
• Strips metadata keys OCI rejects on tool params: title, const, default: None, any x-* namespace.
• Promotes const: "x" → enum: ["x"] (OCI accepts enum, not const).
• Defaults missing items → {"type": "object"} when type == "array".
• Recurses through properties / $defs / definitions as dicts of named sub-schemas, so user-defined field names (e.g. a field literally named title) survive even though schema-level title is stripped.

Wiring — OCIChatCompletionsModel._sanitize_tools_for_oci() is invoked from both complete() and stream(), applied unconditionally to tools[*].function.parameters. Matches langchain-oci's design — the stripped keys are pure metadata that non-Gemini vendors ignore.

Removed — the earlier speculative _requires_gemini_schema_strip + _munge_response_format_for_gemini keyword strip (vendor-gated additionalProperties / patternProperties / dependencies). It was targeting a different OCI endpoint and didn't match the observed bug shape. The now-validated $ref inline for Gemini response_format is preserved.

Drive-by (commit 6ee95fc) — chore(deps): cap starlette <1.2

The first CI run on this PR failed with ModuleNotFoundError: No module named 'httpx2' in tests/unit/test_a2a_protocol.py and tests/unit/test_server_app_full.py. Neither file is touched by the #281 work.

Root cause: starlette 1.2.0 was published on 2026-05-28 (between main's last green CI at 11:35Z and this PR's first CI run at 12:03Z) and makes its TestClient require httpx2 instead of httpx. Locus pins httpx<1.0 (because OCIRequestSigner and BearerAuth subclass the soon-removed top-level httpx.Auth), so the resolver can't satisfy starlette 1.2's TestClient transitively.

Capped starlette<1.2 alongside the existing httpx<1.0 pin; verified the 102 affected tests collect + pass under starlette 1.0.0. Lift both pins together when the auth classes are ported to httpx 2.x.

If you'd prefer the dep pin in its own PR, happy to split — but bundling unblocks CI on this one in the same round-trip.

Why mirror langchain-oci

The langchain-oci package ships Oracle's own LangChain integration against the same OCI Generative AI endpoint Locus's V1 transport hits. Its sanitize_schema is the reference pattern used in production by every Oracle-hosted LangChain agent. Re-deriving the sanitiser independently would just create a parallel set of mistakes; copying the proven pattern keeps the bug surface narrow.

Tests

Unit (tests/unit/test_oci_tool_schema_sanitize.py, 12 tests, all passing):

• test_optional_field_collapses_type_list_to_single_string — Pydantic-generated Optional[str] schema clears the sanitiser.
• test_explicit_type_list_collapses_to_first_non_null — handcrafted ["string","null"] / ["null","number"] / degenerate ["null"].
• test_type_any_normalises_to_object.
• test_metadata_keys_stripped — title/const/x-*/default:None all gone; const: "search" promoted to enum.
• test_user_field_named_title_survives_recursion — defends the properties/$defs recursion seam.
• test_array_without_items_gets_default_items.
• test_does_not_mutate_input.
• test_nested_recursion_through_items_properties — the exact deepest-nesting shape from the issue's error path.
• 4 wiring tests on _sanitize_tools_for_oci: applies to each tool, returns None/[] for empty inputs, passes through non-function tools, doesn't mutate caller's list.

Integration (tests/integration/test_oci_gemini_tool_schema_live.py, gated by RUN_LIVE_OCI=1):

• test_gemini_accepts_optional_field_tool_schema — sends a tool with Optional[str], Optional[int], Any, and a nested array-of-objects to real Gemini 2.5 Flash; pre-fix raised 400, post-fix completes.
• test_gemini_accepts_clean_schema_unchanged — control: a tool with no Optional fields still works (sanitiser is idempotent on clean schemas).

Both integration tests verified live against oci:google.gemini-2.5-flash in us-chicago-1.

Regression sweep: 149 OCI-related unit tests passing (test_oci_*.py + test_tools_*.py), no breakage from removing the speculative response_format strip.

Test plan

• uv run pytest tests/unit/test_oci_tool_schema_sanitize.py -v — 12/12
• RUN_LIVE_OCI=1 uv run pytest tests/integration/test_oci_gemini_tool_schema_live.py -v — 2/2 live against real Gemini
• uv run pytest tests/unit/test_oci_openai_compat*.py tests/unit/test_tools_*.py — 149/149, no regressions
• uv run pytest tests/unit/test_a2a_protocol.py tests/unit/test_server_app_full.py — 102/102 with starlette<1.2 pin
• Pre-commit (ruff lint + format + mypy + codespell + commitizen + DCO sign-off) — passing on both commits