meshagent-openai 0.18.0__py3-none-any.whl

meshagent/openai/tools/schema.py

@@ -0,0 +1,253 @@
+def validate_response_format(response_format) -> str | None:
+    """
+    Validates a response format according to the OpenAI Structured Outputs specification.
+
+    See https://platform.openai.com/docs/guides/structured-outputs for details.
+
+    Note: This code is up to date as of January 21, 2024
+    """
+
+    # Check that response_format is a dictionary
+    if not isinstance(response_format, dict):
+        return "Error: Response format must be a dictionary."
+
+    # Check that response_format contains exactly "type" and "json_schema" keys
+    if set(response_format.keys()) != {"type", "json_schema"}:
+        return (
+            "Error: Response format must contain exactly 'type' and 'json_schema' keys."
+        )
+
+    # Check that response format has type=json_schema
+    if "type" not in response_format or response_format["type"] != "json_schema":
+        return "Error: Response format must have type 'json_schema'."
+
+    # Check that the "json_schema" is a dict
+    if "json_schema" not in response_format or not isinstance(
+        response_format["json_schema"], dict
+    ):
+        return "Error: 'json_schema' key must be a dictionary."
+
+    # Check that "json_schema" contains exactly "name" and "schema" keys, and optionally "description" and "strict" keys
+    required_keys = {"name", "schema"}
+    optional_keys = {"description", "strict"}
+    if set(response_format["json_schema"].keys()) != required_keys.union(optional_keys):
+        return "Error: 'json_schema' key must contain exactly 'name', 'schema', and optionally 'description' and 'strict' keys."
+
+    # Check that "json_schema" contains a "name" string
+    if "name" not in response_format["json_schema"] or not isinstance(
+        response_format["json_schema"]["name"], str
+    ):
+        return "Error: 'name' key must be a string."
+
+    # Check that "description" is a string if present
+    if "description" in response_format["json_schema"] and not isinstance(
+        response_format["json_schema"]["description"], str
+    ):
+        return "Error: 'description' key must be a string."
+
+    # Check that "json_schema" contains a "schema" dict
+    if "schema" not in response_format["json_schema"] or not isinstance(
+        response_format["json_schema"]["schema"], dict
+    ):
+        return "Error: 'schema' key must be a dictionary."
+
+    # Check that "strict" is a bool if present
+    if "strict" in response_format["json_schema"] and not isinstance(
+        response_format["json_schema"]["strict"], bool
+    ):
+        return "Error: 'strict' key must be a boolean."
+
+    return validate_schema(response_format["json_schema"]["schema"])
+
+
+def validate_schema(schema, path="root", depth=0, stats=None):
+    """
+    Validates a JSON schema according to the OpenAI Structured Outputs specification.
+
+    See https://platform.openai.com/docs/guides/structured-outputs for details.
+
+    Note: This code is up to date as of January 21, 2024
+    """
+    print(f"Validating schema at {path}...")
+
+    # Initialize stats
+    if stats is None:
+        stats = {
+            "total_properties": 0,
+            "total_enum_values": 0,
+            "total_enum_string_length": 0,
+            "total_string_length": 0,
+        }
+
+    # Check root object type
+    if path == "root" and schema.get("type") != "object":
+        return f"Error at {path}: Root schema must be of type 'object'."
+
+    # Check for anyOf at root
+    if path == "root" and "anyOf" in schema:
+        return f"Error at {path}: Root schema must not use 'anyOf'."
+
+    # Check for required fields
+    if schema.get("type") == "object" and "properties" in schema:
+        if "required" not in schema or set(schema["required"]) != set(
+            schema["properties"].keys()
+        ):
+            missing_keys = set(schema["properties"].keys()) - set(
+                schema.get("required", [])
+            )
+            return f"Error at {path}: All object properties must be required. Missing keys: {missing_keys}."
+        if (
+            "additionalProperties" not in schema
+            or schema["additionalProperties"] is not False
+        ):
+            return f"Error at {path}: 'additionalProperties' must be set to false."
+
+    # Check for supported type
+    valid_types = {
+        "string",
+        "number",
+        "boolean",
+        "integer",
+        "object",
+        "array",
+        "enum",
+        "anyOf",
+    }
+    if "type" in schema:
+        schema_type = schema["type"]
+        if isinstance(schema_type, list):
+            if (
+                (len(schema_type) != 2)
+                or ("null" not in schema_type)
+                or not any(t in valid_types for t in schema_type if t != "null")
+            ):
+                return f"Error at {path}: Invalid type list {schema_type}. Must contain exactly one valid type and None."
+            null_allowed = True
+        elif schema_type not in valid_types:
+            return f"Error at {path}: Invalid type '{schema_type}'. Must be one of {valid_types}."
+        else:
+            null_allowed = False
+
+    # Check that enum matches specified type
+    if "enum" in schema:
+        for enum in schema["enum"]:
+            if null_allowed and enum is None:
+                continue
+            if not null_allowed and enum is None:
+                return f"Error at {path}: Enum value cannot be null unless type is [..., null]."
+
+            schema_type = schema.get("type")
+            if isinstance(schema_type, list):
+                valid_type = next(t for t in schema_type if t != "null")
+            else:
+                valid_type = schema_type
+
+            if valid_type == "integer" and not isinstance(enum, int):
+                return f"Error at {path}: Enum value '{enum}' does not match type 'integer'."
+            if valid_type == "number" and not isinstance(enum, (int, float)):
+                return f"Error at {path}: Enum value '{enum}' does not match type 'number'."
+            if valid_type == "string" and not isinstance(enum, str):
+                return f"Error at {path}: Enum value '{enum}' does not match type 'string'."
+            if valid_type == "boolean" and not isinstance(enum, bool):
+                return f"Error at {path}: Enum value '{enum}' does not match type 'boolean'."
+            if valid_type == "object" and not isinstance(enum, dict):
+                return f"Error at {path}: Enum value '{enum}' does not match type 'object'."
+            if valid_type == "array" and not isinstance(enum, list):
+                return (
+                    f"Error at {path}: Enum value '{enum}' does not match type 'array'."
+                )
+
+    # Check for unsupported keywords based on type
+    unsupported_keywords_by_type = {
+        "string": ["minLength", "maxLength", "pattern", "format"],
+        "number": ["minimum", "maximum", "multipleOf"],
+        "integer": ["minimum", "maximum", "multipleOf"],
+        "object": [
+            "patternProperties",
+            "unevaluatedProperties",
+            "propertyNames",
+            "minProperties",
+            "maxProperties",
+        ],
+        "array": [
+            "unevaluatedItems",
+            "contains",
+            "minContains",
+            "maxContains",
+            "minItems",
+            "maxItems",
+            "uniqueItems",
+        ],
+    }
+
+    schema_type = schema.get("type")
+    if isinstance(schema_type, list):
+        schema_type = next(t for t in schema_type if t != "null")
+
+    if schema_type in unsupported_keywords_by_type:
+        for keyword in unsupported_keywords_by_type[schema_type]:
+            if keyword in schema:
+                return f"Error at {path}: Unsupported keyword '{keyword}' found for type '{schema_type}'."
+
+    # Check for nesting depth
+    if depth > 5:
+        return f"Error at {path}: Exceeded maximum nesting depth of 5."
+
+    # Check for total properties
+    if schema.get("type") == "object":
+        stats["total_properties"] += len(schema.get("properties", {}))
+        if stats["total_properties"] > 100:
+            return "Error: Exceeded maximum of 100 object properties."
+
+    # Check for total string length
+    for key in schema.get("properties", {}):
+        stats["total_string_length"] += len(key)
+    for enum in schema.get("enum", []):
+        stats["total_enum_values"] += 1
+        stats["total_enum_string_length"] += len(str(enum)) if enum is not None else 4
+    if stats["total_string_length"] > 15000:
+        return "Error: Exceeded maximum total string length of 15,000 characters."
+    if stats["total_enum_values"] > 500:
+        return "Error: Exceeded maximum of 500 enum values."
+    if stats["total_enum_string_length"] > 7500 and stats["total_enum_values"] > 250:
+        return "Error: Exceeded maximum total enum string length of 7,500 characters for more than 250 enum values."
+
+    # Recursively validate nested schemas
+    if "properties" in schema:
+        for prop, subschema in schema["properties"].items():
+            result = validate_schema(
+                subschema, path=f"{path}.{prop}", depth=depth + 1, stats=stats
+            )
+            if result:
+                return result
+
+    if "anyOf" in schema:
+        for index, subschema in enumerate(schema["anyOf"]):
+            result = validate_schema(
+                subschema, path=f"{path}.anyOf[{index}]", depth=depth + 1, stats=stats
+            )
+            if result:
+                return result
+
+    if "$defs" in schema:
+        for def_name, subschema in schema["$defs"].items():
+            result = validate_schema(
+                subschema, path=f"{path}.$defs.{def_name}", depth=depth + 1, stats=stats
+            )
+            if result:
+                return result
+
+    if "items" in schema:
+        result = validate_schema(
+            schema["items"], path=f"{path}.items", depth=depth + 1, stats=stats
+        )
+        if result:
+            return result
+
+    return None
+
+
+def validate_strict_schema(schema) -> str | None:
+    return validate_response_format(
+        {"type": "json_schema", "name": "schema", "strict": True, "json_schema": schema}
+    )

meshagent/openai/tools/stt.py

@@ -0,0 +1,118 @@
+from meshagent.tools import ToolContext, Tool, Toolkit, JsonResponse, TextResponse
+from openai import AsyncOpenAI
+from pydantic import BaseModel
+from meshagent.openai.proxy import get_client
+from typing import Optional
+import io
+import pathlib
+
+
+async def _transcribe(
+    *,
+    client: AsyncOpenAI,
+    data: bytes,
+    model: str,
+    filename: str,
+    response_format: str,
+    timestamp_granularities: list[str] = None,
+    prompt: Optional[str] = None,
+    language: Optional[str] = None,
+):
+    buf = io.BytesIO(data)
+    buf.name = filename
+    transcript: BaseModel = await client.audio.transcriptions.create(
+        model=model,
+        response_format=response_format,
+        file=buf,
+        prompt=prompt,
+        language=language,
+        timestamp_granularities=timestamp_granularities,
+        stream=False,
+    )
+
+    if isinstance(transcript, str):
+        return TextResponse(text=transcript)
+
+    return JsonResponse(json=transcript.model_dump(mode="json"))
+
+
+class OpenAIAudioFileSTT(Tool):
+    def __init__(self, *, client: Optional[AsyncOpenAI] = None):
+        super().__init__(
+            name="openai-file-stt",
+            input_schema={
+                "type": "object",
+                "additionalProperties": False,
+                "required": [
+                    "model",
+                    "path",
+                    "response_format",
+                    "timestamp_granularities",
+                    "prompt",
+                ],
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "the path to a file in the room storage",
+                    },
+                    "prompt": {
+                        "type": "string",
+                        "description": "a prompt. can improve the accuracy of the transcript",
+                    },
+                    "model": {
+                        "type": "string",
+                        "enum": [
+                            "whisper-1",
+                            "gpt-4o-mini-transcribe",
+                            "gpt-4o-transcribe",
+                        ],
+                    },
+                    "response_format": {
+                        "type": "string",
+                        "description": "text and json are supported for all models, srt, verbose_json, and vtt are only supported for whisper-1",
+                        "enum": ["text", "json", "srt", "verbose_json", "vtt"],
+                    },
+                    "timestamp_granularities": {
+                        "description": "timestamp_granularities are only valid with whisper-1",
+                        "type": "array",
+                        "items": {"type": "string", "enum": ["word", "segment"]},
+                    },
+                },
+            },
+            title="OpenAI audio file STT",
+            description="transcribes an audio file to text",
+        )
+        self.client = client
+
+    async def execute(
+        self,
+        context: ToolContext,
+        *,
+        model: str,
+        prompt: str,
+        path: str,
+        response_format: str,
+        timestamp_granularities: list,
+    ):
+        file_data = await context.room.storage.download(path=path)
+        client = self.client
+        if client is None:
+            client = get_client(room=context.room)
+
+        return await _transcribe(
+            client=client,
+            data=file_data.data,
+            model=model,
+            prompt=prompt,
+            filename=pathlib.Path(path).name,
+            response_format=response_format,
+        )
+
+
+class OpenAISTTToolkit(Toolkit):
+    def __init__(self):
+        super().__init__(
+            name="openai-stt",
+            description="tools for speech to text using openai",
+            tools=[OpenAIAudioFileSTT()],
+        )

meshagent/openai/tools/stt_test.py

@@ -0,0 +1,87 @@
+import os
+import asyncio
+import pytest
+
+from openai import AsyncOpenAI
+from meshagent.tools import JsonResponse, TextResponse
+
+from .tts import _transcribe
+
+
+################################################################################
+# Fixtures
+################################################################################
+@pytest.fixture(scope="session")
+def client() -> AsyncOpenAI:
+    """Real async OpenAI client – no mocks, hits the network."""
+    return AsyncOpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+
+
+@pytest.fixture(scope="session")
+def audio_bytes() -> bytes:
+    """Loads the test clip only once per session."""
+    with open("harvard.wav", "rb") as fp:
+        return fp.read()
+
+
+################################################################################
+# Tests – one for “text”, one for “json”.  Add more if you need other formats.
+################################################################################
+@pytest.mark.asyncio
+async def test_transcribe_text(client, audio_bytes):
+    """_transcribe should return non-empty TextResponse for plain-text format."""
+    result = await asyncio.wait_for(
+        _transcribe(
+            client=client,
+            data=audio_bytes,
+            filename="harvard.wav",
+            model="gpt-4o-mini-transcribe",
+            prompt="",
+            response_format="text",
+        ),
+        timeout=90,
+    )
+
+    # Basic sanity checks
+    assert isinstance(result, TextResponse)
+    assert result.text.strip() != ""
+
+
+@pytest.mark.asyncio
+async def test_transcribe_json(client, audio_bytes):
+    """_transcribe should return a well-formed JsonResponse for JSON format."""
+    result = await asyncio.wait_for(
+        _transcribe(
+            client=client,
+            data=audio_bytes,
+            filename="harvard.wav",
+            model="gpt-4o-mini-transcribe",
+            prompt="",
+            response_format="json",
+        ),
+        timeout=90,
+    )
+
+    # Basic sanity checks
+    assert isinstance(result, JsonResponse)
+    assert isinstance(result.json["text"], str)
+
+
+@pytest.mark.asyncio
+async def test_transcribe_verbose_json(client, audio_bytes):
+    """_transcribe should return a well-formed JsonResponse for JSON format."""
+    result = await asyncio.wait_for(
+        _transcribe(
+            client=client,
+            data=audio_bytes,
+            filename="harvard.wav",
+            model="whisper-1",
+            prompt="",
+            response_format="verbose_json",
+        ),
+        timeout=90,
+    )
+
+    # Basic sanity checks
+    assert isinstance(result, JsonResponse)
+    assert isinstance(result.json["segments"], list)

meshagent/openai/version.py

@@ -0,0 +1 @@
+__version__ = "0.18.0"

meshagent_openai-0.18.0.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: meshagent-openai
+Version: 0.18.0
+Summary: OpenAI Building Blocks for Meshagent
+License-Expression: Apache-2.0
+Project-URL: Documentation, https://docs.meshagent.com
+Project-URL: Website, https://www.meshagent.com
+Project-URL: Source, https://www.meshagent.com
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyjwt~=2.10
+Requires-Dist: pytest~=8.4
+Requires-Dist: pytest-asyncio~=0.26
+Requires-Dist: openai~=2.6.0
+Requires-Dist: meshagent-api~=0.18.0
+Requires-Dist: meshagent-agents~=0.18.0
+Requires-Dist: meshagent-tools~=0.18.0
+Dynamic: license-file
+
+# [Meshagent](https://www.meshagent.com)
+
+## MeshAgent OpenAI
+The ``meshagent.openai`` package provides adapters to integrate OpenAI models with MeshAgent tools and agents. 
+
+### Completions Adapter and Responses Adapter
+MeshAgent supports both the OpenAI Chat Completions API and Responses API. It is recommended to use the Responses adapter given the newer OpenAI models and functionality use the Responses adapter.
+
+- ``OpenAICompletionsAdapter``: wraps the OpenAI Chat Completions API. It turns Toolkit objects into OpenAI-style tool definitions and processes tool calls appropriately.
+- ``OpenAIResponsesAdapter``: wraps the newer OpenAI Responses API. It collects tools, handles streaming events, and provides callbacks for advanced features like image generation or web search. 
+
+```Python Python
+from meshagent.openai import OpenAIResponsesAdapter
+from openai import AsyncOpenAI
+
+# Use an OpenAI client inside a MeshAgent LLMAdapter
+adapter = OpenAIResponsesAdapter(client=AsyncOpenAI(api_key="sk-..."))
+```
+
+### Tool Response Adapter
+The ``OpenAICompletionsToolResponseAdapter`` and ``OpenAIResponsesToolResponseAdapter``convert a tool's structured response into plain text or JSOn that can beinserted into an OpenAI chat context. 
+
+---
+### Learn more about MeshAgent on our website or check out the docs for additional examples!
+
+**Website**: [www.meshagent.com](https://www.meshagent.com/)
+
+**Documentation**: [docs.meshagent.com](https://docs.meshagent.com/)
+
+---

meshagent_openai-0.18.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+meshagent/openai/__init__.py,sha256=g4RSQWfL2El6HQ8i2Aw8wwBEJVC861Z61S0GqkFnBys,369
+meshagent/openai/version.py,sha256=0EHw4xygmgkGSyfwNfEoMlQyN0uHxjHtlSFF79s6120,23
+meshagent/openai/proxy/__init__.py,sha256=PkOCHmUptsbuX5sNlWJk5bMxnSzyg5AZhPtooEPV7XE,54
+meshagent/openai/proxy/proxy.py,sha256=iTgk6ONcYUiOGjEownWW3JeeJ-zCyX28faUZ3oFu6fM,2635
+meshagent/openai/tools/__init__.py,sha256=cLXoB9CBqKbCGhZMAJTIX6-yv_UO8AxpaH8vQQ1e8VY,467
+meshagent/openai/tools/apply_patch.py,sha256=iSkZpyq4jaMYHs1lLZ8pkocqmDeuhPKxgzHHCsd7euU,10195
+meshagent/openai/tools/completions_adapter.py,sha256=dBRXuWxc2LiWaTpA8agMhwxhRvbxbMnggvv_9QtK-HA,15946
+meshagent/openai/tools/responses_adapter.py,sha256=x4XJLXLDeVHWt9QkPqHK0eSPd21L8C2KAuJhUQpt5RY,88900
+meshagent/openai/tools/schema.py,sha256=YaP0iEL9Lf2qS4xZy8VILjr1IS52XS9LEcn_cskNreo,10079
+meshagent/openai/tools/stt.py,sha256=H3YusIjigJwxfEdkrK5qZ6DHbjQagaLNj7q_-fTfwy4,3845
+meshagent/openai/tools/stt_test.py,sha256=XE4qZBlNeEWdJW5NjBGyaJmuCKN0ZLlJ2b_GBp7MzVk,2651
+meshagent_openai-0.18.0.dist-info/licenses/LICENSE,sha256=eTt0SPW-sVNdkZe9PS_S8WfCIyLjRXRl7sUBWdlteFg,10254
+meshagent_openai-0.18.0.dist-info/METADATA,sha256=odoFXoF4tXmkqchyIO58E0gX7MWVjNKO9zPnRc2cBdw,2108
+meshagent_openai-0.18.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+meshagent_openai-0.18.0.dist-info/top_level.txt,sha256=GlcXnHtRP6m7zlG3Df04M35OsHtNXy_DY09oFwWrH74,10
+meshagent_openai-0.18.0.dist-info/RECORD,,

meshagent_openai-0.18.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+