augllm 1.0__tar.gz

augllm-1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Shun Ogawa (a.k.a. "ToPo")
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

augllm-1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.1
+Name: augllm
+Version: 1.0
+Summary: ('A library for augmenting large language models',)
+Home-page: https://github.com/ToPo-ToPo-ToPo/augllm
+Author: Shun Ogawa (a.k.a. "ToPo")
+License: Apache License Version 2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# augllm
+
+[English README is here](./README.en.md)
+
+**augllm** は、Ollama を用いた拡張型（Augmented）大規模言語モデル（LLM）操作のためのラッパーライブラリです。  
+Function Calling による外部ツール利用のためのインターフェースを提供します。  
+ただし、ツール本体の実装は含まず、利用者が必要に応じて外部実装を組み込む形を想定しています。
+
+リポジトリ：  
+https://github.com/ToPo‑ToPo‑ToPo/augllm
+
+## 目次
+
+1. 特長 / 概要  
+2. 前提条件  
+3. インストール方法  
+4. 使い方  
+   - サンプルプログラム 
+   - Function Calling との連携  
+6. ライセンス  
+
+## 1. 特長 / 概要
+
+- Ollama を通じて LLM（ローカルまたはクラウド上）とやり取り  
+- Function Calling（関数呼び出し）形式でのツール連携をサポート  
+- ツールは抽象インターフェースとして定義されており、具体的な実装（API 呼び出し、ローカルスクリプト実行など）はユーザーが自由に実装可能  
+- 拡張性重視：カスタムツール、チェーン処理、プロンプト設計などへの組み込み容易  
+
+## 2. 前提条件
+
+- Python 3.8 以上  
+- Ollama コマンドラインや API クライアントが動作可能な環境  
+
+## 3. インストール方法
+1. 仮想環境の作成と起動
+
+以下を実行し、仮想環境を作成します。
+```
+python -m venv env
+```
+
+仮想環境を起動します。Macの場合は以下を実行します。
+```
+source env/bin/activate
+```
+
+2. ライブラリのインストール
+
+```bash
+pip install .
+```
+
+## 4. 使い方
+
+### サンプルプログラム
+リポジトリ内に `test/` ディレクトリがあります。中の2つのファイルを参考にしてください。
+
+### Function Calling との連携
+
+1. プロンプト内で、ツール呼び出しを期待する関数署名を与える  
+2. モデルから返ってきた関数呼び出し要求（ツール名 + 引数）を受け取り  
+3. 対応ツールインターフェースの `run(...)` を呼び出し、結果を受け取り  
+4. 結果をモデルに返して最終応答を得る  
+
+## 5. ライセンス
+
+このプロジェクトは **Apache‑2.0 ライセンス** のもとで公開されています。
+詳細は、[LICENSE](https://github.com/ToPo-ToPo-ToPo/augllm/blob/main/LICENSE)ファイルを確認してください。
+

augllm-1.0/README.md

@@ -0,0 +1,69 @@
+# augllm
+
+[English README is here](./README.en.md)
+
+**augllm** は、Ollama を用いた拡張型（Augmented）大規模言語モデル（LLM）操作のためのラッパーライブラリです。  
+Function Calling による外部ツール利用のためのインターフェースを提供します。  
+ただし、ツール本体の実装は含まず、利用者が必要に応じて外部実装を組み込む形を想定しています。
+
+リポジトリ：  
+https://github.com/ToPo‑ToPo‑ToPo/augllm
+
+## 目次
+
+1. 特長 / 概要  
+2. 前提条件  
+3. インストール方法  
+4. 使い方  
+   - サンプルプログラム 
+   - Function Calling との連携  
+6. ライセンス  
+
+## 1. 特長 / 概要
+
+- Ollama を通じて LLM（ローカルまたはクラウド上）とやり取り  
+- Function Calling（関数呼び出し）形式でのツール連携をサポート  
+- ツールは抽象インターフェースとして定義されており、具体的な実装（API 呼び出し、ローカルスクリプト実行など）はユーザーが自由に実装可能  
+- 拡張性重視：カスタムツール、チェーン処理、プロンプト設計などへの組み込み容易  
+
+## 2. 前提条件
+
+- Python 3.8 以上  
+- Ollama コマンドラインや API クライアントが動作可能な環境  
+
+## 3. インストール方法
+1. 仮想環境の作成と起動
+
+以下を実行し、仮想環境を作成します。
+```
+python -m venv env
+```
+
+仮想環境を起動します。Macの場合は以下を実行します。
+```
+source env/bin/activate
+```
+
+2. ライブラリのインストール
+
+```bash
+pip install .
+```
+
+## 4. 使い方
+
+### サンプルプログラム
+リポジトリ内に `test/` ディレクトリがあります。中の2つのファイルを参考にしてください。
+
+### Function Calling との連携
+
+1. プロンプト内で、ツール呼び出しを期待する関数署名を与える  
+2. モデルから返ってきた関数呼び出し要求（ツール名 + 引数）を受け取り  
+3. 対応ツールインターフェースの `run(...)` を呼び出し、結果を受け取り  
+4. 結果をモデルに返して最終応答を得る  
+
+## 5. ライセンス
+
+このプロジェクトは **Apache‑2.0 ライセンス** のもとで公開されています。
+詳細は、[LICENSE](https://github.com/ToPo-ToPo-ToPo/augllm/blob/main/LICENSE)ファイルを確認してください。
+

augllm-1.0/augllm/__init__.py

@@ -0,0 +1,10 @@
+
+from .augmented_llm import AugmentedLLM
+from .llm_interface import LLMInterface
+from .prompt_builder import PromptBuilder
+
+__all__ = [
+    "AugmentedLLM",
+    "LLMInterface",
+    "PromptBuilder",
+]

augllm-1.0/augllm/augmented_llm.py

@@ -0,0 +1,273 @@
+
+
+from typing import Optional
+from .make_image_paths import make_image_paths
+from .function_calling import register_tools, generate_system_prompt
+from .tool_handler import select_tool
+#===================================================================================
+# Coreの部分
+#===================================================================================
+class AugmentedLLM:
+
+    #---------------------------------------------------------------
+    # パラメータの初期化
+    #---------------------------------------------------------------
+    def __init__(self, llm, prompt_builder, cache_dir, tools=None, tool_selector_name="gemma3:4b"):
+
+        # LLMの設定
+        self.llm = llm
+        self.prompt_builder = prompt_builder
+        
+        # ツールの定義
+        self.tool_dict = register_tools(tools) if tools is not None else None
+        self.tool_selector_name = tool_selector_name
+        
+        # 内部データの保存先
+        self.cache_dir = cache_dir
+        
+        # 結果保存変数
+        self.report_text = None
+        self.report_images = None
+        self.report_data = None
+    
+    #---------------------------------------------------------------
+    # インスタンスを生成する関数
+    #---------------------------------------------------------------
+    @classmethod
+    def from_config(cls, agent_info, llm, prompt_builder, tools=None):
+        return cls(
+            name=agent_info['name'],
+            llm=llm,
+            prompt_builder=prompt_builder,
+            tools=tools,
+            max_chat_history=agent_info['max_chat_history']
+        )
+    
+    #---------------------------------------------------------------
+    # 
+    #---------------------------------------------------------------
+    def get_name(self) -> str:
+        return self.name
+    
+    #---------------------------------------------------------------
+    # ロードしたモデルを止める
+    #---------------------------------------------------------------
+    def free_model(self):
+        self.llm.free_model()
+    
+    #---------------------------------------------------------------
+    # ツール実行結果を整形して、LLMに渡すための最終的なメッセージを作成
+    #---------------------------------------------------------------
+    def build_messages_with_tool_result(self, system_prompt, tool_execution_results, memory, local_history):
+        
+        # 初期化
+        tool_results_summary_for_llm: Optional[str] = None
+        
+        # ツールの結果が何かある場合 YAML関連の応答 (コールあり、空コール、または処理中エラー)
+        if tool_execution_results is not None:
+            
+            # 実際にツールコールがあったか、処理中エラーがあった
+            if tool_execution_results:
+
+                # ツールの実行結果を整理 
+                formatted_results_list = []
+                for res in tool_execution_results:
+
+                    # データ取得
+                    func_name = res["name"]
+                    result_data = res["result"] # これはstatus, data, message を含む辞書
+
+                    # dataフィールドはmessageに含めるか、必要に応じて別途整形してLLMに渡す
+                    status = result_data.get("status", "unknown")
+                    message = result_data.get("message", "結果メッセージなし")
+                    images = result_data.get("images", None)  # ツールを実行した結果、画像が戻る場合がある
+                    
+                    # ツールの実行結果に関する追加プロンプト
+                    if status == "success":
+                        formatted_results_list.append(f"- {message}")
+                    # ツールの実行結果を無視する場合（検索したけど該当しなかったなど）
+                    elif status == "ignore":
+                        pass
+                    # Error or unknown                       
+                    else:
+                        print(f"- '{func_name}' の処理中に問題が発生しました。: {message}") 
+                
+                # ツールの実行結果がある場合はサマリーを作成
+                if formatted_results_list:
+                    tool_results_summary_for_llm = "以下の内部情報に基づき回答してください。：\n" + "\n".join(formatted_results_list)
+        
+        # システムプロンプトの指示に従い、ツール結果を 'user' ロールで履歴に追加
+        if tool_results_summary_for_llm:
+            # 文章の追加
+            local_history[0]["content"] += tool_results_summary_for_llm
+            # 画像の追加
+            if images:
+                #
+                image_paths = []
+                # 画像のパスの取得
+                query_image_paths = make_image_paths(user_images=images, cache_dir=self.cache_dir)
+                image_paths.extend(query_image_paths)
+                # メッセージに追加
+                local_history[0]["images"] = image_paths 
+        
+        # 最終応答のためのメッセージリストを作成
+        # historyには、ユーザープロンプト、LLMのツール試行応答、ツール結果の要約(あれば) が含まれる
+        messages = [system_prompt] + memory + local_history
+        
+        #
+        return messages
+    
+    #---------------------------------------------------------------
+    # LLMに渡すための最終的なメッセージを作成
+    #---------------------------------------------------------------
+    def build_messages(self, system_prompt, memory, local_history):
+        return [system_prompt] + memory + local_history
+    
+    #---------------------------------------------------------------
+    # LLMに渡すための最終的なメッセージを作成
+    #---------------------------------------------------------------
+    def build_user_message(self, text, images=None):
+        
+        # テキストの入力
+        user_message = {
+            "role": "user", 
+            "content": text
+        }
+
+        # 入力画像がある場合 通常の画像データ->画像のパスに変換
+        if images:
+            #
+            image_paths = []
+            # 画像のパスの取得
+            query_image_paths = make_image_paths(user_images=images, cache_dir=self.cache_dir)
+            image_paths.extend(query_image_paths)
+            # メッセージに追加
+            user_message["images"] = image_paths 
+        
+        return user_message
+    
+    #---------------------------------------------------------------
+    # 回答を生成
+    #---------------------------------------------------------------
+    def respond(self, user_text, user_images=None, memory=[], stream=False):
+        
+        # ユーザーの入力を整形
+        query_message = self.build_user_message(
+            text=user_text, 
+            images=user_images
+        )
+        
+        # 初期化
+        messages = None
+        local_history = None
+        
+        # 何かツールがある場合
+        if self.tool_dict:
+
+            # ルール呼び出し機能を持ったシステムプロンプトを作成
+            tool_select_prompt = generate_system_prompt(functions=self.tool_dict)
+            tool_select_system_prompt = {
+                "role": "system",
+                "content": f"{tool_select_prompt}"
+            }
+            
+            # LLMでツールを呼び出し、結果を取得
+            tool_execution_results = select_tool(
+                llm=self.llm,
+                tool_dict=self.tool_dict,
+                system_prompt=tool_select_system_prompt,
+                user_message=query_message
+            )
+
+            # 最終的なメッセージ作成のためlocal_historyを初期化
+            local_history = [query_message]
+            
+            # 最終的なメッセージに対するシステムプロンプト
+            system_prompt={
+                "role": "system",
+                "content": f"{self.prompt_builder.system_prompt_text}"
+            }
+            
+            # ツールの実行結果の整理と最終的なメッセージを作成
+            # local_historyを更新
+            messages = self.build_messages_with_tool_result(
+                system_prompt=system_prompt,
+                tool_execution_results=tool_execution_results,
+                memory=memory,
+                local_history=local_history
+            )
+        # ツールが全く定義されていない場合 -> 通常の回答生成
+        else:
+            # local_historyを初期化
+            local_history = [query_message]
+
+            # システムプロンプトを作成
+            system_prompt = {
+                "role": "system",
+                "content": f"{self.prompt_builder.system_prompt_text}"
+            }
+            
+            # 最終的なメッセージを作成
+            messages = self.build_messages(
+                system_prompt=system_prompt,
+                memory=memory,
+                local_history=local_history
+            )
+            
+        # 最終的な回答を生成
+        full_reply = ""
+        # ストリーミング出力
+        if stream:
+            found = False  # 何か返されたか確認
+            for chunk in self._stream_llm_response(messages=messages):
+                found = True
+                full_reply += chunk
+                yield chunk
+            if not found:
+                yield "[ストリーミング応答が得られませんでした]"            
+        # 通常の生成
+        else:
+            #
+            try:
+                reply = self.llm.chat(messages=messages)["message"]["content"]
+            except Exception as e:
+                yield f"[エラー: {str(e)}]"
+                return
+            #
+            full_reply = reply 
+            yield full_reply
+        
+        # 報告用のデータ作成
+        self.report_text = f"{full_reply}"
+        self.report_images = None
+        self.report_images = local_history[0].get("images", None)
+        self.report_data = None
+    
+    #---------------------------------------------------------------
+    # 
+    #---------------------------------------------------------------
+    def _stream_llm_response(self, messages):
+        try:
+            # 回答を生成
+            generator = self.llm.chat(messages=messages, stream=True)
+            if generator is None:
+                yield "[エラー: モデルがストリーミング応答を返しませんでした]"
+                return
+            #
+            any_chunk = False
+            for chunk in generator:
+                any_chunk = True
+                # 通常生成
+                if "message" in chunk and "content" in chunk["message"]:
+                    yield chunk["message"]["content"]
+                
+                # エラー情報をストリームで返す    
+                elif "error" in chunk:
+                    print(f"Error from llm response: {chunk['error']}")
+                    yield f"\n[エラー: {chunk['error']}]"
+
+            if not any_chunk:
+                yield "[エラー: モデルからの応答が空でした]" 
+        
+        except Exception as e:
+            yield f"[エラー発生: {str(e)}]"