refactor: SyncClient -> FileSyncer

Author: AlePouroullis

src/humanloop/cli/__main__.py

@@ -9,7 +9,7 @@
 from dotenv import load_dotenv
 
 from humanloop import Humanloop
-from humanloop.sync.sync_client import SyncClient
+from humanloop.sync.file_syncer import FileSyncer
 
 # Set up logging
 logger = logging.getLogger(__name__)
@@ -219,12 +219,12 @@ def pull(
 
     Currently only supports syncing Prompt and Agent files. Other file types will be skipped."""
     client = get_client(api_key, env_file, base_url)
-    # Although pull() is available on the Humanloop client, we instantiate SyncClient separately to control its log level.
+    # Although pull() is available on the Humanloop client, we instantiate FileSyncer separately to control its log level.
     # This allows CLI users to toggle between detailed logging (--verbose) and minimal output without affecting the
-    # main Humanloop client logger. The SyncClient uses its own logger namespace (humanloop.sdk.sync), making this
+    # main Humanloop client logger. The FileSyncer uses its own logger namespace (humanloop.sdk.sync), making this
     # modification isolated from the client's OpenTelemetry setup. This client instance is short-lived and only
     # exists for the duration of the CLI command execution.
-    sync_client = SyncClient(
+    file_syncer = FileSyncer(
         client, base_dir=local_files_directory, log_level=logging.DEBUG if verbose else logging.WARNING
     )
 
@@ -233,7 +233,7 @@ def pull(
     click.echo(click.style(f"Environment: {environment or '(default)'}", fg=INFO_COLOR))
 
     start_time = time.time()
-    successful_files, failed_files = sync_client.pull(path, environment)
+    successful_files, failed_files = file_syncer.pull(path, environment)
     duration_ms = int((time.time() - start_time) * 1000)
 
     # Determine if the operation was successful based on failed_files

src/humanloop/client.py

@@ -28,7 +28,7 @@
 from humanloop.overload import overload_client
 from humanloop.prompt_utils import populate_template
 from humanloop.prompts.client import PromptsClient
-from humanloop.sync.sync_client import DEFAULT_CACHE_SIZE, SyncClient
+from humanloop.sync.file_syncer import DEFAULT_CACHE_SIZE, FileSyncer
 
 logger = logging.getLogger("humanloop.sdk")
 
@@ -158,7 +158,7 @@ def __init__(
             )
 
         # Check if cache_size is non-default but use_local_files is False
-        self._sync_client = SyncClient(client=self, base_dir=local_files_directory, cache_size=cache_size)
+        self._file_syncer = FileSyncer(client=self, base_dir=local_files_directory, cache_size=cache_size)
         eval_client = ExtendedEvalsClient(client_wrapper=self._client_wrapper)
         eval_client.client = self
         self.evaluations = eval_client
@@ -168,10 +168,10 @@ def __init__(
         # and the @flow decorator providing the trace_id
         # Additionally, call and log methods are overloaded in the prompts and agents client to support the use of local files
         self.prompts = overload_client(
-            client=self.prompts, sync_client=self._sync_client, use_local_files=self.use_local_files
+            client=self.prompts, file_syncer=self._file_syncer, use_local_files=self.use_local_files
         )
         self.agents = overload_client(
-            client=self.agents, sync_client=self._sync_client, use_local_files=self.use_local_files
+            client=self.agents, file_syncer=self._file_syncer, use_local_files=self.use_local_files
         )
         self.flows = overload_client(client=self.flows)
         self.tools = overload_client(client=self.tools)
@@ -439,7 +439,7 @@ def pull(self, path: Optional[str] = None, environment: Optional[str] = None) ->
                or filesystem issues)
         :raises HumanloopRuntimeError: If there's an error communicating with the API
         """
-        return self._sync_client.pull(environment=environment, path=path)
+        return self._file_syncer.pull(environment=environment, path=path)
 
 
 class AsyncHumanloop(AsyncBaseHumanloop):

src/humanloop/overload.py

@@ -15,7 +15,7 @@
 from humanloop.evaluators.client import EvaluatorsClient
 from humanloop.flows.client import FlowsClient
 from humanloop.prompts.client import PromptsClient
-from humanloop.sync.sync_client import SyncClient
+from humanloop.sync.file_syncer import FileSyncer
 from humanloop.tools.client import ToolsClient
 from humanloop.types import FileType
 from humanloop.types.agent_call_response import AgentCallResponse
@@ -66,7 +66,7 @@ def _get_file_type_from_client(
 
 def _handle_tracing_context(kwargs: Dict[str, Any], client: T) -> Dict[str, Any]:
     """Handle tracing context for both log and call methods."""
-    trace_id = get_trace_id()   
+    trace_id = get_trace_id()
     if trace_id is not None:
         if "flow" in str(type(client).__name__).lower():
             context = get_decorator_context()
@@ -92,7 +92,7 @@ def _handle_tracing_context(kwargs: Dict[str, Any], client: T) -> Dict[str, Any]
 def _handle_local_files(
     kwargs: Dict[str, Any],
     client: T,
-    sync_client: SyncClient,
+    file_syncer: FileSyncer,
 ) -> Dict[str, Any]:
     """Load prompt/agent file content from local filesystem into API request.
 
@@ -103,7 +103,7 @@ def _handle_local_files(
     Args:
         kwargs: API call arguments
         client: Client instance making the call
-        sync_client: SyncClient handling local file operations
+        file_syncer: FileSyncer handling local file operations
 
     Returns:
         Updated kwargs with file content in prompt/agent field
@@ -126,7 +126,7 @@ def _handle_local_files(
         )
 
     # Then check for file extensions
-    if sync_client.is_file(path):
+    if file_syncer.is_file(path):
         # Extract the path without extension to suggest correct format in the error message
         path_without_extension = str(Path(path).with_suffix(""))
 
@@ -147,7 +147,7 @@ def _handle_local_files(
         )
 
     file_type = _get_file_type_from_client(client)
-    if file_type not in SyncClient.SERIALIZABLE_FILE_TYPES:
+    if file_type not in FileSyncer.SERIALIZABLE_FILE_TYPES:
         raise HumanloopRuntimeError(f"Local files are not supported for `{file_type.capitalize()}` files: '{path}'.")
 
     # If file_type is already specified in kwargs (prompt or agent), it means user provided a Prompt- or AgentKernelRequestParams object
@@ -159,7 +159,7 @@ def _handle_local_files(
         return kwargs
 
     try:
-        file_content = sync_client.get_file_content(path, file_type)  # type: ignore[arg-type] # file_type was checked above
+        file_content = file_syncer.get_file_content(path, file_type)  # type: ignore[arg-type] # file_type was checked above
         kwargs[file_type] = file_content
 
         return kwargs
@@ -175,7 +175,7 @@ def _handle_evaluation_context(kwargs: Dict[str, Any]) -> tuple[Dict[str, Any],
     return kwargs, None
 
 
-def _overload_log(self: T, sync_client: Optional[SyncClient], use_local_files: bool, **kwargs) -> LogResponseType:
+def _overload_log(self: T, file_syncer: Optional[FileSyncer], use_local_files: bool, **kwargs) -> LogResponseType:
     try:
         # Special handling for flows - prevent direct log usage
         if type(self) is FlowsClient and get_trace_id() is not None:
@@ -191,18 +191,18 @@ def _overload_log(self: T, sync_client: Optional[SyncClient], use_local_files: b
 
         # Handle loading files from local filesystem when using Prompts and Agents clients
         # This enables users to define prompts/agents in local files rather than fetching from the Humanloop API
-        if use_local_files and _get_file_type_from_client(self) in SyncClient.SERIALIZABLE_FILE_TYPES:
-            # Developer note: sync_client should always be provided during SDK initialization when
+        if use_local_files and _get_file_type_from_client(self) in FileSyncer.SERIALIZABLE_FILE_TYPES:
+            # Developer note: file_syncer should always be provided during SDK initialization when
             # use_local_files=True. If we hit this error, there's likely an initialization issue
-            # in Humanloop.__init__ where the sync_client wasn't properly created or passed to the
+            # in Humanloop.__init__ where the file_syncer wasn't properly created or passed to the
             # overload_client function.
-            if sync_client is None:
-                logger.error("sync_client is None but client has log method and use_local_files=%s", use_local_files)
+            if file_syncer is None:
+                logger.error("file_syncer is None but client has log method and use_local_files=%s", use_local_files)
                 raise HumanloopRuntimeError(
-                    "SDK initialization error: sync_client is missing but required for local file operations. "
+                    "SDK initialization error: file_syncer is missing but required for local file operations. "
                     "This is likely a bug in the SDK initialization - please report this issue to the Humanloop team."
                 )
-            kwargs = _handle_local_files(kwargs, self, sync_client)
+            kwargs = _handle_local_files(kwargs, self, file_syncer)
 
         kwargs, eval_callback = _handle_evaluation_context(kwargs)
         response = self._log(**kwargs)  # type: ignore[union-attr] # Use stored original method
@@ -217,15 +217,15 @@ def _overload_log(self: T, sync_client: Optional[SyncClient], use_local_files: b
         raise HumanloopRuntimeError from e
 
 
-def _overload_call(self: T, sync_client: Optional[SyncClient], use_local_files: bool, **kwargs) -> CallResponseType:
+def _overload_call(self: T, file_syncer: Optional[FileSyncer], use_local_files: bool, **kwargs) -> CallResponseType:
     try:
         kwargs = _handle_tracing_context(kwargs, self)
-        if use_local_files and _get_file_type_from_client(self) in SyncClient.SERIALIZABLE_FILE_TYPES:
-            # Same sync_client requirement as in _overload_log - see developer note there
-            if sync_client is None:
-                logger.error("sync_client is None but client has call method and use_local_files=%s", use_local_files)
-                raise HumanloopRuntimeError("sync_client is required for clients that support call operations")
-            kwargs = _handle_local_files(kwargs, self, sync_client)
+        if use_local_files and _get_file_type_from_client(self) in FileSyncer.SERIALIZABLE_FILE_TYPES:
+            # Same file_syncer requirement as in _overload_log - see developer note there
+            if file_syncer is None:
+                logger.error("file_syncer is None but client has call method and use_local_files=%s", use_local_files)
+                raise HumanloopRuntimeError("file_syncer is required for clients that support call operations")
+            kwargs = _handle_local_files(kwargs, self, file_syncer)
         return self._call(**kwargs)  # type: ignore[union-attr] # Use stored original method
     except HumanloopRuntimeError:
         # Re-raise HumanloopRuntimeError without wrapping to preserve the message
@@ -237,7 +237,7 @@ def _overload_call(self: T, sync_client: Optional[SyncClient], use_local_files:
 
 def overload_client(
     client: T,
-    sync_client: Optional[SyncClient] = None,
+    file_syncer: Optional[FileSyncer] = None,
     use_local_files: bool = False,
 ) -> T:
     """Overloads client methods to add tracing, local file handling, and evaluation context."""
@@ -246,25 +246,25 @@ def overload_client(
         # Store original method with type ignore
         client._log = client.log  # type: ignore
 
-        # Create a closure to capture sync_client and use_local_files
+        # Create a closure to capture file_syncer and use_local_files
         def log_wrapper(self: T, **kwargs) -> LogResponseType:
-            return _overload_log(self, sync_client, use_local_files, **kwargs)
+            return _overload_log(self, file_syncer, use_local_files, **kwargs)
 
         # Replace the log method with type ignore
         client.log = types.MethodType(log_wrapper, client)  # type: ignore
 
     # Overload call method for Prompt and Agent clients
-    if _get_file_type_from_client(client) in SyncClient.SERIALIZABLE_FILE_TYPES:
-        if sync_client is None and use_local_files:
-            logger.error("sync_client is None but client has call method and use_local_files=%s", use_local_files)
-            raise HumanloopRuntimeError("sync_client is required for clients that support call operations")
+    if _get_file_type_from_client(client) in FileSyncer.SERIALIZABLE_FILE_TYPES:
+        if file_syncer is None and use_local_files:
+            logger.error("file_syncer is None but client has call method and use_local_files=%s", use_local_files)
+            raise HumanloopRuntimeError("file_syncer is required for clients that support call operations")
         if hasattr(client, "call") and not hasattr(client, "_call"):
             # Store original method with type ignore
             client._call = client.call  # type: ignore
 
-            # Create a closure to capture sync_client and use_local_files
+            # Create a closure to capture file_syncer and use_local_files
             def call_wrapper(self: T, **kwargs) -> CallResponseType:
-                return _overload_call(self, sync_client, use_local_files, **kwargs)
+                return _overload_call(self, file_syncer, use_local_files, **kwargs)
 
             # Replace the call method with type ignore
             client.call = types.MethodType(call_wrapper, client)  # type: ignore

src/humanloop/path_utils.py

@@ -6,10 +6,7 @@ def normalize_path(path: str, strip_extension: bool = False) -> str:
 
     This function is primarily used when interacting with the Humanloop API to ensure paths
     follow the standard format: 'path/to/resource' without leading/trailing slashes.
-    It's used in several contexts:
-    1. When pulling files from Humanloop to local filesystem (see SyncClient.pull)
-    2. When making API calls that reference files by path
-    3. When handling local file operations that need to match API path conventions
+    It's used when pulling files from Humanloop to local filesystem (see FileSyncer.pull)
 
     The function:
     - Converts Windows backslashes to forward slashes

src/humanloop/sync/__init__.py

@@ -1,3 +1,3 @@
-from humanloop.sync.sync_client import SyncClient
+from humanloop.sync.file_syncer import FileSyncer
 
-__all__ = ["SyncClient"]
+__all__ = ["FileSyncer"]

src/humanloop/sync/sync_client.py src/humanloop/sync/file_syncer.pysrc/humanloop/sync/sync_client.py renamed to src/humanloop/sync/file_syncer.py

@@ -12,12 +12,12 @@
 if TYPE_CHECKING:
     from humanloop.base_client import BaseHumanloop
 
-# Set up isolated logger for sync operations
-# This logger uses the "humanloop.sdk.sync" namespace, separate from the main client's logger,
+# Set up isolated logger for file sync operations
+# This logger uses the "humanloop.sdk.file_syncer" namespace, separate from the main client's logger,
 # allowing CLI commands and other consumers to control sync logging verbosity independently.
 # This approach ensures that increasing verbosity for sync operations doesn't affect
 # other components of the system.
-logger = logging.getLogger("humanloop.sdk.sync")
+logger = logging.getLogger("humanloop.sdk.file_syncer")
 logger.setLevel(logging.INFO)
 console_handler = logging.StreamHandler()
 formatter = logging.Formatter("%(message)s")
@@ -62,16 +62,17 @@ def format_api_error(error: Exception) -> str:
 SerializableFileType = typing.Literal["prompt", "agent"]
 
 
-class SyncClient:
-    """Client for managing synchronization between local filesystem and Humanloop.
+class FileSyncer:
+    """Client for synchronizing Prompt and Agent files between Humanloop workspace and local filesystem.
 
-    This client provides file synchronization between Humanloop and the local filesystem,
-    with built-in caching for improved performance. The cache uses Python's LRU (Least
-    Recently Used) cache to automatically manage memory usage by removing least recently
-    accessed files when the cache is full.
+    This client enables a local development workflow by:
+    1. Pulling files from Humanloop workspace to local filesystem
+    2. Maintaining the same directory structure locally as in Humanloop
+    3. Storing files in human-readable, version-control friendly formats (.prompt and .agent)
+    4. Supporting local file access in the SDK when configured with use_local_files=True
 
-    The cache is automatically updated when files are pulled or saved, and can be
-    manually cleared using the clear_cache() method.
+    Files maintain their relative paths from the Humanloop workspace (with appropriate extensions added),
+    allowing for seamless reference between local and remote environments using the same path identifiers.
     """
 
     # File types that can be serialized to/from the filesystem
@@ -84,15 +85,15 @@ def __init__(
         cache_size: int = DEFAULT_CACHE_SIZE,
         log_level: int = logging.WARNING,
     ):
-        """Initialize the SyncClient.
+        """Initialize the FileSyncer.
 
         Parameters
         ----------
         client: Humanloop client instance
         base_dir: Base directory for synced files (default: "humanloop")
         cache_size: Maximum number of files to cache (default: DEFAULT_CACHE_SIZE)
         log_level: Log level for logging (default: WARNING)
-            Note: The SyncClient uses an isolated logger (humanloop.sdk.sync) separate from
+            Note: The FileSyncer uses an isolated logger (humanloop.sdk.file_syncer) separate from
             the main Humanloop client logger. This allows controlling the verbosity of
             sync operations independently from other client operations, which is particularly
             useful in CLI contexts where users may want detailed sync logs without affecting
@@ -102,7 +103,7 @@ def __init__(
         self.base_dir = Path(base_dir)
         self._cache_size = cache_size
 
-        # Set log level for the isolated SyncClient logger
+        # Set log level for the isolated FileSyncer logger
         logger.setLevel(log_level)
 
         # Create a new cached version of get_file_content with the specified cache size
@@ -242,8 +243,8 @@ def _pull_directory(
 
         Returns:
             Tuple of two lists:
-            - First list contains paths of successfully synced files
-            - Second list contains paths of files that failed to sync.
+            - First list contains paths of successfully pulled files
+            - Second list contains paths of files that failed to pull.
               Failures can occur due to missing content in the response or errors during local file writing.
 
         Raises:
@@ -333,8 +334,8 @@ def pull(self, path: Optional[str] = None, environment: Optional[str] = None) ->
 
         Returns:
             Tuple of two lists:
-            - First list contains paths of successfully synced files
-            - Second list contains paths of files that failed to sync (e.g. failed to write to disk or missing raw content)
+            - First list contains paths of successfully pulled files
+            - Second list contains paths of files that failed to pull (e.g. failed to write to disk or missing raw content)
 
         Raises:
             HumanloopRuntimeError: If there's an error communicating with the API