[OPIK-5152] [SDK] feat: promote search_threads to Opik client API#5739
Open
alexkuzmik wants to merge 5 commits intomainfrom
Open
[OPIK-5152] [SDK] feat: promote search_threads to Opik client API#5739alexkuzmik wants to merge 5 commits intomainfrom
alexkuzmik wants to merge 5 commits intomainfrom
Conversation
Co-Authored-By: Claude Opus 4.6 <[email protected]>
github-actions
bot
added
documentation
Contributor
📋 PR Linter Failed❌ Missing Section. The description is missing the ❌ Missing Section. The description is missing the ❌ Missing Section. The description is missing the ❌ Missing Section. The description is missing the ❌ Missing Section. The description is missing the |
Contributor
Python SDK Unit Tests Results (Python 3.13)2 254 tests +31 2 254 ✅ +31 47s ⏱️ +3s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 3 and adds 34 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
Contributor
Python SDK Unit Tests Results (Python 3.11)2 254 tests +31 2 254 ✅ +31 45s ⏱️ -2s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 3 and adds 34 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
Contributor
Python SDK Unit Tests Results (Python 3.12)2 254 tests +31 2 254 ✅ +31 45s ⏱️ -1s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 3 and adds 34 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
Contributor
Python SDK Unit Tests Results (Python 3.14)2 254 tests +31 2 254 ✅ +31 35s ⏱️ -3s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 3 and adds 34 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
Contributor
Python SDK Unit Tests Results (Python 3.10)2 254 tests +31 2 254 ✅ +31 45s ⏱️ ±0s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 3 and adds 34 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
Contributor
|
🌿 Preview your docs: https://opik-preview-27ed2f59-83c2-4f66-a6a5-bde7eda5d75d.docs.buildwithfern.com/docs/opik No broken links found 📌 Results for commit 1ccdaa3 |
Co-Authored-By: Claude Opus 4.6 <[email protected]>
github-actions
bot
added
the
tests
![baz-reviewer[bot]](https://avatars.githubusercontent.com/in/933528?s=60&v=4){kind=small}
Comment on lines
+69
to
+70
| from ..rest_api import client as rest_api_client | ||
| from ..rest_api import TraceThread |
Contributor
There was a problem hiding this comment.
TraceThread is imported via from ..rest_api import TraceThread despite sdks/python/AGENTS.md preferring module-style imports — should we from .. import rest_api and use rest_api.TraceThread?
Finding type: AI Coding Guidelines | Severity: 🟢 Low
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents:
In sdks/python/src/opik/api_objects/opik_client.py around lines 69 to 70, the new code
uses a single-name import `from ..rest_api import TraceThread`, and the `search_threads`
method return annotation and docstrings reference `TraceThread`. Replace the single-name
import with a module-style import (e.g., `from .. import rest_api`) and update the
`search_threads` signature and any other usages to refer to `rest_api.TraceThread`
instead of `TraceThread`. Ensure any type imports list remains correct and run type
checks to confirm no unresolved references remain.
Contributor
Python SDK E2E Tests Results (Python 3.14)246 tests ±0 244 ✅ ±0 8m 16s ⏱️ -35s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 1 and adds 1 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
Contributor
Python SDK E2E Tests Results (Python 3.11)246 tests ±0 244 ✅ ±0 8m 17s ⏱️ -16s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 1 and adds 1 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
Contributor
Python SDK E2E Tests Results (Python 3.13)246 tests ±0 244 ✅ +2 8m 49s ⏱️ -55s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 1 and adds 1 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
Contributor
Python SDK E2E Tests Results (Python 3.10)246 tests ±0 244 ✅ ±0 9m 12s ⏱️ +24s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 1 and adds 1 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
- Address PR review: use trace_thread.TraceThread instead of bare import - Extract OQL filter reference into shared section for traces/spans/threads - Simplify search_threads docstring to reference search_traces for full filter details Co-Authored-By: Claude Opus 4.6 <[email protected]>
Contributor
Python SDK E2E Tests Results (Python 3.12)246 tests ±0 244 ✅ ±0 9m 16s ⏱️ +29s Results for commit 2b9a90f. ± Comparison against base commit 0ef43e6. This pull request removes 1 and adds 1 tests. Note that renamed tests count towards both.♻️ This comment has been updated with latest results. |
The previous docstrings and docs incorrectly listed trace columns (name, input, output, metadata, usage.*, model, provider, etc.) as available for thread filtering. Threads actually support a narrower set: id, first_message, last_message, status, duration, number_of_messages, feedback_scores, tags, and date fields. Split the shared OQL reference table into per-entity tables (trace, span, thread) so users see only the columns that actually work. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Comment on lines
174
to
185
| <Tabs> | ||
| <Tab value="Python" title="Python"> | ||
| ```python | ||
| import opik | ||
|
|
||
| client = opik.Opik( | ||
| project_name="Default project" | ||
| ) | ||
|
|
||
| # Search for traces where the input contains text | ||
| traces = client.search_traces( | ||
| filter_string='input contains "Opik"' | ||
| ) | ||
| client = opik.Opik(project_name="Default project") | ||
|
|
||
| # Search for traces that were logged after a specific date | ||
| # Trace filters | ||
| traces = client.search_traces(filter_string='input contains "Opik"') | ||
| traces = client.search_traces(filter_string='start_time >= "2024-01-01T00:00:00Z"') | ||
|
|
||
| # Search for traces that have a specific tag | ||
| traces = client.search_traces(filter_string='tags contains "production"') | ||
|
|
||
| # Search for traces based on the number of tokens used | ||
| traces = client.search_traces(filter_string='usage.total_tokens > 1000') | ||
|
|
||
| # Search for traces based on the model used | ||
| traces = client.search_traces(filter_string='metadata.model = "gpt-4o"') |
Contributor
There was a problem hiding this comment.
search_traces/search_threads snippets lack the required one-line intent, inline comments describing the observable behavior of each filter, and a maintenance note pointing to the canonical/generated example; should we prepend an intent sentence, add inline behavior comments, and include the maintenance-note referencing the generated source before keeping the hand-pasted snippet?
Finding type: Keep docs accurate | Severity: 🟢 Low
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents:
In apps/opik-documentation/documentation/fern/docs/tracing/export_data.mdx around lines
174 to 208, the Python and TypeScript examples for search_traces/search_threads are
missing the required metadata and comments. Prepend each language example with a
single-sentence intent describing what the snippet demonstrates (e.g., “Example: show
filtering traces by start_time, usage, metadata, tags, and feedback presence.”). For
every filter call inside the Python and TypeScript code blocks, add an inline comment on
the same line explaining what observable behavior or trigger the filter demonstrates
(e.g., “# finds traces created after 2024-01-01” or “// finds traces with
production tag”). Finally, add a short maintenance note directly after each code block
that references the canonical/generated example source (include the repository path or
URL, the update cadence, and the owning team), e.g. “Maintenance: canonical snippet
generated from <repo/path-or-URL>, regenerated daily, owned by <team-name>.” Make
these edits so the examples meet the documentation reviewer's requirements for intent,
observability comments, and maintenance provenance.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Details
Promote
search_threadsfromThreadsClientto the first-classOpikclient API, making threads search discoverable without needingget_threads_client(). Also updates the export data documentation to cover threads alongside traces and spans.Change checklist
Issues
AI-WATERMARK
AI-WATERMARK: yes
Testing
cd sdks/python && python -c "from opik.api_objects.opik_client import Opik; print('Import OK')"ThreadsClient.search_threads()logic (tests/e2e/test_threads.py)Opik.search_threads()is a thin delegation wrapper, same pattern asOpik.log_threads_feedback_scores()Documentation
apps/opik-documentation/documentation/fern/docs/tracing/export_data.mdxwith a new "Exporting threads" section including examples for filtering by ID, message count, feedback scores, and tags