この `tkai_lib.py` ライブラリの解析結果を以下に示します。

---

## `tkai_lib.py` ライブラリ解析

### 1) このライブラリの主な機能や目的

このライブラリ `tkai_lib.py` は、複数の大手AIサービス（OpenAIのGPTシリーズ、GoogleのGeminiシリーズ、DeepLの翻訳サービス）へのアクセスを統一的に提供することを目的としています。主な機能は以下の通りです。

*   **AIモデル呼び出しの抽象化**: OpenAI (Chat Completions API および Responses API) と Google Gemini API を介して、テキスト生成を行うための関数群を提供します。
*   **DeepL翻訳機能**: DeepL API を利用したテキスト翻訳機能を提供します。
*   **設定管理**: `.env` ファイルからAPIキーなどの環境変数を読み込む機能（`read_ai_config`）を持ち、APIキーの管理を容易にします。
*   **応答解析ヘルパー**: 各AIサービスからの応答をJSON形式に解析するためのヘルパー関数を提供します。
*   **依存関係のチェックと警告**: ライブラリのロード時に必要な非標準ライブラリがインストールされているかをチェックし、不足している場合は警告メッセージとインストールコマンドを表示します。

これにより、開発者は異なるAIサービス間のAPI呼び出しの違いを意識することなく、共通のインターフェースでAIモデルや翻訳サービスを利用できるようになります。

### 2) このライブラリを他のプログラムからimportする方法

`tkai_lib.py` がカレントディレクトリ、またはPythonのパスが通っているディレクトリに存在する場合、以下の方法で他のPythonプログラムからインポートできます。

**ライブラリ全体をインポートする場合:**

```python
import tkai_lib

# 例: 関数の呼び出し
tkai_lib.read_ai_config()
response_text, response_obj = tkai_lib.query(
    prompt="Hello, AI!",
    api="openai",
    api_key="YOUR_OPENAI_API_KEY",
    model="gpt-4o"
)
```

**特定の関数のみをインポートする場合:**

```python
from tkai_lib import query, read_ai_config

# 例: 関数の呼び出し
read_ai_config()
response_text, response_obj = query(
    prompt="Hello, AI!",
    api="openai",
    api_key="YOUR_OPENAI_API_KEY",
    model="gpt-4o"
)
```

### 3) 必要な非標準ライブラリとインストールコマンドとインストール方法

このライブラリは、以下の非標準ライブラリに依存しています。

| ライブラリ名 | 使用目的                 | インストールコマンド                           |
| :----------- | :----------------------- | :--------------------------------------------- |
| `python-dotenv` | 環境変数（.envファイル）の読み込み | `pip install python-dotenv`                    |
| `openai`     | OpenAI APIへのアクセス   | `pip install openai`                           |
| `google-generativeai` | Google Gemini APIへのアクセス | `pip install google-generativeai`              |
| `google-api-core` | Google APIのエラーハンドリング (`gexceptions`) | `pip install google-api-core`                  |
| `requests`   | HTTPリクエストの送信（DeepL API用） | `pip install requests`                         |

**インストール方法:**

これらのライブラリは、Pythonのパッケージマネージャーである `pip` を使用してインストールできます。

1.  **仮想環境の作成（推奨）**: プロジェクトごとにクリーンな環境を保つために、仮想環境を作成することをお勧めします。
    ```bash
    python -m venv venv
    ```
2.  **仮想環境のアクティベート**:
    *   Windows: `.\venv\Scripts\activate`
    *   macOS/Linux: `source venv/bin/activate`
3.  **ライブラリのインストール**: 上記の各インストールコマンドを実行します。
    ```bash
    pip install python-dotenv openai google-generativeai google-api-core requests
    ```
    または、個別にインストールすることも可能です。

    ```bash
    pip install python-dotenv
    pip install openai
    pip install google-generativeai
    pip install google-api-core
    pip install requests
    ```

**注記**:
`tkai_lib.py` をインポートまたは実行する際に、これらのライブラリがインストールされていない場合、コンソールに警告メッセージと `pip install` コマンドが表示され、`dotenv` と `requests` の場合はインストールを促すためにユーザー入力待ちになります。

### 4) importできる変数と関数

#### importできる変数

このライブラリには、グローバルスコープで直接定義され、インポートして利用できる**変数は存在しません**。

#### importできる関数

##### `read_ai_config(config_path: str = "translate.env", read_account_inf = True)`

*   **関数の動作**: 指定された設定ファイル（デフォルトは `translate.env`）から環境変数を読み込みます。また、`read_account_inf` が `True` の場合、その設定ファイル内で定義されている `account_inf_path` を参照し、さらにそのパスにあるアカウント情報ファイル（デフォルトは `accounts.env`）からも環境変数を読み込みます。これにより、APIキーなどの機密情報をコードに直接記述せず、`.env` ファイルで管理できます。
*   **引数**:
    *   `config_path` (str, オプション): メインの設定ファイルのパス。デフォルトは `"translate.env"`。
    *   `read_account_inf` (bool, オプション): `config_path` で指定されたファイルから `account_inf_path` を読み込み、さらにそのパスにあるファイルを読み込むかどうか。デフォルトは `True`。
*   **戻り値**: なし。環境変数をロードするサイドエフェクトがあります。

##### `openai_response_to_json(response)`

*   **関数の動作**: OpenAI Chat Completions API (`gpt-4o` など) からの応答オブジェクトを解析し、メッセージ内容をPythonのJSONオブジェクト（辞書またはリスト）として評価します。評価結果がリストまたはタプルであればその最初の要素と全体を、それ以外であればそのオブジェクトとそれを要素とするリストを返します。
*   **引数**:
    *   `response`: OpenAIの `client.chat.completions.create` メソッドが返す応答オブジェクト。`response.choices[0].message.content` にJSON形式の文字列が含まれていることを想定しています。
*   **戻り値**: `(first_item, full_list)` のタプル。`first_item` はJSON評価結果の最初の要素、`full_list` は評価結果全体（リストまたはタプルに変換したもの）。JSONが単一のオブジェクトだった場合、`first_item` はそのオブジェクト、`full_list` はそれを要素とするリストとなります。

##### `extract_openai5_text(response) -> str | None`

*   **関数の動作**: OpenAI Responses API (GPT-5系) からの応答オブジェクトから、主要なテキストコンテンツを抽出します。まず `response.output_text` プロパティを試み、利用可能であればそれを返します。それがなければ、`response.output` 配列をイテレートし、タイプが "message" で、内容に "output_text" のタイプを持つテキスト要素があれば、それらを結合して返します。
*   **引数**:
    *   `response`: OpenAIの `client.responses.create` メソッドが返す応答オブジェクト。
*   **戻り値**: 抽出されたテキスト (`str`)、またはテキストが見つからなかった場合は `None`。

##### `openai5_response_to_json(response)`

*   **関数の動作**: OpenAI Responses API (GPT-5系) からの応答オブジェクトを解析し、`extract_openai5_text` を使ってテキストを抽出し、そのテキストをPythonのJSONオブジェクトとして評価します。`openai_response_to_json` と同様の形式で結果を返します。
*   **引数**:
    *   `response`: OpenAIの `client.responses.create` メソッドが返す応答オブジェクト。
*   **戻り値**: `(first_item, full_list)` のタプル。`first_item` はJSON評価結果の最初の要素、`full_list` は評価結果全体（リストまたはタプルに変換したもの）。JSONが単一のオブジェクトだった場合、`first_item` はそのオブジェクト、`full_list` はそれを要素とするリストとなります。

##### `google_response_to_json(response)`

*   **関数の動作**: Google Gemini APIからの応答オブジェクトを解析し、`response.text` に含まれるテキスト内容をPythonのJSONオブジェクトとして評価します。`openai_response_to_json` と同様の形式で結果を返します。
*   **引数**:
    *   `response`: Google Geminiの `model.generate_content` メソッドが返す応答オブジェクト。`response.text` にJSON形式の文字列が含まれていることを想定しています。
*   **戻り値**: `(first_item, full_list)` のタプル。`first_item` はJSON評価結果の最初の要素、`full_list` は評価結果全体（リストまたはタプルに変換したもの）。JSONが単一のオブジェクトだった場合、`first_item` はそのオブジェクト、`full_list` はそれを要素とするリストとなります。

##### `query_openai4(prompt, openai_model = "gpt-4o", role = None, response_format = None, temperature = 0.7, max_tokens = 1000, openai_api_key = None)`

*   **関数の動作**: OpenAI Chat Completions API (例: `gpt-4o`) を呼び出し、指定されたプロンプトに対してテキスト応答を生成します。APIキーは引数で渡すか、環境変数 `OPENAI_API_KEY` から取得します。システムロールや応答フォーマット、生成パラメータ（温度、最大トークン数）を設定できます。
*   **引数**:
    *   `prompt` (str): LLMに与えるユーザープロンプト。
    *   `openai_model` (str, オプション): 使用するOpenAIモデルの名前。デフォルトは `"gpt-4o"`。
    *   `role` (str \| None, オプション): システムメッセージとしてLLMに与える役割テキスト。デフォルトは `None` (ユーザープロンプトのみ)。
    *   `response_format` (dict \| None, オプション): 応答のフォーマットを指定する辞書。例: `{"type": "json_object"}`。
    *   `temperature` (float, オプション): 生成される応答のランダム性（0.0: 決定的、1.0: ランダム性が高い）。デフォルトは `0.7`。
    *   `max_tokens` (int, オプション): 応答で生成される最大のトークン数。デフォルトは `1000`。
    *   `openai_api_key` (str \| None, オプション): OpenAI APIキー。指定しない場合、環境変数 `OPENAI_API_KEY` から取得を試みます。
*   **戻り値**: 成功した場合、OpenAIのAPI応答オブジェクト。API呼び出しに失敗した場合やAPIキーが設定されていない場合は `False` または空の辞書 `{}`。

##### `query_openai5(prompt, openai_model="gpt-5", instructions=None, role=None, effort="minimal", max_output_tokens=1024, store=False, response_format=None, openai_api_key=None)`

*   **関数の動作**: OpenAI Responses API (GPT-5系) を呼び出し、指定されたプロンプトに対してテキスト応答を生成します。APIキーは引数で渡すか、環境変数 `OPENAI_API_KEY` から取得します。システム指示 (`instructions`)、努力レベル (`effort`)、最大出力トークン数、応答フォーマットなど、`query_openai4` よりもResponses APIに特化した詳細な設定が可能です。
*   **引数**:
    *   `prompt` (str \| list): LLMに与えるプロンプト。文字列、またはResponses APIの入力形式に準拠したオブジェクトのリスト。
    *   `openai_model` (str, オプション): 使用するOpenAIモデルの名前。デフォルトは `"gpt-5"`。
    *   `instructions` (str \| None, オプション): システム相当の一括方針。
    *   `role` (str \| None, オプション): `prompt` が文字列の場合に適用される、"system" や "user" などの役割。
    *   `effort` (str, オプション): 応答生成における努力レベル ("minimal", "low", "medium", "high")。デフォルトは `"minimal"`。
    *   `max_output_tokens` (int, オプション): 出力トークン上限。デフォルトは `1024`。
    *   `store` (bool, オプション): 応答を保存するかどうか。デフォルトは `False`。
    *   `response_format` (dict \| None, オプション): JSONモードや構造化出力を使う場合の辞書。例: `{"type": "json_object"}`。
    *   `openai_api_key` (str \| None, オプション): OpenAI APIキー。指定しない場合、環境変数 `OPENAI_API_KEY` から取得を試みます。
*   **戻り値**: 成功した場合、OpenAIのAPI応答オブジェクト。API呼び出しに失敗した場合やAPIキーが設定されていない場合は `None`。

##### `query_google(prompt, google_model = "gemini-2.5-flash", role = None, generation_config = None, google_api_key = None)`

*   **関数の動作**: Google Gemini API (例: `gemini-2.5-flash`) を呼び出し、指定されたプロンプトに対してテキスト応答を生成します。APIキーは引数で渡すか、環境変数 `GOOGLE_API_KEY` から取得します。システムロールや応答生成設定 (`generation_config`) を指定できます。
*   **引数**:
    *   `prompt` (str): LLMに与えるユーザープロンプト。
    *   `google_model` (str, オプション): 使用するGoogle Geminiモデルの名前。デフォルトは `"gemini-2.5-flash"`。
    *   `role` (str \| None, オプション): システムメッセージとしてLLMに与える役割テキスト。デフォルトは `None` (ユーザープロンプトのみ)。
    *   `generation_config` (dict \| None, オプション): 応答生成の設定。例: `{"response_mime_type": "application/json"}`。
    *   `google_api_key` (str \| None, オプション): Google APIキー。指定しない場合、環境変数 `GOOGLE_API_KEY` から取得を試みます。
*   **戻り値**: 成功した場合、Google GeminiのAPI応答オブジェクト。API呼び出しに失敗した場合やAPIキーが設定されていない場合は `False` または空の辞書 `{}`。

##### `query_google2(messages, google_model = "gemini-2.5-flash", generation_config = None, safety_settings = None, google_api_key = None)`

*   **関数の動作**: Google Gemini APIを呼び出し、指定されたメッセージのリストに対してテキスト応答を生成します。`query_google` よりも詳細な `generation_config` (温度、top_p, top_k, 最大出力トークン数など) や `safety_settings` (ハラスメント、ヘイトスピーチなどのブロック設定) がデフォルトで設定されており、細かく制御できます。APIキーは引数で渡すか、環境変数 `GOOGLE_API_KEY` から取得します。
*   **引数**:
    *   `messages` (list): LLMに与えるメッセージのリスト。`{"role": "user", "parts": ["..."]}` のような形式。
    *   `google_model` (str, オプション): 使用するGoogle Geminiモデルの名前。デフォルトは `"gemini-2.5-flash"`。
    *   `generation_config` (dict \| None, オプション): 応答生成の設定。デフォルト値が内部で定義されています。
    *   `safety_settings` (list \| None, オプション): 安全性設定。デフォルト値が内部で定義されています。
    *   `google_api_key` (str \| None, オプション): Google APIキー。指定しない場合、環境変数 `GOOGLE_API_KEY` から取得を試みます。
*   **戻り値**: 成功した場合、Google GeminiのAPI応答オブジェクト。API呼び出しに失敗した場合、クォータ超過、またはプロンプトがブロックされた場合は `None`。

##### `extract_deepl_text(response) -> str | None`

*   **関数の動作**: DeepL APIからの `requests` 応答オブジェクトを解析し、翻訳されたテキストを抽出します。HTTPステータスコードが200 (OK) の場合のみ処理します。
*   **引数**:
    *   `response`: `requests` ライブラリが返す応答オブジェクト。
*   **戻り値**: 翻訳されたテキスト (`str`)、またはAPIエラー（ステータスコードが200以外）の場合は `None`。

##### `query_deepl(text, source_lang = "JA", target_lang = "EN", deepl_api_key = None, endpoint = "free")`

*   **関数の動作**: DeepL APIを呼び出し、指定されたテキストを翻訳します。APIキーは引数として明示的に渡す必要があります。フリー版とプロ版のエンドポイントを選択できます。DeepL APIにXMLタグを無視させる設定（`tag_handling="xml"`）がデフォルトで含まれています。
*   **引数**:
    *   `text` (str): 翻訳するテキスト。
    *   `source_lang` (str, オプション): 元の言語コード（例: "JA", "EN"）。デフォルトは `"JA"`。
    *   `target_lang` (str, オプション): 翻訳先の言語コード（例: "EN", "FR"）。デフォルトは `"EN"`。
    *   `deepl_api_key` (str \| None, オプション): DeepL APIキー。この関数は環境変数からは読み込みません。
    *   `endpoint` (str, オプション): DeepL APIのエンドポイント。"free" または "pro" を指定。デフォルトは `"free"`。
*   **戻り値**: 成功した場合、`requests` ライブラリが返す応答オブジェクト。API呼び出しに失敗した場合やエラーが発生した場合は `None`。

##### `query(prompt: str, api: str, api_key: str, model: str)`

*   **関数の動作**: 指定されたAIサービス (`gemini`/`google`, `openai5`, `openai`) とモデルを使用して、プロンプトに対するテキスト応答を生成する汎用関数です。内部で各サービスのAPI呼び出し関数をラップしています。
*   **引数**:
    *   `prompt` (str): LLMに与えるプロンプト。
    *   `api` (str): 使用するAIサービスの名前。`"gemini"` または `"google"` (Google Gemini API)、`"openai5"` (OpenAI Responses API)、`"openai"` (OpenAI Chat Completions API) のいずれか。
    *   `api_key` (str): 使用するAPIのキー。
    *   `model` (str): 使用するモデルの名前（例: `"gemini-2.5-flash"`, `"gpt-4o"`, `"gpt-5"`）。
*   **戻り値**: `(text, response_object)` のタプル。`text` は生成されたテキスト (`str`)、`response_object` はAPIから返された生の応答オブジェクト。API呼び出しに失敗した場合や未対応のAPIが指定された場合は `(None, None)`。

### 5) main scriptとして実行したときの動作

この `tkai_lib.py` ファイルには、`if __name__ == "__main__":` ブロックが記述されていません。
したがって、このファイルを単独でPythonインタープリタによって直接実行しても、特定の処理やデモンストレーションは行われません。

ただし、ライブラリの**ロード時**（`import tkai_lib` が実行された時）には、冒頭の `try-except` ブロックに従って、必要な非標準ライブラリ（`dotenv`, `openai`, `google.generativeai`, `google.api_core`, `requests`）がインストールされているかのチェックが行われます。もしインストールされていないライブラリがあれば、その場でコンソールに警告メッセージと `pip install` コマンドが出力されます。特に `dotenv` と `requests` の場合は、ユーザーにインストールを促す `input()` 関数が呼び出され、何かキーを押すまでプログラムの実行が一時停止します。

例：
```bash
python tkai_lib.py
```
上記コマンドを実行しても、ライブラリロード時の依存関係チェックと警告表示以外には何も出力されず、即座に終了します（もし必要なライブラリが全てインストールされていれば、何も出力されません）。