Merge branch 'main' into sap_om_poc

Author: Venkatakrishnan774

.pre-commit-config.yaml

@@ -9,17 +9,17 @@ repos:
     hooks:
       - id: ruff-format
         name: ruff format
-        entry: uvx ruff format --force-exclude --check
+        entry: uv run ruff format --force-exclude --check
         language: system
         types: [python]
       - id: ruff-check
         name: ruff check
-        entry: uvx ruff check --force-exclude --fix
+        entry: uv run ruff check --force-exclude --fix
         language: system
         types: [python]
       - id: ty-check
         name: ty type check
-        entry: uvx ty check .
+        entry: uv run ty check .
         language: system
         types: [python]
         pass_filenames: false

docs/DEVELOPMENT.md

@@ -34,7 +34,7 @@ Tip:
 ## Type Check
 
 ```bash
-uvx ty check .
+uv run ty check .
 ```
 
 ## Code Quality Checks
@@ -49,9 +49,12 @@ uv run ruff check .
 uv run ruff format --check .
 
 # Type check
-uvx ty check .
+uv run ty check .
 ```
 
+> **Linter versions are pinned.** `ruff` and `ty` are pinned to exact versions in the
+> `pyproject.toml` `[dependency-groups] dev` section (and locked in `uv.lock`) for consistent runs across local and CI.
+
 ## Pre-commit Hooks (Recommended)
 
 Automatically run quality checks before each commit using pre-commit hooks.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sap-cloud-sdk"
-version = "0.40.0"
+version = "0.39.2"
 description = "SAP Cloud SDK for Python"
 readme = "README.md"
 license = "Apache-2.0"
@@ -64,9 +64,9 @@ dev = [
     "pytest-asyncio>=1.0.0",
     "pytest-bdd>=7.2.0",
     "python-dotenv>=1.0.0",
-    "ty>=0.0.21",
+    "ty==0.0.64",
     "cryptography>=46.0.3",
-    "ruff>=0.8.0",
+    "ruff==0.16.0",
     "starlette>=0.40.0",
     "anyio>=3.6.2",
     "httpx>=0.27.0",

src/sap_cloud_sdk/adms/user-guide.md

@@ -45,6 +45,7 @@ relation = client.relations.create(
 
 # Upload bytes to the presigned URL (outside SDK)
 import requests
+
 upload_url = relation.document.document_content_upload_urls[0]
 requests.put(upload_url, data=open("Invoice.pdf", "rb"))
 ```
@@ -82,6 +83,7 @@ client = create_client(user_jwt=request.headers["Authorization"].split()[1])
 ```python
 from sap_cloud_sdk.adms import create_client, TokenCache
 
+
 # By default tokens are cached in-process via InMemoryTokenCache.
 # For multi-instance deployments (Kyma replicas > 1, CF instances > 1),
 # implement your own TokenCache subclass backed by the shared cache your
@@ -91,13 +93,21 @@ class MySharedCache(TokenCache):
     def set(self, key, token, ttl_seconds): ...
     def delete(self, key): ...
 
+
 client = create_client(token_cache=MySharedCache())
 ```
 
 ## Async Client
 
 ```python
-from sap_cloud_sdk.adms import create_async_client, BaseType, CreateDocumentInput, CreateDocumentRelationInput, RelationQueryOptions
+from sap_cloud_sdk.adms import (
+    create_async_client,
+    BaseType,
+    CreateDocumentInput,
+    CreateDocumentRelationInput,
+    RelationQueryOptions,
+)
+
 
 async def main():
     async with create_async_client() as client:
@@ -203,6 +213,7 @@ job = client.jobs.start_zip_download(params)
 
 # Poll until terminal state
 import time
+
 while not job.job_status or not job.job_status.is_terminal():
     time.sleep(2)
     job = client.jobs.get_status(job.job_id)

src/sap_cloud_sdk/agent_decorators/user-guide.md

@@ -21,6 +21,7 @@ from sap_cloud_sdk.agent_decorators import (
 ```python
 from sap_cloud_sdk.agent_decorators import prompt_section, agent_model
 
+
 # Define a prompt with a coded default
 @prompt_section(
     key="prompts.system",
@@ -30,6 +31,7 @@ from sap_cloud_sdk.agent_decorators import prompt_section, agent_model
 def system_prompt() -> str:
     return "You are a helpful assistant."
 
+
 # Define the model selection
 @agent_model(key="config.model", label="LLM Model")
 def model_name() -> str:
@@ -45,6 +47,7 @@ Expose a prompt section for editing.
 ```python
 from sap_cloud_sdk.agent_decorators import prompt_section
 
+
 @prompt_section(
     key="prompts.identity",
     label="Agent Identity",
@@ -62,6 +65,7 @@ Expose a configuration value for editing.
 ```python
 from sap_cloud_sdk.agent_decorators import agent_config
 
+
 @agent_config(
     key="config.temperature",
     label="Temperature",
@@ -78,6 +82,7 @@ Expose a model selection. The `description` parameter is optional.
 ```python
 from sap_cloud_sdk.agent_decorators import agent_model
 
+
 @agent_model(
     key="config.model",
     label="Default Model",
@@ -93,6 +98,7 @@ def default_model() -> str:
 from sap_cloud_sdk.agent_decorators.exceptions import AgentDecoratorError
 
 try:
+
     @prompt_section(key="", label="L", description="D")
     def bad():
         return ""

src/sap_cloud_sdk/agent_memory/user-guide.md

@@ -714,6 +714,7 @@ elif total <= PAGE_SIZE:
         agent_id="my-agent", invoker_id="user-123", limit=total
     )
 else:
+
     def iter_all_memories(client, agent_id, invoker_id, page_size=PAGE_SIZE):
         offset = 0
         while True:
@@ -781,7 +782,8 @@ The default `threshold` of `0.6` may be too strict for your data. Try a lower va
 
 ```python
 results = client.search_memories(
-    agent_id="my-agent", invoker_id="user-123",
+    agent_id="my-agent",
+    invoker_id="user-123",
     query="user display preferences",
     threshold=0.3,
 )
@@ -933,10 +935,10 @@ from sap_cloud_sdk.agent_memory.factory.langgraph_checkpoint import create_check
     key="config.checkpointer.ttl_seconds",
     label="Thread TTL (seconds)",
     description="Evict inactive conversation threads after this period of "
-                "inactivity. Set to 0 to disable eviction.",
+    "inactivity. Set to 0 to disable eviction.",
 )
 def thread_ttl_seconds() -> int:
-    return 3600 # 1 hour
+    return 3600  # 1 hour
 
 
 class MyAgent:

src/sap_cloud_sdk/agentgateway/_customer.py

@@ -642,7 +642,7 @@ async def _list_server_tools(
         async with streamable_http_client(url, http_client=http_client) as (
             read,
             write,
-            _,
+            *_,
         ):
             async with ClientSession(read, write) as session:
                 init_result = await session.initialize()
@@ -672,6 +672,25 @@ async def _list_server_tools(
                 ]
 
 
+def _log_mcp_server_error(ord_id: str, exc: BaseException) -> None:
+    # Unwrap ExceptionGroup from anyio to surface the real HTTP error body
+    if isinstance(exc, BaseExceptionGroup):
+        for inner in exc.exceptions:
+            _log_mcp_server_error(ord_id, inner)
+        return
+    if isinstance(exc, httpx.HTTPStatusError):
+        logger.error(
+            "Failed to load tools from %s (HTTP %d): %s",
+            ord_id,
+            exc.response.status_code,
+            exc.response.text[:500],
+        )
+    else:
+        logger.exception(
+            "Failed to load tools from %s — skipping", ord_id, exc_info=exc
+        )
+
+
 async def get_mcp_tools_customer(
     credentials: CustomerCredentials,
     system_token: str,
@@ -689,16 +708,14 @@ async def get_mcp_tools_customer(
 
     Returns:
         List of MCPTool objects from all servers.
-
-    Raises:
-        AgentGatewaySDKError: If integrationDependencies is empty.
     """
     dependencies = credentials.integration_dependencies
 
     if not dependencies:
-        raise AgentGatewaySDKError(
+        logger.warning(
             "integrationDependencies is empty in credentials — no MCP servers configured."
         )
+        return []
 
     logger.info("Discovering tools from %d MCP server(s)", len(dependencies))
 
@@ -717,8 +734,8 @@ async def get_mcp_tools_customer(
             server_tools = await _list_server_tools(url, system_token, timeout)
             tools.extend(server_tools)
             logger.debug("Loaded %d tool(s) from %s", len(server_tools), dep.ord_id)
-        except Exception:
-            logger.exception("Failed to load tools from %s — skipping", dep.ord_id)
+        except Exception as exc:
+            _log_mcp_server_error(dep.ord_id, exc)
 
     logger.info(
         "Loaded %d MCP tool(s) from %d server(s)", len(tools), len(dependencies)
@@ -758,7 +775,7 @@ async def call_mcp_tool_customer(
         async with streamable_http_client(tool.url, http_client=http_client) as (
             read,
             write,
-            _,
+            *_,
         ):
             async with ClientSession(read, write) as session:
                 await session.initialize()
@@ -769,4 +786,9 @@ async def call_mcp_tool_customer(
                     return ""
 
                 first = result.content[0]
-                return str(getattr(first, "text", ""))
+                text = str(getattr(first, "text", ""))
+
+                if result.isError:
+                    logger.error("Tool '%s' returned an error: %s", tool.name, text)
+
+                return text

src/sap_cloud_sdk/agentgateway/_lob.py

@@ -290,6 +290,26 @@ def _fetch_user_auth_sync():
     return token, gateway_url
 
 
+def _log_mcp_server_error(fragment_name: str, exc: BaseException) -> None:
+    if isinstance(exc, BaseExceptionGroup):
+        for inner in exc.exceptions:
+            _log_mcp_server_error(fragment_name, inner)
+        return
+    if isinstance(exc, httpx.HTTPStatusError):
+        logger.error(
+            "Failed to load tools from fragment '%s' (HTTP %d): %s",
+            fragment_name,
+            exc.response.status_code,
+            exc.response.text[:500],
+        )
+    else:
+        logger.exception(
+            "Failed to load tools from fragment '%s' — skipping",
+            fragment_name,
+            exc_info=exc,
+        )
+
+
 async def list_server_tools(
     dest_url: str, auth_token: str, fragment_name: str, timeout: float
 ) -> list[MCPTool]:
@@ -313,7 +333,7 @@ async def list_server_tools(
         async with streamable_http_client(dest_url, http_client=http_client) as (
             read,
             write,
-            _,
+            *_,
         ):
             async with ClientSession(read, write) as session:
                 init_result = await session.initialize()
@@ -388,11 +408,8 @@ async def get_mcp_tools_lob(
                 len(server_tools),
                 fragment_name,
             )
-        except Exception:
-            logger.exception(
-                "Failed to load tools from fragment '%s' — skipping",
-                fragment_name,
-            )
+        except Exception as exc:
+            _log_mcp_server_error(fragment_name, exc)
 
     logger.info("Loaded %d MCP tool(s) from %d fragment(s)", len(tools), len(fragments))
     return tools
@@ -427,7 +444,7 @@ async def call_mcp_tool_lob(
         async with streamable_http_client(tool.url, http_client=http_client) as (
             read,
             write,
-            _,
+            *_,
         ):
             async with ClientSession(read, write) as session:
                 await session.initialize()
@@ -436,7 +453,12 @@ async def call_mcp_tool_lob(
                     logger.warning("Tool '%s' returned empty content", tool.name)
                     return ""
                 first = result.content[0]
-                return str(getattr(first, "text", ""))
+                text = str(getattr(first, "text", ""))
+
+                if result.isError:
+                    logger.error("Tool '%s' returned an error: %s", tool.name, text)
+
+                return text
 
 
 async def _fetch_agent_card(

src/sap_cloud_sdk/agentgateway/user-guide.md

@@ -250,7 +250,7 @@ from sap_cloud_sdk.agentgateway import AgentCardFilter
 
 AgentCardFilter(
     agent_names=[],  # agent card names to include (matched against card JSON `name`); empty = no filter
-    ord_ids=[],      # ORD IDs to include (extracted from fragment URL); empty = no filter
+    ord_ids=[],  # ORD IDs to include (extracted from fragment URL); empty = no filter
 )
 ```
 
@@ -261,12 +261,14 @@ Both fields default to empty lists. Filters are applied with AND semantics: if b
 ```python
 @dataclass
 class Agent:
-    ord_id: str       # ORD ID from fragment ordId property
+    ord_id: str  # ORD ID from fragment ordId property
     agent_card: AgentCard
 
+
 @dataclass
 class AgentCard:
-    raw: dict         # full parsed JSON from /.well-known/agent-card.json
+    raw: dict  # full parsed JSON from /.well-known/agent-card.json
+
 
 @dataclass
 class MCPTool: