Skip to content

[OPIK-6268] [PY-SDK] feat: add environment support#6622

Draft
petrotiurin wants to merge 6 commits intoboryst/OPIK-6265-be-add-environments-to-spans-traces-threadsfrom
petrot/add-envs
Draft

[OPIK-6268] [PY-SDK] feat: add environment support#6622
petrotiurin wants to merge 6 commits intoboryst/OPIK-6265-be-add-environments-to-spans-traces-threadsfrom
petrot/add-envs

Conversation

@petrotiurin
Copy link
Copy Markdown
Contributor

@petrotiurin petrotiurin commented May 6, 2026 •
edited by atlassian Bot
Loading

Summary

  • Adds environment to the Opik Python SDK so traces/spans can be tagged with a lifecycle stage (e.g. development/staging/production).
  • Resolution priority: per-call argument > Opik(environment=...) constructor > OPIK_ENVIRONMENT env var > None. No new field in OpikConfig, no ~/.opik.config persistence.
  • Opik.trace, Opik.span, @track, plus search helpers (search_traces/search_spans/search_threads) all accept environment=....
  • Environment CRUD on Opik: create_environment, get_environment, get_environments, update_environment, delete_environment. Public opik.Environment re-export.
  • TypeScript SDK and opik configure CLI changes are intentionally out of scope.

Jira: OPIK-6268

Test plan

  • Unit tests: tests/unit/api_objects/test_environment.py (10 tests) — resolution priority, payload propagation, @track(environment=...) flow, backwards-compat defaults.
  • E2E tests: tests/e2e/test_environment.py (5 tests) — CRUD round-trip, search_traces(environment=...), search_spans(environment=...), constructor-set env, no-env back-compat. All pass against the local backend.
  • Full unit + message_processing suite green (3165 passed).
  • CI green.

🤖 Generated with Claude Code

@petrotiurin @claude
[OPIK-6268] [PY-SDK] feat: add environment support
95189c1 
Adds environment to the Python SDK so traces/spans can be tagged with a
lifecycle stage (e.g. development/staging/production) and the
per-workspace set of environments can be managed programmatically.

- Opik(environment=...) constructor; falls back to OPIK_ENVIRONMENT env
  var. Resolution priority: per-call > client > env var > None.
- Opik.trace(...), Opik.span(...), @track(environment=...) flow through
  TraceData/SpanData into CreateTraceMessage/CreateSpanMessage payloads.
- search_traces, search_spans, search_threads accept environment=... and
  inject an OQL filter on the environment field.
- CRUD: create_environment, get_environment, get_environments,
  update_environment, delete_environment on Opik. Public opik.Environment
  re-export.
- TS SDK and `opik configure` CLI changes are out of scope here.

Tests: 10 new unit tests for resolution priority, payload propagation,
@track, and back-compat. 5 new e2e tests for CRUD round-trip and
search-by-environment against a local backend.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@github-actions github-actions Bot added python Pull requests that update Python code tests Including test files, or tests related like configuration. Python SDK labels May 6, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 6, 2026

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Details section.

❌ Missing Section. The description is missing the ## Change checklist section.

❌ Missing Section. The description is missing the ## Issues section.

❌ Missing Section. The description is missing the ## Testing section.

❌ Missing Section. The description is missing the ## Documentation section.

@petrotiurin @claude
refactor(env): make environment CRUD name-based, drop id from public API
2694ad3 
ID is not user-facing for environments — drop get_environment(id), and
identify environments by name in update/delete:
- update_environment(name, description=None, color=None)
- delete_environment(name)  — no-op when name doesn't exist

create_environment still returns the created Environment (looked up
internally by id after create).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 6, 2026

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Details section.

❌ Missing Section. The description is missing the ## Change checklist section.

❌ Missing Section. The description is missing the ## Issues section.

❌ Missing Section. The description is missing the ## Testing section.

❌ Missing Section. The description is missing the ## Documentation section.

@petrotiurin @claude
test(e2e): assert environment in verify_trace, clean up envs across t…
bb85fbe 
…ests

- Extend verify_trace with optional environment kwarg, checked only when
  the caller supplies it (mirrors the project_name pattern).
- Add a created_envs fixture that records env names per test and deletes
  them on teardown — environments are workspace-capped (default 20), so
  leaked envs from earlier runs caused conflict errors.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 6, 2026

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Details section.

❌ Missing Section. The description is missing the ## Change checklist section.

❌ Missing Section. The description is missing the ## Issues section.

❌ Missing Section. The description is missing the ## Testing section.

❌ Missing Section. The description is missing the ## Documentation section.

@petrotiurin @claude
test(e2e): drop search assertions, lean on verifiers for env checks
4670554 
verify_trace and verify_span now both check the persisted environment,
which makes the search-by-environment assertions in the e2e tests
redundant — those filter behaviors are exercised by other suites and
unit-level coverage. Restructure the env e2e file accordingly:

- Add environment kwarg to verify_span (mirrors verify_trace).
- Replace the inline created_envs fixture with an environment_name
  fixture in e2e/conftest.py, mirroring temporary_project_name (yields a
  unique name, best-effort delete on teardown).
- Tests now log a trace/span with environment=, then rely on
  verify_trace/verify_span to confirm persistence — no second round-trip
  through search_traces / search_spans.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 6, 2026

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Details section.

❌ Missing Section. The description is missing the ## Change checklist section.

❌ Missing Section. The description is missing the ## Issues section.

❌ Missing Section. The description is missing the ## Testing section.

❌ Missing Section. The description is missing the ## Documentation section.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 6, 2026

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Details section.

❌ Missing Section. The description is missing the ## Change checklist section.

❌ Missing Section. The description is missing the ## Issues section.

❌ Missing Section. The description is missing the ## Testing section.

❌ Missing Section. The description is missing the ## Documentation section.

@petrotiurin @claude
feat(env): nested span inherits trace environment, ignores per-call o…
6bfd29f 
…verride

Once a trace has been opened with an environment, an inner @track or
context-attached span can no longer override that environment. The
parent trace's (or parent span's) environment wins, and the inner
span's per-call environment kwarg is ignored.

- span_creation_handler.create_span_respecting_context: when a parent
  span or trace is in context with environment set, copy that env onto
  start_span_arguments before building the child span.
- Three new unit tests in test_span_creation_handler covering both
  parent-trace and parent-span branches plus the no-trace-env passthrough.
- e2e test_span__... renamed/rewritten to exercise this rule via @track
  outer/inner pattern (replaces the prior plain-persistence test, which
  was strictly weaker).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 6, 2026

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Details section.

❌ Missing Section. The description is missing the ## Change checklist section.

❌ Missing Section. The description is missing the ## Issues section.

❌ Missing Section. The description is missing the ## Testing section.

❌ Missing Section. The description is missing the ## Documentation section.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@petrotiurin petrotiurin

Labels

Python SDK python Pull requests that update Python code tests Including test files, or tests related like configuration.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@petrotiurin