agents-function-tools 0.4.0__tar.gz → 0.5.0__tar.gz

{agents_function_tools-0.4.0/src/agents_function_tools.egg-info → agents_function_tools-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agents-function-tools
-Version: 0.4.0
+Version: 0.5.0
 Summary: Portable, policy-friendly system function tools for AI applications.
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -10,7 +10,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: openai-agents<1,>=0.1
+Requires-Dist: openai-agents<1,>=0.22
 Requires-Dist: pydantic<3,>=2
 Dynamic: license-file
 
@@ -37,6 +37,30 @@ python -m pip install agents-function-tools
 
 Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, and `error` fields. Paths are always relative to a configured workspace root.
 
+## Machine-readable contracts
+
+Every returned bundle exposes `contracts`, a mapping from FunctionTool name to a `ToolContract`.
+The contract snapshots the SDK-derived input schema and declares the stable response schema,
+failure schema, capability permission, response effect, approval requirement, and retry safety.
+This lets an application build its own CLI, web approval screen, audit log, or policy check without
+binding this package to a particular Agent workflow.
+
+```python
+from function_tools import create_tools
+
+tools = create_tools("./workspace")
+contract = tools.contracts["workspace_write_text"]
+
+assert contract.permission == "workspace.write"
+assert contract.needs_approval is True
+assert contract.retry_safe is False
+print(contract.to_dict())
+```
+
+`needs_approval=True` is enforced by the OpenAI Agents SDK. The host application receives the
+interruption, presents its own approval UI, then resumes the saved run state only after an explicit
+approval. This package deliberately does not impose a CLI or web interaction model.
+
 ## Safety boundary
 
 - Path traversal and access outside the workspace root are rejected.
@@ -73,9 +97,15 @@ agent = Agent(
 
 Use the narrowest domain selector: `tools.files`, `tools.network`, `tools.host`, or `tools.process`. The v0.3-style `tools.read`, `tools.write`, and `tools.execute` selectors remain available for compatibility, but combine more capabilities. Every `*.write` and `*.execute` tool requires approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
 
+## Complete Example
+
+[OpenAI Agents workspace assistant](examples/openai_agents_workspace_assistant/README.md) is a runnable example with `tools.files.read`, `tools.files.write`, and per-call SDK approval. It is intentionally limited to one workspace; it does not attach network, host, process, command, MCP, or database tools.
+
 ## Design specs
 
 - [v0.4 tool expansion spec](docs/v0.4-tool-expansion-spec.md)
+- [release and compatibility policy](docs/release-policy.md)
+- [changelog](CHANGELOG.md)
 
 For configured commands, HTTPS hosts, or readable environment variables, use `ToolConfig`:
 
@@ -129,6 +159,15 @@ uv run --python 3.10 pytest
 
 Tests do not call the OpenAI API and do not require `OPENAI_API_KEY`.
 
+GitHub Actions runs formatting and linting, a Windows/Linux plus Python 3.10-3.12 test matrix, and the same package acceptance gate used before publishing. The suite includes public FunctionTool contracts and offline OpenAI Agents SDK integration tests using `ScriptedModel`, including approval interruption and resume behavior.
+
+## OpenAI Agents SDK compatibility
+
+The package requires `openai-agents>=0.22,<1`; `0.22.0` is the current validated baseline. The
+weekly `OpenAI Agents SDK latest` workflow resolves the newest compatible SDK release from PyPI and
+runs the deterministic suite against it. It detects upstream compatibility changes without silently
+publishing or accepting a new SDK version.
+
 ## Release acceptance
 
 Before every PyPI release, run:
@@ -137,7 +176,7 @@ Before every PyPI release, run:
 uv run python scripts/release_check.py
 ```
 
-The gate checks the lockfile, formatting, linting, tests, wheel and source-distribution contents, package metadata, a clean `python -m pip install --no-deps <wheel>`, and a separate clean runtime installation with dependencies.
+The gate checks the lockfile, formatting, linting, example compilation, tests, wheel and source-distribution contents, package metadata, a clean `python -m pip install --no-deps <wheel>`, and a separate clean runtime installation with dependencies.
 
 Use the following command to run that gate and publish only when it passes:
 

agents_function_tools-0.4.0/PKG-INFO → agents_function_tools-0.5.0/README.md

@@ -1,146 +1,169 @@
-Metadata-Version: 2.4
-Name: agents-function-tools
-Version: 0.4.0
-Summary: Portable, policy-friendly system function tools for AI applications.
-License-Expression: Apache-2.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: openai-agents<1,>=0.1
-Requires-Dist: pydantic<3,>=2
-Dynamic: license-file
-
-# Agents Function Tools
-
-`agents-function-tools` is a portable Python library of policy-friendly system function tools. It contains no business model, Agent routing, domain workflow, database adapter, or code-review logic. Its Python import name is `function_tools`.
-
-## Install
-
-```bash
-python -m pip install agents-function-tools
-```
-
-## Included tools
-
-| Category | Tools | Recommended selector |
-|---|---|---|
-| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `files.read` |
-| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `files.write` |
-| ZIP | List archive entries; create and extract bounded ZIP archives | `files.read` / `files.write` |
-| Network | Fetch bounded HTTPS text; optionally build search URLs, resolve configured hosts, and probe configured TCP ports | `network.read` |
-| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `host.inspect` |
-| Processes and commands | Describe configured aliases; optionally inspect allowlisted process names; run one allowlisted executable with `shell=False` | `process.inspect` / `process.execute` |
-
-Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, and `error` fields. Paths are always relative to a configured workspace root.
-
-## Safety boundary
-
-- Path traversal and access outside the workspace root are rejected.
-- The workspace root cannot be deleted.
-- Recursive deletion must be explicit.
-- File reads, writes, hashes, and archive expansion have byte limits.
-- Every workspace mutation and local command requires the SDK approval gate in addition to the orchestration approval policy. File copy accepts regular, non-symlink source files only.
-- ZIP creation rejects symlinks; ZIP extraction rejects path traversal and symlink entries before writing files.
-- HTTPS fetching requires an exact host allowlist, rejects redirects, URL credentials, and non-default ports, accepts only text-like content types, and blocks resolved private or loopback addresses. No host is enabled by default. Deployment still needs an egress proxy or firewall: application-layer DNS checks do not replace network isolation.
-- Host diagnostics intentionally exclude user identities, network configuration, installed software, and environment variables except for names explicitly configured by the host. Process diagnostics are separate, disabled by default, and return only configured process names, PIDs, states, and start times.
-- Command execution accepts an argument array, never a shell string. Programs must be mapped by the host application, execution has a timeout, and output is truncated.
-- The local command runner is not an OS security sandbox. Production deployment must run the service or runner inside the company-approved container/sandbox with no production secrets and restricted network access.
-- Approval remains the orchestration layer's responsibility. Only attach `tools.write` or `tools.execute` after the matching approval policy has been validated.
-
-This is a controlled operating-system capability adapter, not a general shell, process-management, credential, service-control, or unrestricted-network interface. Give each business Agent only the smallest subset of these tools it needs.
-
-## Example
-
-```python
-from pathlib import Path
-
-from agents import Agent
-
-from function_tools import create_tools
-
-tools = create_tools(Path("./workspace"))
-
-agent = Agent(
-    name="Workspace assistant",
-    instructions="Use workspace tools when needed.",
-    tools=list(tools.files.read),
-)
-```
-
-Use the narrowest domain selector: `tools.files`, `tools.network`, `tools.host`, or `tools.process`. The v0.3-style `tools.read`, `tools.write`, and `tools.execute` selectors remain available for compatibility, but combine more capabilities. Every `*.write` and `*.execute` tool requires approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
-
-## Design specs
-
-- [v0.4 tool expansion spec](docs/v0.4-tool-expansion-spec.md)
-
-For configured commands, HTTPS hosts, or readable environment variables, use `ToolConfig`:
-
-```python
-import sys
-from pathlib import Path
-
-from function_tools import ToolConfig, create_tools
-
-tools = create_tools(
-    ToolConfig(
-        workspace_root=Path("./workspace"),
-        command_programs={"python": sys.executable},
-        http_allowed_hosts=frozenset({"api.example.internal"}),
-        environment_variables=frozenset({"APP_ENV"}),
-    )
-)
-```
-
-Network diagnostics and process inspection are disabled until explicitly configured:
-
-```python
-from function_tools import ToolConfig, create_tools
-
-tools = create_tools(
-    ToolConfig(
-        workspace_root="./workspace",
-        http_allowed_hosts=frozenset({"api.example.internal"}),
-        search_engines={"bing": "https://www.bing.com/search"},
-        network_allowed_ports=frozenset({443}),
-        process_name_allowlist=frozenset({"python.exe"}),
-    )
-)
-
-network_tools = tools.network.read
-process_tools = tools.process.inspect
-```
-
-## License
-
-Apache-2.0. See [LICENSE](LICENSE).
-
-## Development
-
-Use Python 3.10 or newer:
-
-```powershell
-uv sync --python 3.10
-uv run --python 3.10 pytest
-```
-
-Tests do not call the OpenAI API and do not require `OPENAI_API_KEY`.
-
-## Release acceptance
-
-Before every PyPI release, run:
-
-```powershell
-uv run python scripts/release_check.py
-```
-
-The gate checks the lockfile, formatting, linting, tests, wheel and source-distribution contents, package metadata, a clean `python -m pip install --no-deps <wheel>`, and a separate clean runtime installation with dependencies.
-
-Use the following command to run that gate and publish only when it passes:
-
-```powershell
-uv run python scripts/publish.py
-```
+# Agents Function Tools
+
+`agents-function-tools` is a portable Python library of policy-friendly system function tools. It contains no business model, Agent routing, domain workflow, database adapter, or code-review logic. Its Python import name is `function_tools`.
+
+## Install
+
+```bash
+python -m pip install agents-function-tools
+```
+
+## Included tools
+
+| Category | Tools | Recommended selector |
+|---|---|---|
+| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `files.read` |
+| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `files.write` |
+| ZIP | List archive entries; create and extract bounded ZIP archives | `files.read` / `files.write` |
+| Network | Fetch bounded HTTPS text; optionally build search URLs, resolve configured hosts, and probe configured TCP ports | `network.read` |
+| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `host.inspect` |
+| Processes and commands | Describe configured aliases; optionally inspect allowlisted process names; run one allowlisted executable with `shell=False` | `process.inspect` / `process.execute` |
+
+Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, and `error` fields. Paths are always relative to a configured workspace root.
+
+## Machine-readable contracts
+
+Every returned bundle exposes `contracts`, a mapping from FunctionTool name to a `ToolContract`.
+The contract snapshots the SDK-derived input schema and declares the stable response schema,
+failure schema, capability permission, response effect, approval requirement, and retry safety.
+This lets an application build its own CLI, web approval screen, audit log, or policy check without
+binding this package to a particular Agent workflow.
+
+```python
+from function_tools import create_tools
+
+tools = create_tools("./workspace")
+contract = tools.contracts["workspace_write_text"]
+
+assert contract.permission == "workspace.write"
+assert contract.needs_approval is True
+assert contract.retry_safe is False
+print(contract.to_dict())
+```
+
+`needs_approval=True` is enforced by the OpenAI Agents SDK. The host application receives the
+interruption, presents its own approval UI, then resumes the saved run state only after an explicit
+approval. This package deliberately does not impose a CLI or web interaction model.
+
+## Safety boundary
+
+- Path traversal and access outside the workspace root are rejected.
+- The workspace root cannot be deleted.
+- Recursive deletion must be explicit.
+- File reads, writes, hashes, and archive expansion have byte limits.
+- Every workspace mutation and local command requires the SDK approval gate in addition to the orchestration approval policy. File copy accepts regular, non-symlink source files only.
+- ZIP creation rejects symlinks; ZIP extraction rejects path traversal and symlink entries before writing files.
+- HTTPS fetching requires an exact host allowlist, rejects redirects, URL credentials, and non-default ports, accepts only text-like content types, and blocks resolved private or loopback addresses. No host is enabled by default. Deployment still needs an egress proxy or firewall: application-layer DNS checks do not replace network isolation.
+- Host diagnostics intentionally exclude user identities, network configuration, installed software, and environment variables except for names explicitly configured by the host. Process diagnostics are separate, disabled by default, and return only configured process names, PIDs, states, and start times.
+- Command execution accepts an argument array, never a shell string. Programs must be mapped by the host application, execution has a timeout, and output is truncated.
+- The local command runner is not an OS security sandbox. Production deployment must run the service or runner inside the company-approved container/sandbox with no production secrets and restricted network access.
+- Approval remains the orchestration layer's responsibility. Only attach `tools.write` or `tools.execute` after the matching approval policy has been validated.
+
+This is a controlled operating-system capability adapter, not a general shell, process-management, credential, service-control, or unrestricted-network interface. Give each business Agent only the smallest subset of these tools it needs.
+
+## Example
+
+```python
+from pathlib import Path
+
+from agents import Agent
+
+from function_tools import create_tools
+
+tools = create_tools(Path("./workspace"))
+
+agent = Agent(
+    name="Workspace assistant",
+    instructions="Use workspace tools when needed.",
+    tools=list(tools.files.read),
+)
+```
+
+Use the narrowest domain selector: `tools.files`, `tools.network`, `tools.host`, or `tools.process`. The v0.3-style `tools.read`, `tools.write`, and `tools.execute` selectors remain available for compatibility, but combine more capabilities. Every `*.write` and `*.execute` tool requires approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
+
+## Complete Example
+
+[OpenAI Agents workspace assistant](examples/openai_agents_workspace_assistant/README.md) is a runnable example with `tools.files.read`, `tools.files.write`, and per-call SDK approval. It is intentionally limited to one workspace; it does not attach network, host, process, command, MCP, or database tools.
+
+## Design specs
+
+- [v0.4 tool expansion spec](docs/v0.4-tool-expansion-spec.md)
+- [release and compatibility policy](docs/release-policy.md)
+- [changelog](CHANGELOG.md)
+
+For configured commands, HTTPS hosts, or readable environment variables, use `ToolConfig`:
+
+```python
+import sys
+from pathlib import Path
+
+from function_tools import ToolConfig, create_tools
+
+tools = create_tools(
+    ToolConfig(
+        workspace_root=Path("./workspace"),
+        command_programs={"python": sys.executable},
+        http_allowed_hosts=frozenset({"api.example.internal"}),
+        environment_variables=frozenset({"APP_ENV"}),
+    )
+)
+```
+
+Network diagnostics and process inspection are disabled until explicitly configured:
+
+```python
+from function_tools import ToolConfig, create_tools
+
+tools = create_tools(
+    ToolConfig(
+        workspace_root="./workspace",
+        http_allowed_hosts=frozenset({"api.example.internal"}),
+        search_engines={"bing": "https://www.bing.com/search"},
+        network_allowed_ports=frozenset({443}),
+        process_name_allowlist=frozenset({"python.exe"}),
+    )
+)
+
+network_tools = tools.network.read
+process_tools = tools.process.inspect
+```
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).
+
+## Development
+
+Use Python 3.10 or newer:
+
+```powershell
+uv sync --python 3.10
+uv run --python 3.10 pytest
+```
+
+Tests do not call the OpenAI API and do not require `OPENAI_API_KEY`.
+
+GitHub Actions runs formatting and linting, a Windows/Linux plus Python 3.10-3.12 test matrix, and the same package acceptance gate used before publishing. The suite includes public FunctionTool contracts and offline OpenAI Agents SDK integration tests using `ScriptedModel`, including approval interruption and resume behavior.
+
+## OpenAI Agents SDK compatibility
+
+The package requires `openai-agents>=0.22,<1`; `0.22.0` is the current validated baseline. The
+weekly `OpenAI Agents SDK latest` workflow resolves the newest compatible SDK release from PyPI and
+runs the deterministic suite against it. It detects upstream compatibility changes without silently
+publishing or accepting a new SDK version.
+
+## Release acceptance
+
+Before every PyPI release, run:
+
+```powershell
+uv run python scripts/release_check.py
+```
+
+The gate checks the lockfile, formatting, linting, example compilation, tests, wheel and source-distribution contents, package metadata, a clean `python -m pip install --no-deps <wheel>`, and a separate clean runtime installation with dependencies.
+
+Use the following command to run that gate and publish only when it passes:
+
+```powershell
+uv run python scripts/publish.py
+```

{agents_function_tools-0.4.0 → agents_function_tools-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agents-function-tools"
-version = "0.4.0"
+version = "0.5.0"
 description = "Portable, policy-friendly system function tools for AI applications."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,7 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "openai-agents>=0.1,<1",
+    "openai-agents>=0.22,<1",
     "pydantic>=2,<3",
 ]