Metadata-Version: 2.4
Name: sribd-analytics-sdk
Version: 0.1.1
Summary: Python SDK for SRIBD Analytics event ingestion
Requires-Python: >=3.9
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# SRIBD Analytics Python SDK

Python 后端接入 analytics-service 事件采集接口的轻量 SDK。

## 安装

本地开发：

```bash
pip install -e /Users/dongbucheng/workspace/projects/sribd-analytics/analytics-python-sdk
```

作为 Git 依赖接入时，将仓库地址替换为实际地址：

```bash
pip install "sribd-analytics-sdk @ git+ssh://git.example.com/sribd-analytics.git#subdirectory=analytics-python-sdk"
```

## 环境变量

```bash
ANALYTICS_ENABLED=true
ANALYTICS_BASE_URL=http://127.0.0.1:18080
ANALYTICS_SOURCE_SYSTEM=aiplatform
ANALYTICS_INGEST_API_KEY=dev-aiplatform-key
ANALYTICS_TIMEOUT_SECONDS=3
ANALYTICS_STRICT=false
```

`ANALYTICS_SOURCE_SYSTEM` 仅支持：

- `aiplatform`
- `aihub`

`ANALYTICS_STRICT=false` 是推荐默认值。采集服务异常时 SDK 会返回失败结果并记录 warning，不阻塞主业务。需要让业务显式感知失败时再设置为 `true`。

## 快速使用

```python
from sribd_analytics_sdk import AnalyticsClient

analytics = AnalyticsClient.from_env()

result = analytics.track(
    event_type="chat_completed",
    user_key=str(user.id),
    user_id=str(user.id),
    user_email=user.email,
    user_name=user.name,
    session_key=session_id,
    payload={
        "model": model_name,
        "prompt_tokens": 1200,
        "completion_tokens": 300,
    },
)

if not result.ok:
    logger.warning("analytics track failed: %s", result.error)
```

## 显式配置

```python
from sribd_analytics_sdk import AnalyticsClient

analytics = AnalyticsClient(
    base_url="http://127.0.0.1:18080",
    source_system="aihub",
    api_key="dev-aihub-key",
    timeout_seconds=2,
)
```

SDK 会自动补齐：

- `POST /v1/ingest/events`
- `X-API-Key`
- `schema_version=v1`
- `event_id`
- `occurred_at`

`base_url` 可以传服务根地址，也可以传已经带 `/v1` 的 API 前缀；SDK 不会重复拼接 `/v1`。

## 前后端调用边界

浏览器前端不要直接使用该 SDK，也不要持有 `ANALYTICS_INGEST_API_KEY`。前端需要埋点时，应调用本系统已有 Python 后端接口，由 Python 后端使用 SDK 上报 analytics-service。

## 目标源配置示例

aiplatform 后端：

```bash
ANALYTICS_SOURCE_SYSTEM=aiplatform
ANALYTICS_INGEST_API_KEY=dev-aiplatform-key
```

aihub 后端：

```bash
ANALYTICS_SOURCE_SYSTEM=aihub
ANALYTICS_INGEST_API_KEY=dev-aihub-key
```

## 返回值

`track()` 返回 `TrackResult`：

```python
TrackResult(
    ok=True,
    skipped=False,
    status_code=200,
    data={"code": 0, "message": "OK", "data": {...}},
    error=None,
)
```

关闭采集：

```bash
ANALYTICS_ENABLED=false
```

此时 `track()` 返回 `ok=True, skipped=True`，不会发起网络请求。
