AI Assistant Technical Documentation

プログラムの動作

AI_assistant.py は、ユーザーがOpenAI、Google Gemini、LM Studioなどの主要な生成AIモデルを直感的に操作できるように設計されたグラフィカルユーザーインターフェース (GUI) アプリケーションです。

プログラムの目的

複雑なAPI呼び出しを抽象化し、プログラミング知識がないユーザーでもテキストファイルの処理、コンテンツ生成、要約、翻訳といったAIタスクを容易に実行できる環境を提供することを目的としています。

主な機能

  • エディタとファイル管理: ユーザーは任意のテキストエディタの実行パスを指定でき、入力ファイルやAIの出力ファイルをそのエディタで直接開くことができます。入力テキストファイルの選択、読み込み(指定バイト数まで)、および出力ファイルの保存パスの指定が可能です。

  • AIプロバイダーとモデル選択: OpenAI、Google Gemini、LM StudioといったAIプロバイダーをリストボックスから選択し、各プロバイダーが提供する利用可能なAIモデルを動的に表示・選択できます。

  • プロンプト管理: roles.ini および prompt.ini という設定ファイルから、事前に定義された「役割 (Role)」と「プロンプトテンプレート (Prompt Template)」を読み込み、GUIで選択・適用できます。これにより、定型的なタスクのプロンプト作成を簡素化し、ユーザーは最終的なプロンプトをテキストエリアで自由に編集できます。入力ファイルの内容をプロンプトの {{text}} プレースホルダに挿入する機能も備えています。

  • AIクエリパラメータ設定: AIの応答を制御するためのTemperature(ランダム性)、Max Bytes(入力ファイルの最大読み込みサイズ)、Reasoning Effort(推論の深さ)、Verbosity(冗長性)といったパラメータをGUI上で設定できます。

  • 非同期クエリ実行: AIへのクエリ処理は別スレッドで実行されるため、APIからの応答待ちの間もGUIがフリーズすることなく、ユーザーは他の操作を行うことができます。

  • 設定の永続化: アプリケーションの終了時に現在の設定(エディタパス、ファイルパス、API/モデル選択、パラメータ、プロンプト内容など)を .ini ファイルに自動保存し、次回の起動時にその設定を復元します。

  • 文字コード自動検出: 入力ファイルや設定ファイル (.ini ファイル) を読み込む際に、chardet ライブラリを使用して文字コードを自動的に検出し、適切にデコードします。

解決する課題

  • AI利用の敷居を下げる: APIキーの設定やプログラミングを必要とせず、GUIを通じてAIを手軽に利用できるようにします。

  • プロンプトの再利用と効率化: 頻繁に利用するプロンプトや役割をINIファイルで管理し、GUIから簡単に適用できるようにすることで、作業効率を向上させます。

  • 異なるAIモデルへの対応: 複数のAIプロバイダーとモデルを統一されたインターフェースで扱えるようにすることで、ユーザーが目的に応じて最適なAIを選択しやすくなります。

  • 大規模テキスト処理の管理: Max Bytes の設定により、AIモデルの入力制限を考慮しつつ、大量のテキストデータの一部を効率的に処理できるようにします。

原理

本プログラムは、以下に示す技術やアルゴリズムを組み合わせて機能を実現しています。

  • GUIフレームワーク: Pythonの標準GUIライブラリである tkinter を基盤とし、ttkthemes ライブラリを併用することで、よりモダンで洗練されたウィジェットとテーマを提供しています。

  • AI連携: litellm ライブラリは、OpenAI、Google Gemini、LM Studio互換APIなど、多様な生成AIプロバイダーへのAPI呼び出しを抽象化するための中心的な役割を果たします。これにより、プログラムは各プロバイダー固有のAPIエンドポイント、認証メカニズム、リクエスト/レスポンス形式の違いを意識することなく、統一されたインターフェースでAIモデルと通信できます。カスタムライブラリ tkai_lib_litellm は、litellm のラッパーとして、環境変数からのAPIキー読み込み、AIクエリ実行、応答からのテキスト抽出といった補助的な機能を提供します。

  • プロンプト構築ロジック:

    • ユーザーがGUIで「Role (役割)」と「Prompt Template (プロンプトテンプレート)」を選択すると、それぞれの内容が結合され、「Current Prompt」テキストエリアに表示されます。

    • ユーザーが入力ファイルを指定し、かつプロンプトに {{text}} というプレースホルダが含まれている場合、入力ファイルのコンテンツ(Max Bytes で指定されたバイト数まで)が {{text}} の位置に挿入され、AIに送信される最終的なプロンプトが構築されます。

    • 「Verbosity (冗長性)」の設定は、AIへの指示文としてプロンプトの冒頭に追加されます。例えば「short」を選択すると、「回答はできるだけ簡潔に、要点のみを日本語で出力してください。」のような指示が自動で付加され、AIの応答スタイルを調整します。

  • 設定管理: Python標準ライブラリの configparser を使用して、アプリケーションの状態(エディタパス、ファイルパス、選択中のAPI/モデル、パラメータ、プロンプトテキストなど)を .ini ファイル (AI_assistant.ini) に保存および読み込みます。これにより、アプリケーションの再起動時に前回の作業状態が自動的に復元されます。

  • カスタムINIファイル読み込み: roles.ini および prompt.ini のようなカスタム設定ファイルは、プログラム独自の関数 load_ini_file によって読み込まれます。この関数は、desc="説明" の形式で定義された項目とその後の複数行のプロンプト本文を正しくパースし、辞書型リストとして格納します。

    • ファイル読み込み時には、chardet ライブラリを利用してファイルの文字コード(エンコーディング)を自動的に判別します。これにより、UTF-8、Shift_JIS、EUC-JPなど、様々なエンコーディングで保存されたINIファイルにも柔軟に対応できます。

  • 非同期処理: AIへのクエリは、threading モジュールを用いてバックグラウンドスレッド (run_query_logic) で実行されます。これにより、API応答待ちの間にGUIが応答不能になる「フリーズ」を防ぎ、ユーザーエクスペリエンスを向上させます。クエリ結果のGUIへの反映やエラーメッセージの表示は、メインスレッドの master.after メソッドを介して安全に行われます。

  • AIパラメータの制御:

    • Temperature (\(T\)): AIの出力のランダム性や創造性を調整するパラメータです。値が高いほど多様で予測不能な出力を生成し、低いほどより決定的で一貫性のある出力を生成します。 理論的には、言語モデルが出力する次のトークンの確率分布に影響を与えます。典型的なsoftmax関数を用いた確率計算は以下のようになります。 $\(\large P(w_i | \text{context}, T) = \frac{\exp(\text{logits}(w_i) / T)}{\sum_j \exp(\text{logits}(w_j) / T)}\)\( ここで、\)\text{logits}(w_i)\( はモデルが各トークン \)w_i\( に対して計算する生のスコア(ロジット)であり、\)T\( はTemperatureです。\)T > 1\( は分布を平坦にし、より多様な選択を促し、\)0 < T < 1$ は分布を尖鋭化させ、より確実な選択を促します。

    • Max Bytes: 入力ファイルから読み込む最大バイト数を指定するパラメータです。これは、AIモデルの多くが持つ入力トークン数の制限に対応するために重要であり、大規模なファイルを処理する際に全体のコンテンツを送る代わりに、冒頭部分のみを抽出して送ることでコストと処理時間を管理します。

    • Reasoning Effort: GPT-5系モデルや特定のLM Studioモデルで使用される、AIの推論の「深さ」を制御するパラメータです。low, medium, high, xhigh などの段階があり、temperature とは異なるアプローチでAIの思考プロセスに影響を与え、より複雑なタスクにおける応答の質を向上させることを目指します。

必要な非標準ライブラリとインストール方法

このプログラムを実行するには、以下のPython非標準ライブラリが必要です。

pip install ttkthemes chardet python-dotenv litellm
  • ttkthemes: tkinter アプリケーションにモダンなルック&フィールを提供します。

  • chardet: ファイルの文字コード(エンコーディング)を自動的に検出するために使用されます。

  • python-dotenv: .env ファイルから環境変数を読み込むために使用されます(tkai_lib_litellm 内部で利用)。

  • litellm: 複数の生成AIモデル(OpenAI, Google Gemini, LM Studioなど)への統一されたAPIインターフェースを提供します。

必要な入力ファイル

AI_assistant.py を実行するにあたり、以下の種類の入力ファイルが想定されています。

  1. テキストファイル(例: .txt, .py, .md など):

    • 目的: AIに処理させたいソースコンテンツ(コード、文章、レポート、データなど)。

    • 形式: プレーンテキスト。プログラムは Max Bytes で指定されたバイト数までファイルを読み込み、その内容をAIプロンプト内の {{text}} プレースホルダに挿入します。

    • 配置: 任意の場所に配置可能ですが、GUIの「Input Text File」フィールドでパスを指定する必要があります。

  2. 役割定義ファイル (roles.ini):

    • 目的: AIに与える役割やコンテキストを定義したプロンプトのプリセット。

    • 形式: AI_assistant.py と同じディレクトリに配置するINI形式のファイル。独自のフォーマットで記述します。

      • 行頭が # で始まる行はコメントとして無視されます。

      • desc="説明" という形式で役割の短い説明を定義し、その直後に続く複数行がその役割のプロンプト本文となります。

    • 例:

      # 一般的な要約の役割
      desc="文章の要約"
      以下の文章を要約してください。
      
      {{text}}
      
      # コードレビューの役割
      desc="コードのレビュー"
      以下のPythonコードをレビューし、改善点を提案してください。\n\n{{text}}
      
  3. プロンプトテンプレートファイル (prompt.ini):

    • 目的: AIに与える追加の指示やスタイルのテンプレート。

    • 形式: AI_assistant.py と同じディレクトリに配置するINI形式のファイル。roles.ini と同様の独自フォーマットで記述します。

    • 例:

      # 丁寧な言葉遣いを指示するテンプレート
      desc="丁寧な表現"
      常に丁寧な言葉遣いを心がけてください。
      
      # 専門的な表現を指示するテンプレート
      desc="専門的な表現"
      専門用語を適切に使用し、技術的な視点から記述してください。
      
  4. 環境設定ファイル (ai.env, translate.env またはシステム環境変数):

    • 目的: 各AIサービスへの認証に必要なAPIキーや、特定のAPIエンドポイント(例: LM Studio)のURLを設定します。

    • 形式: AI_assistant.py と同じディレクトリに配置する .env 形式のファイル、またはシステム環境変数として設定します。

    • 内容:

      • OPENAI_API_KEY: OpenAI APIの認証キー。

      • GEMINI_API_KEY または GOOGLE_API_KEY: Google Gemini APIの認証キー。

      • LMSTUDIO_API_BASE: LM Studio互換APIのエンドポイントURL (例: http://localhost:1234/v1)。

      • LMSTUDIO_MODEL: LM Studioで使用するデフォルトモデル名 (オプション)。

    • 例 (ai.env):

      OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      GEMINI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      LMSTUDIO_API_BASE="http://localhost:1234/v1"
      LMSTUDIO_MODEL="qwen/qwen3.8-27b"
      

生成される出力ファイル

AI_assistant.py の実行によって、以下のファイルが生成または更新されます。

  1. AI応答ファイル (.txt):

    • ファイル名: GUIの「Output File」フィールドでユーザーが指定したパスに保存されます。入力ファイルが選択されている場合、デフォルトで [入力ファイル名]-output.txt の形式で生成されます(例: my_document-output.txt)。

    • 内容: AIモデルが生成したテキスト応答が、UTF-8エンコーディングで保存されます。

    • 形式: AIの生成内容によりますが、通常はプレーンテキストです。

    • 配置: ユーザーが指定したパス。

  2. 設定保存ファイル (AI_assistant.ini):

    • ファイル名: AI_assistant.py スクリプトと同じディレクトリに AI_assistant.ini という名前で自動的に生成または更新されます。

    • 内容: アプリケーション終了時に、GUI上の全ての現在の設定(エディタパス、入力/出力ファイルパス、選択中のAPI/モデル、Temperature、Max Bytes、選択中の役割/プロンプトテンプレート、現在のプロンプトテキスト、Reasoning Effort、Verbosity)がINI形式で保存されます。次回の起動時にこのファイルが読み込まれ、以前の状態が復元されます。

    • 形式: 標準的なINIファイル形式です。

コマンドラインでの使用例 (Usage)

AI_assistant.py はGUIアプリケーションとして設計されているため、通常は引数なしで直接Pythonインタプリタを通じて実行します。

python AI_assistant.py

このコマンドを実行すると、AIアシスタントのGUIウィンドウが起動します。すべての操作は、このGUIを通じて行われます。

コマンドラインでの具体的な使用例

AI_assistant.py はコマンドライン引数を受け付けて動作を制御する設計ではありません。そのため、以下ではGUIアプリケーションとしての具体的な操作手順と、その結果得られる出力を例示します。

事前準備

  1. AIキーの設定:

    • プログラムと同じディレクトリに ai.env ファイルを作成し、使用するAIサービスのAPIキーを設定します。

      OPENAI_API_KEY="sk-your_openai_api_key_here"
      GEMINI_API_KEY="AIzaSy_your_gemini_api_key_here"
      LMSTUDIO_API_BASE="http://localhost:1234/v1" # LM Studioを使用する場合
      
    • または、システム環境変数としてこれらのキーを設定します。

  2. 入力ファイルの作成:

    • 以下の内容で my_document.txt というテキストファイルを作成し、プログラムと同じディレクトリに保存します。

      デジタル変革は現代ビジネスにおいて不可欠な要素となっています。クラウドコンピューティング、ビッグデータ分析、人工知能といった技術を活用し、企業は業務プロセスを最適化し、新たな顧客体験を創出しています。しかし、これらの技術導入にはセキュリティリスクや従業員のスキル再開発といった課題も伴います。
      

GUI操作例と実行結果

  1. プログラムの起動

    python AI_assistant.py
    

    AIアシスタントのGUIウィンドウが起動します。

  2. エディタの設定

    • 「Editor Executable」の「Browse」ボタンをクリックし、お好みのテキストエディタの実行ファイル(例: Notepad++ (notepad++.exe)、VS Code (code.exe または code))を選択します。例として C:\Program Files\Notepad++\notepad++.exe を設定します。

  3. 入力ファイルと出力ファイルの設定

    • 「Input Text File」の「Browse」ボタンをクリックし、作成した my_document.txt を選択します。

    • 「Output File」フィールドには、自動的に my_document-output.txt が設定されます。このパスは必要に応じて変更可能です。

  4. APIとモデルの選択

    • 「API」ドロップダウンリストから OpenAI を選択します。

    • 「Model」ドロップダウンリストから、例えば gpt-4o を選択します。

  5. 役割とプロンプトの設定

    • 「Role」ドロップダウンリストから 文章の要約 を選択します。これにより、「Current Prompt」テキストエリアに 以下の文章を要約してください。\n\n{{text}} が自動的に入力されます。

    • 「Prompt Template」ドロップダウンリストから 簡潔な表現 を選択します。これにより、「Current Prompt」テキストエリアの末尾に \n\n可能な限り簡潔に、要点のみをまとめてください。 が追加されます。

    • 「Current Prompt」の最終的な内容は以下のようになります。

      以下の文章を要約してください。
      
      {{text}}
      
      可能な限り簡潔に、要点のみをまとめてください。
      
  6. パラメータの設定

    • 「Temperature」を 0.5 に設定します。

    • 「Max Bytes」を 2048 に設定します。

    • 「Verbosity」を short に設定します。

  7. AIクエリの実行

    • 「Query AI」ボタンをクリックします。

    • ステータスバーに「Querying AI... Please wait.」→「Reading input file...」→「Sending query to AI...」→「Saving AI response...」と処理の進捗が表示されます。

    • 処理が完了すると、「成功」というメッセージボックスが表示され、「AIからの応答が my_document-output.txt に保存されました。」と通知されます。同時に、設定したエディタで my_document-output.txt が自動的に開かれます。

実行結果の例

my_document-output.txt の内容(AIの応答は変動する可能性があります):

デジタル変革はクラウド、ビッグデータ、AIを活用し業務最適化と新顧客体験創出を進めるが、セキュリティと従業員スキル再開発が課題です。

この出力は、指定された入力ファイルを「文章の要約」として処理し、「簡潔な表現」という指示と「short」というVerbosity設定に基づいて生成されたものです。