Migrate from OAKRunner to ArazzoRunner (#42)

Author: Killian-Jentic

mcp/pyproject.toml

@@ -58,14 +58,14 @@ mcp = "mcp.main:app"
 
 [tool.black]
 line-length = 100
-target-version = ["py310"]
+target-version = ["py311"]
 
 [tool.isort]
 profile = "black"
 line_length = 100
 
 [tool.mypy]
-python_version = "3.10"
+python_version = "3.11"
 disallow_untyped_defs = true
 disallow_incomplete_defs = true
 check_untyped_defs = true
@@ -78,7 +78,7 @@ warn_unused_ignores = true
 
 [tool.ruff]
 line-length = 100
-target-version = "py310"
+target-version = "py311"
 select = ["E", "F", "B", "W", "I", "N", "UP", "YTT", "S"]
 ignore = []
 

python/README.md

@@ -2,7 +2,7 @@
 
 Jentic SDK is a comprehensive library for discovery and execution of APIs and workflows.
 
-The Jentic SDK is backed by the data in the [Open Agentic Knowledge (OAK)](https://github.com/jentic/oak) repository.
+The Jentic SDK is backed by the data in the [Jentic Public API](https://github.com/jentic/jentic-public-api) repository.
 
 ## Core API & Use Cases
 

python/pdm.lock

@@ -12,7 +12,7 @@ dependencies = [
     "pyyaml>=6.0",
     "jsonpath-ng>=1.5.0",
     "httpx>=0.28.1",
-    "oak-runner>=0.8.9"
+    "arazzo_runner>=0.8.14"
 ]
 requires-python = ">=3.11"
 readme = "README.md"

python/pyproject.toml

@@ -6,10 +6,10 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-from oak_runner.auth.auth_processor import AuthProcessor
-from oak_runner.auth.models import SecurityOption
-from oak_runner.extractor.openapi_extractor import extract_operation_io
-from oak_runner import OAKRunner
+from arazzo_runner.auth.auth_processor import AuthProcessor
+from arazzo_runner.auth.models import SecurityOption
+from arazzo_runner.extractor.openapi_extractor import extract_operation_io
+from arazzo_runner import ArazzoRunner
 
 from jentic.api.api_hub import JenticAPIClient
 from jentic.models import GetFilesResponse
@@ -186,7 +186,7 @@ async def generate_config_from_uuids(
             )
 
         # Step 5: Process authentication requirements
-        env_mappings = OAKRunner.generate_env_mappings(arazzo_docs=all_arazzo_specs, source_descriptions=all_openapi_specs)
+        env_mappings = ArazzoRunner.generate_env_mappings(arazzo_docs=all_arazzo_specs, source_descriptions=all_openapi_specs)
 
         # Step 6: Compose final config
         final_config = {

python/src/jentic/agent_runtime/config.py

@@ -5,7 +5,7 @@
 from dataclasses import dataclass
 from typing import Any, Dict, Optional
 
-from oak_runner import OAKRunner, WorkflowExecutionResult, WorkflowExecutionStatus
+from arazzo_runner import ArazzoRunner, WorkflowExecutionResult, WorkflowExecutionStatus
 
 from jentic import api
 from jentic.api import JenticAPIClient
@@ -54,7 +54,7 @@ def __init__(self, api_hub_client: Optional[JenticAPIClient] = None):
         self.api_hub_client = api_hub_client or JenticAPIClient()
 
     async def execute_workflow(self, workflow_uuid: str, inputs: Dict[str, Any]) -> WorkflowResult:
-        """Executes a specified workflow using OAK runner.
+        """Executes a specified workflow using Arazzo runner.
 
         Args:
             workflow_uuid: The UUID of the workflow to execute.
@@ -94,18 +94,18 @@ async def execute_workflow(self, workflow_uuid: str, inputs: Dict[str, Any]) ->
                     error=f"Arazzo document or internal workflow ID missing for {workflow_uuid}",
                 )
 
-            # 4. Instantiate OAKRunner
+            # 4. Instantiate ArazzoRunner
             logger.debug(
-                f"Instantiating OAKRunner for internal workflow ID: {friendly_workflow_id}"
+                f"Instantiating ArazzoRunner for internal workflow ID: {friendly_workflow_id}"
             )
-            runner = OAKRunner(
+            runner = ArazzoRunner(
                 arazzo_doc=arazzo_doc,
                 source_descriptions=source_descriptions,
             )
 
             # 5. Execute the workflow using the INTERNAL workflow ID
             logger.debug(
-                f"Running workflow {friendly_workflow_id} via OAKRunner with UUID {workflow_uuid}."
+                f"Running workflow {friendly_workflow_id} via ArazzoRunner with UUID {workflow_uuid}."
             )
             # Removed await as runner.execute_workflow seems synchronous based on TypeError
             execution_output: WorkflowExecutionResult = runner.execute_workflow(
@@ -136,7 +136,7 @@ async def execute_operation(
         inputs: Dict[str, Any],
     ) -> OperationResult:
         """
-        Executes a specified API operation using OAKRunner after fetching required files from the API.
+        Executes a specified API operation using ArazzoRunner after fetching required files from the API.
 
         Args:
             operation_uuid: The UUID of the operation to execute.
@@ -167,7 +167,7 @@ async def execute_operation(
                 )
             operation_entry = exec_files_response.operations[operation_uuid]
 
-            # Prepare OpenAPI spec for OAKRunner
+            # Prepare OpenAPI spec for ArazzoRunner
             openapi_content = None
             openapi_files = exec_files_response.files.get("open_api", {})
             if operation_entry.files.open_api:
@@ -183,15 +183,15 @@ async def execute_operation(
                 )
             source_descriptions = {"default": openapi_content}
 
-            # Prepare OAKRunner and execute the operation
-            runner = OAKRunner(source_descriptions=source_descriptions)
+            # Prepare ArazzoRunner and execute the operation
+            runner = ArazzoRunner(source_descriptions=source_descriptions)
             # Pass operation_uuid, path, and method from the operation_entry
-            oak_result: Any = runner.execute_operation(
+            runner_result: Any = runner.execute_operation(
                 inputs=inputs, operation_path=f"{operation_entry.method} {operation_entry.path}"
             )
-            logger.debug(f"Operation execution result: {oak_result}")
+            logger.debug(f"Operation execution result: {runner_result}")
 
-            return self._process_operation_result(oak_result, operation_uuid, inputs)
+            return self._process_operation_result(runner_result, operation_uuid, inputs)
         except Exception as e:
             logger.exception(f"Error executing operation {operation_uuid}: {e}")
             return OperationResult(
@@ -201,18 +201,18 @@ async def execute_operation(
             )
 
     def _process_operation_result(
-        self, oak_result: Dict[str, Any], operation_uuid: str, inputs: Dict[str, Any]
+        self, runner_result: Dict[str, Any], operation_uuid: str, inputs: Dict[str, Any]
     ) -> "OperationResult":
-        """Process the OAKRunner operation result, check status codes, and handle casting.
+        """Process the ArazzoRunner operation result, check status codes, and handle casting.
 
         Args:
-            oak_result: The result dictionary from OAKRunner.execute_operation.
+            runner_result: The result dictionary from ArazzoRunner.execute_operation.
             operation_uuid: The UUID of the operation being executed, for logging.
 
         Returns:
             An OperationResult object.
         """
-        status_code_uncast = oak_result.get("status_code")
+        status_code_uncast = runner_result.get("status_code")
 
         if status_code_uncast is None:
             logger.debug(
@@ -221,7 +221,7 @@ def _process_operation_result(
             )
             return OperationResult(
                 success=True,
-                output=oak_result.get("body") if "body" in oak_result else oak_result,
+                output=runner_result.get("body") if "body" in runner_result else runner_result,
                 inputs=inputs,
             )
 
@@ -240,7 +240,7 @@ def _process_operation_result(
                 return OperationResult(
                     success=False,
                     error=f"Invalid status_code format: '{status_code_uncast}'. Expected an integer or integer-convertible value.",
-                    output=oak_result,  # Include full OAK result for context on casting errors
+                    output=runner_result,  # Include full OAK result for context on casting errors
                     inputs=inputs,
                 )
         else:
@@ -252,12 +252,12 @@ def _process_operation_result(
             return OperationResult(
                 success=True,
                 status_code=status_code,
-                output=oak_result.get("body") if "body" in oak_result else oak_result,
+                output=runner_result.get("body") if "body" in runner_result else runner_result,
                 inputs=inputs,
             )
         else:
             # Non-2xx status code, indicates an error
-            body_content = oak_result.get("body")
+            body_content = runner_result.get("body")
             error_detail = ""
 
             if isinstance(body_content, dict):
@@ -284,7 +284,7 @@ def _process_operation_result(
                 success=False,
                 status_code=status_code,
                 error=error_detail,
-                output=oak_result,  # Return the full OAK result as output for context on errors
+                output=runner_result,  # Return the full OAK result as output for context on errors
                 inputs=inputs,
             )
 

python/src/jentic/agent_runtime/tool_execution.py

@@ -133,17 +133,17 @@ def _build_source_descriptions(
                 openapi_file_id = openapi_file_id_obj.id
                 if openapi_file_id in all_openapi_files:
                     file_entry = all_openapi_files[openapi_file_id]
-                    # Store content and oak_path for direct matching
-                    # Assumes file_entry has an 'oak_path' attribute from the API response
-                    if hasattr(file_entry, 'oak_path') and file_entry.oak_path is not None:
+                    # Store content and source_path for direct matching
+                    # Assumes file_entry has a 'source_path' attribute from the API response
+                    if hasattr(file_entry, 'source_path') and file_entry.source_path is not None:
                         openapi_files[openapi_file_id] = {
                             "content": file_entry.content,
-                            "oak_path": file_entry.oak_path
+                            "source_path": file_entry.source_path
                         }
-                        logger.debug(f"Found OpenAPI file with oak_path: {file_entry.oak_path} (ID: {openapi_file_id})")
+                        logger.debug(f"Found OpenAPI file with source_path: {file_entry.source_path} (ID: {openapi_file_id})")
                     else:
                         logger.warning(
-                            f"OpenAPI file entry with ID {openapi_file_id} (filename: {file_entry.filename}) is missing 'oak_path'. Cannot use for matching."
+                            f"OpenAPI file entry with ID {openapi_file_id} (filename: {file_entry.filename}) is missing 'source_path'. Cannot use for matching."
                         )
                 else:
                     logger.warning(
@@ -152,7 +152,7 @@ def _build_source_descriptions(
 
             if not openapi_files:
                 logger.warning(
-                    f"No usable OpenAPI file content (with oak_path) found for workflow {workflow_entry.workflow_id} despite references."
+                    f"No usable OpenAPI file content (with source_path) found for workflow {workflow_entry.workflow_id} despite references."
                 )
         elif not all_openapi_files:
             logger.warning(
@@ -163,7 +163,7 @@ def _build_source_descriptions(
                 f"Workflow {workflow_entry.workflow_id} does not reference any OpenAPI files."
             )
 
-        # 3. Map each Arazzo source description to matching OpenAPI content by oak_path
+        # 3. Map each Arazzo source description to matching OpenAPI content by source_path
         if arazzo_source_names and openapi_files:
             # Extract source descriptions with their URLs
             arazzo_sources_with_urls = []
@@ -178,33 +178,33 @@ def _build_source_descriptions(
             except Exception as e:
                 logger.error(f"Error extracting URLs from sourceDescriptions: {e}")
 
-            # Match Arazzo sourceDescriptions to OpenAPI files by comparing source.url with file.oak_path
+            # Match Arazzo sourceDescriptions to OpenAPI files by comparing source.url with file.source_path
             for source in arazzo_sources_with_urls:
                 source_name = source["name"]
                 source_url = source["url"]
 
                 matched = False
                 for file_id, file_info in openapi_files.items():
-                    openapi_oak_path = file_info["oak_path"]
+                    openapi_source_path = file_info["source_path"]
 
-                    if source_url == openapi_oak_path:
+                    if source_url == openapi_source_path:
                         source_descriptions[source_name] = file_info["content"]
                         matched = True
                         logger.info(
                             f"Matched Arazzo source '{source_name}' (URL: {source_url}) "
-                            f"to OpenAPI file with oak_path '{openapi_oak_path}' (ID: {file_id})"
+                            f"to OpenAPI file with source_path '{openapi_source_path}' (ID: {file_id})"
                         )
                         break # Found the match for this Arazzo source
 
                 if not matched:
                     logger.warning(
-                        f"Could not find an OpenAPI file with oak_path matching Arazzo sourceDescription URL '{source_url}' "
+                        f"Could not find an OpenAPI file with source_path matching Arazzo sourceDescription URL '{source_url}' "
                         f"for source name '{source_name}' in workflow {workflow_entry.workflow_id}. This source will not be available."
                     )
 
         elif not openapi_files and arazzo_source_names:
             logger.warning(
-                f"No OpenAPI files with oak_path were available to match against Arazzo source descriptions for workflow {workflow_entry.workflow_id}."
+                f"No OpenAPI files with source_path were available to match against Arazzo source descriptions for workflow {workflow_entry.workflow_id}."
             )
 
         if not source_descriptions and arazzo_source_names:

python/src/jentic/api/api_hub.py

@@ -1,6 +1,6 @@
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 
 # Represents a reference to a file ID
@@ -14,7 +14,25 @@ class FileEntry(BaseModel):
     filename: str
     type: str
     content: Dict[str, Any]  # Content can be any valid JSON object
-    oak_path: Optional[str] = None  # Contextual path for the file, e.g., from Arazzo spec_files
+    source_path: Optional[str] = None  # Contextual path for the file, e.g., from Arazzo spec_files
+    
+    @model_validator(mode='before')
+    @classmethod
+    def handle_oak_path_alias(cls, values):
+        """Handle backward compatibility for oak_path field name."""
+        if isinstance(values, dict):
+            # If oak_path is provided but source_path is not, use oak_path
+            if 'oak_path' in values and 'source_path' not in values:
+                values['source_path'] = values.pop('oak_path')
+            # If both are provided, prefer source_path and remove oak_path
+            elif 'oak_path' in values and 'source_path' in values:
+                values.pop('oak_path')
+        return values
+    
+    @property
+    def oak_path(self) -> Optional[str]:
+        """Backward compatibility property for oak_path."""
+        return self.source_path
 
 
 # Represents an API reference within a workflow