toolschema 1.0.0__py3-none-any.whl

toolschema/__init__.py

@@ -0,0 +1,29 @@
+"""toolschema — function to JSON Schema for AI agent tools."""
+
+from toolschema._decorator import tool
+from toolschema._fields import Field
+from toolschema._introspect import schema
+from toolschema._ir import ToolDefinition
+from toolschema._standard import JSONSchemaOptions, StandardSchemaHost
+from toolschema._validate import (
+    ValidationFailure,
+    ValidationIssue,
+    ValidationResult,
+    ValidationSuccess,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "tool",
+    "schema",
+    "Field",
+    "ToolDefinition",
+    "JSONSchemaOptions",
+    "StandardSchemaHost",
+    "ValidationFailure",
+    "ValidationIssue",
+    "ValidationResult",
+    "ValidationSuccess",
+    "__version__",
+]

toolschema/__main__.py

@@ -0,0 +1,4 @@
+from toolschema.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

toolschema/_decorator.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any, TypeVar, overload
+
+from toolschema._introspect import ToolMeta
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@overload
+def tool(fn: F) -> F: ...
+
+
+@overload
+def tool(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Callable[[F], F]: ...
+
+
+def tool(
+    fn: F | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> F | Callable[[F], F]:
+    """Mark a function as a tool and optionally override name or description."""
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return func(*args, **kwargs)
+
+        wrapper._toolschema = ToolMeta(  # type: ignore[attr-defined]
+            name=name,
+            description=description,
+        )
+        wrapper.__wrapped__ = func  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator

toolschema/_fields.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Field:
+    """Metadata for Annotated type hints, mapped to JSON Schema constraints."""
+
+    description: str | None = None
+    min_length: int | None = None
+    max_length: int | None = None
+    ge: int | float | None = None
+    le: int | float | None = None
+    gt: int | float | None = None
+    lt: int | float | None = None
+    pattern: str | None = None
+
+
+def field_to_schema_extras(field: Field) -> dict[str, Any]:
+    """Convert Field metadata to JSON Schema keyword fragments."""
+    extras: dict[str, Any] = {}
+    if field.description is not None:
+        extras["description"] = field.description
+    if field.min_length is not None:
+        extras["minLength"] = field.min_length
+    if field.max_length is not None:
+        extras["maxLength"] = field.max_length
+    if field.ge is not None:
+        extras["minimum"] = field.ge
+    if field.le is not None:
+        extras["maximum"] = field.le
+    if field.gt is not None:
+        extras["exclusiveMinimum"] = field.gt
+    if field.lt is not None:
+        extras["exclusiveMaximum"] = field.lt
+    if field.pattern is not None:
+        extras["pattern"] = field.pattern
+    return extras
+
+
+def extract_annotated_metadata(metadata: tuple[Any, ...]) -> tuple[type[Any], dict[str, Any]]:
+    """Extract base type and merged schema extras from Annotated metadata."""
+    if not metadata:
+        return object, {}
+
+    base_type = metadata[0] if isinstance(metadata[0], type) else metadata[0]
+    extras: dict[str, Any] = {}
+
+    for item in metadata[1:]:
+        if isinstance(item, Field):
+            extras.update(field_to_schema_extras(item))
+        elif isinstance(item, str):
+            if "description" not in extras:
+                extras["description"] = item
+
+    return base_type, extras
+
+
+def merge_field_into_schema(base_schema: dict[str, Any], extras: dict[str, Any]) -> dict[str, Any]:
+    """Merge Field / Annotated metadata into a JSON Schema fragment."""
+    if not extras:
+        return base_schema
+    return {**base_schema, **extras}

toolschema/_init_scaffold.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import re
+import shutil
+from importlib import resources
+from pathlib import Path
+from typing import NamedTuple
+
+
+class ScaffoldResult(NamedTuple):
+    root: Path
+    package_name: str
+    project_name: str
+
+
+def slugify_package_name(name: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "_", name.lower()).strip("_")
+    if not slug:
+        raise ValueError("Project name must contain at least one letter or digit")
+    if slug[0].isdigit():
+        slug = f"mcp_{slug}"
+    return slug
+
+
+def _render(text: str, *, project_name: str, package_name: str, project_title: str) -> str:
+    return (
+        text.replace("{{project_name}}", project_name)
+        .replace("{{package_name}}", package_name)
+        .replace("{{project_title}}", project_title)
+    )
+
+
+def scaffold_mcp_server(target_dir: Path, project_name: str) -> ScaffoldResult:
+    """Scaffold a new MCP server project from the packaged template."""
+    package_name = slugify_package_name(project_name)
+    project_title = project_name.replace("-", " ").replace("_", " ").title()
+    root = target_dir.resolve() / project_name
+
+    if root.exists():
+        raise FileExistsError(f"Directory already exists: {root}")
+
+    template_root = resources.files("toolschema.templates") / "mcp_server"
+    _copy_template_tree(template_root, root)
+
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        content = path.read_text(encoding="utf-8")
+        rendered = _render(
+            content,
+            project_name=project_name,
+            package_name=package_name,
+            project_title=project_title,
+        )
+        path.write_text(rendered, encoding="utf-8")
+
+    package_dir = root / "src" / "PACKAGE"
+    final_package_dir = root / "src" / package_name
+    package_dir.rename(final_package_dir)
+
+    return ScaffoldResult(root=root, package_name=package_name, project_name=project_name)
+
+
+def _copy_template_tree(source: resources.abc.Traversable, destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    for item in source.iterdir():
+        if item.is_dir():
+            _copy_template_tree(item, destination / item.name)
+        else:
+            shutil.copyfile(item, destination / item.name)

toolschema/_introspect.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, get_type_hints
+
+from toolschema._ir import ToolDefinition
+from toolschema._types import JSON_SCHEMA_2020_12, type_to_schema
+
+
+@dataclass(frozen=True)
+class ToolMeta:
+    """Metadata attached by the @tool decorator."""
+
+    name: str | None = None
+    description: str | None = None
+
+
+def _unwrap_tool(fn: Callable[..., Any]) -> tuple[Callable[..., Any], ToolMeta | None]:
+    meta = getattr(fn, "_toolschema", None)
+    if meta is not None:
+        wrapped = getattr(fn, "__wrapped__", fn)
+        return wrapped, meta
+    return fn, None
+
+
+def _parse_docstring_description(doc: str | None) -> str:
+    if not doc:
+        return ""
+    paragraphs = doc.strip().split("\n\n")
+    return paragraphs[0].strip().replace("\n", " ")
+
+
+def _build_parameters_schema(fn: Callable[..., Any]) -> dict[str, Any]:
+    hints = get_type_hints(fn, include_extras=True)
+    sig = inspect.signature(fn)
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    for name, param in sig.parameters.items():
+        if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD):
+            continue
+        if name in ("self", "cls"):
+            continue
+
+        annotation = hints.get(name, Any)
+        prop_schema = type_to_schema(annotation)
+
+        if param.default is not inspect.Parameter.empty:
+            prop_schema = {**prop_schema, "default": param.default}
+        else:
+            required.append(name)
+
+        properties[name] = prop_schema
+
+    schema: dict[str, Any] = {
+        "$schema": JSON_SCHEMA_2020_12,
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def _build_output_schema(fn: Callable[..., Any]) -> dict[str, Any] | None:
+    hints = get_type_hints(fn, include_extras=True)
+    return_type = hints.get("return", inspect.Signature.empty)
+    if return_type is inspect.Signature.empty or return_type is None or return_type is type(None):
+        return None
+    return type_to_schema(return_type)
+
+
+def schema(fn: Callable[..., Any]) -> ToolDefinition:
+    """Build a ToolDefinition from a Python function's signature and annotations."""
+    target, meta = _unwrap_tool(fn)
+
+    name = (meta.name if meta and meta.name else None) or target.__name__
+    description = (
+        meta.description
+        if meta and meta.description is not None
+        else _parse_docstring_description(target.__doc__)
+    )
+
+    return ToolDefinition(
+        name=name,
+        description=description,
+        parameters=_build_parameters_schema(target),
+        output=_build_output_schema(target),
+    )

toolschema/_ir.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from toolschema._standard import StandardSchemaHost, build_standard_schema
+from toolschema._validate import ValidationResult, validate_arguments
+
+
+@dataclass(frozen=True)
+class ToolDefinition:
+    """Intermediate representation of a tool derived from a Python function."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    output: dict[str, Any] | None = None
+
+    def to_json_schema(self) -> dict[str, Any]:
+        """Return canonical tool record with JSON Schema 2020-12 parameters."""
+        result: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters,
+        }
+        if self.output is not None:
+            result["output"] = self.output
+        return result
+
+    def validate(self, args: Any) -> ValidationResult:
+        """Validate tool arguments against the canonical parameters schema."""
+        return validate_arguments(args, self.parameters)
+
+    @property
+    def standard(self) -> StandardSchemaHost:
+        """Standard Schema + Standard JSON Schema protocol host."""
+        return build_standard_schema(
+            parameters=self.parameters,
+            output=self.output,
+            validate=self.validate,
+        )
+
+    def to_openai(self, *, strict: bool = False) -> dict[str, Any]:
+        from toolschema.adapters.openai import to_openai
+
+        return to_openai(self, strict=strict)
+
+    def to_anthropic(self) -> dict[str, Any]:
+        from toolschema.adapters.anthropic import to_anthropic
+
+        return to_anthropic(self)
+
+    def to_mcp(self, *, inline_refs: bool = True) -> dict[str, Any]:
+        from toolschema.adapters.mcp import to_mcp
+
+        return to_mcp(self, inline_refs=inline_refs)
+
+    def to_gemini(self) -> dict[str, Any]:
+        from toolschema.adapters.gemini import to_gemini
+
+        return to_gemini(self)

toolschema/_schema_utils.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+def strip_canonical_meta(schema: dict[str, Any]) -> dict[str, Any]:
+    """Remove JSON Schema dialect metadata not used by provider payloads."""
+    result = copy.deepcopy(schema)
+    result.pop("$schema", None)
+    return result

toolschema/_standard.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from toolschema._schema_utils import strip_canonical_meta
+from toolschema._validate import ValidationResult
+
+STANDARD_VERSION = 1
+STANDARD_VENDOR = "toolschema"
+
+JSONSchemaTarget = Literal["draft-2020-12", "draft-07", "openapi-3.0"]
+
+
+@dataclass(frozen=True)
+class JSONSchemaOptions:
+    target: JSONSchemaTarget = "draft-2020-12"
+    library_options: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class StandardSchemaProps:
+    """Standard Schema + Standard JSON Schema properties for ecosystem interop."""
+
+    version: int
+    vendor: str
+    validate: Callable[[Any], ValidationResult]
+    json_schema_input: Callable[[JSONSchemaOptions], dict[str, Any]]
+    json_schema_output: Callable[[JSONSchemaOptions], dict[str, Any]]
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "version": self.version,
+            "vendor": self.vendor,
+            "validate": self.validate,
+            "jsonSchema": {
+                "input": self.json_schema_input,
+                "output": self.json_schema_output,
+            },
+        }
+
+
+class StandardSchemaHost(Mapping[str, Any]):
+    """Mapping host exposing the ``~standard`` Standard Schema protocol key."""
+
+    def __init__(self, props: StandardSchemaProps) -> None:
+        self._props = props
+
+    def __getitem__(self, key: str) -> Any:
+        if key == "~standard":
+            return self._props.to_mapping()
+        raise KeyError(key)
+
+    def __iter__(self):
+        yield "~standard"
+
+    def __len__(self) -> int:
+        return 1
+
+
+def build_standard_schema(
+    *,
+    parameters: dict[str, Any],
+    output: dict[str, Any] | None,
+    validate: Callable[[Any], ValidationResult],
+) -> StandardSchemaHost:
+    def json_schema_input(
+        options: JSONSchemaOptions | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        opts = _coerce_options(options)
+        _ensure_target(opts.target)
+        return strip_canonical_meta(parameters)
+
+    def json_schema_output(
+        options: JSONSchemaOptions | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        opts = _coerce_options(options)
+        _ensure_target(opts.target)
+        if output is None:
+            raise ValueError("Tool has no output schema")
+        return strip_canonical_meta(output)
+
+    props = StandardSchemaProps(
+        version=STANDARD_VERSION,
+        vendor=STANDARD_VENDOR,
+        validate=validate,
+        json_schema_input=json_schema_input,
+        json_schema_output=json_schema_output,
+    )
+    return StandardSchemaHost(props)
+
+
+def _coerce_options(options: JSONSchemaOptions | dict[str, Any] | None) -> JSONSchemaOptions:
+    if options is None:
+        return JSONSchemaOptions()
+    if isinstance(options, JSONSchemaOptions):
+        return options
+    return JSONSchemaOptions(
+        target=options.get("target", "draft-2020-12"),
+        library_options=options.get("libraryOptions"),
+    )
+
+
+def _ensure_target(target: str) -> None:
+    if target not in {"draft-2020-12", "draft-07", "openapi-3.0"}:
+        raise ValueError(f"Unsupported JSON Schema target: {target!r}")

toolschema/_types.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import dataclasses
+import enum
+import types
+from typing import Annotated, Any, Literal, Union, get_args, get_origin, get_type_hints
+
+from toolschema._fields import extract_annotated_metadata, merge_field_into_schema
+
+JSON_SCHEMA_2020_12 = "https://json-schema.org/draft/2020-12/schema"
+
+
+def _normalize_pydantic_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Normalize a Pydantic model_json_schema() payload to a property schema."""
+    result = {k: v for k, v in schema.items() if k not in {"$defs", "$schema", "title"}}
+    properties = result.get("properties")
+    if isinstance(properties, dict):
+        result["properties"] = {
+            name: {k: v for k, v in prop.items() if k != "title"}
+            for name, prop in properties.items()
+            if isinstance(prop, dict)
+        }
+    if "properties" in result:
+        result.setdefault("type", "object")
+        result.setdefault("additionalProperties", False)
+    return result
+
+
+def _is_typeddict(tp: Any) -> bool:
+    try:
+        from typing_extensions import is_typeddict
+
+        return is_typeddict(tp)
+    except ImportError:
+        return isinstance(tp, type) and hasattr(tp, "__annotations__") and hasattr(tp, "__total__")
+
+
+def _typeddict_to_schema(tp: type[Any]) -> dict[str, Any]:
+    hints = get_type_hints(tp)
+    total = getattr(tp, "__total__", True)
+    properties = {name: type_to_schema(annotation) for name, annotation in hints.items()}
+    required = list(hints.keys()) if total else []
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def _dataclass_to_schema(tp: type[Any]) -> dict[str, Any]:
+    hints = get_type_hints(tp)
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for field in dataclasses.fields(tp):
+        annotation = hints.get(field.name, Any)
+        properties[field.name] = type_to_schema(annotation)
+        if field.default is dataclasses.MISSING and field.default_factory is dataclasses.MISSING:
+            required.append(field.name)
+        elif field.default is not dataclasses.MISSING:
+            properties[field.name] = {
+                **properties[field.name],
+                "default": field.default,
+            }
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def type_to_schema(tp: Any) -> dict[str, Any]:
+    """Convert a Python type annotation to a JSON Schema 2020-12 fragment."""
+    origin = get_origin(tp)
+    args = get_args(tp)
+
+    if origin is Annotated:
+        base_type, extras = extract_annotated_metadata(args)
+        schema = type_to_schema(base_type)
+        return merge_field_into_schema(schema, extras)
+
+    if origin is Union or isinstance(tp, types.UnionType):
+        non_none = [a for a in args if a is not type(None)]
+        if not non_none:
+            return {"type": "null"}
+        if len(non_none) == 1 and type(None) in args:
+            inner = type_to_schema(non_none[0])
+            return {"anyOf": [inner, {"type": "null"}]}
+        schemas = [type_to_schema(a) for a in args if a is not type(None)]
+        if type(None) in args:
+            schemas.append({"type": "null"})
+        if len(schemas) == 1:
+            return schemas[0]
+        return {"anyOf": schemas}
+
+    if origin is tuple:
+        if len(args) == 2 and args[1] is Ellipsis:
+            return {"type": "array", "items": type_to_schema(args[0])}
+        if args:
+            return {
+                "type": "array",
+                "prefixItems": [type_to_schema(arg) for arg in args],
+                "minItems": len(args),
+                "maxItems": len(args),
+            }
+        return {"type": "array"}
+
+    if origin is list:
+        item_type = args[0] if args else Any
+        return {"type": "array", "items": type_to_schema(item_type)}
+
+    if origin is dict:
+        if len(args) == 2 and args[0] is str:
+            return {
+                "type": "object",
+                "additionalProperties": type_to_schema(args[1]),
+            }
+        if not args:
+            return {"type": "object"}
+        raise TypeError(f"Unsupported dict type (only dict[str, T] supported): {tp!r}")
+
+    if origin is Literal:
+        values = list(args)
+        if all(isinstance(v, str) for v in values):
+            return {"enum": values}
+        if all(isinstance(v, (int, float)) and not isinstance(v, bool) for v in values):
+            return {"enum": values}
+        if all(isinstance(v, bool) for v in values):
+            return {"enum": values}
+        return {"enum": values}
+
+    if isinstance(tp, type) and issubclass(tp, enum.Enum):
+        return {"enum": [member.value for member in tp]}
+
+    if isinstance(tp, type) and _is_typeddict(tp):
+        return _typeddict_to_schema(tp)
+
+    if isinstance(tp, type) and dataclasses.is_dataclass(tp):
+        return _dataclass_to_schema(tp)
+
+    if isinstance(tp, type) and hasattr(tp, "model_json_schema"):
+        return _normalize_pydantic_schema(tp.model_json_schema())
+
+    if tp is str:
+        return {"type": "string"}
+    if tp is int:
+        return {"type": "integer"}
+    if tp is float:
+        return {"type": "number"}
+    if tp is bool:
+        return {"type": "boolean"}
+    if tp is dict:
+        return {"type": "object"}
+    if tp is type(None):
+        return {"type": "null"}
+    if tp is Any:
+        return {}
+
+    raise TypeError(f"Unsupported type annotation: {tp!r}")