1
+"""Cross-provider ``$ref`` handling contract.
2
+
3
+Every provider under ``python/providers`` must be classified here. A provider
4
+either resolves internal ``$ref``/``$defs`` pointers before translating the
5
+schema for its framework, or forwards the schema whole to a vendor that
6
+resolves references natively. Adding a provider without classifying it fails
7
+the suite, so the taxonomy is a build gate rather than tribal knowledge.
8
+
9
+The test reads source text instead of importing the providers: importing all
10
+of them would make every vendor SDK a test dependency of the core package.
11
+Behavioral assertions live next to each provider (for example
12
+``tests/test_google_provider.py``); this test owns completeness.
13
+
14
+TypeScript counterpart: ``ts/packages/core/test/providers/refContract.test.ts``.
15
+"""
16
+
17
+from __future__ import annotations
18
+
19
+import typing as t
20
+from dataclasses import dataclass
21
+from pathlib import Path
22
+
23
+import pytest
24
+
25
+REPO_ROOT = Path(__file__).resolve().parents[2]
26
+PROVIDERS_DIR = REPO_ROOT / "python" / "providers"
27
+
28
+# Helpers that inline internal references before schema translation.
29
+# ``alias_tool_input_schema`` and ``substitute_reserved_python_keywords``
30
+# call ``dereference_json_schema`` internally. ``json_schema_to_model`` is
31
+# not one of them: it types a referenced property as ``Any``.
32
+RESOLVER_HELPERS: t.Final = (
33
+ "dereference_json_schema",
34
+ "alias_tool_input_schema",
35
+ "substitute_reserved_python_keywords",
36
+)
37
+
38
+
39
+@dataclass(frozen=True)
40
+class Classification:
41
+ """How a provider treats a tool's input schema."""
42
+
43
+ treatment: t.Literal["resolves-refs", "passthrough"]
44
+ reason: str
45
+ # Helper the provider relies on; required for ``resolves-refs``.
46
+ via: t.Optional[str] = None
47
+
48
+
49
+PROVIDER_PACKAGES: t.Final[dict[str, Classification]] = {
50
+ "anthropic": Classification(
51
+ "resolves-refs",
52
+ "aliases property keys, which requires keys behind a ref to be materialized",
53
+ via="alias_tool_input_schema",
54
+ ),
55
+ "autogen": Classification(
56
+ "resolves-refs",
57
+ "builds a Python signature from properties, so refs must be inlined first",
58
+ via="substitute_reserved_python_keywords",
59
+ ),
60
+ "claude_agent_sdk": Classification(
61
+ "resolves-refs",
62
+ "aliases property keys before building the MCP tool schema",
63
+ via="alias_tool_input_schema",
64
+ ),
65
+ "crewai": Classification(
66
+ "resolves-refs",
67
+ "converts to a Pydantic model; the converter types a $ref property as Any",
68
+ via="dereference_json_schema",
69
+ ),
70
+ "gemini": Classification(
71
+ "resolves-refs",
72
+ "aliases property keys and converts to a Pydantic model",
73
+ via="alias_tool_input_schema",
74
+ ),
75
+ "google": Classification(
76
+ "resolves-refs",
77
+ "rebuilds the root from properties/required; Vertex FunctionDeclaration "
78
+ "has no ref/defs field",
79
+ via="dereference_json_schema",
80
+ ),
81
+ "google_adk": Classification(
82
+ "resolves-refs",
83
+ "builds a Python signature from properties, so refs must be inlined first",
84
+ via="alias_tool_input_schema",
85
+ ),
86
+ "langchain": Classification(
87
+ "resolves-refs",
88
+ "builds a Pydantic args schema from properties",
89
+ via="substitute_reserved_python_keywords",
90
+ ),
91
+ "langgraph": Classification(
92
+ "resolves-refs",
93
+ "builds a Pydantic args schema from properties",
94
+ via="substitute_reserved_python_keywords",
95
+ ),
96
+ "llamaindex": Classification(
97
+ "resolves-refs",
98
+ "builds a Python signature from properties, so refs must be inlined first",
99
+ via="substitute_reserved_python_keywords",
100
+ ),
101
+ "openai": Classification(
102
+ "passthrough",
103
+ "re-exports the core OpenAI providers, which forward the whole schema",
104
+ ),
105
+ "openai_agents": Classification(
106
+ "passthrough",
107
+ "forwards the whole schema; OpenAI resolves $defs/$ref natively",
108
+ ),
109
+}
110
+
111
+# Sources outside ``python/providers`` that hand schemas to a vendor.
112
+EXTRA_PASSTHROUGH_SOURCES: t.Final[dict[str, str]] = {
113
+ "python/composio/core/provider/_openai.py": "forwards the whole schema",
114
+ "python/composio/core/provider/_openai_responses.py": "forwards the whole schema",
115
+}
116
+
117
+
118
+def _discover_providers() -> list[str]:
119
+ return sorted(
120
+ entry.name
121
+ for entry in PROVIDERS_DIR.iterdir()
122
+ if entry.is_dir() and (entry / "pyproject.toml").is_file()
123
+ )
124
+
125
+
126
+def _provider_source(provider: str) -> str:
127
+ package_dirs = [
128
+ entry
129
+ for entry in (PROVIDERS_DIR / provider).iterdir()
130
+ if entry.is_dir() and entry.name.startswith("composio_")
131
+ ]
132
+ assert package_dirs, f"no composio_* package under providers/{provider}"
133
+ return "\n".join(
134
+ path.read_text(encoding="utf-8")
135
+ for package_dir in package_dirs
136
+ for path in sorted(package_dir.rglob("*.py"))
137
+ )
138
+
139
+
140
+DISCOVERED: t.Final = _discover_providers()
141
+
142
+
143
+def test_discovers_provider_packages() -> None:
144
+ # Guards the test itself: a broken path would make everything below
145
+ # vacuously pass.
146
+ assert len(DISCOVERED) >= 12
147
+
148
+
149
+def test_classifies_every_provider_package() -> None:
150
+ assert [name for name in DISCOVERED if name not in PROVIDER_PACKAGES] == []
151
+
152
+
153
+def test_does_not_classify_removed_providers() -> None:
154
+ assert [name for name in PROVIDER_PACKAGES if name not in DISCOVERED] == []
155
+
156
+
157
+@pytest.mark.parametrize(
158
+ "provider",
159
+ [n for n, c in PROVIDER_PACKAGES.items() if c.treatment == "resolves-refs"],
160
+)
161
+def test_resolves_refs_before_translation(provider: str) -> None:
162
+ classification = PROVIDER_PACKAGES[provider]
163
+ assert classification.via in RESOLVER_HELPERS, classification.reason
164
+ assert classification.via in _provider_source(provider), classification.reason
165
+
166
+
167
+@pytest.mark.parametrize(
168
+ "provider",
169
+ [n for n, c in PROVIDER_PACKAGES.items() if c.treatment == "passthrough"],
170
+)
171
+def test_forwards_schema_whole(provider: str) -> None:
172
+ classification = PROVIDER_PACKAGES[provider]
173
+ assert classification.via is None
174
+ source = _provider_source(provider)
175
+ assert [h for h in RESOLVER_HELPERS if h in source] == [], classification.reason
176
+
177
+
178
+@pytest.mark.parametrize("relative_path", sorted(EXTRA_PASSTHROUGH_SOURCES))
179
+def test_extra_sources_forward_schema_whole(relative_path: str) -> None:
180
+ path = REPO_ROOT / relative_path
181
+ assert path.is_file(), f"{relative_path} not found; update this test"
182
+ source = path.read_text(encoding="utf-8")
183
+ assert [h for h in RESOLVER_HELPERS if h in source] == []