matrix-fn-schema 0.1.0__tar.gz

matrix_fn_schema-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matrix_fn_schema-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: matrix-fn-schema
+Version: 0.1.0
+Summary: Python function signatures to OpenAI-compatible JSON Schema
+License-Expression: MIT
+Keywords: openai,json-schema,function-calling,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: docstring-parser>=0.16
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2; extra == "pydantic"
+Dynamic: license-file
+
+# matrixschema
+
+Convert Python function signatures (type annotations + docstrings) into OpenAI-compatible JSON Schema (tool call format).
+
+```python
+from src.matrixschema import build_json_schema
+
+
+def get_weather(city: str, units: Literal["metric", "imperial"] = "metric") -> str:
+    """Get the current weather for a city."""
+    ...
+
+
+schema = build_json_schema(get_weather)
+# {
+#   "type": "function",
+#   "name": "get_weather",
+#   "description": "Get the current weather for a city.",
+#   "strict": True,
+#   "parameters": {
+#     "type": "object",
+#     "properties": {
+#       "city": {"type": "string"},
+#       "units": {"anyOf": [{"enum": ["metric", "imperial"]}, {"type": "null"}]}
+#     },
+#     "additionalProperties": False,
+#     "required": ["city", "units"]
+#   }
+# }
+```
+
+Supports: `int`, `float`, `str`, `bool`, `None`, `Optional[X]`, `Union[...]`, `Literal[...]`, `list[X]`, `tuple[X, ...]`, `dict[K, V]`, nested `pydantic.BaseModel`.
+
+Requires Python 3.10+.
+
+Written with love by dotmatrix.

matrix_fn_schema-0.1.0/README.md

@@ -0,0 +1,36 @@
+# matrixschema
+
+Convert Python function signatures (type annotations + docstrings) into OpenAI-compatible JSON Schema (tool call format).
+
+```python
+from src.matrixschema import build_json_schema
+
+
+def get_weather(city: str, units: Literal["metric", "imperial"] = "metric") -> str:
+    """Get the current weather for a city."""
+    ...
+
+
+schema = build_json_schema(get_weather)
+# {
+#   "type": "function",
+#   "name": "get_weather",
+#   "description": "Get the current weather for a city.",
+#   "strict": True,
+#   "parameters": {
+#     "type": "object",
+#     "properties": {
+#       "city": {"type": "string"},
+#       "units": {"anyOf": [{"enum": ["metric", "imperial"]}, {"type": "null"}]}
+#     },
+#     "additionalProperties": False,
+#     "required": ["city", "units"]
+#   }
+# }
+```
+
+Supports: `int`, `float`, `str`, `bool`, `None`, `Optional[X]`, `Union[...]`, `Literal[...]`, `list[X]`, `tuple[X, ...]`, `dict[K, V]`, nested `pydantic.BaseModel`.
+
+Requires Python 3.10+.
+
+Written with love by dotmatrix.

matrix_fn_schema-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "matrix-fn-schema"
+dynamic = ["version"]
+description = "Python function signatures to OpenAI-compatible JSON Schema"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["openai", "json-schema", "function-calling", "tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "docstring-parser>=0.16",
+]
+
+[project.optional-dependencies]
+pydantic = ["pydantic>=2"]
+
+[tool.setuptools.dynamic]
+version = {attr = "matrix_fn_schema.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["matrix_fn_schema*"]

matrix_fn_schema-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matrix_fn_schema-0.1.0/src/matrix_fn_schema/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+from matrix_fn_schema.schema import build_json_schema
+
+__all__ = ["build_json_schema"]

matrix_fn_schema-0.1.0/src/matrix_fn_schema/py.typed

@@ -0,0 +1 @@
+

matrix_fn_schema-0.1.0/src/matrix_fn_schema/schema.py

@@ -0,0 +1,175 @@
+from typing import Any, Callable, Union, Awaitable
+
+from docstring_parser import parse as _parse_docstring
+from typing import Literal, get_args, get_origin, get_type_hints
+import sys
+import inspect
+
+AsyncOrSyncFunction = Union[Callable[..., object], Callable[..., Awaitable[object]]]
+
+_PRIMITIVES: dict[type, str] = {
+    int: 'integer',
+    float: 'number',
+    str: 'string',
+    bool: 'boolean',
+    type(None): 'null',
+}
+
+
+def _parse_param_docs(fn: AsyncOrSyncFunction) -> dict[str, str]:
+    return {
+        p.arg_name: p.description or ''
+        for p in _parse_docstring(inspect.getdoc(fn) or '').params
+    }
+
+
+def _get_union_args(annotation: Any) -> tuple[Any, ...] | None:
+    """
+    Returns Union/Optional/X|Y arguments, or None if not a Union.
+    Handles typing.Union and types.UnionType (Python 3.10+ pipe syntax).
+    """
+    if get_origin(annotation) is Union:
+        return get_args(annotation)
+    if sys.version_info >= (3, 10):
+        import types
+        if type(annotation) is types.UnionType:
+            return get_args(annotation)
+    return None
+
+
+def _annotation_to_schema(annotation: Any) -> dict[str, Any]:
+    # empty / Any - no constraints
+    if annotation is inspect.Parameter.empty or annotation is Any:
+        return {}
+
+    if annotation is type(None):
+        return {'type': 'null'}
+
+    if annotation in _PRIMITIVES:
+        return {'type': _PRIMITIVES[annotation]}
+
+    # Union / Optional / X | Y
+    union_args = _get_union_args(annotation)
+    if union_args is not None:
+        null_schema = {'type': 'null'}
+        arg_schemas = [_annotation_to_schema(a) for a in union_args]
+        non_null = [s for s in arg_schemas if s != null_schema]
+
+        if len(arg_schemas) == 2 and null_schema in arg_schemas:
+            # Optional[X] / X | None - keep flat structure
+            return {'anyOf': [non_null[0], null_schema]}
+        return {'anyOf': arg_schemas}
+
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    # Literal["a", "b"]
+    if origin is Literal:
+        return {'enum': list(args)}
+
+    # list[X]
+    if origin is list:
+        schema: dict[str, Any] = {'type': 'array'}
+        if args:
+            schema['items'] = _annotation_to_schema(args[0])
+        return schema
+
+    # tuple[X, Y] / tuple[X, ...]
+    if origin is tuple:
+        if not args:
+            return {'type': 'array'}
+        if len(args) == 2 and args[1] is Ellipsis:
+            # tuple[int, ...] - variable length
+            return {'type': 'array', 'items': _annotation_to_schema(args[0])}
+        # tuple[int, str, float] - fixed structure
+        return {
+            'type': 'array',
+            'prefixItems': [_annotation_to_schema(a) for a in args],
+            'minItems': len(args),
+            'maxItems': len(args),
+        }
+
+    # dict[K, V]
+    if origin is dict:
+        schema = {'type': 'object'}
+        if len(args) == 2:
+            val_schema = _annotation_to_schema(args[1])
+            if val_schema:
+                schema['additionalProperties'] = val_schema
+        return schema
+
+    # Pydantic BaseModel - nested schema
+    try:
+        from pydantic import BaseModel
+        if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+            return annotation.model_json_schema()
+    except ImportError:
+        pass
+
+    return {}
+
+
+def _is_optional_param(annotation: Any, default: Any) -> bool:
+    if default is not inspect.Parameter.empty:
+        return True
+    origin = get_origin(annotation)
+    return get_origin(origin) is Union and type(None) in get_args(annotation)
+
+
+def _make_strict_schema(base: dict[str, Any]) -> dict[str, Any]:
+    """
+    In strict mode, a parameter with a default must accept null
+    (the LLM will pass null instead of omitting the argument).
+    If the schema already has anyOf with null, do not duplicate.
+    """
+    null_schema = {'type': 'null'}
+    if not base:
+        return null_schema
+    # already nullable
+    if 'anyOf' in base and null_schema in base['anyOf']:
+        return base
+    return {'anyOf': [base, null_schema]}
+
+
+def build_json_schema(fn: AsyncOrSyncFunction) -> dict[str, Any]:
+    sig = inspect.signature(fn)
+    hints = get_type_hints(fn)
+    param_docs = _parse_param_docs(fn)
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []  # in strict mode — all parameters
+
+    for name, param in sig.parameters.items():
+        if name in ('self', 'cls'):
+            continue
+
+        annotation = hints.get(name, inspect.Parameter.empty)
+        has_default = param.default is not inspect.Parameter.empty
+        base_schema = _annotation_to_schema(annotation)
+
+        # optional - anyOf [type, null] so the LLM can explicitly pass null
+        if has_default:
+            prop = _make_strict_schema(base_schema)
+        else:
+            prop = base_schema
+
+        if description := param_docs.get(name):
+            prop['description'] = description
+
+        properties[name] = prop
+        required.append(name)  # always
+
+    description = (inspect.getdoc(fn) or '').replace('\n', ' ').strip()
+
+    return {
+        'type': 'function',
+        'name': fn.__name__,
+        'description': description,
+        'strict': True,
+        'parameters': {
+            'type': 'object',
+            'properties': properties,
+            'additionalProperties': False,
+            'required': required,
+        },
+    }

matrix_fn_schema-0.1.0/src/matrix_fn_schema.egg-info/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: matrix-fn-schema
+Version: 0.1.0
+Summary: Python function signatures to OpenAI-compatible JSON Schema
+License-Expression: MIT
+Keywords: openai,json-schema,function-calling,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: docstring-parser>=0.16
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2; extra == "pydantic"
+Dynamic: license-file
+
+# matrixschema
+
+Convert Python function signatures (type annotations + docstrings) into OpenAI-compatible JSON Schema (tool call format).
+
+```python
+from src.matrixschema import build_json_schema
+
+
+def get_weather(city: str, units: Literal["metric", "imperial"] = "metric") -> str:
+    """Get the current weather for a city."""
+    ...
+
+
+schema = build_json_schema(get_weather)
+# {
+#   "type": "function",
+#   "name": "get_weather",
+#   "description": "Get the current weather for a city.",
+#   "strict": True,
+#   "parameters": {
+#     "type": "object",
+#     "properties": {
+#       "city": {"type": "string"},
+#       "units": {"anyOf": [{"enum": ["metric", "imperial"]}, {"type": "null"}]}
+#     },
+#     "additionalProperties": False,
+#     "required": ["city", "units"]
+#   }
+# }
+```
+
+Supports: `int`, `float`, `str`, `bool`, `None`, `Optional[X]`, `Union[...]`, `Literal[...]`, `list[X]`, `tuple[X, ...]`, `dict[K, V]`, nested `pydantic.BaseModel`.
+
+Requires Python 3.10+.
+
+Written with love by dotmatrix.

matrix_fn_schema-0.1.0/src/matrix_fn_schema.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/matrix_fn_schema/__init__.py
+src/matrix_fn_schema/py.typed
+src/matrix_fn_schema/schema.py
+src/matrix_fn_schema.egg-info/PKG-INFO
+src/matrix_fn_schema.egg-info/SOURCES.txt
+src/matrix_fn_schema.egg-info/dependency_links.txt
+src/matrix_fn_schema.egg-info/requires.txt
+src/matrix_fn_schema.egg-info/top_level.txt

matrix_fn_schema-0.1.0/src/matrix_fn_schema.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

matrix_fn_schema-0.1.0/src/matrix_fn_schema.egg-info/requires.txt

@@ -0,0 +1,4 @@
+docstring-parser>=0.16
+
+[pydantic]
+pydantic>=2

matrix_fn_schema-0.1.0/src/matrix_fn_schema.egg-info/top_level.txt

@@ -0,0 +1 @@
+matrix_fn_schema