language-model-common 2.1.2__tar.gz → 3.0.0__tar.gz

{language_model_common-2.1.2/language_model_common.egg-info → language_model_common-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: language-model-common
-Version: 2.1.2
+Version: 3.0.0
 Summary: Provides the underlying framework to enhance langchain and add loading configurations
 Author-email: Imran Qureshi <imran.qureshi@bwell.com>
 License: Apache-2.0
@@ -46,7 +46,7 @@ A shared Python framework for building LLM-powered agent applications with LangC
 
 - **Multi-source configuration loading** — Read LLM model configs from local filesystem, AWS S3, or GitHub repositories with TTL-based caching and client-specific overrides (see [config reader security notes](docs/config-reader-security.md))
 - **LangGraph-to-OpenAI protocol conversion** — Stream LangGraph agent output as OpenAI-compatible Server-Sent Events (SSE) for chat completion APIs
-- **MCP (Model Context Protocol) integration** — Tool discovery with BM25 search ranking, OAuth 2.1/OIDC support, dynamic client registration, and [MCP Apps](docs/mcp-apps.md) UI rendering via `ui://` resources
+- **MCP (Model Context Protocol) client toolkit** — Connect to and invoke tools on a single MCP server as LangChain-compatible tools, with session pooling, server-card discovery, and tool-result caching
 - **Prompt template library** — Load and manage prompt templates from organized directory structures with GitHub auto-download support
 - **File management abstraction** — Unified interface for local and AWS S3 storage with factory-based backend selection
 - **Token and cost management** — Token reduction for long conversations and usage metadata tracking via tiktoken
@@ -123,18 +123,6 @@ manager = factory.create("s3://my-bucket")
 await manager.save_file_async(file_data, "s3://my-bucket", "output.json", "application/json")
 ```
 
-### MCP Tool Discovery
-
-```python
-from languagemodelcommon.mcp import ToolCatalog
-
-catalog = ToolCatalog()
-catalog.register_server("my-server", url="http://localhost:8080")
-
-# BM25-ranked search for relevant tools
-results = catalog.search("search patient records")
-```
-
 ### Using the Dependency Injection Container
 
 ```python

{language_model_common-2.1.2 → language_model_common-3.0.0}/README.md

@@ -6,7 +6,7 @@ A shared Python framework for building LLM-powered agent applications with LangC
 
 - **Multi-source configuration loading** — Read LLM model configs from local filesystem, AWS S3, or GitHub repositories with TTL-based caching and client-specific overrides (see [config reader security notes](docs/config-reader-security.md))
 - **LangGraph-to-OpenAI protocol conversion** — Stream LangGraph agent output as OpenAI-compatible Server-Sent Events (SSE) for chat completion APIs
-- **MCP (Model Context Protocol) integration** — Tool discovery with BM25 search ranking, OAuth 2.1/OIDC support, dynamic client registration, and [MCP Apps](docs/mcp-apps.md) UI rendering via `ui://` resources
+- **MCP (Model Context Protocol) client toolkit** — Connect to and invoke tools on a single MCP server as LangChain-compatible tools, with session pooling, server-card discovery, and tool-result caching
 - **Prompt template library** — Load and manage prompt templates from organized directory structures with GitHub auto-download support
 - **File management abstraction** — Unified interface for local and AWS S3 storage with factory-based backend selection
 - **Token and cost management** — Token reduction for long conversations and usage metadata tracking via tiktoken
@@ -83,18 +83,6 @@ manager = factory.create("s3://my-bucket")
 await manager.save_file_async(file_data, "s3://my-bucket", "output.json", "application/json")
 ```
 
-### MCP Tool Discovery
-
-```python
-from languagemodelcommon.mcp import ToolCatalog
-
-catalog = ToolCatalog()
-catalog.register_server("my-server", url="http://localhost:8080")
-
-# BM25-ranked search for relevant tools
-results = catalog.search("search patient records")
-```
-
 ### Using the Dependency Injection Container
 
 ```python

language_model_common-3.0.0/VERSION

@@ -0,0 +1 @@
+3.0.0

{language_model_common-2.1.2 → language_model_common-3.0.0/language_model_common.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: language-model-common
-Version: 2.1.2
+Version: 3.0.0
 Summary: Provides the underlying framework to enhance langchain and add loading configurations
 Author-email: Imran Qureshi <imran.qureshi@bwell.com>
 License: Apache-2.0
@@ -46,7 +46,7 @@ A shared Python framework for building LLM-powered agent applications with LangC
 
 - **Multi-source configuration loading** — Read LLM model configs from local filesystem, AWS S3, or GitHub repositories with TTL-based caching and client-specific overrides (see [config reader security notes](docs/config-reader-security.md))
 - **LangGraph-to-OpenAI protocol conversion** — Stream LangGraph agent output as OpenAI-compatible Server-Sent Events (SSE) for chat completion APIs
-- **MCP (Model Context Protocol) integration** — Tool discovery with BM25 search ranking, OAuth 2.1/OIDC support, dynamic client registration, and [MCP Apps](docs/mcp-apps.md) UI rendering via `ui://` resources
+- **MCP (Model Context Protocol) client toolkit** — Connect to and invoke tools on a single MCP server as LangChain-compatible tools, with session pooling, server-card discovery, and tool-result caching
 - **Prompt template library** — Load and manage prompt templates from organized directory structures with GitHub auto-download support
 - **File management abstraction** — Unified interface for local and AWS S3 storage with factory-based backend selection
 - **Token and cost management** — Token reduction for long conversations and usage metadata tracking via tiktoken
@@ -123,18 +123,6 @@ manager = factory.create("s3://my-bucket")
 await manager.save_file_async(file_data, "s3://my-bucket", "output.json", "application/json")
 ```
 
-### MCP Tool Discovery
-
-```python
-from languagemodelcommon.mcp import ToolCatalog
-
-catalog = ToolCatalog()
-catalog.register_server("my-server", url="http://localhost:8080")
-
-# BM25-ranked search for relevant tools
-results = catalog.search("search patient records")
-```
-
 ### Using the Dependency Injection Container
 
 ```python

{language_model_common-2.1.2 → language_model_common-3.0.0}/language_model_common.egg-info/SOURCES.txt

@@ -11,20 +11,9 @@ language_model_common.egg-info/top_level.txt
 languagemodelcommon/__init__.py
 languagemodelcommon/py.typed
 languagemodelcommon/auth/__init__.py
-languagemodelcommon/auth/oauth_provider_registrar.py
-languagemodelcommon/auth/pass_through_token_manager.py
-languagemodelcommon/auth/token_storage_auth_manager.py
 languagemodelcommon/auth/authenticator/__init__.py
 languagemodelcommon/auth/exceptions/__init__.py
-languagemodelcommon/auth/exceptions/authorization_mcp_tool_token_invalid_exception.py
-languagemodelcommon/auth/exceptions/authorization_token_cache_item_expired_exception.py
-languagemodelcommon/auth/exceptions/authorization_token_cache_item_not_found_exception.py
 languagemodelcommon/auth/models/__init__.py
-languagemodelcommon/auth/models/token_cache_item.py
-languagemodelcommon/auth/token_exchange/__init__.py
-languagemodelcommon/auth/token_exchange/token_exchange_manager.py
-languagemodelcommon/auth/tools/__init__.py
-languagemodelcommon/auth/tools/tool_auth_manager.py
 languagemodelcommon/aws/__init__.py
 languagemodelcommon/aws/aws_client_factory.py
 languagemodelcommon/configs/__init__.py
@@ -90,33 +79,21 @@ languagemodelcommon/markdown/__init__.py
 languagemodelcommon/markdown/html_to_markdown_converter.py
 languagemodelcommon/mcp/__init__.py
 languagemodelcommon/mcp/callbacks.py
-languagemodelcommon/mcp/mcp_tool_provider.py
-languagemodelcommon/mcp/tool_catalog.py
-languagemodelcommon/mcp/tool_discovery_middleware.py
 languagemodelcommon/mcp/auth/__init__.py
-languagemodelcommon/mcp/auth/auth_server_metadata_discovery.py
-languagemodelcommon/mcp/auth/mcp_authorization_helper.py
 languagemodelcommon/mcp/exceptions/__init__.py
-languagemodelcommon/mcp/exceptions/mcp_tool_exception.py
-languagemodelcommon/mcp/exceptions/mcp_tool_not_found_exception.py
-languagemodelcommon/mcp/exceptions/mcp_tool_unauthorized_exception.py
-languagemodelcommon/mcp/exceptions/mcp_tool_unknown_exception.py
 languagemodelcommon/mcp/interceptors/__init__.py
-languagemodelcommon/mcp/interceptors/auth.py
 languagemodelcommon/mcp/interceptors/tracing.py
 languagemodelcommon/mcp/interceptors/truncation.py
 languagemodelcommon/mcp/interceptors/types.py
 languagemodelcommon/mcp/mcp_client/__init__.py
 languagemodelcommon/mcp/mcp_client/content_conversion.py
 languagemodelcommon/mcp/mcp_client/langchain_adapter.py
-languagemodelcommon/mcp/mcp_client/mcp_app_proxy.py
 languagemodelcommon/mcp/mcp_client/mcp_tool_list_store.py
 languagemodelcommon/mcp/mcp_client/server_card_discovery.py
 languagemodelcommon/mcp/mcp_client/session.py
 languagemodelcommon/mcp/mcp_client/session_pool.py
 languagemodelcommon/mcp/mcp_client/tool_invocation.py
 languagemodelcommon/mcp/mcp_client/tool_list_cache.py
-languagemodelcommon/mcp/mcp_client/ui_resource.py
 languagemodelcommon/mocks/__init__.py
 languagemodelcommon/mocks/mock_aws_client_factory.py
 languagemodelcommon/mocks/mock_http_client_factory.py
@@ -157,8 +134,6 @@ languagemodelcommon/structures/openai/request/chat_request_wrapper.py
 languagemodelcommon/structures/openai/request/responses_api_request_wrapper.py
 languagemodelcommon/tools/__init__.py
 languagemodelcommon/tools/mcp/__init__.py
-languagemodelcommon/tools/mcp/call_tool_tool.py
-languagemodelcommon/tools/mcp/search_tools_tool.py
 languagemodelcommon/utilities/__init__.py
 languagemodelcommon/utilities/chat_message_helpers.py
 languagemodelcommon/utilities/config_substitution.py

{language_model_common-2.1.2 → language_model_common-3.0.0}/languagemodelcommon/container/container_factory.py

@@ -38,9 +38,6 @@ from languagemodelcommon.ocr.ocr_extractor_factory import OCRExtractorFactory
 from languagemodelcommon.persistence.persistence_factory import PersistenceFactory
 from key_value.aio.stores.base import BaseStore as KeyValueBaseStore
 
-from languagemodelcommon.mcp.auth.auth_server_metadata_discovery import (
-    McpAuthServerDiscovery,
-)
 from languagemodelcommon.mcp.mcp_client.mcp_tool_list_store import McpToolListStore
 from languagemodelcommon.mcp.mcp_client.server_card_discovery import (
     ServerCardDiscovery,
@@ -165,10 +162,6 @@ class LanguageModelCommonContainerFactory:
         container.singleton(
             service_type=McpJsonFetcher, factory=_create_mcp_json_fetcher
         )
-        container.singleton(
-            service_type=McpAuthServerDiscovery,
-            factory=lambda c: McpAuthServerDiscovery(),
-        )
         container.singleton(
             service_type=ServerCardDiscovery,
             factory=lambda c: ServerCardDiscovery(),

{language_model_common-2.1.2 → language_model_common-3.0.0}/languagemodelcommon/converters/langgraph_to_openai_converter.py

@@ -53,8 +53,6 @@ from languagemodelcommon.converters.stream_debug_output_manager import (
 from languagemodelcommon.converters.streaming_manager import LangGraphStreamingManager
 from languagemodelcommon.exceptions.bailey_exception import BaileyException
 from languagemodelcommon.exceptions.rate_limit_exception import RateLimitException
-from languagemodelcommon.mcp.tool_catalog import ToolCatalog
-from languagemodelcommon.mcp.tool_discovery_middleware import ToolDiscoveryMiddleware
 from languagemodelcommon.converters.history_cache_middleware import (
     HistoryCacheMiddleware,
 )
@@ -1209,7 +1207,6 @@ class LangGraphToOpenAIConverter(StreamContextMixin):
         store: BaseStore | None,
         checkpointer: BaseCheckpointSaver[str] | None,
         system_prompts: List[PromptConfig] | None = None,
-        tool_catalog: ToolCatalog | None = None,
     ) -> CompiledStateGraph[MyMessagesState]:
         """
         Create a graph for the language model asynchronously.
@@ -1225,7 +1222,6 @@ class LangGraphToOpenAIConverter(StreamContextMixin):
             system_prompts: Optional list of PromptConfig objects. Each becomes a
                 separate content block in the system message. Blocks with cache=True
                 are marked for prompt caching (cache_control: ephemeral).
-            tool_catalog: Optional tool catalog for tool discovery middleware
         """
         prompt: SystemMessage | None = None
         if system_prompts:
@@ -1261,8 +1257,6 @@ class LangGraphToOpenAIConverter(StreamContextMixin):
         )
         # Create the react agent with optional system prompt
         middleware: list[AgentMiddleware] = []
-        if tool_catalog is not None:
-            middleware.append(ToolDiscoveryMiddleware(catalog=tool_catalog))
         if self.environment_variables.enable_history_prompt_caching:
             middleware.append(HistoryCacheMiddleware())
 

{language_model_common-2.1.2 → language_model_common-3.0.0}/languagemodelcommon/converters/stream_buffer.py

@@ -18,6 +18,29 @@ class StreamBufferManager:
         self._flush_interval_seconds = flush_interval_seconds
         self._enabled = enabled
         self._buffer = StreamBuffer(chunks=[], last_flush_ts=time.monotonic())
+        self._last_emitted_char: str | None = None
+        self._pending_invocation_boundary = False
+
+    def mark_new_invocation_boundary(self) -> None:
+        """Flag that the next content flows from a fresh chat-model invocation.
+
+        LangGraph re-invokes the chat model independently after each tool
+        call, so the resumed completion has no guaranteed leading whitespace
+        against whatever this request already streamed. The flag is consumed
+        by the next non-empty ``content_text`` passed to ``buffer_content``.
+        """
+        self._pending_invocation_boundary = True
+
+    def _apply_invocation_boundary(self, *, content_text: str) -> str:
+        if not self._pending_invocation_boundary:
+            return content_text
+        self._pending_invocation_boundary = False
+        needs_separator = (
+            self._last_emitted_char is not None
+            and not self._last_emitted_char.isspace()
+            and not content_text[0].isspace()
+        )
+        return f" {content_text}" if needs_separator else content_text
 
     async def buffer_content(
         self,
@@ -25,6 +48,10 @@ class StreamBufferManager:
         content_text: str,
         force_flush: bool = False,
     ) -> str | None:
+        if content_text:
+            content_text = self._apply_invocation_boundary(content_text=content_text)
+            self._last_emitted_char = content_text[-1]
+
         if not self._enabled:
             existing_text = "".join(self._buffer.chunks) if self._buffer.chunks else ""
             self._buffer.chunks.clear()

{language_model_common-2.1.2 → language_model_common-3.0.0}/languagemodelcommon/converters/streaming_manager.py

@@ -293,6 +293,11 @@ class LangGraphStreamingManager(StreamContextMixin):
         chat_request_wrapper: ChatRequestWrapper,
         request_information: RequestInformation,
     ) -> AsyncGenerator[str | None, None]:
+        # Each on_chat_model_start after the first marks a fresh model
+        # invocation (e.g. resuming after a tool call) whose first token has
+        # no guaranteed whitespace against what was already streamed -- see
+        # StreamBufferManager.mark_new_invocation_boundary.
+        self._stream_buffer_manager.mark_new_invocation_boundary()
         yield None
 
     async def _handle_on_chat_model_end(

{language_model_common-2.1.2 → language_model_common-3.0.0}/languagemodelcommon/graph/graph_builder.py

@@ -19,8 +19,6 @@ from languagemodelcommon.history.conversation_history_manager import (
     ConversationHistoryManager,
 )
 from languagemodelcommon.history.smart_history_manager import SmartHistoryManager
-from languagemodelcommon.mcp.tool_catalog import ToolCatalog
-from languagemodelcommon.mcp.tool_discovery_middleware import ToolDiscoveryMiddleware
 from languagemodelcommon.state.messages_state import MyMessagesState
 
 logger = logging.getLogger(__name__)
@@ -46,7 +44,6 @@ class GraphBuilder:
         store: BaseStore | None,
         checkpointer: BaseCheckpointSaver[str] | None,
         system_prompts: List[str] | None = None,
-        tool_catalog: ToolCatalog | None = None,
         max_messages: int = 20,
         max_tokens: int = 4000,
     ) -> CompiledStateGraph[MyMessagesState]:
@@ -98,8 +95,6 @@ class GraphBuilder:
 
         # Create react agent
         middleware: list[AgentMiddleware] = []
-        if tool_catalog is not None:
-            middleware.append(ToolDiscoveryMiddleware(catalog=tool_catalog))
 
         react_agent_runnable = create_agent(
             model=llm,

language_model_common-2.1.2/VERSION

@@ -1 +0,0 @@
-2.1.2

language_model_common-2.1.2/languagemodelcommon/auth/exceptions/authorization_mcp_tool_token_invalid_exception.py

@@ -1,31 +0,0 @@
-from oidcauthlib.auth.exceptions.authorization_needed_exception import (
-    AuthorizationNeededException,
-)
-from oidcauthlib.auth.models.token import Token
-
-
-class AuthorizationMcpToolTokenInvalidException(AuthorizationNeededException):
-    """
-    Exception raised when a tool token is invalid.
-    This exception is used to indicate that the provided tool token does not meet the
-    required format or is not recognized by the authentication system.
-    It inherits from AuthorizationNeededException and provides additional context
-    about the invalid token and the tool URL.
-    """
-
-    def __init__(self, *, message: str, token: Token | None, tool_url: str) -> None:
-        """
-        Initialize the AuthorizationNeededException with a message and an optional token cache item.
-        """
-        super().__init__(message=message)
-        self.message = message
-        self.token: Token | None = token
-        self.tool_url: str = tool_url
-
-    @staticmethod
-    def build_login_required_message(tool_name: str) -> str:
-        """Build the user-facing prefix shown before login links."""
-        return (
-            f"I found a tool **{tool_name}** that can help with your task. "
-            "This tool requires you to log in below."
-        )

language_model_common-2.1.2/languagemodelcommon/auth/exceptions/authorization_token_cache_item_expired_exception.py

@@ -1,25 +0,0 @@
-from oidcauthlib.auth.exceptions.authorization_needed_exception import (
-    AuthorizationNeededException,
-)
-
-from languagemodelcommon.auth.models.token_cache_item import TokenCacheItem
-
-
-class AuthorizationTokenCacheItemExpiredException(AuthorizationNeededException):
-    """
-    Exception raised when a token cache item has expired.
-    This exception is used to indicate that the cached token is no longer valid
-    and needs to be refreshed or re-obtained.
-    It inherits from AuthorizationNeededException and provides a message to indicate the
-    nature of the error, along with an optional token cache item for further context.
-    """
-
-    def __init__(
-        self, *, message: str, token_cache_item: TokenCacheItem | None
-    ) -> None:
-        """
-        Initialize the AuthorizationNeededException with a message and an optional token cache item.
-        """
-        super().__init__(message=message)
-        self.message = message
-        self.token_cache_item: TokenCacheItem | None = token_cache_item

language_model_common-2.1.2/languagemodelcommon/auth/exceptions/authorization_token_cache_item_not_found_exception.py

@@ -1,23 +0,0 @@
-from oidcauthlib.auth.exceptions.authorization_needed_exception import (
-    AuthorizationNeededException,
-)
-
-
-class AuthorizationTokenCacheItemNotFoundException(AuthorizationNeededException):
-    """
-    Exception raised when a token cache item is not found.
-    This exception is used to indicate that the requested token cache item does not exist
-    in the cache, which may occur if the token has never been cached or has been removed
-    due to expiration or other reasons.
-    It inherits from AuthorizationNeededException and provides a message to indicate the
-    nature of the error, along with an optional list of tool authentication audiences
-    that may be relevant for the authorization process.
-    """
-
-    def __init__(self, *, message: str, tool_auth_providers: list[str] | None) -> None:
-        """
-        Initialize the AuthorizationNeededException with a message and an optional token cache item.
-        """
-        super().__init__(message=message)
-        self.message = message
-        self.tool_auth_providers = tool_auth_providers

language_model_common-2.1.2/languagemodelcommon/auth/models/token_cache_item.py

@@ -1,212 +0,0 @@
-from typing import Optional
-
-from bson import ObjectId
-from oidcauthlib.auth.models.base_db_model import BaseDbModel
-from pydantic import Field
-
-from datetime import datetime, UTC
-
-from oidcauthlib.auth.models.token import Token
-
-
-class TokenCacheItem(BaseDbModel):
-    """
-    Represents a token cache item in the database.
-    """
-
-    schema_version: Optional[str] = Field(
-        default=None,
-        description="Schema version of this cache entry. Used to filter out stale entries after schema changes.",
-    )
-
-    created: datetime = Field(
-        description="The creation time of the token as a datetime object."
-    )
-    updated: Optional[datetime] = Field(
-        default=None,
-        description="The last update time of the token as a datetime object.",
-    )
-    refreshed: Optional[datetime] = Field(
-        default=None,
-        description="The last refresh time of the token as a datetime object.",
-    )
-
-    auth_provider: str = Field(
-        description="The authentication provider associated with the token."
-    )
-    client_id: Optional[str] = Field(
-        default=None,
-        description="The client ID associated with the token, if applicable.",
-    )
-    issuer: str | None = Field(
-        default=None,
-        description="The issuer of the token, typically the authorization server.",
-    )
-    audience: str = Field(
-        description="The intended audience for the token, usually the resource server."
-    )
-    email: Optional[str] = Field(
-        description="The email associated with the token, used for user identification."
-    )
-    subject: str = Field(
-        description="The subject of the token, typically the user ID or unique identifier."
-    )
-    referring_email: Optional[str] = Field(
-        description="The email of the original token that is linked to this token, if applicable."
-    )
-    referring_subject: str = Field(
-        description="The subject of the original token that is linked to this token, if applicable."
-    )
-    referrer: Optional[str] = Field(
-        default=None, description="The URL associated with the token, if applicable."
-    )
-    access_token: Optional[Token] = Field(
-        default=None, description="The access token used for authentication."
-    )
-    id_token: Optional[Token] = Field(
-        default=None, description="The ID token containing user information."
-    )
-    refresh_token: Optional[Token] = Field(
-        default=None, description="The refresh token used to obtain new access tokens."
-    )
-
-    access_token_raw: Optional[str] = Field(
-        default=None,
-        description="The raw access token string. Stored because the access token may be opaque (non-JWT) for some providers (e.g., Atlassian).",
-    )
-
-    refresh_token_raw: Optional[str] = Field(
-        default=None,
-        description="The raw refresh token string, stored for use in token refresh operations. This is necessary because the refresh token may not be a JWT and may not have the same structure as access or ID tokens.",
-    )
-
-    def is_valid_id_token(self) -> bool:
-        """
-        Check if the token is valid based on its expiration time.
-        Returns:
-            bool: True if the token is valid, False otherwise.
-        """
-        return self.id_token.is_valid() if self.id_token else False
-
-    def is_valid_refresh_token(self) -> bool:
-        """
-        Check if the refresh token is valid based on its expiration time.
-        Returns:
-            bool: True if the refresh token is valid, False otherwise.
-        """
-        return self.refresh_token.is_valid() if self.refresh_token else False
-
-    def is_valid_access_token(self) -> bool:
-        """
-        Check if the access token is valid based on its expiration time.
-        For opaque tokens (no decoded Token object), returns True if a raw
-        access token string exists since expiry cannot be determined locally.
-        Returns:
-            bool: True if the access token is valid, False otherwise.
-        """
-        if self.access_token:
-            return self.access_token.is_valid()
-        # Opaque token — we have the raw string but can't check expiry locally
-        return self.access_token_raw is not None
-
-    def get_access_token_string(self) -> Optional[str]:
-        """
-        Gets the raw access token string, preferring the decoded Token's string
-        but falling back to access_token_raw for opaque tokens.
-        """
-        if self.access_token:
-            return self.access_token.token
-        return self.access_token_raw
-
-    def get_access_token(self) -> Optional[Token]:
-        """
-        Gets the access token Token object if available.
-        Returns:
-            Optional[Token]: The access token if present, otherwise None.
-        """
-        return self.access_token if self.access_token else None
-
-    def get_id_token(self) -> Optional[Token]:
-        """
-        Gets the ID token if it is valid, otherwise returns the access token.
-        Returns:
-            Optional[str]: The id token if valid, otherwise the access token.
-        """
-        return self.id_token if self.id_token else None
-
-    def get_refresh_token(self) -> Optional[Token]:
-        """
-        Gets the refresh token if it is valid.
-        Returns:
-            Optional[str]: The refresh token if valid, otherwise None.
-        """
-        return self.refresh_token if self.refresh_token else None
-
-    @classmethod
-    def create(
-        cls,
-        *,
-        token: Token,
-        auth_provider: str,
-        referring_email: Optional[str],
-        referring_subject: str,
-    ) -> "TokenCacheItem":
-        # see what the token this is
-
-        audience: str | None = None
-        if isinstance(token.audience, list):
-            if len(token.audience) == 1:
-                audience = token.audience[0]
-        elif isinstance(token.audience, str):
-            audience = token.audience
-
-        if audience is None:
-            raise ValueError("Audience must be a string or a list with one string.")
-
-        if token.subject is None:
-            raise ValueError("Token must have a subject claim.")
-
-        token_cache_item: TokenCacheItem = TokenCacheItem(
-            id=ObjectId(),
-            created=datetime.now(UTC),
-            updated=None,
-            refreshed=None,
-            auth_provider=auth_provider,
-            issuer=token.issuer,
-            audience=audience,
-            email=token.email or referring_email,
-            subject=token.subject or referring_subject,
-            referrer=None,
-            access_token=token,
-            id_token=None,
-            refresh_token=None,
-            referring_email=referring_email,
-            referring_subject=referring_subject,
-        )
-        if token.is_id_token:
-            token_cache_item.id_token = token
-        elif token.is_access_token:
-            token_cache_item.access_token = token
-        elif token.is_refresh_token:
-            token_cache_item.refresh_token = token
-        else:
-            raise ValueError(
-                f"Token type must be id, bearer or refresh but was: {token.token_type}"
-            )
-
-        return token_cache_item
-
-    def is_expired(self) -> bool:
-        """
-        Check if the token cache item is expired based on the access token.
-        For opaque tokens, returns False (not expired) if a raw access token exists.
-        Returns:
-            bool: True if the access token is expired, False otherwise.
-        """
-        return (
-            not self.id_token.is_valid()
-            if self.id_token
-            else not self.access_token.is_valid()
-            if self.access_token
-            else self.access_token_raw is None
-        )