# AITracer Python SDK

AIエージェント/LLMアプリの実行ログ・コスト・パフォーマンスを監視するためのPython SDK。

## 本番環境

- **API エンドポイント**: `https://api.aitracer.co`
- **ダッシュボード**: `https://app.aitracer.co`

SDKはデフォルトで `https://api.aitracer.co` に接続します。

## インストール

```bash
pip install aitracer
```

## クイックスタート

### 基本的な使い方

```python
from aitracer import AITracer
from openai import OpenAI

# AITracerを初期化
tracer = AITracer(
    api_key="at-xxxxxxxx",
    project="my-chatbot"
)

# OpenAIクライアントをラップ
client = tracer.wrap_openai(OpenAI())

# 普通に使う（自動でログが送信される）
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### Anthropic対応

```python
from aitracer import AITracer
from anthropic import Anthropic

tracer = AITracer(
    api_key="at-xxxxxxxx",
    project="my-chatbot"
)

# Anthropicクライアントをラップ
client = tracer.wrap_anthropic(Anthropic())

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### Google Gemini対応

```python
from aitracer import AITracer
import google.generativeai as genai

tracer = AITracer(
    api_key="at-xxxxxxxx",
    project="my-chatbot"
)

# Geminiを設定
genai.configure(api_key="your-google-api-key")
model = genai.GenerativeModel("gemini-1.5-flash")

# Geminiモデルをラップ
model = tracer.wrap_gemini(model)

response = model.generate_content("Hello!")
print(response.text)
```

ストリーミングも対応しています：

```python
response = model.generate_content("Write a story...", stream=True)
for chunk in response:
    print(chunk.text, end="")
```

### トレース機能

複数のAPI呼び出しをグループ化して追跡できます。

```python
with tracer.trace("user-query-123") as trace:
    # この中のAPI呼び出しは同じtrace_idでグループ化される
    response1 = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Summarize this..."}]
    )

    response2 = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Translate to Japanese..."}]
    )

    # メタデータを追加
    trace.set_metadata({
        "user_id": "user-456",
        "feature": "summarization"
    })

    # タグを追加
    trace.add_tag("production")
```

### ストリーミング対応

ストリーミングレスポンスも自動的にログされます。

```python
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a story..."}],
    stream=True
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

# ストリーム完了後に自動的にログが送信される
```

## 設定オプション

```python
tracer = AITracer(
    # 必須
    api_key="at-xxxxxxxx",      # または AITRACER_API_KEY 環境変数
    project="my-chatbot",        # または AITRACER_PROJECT 環境変数

    # オプション
    base_url="https://api.aitracer.co",  # APIエンドポイント（デフォルト）
    sync=False,                  # True: 同期送信（Lambda用）
    flush_on_exit=True,          # 終了時に未送信ログをフラッシュ
    batch_size=10,               # バッチサイズ
    flush_interval=5.0,          # 自動フラッシュ間隔（秒）
    enabled=True,                # False: ログ無効化（テスト用）
)
```

### Lambda/サーバーレス環境

サーバーレス環境では `sync=True` を使用してください。

```python
tracer = AITracer(
    api_key="at-xxxxxxxx",
    project="my-lambda",
    sync=True  # 同期送信
)
```

### 環境変数

```bash
export AITRACER_API_KEY=at-xxxxxxxx
export AITRACER_PROJECT=my-chatbot
```

```python
# 環境変数から自動で読み込み
tracer = AITracer()
```

## 手動ログ

自動ラッパーを使わずに手動でログを送信することもできます。

```python
tracer.log(
    model="gpt-4o",
    provider="openai",
    input_data={"messages": [{"role": "user", "content": "Hello"}]},
    output_data={"content": "Hi there!"},
    input_tokens=10,
    output_tokens=5,
    latency_ms=150,
    status="success",
    metadata={"user_id": "user-123"},
    tags=["production"]
)
```

## フラッシュとシャットダウン

```python
# 未送信のログを即座に送信
tracer.flush()

# シャットダウン（フラッシュ + リソース解放）
tracer.shutdown()
```

## ライセンス

Copyright (c) 株式会社HARO. All rights reserved.
