Add header to Codex API requests for capturing product analytics data (#53)

* pass metadata in header for codex API requests to indicate integration type

* hatch fmt

* small fixes

* ignore type check in test

* include cleanlab-codex version in headers for codex backend requests

* update client lib version

* respond to PR feedback

* add instructions to DEVELOPMENT for how to build and install the package locally

* small changes re: angela's feedback

* amend changelog

Author: kelsey-wong

CHANGELOG.md

@@ -7,8 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.2] - 2025-03-07
+
 - Extract scores and metadata from detection functions in `response_validation.py`.
 - Normalize scores used by `is_fallback_response` function to be between 0 and 1.
+- Pass metadata in headers for query requests.
 
 ## [1.0.1] - 2025-02-26
 
@@ -18,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release of the `cleanlab-codex` client library.
 
-[Unreleased]: https://github.com/cleanlab/cleanlab-codex/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/cleanlab/cleanlab-codex/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/cleanlab/cleanlab-codex/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/cleanlab/cleanlab-codex/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/cleanlab/cleanlab-codex/compare/267a93300f77c94e215d7697223931e7926cad9e...v1.0.0

DEVELOPMENT.md

@@ -90,6 +90,15 @@ Automated releases are handled by the [release workflow][release-workflow] which
 [hatch-version]: https://hatch.pypa.io/latest/version/#updating
 [changelog]: CHANGELOG.md
 
+
+### How to build and install the package locally
+
+You may want to build and install the package locally - for example, to see how your changes affect other Python code in a script or Jupyter notebook.
+
+To do this, you can build the package with `hatch build` and then install it in your local environment with `pip install dist/cleanlab_codex-<version>-py3-none-any.whl`.
+
+Alternatively, you can use `pip install -e /path/to/cleanlab-codex` to install the package from your local code. Note that if you make further local changes after that, you may need to reload the module, i.e. `reload(cleanlab_codex)`, or restart the kernel.
+
 ## Continuous integration
 
 Testing, type checking, and formatting/linting is [checked in CI][ci].

src/cleanlab_codex/__about__.py

@@ -1,2 +1,2 @@
 # SPDX-License-Identifier: MIT
-__version__ = "1.0.1"
+__version__ = "1.0.2"

src/cleanlab_codex/codex_tool.py

@@ -6,6 +6,7 @@
 
 from typing_extensions import Annotated
 
+from cleanlab_codex.internal.analytics import IntegrationType, _AnalyticsMetadata
 from cleanlab_codex.project import Project
 from cleanlab_codex.utils.errors import MissingDependencyError
 from cleanlab_codex.utils.function import (
@@ -110,7 +111,11 @@ def query(
         Returns:
             The answer to the question if available. If no answer is available, this returns a fallback answer or None.
         """
-        return self._project.query(question, fallback_answer=self._fallback_answer)[0]
+        return self._project.query(
+            question=question,
+            fallback_answer=self._fallback_answer,
+            analytics_metadata=_AnalyticsMetadata(integration_type=IntegrationType.TOOL),
+        )[0]
 
     def to_openai_tool(self) -> dict[str, Any]:
         """Converts the tool to the expected format for an [OpenAI function tool](https://platform.openai.com/docs/guides/function-calling).

src/cleanlab_codex/internal/analytics.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from enum import Enum
+
+from cleanlab_codex.__about__ import __version__ as package_version
+
+
+class IntegrationType(str, Enum):
+    """Supported methods for integrating Codex into a RAG system using this library."""
+
+    BACKUP = "backup"
+    TOOL = "tool"
+
+
+class _AnalyticsMetadata:
+    def __init__(self, *, integration_type: IntegrationType):
+        self._integration_type = integration_type
+        self._package_version = package_version
+        self._source = "cleanlab-codex-python"
+
+    def to_headers(self) -> dict[str, str]:
+        return {
+            "X-Integration-Type": self._integration_type,
+            "X-Client-Library-Version": self._package_version,
+            "X-Source": self._source,
+        }

src/cleanlab_codex/internal/project.py

@@ -8,16 +8,17 @@
 
 from codex import AuthenticationError
 
-from cleanlab_codex.internal.project import query_project
+from cleanlab_codex.internal.analytics import IntegrationType, _AnalyticsMetadata
 from cleanlab_codex.internal.sdk_client import client_from_access_key
+from cleanlab_codex.types.entry import Entry
 from cleanlab_codex.types.project import ProjectConfig
 
 if _TYPE_CHECKING:
     from datetime import datetime
 
     from codex import Codex as _Codex
 
-    from cleanlab_codex.types.entry import Entry, EntryCreate
+    from cleanlab_codex.types.entry import EntryCreate
 
 _ERROR_CREATE_ACCESS_KEY = (
     "Failed to create access key. Please ensure you have the necessary permissions "
@@ -159,6 +160,7 @@ def query(
         *,
         fallback_answer: Optional[str] = None,
         read_only: bool = False,
+        analytics_metadata: Optional[_AnalyticsMetadata] = None,
     ) -> tuple[Optional[str], Optional[Entry]]:
         """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.
 
@@ -173,10 +175,38 @@ def query(
                 If Codex is able to answer the question, the first element will be the answer returned by Codex and the second element will be the existing [`Entry`](/codex/api/python/types.entry#class-entry) in the Codex project.
                 If Codex is unable to answer the question, the first element will be `fallback_answer` if provided, otherwise None. The second element will be a new [`Entry`](/codex/api/python/types.entry#class-entry) in the Codex project.
         """
-        return query_project(
-            client=self._sdk_client,
+        if not analytics_metadata:
+            analytics_metadata = _AnalyticsMetadata(integration_type=IntegrationType.BACKUP)
+
+        return self._query_project(
             question=question,
-            project_id=self.id,
             fallback_answer=fallback_answer,
             read_only=read_only,
+            analytics_metadata=analytics_metadata,
         )
+
+    def _query_project(
+        self,
+        question: str,
+        *,
+        fallback_answer: Optional[str] = None,
+        read_only: bool = False,
+        analytics_metadata: Optional[_AnalyticsMetadata] = None,
+    ) -> tuple[Optional[str], Optional[Entry]]:
+        extra_headers = analytics_metadata.to_headers() if analytics_metadata else None
+        maybe_entry = self._sdk_client.projects.entries.query(self._id, question=question, extra_headers=extra_headers)
+
+        if maybe_entry is not None:
+            entry = Entry.model_validate(maybe_entry.model_dump())
+            if entry.answer is not None:
+                return entry.answer, entry
+
+            return fallback_answer, entry
+
+        if not read_only:
+            created_entry = Entry.model_validate(
+                self._sdk_client.projects.entries.add_question(self._id, question=question).model_dump()
+            )
+            return fallback_answer, created_entry
+
+        return fallback_answer, None

src/cleanlab_codex/project.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import pytest
+
+from cleanlab_codex.__about__ import __version__ as package_version
+from cleanlab_codex.internal.analytics import IntegrationType, _AnalyticsMetadata
+
+
+def test_analytics_metadata_to_headers_uses_defaults() -> None:
+    metadata = _AnalyticsMetadata(integration_type=IntegrationType.BACKUP)
+
+    assert metadata.to_headers() == {
+        "X-Integration-Type": IntegrationType.BACKUP,
+        "X-Source": "cleanlab-codex-python",
+        "X-Client-Library-Version": package_version,
+    }
+
+
+def test_analytics_metadata_requires_integration_type() -> None:
+    with pytest.raises(TypeError):
+        _AnalyticsMetadata()  # type: ignore[call-arg]