From 32b00cea4fb1982fc6cd73bf84df6436f31c5a77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E5=AE=B6=E5=90=8D?= <13774486042@163.com> Date: Sat, 14 Mar 2026 00:42:54 +0800 Subject: [PATCH] docs: improve type hints and documentation in client_wrapper (#570) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive docstrings to all API namespace classes - Add return type annotations (Any) to all methods - Add detailed Args and Returns sections to method docstrings - Improve HindsightClient class docstring with Attributes section - Add type annotations to __init__ parameters Co-authored-by: 陈家名 --- hindsight-all/hindsight/client_wrapper.py | 266 ++++++++++++++++++---- 1 file changed, 223 insertions(+), 43 deletions(-) diff --git a/hindsight-all/hindsight/client_wrapper.py b/hindsight-all/hindsight/client_wrapper.py index 865dde10..2ea05a3f 100644 --- a/hindsight-all/hindsight/client_wrapper.py +++ b/hindsight-all/hindsight/client_wrapper.py @@ -13,7 +13,10 @@ from hindsight_client import Hindsight class BanksAPI: - """Namespace for bank-related operations.""" + """Namespace for bank-related operations. + + Provides methods to create, delete, and manage memory banks. + """ def __init__(self, client: Hindsight): self._client = client @@ -24,8 +27,18 @@ class BanksAPI: name: str | None = None, mission: str | None = None, disposition: dict[str, Any] | None = None, - ): - """Create a new bank.""" + ) -> Any: + """Create a new bank. + + Args: + bank_id: Unique identifier for the bank. + name: Optional display name for the bank. + mission: Optional mission statement for the bank. + disposition: Optional disposition configuration dict. + + Returns: + Bank creation response from the API. + """ return self._client.create_bank( bank_id=bank_id, name=name, @@ -33,27 +46,57 @@ class BanksAPI: disposition=disposition, ) - def delete(self, bank_id: str): - """Delete a bank.""" + def delete(self, bank_id: str) -> Any: + """Delete a bank. + + Args: + bank_id: The ID of the bank to delete. + + Returns: + Deletion response from the API. + """ return self._client.delete_bank(bank_id=bank_id) - def set_mission(self, bank_id: str, mission: str): - """Set or update the mission for a bank.""" + def set_mission(self, bank_id: str, mission: str) -> Any: + """Set or update the mission for a bank. + + Args: + bank_id: The ID of the bank. + mission: The mission statement to set. + + Returns: + API response confirming the update. + """ return self._client.set_mission(bank_id=bank_id, mission=mission) - def set_disposition(self, bank_id: str, disposition: dict[str, Any]): - """Set or update the disposition for a bank.""" + def set_disposition(self, bank_id: str, disposition: dict[str, Any]) -> Any: + """Set or update the disposition for a bank. + + Args: + bank_id: The ID of the bank. + disposition: The disposition configuration dict. + + Returns: + API response confirming the update. + """ return self._client.set_disposition(bank_id=bank_id, disposition=disposition) - def list(self): - """List all banks.""" + def list(self) -> Any: + """List all banks. + + Returns: + List of banks from the API. + """ from hindsight_client.hindsight_client import _run_async return _run_async(self._client._banks_api.list_banks()) class MentalModelsAPI: - """Namespace for mental model operations.""" + """Namespace for mental model operations. + + Mental models are reusable knowledge structures that guide agent behavior. + """ def __init__(self, client: Hindsight): self._client = client @@ -64,8 +107,18 @@ class MentalModelsAPI: name: str, content: str, tags: list[str] | None = None, - ): - """Create a new mental model.""" + ) -> Any: + """Create a new mental model. + + Args: + bank_id: The ID of the bank to add the model to. + name: Name for the mental model. + content: The content/instructions for the mental model. + tags: Optional list of tags for categorization. + + Returns: + Creation response from the API. + """ return self._client.create_mental_model( bank_id=bank_id, name=name, @@ -73,16 +126,40 @@ class MentalModelsAPI: tags=tags, ) - def list(self, bank_id: str, tags: list[str] | None = None): - """List all mental models for a bank.""" + def list(self, bank_id: str, tags: list[str] | None = None) -> Any: + """List all mental models for a bank. + + Args: + bank_id: The ID of the bank. + tags: Optional filter by tags. + + Returns: + List of mental models. + """ return self._client.list_mental_models(bank_id=bank_id, tags=tags) - def get(self, bank_id: str, mental_model_id: str): - """Get a specific mental model.""" + def get(self, bank_id: str, mental_model_id: str) -> Any: + """Get a specific mental model. + + Args: + bank_id: The ID of the bank. + mental_model_id: The ID of the mental model. + + Returns: + The mental model details. + """ return self._client.get_mental_model(bank_id=bank_id, mental_model_id=mental_model_id) - def refresh(self, bank_id: str, mental_model_id: str): - """Refresh a mental model.""" + def refresh(self, bank_id: str, mental_model_id: str) -> Any: + """Refresh a mental model. + + Args: + bank_id: The ID of the bank. + mental_model_id: The ID of the mental model to refresh. + + Returns: + Refresh response from the API. + """ return self._client.refresh_mental_model(bank_id=bank_id, mental_model_id=mental_model_id) def update( @@ -92,8 +169,19 @@ class MentalModelsAPI: name: str | None = None, content: str | None = None, tags: list[str] | None = None, - ): - """Update a mental model.""" + ) -> Any: + """Update a mental model. + + Args: + bank_id: The ID of the bank. + mental_model_id: The ID of the mental model to update. + name: Optional new name. + content: Optional new content. + tags: Optional new tags list. + + Returns: + Update response from the API. + """ return self._client.update_mental_model( bank_id=bank_id, mental_model_id=mental_model_id, @@ -102,13 +190,24 @@ class MentalModelsAPI: tags=tags, ) - def delete(self, bank_id: str, mental_model_id: str): - """Delete a mental model.""" + def delete(self, bank_id: str, mental_model_id: str) -> Any: + """Delete a mental model. + + Args: + bank_id: The ID of the bank. + mental_model_id: The ID of the mental model to delete. + + Returns: + Deletion response from the API. + """ return self._client.delete_mental_model(bank_id=bank_id, mental_model_id=mental_model_id) class DirectivesAPI: - """Namespace for directive operations.""" + """Namespace for directive operations. + + Directives are explicit instructions that guide agent behavior. + """ def __init__(self, client: Hindsight): self._client = client @@ -119,8 +218,18 @@ class DirectivesAPI: name: str, content: str, tags: list[str] | None = None, - ): - """Create a new directive.""" + ) -> Any: + """Create a new directive. + + Args: + bank_id: The ID of the bank to add the directive to. + name: Name for the directive. + content: The directive content/instructions. + tags: Optional list of tags for categorization. + + Returns: + Creation response from the API. + """ return self._client.create_directive( bank_id=bank_id, name=name, @@ -128,12 +237,28 @@ class DirectivesAPI: tags=tags, ) - def list(self, bank_id: str, tags: list[str] | None = None): - """List all directives for a bank.""" + def list(self, bank_id: str, tags: list[str] | None = None) -> Any: + """List all directives for a bank. + + Args: + bank_id: The ID of the bank. + tags: Optional filter by tags. + + Returns: + List of directives. + """ return self._client.list_directives(bank_id=bank_id, tags=tags) - def get(self, bank_id: str, directive_id: str): - """Get a specific directive.""" + def get(self, bank_id: str, directive_id: str) -> Any: + """Get a specific directive. + + Args: + bank_id: The ID of the bank. + directive_id: The ID of the directive. + + Returns: + The directive details. + """ return self._client.get_directive(bank_id=bank_id, directive_id=directive_id) def update( @@ -143,8 +268,19 @@ class DirectivesAPI: name: str | None = None, content: str | None = None, tags: list[str] | None = None, - ): - """Update a directive.""" + ) -> Any: + """Update a directive. + + Args: + bank_id: The ID of the bank. + directive_id: The ID of the directive to update. + name: Optional new name. + content: Optional new content. + tags: Optional new tags list. + + Returns: + Update response from the API. + """ return self._client.update_directive( bank_id=bank_id, directive_id=directive_id, @@ -153,13 +289,24 @@ class DirectivesAPI: tags=tags, ) - def delete(self, bank_id: str, directive_id: str): - """Delete a directive.""" + def delete(self, bank_id: str, directive_id: str) -> Any: + """Delete a directive. + + Args: + bank_id: The ID of the bank. + directive_id: The ID of the directive to delete. + + Returns: + Deletion response from the API. + """ return self._client.delete_directive(bank_id=bank_id, directive_id=directive_id) class MemoriesAPI: - """Namespace for memory operations.""" + """Namespace for memory operations. + + Provides methods to query and retrieve stored memories. + """ def __init__(self, client: Hindsight): self._client = client @@ -171,8 +318,19 @@ class MemoriesAPI: search_query: str | None = None, limit: int = 100, offset: int = 0, - ): - """List memories in a bank.""" + ) -> Any: + """List memories in a bank. + + Args: + bank_id: The ID of the bank to query. + type: Optional filter by memory type. + search_query: Optional search query for filtering. + limit: Maximum number of results to return (default: 100). + offset: Number of results to skip for pagination (default: 0). + + Returns: + List of memories matching the criteria. + """ return self._client.list_memories( bank_id=bank_id, type=type, @@ -205,9 +363,15 @@ class HindsightClient(Hindsight): directives = client.directives.list(bank_id="test") memories = client.memories.list(bank_id="test") ``` + + Attributes: + banks: Namespace for bank management operations. + mental_models: Namespace for mental model operations. + directives: Namespace for directive operations. + memories: Namespace for memory listing operations. """ - def __init__(self, *args, **kwargs): + def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) self._banks_namespace: BanksAPI | None = None self._mental_models_namespace: MentalModelsAPI | None = None @@ -216,28 +380,44 @@ class HindsightClient(Hindsight): @property def banks(self) -> BanksAPI: - """Access bank management operations.""" + """Access bank management operations. + + Returns: + BanksAPI instance for bank operations. + """ if self._banks_namespace is None: self._banks_namespace = BanksAPI(self) return self._banks_namespace @property def mental_models(self) -> MentalModelsAPI: - """Access mental model operations.""" + """Access mental model operations. + + Returns: + MentalModelsAPI instance for mental model operations. + """ if self._mental_models_namespace is None: self._mental_models_namespace = MentalModelsAPI(self) return self._mental_models_namespace @property def directives(self) -> DirectivesAPI: - """Access directive operations.""" + """Access directive operations. + + Returns: + DirectivesAPI instance for directive operations. + """ if self._directives_namespace is None: self._directives_namespace = DirectivesAPI(self) return self._directives_namespace @property def memories(self) -> MemoriesAPI: - """Access memory listing operations.""" + """Access memory listing operations. + + Returns: + MemoriesAPI instance for memory operations. + """ if self._memories_namespace is None: self._memories_namespace = MemoriesAPI(self) return self._memories_namespace