hidden-moves-openai 0.1.0__tar.gz

hidden_moves_openai-0.1.0/LICENSE

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

hidden_moves_openai-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: hidden-moves-openai
+Version: 0.1.0
+Summary: Export selected Python capabilities as OpenAI Responses function tools.
+Keywords: openai,responses,function-calling,tools
+Author: Ella Inng
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: hidden-moves>=0.1,<0.2
+Maintainer: Outside Labs
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/outside-labs/hidden_moves
+Project-URL: Source, https://github.com/outside-labs/hidden_moves
+Project-URL: Issues, https://github.com/outside-labs/hidden_moves/issues
+Project-URL: Documentation, https://github.com/outside-labs/hidden_moves/blob/main/packages/hidden-moves-openai/README.md
+Description-Content-Type: text/markdown
+
+# Function-tool adapter
+
+This separate distribution exports a selected `CapabilityCatalog` as OpenAI
+Responses function tools and dispatches returned calls through that catalog.
+It uses the standard library and the core package; an API SDK is optional in the
+application that consumes it.
+
+```sh
+python -m pip install hidden-moves-openai==0.1.0
+```
+
+The experimental 0.1.x adapter depends on `hidden-moves>=0.1,<0.2` and Python
+3.11 or newer. Published GitHub releases use `v0.1.0-openai` for this package in
+the shared repository. `.github/workflows/release.yaml` checks installed-wheel
+offline export and dispatch, then publishes in environment `pypi-openai`.
+
+## Local setup
+
+From the repository root, install both distributions in your chosen environment:
+
+```sh
+uv pip install --python .venv/bin/python -e . -e ./examples/text-plugin -e ./packages/hidden-moves-openai
+```
+
+Export and dispatch work offline:
+
+```python
+import asyncio
+import json
+
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from hidden_moves_example_text import repeat_text
+from hidden_moves_openai import FunctionToolAdapter
+
+moves = Moves()
+moves.learn(repeat_text, name="repeat", namespace="example.text")
+adapter = FunctionToolAdapter(CapabilityCatalog(moves, ["example.text.repeat"]))
+print(json.dumps(adapter.tools(), indent=2))
+
+output = asyncio.run(adapter.call_output(
+	"local-call-1", "example__text__repeat", '{"value": "Hello World"}',
+))
+assert json.loads(output["output"]) == "Hello World Hello World"
+```
+
+In an existing asynchronous Responses application, pass `adapter.tools()` as
+`tools`. For each returned `function_call` item, use
+`await adapter.call_output(item.call_id, item.name, item.arguments)` to construct
+its result item. The application keeps the response history, sends results to
+the API, and decides whether to request another response. The adapter owns no
+API client, credentials, model choice, retries, approvals, or event loop.
+
+## Names and schemas
+
+Dots become double underscores: `example.text.repeat` exports as `example__text__repeat`.
+Names use 1-64 ASCII letters, digits, underscores, or hyphens. Invalid names and
+collisions fail at construction; use `tool_names={"qualified.name": "alias"}`
+for an explicit mapping. The original catalog retains its qualified names.
+
+Tool dictionaries use the flat Responses format, with explicit `strict=False`
+by default. This preserves omitted Python defaults. Schema dialect declarations,
+defaults, and examples are omitted from the exported parameters. Property names
+and neutral definitions remain unchanged. Behavioral hints and arbitrary metadata
+stay in the catalog rather than becoming unsupported API fields.
+
+`strict=True` accepts a conservative structural subset: each object is closed
+and requires every property; arrays have typed items; unions use `anyOf` or a
+nullable type pair. Scalar enums gain an inferred type when possible. Optional
+properties, open mappings, untyped values, and mixed untyped enums fail exposure.
+The adapter does not replace omitted arguments with `null` or invent required
+defaults. Model-specific schema size limits remain the application's concern.
+
+These choices follow the official [function calling guide](https://developers.openai.com/api/docs/guides/function-calling)
+and [Structured Outputs requirements](https://developers.openai.com/api/docs/guides/structured-outputs),
+checked October 3, 2026. Local tests validate export and dispatch. Live API
+acceptance and a model conversation have not been tested.
+
+## Invocation and errors
+
+`call(name, arguments)` accepts a JSON string or mapping and returns JSON text.
+`call_output` adds the supplied call ID in a `function_call_output` item.
+Only selected aliases can dispatch, and validation happens before invocation.
+Async functions and returned awaitables run in the caller's existing loop;
+synchronous functions run inline. Results use the catalog's dataclass, enum,
+TypedDict, and finite JSON conversions and output validation.
+
+Invalid arguments raise `CapabilityArgumentError`; invalid results raise
+`CapabilityResultError`; unselected names raise `UnknownMoveError`. Capability
+exceptions and cancellation propagate to the application. The application must
+choose its error reporting and invocation policy before returning failures to
+a remote service.
+
+Run the adapter tests in an environment with both local packages installed:
+
+```sh
+python -m unittest discover -s packages/hidden-moves-openai/tests -v
+```

hidden_moves_openai-0.1.0/README.md

@@ -0,0 +1,98 @@
+# Function-tool adapter
+
+This separate distribution exports a selected `CapabilityCatalog` as OpenAI
+Responses function tools and dispatches returned calls through that catalog.
+It uses the standard library and the core package; an API SDK is optional in the
+application that consumes it.
+
+```sh
+python -m pip install hidden-moves-openai==0.1.0
+```
+
+The experimental 0.1.x adapter depends on `hidden-moves>=0.1,<0.2` and Python
+3.11 or newer. Published GitHub releases use `v0.1.0-openai` for this package in
+the shared repository. `.github/workflows/release.yaml` checks installed-wheel
+offline export and dispatch, then publishes in environment `pypi-openai`.
+
+## Local setup
+
+From the repository root, install both distributions in your chosen environment:
+
+```sh
+uv pip install --python .venv/bin/python -e . -e ./examples/text-plugin -e ./packages/hidden-moves-openai
+```
+
+Export and dispatch work offline:
+
+```python
+import asyncio
+import json
+
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from hidden_moves_example_text import repeat_text
+from hidden_moves_openai import FunctionToolAdapter
+
+moves = Moves()
+moves.learn(repeat_text, name="repeat", namespace="example.text")
+adapter = FunctionToolAdapter(CapabilityCatalog(moves, ["example.text.repeat"]))
+print(json.dumps(adapter.tools(), indent=2))
+
+output = asyncio.run(adapter.call_output(
+	"local-call-1", "example__text__repeat", '{"value": "Hello World"}',
+))
+assert json.loads(output["output"]) == "Hello World Hello World"
+```
+
+In an existing asynchronous Responses application, pass `adapter.tools()` as
+`tools`. For each returned `function_call` item, use
+`await adapter.call_output(item.call_id, item.name, item.arguments)` to construct
+its result item. The application keeps the response history, sends results to
+the API, and decides whether to request another response. The adapter owns no
+API client, credentials, model choice, retries, approvals, or event loop.
+
+## Names and schemas
+
+Dots become double underscores: `example.text.repeat` exports as `example__text__repeat`.
+Names use 1-64 ASCII letters, digits, underscores, or hyphens. Invalid names and
+collisions fail at construction; use `tool_names={"qualified.name": "alias"}`
+for an explicit mapping. The original catalog retains its qualified names.
+
+Tool dictionaries use the flat Responses format, with explicit `strict=False`
+by default. This preserves omitted Python defaults. Schema dialect declarations,
+defaults, and examples are omitted from the exported parameters. Property names
+and neutral definitions remain unchanged. Behavioral hints and arbitrary metadata
+stay in the catalog rather than becoming unsupported API fields.
+
+`strict=True` accepts a conservative structural subset: each object is closed
+and requires every property; arrays have typed items; unions use `anyOf` or a
+nullable type pair. Scalar enums gain an inferred type when possible. Optional
+properties, open mappings, untyped values, and mixed untyped enums fail exposure.
+The adapter does not replace omitted arguments with `null` or invent required
+defaults. Model-specific schema size limits remain the application's concern.
+
+These choices follow the official [function calling guide](https://developers.openai.com/api/docs/guides/function-calling)
+and [Structured Outputs requirements](https://developers.openai.com/api/docs/guides/structured-outputs),
+checked October 3, 2026. Local tests validate export and dispatch. Live API
+acceptance and a model conversation have not been tested.
+
+## Invocation and errors
+
+`call(name, arguments)` accepts a JSON string or mapping and returns JSON text.
+`call_output` adds the supplied call ID in a `function_call_output` item.
+Only selected aliases can dispatch, and validation happens before invocation.
+Async functions and returned awaitables run in the caller's existing loop;
+synchronous functions run inline. Results use the catalog's dataclass, enum,
+TypedDict, and finite JSON conversions and output validation.
+
+Invalid arguments raise `CapabilityArgumentError`; invalid results raise
+`CapabilityResultError`; unselected names raise `UnknownMoveError`. Capability
+exceptions and cancellation propagate to the application. The application must
+choose its error reporting and invocation policy before returning failures to
+a remote service.
+
+Run the adapter tests in an environment with both local packages installed:
+
+```sh
+python -m unittest discover -s packages/hidden-moves-openai/tests -v
+```

hidden_moves_openai-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "hidden-moves-openai"
+version = "0.1.0"
+description = "Export selected Python capabilities as OpenAI Responses function tools."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "openai",
+    "responses",
+    "function-calling",
+    "tools",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["hidden-moves>=0.1,<0.2"]
+
+[[project.authors]]
+name = "Ella Inng"
+
+[[project.maintainers]]
+name = "Outside Labs"
+
+[project.urls]
+Homepage = "https://github.com/outside-labs/hidden_moves"
+Source = "https://github.com/outside-labs/hidden_moves"
+Issues = "https://github.com/outside-labs/hidden_moves/issues"
+Documentation = "https://github.com/outside-labs/hidden_moves/blob/main/packages/hidden-moves-openai/README.md"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"

hidden_moves_openai-0.1.0/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "hidden-moves-openai"
+version = "0.1.0"
+description = "Export selected Python capabilities as OpenAI Responses function tools."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ella Inng" }]
+maintainers = [{ name = "Outside Labs" }]
+keywords = ["openai", "responses", "function-calling", "tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["hidden-moves>=0.1,<0.2"]
+
+[project.urls]
+Homepage = "https://github.com/outside-labs/hidden_moves"
+Source = "https://github.com/outside-labs/hidden_moves"
+Issues = "https://github.com/outside-labs/hidden_moves/issues"
+Documentation = "https://github.com/outside-labs/hidden_moves/blob/main/packages/hidden-moves-openai/README.md"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"

hidden_moves_openai-0.1.0/src/hidden_moves_openai/__init__.py

@@ -0,0 +1,5 @@
+"""An optional function-tool format and dispatcher; no API client is required."""
+
+from .adapter import FunctionToolAdapter
+
+__all__ = ["FunctionToolAdapter"]

hidden_moves_openai-0.1.0/src/hidden_moves_openai/adapter.py

@@ -0,0 +1,141 @@
+"""Responses function tools consume the same selected catalog as other interfaces."""
+
+from __future__ import annotations
+
+import inspect
+import json
+import re
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any
+
+from hidden_moves import UnknownMoveError
+from hidden_moves.adapters import CapabilityArgumentError, CapabilityCatalog, CapabilityExposureError
+
+_TOOL_NAME = re.compile(r"[A-Za-z0-9_-]{1,64}\Z")
+_OMITTED_KEYWORDS = frozenset({"$schema", "default", "examples"})
+
+
+def _parameters(schema: dict[str, Any]) -> dict[str, Any]:
+	"""Drop declaration-only keywords without changing property names or enum values."""
+	result = {key: value for key, value in schema.items() if key not in _OMITTED_KEYWORDS}
+	if "properties" in result:
+		result["properties"] = {name: _parameters(child) for name, child in result["properties"].items()}
+	if "anyOf" in result:
+		result["anyOf"] = [_parameters(child) for child in result["anyOf"]]
+	for key in ("items", "additionalProperties"):
+		if isinstance(result.get(key), dict):
+			result[key] = _parameters(result[key])
+	return result
+
+
+def _enum_type(values: list[Any]) -> str | None:
+	kinds = {
+		"null" if value is None else "boolean" if type(value) is bool else
+		"integer" if type(value) is int else "number" if type(value) is float else
+		"string" if isinstance(value, str) else None
+		for value in values
+	}
+	if kinds <= {"integer", "number"}:
+		return "number" if "number" in kinds else "integer"
+	return next(iter(kinds)) if len(kinds) == 1 else None
+
+
+def _check_strict(schema: dict[str, Any], path: str = "$parameters") -> None:
+	"""Accept a conservative subset without rewriting Python omission semantics."""
+	def unsupported(reason: str) -> None:
+		raise CapabilityExposureError(f"{path}: {reason}; use strict=False or a compatible callable/schema.")
+
+	if "anyOf" in schema:
+		if any(key in schema for key in ("type", "enum", "properties", "items")):
+			unsupported("strict unions must use separate anyOf branches")
+		for index, branch in enumerate(schema["anyOf"]):
+			_check_strict(branch, f"{path}.anyOf[{index}]")
+		return
+	if "type" not in schema and "enum" in schema:
+		kind = _enum_type(schema["enum"])
+		if kind is not None:
+			schema["type"] = kind
+	types = schema.get("type")
+	if types is None:
+		unsupported("strict schemas require typed values")
+	if isinstance(types, list):
+		if len(types) != 2 or "null" not in types or len(set(types)) != 2:
+			unsupported("strict type lists must contain one type and null")
+	else:
+		types = [types]
+	if "object" in types:
+		if schema.get("additionalProperties") is not False:
+			unsupported("strict objects must reject additional properties")
+		properties = schema.get("properties", {})
+		if set(schema.get("required", ())) != set(properties):
+			unsupported("strict objects must require every property")
+		for name, child in properties.items():
+			_check_strict(child, f"{path}.{name}")
+	if "array" in types:
+		if "items" not in schema:
+			unsupported("strict arrays require an item schema")
+		_check_strict(schema["items"], f"{path}.items")
+
+
+class FunctionToolAdapter:
+	"""Export Responses tool dictionaries and execute calls in the caller's loop."""
+
+	def __init__(
+		self,
+		catalog: CapabilityCatalog,
+		*,
+		tool_names: Mapping[str, str] | None = None,
+		strict: bool = False,
+	) -> None:
+		if type(strict) is not bool:
+			raise TypeError("strict must be a boolean.")
+		self.catalog = catalog
+		aliases = dict(tool_names or {})
+		selected = {definition.name for definition in catalog.definitions()}
+		if set(aliases) - selected:
+			raise ValueError("Tool aliases must reference selected capabilities.")
+		self._names: dict[str, str] = {}
+		tools = []
+		for definition in catalog.definitions():
+			name = aliases.get(definition.name, definition.name.replace(".", "__"))
+			if not isinstance(name, str) or not _TOOL_NAME.fullmatch(name):
+				raise ValueError("Function tool names require 1-64 ASCII letters, digits, underscores, or hyphens; supply an alias.")
+			if name in self._names:
+				raise ValueError(f"Function tool name collision: {name!r}.")
+			parameters = _parameters(definition.to_dict()["input_schema"])
+			if strict:
+				_check_strict(parameters)
+			tool = {"type": "function", "name": name, "parameters": parameters, "strict": strict}
+			if definition.description is not None:
+				tool["description"] = definition.description
+			tools.append(tool)
+			self._names[name] = definition.name
+		self._tools = tuple(tools)
+
+	def tools(self) -> list[dict[str, Any]]:
+		"""Return fresh flat Responses definitions, ready for an application's request."""
+		return deepcopy(list(self._tools))
+
+	async def call(self, name: str, arguments: str | Mapping[str, Any]) -> str:
+		"""Validate selected arguments, await when needed, and return finite JSON text."""
+		try:
+			qualified_name = self._names[name]
+		except KeyError as error:
+			raise UnknownMoveError(f"Function tool {name!r} is not selected in this adapter.") from error
+		if isinstance(arguments, str):
+			try:
+				arguments = json.loads(arguments)
+			except (ValueError, RecursionError) as error:
+				raise CapabilityArgumentError("Function arguments must be valid JSON.") from error
+		result = self.catalog.invoke(qualified_name, arguments)
+		if inspect.isawaitable(result):
+			result = await result
+		value = self.catalog.serialize_result(qualified_name, result)
+		return json.dumps(value, ensure_ascii=False, allow_nan=False)
+
+	async def call_output(self, call_id: str, name: str, arguments: str | Mapping[str, Any]) -> dict[str, str]:
+		"""Build the application's function_call_output item without contacting an API."""
+		if not isinstance(call_id, str) or not call_id:
+			raise ValueError("call_id must be a nonempty string.")
+		return {"type": "function_call_output", "call_id": call_id, "output": await self.call(name, arguments)}