3tears-tool-schema 0.55.0__tar.gz

3tears_tool_schema-0.55.0/.gitignore

@@ -0,0 +1,250 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+# Anchored: these name top-level build output. Unanchored, `lib/` matches at ANY depth --
+# it swallowed a vendored `.../pako/lib/` tree, and hatchling reads this file with its own
+# matcher that does NOT honour `!` re-inclusion, so the miss reached built artifacts.
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Claude Code local state
+# .claude/* rather than .claude/ so the one file below can be re-included:
+# git never descends into an excluded DIRECTORY, so a negation inside one is
+# silently dead. Excluding the contents instead leaves the directory readable.
+.claude/*
+# Prawduct install reference. Committed on purpose: it is what enables the
+# plugin for anyone who clones this repo. Without it the governance hooks run
+# only on a machine that already has prawduct installed, and a new developer
+# gets none of them.
+!.claude/settings.json
+
+# prawduct session evidence (local governance artifacts, never shipped)
+.prawduct/
+
+# macOS folder metadata
+.DS_Store
+
+
+# Prawduct session files
+.claude/settings.local.json
+.prawduct/.bug-inbox
+.prawduct/.critic-active
+.prawduct/.critic-findings.json
+.prawduct/.critic-partials/
+.prawduct/.critic-partials-archive/
+.prawduct/.governance-ledger.jsonl
+.prawduct/.handoff-notes.md
+.prawduct/.test-evidence.json
+.prawduct/.pr-reviews/
+.prawduct/.session-base-tree
+.prawduct/.session-git-baseline
+.prawduct/.session-handoff.md
+.prawduct/.session-reflected
+.prawduct/.session-start
+.prawduct/.subagent-briefing.md
+.prawduct/.gates-waived
+.prawduct/.advisories.json
+.prawduct/.work-model-index.json
+.prawduct/reflections.md

3tears_tool_schema-0.55.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Pace
+
+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.

3tears_tool_schema-0.55.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: 3tears-tool-schema
+Version: 0.55.0
+Summary: Dependency-free helpers that make a tool's JSON Schema self-contained for models and validators
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# 3tears-tool-schema
+
+Dependency-free helpers for the JSON Schema a tool advertises for its arguments.
+
+A tool's arguments reach a model as a JSON Schema: pydantic's `model_json_schema()`, an MCP
+server's `inputSchema`, a LangChain tool's `args_schema`. Pydantic writes every nested model as a
+`$ref` into the schema's `$defs`, and every optional field as `anyOf: [X, {"type": "null"}]`.
+Anything that reads only a property's own `type` gets both wrong. A model is shown a string where
+the tool wants a list of objects, and an input normaliser leaves `"[]"` as a string where the tool
+wants a list.
+
+This package has **no dependencies**, so any tool host can take it without inheriting a framework:
+a LangGraph app, an MCP server, a model adapter, a validator.
+
+## `self_contained_input_schema`
+
+One schema per tool, with no references left in it.
+
+```python
+from pydantic import BaseModel
+from threetears.tool_schema import self_contained_input_schema
+
+
+class Shot(BaseModel):
+    prompt: str
+    seconds: int | None = None
+
+
+class Storyboard(BaseModel):
+    shots: list[Shot]
+
+
+schema = self_contained_input_schema(Storyboard.model_json_schema(), tool_name="storyboard")
+# {"type": "object",
+#  "properties": {"shots": {"type": "array",
+#                           "items": {"type": "object",
+#                                     "properties": {"prompt": {"type": "string"},
+#                                                    "seconds": {"type": "integer"}},
+#                                     "required": ["prompt"]}}},
+#  "required": ["shots"]}
+```
+
+What it does:
+
+- Inlines every `$ref` into the schema's own `$defs` or `definitions`, through `items`, unions and
+  nested properties. Each level keeps its `required` list and descriptions, and a field's own
+  description wins over its model's.
+- Collapses an optional union (`anyOf: [X, null]`) to `X` at every depth, dropping the
+  `default: null` that would contradict `X`.
+- Keeps a union of two or more real members whole, rather than choosing one.
+- Leaves an untyped (`Any`) field untyped.
+- Expands a recursive model until it recurs. The point of recursion keeps the definition's type and
+  reads `"A Node: the same shape as the Node that contains it."`, rather than being cut to `{}`.
+- Drops titles and the root description; the tool's description travels beside its schema.
+- Always returns `type: "object"`, `properties` and `required`.
+
+A `$ref` to anything but the schema's own definitions raises `ValueError` naming the tool and the
+reference. A reference left in place would point at nothing the reader has.
+
+### In an MCP server
+
+List a tool whose arguments are a pydantic model, with an `inputSchema` any client can read:
+
+```python
+from mcp.types import Tool
+from threetears.tool_schema import self_contained_input_schema
+
+tool = Tool(
+    name="storyboard",
+    description="Plan the shots for a scene.",
+    inputSchema=self_contained_input_schema(Storyboard.model_json_schema(), tool_name="storyboard"),
+)
+```
+
+### In a LangGraph app
+
+Hand a model provider that takes raw tool specs the same self-contained shape:
+
+```python
+from langchain_core.tools import StructuredTool
+from threetears.tool_schema import self_contained_input_schema
+
+tool = StructuredTool.from_function(plan, name="storyboard", args_schema=Storyboard)
+spec = {
+    "name": tool.name,
+    "description": tool.description,
+    "input_schema": self_contained_input_schema(Storyboard.model_json_schema(), tool_name=tool.name),
+}
+```
+
+## `declared_type`
+
+The one JSON type a property declares, read through the shapes pydantic writes. Use it to coerce
+loose input toward the declared type.
+
+```python
+from threetears.tool_schema import declared_type
+
+schema = Storyboard.model_json_schema()
+declared_type(schema["properties"]["shots"], schema)  # "array"
+```
+
+It reads through:
+
+- a nullable type list, such as `["array", "null"]`;
+- an optional union;
+- a `$ref` into the schema's definitions.
+
+It answers `None` for a union of two or more real types, and for a reference it cannot follow. It
+never raises, so code that must not fail on a schema it only half understands can call it.
+
+In 3tears, `3tears-models` shows every bound tool to a Claude subscription model through
+`self_contained_input_schema`, and `3tears-agent-tools` coerces tool input with `declared_type`.

3tears_tool_schema-0.55.0/README.md

@@ -0,0 +1,113 @@
+# 3tears-tool-schema
+
+Dependency-free helpers for the JSON Schema a tool advertises for its arguments.
+
+A tool's arguments reach a model as a JSON Schema: pydantic's `model_json_schema()`, an MCP
+server's `inputSchema`, a LangChain tool's `args_schema`. Pydantic writes every nested model as a
+`$ref` into the schema's `$defs`, and every optional field as `anyOf: [X, {"type": "null"}]`.
+Anything that reads only a property's own `type` gets both wrong. A model is shown a string where
+the tool wants a list of objects, and an input normaliser leaves `"[]"` as a string where the tool
+wants a list.
+
+This package has **no dependencies**, so any tool host can take it without inheriting a framework:
+a LangGraph app, an MCP server, a model adapter, a validator.
+
+## `self_contained_input_schema`
+
+One schema per tool, with no references left in it.
+
+```python
+from pydantic import BaseModel
+from threetears.tool_schema import self_contained_input_schema
+
+
+class Shot(BaseModel):
+    prompt: str
+    seconds: int | None = None
+
+
+class Storyboard(BaseModel):
+    shots: list[Shot]
+
+
+schema = self_contained_input_schema(Storyboard.model_json_schema(), tool_name="storyboard")
+# {"type": "object",
+#  "properties": {"shots": {"type": "array",
+#                           "items": {"type": "object",
+#                                     "properties": {"prompt": {"type": "string"},
+#                                                    "seconds": {"type": "integer"}},
+#                                     "required": ["prompt"]}}},
+#  "required": ["shots"]}
+```
+
+What it does:
+
+- Inlines every `$ref` into the schema's own `$defs` or `definitions`, through `items`, unions and
+  nested properties. Each level keeps its `required` list and descriptions, and a field's own
+  description wins over its model's.
+- Collapses an optional union (`anyOf: [X, null]`) to `X` at every depth, dropping the
+  `default: null` that would contradict `X`.
+- Keeps a union of two or more real members whole, rather than choosing one.
+- Leaves an untyped (`Any`) field untyped.
+- Expands a recursive model until it recurs. The point of recursion keeps the definition's type and
+  reads `"A Node: the same shape as the Node that contains it."`, rather than being cut to `{}`.
+- Drops titles and the root description; the tool's description travels beside its schema.
+- Always returns `type: "object"`, `properties` and `required`.
+
+A `$ref` to anything but the schema's own definitions raises `ValueError` naming the tool and the
+reference. A reference left in place would point at nothing the reader has.
+
+### In an MCP server
+
+List a tool whose arguments are a pydantic model, with an `inputSchema` any client can read:
+
+```python
+from mcp.types import Tool
+from threetears.tool_schema import self_contained_input_schema
+
+tool = Tool(
+    name="storyboard",
+    description="Plan the shots for a scene.",
+    inputSchema=self_contained_input_schema(Storyboard.model_json_schema(), tool_name="storyboard"),
+)
+```
+
+### In a LangGraph app
+
+Hand a model provider that takes raw tool specs the same self-contained shape:
+
+```python
+from langchain_core.tools import StructuredTool
+from threetears.tool_schema import self_contained_input_schema
+
+tool = StructuredTool.from_function(plan, name="storyboard", args_schema=Storyboard)
+spec = {
+    "name": tool.name,
+    "description": tool.description,
+    "input_schema": self_contained_input_schema(Storyboard.model_json_schema(), tool_name=tool.name),
+}
+```
+
+## `declared_type`
+
+The one JSON type a property declares, read through the shapes pydantic writes. Use it to coerce
+loose input toward the declared type.
+
+```python
+from threetears.tool_schema import declared_type
+
+schema = Storyboard.model_json_schema()
+declared_type(schema["properties"]["shots"], schema)  # "array"
+```
+
+It reads through:
+
+- a nullable type list, such as `["array", "null"]`;
+- an optional union;
+- a `$ref` into the schema's definitions.
+
+It answers `None` for a union of two or more real types, and for a reference it cannot follow. It
+never raises, so code that must not fail on a schema it only half understands can call it.
+
+In 3tears, `3tears-models` shows every bound tool to a Claude subscription model through
+`self_contained_input_schema`, and `3tears-agent-tools` coerces tool input with `declared_type`.

3tears_tool_schema-0.55.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "3tears-tool-schema"
+version = "0.55.0"
+description = "Dependency-free helpers that make a tool's JSON Schema self-contained for models and validators"
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [{name = "pace"}]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+# dependency-free by design, enforced by the contract-purity check in
+# tests/enforcement/: every tool host needs this -- a model adapter, a tool
+# framework, an agent SDK, an MCP server -- and none of them should inherit
+# another's dependency closure to read a JSON Schema.
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/pacepace/3tears"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threetears"]

3tears_tool_schema-0.55.0/src/threetears/tool_schema/__init__.py

@@ -0,0 +1,28 @@
+"""dependency-free helpers for the JSON Schema a tool advertises for its arguments.
+
+:func:`self_contained_input_schema` inlines every ``$ref`` and collapses every optional union, so a
+model or validator handed one schema per tool sees nested models as the objects they are.
+:func:`declared_type` reads the one JSON type a property declares through optional unions and
+references. This package depends on nothing, so every tool host -- a model adapter, a tool
+framework, an MCP server -- can take it without inheriting another's dependency closure; purity is
+enforced by the contract-purity check in the workspace's ``tests/enforcement/``.
+"""
+
+# Version derived from package metadata so the metadata is the single source of truth -- a release
+# that bumps pyproject cannot leave a stale runtime ``__version__`` behind. The fallback keeps the
+# import working from a source tree that was never installed. ``importlib.metadata`` is stdlib, so
+# the dependency-free floor is untouched.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("3tears-tool-schema")
+except _PackageNotFoundError:  # pragma: no cover - dev fallback
+    __version__ = "unknown"
+
+from threetears.tool_schema.self_contained import declared_type, self_contained_input_schema
+
+__all__ = [
+    "declared_type",
+    "self_contained_input_schema",
+]

3tears_tool_schema-0.55.0/src/threetears/tool_schema/self_contained.py

@@ -0,0 +1,275 @@
+"""a tool's JSON Schema made self-contained, and the one type a property declares.
+
+A tool advertises its arguments as a JSON Schema -- pydantic's ``model_json_schema()``, an MCP
+server's ``inputSchema``, a LangChain tool's ``args_schema`` -- and pydantic writes every nested
+model as a ``$ref`` into the schema's ``$defs`` and every optional field as
+``anyOf: [X, {"type": "null"}]``. A consumer that reads only a property's own ``type`` then sees a
+nested model as nothing and an optional list as nothing: a model is shown a string field where the
+tool wants a list of objects, and an input normaliser leaves a JSON-encoded list as a string.
+
+:func:`self_contained_input_schema` resolves all of that into one schema with no references, for a
+model or validator that is handed a single schema per tool. :func:`declared_type` answers the
+narrower question a normaliser asks of one property: which single JSON type does it declare.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+__all__ = [
+    "declared_type",
+    "self_contained_input_schema",
+]
+
+#: JSON Schema keywords whose value is one subschema.
+_SUBSCHEMA_KEYWORDS = frozenset(
+    {"items", "additionalProperties", "not", "contains", "if", "then", "else", "propertyNames", "unevaluatedItems"}
+)
+
+#: JSON Schema keywords whose value is a list of subschemas.
+_SUBSCHEMA_LIST_KEYWORDS = frozenset({"anyOf", "oneOf", "allOf", "prefixItems"})
+
+#: JSON Schema keywords whose value maps names to subschemas. The names are data, not keywords.
+_SUBSCHEMA_MAP_KEYWORDS = frozenset({"properties", "patternProperties", "dependentSchemas", "$defs", "definitions"})
+
+#: Where a local definition lives, for each spelling of it: ``$defs`` (JSON Schema 2019-09 on,
+#: pydantic 2) and ``definitions`` (draft 7, pydantic 1).
+_DEFINITION_PREFIXES = ("#/$defs/", "#/definitions/")
+
+
+def _definitions(schema: Mapping[str, Any]) -> dict[str, Any]:
+    """the schema's local definitions, both spellings merged.
+
+    :param schema: the root schema
+    :ptype schema: Mapping[str, Any]
+    :return: definition name to definition
+    :rtype: dict[str, Any]
+    """
+    return {**(schema.get("definitions") or {}), **(schema.get("$defs") or {})}
+
+
+def _local_definition_name(ref: str) -> str | None:
+    """the name of the local definition ``ref`` points at, or ``None`` when it points elsewhere.
+
+    :param ref: a ``$ref`` value
+    :ptype ref: str
+    :return: the definition's name, JSON-pointer escapes decoded, or ``None``
+    :rtype: str | None
+    """
+    prefix = next((p for p in _DEFINITION_PREFIXES if ref.startswith(p)), None)
+    name: str | None = None
+    if prefix is not None and "/" not in ref[len(prefix) :]:
+        name = ref[len(prefix) :].replace("~1", "/").replace("~0", "~")
+    return name
+
+
+def _walk_subschemas(node: Mapping[str, Any], transform: Callable[[Any], Any]) -> dict[str, Any]:
+    """``node`` with ``transform`` applied to every subschema it holds, and everything else copied.
+
+    Only schema-bearing keywords are walked: a ``default``, ``enum``, ``const`` or ``examples`` value
+    is data, and a dict inside one must not be read as a schema.
+
+    :param node: one schema object
+    :ptype node: Mapping[str, Any]
+    :param transform: applied to each immediate subschema
+    :ptype transform: Callable[[Any], Any]
+    :return: a new schema object; ``node`` is not mutated
+    :rtype: dict[str, Any]
+    """
+    walked: dict[str, Any] = {}
+    for key, value in node.items():
+        if key in _SUBSCHEMA_KEYWORDS and isinstance(value, Mapping):
+            walked[key] = transform(value)
+        elif key in _SUBSCHEMA_LIST_KEYWORDS and isinstance(value, list):
+            walked[key] = [transform(item) for item in value]
+        elif key in _SUBSCHEMA_MAP_KEYWORDS and isinstance(value, Mapping):
+            walked[key] = {name: transform(item) for name, item in value.items()}
+        else:
+            walked[key] = value
+    return walked
+
+
+def _collapse_optional(node: Any) -> Any:
+    """``node`` with every ``X | None`` union collapsed to ``X``, at every depth.
+
+    Pydantic renders an optional field as ``anyOf: [X, {"type": "null"}]`` with no top-level
+    ``type``. A union with exactly one non-null member becomes that member, carrying the field's
+    own keywords over it -- the field's description is the more specific one -- minus the
+    ``default: null`` that would contradict the member's type. A union of two or more real members
+    is left whole: choosing one would drop the others.
+
+    :param node: a schema, or any value inside one
+    :ptype node: Any
+    :return: the schema with optional unions collapsed; ``node`` is not mutated
+    :rtype: Any
+    """
+    if not isinstance(node, Mapping):
+        return node
+    result = _walk_subschemas(node, _collapse_optional)
+    union_key = "anyOf" if "anyOf" in result else "oneOf" if "oneOf" in result else None
+    if union_key is not None and "type" not in result:
+        members = result[union_key]
+        real = [m for m in members if not (isinstance(m, Mapping) and m.get("type") == "null")]
+        if len(real) == 1 and len(real) < len(members) and isinstance(real[0], Mapping):
+            field = {k: v for k, v in result.items() if k != union_key and not (k == "default" and v is None)}
+            result = {**real[0], **field}
+    return result
+
+
+def _inline_refs(
+    node: Any,
+    definitions: dict[str, Any],
+    tool_name: str,
+    expanding: tuple[str, ...] = (),
+) -> Any:
+    """``node`` with every ``$ref`` replaced by the definition it names, and titles removed.
+
+    A reference's sibling keywords override the definition's -- pydantic writes a field's own
+    description beside the ``$ref``, and it is the more specific one. Titles go because they are
+    noise to a model, and LangChain's own conversion for the provider APIs removes them too.
+
+    A recursive model cannot be inlined completely: its schema is infinite. It is expanded until a
+    definition recurs inside its own expansion, and at that point the schema says in words what
+    the value is -- the same shape as the enclosing one -- keeping the definition's ``type``. A
+    bounded expansion rather than a refusal, so a tool with a tree-shaped argument stays usable;
+    described rather than cut to ``{}``, so a model is not shown "anything" where the tool requires
+    a particular shape.
+
+    :param node: a schema, or any value inside one
+    :ptype node: Any
+    :param definitions: the root schema's ``$defs`` and ``definitions``, merged
+    :ptype definitions: dict[str, Any]
+    :param tool_name: the tool whose schema this is, for errors
+    :ptype tool_name: str
+    :param expanding: the definitions being expanded on the path to ``node``, outermost first
+    :ptype expanding: tuple[str, ...]
+    :return: the inlined schema; ``node`` is not mutated
+    :rtype: Any
+    :raises ValueError: when a ``$ref`` names no local definition
+    """
+    if not isinstance(node, Mapping):
+        return node
+    siblings = _walk_subschemas(
+        {k: v for k, v in node.items() if k not in ("$ref", "title", "$defs", "definitions")},
+        lambda child: _inline_refs(child, definitions, tool_name, expanding),
+    )
+    ref = node.get("$ref")
+    result: Any = siblings
+    if isinstance(ref, str):
+        name = _local_definition_name(ref)
+        if name is None:
+            raise ValueError(
+                f"tool {tool_name!r}: cannot make its input schema self-contained: $ref {ref!r} does "
+                "not name a definition in the schema's own $defs, so it cannot be inlined"
+            )
+        if name not in definitions:
+            raise ValueError(
+                f"tool {tool_name!r}: cannot make its input schema self-contained: $ref {ref!r} names "
+                "a definition the schema does not carry"
+            )
+        definition = definitions[name]
+        if name in expanding:
+            note = f"A {name}: the same shape as the {name} that contains it."
+            field_description = siblings.pop("description", None)
+            recursion: dict[str, Any] = {"description": f"{field_description} {note}" if field_description else note}
+            if isinstance(definition, Mapping) and "type" in definition:
+                recursion = {"type": definition["type"], **recursion}
+            result = {**recursion, **siblings}
+        else:
+            expanded = _inline_refs(definition, definitions, tool_name, (*expanding, name))
+            result = {**expanded, **siblings} if isinstance(expanded, Mapping) else expanded
+    return result
+
+
+def self_contained_input_schema(schema: Mapping[str, Any], *, tool_name: str) -> dict[str, Any]:
+    """a tool's input schema with every reference inlined, as one ``type: object`` schema.
+
+    For a consumer handed one schema per tool and no shared definitions -- a model's tool listing,
+    an MCP client, a validator given the properties alone. Every ``$ref`` into the schema's own
+    ``$defs`` / ``definitions`` is inlined, through ``items``, unions and nested properties, with
+    each level's ``required`` list and descriptions kept; a field's description wins over its
+    model's. Every optional union (``anyOf: [X, null]``) collapses to ``X`` at every depth; a union
+    of two or more real members is kept whole; an untyped field stays untyped. A recursive model is
+    expanded until it recurs, and the point of recursion reads
+    ``"A Node: the same shape as the Node that contains it."`` with the definition's type. Titles
+    and the root description are dropped -- the tool's own description travels beside its schema.
+
+    The result always has ``type: "object"``, ``properties`` and ``required``, so a builder that
+    would otherwise mark every property required uses it as it stands.
+
+    :param schema: the tool's input JSON Schema -- pydantic's ``model_json_schema()``, an MCP
+        ``inputSchema``, a LangChain ``args_schema`` or ``tool_call_schema``; not mutated
+    :ptype schema: Mapping[str, Any]
+    :param tool_name: the tool's name, for errors
+    :ptype tool_name: str
+    :return: the self-contained schema
+    :rtype: dict[str, Any]
+    :raises ValueError: when a ``$ref`` points anywhere but the schema's own definitions, or names
+        one it does not carry -- a reference left in place would point at nothing the reader has
+    """
+    collapsed = _collapse_optional(schema)
+    root = _inline_refs(collapsed, _definitions(collapsed), tool_name)
+    root.pop("description", None)
+    return {
+        **root,
+        "type": "object",
+        "properties": root.get("properties") or {},
+        "required": list(root.get("required") or []),
+    }
+
+
+def declared_type(prop: Any, schema: Mapping[str, Any]) -> str | None:
+    """the one JSON Schema type ``prop`` declares, read through the shapes pydantic writes.
+
+    A property's own ``type`` answers when it is a string, or a list naming one type besides
+    ``null``. An optional field has no ``type`` -- pydantic writes ``anyOf: [X, {"type": "null"}]``
+    -- and answers with ``X``'s. A nested model is a ``$ref`` into the schema's own definitions and
+    answers with the definition's. A union of two or more real types answers ``None``: the value
+    may be any of them, and treating it as one would choose for the caller. So does a reference
+    that points elsewhere or names nothing, and one already being followed.
+
+    Never raises: it is for code that must not fail on a schema it half understands, such as a
+    normaliser that coerces a JSON-encoded string into the list a property declares.
+
+    :param prop: one property's schema
+    :ptype prop: Any
+    :param schema: the whole schema, whose definitions a reference names
+    :ptype schema: Mapping[str, Any]
+    :return: the declared type, or ``None`` when there is no single one
+    :rtype: str | None
+    """
+    return _declared_type(prop, schema, frozenset())
+
+
+def _declared_type(prop: Any, schema: Mapping[str, Any], following: frozenset[str]) -> str | None:
+    """:func:`declared_type`, carrying the references already followed so a cycle ends.
+
+    :param prop: one property's schema
+    :ptype prop: Any
+    :param schema: the whole schema
+    :ptype schema: Mapping[str, Any]
+    :param following: references already followed on this path
+    :ptype following: frozenset[str]
+    :return: the declared type, or ``None``
+    :rtype: str | None
+    """
+    result: str | None = None
+    if not isinstance(prop, Mapping):
+        return result
+    declared = prop.get("type")
+    ref = prop.get("$ref")
+    members = prop.get("anyOf") or prop.get("oneOf")
+    if isinstance(declared, str):
+        result = declared
+    elif isinstance(declared, list):
+        real_types = [t for t in declared if t != "null"]
+        result = real_types[0] if len(real_types) == 1 and isinstance(real_types[0], str) else None
+    elif isinstance(ref, str) and ref not in following:
+        name = _local_definition_name(ref)
+        if name is not None:
+            result = _declared_type(_definitions(schema).get(name), schema, following | {ref})
+    elif isinstance(members, list):
+        real = [m for m in members if not (isinstance(m, Mapping) and m.get("type") == "null")]
+        result = _declared_type(real[0], schema, following) if len(real) == 1 else None
+    return result

3tears_tool_schema-0.55.0/tests/test_self_contained.py

@@ -0,0 +1,370 @@
+"""a tool's JSON Schema made self-contained, and the one type a property declares.
+
+The schema below is exactly what pydantic 2 renders for a storyboard tool's arguments -- nested
+models as ``$ref`` into ``$defs``, optional fields as ``anyOf`` with ``null``, a two-model union, an
+untyped field and a recursive outline -- written out so this dependency-free package is tested
+without pydantic.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+import pytest
+
+from threetears.tool_schema import declared_type, self_contained_input_schema
+
+_STORYBOARD: dict[str, Any] = {
+    "$defs": {
+        "Close": {
+            "description": "A close-up.",
+            "properties": {"subject": {"title": "Subject", "type": "string"}},
+            "required": ["subject"],
+            "title": "Close",
+            "type": "object",
+        },
+        "Lighting": {
+            "description": "How a scene is lit.",
+            "properties": {"key": {"description": "the key light", "title": "Key", "type": "string"}},
+            "required": ["key"],
+            "title": "Lighting",
+            "type": "object",
+        },
+        "Node": {
+            "description": "An outline node.",
+            "properties": {
+                "label": {"description": "the node's text", "title": "Label", "type": "string"},
+                "children": {
+                    "description": "the nodes under this one",
+                    "items": {"$ref": "#/$defs/Node"},
+                    "title": "Children",
+                    "type": "array",
+                },
+            },
+            "required": ["label"],
+            "title": "Node",
+            "type": "object",
+        },
+        "Scene": {
+            "description": "Where a scene happens.",
+            "properties": {
+                "location": {"description": "the place", "title": "Location", "type": "string"},
+                "lighting": {
+                    "anyOf": [{"$ref": "#/$defs/Lighting"}, {"type": "null"}],
+                    "default": None,
+                    "description": "the lighting, when it matters",
+                },
+            },
+            "required": ["location"],
+            "title": "Scene",
+            "type": "object",
+        },
+        "Shot": {
+            "description": "One camera shot.",
+            "properties": {
+                "prompt": {"description": "what the shot shows", "title": "Prompt", "type": "string"},
+                "seconds": {
+                    "anyOf": [{"type": "integer"}, {"type": "null"}],
+                    "default": None,
+                    "description": "how long it runs",
+                    "title": "Seconds",
+                },
+            },
+            "required": ["prompt"],
+            "title": "Shot",
+            "type": "object",
+        },
+        "Wide": {
+            "description": "A wide shot.",
+            "properties": {"landscape": {"title": "Landscape", "type": "string"}},
+            "required": ["landscape"],
+            "title": "Wide",
+            "type": "object",
+        },
+    },
+    "properties": {
+        "shots": {
+            "description": "the shots, in order",
+            "items": {"$ref": "#/$defs/Shot"},
+            "title": "Shots",
+            "type": "array",
+        },
+        "scene": {"$ref": "#/$defs/Scene", "description": "the scene they belong to"},
+        "framing": {
+            "anyOf": [{"$ref": "#/$defs/Close"}, {"$ref": "#/$defs/Wide"}],
+            "description": "the framing",
+            "title": "Framing",
+        },
+        "anything": {"default": None, "description": "any value at all", "title": "Anything"},
+        "outline": {
+            "anyOf": [{"$ref": "#/$defs/Node"}, {"type": "null"}],
+            "default": None,
+            "description": "the outline, if there is one",
+        },
+    },
+    "required": ["shots", "scene", "framing"],
+    "title": "StoryboardInput",
+    "type": "object",
+}
+
+
+_SHOT = {
+    "type": "object",
+    "description": "One camera shot.",
+    "properties": {
+        "prompt": {"type": "string", "description": "what the shot shows"},
+        "seconds": {"type": "integer", "description": "how long it runs"},
+    },
+    "required": ["prompt"],
+}
+
+
+def _storyboard() -> dict[str, Any]:
+    """the storyboard schema, self-contained.
+
+    :return: the result
+    :rtype: dict[str, Any]
+    """
+    return self_contained_input_schema(_STORYBOARD, tool_name="storyboard")
+
+
+class TestSelfContainedInputSchema:
+    def test_a_list_of_models_is_an_array_of_objects(self) -> None:
+        """``list[Shot]`` is an array of Shot objects, each keeping its required list.
+
+        :return: none
+        :rtype: None
+        """
+        assert _storyboard()["properties"]["shots"] == {
+            "type": "array",
+            "description": "the shots, in order",
+            "items": _SHOT,
+        }
+
+    def test_a_nested_sub_object_keeps_its_properties_required_list_and_field_description(self) -> None:
+        """a sub-object is the object, and the field's description wins over the model's.
+
+        :return: none
+        :rtype: None
+        """
+        scene = _storyboard()["properties"]["scene"]
+        assert scene["type"] == "object"
+        assert scene["description"] == "the scene they belong to"
+        assert scene["required"] == ["location"]
+        assert scene["properties"]["location"] == {"type": "string", "description": "the place"}
+
+    def test_an_optional_nested_model_is_unwrapped_to_the_object(self) -> None:
+        """``Lighting | None`` collapses to the Lighting object, at any depth.
+
+        :return: none
+        :rtype: None
+        """
+        assert _storyboard()["properties"]["scene"]["properties"]["lighting"] == {
+            "type": "object",
+            "description": "the lighting, when it matters",
+            "properties": {"key": {"type": "string", "description": "the key light"}},
+            "required": ["key"],
+        }
+
+    def test_a_union_of_models_keeps_every_member(self) -> None:
+        """``Close | Wide`` stays a union of both, never the first alone.
+
+        :return: none
+        :rtype: None
+        """
+        framing = _storyboard()["properties"]["framing"]
+        assert framing["description"] == "the framing"
+        assert [sorted(member["properties"]) for member in framing["anyOf"]] == [["subject"], ["landscape"]]
+
+    def test_an_untyped_field_is_not_forced_to_a_string(self) -> None:
+        """``Any`` stays untyped.
+
+        :return: none
+        :rtype: None
+        """
+        assert _storyboard()["properties"]["anything"] == {"default": None, "description": "any value at all"}
+
+    def test_no_reference_is_left_dangling(self) -> None:
+        """nothing in the result points anywhere.
+
+        :return: none
+        :rtype: None
+        """
+        result = _storyboard()
+        assert "$ref" not in repr(result)
+        assert "$defs" not in result
+
+    def test_the_top_level_is_an_object_with_the_models_required_list(self) -> None:
+        """``type``, ``properties`` and ``required`` are always there.
+
+        :return: none
+        :rtype: None
+        """
+        result = _storyboard()
+        assert result["type"] == "object"
+        assert result["required"] == ["shots", "scene", "framing"]
+        assert "title" not in result
+        assert "description" not in result
+
+    def test_a_recursive_model_is_expanded_once_and_its_recursion_named(self) -> None:
+        """the point of recursion keeps its type and says in words what it is.
+
+        :return: none
+        :rtype: None
+        """
+        outline = _storyboard()["properties"]["outline"]
+        assert outline["type"] == "object"
+        assert outline["description"] == "the outline, if there is one"
+        children = outline["properties"]["children"]
+        assert children["type"] == "array"
+        assert children["description"] == "the nodes under this one"
+        assert children["items"] == {
+            "type": "object",
+            "description": "A Node: the same shape as the Node that contains it.",
+        }
+
+    def test_the_draft_7_definitions_spelling_is_inlined_too(self) -> None:
+        """pydantic 1 and draft-7 schemas keep definitions under ``definitions``.
+
+        :return: none
+        :rtype: None
+        """
+        schema = {
+            "type": "object",
+            "properties": {"shot": {"$ref": "#/definitions/Shot"}},
+            "definitions": {"Shot": {"type": "object", "properties": {"prompt": {"type": "string"}}}},
+        }
+        assert self_contained_input_schema(schema, tool_name="t")["properties"]["shot"] == {
+            "type": "object",
+            "properties": {"prompt": {"type": "string"}},
+        }
+
+    def test_a_schema_with_no_properties_is_still_an_object(self) -> None:
+        """an argument-less tool gets empty ``properties`` and ``required``.
+
+        :return: none
+        :rtype: None
+        """
+        assert self_contained_input_schema({}, tool_name="t") == {"type": "object", "properties": {}, "required": []}
+
+    def test_the_input_is_not_mutated(self) -> None:
+        """callers keep the schema they passed.
+
+        :return: none
+        :rtype: None
+        """
+        before = copy.deepcopy(_STORYBOARD)
+        _storyboard()
+        assert _STORYBOARD == before
+
+    def test_a_reference_outside_the_schema_is_refused_naming_the_tool(self) -> None:
+        """a foreign reference cannot be inlined, and a left one points at nothing.
+
+        :return: none
+        :rtype: None
+        """
+        schema = {"type": "object", "properties": {"shot": {"$ref": "https://example.com/shot.json"}}}
+        with pytest.raises(ValueError, match=r"storyboard.*https://example.com/shot.json"):
+            self_contained_input_schema(schema, tool_name="storyboard")
+
+    def test_a_reference_to_a_missing_definition_is_refused_naming_the_tool(self) -> None:
+        """a local reference to a definition the schema lacks is refused too.
+
+        :return: none
+        :rtype: None
+        """
+        schema = {"type": "object", "properties": {"shot": {"$ref": "#/$defs/Missing"}}}
+        with pytest.raises(ValueError, match=r"storyboard.*#/\$defs/Missing"):
+            self_contained_input_schema(schema, tool_name="storyboard")
+
+
+class TestDeclaredType:
+    def test_a_plain_type(self) -> None:
+        """a property's own ``type`` answers.
+
+        :return: none
+        :rtype: None
+        """
+        assert declared_type(_STORYBOARD["properties"]["shots"], _STORYBOARD) == "array"
+
+    def test_an_optional_field_answers_with_its_member(self) -> None:
+        """``anyOf: [integer, null]`` declares integer.
+
+        :return: none
+        :rtype: None
+        """
+        shot = _STORYBOARD["$defs"]["Shot"]
+        assert declared_type(shot["properties"]["seconds"], _STORYBOARD) == "integer"
+
+    def test_a_nullable_type_list_answers_with_the_real_type(self) -> None:
+        """``["array", "null"]`` declares array.
+
+        :return: none
+        :rtype: None
+        """
+        assert declared_type({"type": ["array", "null"]}, {}) == "array"
+
+    def test_a_nested_model_answers_with_its_definition(self) -> None:
+        """a ``$ref`` is followed into the definitions.
+
+        :return: none
+        :rtype: None
+        """
+        assert declared_type(_STORYBOARD["properties"]["scene"], _STORYBOARD) == "object"
+
+    def test_an_optional_nested_model_answers_with_its_definition(self) -> None:
+        """an optional ``$ref`` is followed too.
+
+        :return: none
+        :rtype: None
+        """
+        assert declared_type(_STORYBOARD["properties"]["outline"], _STORYBOARD) == "object"
+
+    def test_a_union_of_real_types_declares_no_single_type(self) -> None:
+        """``Close | Wide`` could be either.
+
+        :return: none
+        :rtype: None
+        """
+        assert declared_type(_STORYBOARD["properties"]["framing"], _STORYBOARD) is None
+
+    def test_an_untyped_field_declares_nothing(self) -> None:
+        """``Any`` declares no type.
+
+        :return: none
+        :rtype: None
+        """
+        assert declared_type(_STORYBOARD["properties"]["anything"], _STORYBOARD) is None
+
+    def test_a_reference_it_cannot_follow_declares_nothing_and_does_not_raise(self) -> None:
+        """a missing or foreign reference answers ``None``.
+
+        :return: none
+        :rtype: None
+        """
+        assert declared_type({"$ref": "#/$defs/Missing"}, {}) is None
+        assert declared_type({"$ref": "https://example.com/x.json"}, {}) is None
+
+    def test_a_reference_cycle_ends(self) -> None:
+        """a definition that is only a reference to itself answers ``None`` rather than looping.
+
+        :return: none
+        :rtype: None
+        """
+        schema = {"$defs": {"Loop": {"$ref": "#/$defs/Loop"}}}
+        assert declared_type({"$ref": "#/$defs/Loop"}, schema) is None
+
+
+class TestPublicSurface:
+    def test_every_exported_name_is_importable(self) -> None:
+        """``__all__`` names what the package exports, and each resolves.
+
+        :return: none
+        :rtype: None
+        """
+        import threetears.tool_schema as tool_schema
+
+        assert tool_schema.__all__
+        for name in tool_schema.__all__:
+            assert callable(getattr(tool_schema, name))