cozeloop 0.1.0__py3-none-any.whl

cozeloop/__init__.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+from .entities.prompt import Prompt, Message
+import cozeloop.entities
+from .logger import set_log_level, add_log_handler
+
+from .internal import __version__
+from .internal.consts import (
+    CN_BASE_URL,
+)
+from .internal.consts.error import *
+
+from .client import Client
+from ._client import (
+    new_client,
+    workspace_id,
+    close,
+    get_prompt,
+    prompt_format,
+    start_span,
+    get_span_from_context,
+    get_span_from_header,
+    flush,
+    ENV_API_BASE_URL,
+    ENV_WORKSPACE_ID,
+    ENV_API_TOKEN,
+    ENV_JWT_OAUTH_CLIENT_ID,
+    ENV_JWT_OAUTH_PRIVATE_KEY,
+    ENV_JWT_OAUTH_PUBLIC_KEY_ID
+)
+
+from .span import SpanContext, Span

cozeloop/_client.py

@@ -0,0 +1,315 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+import atexit
+import hashlib
+import logging
+import os
+import threading
+from datetime import datetime
+from typing import Dict, Any, List, Optional
+
+from cozeloop.client import Client
+from cozeloop._noop import NOOP_SPAN, _NoopClient
+from cozeloop.entities.prompt import Prompt, Message, PromptVariable
+from cozeloop.internal import consts, httpclient
+from cozeloop.internal.consts import ClientClosedError
+from cozeloop.internal.httpclient import Auth
+from cozeloop.internal.prompt import PromptProvider
+from cozeloop.internal.trace import TraceProvider
+from cozeloop.span import SpanContext, Span
+
+logger = logging.getLogger(__name__)
+
+# environment keys for loop client
+ENV_API_BASE_URL = "COZELOOP_API_BASE_URL"
+ENV_WORKSPACE_ID = "COZELOOP_WORKSPACE_ID"
+ENV_API_TOKEN = "COZELOOP_API_TOKEN"
+ENV_JWT_OAUTH_CLIENT_ID = "COZELOOP_JWT_OAUTH_CLIENT_ID"
+ENV_JWT_OAUTH_PRIVATE_KEY = "COZELOOP_JWT_OAUTH_PRIVATE_KEY"
+ENV_JWT_OAUTH_PUBLIC_KEY_ID = "COZELOOP_JWT_OAUTH_PUBLIC_KEY_ID"
+
+_client_cache = {}
+_cache_lock = threading.Lock()
+
+_default_client = None
+_client_lock = threading.Lock()
+
+
+def _generate_cache_key(*args) -> str:
+    key_str = "\t".join(str(arg) for arg in args)
+    return hashlib.md5(key_str.encode('utf-8')).hexdigest()
+
+
+def new_client(
+        api_base_url: str = "",
+        workspace_id: str = "",
+        api_token: str = "",
+        jwt_oauth_client_id: str = "",
+        jwt_oauth_private_key: str = "",
+        jwt_oauth_public_key_id: str = "",
+        timeout: int = consts.DEFAULT_TIMEOUT,
+        upload_timeout: int = consts.DEFAULT_UPLOAD_TIMEOUT,
+        ultra_large_report: bool = False,
+        prompt_cache_max_count: int = consts.DEFAULT_PROMPT_CACHE_MAX_COUNT,
+        prompt_cache_refresh_interval: int = consts.DEFAULT_PROMPT_CACHE_REFRESH_INTERVAL,
+        prompt_trace: bool = False,
+) -> Client:
+    cache_key = _generate_cache_key(
+        api_base_url,
+        workspace_id,
+        api_token,
+        jwt_oauth_client_id,
+        jwt_oauth_private_key,
+        jwt_oauth_public_key_id,
+        timeout,
+        upload_timeout,
+        ultra_large_report,
+        prompt_cache_max_count,
+        prompt_cache_refresh_interval,
+        prompt_trace
+    )
+
+    with _cache_lock:
+        if cache_key in _client_cache:
+            logger.warning("You shouldn't creating a client with same options repeatedly, " +
+                           "return the cached client instead.")
+            return _client_cache[cache_key]
+        client = _LoopClient(
+            api_base_url=api_base_url,
+            workspace_id=workspace_id,
+            api_token=api_token,
+            jwt_oauth_client_id=jwt_oauth_client_id,
+            jwt_oauth_private_key=jwt_oauth_private_key,
+            jwt_oauth_public_key_id=jwt_oauth_public_key_id,
+            timeout=timeout,
+            upload_timeout=upload_timeout,
+            ultra_large_report=ultra_large_report,
+            prompt_cache_max_count=prompt_cache_max_count,
+            prompt_cache_refresh_interval=prompt_cache_refresh_interval,
+            prompt_trace=prompt_trace,
+        )
+        _client_cache[cache_key] = client
+        return client
+
+
+class _LoopClient(Client):
+    _workspace_id: str
+    _trace_provider: TraceProvider
+    _prompt_provider: PromptProvider
+
+    _closed: bool = False
+
+    def __init__(
+            self,
+            api_base_url: str = "",
+            workspace_id: str = "",
+            api_token: str = "",
+            jwt_oauth_client_id: str = "",
+            jwt_oauth_private_key: str = "",
+            jwt_oauth_public_key_id: str = "",
+            timeout: int = consts.DEFAULT_TIMEOUT,
+            upload_timeout: int = consts.DEFAULT_UPLOAD_TIMEOUT,
+            ultra_large_report: bool = False,
+            prompt_cache_max_count: int = consts.DEFAULT_PROMPT_CACHE_MAX_COUNT,
+            prompt_cache_refresh_interval: int = consts.DEFAULT_PROMPT_CACHE_REFRESH_INTERVAL,
+            prompt_trace: bool = False
+    ):
+        workspace_id = self._get_from_env(workspace_id, ENV_WORKSPACE_ID)
+        api_base_url = self._get_from_env(api_base_url, ENV_API_BASE_URL)
+        api_token = self._get_from_env(api_token, ENV_API_TOKEN)
+        jwt_oauth_client_id = self._get_from_env(jwt_oauth_client_id, ENV_JWT_OAUTH_CLIENT_ID)
+        jwt_oauth_private_key = self._get_from_env(jwt_oauth_private_key, ENV_JWT_OAUTH_PRIVATE_KEY)
+        jwt_oauth_public_key_id = self._get_from_env(jwt_oauth_public_key_id, ENV_JWT_OAUTH_PUBLIC_KEY_ID)
+
+        api_base_url = consts.CN_BASE_URL if not api_base_url else api_base_url
+        api_base_url = api_base_url.strip().rstrip("/")
+
+        if not api_base_url:
+            raise consts.InvalidParamError("api_base_url is required.")
+        if not workspace_id:
+            raise consts.InvalidParamError("workspace_id is required.")
+        if prompt_cache_max_count <= 0:
+            prompt_cache_max_count = consts.DEFAULT_PROMPT_CACHE_MAX_COUNT
+        if prompt_cache_refresh_interval <= 0:
+            prompt_cache_refresh_interval = consts.DEFAULT_PROMPT_CACHE_REFRESH_INTERVAL
+
+        self._workspace_id = workspace_id
+        inner_client = httpclient.HTTPClient()
+        auth = self._build_auth(
+            api_base_url=api_base_url,
+            http_client=inner_client,
+            api_token=api_token,
+            jwt_oauth_client_id=jwt_oauth_client_id,
+            jwt_oauth_private_key=jwt_oauth_private_key,
+            jwt_oauth_public_key_id=jwt_oauth_public_key_id
+        )
+        http_client = httpclient.Client(
+            api_base_url=api_base_url,
+            http_client=inner_client,
+            auth=auth,
+            timeout=timeout,
+            upload_timeout=upload_timeout
+        )
+        self._trace_provider = TraceProvider(
+            http_client=http_client,
+            workspace_id=workspace_id,
+            ultra_large_report=ultra_large_report
+        )
+        self._prompt_provider = PromptProvider(
+            workspace_id=workspace_id,
+            http_client=http_client,
+            trace_provider=self._trace_provider,
+            prompt_cache_max_count=prompt_cache_max_count,
+            prompt_cache_refresh_interval=prompt_cache_refresh_interval,
+            prompt_trace=prompt_trace
+        )
+
+    def _get_from_env(self, val: str, env_key: str) -> str:
+        if val:
+            return val
+        env_val = os.environ.get(env_key)
+        if env_val:
+            return env_val
+        else:
+            return ""
+
+    def _build_auth(
+            self,
+            api_base_url: str,
+            http_client: httpclient.HTTPClient,
+            api_token: str,
+            jwt_oauth_client_id: str,
+            jwt_oauth_private_key: str,
+            jwt_oauth_public_key_id: str
+    ) -> Auth:
+        if jwt_oauth_client_id and jwt_oauth_private_key and jwt_oauth_public_key_id:
+            return httpclient.JWTAuth(
+                client_id=jwt_oauth_client_id,
+                private_key=jwt_oauth_private_key,
+                public_key_id=jwt_oauth_public_key_id,
+                base_url=api_base_url,
+                http_client=http_client
+            )
+        if api_token:
+            return httpclient.TokenAuth(api_token)
+        raise consts.AuthInfoRequiredError
+
+    def workspace_id(self) -> str:
+        # Return the space ID
+        return self._workspace_id
+
+    def close(self):
+        if self._closed:
+            return
+        # Perform cleanup by flushing and closing the trace client
+        self._trace_provider.close_trace()
+        self._closed = True
+
+    def get_prompt(self, prompt_key: str, version: str = '') -> Optional[Prompt]:
+        if self._closed:
+            raise ClientClosedError()
+        return self._prompt_provider.get_prompt(prompt_key, version)
+
+    def prompt_format(self, prompt: Prompt, variables: Dict[str, PromptVariable]) -> List[Message]:
+        if self._closed:
+            raise ClientClosedError()
+        return self._prompt_provider.prompt_format(prompt, variables)
+
+    def start_span(
+            self,
+            name: str,
+            span_type: str,
+            *,
+            start_time: Optional[datetime] = None,
+            child_of: Optional[SpanContext] = None,
+            start_new_trace: bool = False,
+    ) -> Span:
+        if self._closed:
+            return NOOP_SPAN
+        try:
+            if child_of is None:
+                return self._trace_provider.start_span(name=name, span_type=span_type, start_time=start_time,
+                                                       start_new_trace=start_new_trace)
+            else:
+                return self._trace_provider.start_span(name=name, span_type=span_type, start_time=start_time,
+                                                       parent_span_id=child_of.span_id, trace_id=child_of.trace_id,
+                                                       baggage=child_of.baggage, start_new_trace=start_new_trace)
+        except Exception as e:
+            logger.warning(f"Start span failed, returning noop span. Error: {e}")
+            return NOOP_SPAN
+
+    def get_span_from_context(self) -> Span:
+        if self._closed:
+            return NOOP_SPAN
+        span = self._trace_provider.get_span_from_context()
+        if span is None:
+            return NOOP_SPAN
+        return span
+
+    def get_span_from_header(self, header: dict) -> SpanContext:
+        if self._closed:
+            return NOOP_SPAN
+        return self._trace_provider.get_span_from_header(header)
+
+    def flush(self):
+        if self._closed:
+            return
+        self._trace_provider.flush()
+
+
+def get_default_client() -> Client:
+    global _default_client
+    if _default_client is None:
+        with _client_lock:
+            if _default_client is None:
+                try:
+                    _default_client = new_client()
+                    atexit.register(_graceful_shutdown)
+                except Exception as e:
+                    new_exception = e
+                    _default_client = _NoopClient(new_exception)
+    return _default_client
+
+
+def _graceful_shutdown():
+    global _default_client
+    with _client_lock:
+        if _default_client is not None:
+            logger.info("Starting graceful shutdown...")
+            _default_client.close()
+            _default_client = _NoopClient(ClientClosedError())
+            logger.info("Graceful shutdown finished.")
+
+
+def workspace_id() -> str:
+    return get_default_client().workspace_id
+
+
+def close():
+    return get_default_client().close()
+
+
+def get_prompt(prompt_key: str, version: str = '') -> Prompt:
+    return get_default_client().get_prompt(prompt_key, version)
+
+
+def prompt_format(prompt: Prompt, variables: Dict[str, Any]) -> List[Message]:
+    return get_default_client().prompt_format(prompt, variables)
+
+
+def start_span(name: str, span_type: str, *, start_time: Optional[int] = None,
+               child_of: Optional[SpanContext] = None) -> Span:
+    return get_default_client().start_span(name, span_type, start_time=start_time, child_of=child_of)
+
+
+def get_span_from_context() -> Span:
+    return get_default_client().get_span_from_context()
+
+
+def get_span_from_header(header: Dict[str, str]) -> SpanContext:
+    return get_default_client().get_span_from_header(header)
+
+
+def flush() -> None:
+    return get_default_client().flush()

cozeloop/_noop.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+import logging
+from typing import Dict, Optional, List
+
+from cozeloop.client import Client
+from cozeloop.entities.prompt import Prompt, Message, PromptVariable
+from cozeloop.internal.trace.noop_span import NoopSpan
+from cozeloop.span import SpanContext, Span
+
+NOOP_SPAN = NoopSpan()
+
+
+logger = logging.getLogger(__name__)
+
+
+class _NoopClient(Client):
+    def __init__(self, e: Exception):
+        self.new_exception = e
+
+    @property
+    def workspace_id(self) -> str:
+        logger.warning(f"Noop client not supported. {self.new_exception}")
+        return ""
+
+    def close(self):
+        logger.warning(f"Noop client not supported. {self.new_exception}")
+
+    def get_prompt(self, prompt_key: str, version: str = '') -> Optional[Prompt]:
+        logger.warning(f"Noop client not supported. {self.new_exception}")
+        raise self.new_exception
+
+    def prompt_format(self, prompt: Prompt, variables: Dict[str, PromptVariable]) -> List[Message]:
+        logger.warning(f"Noop client not supported. {self.new_exception}")
+        raise self.new_exception
+
+    def start_span(self, name: str, span_type: str, *, start_time: Optional[int] = None,
+                   child_of: Optional[SpanContext] = None, start_new_trace: bool = False) -> Span:
+        logger.warning(f"Noop client not supported. {self.new_exception}")
+        return NOOP_SPAN
+
+    def get_span_from_context(self) -> Span:
+        logger.warning(f"Noop client not supported. {self.new_exception}")
+        return NOOP_SPAN
+
+    def get_span_from_header(self, header: Dict[str, str]) -> SpanContext:
+        logger.warning(f"Noop client not supported. {self.new_exception}")
+        return NOOP_SPAN
+
+    def flush(self) -> None:
+        logger.warning(f"Noop client not supported. {self.new_exception}")

cozeloop/attribute/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+

cozeloop/attribute/trace/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+

cozeloop/attribute/trace/model.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+from enum import Enum
+from typing import List, Optional, Dict, Any
+
+from pydantic import BaseModel
+
+# ModelInput is the input for model span, for tag key: input
+class ModelInput(BaseModel):
+    messages: Optional[List['ModelMessage']] = None
+    tools: Optional[List['ModelTool']] = None
+    model_tool_choice: Optional['ModelToolChoice'] = None
+
+
+# ModelOutput is the output for model span, for tag key: output
+class ModelOutput(BaseModel):
+    choices: List['ModelChoice'] = []
+
+
+# ModelCallOption is the option for model span, for tag key: call_options
+class ModelCallOption(BaseModel):
+    temperature: float = 0.0
+    max_tokens: Optional[int] = None
+    stop: Optional[List[str]] = None
+    top_p: Optional[float] = None
+    n: Optional[int] = None
+    top_k: Optional[int] = None
+    presence_penalty: Optional[float] = None
+    frequency_penalty: Optional[float] = None
+    reasoning_effort: Optional[str] = None
+
+
+class ModelMessage(BaseModel):
+    role: str = ""                            # from enum VRole in span_value
+    content: Optional[str] = None             # single content
+    reasoning_content: Optional[str] = None   # only for output
+    parts: Optional[List['ModelMessagePart']] = None # multi-modality content
+    name: Optional[str] = None
+    tool_calls: Optional[List['ModelToolCall']] = None
+    tool_call_id: Optional[str] = None
+    metadata: Optional[Dict[str, str]] = None
+
+
+class ModelMessagePartType(str, Enum):
+    TEXT = "text"
+    IMAGE = "image_url"
+    FILE = "file_url"
+
+
+class ModelMessagePart(BaseModel):
+    type: ModelMessagePartType
+    text: Optional[str] = None
+    image_url: Optional['ModelImageURL'] = None
+    file_url: Optional['ModelFileURL'] = None
+
+
+class ModelImageURL(BaseModel):
+    name: Optional[str] = None
+    # Required. You can enter a valid image URL or MDN Base64 data of an image().
+    # MDN: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data#syntax
+    url: str = ""
+    detail: Optional[str] = None
+
+
+class ModelFileURL(BaseModel):
+    name: Optional[str] = None
+    # Required. You can enter a valid file URL or MDN Base64 data of file.
+    # MDN: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data#syntax
+    url: str = ""
+    detail: Optional[str] = None
+    suffix: Optional[str] = None
+
+
+class ModelToolCall(BaseModel):
+    id: Optional[str] = None
+    type: Optional[str] = None
+    function: Optional['ModelToolCallFunction'] = None
+
+
+class ModelToolCallFunction(BaseModel):
+    name: str = ""
+    arguments: Optional[str] = None
+
+
+class ModelTool(BaseModel):
+    type: str = "function"
+    function: Optional['ModelToolFunction'] = None
+
+
+class ModelToolFunction(BaseModel):
+    name: str = ""
+    description: str = ""
+    parameters: Optional[dict] = None
+
+
+class ModelChoice(BaseModel):
+    finish_reason: str = ""
+    index: int = 0
+    message: Optional['ModelMessage'] = None
+
+
+class ModelToolChoice(BaseModel):
+    type: str = ""                                       # from enum VToolChoice in span_value
+    function: Optional['ModelToolCallFunction'] = None   # field name only.

cozeloop/attribute/trace/prompt.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+from typing import List, Optional, Any
+
+from pydantic import BaseModel
+
+from cozeloop.attribute.trace.model import ModelMessage
+
+
+class PromptInput(BaseModel):
+    templates: Optional[List['ModelMessage']] = None
+    arguments: Optional[List['PromptArgument']] = None
+
+
+class PromptArgument(BaseModel):
+    key: str = ""
+    value: Optional[Any] = None
+
+
+class PromptOutput(BaseModel):
+    prompts: Optional[List['ModelMessage']] = None

cozeloop/attribute/trace/retriever.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+from typing import List, Optional
+from pydantic import BaseModel
+
+class RetrieverInput(BaseModel):
+    query: Optional[str] = None
+
+class RetrieverDocument(BaseModel):
+    id: Optional[str] = None
+    index: Optional[str] = None
+    content: str
+    vector: Optional[List[float]] = None
+    score: float
+
+class RetrieverOutput(BaseModel):
+    documents: Optional[List[RetrieverDocument]] = None
+
+class RetrieverCallOption(BaseModel):
+    top_k: Optional[int] = None
+    min_score: Optional[float] = None
+    filter: Optional[str] = None

cozeloop/attribute/trace/runtime.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+from typing import Optional
+from pydantic import BaseModel
+
+class Runtime(BaseModel):
+    language: Optional[str] = None # from enum VLang in span_value.go
+    library: Optional[str] = None  # integration library, from enum VLib in span_value.go
+    scene: Optional[str] = None  # usage scene, from enum VScene in span_value.go
+
+    # Dependency Versions.
+    library_version: Optional[str] = None
+    loop_sdk_version: Optional[str] = None

cozeloop/attribute/trace/span_key.py

@@ -0,0 +1,38 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+# Tags for model-type span.
+CALL_OPTIONS = "call_options" # Used to identify option for model, like temperature, etc. Recommend use ModelCallOption class.
+STREAM = "stream"             # Used to identify whether it is a streaming output.
+REASONING_TOKENS = "reasoning_tokens"   # The token usage during the reasoning process.
+REASONING_DURATION = "reasoning_duration" # The duration during the reasoning process, unit: microseconds.
+
+# Tags for retriever-type span
+RETRIEVER_PROVIDER = "retriever_provider" # Data retrieval providers, such as Elasticsearch (ES), VikingDB, etc.
+VIKINGDB_NAME = "vikingdb_name"      # When using VikingDB to provide retrieval capabilities, db name.
+VIKINGDB_REGION = "vikingdb_region"    # When using VikingDB to provide retrieval capabilities, db region.
+ES_NAME = "es_name"            # When using ES to provide retrieval capabilities, es name.
+ES_INDEX = "es_index"           # When using ES to provide retrieval capabilities, es index.
+ES_CLUSTER = "es_cluster"         # When using ES to provide retrieval capabilities, es cluster.
+
+# Tags for prompt-type span.
+PROMPT_PROVIDER = "prompt_provider" # Prompt providers, such as Loop, Langsmith, etc.
+PROMPT_KEY = "prompt_key"
+PROMPT_VERSION = "prompt_version"
+
+# Internal experimental field.
+# It is not recommended to use for the time being. Instead, use the corresponding Set method.
+SPAN_TYPE = "span_type"
+INPUT = "input"
+OUTPUT = "output"
+ERROR = "error"
+RUNTIME_ = "runtime"
+
+MODEL_PROVIDER = "model_provider"
+MODEL_NAME = "model_name"
+INPUT_TOKENS = "input_tokens"
+OUTPUT_TOKENS = "output_tokens"
+TOKENS = "tokens"
+MODEL_PLATFORM = "model_platform"
+MODEL_IDENTIFICATION = "model_identification"
+TOKEN_USAGE_BACKUP = "token_usage_backup"

cozeloop/attribute/trace/span_value.py

@@ -0,0 +1,38 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+# SpanType tag builtin values
+V_PROMPT_SPAN_TYPE = "prompt"
+V_MODEL_SPAN_TYPE = "model"
+V_RETRIEVER_SPAN_TYPE = "retriever"
+V_TOOL_SPAN_TYPE = "tool"
+
+V_ERR_DEFAULT = -1  # Default StatusCode for errors.
+
+# Tag values for model messages.
+V_ROLE_USER = "user"
+V_ROLE_SYSTEM = "system"
+V_ROLE_ASSISTANT = "assistant"
+V_ROLE_TOOL = "tool"
+
+# VToolChoiceNone Reference: https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages
+V_TOOL_CHOICE_NONE = "none"     # Means the model will not call any tool and instead generates a message.
+V_TOOL_CHOICE_AUTO = "auto"     # Means the model can pick between generating a message or calling one or more tools.
+V_TOOL_CHOICE_REQUIRED = "required"  # Means the model must call one or more tools.
+V_TOOL_CHOICE_FUNCTION = "function"  # Forces the model to call that tool.
+
+# Tag values for runtime tags.
+V_LANG_GO = "go"
+V_LANG_PYTHON = "python"
+V_LANG_TYPESCRIPT = "ts"
+
+V_LIB_EINO = "eino"
+V_LIB_LANGCHAIN = "langchain"
+
+V_SCENE_CUSTOM = "custom"          # user custom, it has the same meaning as blank.
+V_SCENE_PROMPT_HUB = "prompt_hub"      # get_prompt
+V_SCENE_PROMPT_TEMPLATE = "prompt_template"  # prompt_template
+
+# Tag values for prompt input.
+V_PROMPT_ARG_SOURCE_INPUT = "input"
+V_PROMPT_ARG_SOURCE_PARTIAL = "partial"

cozeloop/client.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# SPDX-License-Identifier: MIT
+
+from abc import ABC, abstractmethod
+
+from cozeloop.prompt import PromptClient
+from cozeloop.trace import TraceClient
+
+
+class Client(PromptClient, TraceClient, ABC):
+    """
+    Abstract base class for a thread-safe loop client.
+    Do not create multiple instances.
+    """
+
+    @property
+    @abstractmethod
+    def workspace_id(self) -> str:
+        """
+        Return the workspace ID.
+        """
+
+    @abstractmethod
+    def close(self):
+        """
+        Close the client. Should be called before program exit.
+        """
+