optimizely-opal.opal-tools-sdk 0.1.18.dev0__tar.gz → 0.1.20.dev0__tar.gz

{optimizely_opal_opal_tools_sdk-0.1.18.dev0 → optimizely_opal_opal_tools_sdk-0.1.20.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.18.dev0
+Version: 0.1.20.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely

{optimizely_opal_opal_tools_sdk-0.1.18.dev0 → optimizely_opal_opal_tools_sdk-0.1.20.dev0}/opal_tools_sdk/decorators.py

@@ -1,7 +1,7 @@
 import inspect
 import re
 import logging
-from typing import Callable, Any, List, Dict, Type, get_origin, get_type_hints, Optional, Union
+from typing import Callable, Any, List, Dict, Type, get_args, get_origin, get_type_hints, Optional, Union
 from fastapi import APIRouter, Depends, Header, HTTPException
 from pydantic import BaseModel
 
@@ -10,6 +10,81 @@ from .logging import get_logger
 
 logger = get_logger(__name__)
 
+
+def _resolve_json_schema(schema: dict, defs: dict, _seen: Optional[set] = None) -> dict:
+    """Resolve $ref references and simplify Pydantic v2 JSON schema output.
+
+    - Resolves ``$ref`` pointers by looking up ``$defs``
+    - Simplifies ``anyOf: [{type: X}, {type: "null"}]`` to ``{type: X}`` (Optional encoding)
+    - Recursively resolves nested ``properties`` and ``items``
+    - Strips Pydantic metadata (``title``, ``$defs`` at root)
+    - Guards against circular ``$ref`` via a ``_seen`` set
+    """
+    if _seen is None:
+        _seen = set()
+
+    # Resolve $ref
+    if "$ref" in schema:
+        ref_path = schema["$ref"]  # e.g. "#/$defs/OutputFormat"
+        ref_name = ref_path.rsplit("/", 1)[-1]
+        if ref_name in _seen:
+            return {"type": "object"}  # break circular ref
+        if ref_name in defs:
+            resolved = _resolve_json_schema(defs[ref_name], defs, _seen | {ref_name})
+            # Preserve sibling description from the outer schema
+            if "description" in schema and "description" not in resolved:
+                resolved["description"] = schema["description"]
+            return resolved
+        return {"type": "string"}
+
+    # Simplify anyOf (Pydantic Optional encoding)
+    if "anyOf" in schema:
+        non_null = [
+            s for s in schema["anyOf"]
+            if (s.get("type") != "null" and "$ref" not in s) or "$ref" in s
+        ]
+        if len(non_null) == 1:
+            resolved = _resolve_json_schema(non_null[0], defs, _seen)
+            # Preserve description from the outer schema
+            if "description" in schema and "description" not in resolved:
+                resolved["description"] = schema["description"]
+            return resolved
+        # If multiple non-null types, fall back to string
+        result: dict = {"type": "string"}
+        if "description" in schema:
+            result["description"] = schema["description"]
+        return result
+
+    result = {}
+
+    # Copy type
+    if "type" in schema:
+        result["type"] = schema["type"]
+
+    # Copy description
+    if "description" in schema:
+        result["description"] = schema["description"]
+
+    # Copy enum
+    if "enum" in schema:
+        result["enum"] = schema["enum"]
+
+    # Recursively resolve properties
+    if "properties" in schema:
+        result["properties"] = {}
+        for prop_name, prop_schema in schema["properties"].items():
+            result["properties"][prop_name] = _resolve_json_schema(prop_schema, defs, _seen)
+
+    # Copy required
+    if "required" in schema:
+        result["required"] = schema["required"]
+
+    # Recursively resolve items
+    if "items" in schema:
+        result["items"] = _resolve_json_schema(schema["items"], defs, _seen)
+
+    return result
+
 def tool(
     name: str,
     description: str,
@@ -87,6 +162,8 @@ def tool(
 
                 # Map Python type to Parameter type
                 param_type = ParameterType.string
+                full_schema = None
+
                 if field_type is int:
                     param_type = ParameterType.integer
                 elif field_type is float:
@@ -95,8 +172,33 @@ def tool(
                     param_type = ParameterType.boolean
                 elif field_type is list or get_origin(field_type) is list:
                     param_type = ParameterType.list
+                    # Extract item type from List[T] and build complete schema
+                    type_args_inner = get_args(field_type)
+                    items_schema = None
+                    if type_args_inner:
+                        item_type = type_args_inner[0]
+                        if hasattr(item_type, 'model_json_schema'):
+                            raw = item_type.model_json_schema()
+                            raw_defs = raw.pop('$defs', {})
+                            items_schema = _resolve_json_schema(raw, raw_defs)
+                        elif item_type is str:
+                            items_schema = {"type": "string"}
+                        elif item_type is int:
+                            items_schema = {"type": "integer"}
+                        elif item_type is float:
+                            items_schema = {"type": "number"}
+                        elif item_type is bool:
+                            items_schema = {"type": "boolean"}
+                    if items_schema is not None:
+                        full_schema = {"type": "array", "items": items_schema}
                 elif field_type is dict or get_origin(field_type) is dict:
                     param_type = ParameterType.dictionary
+                elif hasattr(field_type, 'model_json_schema'):
+                    param_type = ParameterType.dictionary
+                    raw = field_type.model_json_schema()
+                    raw_defs = raw.pop('$defs', {})
+                    resolved = _resolve_json_schema(raw, raw_defs)
+                    full_schema = resolved
 
                 # Determine if required
                 field_info_extra = getattr(field_info, "json_schema_extra") or {}
@@ -125,12 +227,18 @@ def tool(
                 elif hasattr(field, 'description'):
                     description_text = field.description
 
+                # Build the complete schema with description included
+                if full_schema is not None:
+                    if "description" not in full_schema:
+                        full_schema["description"] = description_text
+
                 parameters.append(Parameter(
                     name=field_name,
                     param_type=param_type,
                     description=description_text,
                     required=required,
-                    in_context=in_context
+                    in_context=in_context,
+                    schema=full_schema,
                 ))
 
                 logger.info(f"Registered parameter: {field_name} of type {param_type.value}, required: {required}")

{optimizely_opal_opal_tools_sdk-0.1.18.dev0 → optimizely_opal_opal_tools_sdk-0.1.20.dev0}/opal_tools_sdk/models.py

@@ -1,6 +1,6 @@
 from enum import Enum
 from typing import List, Dict, Any, Optional, Literal, TypedDict
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from pydantic import BaseModel, Field
 
@@ -25,16 +25,20 @@ class Parameter:
     description: str
     required: bool
     in_context: bool = False
+    schema: Optional[Dict[str, Any]] = field(default=None)
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for the discovery endpoint."""
-        return {
+        result = {
             "name": self.name,
             "type": self.param_type.value,
             "description": self.description,
             "required": self.required,
             "in_context": self.in_context,
         }
+        if self.schema is not None:
+            result["schema"] = self.schema
+        return result
 
 
 @dataclass

{optimizely_opal_opal_tools_sdk-0.1.18.dev0 → optimizely_opal_opal_tools_sdk-0.1.20.dev0}/opal_tools_sdk/proteus.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  proteus-document-spec.json
-#   timestamp: 2026-03-12T17:59:00+00:00
+#   timestamp: 2026-03-17T21:59:22+00:00
 
 from __future__ import annotations
 
@@ -1971,6 +1971,14 @@ class ProteusImage(BaseModel):
     src: ProteusValue | str | None = Field(default=None, description='The image source URL')
 
 
+class ProteusQuestion(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    field_type: Literal['Question'] = Field(default='Question', alias='$type')
+    questions: ProteusValue = Field(..., description='Array of questions data')
+
+
 class ProteusRange(BaseModel):
     model_config = ConfigDict(
         extra='forbid',
@@ -2908,36 +2916,6 @@ class ProteusCardLink(BaseModel):
     z: SprinklePropZ | None = None
 
 
-class ProteusChoice(BaseModel):
-    model_config = ConfigDict(
-        extra='forbid',
-    )
-    field_type: Literal['Choice'] = Field(default='Choice', alias='$type')
-    addonBefore: ProteusNode | None = Field(
-        default=None, description='Content to display before the choice text (e.g., numbered badge)'
-    )
-    children: ProteusNode | None = Field(default=None, description='Title/label of the choice')
-    description: ProteusNode | None = Field(
-        default=None, description='Secondary description text shown below the title'
-    )
-    onClick: ProteusEventHandler | None = Field(
-        default=None, description='Action triggered when choice is selected'
-    )
-    required: bool | None = Field(
-        default=None, description='Whether selecting this choice is required to proceed'
-    )
-    value: str | None = Field(default=None, description='Value associated with this choice')
-
-
-class ProteusChoiceGroup(BaseModel):
-    model_config = ConfigDict(
-        extra='forbid',
-    )
-    field_type: Literal['ChoiceGroup'] = Field(default='ChoiceGroup', alias='$type')
-    children: ProteusNode | None = Field(default=None, description='Choice elements to render')
-    name: str | None = Field(default=None, description='Data field name for the selected value')
-
-
 class ProteusField(BaseModel):
     model_config = ConfigDict(
         extra='forbid',
@@ -3563,8 +3541,6 @@ class ProteusElement(
         | ProteusCardHeader
         | ProteusCardLink
         | ProteusChart
-        | ProteusChoice
-        | ProteusChoiceGroup
         | ProteusDataTable
         | ProteusField
         | ProteusGroup
@@ -3574,6 +3550,7 @@ class ProteusElement(
         | ProteusInput
         | ProteusLink
         | ProteusMap
+        | ProteusQuestion
         | ProteusRange
         | ProteusSelect
         | ProteusSelectContent
@@ -3595,8 +3572,6 @@ class ProteusElement(
         | ProteusCardHeader
         | ProteusCardLink
         | ProteusChart
-        | ProteusChoice
-        | ProteusChoiceGroup
         | ProteusDataTable
         | ProteusField
         | ProteusGroup
@@ -3606,6 +3581,7 @@ class ProteusElement(
         | ProteusInput
         | ProteusLink
         | ProteusMap
+        | ProteusQuestion
         | ProteusRange
         | ProteusSelect
         | ProteusSelectContent
@@ -3655,8 +3631,6 @@ ProteusCancelAction.model_rebuild()
 ProteusCard.model_rebuild()
 ProteusCardHeader.model_rebuild()
 ProteusCardLink.model_rebuild()
-ProteusChoice.model_rebuild()
-ProteusChoiceGroup.model_rebuild()
 ProteusField.model_rebuild()
 ProteusGroup.model_rebuild()
 ProteusHeading.model_rebuild()
@@ -3689,8 +3663,6 @@ class UI:
     CardHeader = ProteusCardHeader
     CardLink = ProteusCardLink
     Chart = ProteusChart
-    Choice = ProteusChoice
-    ChoiceGroup = ProteusChoiceGroup
     DataTable = ProteusDataTable
     Document = ProteusDocument
     Field = ProteusField
@@ -3701,6 +3673,7 @@ class UI:
     Input = ProteusInput
     Link = ProteusLink
     Map = ProteusMap
+    Question = ProteusQuestion
     Range = ProteusRange
     Select = ProteusSelect
     SelectContent = ProteusSelectContent

{optimizely_opal_opal_tools_sdk-0.1.18.dev0 → optimizely_opal_opal_tools_sdk-0.1.20.dev0}/optimizely_opal.opal_tools_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.18.dev0
+Version: 0.1.20.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely

{optimizely_opal_opal_tools_sdk-0.1.18.dev0 → optimizely_opal_opal_tools_sdk-0.1.20.dev0}/optimizely_opal.opal_tools_sdk.egg-info/SOURCES.txt

@@ -16,4 +16,5 @@ optimizely_opal.opal_tools_sdk.egg-info/dependency_links.txt
 optimizely_opal.opal_tools_sdk.egg-info/requires.txt
 optimizely_opal.opal_tools_sdk.egg-info/top_level.txt
 tests/test_integration.py
+tests/test_nested_schema.py
 tests/test_proteus.py

{optimizely_opal_opal_tools_sdk-0.1.18.dev0 → optimizely_opal_opal_tools_sdk-0.1.20.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "optimizely-opal.opal-tools-sdk"
-version = "0.1.18-dev"
+version = "0.1.20-dev"
 description = "SDK for creating Opal-compatible tools services"
 authors = [{ name = "Optimizely", email = "opal-team@optimizely.com" }]
 readme = "README.md"

{optimizely_opal_opal_tools_sdk-0.1.18.dev0 → optimizely_opal_opal_tools_sdk-0.1.20.dev0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="optimizely-opal.opal-tools-sdk",
-    version="0.1.18-dev",
+    version="0.1.19-dev",
     packages=find_packages(),
     install_requires=[
         "fastapi>=0.100.0",

optimizely_opal_opal_tools_sdk-0.1.20.dev0/tests/test_nested_schema.py

@@ -0,0 +1,235 @@
+"""Tests for nested schema extraction from Pydantic models in the @tool decorator."""
+
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from opal_tools_sdk.decorators import _resolve_json_schema
+from opal_tools_sdk.models import Parameter, ParameterType
+
+
+class OutputFormat(str, Enum):
+    markdown = "markdown"
+    raw = "raw"
+
+
+class BrowseWebUrlItem(BaseModel):
+    url: str = Field(description="The webpage URL to browse.")
+    information_needed: Optional[str] = Field(
+        default=None, description="What information to extract"
+    )
+    output_format: Optional[OutputFormat] = Field(
+        default=None, description="Output format"
+    )
+
+
+class SimpleItem(BaseModel):
+    name: str = Field(description="Item name")
+    count: int = Field(description="Item count")
+
+
+class TestResolveJsonSchema:
+    """Tests for _resolve_json_schema helper."""
+
+    def test_simple_object(self):
+        schema = SimpleItem.model_json_schema()
+        defs = schema.pop("$defs", {})
+        resolved = _resolve_json_schema(schema, defs)
+        assert resolved["type"] == "object"
+        assert resolved["properties"]["name"] == {
+            "type": "string",
+            "description": "Item name",
+        }
+        assert resolved["properties"]["count"] == {
+            "type": "integer",
+            "description": "Item count",
+        }
+        assert resolved["required"] == ["name", "count"]
+
+    def test_optional_field_simplified(self):
+        schema = BrowseWebUrlItem.model_json_schema()
+        defs = schema.pop("$defs", {})
+        resolved = _resolve_json_schema(schema, defs)
+        info = resolved["properties"]["information_needed"]
+        assert info["type"] == "string"
+        assert "description" in info
+
+    def test_enum_ref_resolved(self):
+        schema = BrowseWebUrlItem.model_json_schema()
+        defs = schema.pop("$defs", {})
+        resolved = _resolve_json_schema(schema, defs)
+        fmt = resolved["properties"]["output_format"]
+        assert fmt["type"] == "string"
+        assert fmt["enum"] == ["markdown", "raw"]
+
+    def test_required_fields(self):
+        schema = BrowseWebUrlItem.model_json_schema()
+        defs = schema.pop("$defs", {})
+        resolved = _resolve_json_schema(schema, defs)
+        assert resolved["required"] == ["url"]
+
+    def test_ref_resolution(self):
+        defs = {"MyType": {"type": "string", "enum": ["a", "b"]}}
+        schema = {"$ref": "#/$defs/MyType"}
+        resolved = _resolve_json_schema(schema, defs)
+        assert resolved == {"type": "string", "enum": ["a", "b"]}
+
+    def test_strips_title(self):
+        schema = {"type": "object", "title": "SomeModel", "properties": {}}
+        resolved = _resolve_json_schema(schema, {})
+        assert "title" not in resolved
+
+    def test_ref_preserves_sibling_description(self):
+        """$ref with sibling description should preserve the description."""
+        defs = {"Inner": {"type": "object", "properties": {"x": {"type": "string"}}}}
+        schema = {"$ref": "#/$defs/Inner", "description": "My inner object"}
+        resolved = _resolve_json_schema(schema, defs)
+        assert resolved["description"] == "My inner object"
+        assert resolved["type"] == "object"
+
+    def test_circular_ref_does_not_crash(self):
+        """Self-referential $ref should not cause infinite recursion."""
+        defs = {
+            "TreeNode": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "children": {"type": "array", "items": {"$ref": "#/$defs/TreeNode"}},
+                },
+            }
+        }
+        schema = {"$ref": "#/$defs/TreeNode"}
+        resolved = _resolve_json_schema(schema, defs)
+        assert resolved["type"] == "object"
+        # The circular ref should be broken with {type: object}
+        assert resolved["properties"]["children"]["items"]["type"] == "object"
+
+    def test_anyof_with_multiple_non_null_types(self):
+        """Union[str, int] should fall back to string."""
+        schema = {
+            "anyOf": [{"type": "string"}, {"type": "integer"}],
+            "description": "A union field",
+        }
+        resolved = _resolve_json_schema(schema, {})
+        assert resolved == {"type": "string", "description": "A union field"}
+
+
+class TestParameterToDict:
+    """Tests for Parameter.to_dict with schema field."""
+
+    def test_to_dict_with_array_schema(self):
+        param = Parameter(
+            name="urls",
+            param_type=ParameterType.list,
+            description="URLs",
+            required=True,
+            schema={"type": "array", "description": "URLs", "items": {"type": "object", "properties": {"url": {"type": "string"}}}},
+        )
+        d = param.to_dict()
+        assert d["schema"]["type"] == "array"
+        assert d["schema"]["items"]["properties"]["url"] == {"type": "string"}
+
+    def test_to_dict_with_object_schema(self):
+        param = Parameter(
+            name="config",
+            param_type=ParameterType.dictionary,
+            description="Config",
+            required=True,
+            schema={"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]},
+        )
+        d = param.to_dict()
+        assert d["schema"]["properties"]["name"] == {"type": "string"}
+        assert d["schema"]["required"] == ["name"]
+
+    def test_to_dict_without_schema(self):
+        """Backward compat: no schema key when None."""
+        param = Parameter(
+            name="query",
+            param_type=ParameterType.string,
+            description="Search",
+            required=True,
+        )
+        d = param.to_dict()
+        assert "schema" not in d
+
+    def test_schema_is_complete_json_schema(self):
+        """schema field must be a complete, self-contained JSON Schema."""
+        param = Parameter(
+            name="urls",
+            param_type=ParameterType.list,
+            description="URLs to browse",
+            required=True,
+            schema={
+                "type": "array",
+                "description": "URLs to browse",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "url": {"type": "string", "description": "The URL"},
+                    },
+                    "required": ["url"],
+                },
+            },
+        )
+        d = param.to_dict()
+        schema = d["schema"]
+        # Schema is self-contained: includes type and description
+        assert schema["type"] == "array"
+        assert schema["description"] == "URLs to browse"
+        assert schema["items"]["type"] == "object"
+        assert schema["items"]["required"] == ["url"]
+
+
+class TestToolDecoratorNestedExtraction:
+    """Tests for the @tool decorator extracting nested schemas from Pydantic models."""
+
+    def test_list_of_pydantic_model(self):
+        """Simulates what the decorator does for List[BaseModel] fields."""
+        raw = SimpleItem.model_json_schema()
+        defs = raw.pop("$defs", {})
+        items_schema = _resolve_json_schema(raw, defs)
+        assert items_schema["type"] == "object"
+        assert "name" in items_schema["properties"]
+        assert "count" in items_schema["properties"]
+
+    def test_list_of_str_schema(self):
+        """List[str] should produce a complete array schema."""
+        param = Parameter(
+            name="tags",
+            param_type=ParameterType.list,
+            description="Tags",
+            required=False,
+            schema={"type": "array", "description": "Tags", "items": {"type": "string"}},
+        )
+        d = param.to_dict()
+        assert d["schema"]["type"] == "array"
+        assert d["schema"]["items"] == {"type": "string"}
+
+    def test_browse_web_url_item_full(self):
+        """Full integration test with BrowseWebUrlItem model."""
+        raw = BrowseWebUrlItem.model_json_schema()
+        defs = raw.pop("$defs", {})
+        items_schema = _resolve_json_schema(raw, defs)
+
+        assert items_schema["type"] == "object"
+        assert items_schema["properties"]["url"]["type"] == "string"
+        assert items_schema["properties"]["information_needed"]["type"] == "string"
+        assert items_schema["properties"]["output_format"]["enum"] == ["markdown", "raw"]
+        assert items_schema["required"] == ["url"]
+
+        # Build the complete schema as the decorator would
+        full_schema = {"type": "array", "description": "URLs to browse", "items": items_schema}
+        param = Parameter(
+            name="urls",
+            param_type=ParameterType.list,
+            description="URLs to browse",
+            required=True,
+            schema=full_schema,
+        )
+        d = param.to_dict()
+        assert d["schema"]["type"] == "array"
+        assert d["schema"]["items"]["type"] == "object"
+        assert "url" in d["schema"]["items"]["properties"]
+        # Uses standard "required" key, not "required_properties"
+        assert d["schema"]["items"]["required"] == ["url"]