feat(util-genai): refactor and make API smaller and more user-friendly by lmolkova · Pull Request #4391 · open-telemetry/opentelemetry-python-contrib

lmolkova · 2026-04-03T02:00:06Z

Replaces the handler.start_llm(invocation) / handler.stop_llm(invocation) pattern with factory methods that construct and start spans in one call, and moves lifecycle ownership onto the invocation object. Existing code continues to work — LLMInvocation, stop_llm, and fail_llm are kept with @deprecated markers.

Before

inv = LLMInvocation(provider="openai", request_model="gpt-4o")
# inv is in invalid state now
handler.start_llm(inv)
try:
    inv.output_messages = [...]
    # need to carry both - handler and inv to here
    handler.stop_llm(inv)
except Exception as exc:
   # why not just pass exc ?
    handler.fail_llm(inv, Error(type=type(exc), message=str(exc)))

After

inv = handler.start_inference("openai", "gpt-4o")
# valid state right away
try:
    inv.output_messages = [...]
    # no need to pass handler here if happens in a different method
    inv.stop()
except Exception as exc:
    # much shorter
    inv.fail(exc); 
    raise

with handler.inference("openai", "gpt-4o") as inv:
    inv.output_messages = [...]

MikeGoldsmith

Looks good to me. I've left one small suggestion for separating invocation types file, but not blocking.

I see you have a few TODOs you'd like to probably resolve before merging too.

lmolkova · 2026-04-03T16:06:21Z

@MikeGoldsmith and @DylanRussell thanks for the review!

The todos are the existing ones - it's easy to a address them but I didn't want to include any new features into this pure refactoring PR.

lmolkova · 2026-04-07T01:15:11Z

/cc @Cirilla-zmh

MikeGoldsmith

Still looks good but has some conflicts that need resolving first.

@deprecated

open-telemetry#4391) * Refactor public API on GenAI utils * more lint * review feedback * update tests to use named params * address some of the comments * up * fix failing checks and clean up imports * lint * lint * fix lint * replace @deprecated with docstring info to avoid warnings for users * up * common code for context manager

@deprecated

* linting fix * Updating changelog * Updating changelog PR number * Removing embedding events emission * Refatoring and adding input token metric for Embedding invocation * Merging and removing unused import * build(deps): bump aiohttp from 3.13.3 to 3.13.4 (#4386) --- updated-dependencies: - dependency-name: aiohttp dependency-version: 3.13.4 dependency-type: direct:production ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Revert "Build list of required jobs in generate-workflow (#4326)" (#4413) This reverts commit 22879d6. Now that we have just one job to check we don't need to build the list anymore. * Drop Python 3.9 support (#4412) * Drop Python 3.9 support Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * generate-workflows Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * fixes Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * remove extra reference to pypy310 Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * changelog Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * fix flask tests Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * fix google-genai tests Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * fix google-genai tests Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * fix Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> * remove unused _ensure_gzip_single_response Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> --------- Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> Co-authored-by: Riccardo Magliocchetti <riccardo.magliocchetti@gmail.com> * Add AGENTS.md with project structure and commands (#4233) * Add CLAUDE.md with project structure and commands * Add AGENTS.md symlink to CLAUDE.md * Move guidance to AGENTS.md and address review feedback - Move main content from CLAUDE.md to AGENTS.md so all AI agents (not only Claude) pick up the guidance; CLAUDE.md now just references it via `@AGENTS.md`. - Add general rules, PR scoping, and `Assisted-by:` commit trailer guidance (inspired by the Collector's AGENTS.md). - Clarify that only instrumentation packages live under `src/opentelemetry/instrumentation/{name}/`; other package types use their own namespace. --------- Co-authored-by: Riccardo Magliocchetti <riccardo.magliocchetti@gmail.com> * scripts: drop update_sha (#4430) It's buggy and unused. * Fix pylint false positives for ThreadPoolExecutor (#4244) * Bump pylint to 4.0.5 to fix Python 3.14 concurrent.futures false positives * Fix too-many-positional-arguments pylint failures - Add max-positional-arguments=10, Add pylint: disable=too-many-positional-arguments to functions that legitimately exceed the limit * Bump max-positional-arguments to 12 and remove unnecessary disable comments * Address review comments: fix CHANGELOG, remove stale pylintrc comment, add openai-agents disable * Fix formatting: restore blank line in CHANGELOG and remove extra blank line in .pylintrc * Update processor.py * Update test_botocore_bedrock.py --------- Co-authored-by: Riccardo Magliocchetti <riccardo.magliocchetti@gmail.com> * feat(util-genai): refactor and make API smaller and more user-friendly (#4391) * Refactor public API on GenAI utils * more lint * review feedback * update tests to use named params * address some of the comments * up * fix failing checks and clean up imports * lint * lint * fix lint * replace @deprecated with docstring info to avoid warnings for users * up * common code for context manager * Adding metrics call for Embedding type after refactoring * Updating metrics tests with embedding * Adding fix for markdown-link-check --------- Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Riccardo Magliocchetti <riccardo.magliocchetti@gmail.com> Co-authored-by: Emídio Neto <9735060+emdneto@users.noreply.github.com> Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com> Co-authored-by: Sri Kaaviya <107148069+srikaaviya@users.noreply.github.com> Co-authored-by: Liudmila Molkova <neskazu@gmail.com>

lmolkova requested a review from a team as a code owner April 3, 2026 02:00

github-project-automation bot added this to Python PR digest Apr 3, 2026

github-actions bot assigned DylanRussell, keith-decker and lmolkova Apr 3, 2026

lmolkova force-pushed the genai-utils-api-cleanup branch from 720ba87 to 23e777f Compare April 3, 2026 02:07

lmolkova commented Apr 3, 2026

View reviewed changes

Comment thread util/opentelemetry-util-genai/tests/test_toolcall.py

lmolkova commented Apr 3, 2026

View reviewed changes

Comment thread util/opentelemetry-util-genai/tests/test_utils.py

lmolkova commented Apr 3, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

Refactor public API on GenAI utils

b8e7e4e

lmolkova force-pushed the genai-utils-api-cleanup branch from 0fc33e7 to b8e7e4e Compare April 3, 2026 05:46

more lint

dc2cd6d

xrmx added the gen-ai Related to generative AI label Apr 3, 2026

MikeGoldsmith approved these changes Apr 3, 2026

View reviewed changes

Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py Outdated

DylanRussell reviewed Apr 3, 2026

View reviewed changes

Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py

Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py

Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/tool_invocation.py Outdated

review feedback

baf3b95

Merge branch 'main' into genai-utils-api-cleanup

56ce2ad

github-actions bot assigned MikeGoldsmith Apr 3, 2026

update tests to use named params

a1ef607

DylanRussell approved these changes Apr 3, 2026

View reviewed changes

Kludex reviewed Apr 4, 2026

View reviewed changes

Comment thread .gitignore Outdated

Kludex reviewed Apr 4, 2026

View reviewed changes

lmolkova added 4 commits April 4, 2026 09:17

address some of the comments

cdce292

Merge branch 'main' into genai-utils-api-cleanup

af3081a

up

941bc17

fix failing checks and clean up imports

39ffa9d

lmolkova force-pushed the genai-utils-api-cleanup branch from 392ae45 to 39ffa9d Compare April 4, 2026 17:36

lmolkova added 2 commits April 4, 2026 10:42

lint

e67649c

lint

0816045

keith-decker reviewed Apr 6, 2026

View reviewed changes

Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py

keith-decker approved these changes Apr 6, 2026

View reviewed changes

MikeGoldsmith approved these changes Apr 8, 2026

View reviewed changes

MikeGoldsmith moved this to Approved PRs that need fixes in Python PR digest Apr 8, 2026

lmolkova added 3 commits April 9, 2026 09:17

Merge branch 'main' into genai-utils-api-cleanup

a0963e5

fix lint

80b86e2

replace @deprecated with docstring info to avoid warnings for users

320bfd0

lmolkova force-pushed the genai-utils-api-cleanup branch from 4d4e31d to 320bfd0 Compare April 9, 2026 21:22

up

8f45cc2

eternalcuriouslearner reviewed Apr 13, 2026

View reviewed changes

Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py Outdated

MikeGoldsmith moved this from Approved PRs that need fixes to Approved PRs in Python PR digest Apr 13, 2026

lmolkova added 2 commits April 14, 2026 13:14

Merge branch 'main' into genai-utils-api-cleanup

35f74be

common code for context manager

8bca50a

eternalcuriouslearner approved these changes Apr 15, 2026

View reviewed changes

xrmx approved these changes Apr 15, 2026

View reviewed changes

xrmx merged commit 34bfc28 into open-telemetry:main Apr 15, 2026
750 checks passed

github-project-automation bot moved this from Approved PRs to Done in Python PR digest Apr 15, 2026

wrisa mentioned this pull request Apr 16, 2026

Add LangChain workflow span support and refactor LLM invocation #4449

Draft

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(util-genai): refactor and make API smaller and more user-friendly#4391

feat(util-genai): refactor and make API smaller and more user-friendly#4391
xrmx merged 17 commits intoopen-telemetry:mainfrom
lmolkova:genai-utils-api-cleanup

lmolkova commented Apr 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MikeGoldsmith left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmolkova commented Apr 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmolkova commented Apr 7, 2026

Uh oh!

MikeGoldsmith left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Conversation

lmolkova commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before

After

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MikeGoldsmith left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmolkova commented Apr 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmolkova commented Apr 7, 2026

Uh oh!

MikeGoldsmith left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

lmolkova commented Apr 3, 2026 •

edited

Loading