@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 03:37 UTC

next
py 189 lines 6.58 KB
Raw
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="alias_tool_input_schema",
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 "typesafe": Classification(
110 "resolves-refs",
111 "compiles each property into questions, so an enum behind a ref must be "
112 "materialized to be asked",
113 via="dereference_json_schema",
114 ),
115 }
116
117 # Sources outside ``python/providers`` that hand schemas to a vendor.
118 EXTRA_PASSTHROUGH_SOURCES: t.Final[dict[str, str]] = {
119 "python/composio/core/provider/_openai.py": "forwards the whole schema",
120 "python/composio/core/provider/_openai_responses.py": "forwards the whole schema",
121 }
122
123
124 def _discover_providers() -> list[str]:
125 return sorted(
126 entry.name
127 for entry in PROVIDERS_DIR.iterdir()
128 if entry.is_dir() and (entry / "pyproject.toml").is_file()
129 )
130
131
132 def _provider_source(provider: str) -> str:
133 package_dirs = [
134 entry
135 for entry in (PROVIDERS_DIR / provider).iterdir()
136 if entry.is_dir() and entry.name.startswith("composio_")
137 ]
138 assert package_dirs, f"no composio_* package under providers/{provider}"
139 return "\n".join(
140 path.read_text(encoding="utf-8")
141 for package_dir in package_dirs
142 for path in sorted(package_dir.rglob("*.py"))
143 )
144
145
146 DISCOVERED: t.Final = _discover_providers()
147
148
149 def test_discovers_provider_packages() -> None:
150 # Guards the test itself: a broken path would make everything below
151 # vacuously pass.
152 assert len(DISCOVERED) >= 12
153
154
155 def test_classifies_every_provider_package() -> None:
156 assert [name for name in DISCOVERED if name not in PROVIDER_PACKAGES] == []
157
158
159 def test_does_not_classify_removed_providers() -> None:
160 assert [name for name in PROVIDER_PACKAGES if name not in DISCOVERED] == []
161
162
163 @pytest.mark.parametrize(
164 "provider",
165 [n for n, c in PROVIDER_PACKAGES.items() if c.treatment == "resolves-refs"],
166 )
167 def test_resolves_refs_before_translation(provider: str) -> None:
168 classification = PROVIDER_PACKAGES[provider]
169 assert classification.via in RESOLVER_HELPERS, classification.reason
170 assert classification.via in _provider_source(provider), classification.reason
171
172
173 @pytest.mark.parametrize(
174 "provider",
175 [n for n, c in PROVIDER_PACKAGES.items() if c.treatment == "passthrough"],
176 )
177 def test_forwards_schema_whole(provider: str) -> None:
178 classification = PROVIDER_PACKAGES[provider]
179 assert classification.via is None
180 source = _provider_source(provider)
181 assert [h for h in RESOLVER_HELPERS if h in source] == [], classification.reason
182
183
184 @pytest.mark.parametrize("relative_path", sorted(EXTRA_PASSTHROUGH_SOURCES))
185 def test_extra_sources_forward_schema_whole(relative_path: str) -> None:
186 path = REPO_ROOT / relative_path
187 assert path.is_file(), f"{relative_path} not found; update this test"
188 source = path.read_text(encoding="utf-8")
189 assert [h for h in RESOLVER_HELPERS if h in source] == []