toolschema 1.0.0__py3-none-any.whl

toolschema/_validate.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class ValidationIssueKind(str, Enum):
+    REQUIRED = "required"
+    TYPE = "type"
+    ENUM = "enum"
+    CONSTRAINT = "constraint"
+    ADDITIONAL_PROPERTY = "additional_property"
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    message: str
+    path: tuple[str | int, ...] = ()
+    kind: ValidationIssueKind = ValidationIssueKind.TYPE
+
+
+@dataclass(frozen=True)
+class ValidationSuccess:
+    value: dict[str, Any]
+    issues: None = None
+
+
+@dataclass(frozen=True)
+class ValidationFailure:
+    value: None = None
+    issues: tuple[ValidationIssue, ...] = ()
+
+
+ValidationResult = ValidationSuccess | ValidationFailure
+
+
+def _issue(
+    message: str,
+    *,
+    path: tuple[str | int, ...] = (),
+    kind: ValidationIssueKind = ValidationIssueKind.TYPE,
+) -> ValidationIssue:
+    return ValidationIssue(message=message, path=path, kind=kind)
+
+
+def _type_name(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int) and not isinstance(value, bool):
+        return "integer"
+    if isinstance(value, float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__
+
+
+def _matches_type(value: Any, expected: str) -> bool:
+    if expected == "null":
+        return value is None
+    if expected == "boolean":
+        return isinstance(value, bool)
+    if expected == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if expected == "string":
+        return isinstance(value, str)
+    if expected == "array":
+        return isinstance(value, list)
+    if expected == "object":
+        return isinstance(value, dict)
+    return True
+
+
+def _validate_constraints(
+    value: Any, schema: dict[str, Any], path: tuple[str | int, ...]
+) -> list[ValidationIssue]:
+    issues: list[ValidationIssue] = []
+
+    if isinstance(value, str):
+        min_length = schema.get("minLength")
+        max_length = schema.get("maxLength")
+        pattern = schema.get("pattern")
+        if min_length is not None and len(value) < min_length:
+            issues.append(
+                _issue(
+                    f"String too short (minLength {min_length})",
+                    path=path,
+                    kind=ValidationIssueKind.CONSTRAINT,
+                )
+            )
+        if max_length is not None and len(value) > max_length:
+            issues.append(
+                _issue(
+                    f"String too long (maxLength {max_length})",
+                    path=path,
+                    kind=ValidationIssueKind.CONSTRAINT,
+                )
+            )
+        if pattern is not None and re.search(pattern, value) is None:
+            issues.append(
+                _issue(
+                    f"String does not match pattern {pattern!r}",
+                    path=path,
+                    kind=ValidationIssueKind.CONSTRAINT,
+                )
+            )
+
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        minimum = schema.get("minimum")
+        maximum = schema.get("maximum")
+        exclusive_minimum = schema.get("exclusiveMinimum")
+        exclusive_maximum = schema.get("exclusiveMaximum")
+        if minimum is not None and value < minimum:
+            issues.append(
+                _issue(
+                    f"Value must be >= {minimum}", path=path, kind=ValidationIssueKind.CONSTRAINT
+                )
+            )
+        if maximum is not None and value > maximum:
+            issues.append(
+                _issue(
+                    f"Value must be <= {maximum}", path=path, kind=ValidationIssueKind.CONSTRAINT
+                )
+            )
+        if exclusive_minimum is not None and value <= exclusive_minimum:
+            issues.append(
+                _issue(
+                    f"Value must be > {exclusive_minimum}",
+                    path=path,
+                    kind=ValidationIssueKind.CONSTRAINT,
+                )
+            )
+        if exclusive_maximum is not None and value >= exclusive_maximum:
+            issues.append(
+                _issue(
+                    f"Value must be < {exclusive_maximum}",
+                    path=path,
+                    kind=ValidationIssueKind.CONSTRAINT,
+                )
+            )
+
+    return issues
+
+
+def _validate_value(
+    value: Any, schema: dict[str, Any], path: tuple[str | int, ...] = ()
+) -> list[ValidationIssue]:
+    if "anyOf" in schema:
+        branch_issues = [_validate_value(value, branch, path) for branch in schema["anyOf"]]
+        if any(not branch for branch in branch_issues):
+            return []
+        return [
+            _issue(
+                f"Value {_type_name(value)!r} does not match anyOf",
+                path=path,
+                kind=ValidationIssueKind.TYPE,
+            )
+        ]
+
+    if "enum" in schema and value not in schema["enum"]:
+        return [
+            _issue(
+                f"Value {value!r} is not in enum {schema['enum']!r}",
+                path=path,
+                kind=ValidationIssueKind.ENUM,
+            )
+        ]
+
+    json_type = schema.get("type")
+    if json_type and not _matches_type(value, json_type):
+        return [
+            _issue(
+                f"Expected {json_type}, got {_type_name(value)}",
+                path=path,
+                kind=ValidationIssueKind.TYPE,
+            )
+        ]
+
+    issues = _validate_constraints(value, schema, path)
+
+    if json_type == "array" and "items" in schema and isinstance(value, list):
+        for index, item in enumerate(value):
+            issues.extend(_validate_value(item, schema["items"], path + (index,)))
+
+    if json_type == "object" and isinstance(value, dict):
+        properties = schema.get("properties", {})
+        required = set(schema.get("required", []))
+
+        if schema.get("additionalProperties") is False:
+            extra = set(value) - set(properties)
+            for key in sorted(extra):
+                issues.append(
+                    _issue(
+                        f"Additional property {key!r} is not allowed",
+                        path=path + (key,),
+                        kind=ValidationIssueKind.ADDITIONAL_PROPERTY,
+                    )
+                )
+
+        for key in sorted(required):
+            if key not in value:
+                prop_schema = properties.get(key, {})
+                if "default" not in prop_schema:
+                    issues.append(
+                        _issue(
+                            f"Missing required property {key!r}",
+                            path=path + (key,),
+                            kind=ValidationIssueKind.REQUIRED,
+                        )
+                    )
+
+        for key, prop_schema in properties.items():
+            if key in value:
+                issues.extend(_validate_value(value[key], prop_schema, path + (key,)))
+
+        additional = schema.get("additionalProperties")
+        if isinstance(additional, dict):
+            for key, item in value.items():
+                if key not in properties:
+                    issues.extend(_validate_value(item, additional, path + (key,)))
+
+    return issues
+
+
+def validate_arguments(args: Any, parameters_schema: dict[str, Any]) -> ValidationResult:
+    """Validate tool arguments against a JSON Schema parameters object."""
+    if not isinstance(args, dict):
+        return ValidationFailure(
+            issues=(
+                _issue(
+                    f"Arguments must be an object, got {_type_name(args)}",
+                    kind=ValidationIssueKind.TYPE,
+                ),
+            )
+        )
+
+    if parameters_schema.get("type") != "object":
+        issues = _validate_value(args, parameters_schema)
+        return ValidationFailure(issues=tuple(issues)) if issues else ValidationSuccess(value=args)
+
+    properties = parameters_schema.get("properties", {})
+    required = set(parameters_schema.get("required", []))
+    issues: list[ValidationIssue] = []
+
+    for key in sorted(required):
+        if key not in args:
+            prop_schema = properties.get(key, {})
+            if "default" not in prop_schema:
+                issues.append(
+                    _issue(
+                        f"Missing required property {key!r}",
+                        path=(key,),
+                        kind=ValidationIssueKind.REQUIRED,
+                    )
+                )
+
+    normalized = dict(args)
+    for key, prop_schema in properties.items():
+        if key not in normalized and isinstance(prop_schema, dict) and "default" in prop_schema:
+            normalized[key] = prop_schema["default"]
+
+    if parameters_schema.get("additionalProperties") is False:
+        extra = set(normalized) - set(properties)
+        for key in sorted(extra):
+            issues.append(
+                _issue(
+                    f"Additional property {key!r} is not allowed",
+                    path=(key,),
+                    kind=ValidationIssueKind.ADDITIONAL_PROPERTY,
+                )
+            )
+
+    for key, prop_schema in properties.items():
+        if key in normalized:
+            issues.extend(_validate_value(normalized[key], prop_schema, (key,)))
+
+    if issues:
+        return ValidationFailure(issues=tuple(issues))
+    return ValidationSuccess(value=normalized)

toolschema/adapters/__init__.py

@@ -0,0 +1,6 @@
+from toolschema.adapters.anthropic import to_anthropic
+from toolschema.adapters.gemini import to_gemini
+from toolschema.adapters.mcp import to_mcp
+from toolschema.adapters.openai import to_openai
+
+__all__ = ["to_anthropic", "to_gemini", "to_mcp", "to_openai"]

toolschema/adapters/_inline_refs.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+def _resolve_ref(ref: str, defs: dict[str, Any]) -> dict[str, Any]:
+    if not ref.startswith("#/$defs/"):
+        raise ValueError(f"Unsupported $ref format: {ref!r}")
+    key = ref.removeprefix("#/$defs/")
+    if key not in defs:
+        raise ValueError(f"Unresolved $ref: {ref!r}")
+    return copy.deepcopy(defs[key])
+
+
+def _inline_node(node: Any, defs: dict[str, Any], resolving: set[str]) -> Any:
+    if isinstance(node, dict):
+        if "$ref" in node:
+            ref = node["$ref"]
+            key = ref.removeprefix("#/$defs/")
+            if key in resolving:
+                raise ValueError(f"Circular $ref detected: {ref!r}")
+            resolving = resolving | {key}
+            resolved = _inline_node(_resolve_ref(ref, defs), defs, resolving)
+            extras = {k: v for k, v in node.items() if k != "$ref"}
+            if extras:
+                if not isinstance(resolved, dict):
+                    return resolved
+                return {**resolved, **extras}
+            return resolved
+
+        return {k: _inline_node(v, defs, resolving) for k, v in node.items()}
+
+    if isinstance(node, list):
+        return [_inline_node(item, defs, resolving) for item in node]
+
+    return node
+
+
+def inline_refs(schema: dict[str, Any]) -> dict[str, Any]:
+    """Flatten JSON Schema $ref pointers using local $defs."""
+    cloned = copy.deepcopy(schema)
+    defs = cloned.pop("$defs", {})
+    if not defs:
+        return cloned
+    return _inline_node(cloned, defs, set())

toolschema/adapters/anthropic.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from toolschema._ir import ToolDefinition
+from toolschema._schema_utils import strip_canonical_meta
+
+_CONSTRAINT_KEYS = frozenset(
+    {
+        "minLength",
+        "maxLength",
+        "minimum",
+        "maximum",
+        "exclusiveMinimum",
+        "exclusiveMaximum",
+        "pattern",
+    }
+)
+
+
+def _constraint_to_description(prop: dict[str, Any]) -> str | None:
+    parts: list[str] = []
+    if "minLength" in prop:
+        parts.append(f"min length {prop['minLength']}")
+    if "maxLength" in prop:
+        parts.append(f"max length {prop['maxLength']}")
+    if "minimum" in prop:
+        parts.append(f"minimum {prop['minimum']}")
+    if "maximum" in prop:
+        parts.append(f"maximum {prop['maximum']}")
+    if "exclusiveMinimum" in prop:
+        parts.append(f"exclusive minimum {prop['exclusiveMinimum']}")
+    if "exclusiveMaximum" in prop:
+        parts.append(f"exclusive maximum {prop['exclusiveMaximum']}")
+    if "pattern" in prop:
+        parts.append(f"pattern {prop['pattern']!r}")
+    return "; ".join(parts) if parts else None
+
+
+def _adapt_property(prop: dict[str, Any]) -> dict[str, Any]:
+    result = copy.deepcopy(prop)
+    constraint_desc = _constraint_to_description(result)
+    if constraint_desc:
+        existing = result.get("description", "")
+        suffix = f" ({constraint_desc})"
+        result["description"] = f"{existing}{suffix}" if existing else constraint_desc
+        for key in _CONSTRAINT_KEYS:
+            result.pop(key, None)
+    return result
+
+
+def _adapt_input_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    result = strip_canonical_meta(schema)
+    properties = result.get("properties")
+    if isinstance(properties, dict):
+        result["properties"] = {k: _adapt_property(v) for k, v in properties.items()}
+    return result
+
+
+def to_anthropic(tool: ToolDefinition) -> dict[str, Any]:
+    """Convert ToolDefinition to Anthropic tool format."""
+    return {
+        "name": tool.name,
+        "description": tool.description,
+        "input_schema": _adapt_input_schema(tool.parameters),
+    }

toolschema/adapters/gemini.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from toolschema._ir import ToolDefinition
+
+_TYPE_MAP = {
+    "string": "STRING",
+    "integer": "INTEGER",
+    "number": "NUMBER",
+    "boolean": "BOOLEAN",
+    "array": "ARRAY",
+    "object": "OBJECT",
+    "null": "NULL",
+}
+
+
+def _strip_canonical_meta(schema: dict[str, Any]) -> dict[str, Any]:
+    result = copy.deepcopy(schema)
+    result.pop("$schema", None)
+    return result
+
+
+def _convert_type(schema: dict[str, Any]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in schema.items():
+        if key == "type" and isinstance(value, str):
+            result["type"] = _TYPE_MAP.get(value, value.upper())
+        elif key == "properties" and isinstance(value, dict):
+            result["properties"] = {k: _convert_schema(v) for k, v in value.items()}
+        elif key == "items" and isinstance(value, dict):
+            result["items"] = _convert_schema(value)
+        elif key == "additionalProperties" and isinstance(value, dict):
+            result["additionalProperties"] = _convert_schema(value)
+        elif key == "anyOf" and isinstance(value, list):
+            result["anyOf"] = [_convert_schema(item) for item in value]
+        else:
+            result[key] = value
+    return result
+
+
+def _convert_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    return _convert_type(copy.deepcopy(schema))
+
+
+def to_gemini(tool: ToolDefinition) -> dict[str, Any]:
+    """Convert ToolDefinition to Gemini FunctionDeclaration format."""
+    parameters = _convert_schema(_strip_canonical_meta(tool.parameters))
+    if "type" not in parameters:
+        parameters["type"] = "OBJECT"
+
+    result: dict[str, Any] = {
+        "name": tool.name,
+        "description": tool.description,
+        "parameters": parameters,
+    }
+    return result

toolschema/adapters/mcp.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+from toolschema._ir import ToolDefinition
+from toolschema._schema_utils import strip_canonical_meta
+from toolschema.adapters._inline_refs import inline_refs as resolve_inline_refs
+
+
+def to_mcp(tool: ToolDefinition, *, inline_refs: bool = True) -> dict[str, Any]:
+    """Convert ToolDefinition to MCP tools/list format."""
+    input_schema = strip_canonical_meta(tool.parameters)
+    if inline_refs:
+        input_schema = resolve_inline_refs(input_schema)
+
+    result: dict[str, Any] = {
+        "name": tool.name,
+        "description": tool.description,
+        "inputSchema": input_schema,
+    }
+
+    if tool.output is not None:
+        output_schema = strip_canonical_meta(tool.output)
+        if inline_refs:
+            output_schema = resolve_inline_refs(output_schema)
+        result["outputSchema"] = output_schema
+
+    return result

toolschema/adapters/openai.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from toolschema._ir import ToolDefinition
+from toolschema._schema_utils import strip_canonical_meta
+
+
+def _apply_strict(parameters: dict[str, Any]) -> dict[str, Any]:
+    params = copy.deepcopy(parameters)
+    params["additionalProperties"] = False
+    properties = params.get("properties", {})
+    if properties:
+        params["required"] = list(properties.keys())
+    return params
+
+
+def to_openai(tool: ToolDefinition, *, strict: bool = False) -> dict[str, Any]:
+    """Convert ToolDefinition to OpenAI function-calling tool format."""
+    parameters = strip_canonical_meta(tool.parameters)
+    if strict:
+        parameters = _apply_strict(parameters)
+
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": parameters,
+        },
+    }