From 32d8f631cb96af8fe5170690b08fa0ed5f8b4958 Mon Sep 17 00:00:00 2001 From: Kelsey Wong Date: Fri, 14 Feb 2025 15:27:46 -0800 Subject: [PATCH 1/5] update comments and types for generating python API reference --- src/cleanlab_codex/codex_tool.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/cleanlab_codex/codex_tool.py b/src/cleanlab_codex/codex_tool.py index 1e4e87c..c902c63 100644 --- a/src/cleanlab_codex/codex_tool.py +++ b/src/cleanlab_codex/codex_tool.py @@ -27,6 +27,12 @@ def __init__( *, fallback_answer: Optional[str] = DEFAULT_FALLBACK_ANSWER, ): + """Initialize a CodexTool. + + Args: + project (Project): The Codex project to use for this tool. + fallback_answer (str, optional): The fallback answer to use if the Codex project cannot answer the question. A default will be used if not provided. + """ self._project = project self._fallback_answer = fallback_answer self._tool_function_schema = pydantic_model_from_function(self._tool_name, self.query) @@ -40,7 +46,7 @@ def from_access_key( *, fallback_answer: Optional[str] = DEFAULT_FALLBACK_ANSWER, ) -> CodexTool: - """Creates a CodexTool from an access key. The CodexTool will use the project ID associated with the access key provided. + """Creates a CodexTool from an access key. The CodexTool will use the project associated with the access key provided. Args: access_key (str): The access key for the Codex project. @@ -89,13 +95,7 @@ def fallback_answer(self, value: Optional[str]) -> None: """Sets the fallback answer to use if the Codex project cannot answer the question.""" self._fallback_answer = value - def query( - self, - question: Annotated[ - str, - "The query to search in the database. It should match the original user query unless clarification is needed (for instance to account for prior user messages), in which case changes to the query should be minimal.", - ], - ) -> Optional[str]: + def query(self, question: str) -> Optional[str]: """Consults a database that contains answers to any possible question. If the answer is not available, this returns None. Args: From 8af1355d36b140f22bdddc3597a563a8f50264e4 Mon Sep 17 00:00:00 2001 From: Kelsey Wong Date: Fri, 14 Feb 2025 16:04:47 -0800 Subject: [PATCH 2/5] more updates --- src/cleanlab_codex/codex_tool.py | 12 ++++++++---- src/cleanlab_codex/project.py | 30 +++++++++++++++--------------- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/src/cleanlab_codex/codex_tool.py b/src/cleanlab_codex/codex_tool.py index c902c63..13f613b 100644 --- a/src/cleanlab_codex/codex_tool.py +++ b/src/cleanlab_codex/codex_tool.py @@ -2,9 +2,7 @@ from __future__ import annotations -from typing import Any, Optional - -from typing_extensions import Annotated +from typing_extensions import Annotated, Any, Optional from cleanlab_codex.project import Project from cleanlab_codex.utils.errors import MissingDependencyError @@ -95,7 +93,13 @@ def fallback_answer(self, value: Optional[str]) -> None: """Sets the fallback answer to use if the Codex project cannot answer the question.""" self._fallback_answer = value - def query(self, question: str) -> Optional[str]: + def query( + self, + question: Annotated[ + str, + "The query to search in the database. It should match the original user query unless clarification is needed (for instance to account for prior user messages), in which case changes to the query should be minimal.", + ], + ) -> Optional[str]: """Consults a database that contains answers to any possible question. If the answer is not available, this returns None. Args: diff --git a/src/cleanlab_codex/project.py b/src/cleanlab_codex/project.py index 52174be..dbc49f0 100644 --- a/src/cleanlab_codex/project.py +++ b/src/cleanlab_codex/project.py @@ -33,7 +33,7 @@ class MissingProjectError(Exception): - """Raised when the project ID does not match any existing project.""" + """Raised when the project ID or access key does not match any existing project.""" def __str__(self) -> str: return "valid project ID or access key is required to authenticate access" @@ -52,9 +52,9 @@ def __init__(self, sdk_client: _Codex, project_id: str, *, verify_existence: boo [`Client.create_project()`](/reference/python/client#method-create_project), or [`Project.from_access_key()`](/reference/python/project#classmethod-from_access_key) methods. Args: - sdk_client (_Codex): The Codex SDK client to use to interact with the project. - project_id (str): The ID of the project. - verify_existence (bool, optional): Whether to verify that the project exists. + sdk_client (`Codex`): The Codex SDK client to use to interact with the project. + project_id (`str`): The ID of the project. + verify_existence (`bool`, optional): Whether to verify that the project exists. """ self._sdk_client = sdk_client self._id = project_id @@ -73,7 +73,7 @@ def from_access_key(cls, access_key: str) -> Project: """Initialize a Project from a [project-level access key](/codex/sme_tutorials/getting_started/#access-keys). Args: - access_key (str): The access key for authenticating project access. + access_key (`str`): The access key for authenticating project access. Returns: Project: The project associated with the access key. @@ -92,10 +92,10 @@ def create(cls, sdk_client: _Codex, organization_id: str, name: str, description """Create a new Codex project. This method is not meant to be used directly. Instead, use the [`create_project`](/reference/python/client#method-create_project) method on the `Client` class. Args: - sdk_client (_Codex): The Codex SDK client to use to create the project. This client must be authenticated with a user-level API key. - organization_id (str): The ID of the organization to create the project in. - name (str): The name of the project. - description (:obj:`str`, optional): The description of the project. + sdk_client (`Codex`): The Codex SDK client to use to create the project. This client must be authenticated with a user-level API key. + organization_id (`str`): The ID of the organization to create the project in. + name (`str`): The name of the project. + description (`str`, optional): The description of the project. Returns: Project: The created project. @@ -117,9 +117,9 @@ def create_access_key(self, name: str, description: str | None = None, expiratio See [`Client.create_project()`](/reference/python/client#method-create_project) or [`Client.get_project()`](/reference/python/client#method-get_project). Args: - name (str): The name of the access key. - description (:obj:`str`, optional): The description of the access key. - expiration (:obj:`datetime`, optional): The expiration date of the access key. If not provided, the access key will not expire. + name (`str`): The name of the access key. + description (`str`, optional): The description of the access key. + expiration (`datetime`, optional): The expiration date of the access key. If not provided, the access key will not expire. Returns: str: The access key token. @@ -163,9 +163,9 @@ def query( """Query Codex to check if this project contains an answer to the question. Add the question to the project for SME review if it does not. Args: - question (str): The question to ask the Codex API. - fallback_answer (str, optional): Optional fallback answer to return if Codex is unable to answer the question. - read_only (bool, optional): Whether to query the Codex API in read-only mode. If True, the question will not be added to the Codex project for SME review. + question (`str`): The question to ask the Codex API. + fallback_answer (`str`, optional): Optional fallback answer to return if Codex is unable to answer the question. + read_only (`bool`, optional): Whether to query the Codex API in read-only mode. If True, the question will not be added to the Codex project for SME review. This can be useful for testing purposes when setting up your project configuration. Returns: From 0a118607abb11c59f554fc2efe4afee1ad4151cc Mon Sep 17 00:00:00 2001 From: Kelsey Wong Date: Fri, 14 Feb 2025 16:13:50 -0800 Subject: [PATCH 3/5] fix imports --- src/cleanlab_codex/codex_tool.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/cleanlab_codex/codex_tool.py b/src/cleanlab_codex/codex_tool.py index 13f613b..442b8ff 100644 --- a/src/cleanlab_codex/codex_tool.py +++ b/src/cleanlab_codex/codex_tool.py @@ -2,7 +2,9 @@ from __future__ import annotations -from typing_extensions import Annotated, Any, Optional +from typing import Any, Optional + +from typing_extensions import Annotated from cleanlab_codex.project import Project from cleanlab_codex.utils.errors import MissingDependencyError From 3d30cf273213c48cb922ece5f48d7bb7e3521fab Mon Sep 17 00:00:00 2001 From: Kelsey Wong Date: Fri, 14 Feb 2025 16:32:24 -0800 Subject: [PATCH 4/5] bump version --- CHANGELOG.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee39fc6..1de2331 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.1a7] - 2025-02-15 + +### Changed + +- Added and edited docstrings to make the auto-generated API reference more clear. + ## [0.0.1a6] - 2025-02-14 ### Changed @@ -50,7 +56,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Pre-release of the Cleanlab Codex Python client. -[Unreleased]: https://github.com/cleanlab/cleanlab-codex/compare/v0.0.1a6...HEAD +[Unreleased]: https://github.com/cleanlab/cleanlab-codex/compare/v0.0.1a7...HEAD +[0.0.1a7]: https://github.com/cleanlab/cleanlab-codex/compare/v0.0.1a6...v0.0.1a7 [0.0.1a6]: https://github.com/cleanlab/cleanlab-codex/compare/v0.0.1a5...v0.0.1a6 [0.0.1a5]: https://github.com/cleanlab/cleanlab-codex/compare/v0.0.1a4...v0.0.1a5 [0.0.1a4]: https://github.com/cleanlab/cleanlab-codex/compare/v0.0.1a3...v0.0.1a4 From f634d1ab026d1f3525f24df726932b093730f639 Mon Sep 17 00:00:00 2001 From: Kelsey Wong Date: Tue, 18 Feb 2025 13:12:16 -0800 Subject: [PATCH 5/5] remove backticks around arg types --- src/cleanlab_codex/__about__.py | 2 +- src/cleanlab_codex/project.py | 28 ++++++++++++++-------------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/cleanlab_codex/__about__.py b/src/cleanlab_codex/__about__.py index 90dac42..259fd7a 100644 --- a/src/cleanlab_codex/__about__.py +++ b/src/cleanlab_codex/__about__.py @@ -1,2 +1,2 @@ # SPDX-License-Identifier: MIT -__version__ = "0.0.1a6" +__version__ = "0.0.1a7" diff --git a/src/cleanlab_codex/project.py b/src/cleanlab_codex/project.py index dbc49f0..07548cd 100644 --- a/src/cleanlab_codex/project.py +++ b/src/cleanlab_codex/project.py @@ -52,9 +52,9 @@ def __init__(self, sdk_client: _Codex, project_id: str, *, verify_existence: boo [`Client.create_project()`](/reference/python/client#method-create_project), or [`Project.from_access_key()`](/reference/python/project#classmethod-from_access_key) methods. Args: - sdk_client (`Codex`): The Codex SDK client to use to interact with the project. - project_id (`str`): The ID of the project. - verify_existence (`bool`, optional): Whether to verify that the project exists. + sdk_client (Codex): The Codex SDK client to use to interact with the project. + project_id (str): The ID of the project. + verify_existence (bool, optional): Whether to verify that the project exists. """ self._sdk_client = sdk_client self._id = project_id @@ -73,7 +73,7 @@ def from_access_key(cls, access_key: str) -> Project: """Initialize a Project from a [project-level access key](/codex/sme_tutorials/getting_started/#access-keys). Args: - access_key (`str`): The access key for authenticating project access. + access_key (str): The access key for authenticating project access. Returns: Project: The project associated with the access key. @@ -92,10 +92,10 @@ def create(cls, sdk_client: _Codex, organization_id: str, name: str, description """Create a new Codex project. This method is not meant to be used directly. Instead, use the [`create_project`](/reference/python/client#method-create_project) method on the `Client` class. Args: - sdk_client (`Codex`): The Codex SDK client to use to create the project. This client must be authenticated with a user-level API key. - organization_id (`str`): The ID of the organization to create the project in. - name (`str`): The name of the project. - description (`str`, optional): The description of the project. + sdk_client (Codex): The Codex SDK client to use to create the project. This client must be authenticated with a user-level API key. + organization_id (str): The ID of the organization to create the project in. + name (str): The name of the project. + description (str, optional): The description of the project. Returns: Project: The created project. @@ -117,9 +117,9 @@ def create_access_key(self, name: str, description: str | None = None, expiratio See [`Client.create_project()`](/reference/python/client#method-create_project) or [`Client.get_project()`](/reference/python/client#method-get_project). Args: - name (`str`): The name of the access key. - description (`str`, optional): The description of the access key. - expiration (`datetime`, optional): The expiration date of the access key. If not provided, the access key will not expire. + name (str): The name of the access key. + description (str, optional): The description of the access key. + expiration (datetime, optional): The expiration date of the access key. If not provided, the access key will not expire. Returns: str: The access key token. @@ -163,9 +163,9 @@ def query( """Query Codex to check if this project contains an answer to the question. Add the question to the project for SME review if it does not. Args: - question (`str`): The question to ask the Codex API. - fallback_answer (`str`, optional): Optional fallback answer to return if Codex is unable to answer the question. - read_only (`bool`, optional): Whether to query the Codex API in read-only mode. If True, the question will not be added to the Codex project for SME review. + question (str): The question to ask the Codex API. + fallback_answer (str, optional): Optional fallback answer to return if Codex is unable to answer the question. + read_only (bool, optional): Whether to query the Codex API in read-only mode. If True, the question will not be added to the Codex project for SME review. This can be useful for testing purposes when setting up your project configuration. Returns: