optimize code comments.

Author: JDOxygen

examples/a2a/agentscope_interop/demo_agentscope_a2a_server.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """AgentScope A2A server demo.
 
 Run:

examples/a2a/google_sdk_interop/demo_google_sdk_a2a_server.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """Minimal Google A2A SDK server demo (local).
 
 Run:

function_hubs/shortest_path.py

@@ -1,23 +1,25 @@
-#!/usr/bin/env python3
 """
 使用 Google OR-Tools 解决最短路径问题的示例
 
 这个示例展示了如何使用 OR-Tools 的图算法来解决城市间的最短路径问题。
 """
 
-from ortools.graph.python import min_cost_flow
 import time
+
 import matplotlib.pyplot as plt
 import networkx as nx
 import pandas as pd
+from ortools.graph.python import min_cost_flow
+
 from oxygent import oxy
 
-shortest_path_tools = oxy.FunctionHub(
-    name="shortest_path_tools")
+shortest_path_tools = oxy.FunctionHub(name="shortest_path_tools")
 column_data = {}
 
 
-@shortest_path_tools.tool(description="Update city and distance information based on Excel.")
+@shortest_path_tools.tool(
+    description="Update city and distance information based on Excel."
+)
 async def info_update(file_path, sheet_name=0):
     # 读取 Excel 文件
     df = pd.read_excel(file_path, sheet_name=sheet_name)
@@ -35,16 +37,18 @@ async def info_update(file_path, sheet_name=0):
     return "File is Empty"
 
 
-@shortest_path_tools.tool(description="A tool that can calculate the shortest path between different points")
+@shortest_path_tools.tool(
+    description="A tool that can calculate the shortest path between different points"
+)
 async def shortest_path(start_city: str, end_city):
     # 城市列表
-    city_to_index = {city: i for i, city in enumerate(column_data['cities'])}
+    city_to_index = {city: i for i, city in enumerate(column_data["cities"])}
     print(start_city, end_city)
 
-    cities = column_data['cities']
-    start_cities = column_data['start_cities']
-    end_cities = column_data['end_cities']
-    distances = column_data['distances']
+    cities = column_data["cities"]
+    start_cities = column_data["start_cities"]
+    end_cities = column_data["end_cities"]
+    distances = column_data["distances"]
     # 转换城市名称为索引
     start_nodes = [city_to_index[city] for city in start_cities]
     end_nodes = [city_to_index[city] for city in end_cities]
@@ -54,9 +58,11 @@ async def shortest_path(start_city: str, end_city):
     # 添加每条边到图中 (注意：我们需要添加双向边，因为城市之间的道路是双向的)
     for i in range(len(start_nodes)):
         sp_func.add_arc_with_capacity_and_unit_cost(
-            start_nodes[i], end_nodes[i], 1, distances[i])
+            start_nodes[i], end_nodes[i], 1, distances[i]
+        )
         sp_func.add_arc_with_capacity_and_unit_cost(
-            end_nodes[i], start_nodes[i], 1, distances[i])
+            end_nodes[i], start_nodes[i], 1, distances[i]
+        )
 
     # 设置起点和终点的供应/需求
     sp_func.set_node_supply(city_to_index[start_city], 1)  # 起点
@@ -133,20 +139,24 @@ def visualize_city_path(cities, start_cities, end_cities, distances, path):
         for u, v in path:
             path_edges.append((cities[u], cities[v]))
 
-        nx.draw_networkx_edges(G, city_positions, edgelist=path_edges, width=3, edge_color='r')
+        nx.draw_networkx_edges(
+            G, city_positions, edgelist=path_edges, width=3, edge_color="r"
+        )
 
         # 绘制节点
-        nx.draw_networkx_nodes(G, city_positions, node_size=700, node_color='lightblue')
+        nx.draw_networkx_nodes(G, city_positions, node_size=700, node_color="lightblue")
 
         # 绘制节点标签
-        nx.draw_networkx_labels(G, city_positions, font_size=12, font_family='SimHei')
+        nx.draw_networkx_labels(G, city_positions, font_size=12, font_family="SimHei")
 
         # 绘制边权重
-        edge_labels = nx.get_edge_attributes(G, 'weight')
-        nx.draw_networkx_edge_labels(G, city_positions, edge_labels=edge_labels, font_size=8)
+        edge_labels = nx.get_edge_attributes(G, "weight")
+        nx.draw_networkx_edge_labels(
+            G, city_positions, edge_labels=edge_labels, font_size=8
+        )
 
-        plt.title("中国城市间最短路径", fontsize=16, fontfamily='SimHei')
-        plt.axis('off')
+        plt.title("中国城市间最短路径", fontsize=16, fontfamily="SimHei")
+        plt.axis("off")
         plt.tight_layout()
         plt.savefig("city_shortest_path.png")
         print("\n城市路径图已保存为 'city_shortest_path.png'")

oxygent/__init__.py

@@ -1,3 +1,8 @@
+"""OxyGent -- Multi-Agent System framework.
+
+Public API surface re-exported for convenience.
+"""
+
 from dotenv import load_dotenv
 
 from .config import Config

oxygent/banner.py

@@ -1,3 +1,5 @@
+"""ASCII art banners for the OxyGent startup display."""
+
 oxygent_larry3d = """
  _____                    ____                   __      
 /\  __`\                 /\  _`\                /\ \__   

oxygent/config.py

@@ -1,4 +1,10 @@
-"""Configuration settings for the MAS."""
+"""Centralized configuration singleton for the OxyGent framework.
+
+Loads settings from ``config.json`` with environment-based layering (``default``
+then ``APP_ENV``), supports ``${VAR}`` environment-variable substitution, and
+exposes typed getter/setter methods grouped by domain (app, log, LLM, agent,
+tool, server, Elasticsearch, Redis, message, token tracking, etc.).
+"""
 
 import json
 import logging

oxygent/core_tools/retrieve_tools.py

@@ -1,7 +1,7 @@
-"""Tool Retrieval Module.
+"""Semantic tool retrieval via vector similarity search.
 
-This file demonstrates the structure of the 'retrieve_tools', which can select
-appropriate functions for an agent based on specific circumstances and requirements.
+Provides a FunctionHub tool that queries a Vearch vector database to find
+the most relevant tools for a given query, filtered by application and agent.
 """
 
 from typing import Any

oxygent/databases/base_db.py

@@ -1,7 +1,7 @@
-"""base_db.py Base Database Class Module.
+"""Base database service class with retry and error handling.
 
-This file defines the base class for database services, providing common functionality
-such as retry mechanisms and error handling for database operations.
+Defines the abstract base class for all database services, providing common
+functionality such as configurable retry mechanisms and error handling.
 """
 
 import asyncio

oxygent/databases/db_es/__init__.py

@@ -1,3 +1,5 @@
+"""Elasticsearch database backends (JES, local filesystem, in-memory)."""
+
 from .jes_es import JesEs
 from .local_es import LocalEs
 from .memory_es import MemoryEs

oxygent/databases/db_es/base_es.py

@@ -1,7 +1,7 @@
-"""base_es.py Base Elasticsearch Database Class Module.
+"""Abstract base class for Elasticsearch database services.
 
-This file defines the abstract base class for Elasticsearch database services,
-inheriting from BaseDB and providing the interface contract for ES operations.
+Inherits from BaseDB and defines the interface contract for Elasticsearch
+operations including index management, document CRUD, and search queries.
 """
 
 import logging