From f8d6f94f3f162318cb488636ef16d8d423cbf223 Mon Sep 17 00:00:00 2001 From: Leena Catherine H Date: Wed, 30 Sep 2026 11:50:42 +0530 Subject: [PATCH 1/2] Improve context provider functions in llm_context.py Refactor context provider functions for clarity and type hints. --- core/llm_context.py | 55 +++++++++++++++++---------------------------- 1 file changed, 20 insertions(+), 35 deletions(-) diff --git a/core/llm_context.py b/core/llm_context.py index 978a1bf..e90d93d 100644 --- a/core/llm_context.py +++ b/core/llm_context.py @@ -1,27 +1,3 @@ -"""The ContextVar seam BYOK uses to reach get_llm_provider() (providers/llm/__init__.py) -without threading a provider through every agent constructor and every -core/container.py factory. - -Why a ContextVar and not wider plumbing ----------------------------------------- -`agents/base.py:BaseAgent.__init__` resolves its provider as -`llm_provider or get_llm_provider()`, called deep inside a tree of agents -built by core/container.py's `*_factory_for` methods. Threading a user_id -or a provider through every one of those constructors for one optional -BYOK value would be a wide diff across every production code path whose -only purpose is carrying that one value. A ContextVar touches exactly the -resolution seam inside get_llm_provider() and nothing else. - -What this does NOT solve (see docs/superpowers/specs/2026-09-06-byok-design.md -"The boundary, stated plainly") ------------------------------------------------------------------------------- -Ambient context only reaches code running inside the request/task that set -it. `main.py` (the CLI) and any future out-of-process worker see no -ContextVar and correctly fall through to the environment. A long-lived -interview session that outlives the request that created it must NOT rely -on this - it stores the owning recruiter's user_id and re-resolves -explicitly at use time instead (services/evaluation_service.py). -""" from __future__ import annotations from contextvars import ContextVar, Token @@ -30,30 +6,39 @@ if TYPE_CHECKING: from providers.base import LLMProvider + _current_llm_provider: ContextVar[Optional["LLMProvider"]] = ContextVar( "_current_llm_provider", default=None ) -def set_context_provider(provider: Optional["LLMProvider"]) -> Token: - """Set the provider for the current context (request). Returns a Token - that MUST be passed to reset_context_provider when the request ends - - see api/dependencies for the yield-dependency that does this.""" +def set_context_provider( + provider: Optional["LLMProvider"], +) -> Token[Optional["LLMProvider"]]: + """Set the provider for the current context (request). + + Returns a token that must be passed to reset_context_provider() + when the request ends. + """ return _current_llm_provider.set(provider) def reset_context_provider(token: Token) -> None: - """Undo a prior set_context_provider call. Always call this in a - `finally` block paired with the `set_context_provider` that produced - `token`, so a provider never outlives the request that set it.""" + """Undo a prior set_context_provider call. + + Always call this in a finally block paired with the + set_context_provider() call that produced the token. + """ _current_llm_provider.reset(token) def get_context_provider() -> Optional["LLMProvider"]: - """The provider set for the current context, or None if none is set - - read by providers/llm/__init__.py:get_llm_provider() before it falls - back to the environment-based dispatch.""" + """Return the provider set for the current context, or None.""" return _current_llm_provider.get() -__all__ = ["get_context_provider", "reset_context_provider", "set_context_provider"] +__all__ = [ + "get_context_provider", + "reset_context_provider", + "set_context_provider", +] From 56a65355c4bc2f9ad38ff909ecee73226ff266f6 Mon Sep 17 00:00:00 2001 From: Siddhartha Kushwaha Date: Wed, 28 Oct 2026 11:48:35 +0530 Subject: [PATCH 2/2] docs(core): retain module docstring and type Token parameter in reset_context_provider --- core/llm_context.py | 43 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/core/llm_context.py b/core/llm_context.py index e90d93d..6ffa211 100644 --- a/core/llm_context.py +++ b/core/llm_context.py @@ -1,3 +1,27 @@ +"""The ContextVar seam BYOK uses to reach get_llm_provider() (providers/llm/__init__.py) +without threading a provider through every agent constructor and every +core/container.py factory. + +Why a ContextVar and not wider plumbing +---------------------------------------- +`agents/base.py:BaseAgent.__init__` resolves its provider as +`llm_provider or get_llm_provider()`, called deep inside a tree of agents +built by core/container.py's `*_factory_for` methods. Threading a user_id +or a provider through every one of those constructors for one optional +BYOK value would be a wide diff across every production code path whose +only purpose is carrying that one value. A ContextVar touches exactly the +resolution seam inside get_llm_provider() and nothing else. + +What this does NOT solve (see docs/superpowers/specs/2026-09-06-byok-design.md +"The boundary, stated plainly") +------------------------------------------------------------------------------ +Ambient context only reaches code running inside the request/task that set +it. `main.py` (the CLI) and any future out-of-process worker see no +ContextVar and correctly fall through to the environment. A long-lived +interview session that outlives the request that created it must NOT rely +on this - it stores the owning recruiter's user_id and re-resolves +explicitly at use time instead (services/evaluation_service.py). +""" from __future__ import annotations from contextvars import ContextVar, Token @@ -6,7 +30,6 @@ if TYPE_CHECKING: from providers.base import LLMProvider - _current_llm_provider: ContextVar[Optional["LLMProvider"]] = ContextVar( "_current_llm_provider", default=None ) @@ -17,23 +40,29 @@ def set_context_provider( ) -> Token[Optional["LLMProvider"]]: """Set the provider for the current context (request). - Returns a token that must be passed to reset_context_provider() - when the request ends. + Returns a Token that MUST be passed to reset_context_provider() + when the request ends - see api/dependencies for the yield-dependency + that manages this lifecycle. """ return _current_llm_provider.set(provider) -def reset_context_provider(token: Token) -> None: +def reset_context_provider(token: Token[Optional["LLMProvider"]]) -> None: """Undo a prior set_context_provider call. - Always call this in a finally block paired with the - set_context_provider() call that produced the token. + Always call this in a `finally` block paired with the + set_context_provider() call that produced `token`, so a provider + never outlives the request that set it. """ _current_llm_provider.reset(token) def get_context_provider() -> Optional["LLMProvider"]: - """Return the provider set for the current context, or None.""" + """The provider set for the current context, or None if none is set. + + Read by providers/llm/__init__.py:get_llm_provider() before it falls + back to the environment-based dispatch. + """ return _current_llm_provider.get()