> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Python SDK

> Alephant Analytics Python SDK 的安装、配置和使用

官方 Alephant Analytics Python SDK 让 Python 脚本或数据科学 notebook 能够访问 Alephant Analytics API。它同时支持同步和异步执行。

## 安装

通过 pip 安装 SDK：

```bash
pip install alephantai-analytics-api
```

## 初始化

您可以根据架构初始化同步或异步客户端。

### 同步客户端

```python
import os
from alephant_logs_collector import (
    LogsCollectorAnalyticsClient,
    LogsCollectorAnalyticsClientEnvironment,
)

client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.DEVELOPMENT,
)
```

### 异步客户端

适用于 FastAPI、异步 Web 框架或高并发应用程序：

```python
import os
from alephant_logs_collector import (
    AsyncLogsCollectorAnalyticsClient,
    LogsCollectorAnalyticsClientEnvironment,
)

async_client = AsyncLogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.DEVELOPMENT,
)
```

## 使用示例

### 冒烟测试

使用公开 health 端点验证 SDK 能否连接到 Analytics 开发服务。

```python
response = client.analytics_atomic.get_health()
print(response.data.status)
```

### 实时 24 小时面板概览

获取展示热门模型和密钥的滚动实时 24 小时仪表板式面板。

```python
def fetch_live_summary():
    try:
        response = client.analytics_saas.get_saas_live24h(
            limit=5,
            authorization=f"Bearer {os.environ['ALEPHANT_API_TOKEN']}",
            x_workspace_id=os.environ["ALEPHANT_WORKSPACE_ID"],
        )
        print(response.data)
    except Exception as e:
        print(f"Failed to fetch live summary: {e}")
```

### 获取用量序列

获取指定日期范围内的每日用量指标。

```python
async def get_usage_series():
    response = await async_client.analytics_saas.get_saas_usage(
        date_from="2026-03-01",
        date_to="2026-03-31",
        authorization=f"Bearer {os.environ['ALEPHANT_API_TOKEN']}",
        x_workspace_id=os.environ["ALEPHANT_WORKSPACE_ID"],
    )

    print(response.data)
```

## 错误处理

任何产生 4xx 或 5xx 状态码的请求都会抛出与错误类型相对应的异常（`ApiError`、`RateLimitError` 等）。在 Python 中原生捕获它们以执行回退逻辑或指数退避。