0.2.1

[h3xxit]

Summary by cubic

Added detailed docstrings and usage documentation to all core UTCP modules, models, and interfaces to improve code clarity and developer onboarding.

• Docs and Comments
  • Added or expanded module-level and class-level docstrings for all main files, including client interfaces, providers, transports, tool schemas, and configuration.
  • Clarified usage, attributes, and examples for each provider and tool type.
  • Improved inline documentation for variable substitution, search strategies, and authentication models.

[cubic-dev-ai]

cubic analysis

3 issues found across 16 files • Review in cubic

_{React with 👍 or 👎 to teach cubic. You can also tag @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

The new type hint restricts obj to dict | list | str, but the method documentation and implementation are designed to accept any type; this mismatch can trigger unnecessary type-checking errors and breaks backward compatibility.

Prompt for AI agents

Address the following comment on src/utcp/client/variable_substitutor.py at line 31:

<comment>The new type hint restricts `obj` to `dict | list | str`, but the method documentation and implementation are designed to accept any type; this mismatch can trigger unnecessary type-checking errors and breaks backward compatibility.</comment>

<file context>
@@ -7,16 +19,87 @@
 from typing import List, Optional
 
 class VariableSubstitutor(ABC):
+    &quot;&quot;&quot;Abstract interface for variable substitution implementations.
+
+    Defines the contract for variable substitution systems that can replace
+    placeholders in configuration data with actual values from various sources.
+    Implementations handle different variable resolution strategies and
+    source hierarchies.
</file context>

Suggested change

	def substitute(self, obj: dict | list | str, config: UtcpClientConfig, provider_name: Optional[str] = None) -> Any:
	def substitute(self, obj: Any, config: UtcpClientConfig, provider_name: Optional[str] = None) -> Any:

[cubic-dev-ai]

Docstring says the logger accepts only a log message, but the implementation calls the logger with additional keyword arguments (e.g., error=True), so the documentation is misleading.

Prompt for AI agents

Address the following comment on src/utcp/client/transport_interfaces/http_transport.py at line 57:

<comment>Docstring says the logger accepts only a log message, but the implementation calls the logger with additional keyword arguments (e.g., error=True), so the documentation is misleading.</comment>

<file context>
@@ -15,7 +29,34 @@
 from aiohttp import ClientSession, BasicAuth as AiohttpBasicAuth
 
 class HttpClientTransport(ClientTransportInterface):
+    &quot;&quot;&quot;HTTP transport implementation for UTCP client.
+
+    Handles communication with HTTP-based tool providers, supporting various
+    authentication methods, URL path parameters, and automatic tool discovery.
+    Enforces security by requiring HTTPS or localhost connections.
+
</file context>

Suggested change

	logger: Optional logging function that accepts log messages.
	logger: Optional logging function that accepts *args and **kwargs.

[cubic-dev-ai]

param_description is Optional but later treated as a dict without a None-check; calling this function with the default None will raise AttributeError at runtime

Prompt for AI agents

Address the following comment on src/utcp/shared/tool.py at line 339:

<comment>param_description is Optional but later treated as a dict without a None-check; calling this function with the default None will raise AttributeError at runtime</comment>

<file context>
@@ -176,7 +336,20 @@ def recurse_type(param_type):
         &quot;description&quot;: &quot;&quot;
     }
 
-def type_to_json_schema(param_type, param_name=None, param_description=None):
+def type_to_json_schema(param_type, param_name: Optional[str] = None, param_description: Optional[Dict[str, str]] = None) -&gt; Dict[str, Any]:
+    &quot;&quot;&quot;Convert Python type to JSON Schema with description handling.
+
</file context>