hiagent-observe 0.1.0__tar.gz

hiagent_observe-0.1.0/.gitignore

@@ -0,0 +1,169 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+chainlit.md
+.chainlit/
+.vscode
+.idea
+license.py

hiagent_observe-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: hiagent-observe
+Version: 0.1.0
+Summary: HiAgent Observe SDK
+Requires-Python: >=3.10
+Requires-Dist: hiagent-api<0.2.0,>=0.1.0
+Requires-Dist: opentelemetry-api>=1.33.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.33.1
+Requires-Dist: opentelemetry-sdk>=1.33.1
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: requests==2.32.3
+Description-Content-Type: text/markdown
+
+# HiAgent Observe SDK

hiagent_observe-0.1.0/README.md

@@ -0,0 +1 @@
+# HiAgent Observe SDK

hiagent_observe-0.1.0/hiagent_observe/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2024 Bytedance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+VERSION = "v0.1.0"

hiagent_observe-0.1.0/hiagent_observe/client.py

@@ -0,0 +1,123 @@
+# Copyright (c) 2024 Bytedance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import logging
+import time
+
+import requests
+from hiagent_api.observe import ObserveService, observe_types
+from hiagent_observe import VERSION
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.propagate import set_global_textmap
+from opentelemetry.propagators.composite import CompositePropagator
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.semconv.resource import ResourceAttributes
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+logger = logging.getLogger(__name__)
+
+
+class AuthSession(requests.Session):
+    def __init__(self, endpoint: str, ak: str, sk: str, workspace_id: str, app_id: str):
+        super().__init__()
+        self.workspace_id = workspace_id
+        self.app_id = app_id
+        self.token = None
+        self.expires_at = 0
+        self.observe_svc = ObserveService(endpoint=endpoint, region="cn-north-1")
+        self.observe_svc.set_ak(ak)
+        self.observe_svc.set_sk(sk)
+
+    def get_token(self) -> str:
+        token_resp = self.observe_svc.CreateApiToken(
+            observe_types.CreateApiTokenRequest(
+                WorkspaceID=self.workspace_id, CustomAppID=self.app_id
+            )
+        )
+        self.token = token_resp.Token
+
+        # 预留一些空间提前过期
+        self.expires_at = time.time() + token_resp.ExpiresIn - 100
+
+        return self.token
+
+    def is_token_expired(self):
+        return time.time() >= self.expires_at
+
+    def refresh_token_if_needed(self):
+        if not self.token or self.is_token_expired():
+            logger.debug("token expired or not set, refreshing...")
+            self.get_token()
+
+    def request(self, method, url, headers=None, **kwargs):
+        self.refresh_token_if_needed()
+
+        headers = headers or {}
+        headers["Authorization"] = f"Bearer {self.token}"
+        logger.debug(f"requesting {url} to export trace data")
+
+        response = super().request(method, url, headers=headers, **kwargs)
+
+        # 如果 token 失效，尝试重新获取并重试一次
+        if response.status_code == 401:
+            self.get_token()
+            headers["Authorization"] = f"Bearer {self.token}"
+            response = super().request(method, url, headers=headers, **kwargs)
+
+        return response
+
+
+def init(
+    trace_endpoint: str,
+    top_endpoint: str,
+    ak: str,
+    sk: str,
+    workspace_id: str,
+    app_id: str,
+):
+    auth_session = AuthSession(top_endpoint, ak, sk, workspace_id, app_id)
+
+    try:
+        token = auth_session.get_token()
+        logger.debug(f"got initial token: {token}")
+    except Exception as e:
+        raise RuntimeError(f"failed to get initial token: {e}")
+
+    exporter = OTLPSpanExporter(
+        endpoint=f"{trace_endpoint}/v1/traces", session=auth_session
+    )
+
+    resource = Resource.create(
+        {
+            ResourceAttributes.SERVICE_NAME: "HIAGENT_OBSERVE_SDK",
+            ResourceAttributes.SERVICE_VERSION: VERSION,
+        }
+    )
+    provider = TracerProvider(
+        resource=resource,
+    )
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+
+    set_global_textmap(
+        CompositePropagator(
+            [
+                TraceContextTextMapPropagator(),
+            ]
+        )
+    )
+
+    return provider

hiagent_observe-0.1.0/hiagent_observe/helper.py

@@ -0,0 +1,113 @@
+# Copyright (c) 2024 Bytedance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import logging
+from contextlib import contextmanager
+from functools import wraps
+from typing import Dict
+
+from hiagent_observe.semconv import SemanticConvention
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode
+
+
+def tracable(wrapped):
+    """
+    Generates a telemetry wrapper for messages to collect metrics.
+    """
+    if not callable(wrapped):
+        raise TypeError(
+            f"@trace can only be applied to callable objects, got {type(wrapped).__name__}"
+        )
+
+    try:
+        __trace = trace.get_tracer_provider()
+        tracer = __trace.get_tracer(__name__)
+    except Exception as tracer_exception:
+        logging.error(
+            "Failed to initialize tracer: %s", tracer_exception, exc_info=True
+        )
+        raise
+
+    @wraps(wrapped)
+    def wrapper(*args, **kwargs):
+        with tracer.start_as_current_span(
+            name=wrapped.__name__,
+            kind=SpanKind.CLIENT,
+        ) as span:
+            response = None
+            try:
+                response = wrapped(*args, **kwargs)
+                span.set_attribute(
+                    SemanticConvention.GEN_AI_CONTENT_COMPLETION, response or ""
+                )
+                span.set_status(Status(StatusCode.OK))
+            except Exception as e:
+                span.record_exception(e)
+                span.set_status(status=Status(StatusCode.ERROR), description=str(e))
+                logging.error("Error in %s: %s", wrapped.__name__, e, exc_info=True)
+                raise
+
+            try:
+                span.set_attribute("function.args", str(args))
+                span.set_attribute("function.kwargs", str(kwargs))
+                # span.set_attribute(
+                #     SERVICE_NAME,
+                #     OpenlitConfig.application_name,
+                # )
+                # span.set_attribute(DEPLOYMENT_ENVIRONMENT, OpenlitConfig.environment)
+            except Exception as meta_exception:
+                logging.error(
+                    "Failed to set metadata for %s: %s",
+                    wrapped.__name__,
+                    meta_exception,
+                    exc_info=True,
+                )
+
+            return response
+
+    return wrapper
+
+
+class TracedSpan:
+    def __init__(self, span: Span):
+        self._span: Span = span
+
+    def __enter__(self):
+        return self
+
+    def set_attribute(self, key: str, value: str):
+        self._span.set_attribute(key, value)
+        self._span.set_status(Status(StatusCode.OK))
+
+    def set_status(self, status: StatusCode, description: str):
+        self._span.set_status(status=status, description=description)
+
+    def set_attributes(self, attributes: Dict):
+        for key, value in attributes.items():
+            self.set_attribute(key, value)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._span.end()
+
+
+@contextmanager
+def start_trace(name: str, provider: TracerProvider):
+    if provider is None:
+        provider = trace.get_tracer_provider()
+    with provider.get_tracer(__name__).start_as_current_span(
+        name,
+        kind=SpanKind.CLIENT,
+    ) as span:
+        yield TracedSpan(span)

hiagent_observe-0.1.0/hiagent_observe/semconv/__init__.py

@@ -0,0 +1,208 @@
+# Copyright (c) 2024 Bytedance Ltd. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from enum import Enum
+
+
+class SpanType(Enum):
+    START = "start"
+    """
+    START 表示开始调用模型或者工作流
+    """
+    END = "end"
+    """
+    END 停止调用模型或者工作流
+    """
+    LLM = "llm"
+    """
+    LLM 大模型调用节点
+    """
+    QA = "qa"
+    """
+    QA 代表问答库调用节点
+    """
+    KNOWLEDGE = "knowledge"
+    """
+    KNOWLEDGE 代表知识库调用节点
+    """
+    WORKFLOW = "workflow"
+    """
+    WORKFLOW 代表工作流的调用节点
+    """
+    RERANK = "rerank"
+    """
+    RERANK 代表 rerank 模型调用节点
+    """
+    EMBEDDINGS = "embeddings"
+    """
+    EMBEDDINGS 代表向量化模型调用节点
+    """
+    TOOL = "tool"
+    """
+    TOOL 代表工具调用节点
+    """
+    TERMINLOGY = "terminology"
+    """
+    TOOL_CALL 代表术语库调用节点
+    """
+
+
+class SemanticConvention:
+    """
+    定义常用的语义化的属性
+    """
+
+    APP_ID: str = "app_id"
+    """
+    APP_ID 是应用中的保留字，不允许设置，如果设置，将会在 collector 中被覆盖为当前自定义应用的 ID
+    """
+
+    WORKSPACE_ID: str = "workspace_id"
+    """
+    WORKSPACE_ID 是工作区的保留字，是 HiAgent 平台内工作区的唯一标识符，如果设置，将会在 collector 中被覆盖为当前自定义应用所在工作区的 ID
+    """
+
+    USER_ID: str = "user_id"
+    """
+    USER_ID 当前会话的用户 ID
+    """
+
+    TENANT_ID: str = "tenant_id"
+    """
+    TENANT_ID 是当前会话的租户 ID
+    """
+
+    CONVERSATION_ID: str = "conversation_id"
+    """
+    Conversation ID 是会话的保留字，是用户在一个有完整上下文的会话唯一标识符
+    """
+
+    MESSAGE_ID: str = "message_id"
+    """
+    Message ID 是会话中的保留字，是用户在一个问答中的唯一标识符
+    """
+
+    MODEL_ID: str = "model_id"
+    """
+    Model ID 是在对话中使用的模型的 ID
+    """
+
+    MODEL_NAME: str = "model_name"
+    """
+    Model Name 是在对话中使用的模型名称
+    """
+
+    MODEL_PROVIDER: str = "model_provider"
+    """
+    Model Provider 是模型提供者的保留字，是模型提供者的名称
+    """
+
+    NODE_ID: str = "node_id"
+    """
+    Node ID 如果在工作流中则是工作流的节点 ID
+    """
+
+    WORKFLOW_ID: str = "workflow_id"
+    """
+    Workflow ID 如果在有工作流中的工作流 ID
+    """
+
+    TOP_P: str = "top_p"
+    """
+    TOP_P 是模型生成的概率阈值
+    """
+
+    TEMPERATURE: str = "temperature"
+    """
+    TEMPERATURE 是模型生成的温度阈值
+    """
+
+    TOP_K: str = "top_k"
+    """
+    TOP_K 是知识库的召回数量阈值
+    """
+
+    STREAM: str = "stream"
+    """
+    STREAM 是否是流式返回
+    """
+
+    SPAN_TYPE: str = "span_type"
+    """
+    SPAN_TYPE 是 span 的类型，用于在页面上拆分不同的展示类型
+    """
+
+    REQUEST_ID: str = "request_id"
+    """
+    Request ID 是请求的唯一标识符
+    """
+
+    LATENCY: str = "latency"
+    """
+    LATENCY 是请求的延迟时间，毫秒为单位
+    """
+
+    LATENCT_FIRST_RESP: str = "latency_first_resp"
+    """
+    LATENCT_FIRST_RESP 是首 token 的延迟时间，毫秒为单位
+    """
+
+    INPUT: str = "input"
+    """
+    INPUT 是用户输入
+    """
+
+    INPUT_RAW: str = "input_raw"
+    """
+    INPUT_RAW 是用户输入的原始数据
+    """
+
+    INPUT_TOKENS: str = "input_tokens"
+    """
+    INPUT_TOKENS 是用户输入的 token 数目
+    """
+
+    INPUT_PRICE: str = "input_price"
+    """
+    INPUT_PRICE 是用户输入的 token 价格
+    """
+
+    CURRENCY: str = "currency"
+    """
+    CURRENCY 是用户输入的货币类型，可选：RMB，USD
+    """
+
+    OUTPUT: str = "output"
+    """
+    OUTPUT 是模型生成的结果
+    """
+
+    OUTPUT_RAW: str = "output_raw"
+    """
+    OUTPUT_RAW 是模型生成的结果的原始数据
+    """
+
+    OUTPUT_TOKENS: str = "output_tokens"
+    """
+    OUTPUT_TOKENS 是模型生成的结果的 token 数目
+    """
+
+    OUTPUT_PRICE: str = "output_price"
+    """
+    OUTPUT_PRICE 是模型生成的结果的价格
+    """
+
+    PRICE_UNIT: str = "price_unit"
+    """
+    PRICE_UNIT 是模型生成的结果的价格单位
+    """

hiagent_observe-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "hiagent-observe"
+version = "0.1.0"
+description = "HiAgent Observe SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "opentelemetry-api>=1.33.1",
+    "opentelemetry-exporter-otlp-proto-http>=1.33.1",
+    "opentelemetry-sdk>=1.33.1",
+    "pydantic>=2.11.5",
+    "python-dotenv>=1.1.0",
+    "hiagent-api>=0.1.0,<0.2.0",
+    "requests==2.32.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "samples/",
+]
+
+[dependency-groups]
+dev = [
+    "chainlit>=2.2.1",
+]