diff --git a/.github/workflows/run_regressions.yml b/.github/workflows/run_regressions.yml index 997682c9..fe96e952 100644 --- a/.github/workflows/run_regressions.yml +++ b/.github/workflows/run_regressions.yml @@ -22,6 +22,11 @@ jobs: python -m pip install --upgrade pip pip3 install -e . + - name: Setup Git LFS + run: | + git lfs install + git lfs pull + - name: Run regression tests run: | pytest -m regression diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4fcc8f34..36688a8e 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,22 +10,12 @@ build: os: ubuntu-22.04 tools: python: "3.9" - # You can also specify other tool versions: - # nodejs: "19" - # rust: "1.64" - # golang: "1.19" # Build documentation in the "docs/" directory with Sphinx sphinx: - configuration: automata/docs/conf.py -# Optionally build your docs in additional formats such as PDF and ePub -# formats: -# - pdf -# - epub + configuration: docs/conf.py -# Optional but recommended, declare the Python requirements required -# to build your documentation -# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +# Specify requirements python: install: - - requirements: automata/docs/requirements.txt + - requirements: docs/requirements.txt diff --git a/README.md b/README.md index dd4a6be6..1a1cc70a 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,10 @@ ![Banner](https://github.com/emrgnt-cmplxty/Automata/assets/68796651/61fe3c33-9b7a-4c1b-9726-a77140476b83) [![codecov](https://codecov.io/github/emrgnt-cmplxty/Automata/branch/main/graph/badge.svg?token=ZNE7RDUJQD)](https://codecov.io/github/emrgnt-cmplxty/Automata) + + License + | [![Documentation Status](https://readthedocs.org/projects/automata/badge/?version=latest)](https://automata.readthedocs.io/en/latest/?badge=latest) -[![Type Checking](https://github.com/emrgnt-cmplxty/Automata/actions/workflows/check-mypy.yml/badge.svg)](https://github.com/emrgnt-cmplxty/Automata/actions/workflows/check-mypy.yml) [![Discord](https://img.shields.io/discord/1120774652915105934?logo=discord)](https://discord.gg/j9GxfbxqAe) [![Twitter Follow](https://img.shields.io/twitter/follow/ocolegro?style=social)](https://twitter.com/ocolegro) @@ -105,10 +107,10 @@ Sometimes the best way to understand a complicated system is to start by underst from automata.config.base import AgentConfigName from automata.config.openai_agent import OpenAIAutomataAgentConfigBuilder -from automata.core.agent.providers import OpenAIAutomataAgent -from automata.core.singletons.dependency_factory import dependency_factory -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.tools.factory import AgentToolFactory +from automata.agent.providers import OpenAIAutomataAgent +from automata.singletons.dependency_factory import dependency_factory +from automata.singletons.py_module_loader import py_module_loader +from automata.tools.factory import AgentToolFactory # Initialize the module loader to the local directory py_module_loader.initialize() @@ -147,10 +149,10 @@ Code example for creating an instance of 'SymbolCodeEmbedding': ```python import numpy as np -from automata.core.symbol_embedding.base import SymbolCodeEmbedding -from automata.core.symbol.parser import parse_symbol +from automata.symbol_embedding.base import SymbolCodeEmbedding +from automata.symbol.parser import parse_symbol -symbol_str = 'scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.agent.agent_enums`/ActionIndicator#' +symbol_str = 'scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#' symbol = parse_symbol(symbol_str) source_code = 'symbol_source' vector = np.array([1, 0, 0, 0]) @@ -161,8 +163,8 @@ embedding = SymbolCodeEmbedding(symbol=symbol, source_code=source_code, vector=v Code example for creating an instance of 'SymbolDocEmbedding': ```python -from automata.core.symbol_embedding.base import SymbolDocEmbedding -from automata.core.symbol.parser import parse_symbol +from automata.symbol_embedding.base import SymbolDocEmbedding +from automata.symbol.parser import parse_symbol import numpy as np symbol = parse_symbol('your_symbol_here') diff --git a/automata/core/agent/__init__.py b/automata/agent/__init__.py similarity index 100% rename from automata/core/agent/__init__.py rename to automata/agent/__init__.py diff --git a/automata/core/agent/agent.py b/automata/agent/agent.py similarity index 95% rename from automata/core/agent/agent.py rename to automata/agent/agent.py index 658b2bc9..3747c044 100644 --- a/automata/core/agent/agent.py +++ b/automata/agent/agent.py @@ -6,11 +6,8 @@ from pydantic import BaseModel from automata.config.base import AgentConfigName, LLMProvider -from automata.core.llm.foundation import ( - LLMConversationDatabaseProvider, - LLMIterationResult, -) -from automata.core.tools.base import Tool +from automata.llm.foundation import LLMConversationDatabaseProvider, LLMIterationResult +from automata.tools.base import Tool logger = logging.getLogger(__name__) diff --git a/automata/core/agent/error.py b/automata/agent/error.py similarity index 100% rename from automata/core/agent/error.py rename to automata/agent/error.py diff --git a/automata/core/agent/instances.py b/automata/agent/instances.py similarity index 91% rename from automata/core/agent/instances.py rename to automata/agent/instances.py index 362a38f3..d796eb60 100644 --- a/automata/core/agent/instances.py +++ b/automata/agent/instances.py @@ -2,12 +2,12 @@ from pydantic import BaseModel +from automata.agent.agent import AgentInstance from automata.config.base import AgentConfigName from automata.config.openai_agent import OpenAIAutomataAgentConfigBuilder -from automata.core.agent.agent import AgentInstance if TYPE_CHECKING: - from automata.core.agent.providers import OpenAIAutomataAgent + from automata.agent.providers import OpenAIAutomataAgent class OpenAIAutomataAgentInstance(AgentInstance, BaseModel): diff --git a/automata/core/agent/providers.py b/automata/agent/providers.py similarity index 98% rename from automata/core/agent/providers.py rename to automata/agent/providers.py index a4a40e96..f85eba7b 100644 --- a/automata/core/agent/providers.py +++ b/automata/agent/providers.py @@ -2,22 +2,23 @@ from abc import ABC, abstractmethod from typing import Dict, Final, List, Sequence -from automata.config.base import ConfigCategory -from automata.config.openai_agent import OpenAIAutomataAgentConfig -from automata.core.agent.agent import Agent, AgentToolkitBuilder -from automata.core.agent.error import ( +from automata.agent.agent import Agent, AgentToolkitBuilder +from automata.agent.error import ( AgentDatabaseError, AgentGeneralError, AgentMaxIterError, AgentResultError, AgentStopIteration, ) -from automata.core.llm.foundation import ( +from automata.config.base import ConfigCategory +from automata.config.openai_agent import OpenAIAutomataAgentConfig +from automata.core.utils import format_text, load_config +from automata.llm.foundation import ( LLMChatMessage, LLMConversationDatabaseProvider, LLMIterationResult, ) -from automata.core.llm.providers.openai import ( +from automata.llm.providers.openai import ( FunctionCall, OpenAIChatCompletionProvider, OpenAIChatMessage, @@ -25,7 +26,6 @@ OpenAIFunction, OpenAITool, ) -from automata.core.utils import format_text, load_config logger = logging.getLogger(__name__) diff --git a/automata/cli/scripts/run_agent.py b/automata/cli/scripts/run_agent.py index 9a1c4c7a..d5cc196b 100644 --- a/automata/cli/scripts/run_agent.py +++ b/automata/cli/scripts/run_agent.py @@ -1,14 +1,14 @@ import logging from typing import List +from automata.agent.providers import OpenAIAutomataAgent from automata.config import GITHUB_API_KEY, REPOSITORY_NAME from automata.config.base import AgentConfigName from automata.config.openai_agent import OpenAIAutomataAgentConfigBuilder -from automata.core.agent.providers import OpenAIAutomataAgent -from automata.core.github_management.client import GitHubClient -from automata.core.singletons.dependency_factory import dependency_factory -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.tools.factory import AgentToolFactory +from automata.github_management.client import GitHubClient +from automata.singletons.dependency_factory import dependency_factory +from automata.singletons.py_module_loader import py_module_loader +from automata.tools.factory import AgentToolFactory logger = logging.getLogger(__name__) diff --git a/automata/cli/scripts/run_agent_config_validation.py b/automata/cli/scripts/run_agent_config_validation.py index 19ecd99f..0c4926ca 100644 --- a/automata/cli/scripts/run_agent_config_validation.py +++ b/automata/cli/scripts/run_agent_config_validation.py @@ -8,7 +8,7 @@ from automata.config.base import ConfigCategory -# from automata.core.agent.action import AutomataActionExtractor +# from automata.agent.action import AutomataActionExtractor from automata.core.utils import get_config_fpath, get_logging_config logger = logging.getLogger(__name__) diff --git a/automata/cli/scripts/run_code_embedding.py b/automata/cli/scripts/run_code_embedding.py index 29a9310c..4a27cf20 100644 --- a/automata/cli/scripts/run_code_embedding.py +++ b/automata/cli/scripts/run_code_embedding.py @@ -4,13 +4,13 @@ from tqdm import tqdm from automata.config.base import ConfigCategory -from automata.core.llm.providers.openai import OpenAIEmbeddingProvider -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.singletons.dependency_factory import dependency_factory -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.symbol.graph import SymbolGraph -from automata.core.symbol.symbol_utils import get_rankable_symbols from automata.core.utils import get_config_fpath +from automata.llm.providers.openai import OpenAIEmbeddingProvider +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.singletons.dependency_factory import dependency_factory +from automata.singletons.py_module_loader import py_module_loader +from automata.symbol.graph import SymbolGraph +from automata.symbol.symbol_utils import get_rankable_symbols logger = logging.getLogger(__name__) diff --git a/automata/cli/scripts/run_doc_embedding.py b/automata/cli/scripts/run_doc_embedding.py index ddda9e9c..61fd05c0 100644 --- a/automata/cli/scripts/run_doc_embedding.py +++ b/automata/cli/scripts/run_doc_embedding.py @@ -4,18 +4,18 @@ from tqdm import tqdm from automata.config.base import ConfigCategory -from automata.core.context_providers.symbol_synchronization import ( +from automata.context_providers.symbol_synchronization import ( SymbolProviderSynchronizationContext, ) -from automata.core.llm.providers.openai import OpenAIEmbeddingProvider -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler -from automata.core.singletons.dependency_factory import dependency_factory -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.symbol.graph import SymbolGraph -from automata.core.symbol.symbol_utils import get_rankable_symbols -from automata.core.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase from automata.core.utils import get_config_fpath +from automata.llm.providers.openai import OpenAIEmbeddingProvider +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler +from automata.singletons.dependency_factory import dependency_factory +from automata.singletons.py_module_loader import py_module_loader +from automata.symbol.graph import SymbolGraph +from automata.symbol.symbol_utils import get_rankable_symbols +from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase logger = logging.getLogger(__name__) diff --git a/automata/cli/scripts/run_doc_post_process.py b/automata/cli/scripts/run_doc_post_process.py index 32021fb1..f3d2ed21 100644 --- a/automata/cli/scripts/run_doc_post_process.py +++ b/automata/cli/scripts/run_doc_post_process.py @@ -1,10 +1,10 @@ import logging import os +from automata.code_handling.py.writer import PyDocWriter from automata.config.base import ConfigCategory -from automata.core.code_handling.py.writer import PyDocWriter -from automata.core.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase -from automata.core.utils import get_config_fpath, get_root_py_fpath +from automata.core.utils import get_config_fpath, get_root_fpath +from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase logger = logging.getLogger(__name__) @@ -13,7 +13,7 @@ def main(*args, **kwargs) -> str: """ Update the symbol code embedding based on the specified SCIP index file. """ - doc_writer = PyDocWriter(get_root_py_fpath()) + doc_writer = PyDocWriter(get_root_fpath()) embedding_path = os.path.join( get_config_fpath(), ConfigCategory.SYMBOL.value, "symbol_doc_embedding_l2.json" @@ -25,5 +25,5 @@ def main(*args, **kwargs) -> str: docs = {symbol: embedding_db.get(symbol.dotpath) for symbol in symbols} - doc_writer.write_documentation(docs, symbols, os.path.join(get_root_py_fpath(), "docs")) # type: ignore + doc_writer.write_documentation(docs, symbols, os.path.join(get_root_fpath(), "docs")) # type: ignore return "Success" diff --git a/automata/core/code_handling/__init__.py b/automata/code_handling/__init__.py similarity index 100% rename from automata/core/code_handling/__init__.py rename to automata/code_handling/__init__.py diff --git a/automata/core/code_handling/py/reader.py b/automata/code_handling/py/reader.py similarity index 97% rename from automata/core/code_handling/py/reader.py rename to automata/code_handling/py/reader.py index 061972a9..edb162d6 100644 --- a/automata/core/code_handling/py/reader.py +++ b/automata/code_handling/py/reader.py @@ -5,8 +5,8 @@ from redbaron import ClassNode, DefNode, Node, RedBaron, StringNode -from automata.core.navigation.py.navigation_utils import find_syntax_tree_node -from automata.core.singletons.py_module_loader import py_module_loader +from automata.navigation.py.navigation_utils import find_syntax_tree_node +from automata.singletons.py_module_loader import py_module_loader logger = logging.getLogger(__name__) FSTNode = Union[Node, RedBaron] diff --git a/automata/core/code_handling/py/writer.py b/automata/code_handling/py/writer.py similarity index 98% rename from automata/core/code_handling/py/writer.py rename to automata/code_handling/py/writer.py index f5005541..6d694154 100644 --- a/automata/core/code_handling/py/writer.py +++ b/automata/code_handling/py/writer.py @@ -8,17 +8,17 @@ import pypandoc from redbaron import ClassNode, DefNode, Node, NodeList, RedBaron -from automata.core.code_handling.py.reader import PyReader -from automata.core.navigation.directory import DirectoryManager -from automata.core.navigation.py.navigation_utils import ( +from automata.code_handling.py.reader import PyReader +from automata.navigation.directory import DirectoryManager +from automata.navigation.py.navigation_utils import ( find_all_function_and_class_syntax_tree_nodes, find_import_syntax_tree_node_by_name, find_import_syntax_tree_nodes, find_syntax_tree_node, ) -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.symbol.base import Symbol -from automata.core.symbol_embedding.base import SymbolDocEmbedding +from automata.singletons.py_module_loader import py_module_loader +from automata.symbol.base import Symbol +from automata.symbol_embedding.base import SymbolDocEmbedding logger = logging.getLogger(__name__) diff --git a/automata/config/base.py b/automata/config/base.py index d22441d2..20ec0412 100644 --- a/automata/config/base.py +++ b/automata/config/base.py @@ -6,8 +6,8 @@ import yaml from pydantic import BaseModel, PrivateAttr -from automata.core.tools.base import Tool from automata.core.utils import convert_kebab_to_snake +from automata.tools.base import Tool class ConfigCategory(Enum): diff --git a/automata/config/openai_agent.py b/automata/config/openai_agent.py index 873efe56..594396f6 100644 --- a/automata/config/openai_agent.py +++ b/automata/config/openai_agent.py @@ -10,8 +10,8 @@ InstructionConfigVersion, LLMProvider, ) -from automata.core.experimental.search.rank import SymbolRank -from automata.core.singletons.dependency_factory import dependency_factory +from automata.experimental.search.rank import SymbolRank +from automata.singletons.dependency_factory import dependency_factory class OpenAIAutomataAgentConfig(AgentConfig): diff --git a/automata/config/prompt/doc_generation.py b/automata/config/prompt/doc_generation.py index 36d886e2..9233139f 100644 --- a/automata/config/prompt/doc_generation.py +++ b/automata/config/prompt/doc_generation.py @@ -40,9 +40,9 @@ ## Related Symbols - `config.config_enums.AgentConfigName` - - `automata.core.agent.agent.AutomataAgent` + - `automata.agent.agent.AutomataAgent` - `config.automata_agent_config_utils.AutomataAgentConfigBuilder` - - `automata.core.coordinator.automata_instance.AutomataInstance` + - `automata.coordinator.automata_instance.AutomataInstance` ## Example diff --git a/automata/config/symbol/symbol_code_embedding.json b/automata/config/symbol/symbol_code_embedding.json index 9082cb65..a2759554 100644 --- a/automata/config/symbol/symbol_code_embedding.json +++ b/automata/config/symbol/symbol_code_embedding.json @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:d22dd6078cc56e7c6031998aa0f8dbb3569588d12ee4dc1c550bb8b4c0e968d2 -size 15072330 +oid sha256:836afd15b04ed4ee222bf7a889dcad09bfd571ef9758235f5aa5ecc89262b516 +size 15043469 diff --git a/automata/config/symbol/symbol_doc_embedding_l2.json b/automata/config/symbol/symbol_doc_embedding_l2.json index e4082e89..c52e4916 100644 --- a/automata/config/symbol/symbol_doc_embedding_l2.json +++ b/automata/config/symbol/symbol_doc_embedding_l2.json @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:46d457939aa960c009e168bbc230c4cb2ff99bf8bf4e2b0e43d5ffe73d9e44d4 -size 17671722 +oid sha256:6708aae775a1d9e87413c97710d7a3e132cec2b084a319f111e37ddb1580d19e +size 17626332 diff --git a/automata/config/symbol/symbol_doc_embedding_l3.json b/automata/config/symbol/symbol_doc_embedding_l3.json index e4082e89..34778533 100644 --- a/automata/config/symbol/symbol_doc_embedding_l3.json +++ b/automata/config/symbol/symbol_doc_embedding_l3.json @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:46d457939aa960c009e168bbc230c4cb2ff99bf8bf4e2b0e43d5ffe73d9e44d4 -size 17671722 +oid sha256:6b9b23f2f1e6d823cde694d5d5c8cfb61fa3ebe93fbb5dde4f42c77bb0a1e895 +size 17654217 diff --git a/automata/core/context_providers/symbol_synchronization.py b/automata/context_providers/symbol_synchronization.py similarity index 97% rename from automata/core/context_providers/symbol_synchronization.py rename to automata/context_providers/symbol_synchronization.py index 4cf5c008..ac50677d 100644 --- a/automata/core/context_providers/symbol_synchronization.py +++ b/automata/context_providers/symbol_synchronization.py @@ -1,6 +1,6 @@ from typing import List, Set -from automata.core.symbol.base import ISymbolProvider, Symbol +from automata.symbol.base import ISymbolProvider, Symbol class SymbolProviderRegistry: diff --git a/automata/core/utils.py b/automata/core/utils.py index 2a222d8c..b9063143 100644 --- a/automata/core/utils.py +++ b/automata/core/utils.py @@ -9,7 +9,7 @@ import openai import yaml -from automata.core.symbol.base import Symbol +from automata.symbol.base import Symbol def set_openai_api_key(override_key: Optional[str] = None) -> None: diff --git a/automata/core/embedding/base.py b/automata/embedding/base.py similarity index 97% rename from automata/core/embedding/base.py rename to automata/embedding/base.py index 9cc9c712..3cf5d364 100644 --- a/automata/core/embedding/base.py +++ b/automata/embedding/base.py @@ -6,7 +6,7 @@ import numpy as np from automata.core.base.database.vector import VectorDatabaseProvider -from automata.core.symbol.base import Symbol +from automata.symbol.base import Symbol logger = logging.getLogger(__name__) @@ -54,7 +54,7 @@ def build(self, source_text: str, symbol: Symbol) -> Any: def fetch_embedding_source_code(self, symbol: Symbol) -> str: """An abstract method for embedding the context is the source code itself.""" - from automata.core.symbol.symbol_utils import ( # imported late for mocking + from automata.symbol.symbol_utils import ( # imported late for mocking convert_to_fst_object, ) diff --git a/automata/core/experimental/__init__.py b/automata/experimental/__init__.py similarity index 100% rename from automata/core/experimental/__init__.py rename to automata/experimental/__init__.py diff --git a/automata/core/experimental/search/__init__.py b/automata/experimental/search/__init__.py similarity index 100% rename from automata/core/experimental/search/__init__.py rename to automata/experimental/search/__init__.py diff --git a/automata/core/experimental/search/rank.py b/automata/experimental/search/rank.py similarity index 99% rename from automata/core/experimental/search/rank.py rename to automata/experimental/search/rank.py index a420451f..d3d77448 100644 --- a/automata/core/experimental/search/rank.py +++ b/automata/experimental/search/rank.py @@ -4,7 +4,7 @@ from networkx.exception import NetworkXError from pydantic import BaseModel -from automata.core.symbol.base import Symbol +from automata.symbol.base import Symbol class SymbolRankConfig(BaseModel): diff --git a/automata/core/experimental/search/symbol_search.py b/automata/experimental/search/symbol_search.py similarity index 91% rename from automata/core/experimental/search/symbol_search.py rename to automata/experimental/search/symbol_search.py index dbdeb05d..92cf6692 100644 --- a/automata/core/experimental/search/symbol_search.py +++ b/automata/experimental/search/symbol_search.py @@ -3,14 +3,14 @@ import numpy as np from redbaron import RedBaron -from automata.core.embedding.base import EmbeddingSimilarityCalculator -from automata.core.experimental.search.rank import SymbolRank, SymbolRankConfig -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.symbol.base import Symbol, SymbolReference -from automata.core.symbol.graph import SymbolGraph -from automata.core.symbol.parser import parse_symbol -from automata.core.symbol.symbol_utils import convert_to_fst_object -from automata.core.symbol_embedding.base import SymbolEmbeddingHandler +from automata.embedding.base import EmbeddingSimilarityCalculator +from automata.experimental.search.rank import SymbolRank, SymbolRankConfig +from automata.singletons.py_module_loader import py_module_loader +from automata.symbol.base import Symbol, SymbolReference +from automata.symbol.graph import SymbolGraph +from automata.symbol.parser import parse_symbol +from automata.symbol.symbol_utils import convert_to_fst_object +from automata.symbol_embedding.base import SymbolEmbeddingHandler SymbolReferencesResult = Dict[str, List[SymbolReference]] SymbolRankResult = List[Tuple[Symbol, float]] diff --git a/automata/core/github_management/client.py b/automata/github_management/client.py similarity index 100% rename from automata/core/github_management/client.py rename to automata/github_management/client.py diff --git a/automata/core/llm/__init__.py b/automata/llm/__init__.py similarity index 100% rename from automata/core/llm/__init__.py rename to automata/llm/__init__.py diff --git a/automata/core/llm/foundation.py b/automata/llm/foundation.py similarity index 100% rename from automata/core/llm/foundation.py rename to automata/llm/foundation.py diff --git a/automata/core/llm/providers/openai.py b/automata/llm/providers/openai.py similarity index 98% rename from automata/core/llm/providers/openai.py rename to automata/llm/providers/openai.py index 4e86c642..5c36eb40 100644 --- a/automata/core/llm/providers/openai.py +++ b/automata/llm/providers/openai.py @@ -7,15 +7,15 @@ import tiktoken from termcolor import colored -from automata.core.embedding.base import EmbeddingVectorProvider -from automata.core.llm.foundation import ( +from automata.core.utils import set_openai_api_key +from automata.embedding.base import EmbeddingVectorProvider +from automata.llm.foundation import ( LLMChatCompletionProvider, LLMChatMessage, LLMCompletionResult, LLMConversation, ) -from automata.core.tools.base import Tool -from automata.core.utils import set_openai_api_key +from automata.tools.base import Tool logger = logging.getLogger(__name__) diff --git a/automata/core/memory_store/__init__.py b/automata/memory_store/__init__.py similarity index 100% rename from automata/core/memory_store/__init__.py rename to automata/memory_store/__init__.py diff --git a/automata/core/memory_store/agent_conversation_database.py b/automata/memory_store/agent_conversation_database.py similarity index 95% rename from automata/core/memory_store/agent_conversation_database.py rename to automata/memory_store/agent_conversation_database.py index 32f9943c..0115697a 100644 --- a/automata/core/memory_store/agent_conversation_database.py +++ b/automata/memory_store/agent_conversation_database.py @@ -1,7 +1,7 @@ from typing import List from automata.config import CONVERSATION_DB_PATH -from automata.core.llm.foundation import LLMChatMessage, LLMConversationDatabaseProvider +from automata.llm.foundation import LLMChatMessage, LLMConversationDatabaseProvider class AgentConversationDatabase(LLMConversationDatabaseProvider): diff --git a/automata/core/memory_store/symbol_code_embedding.py b/automata/memory_store/symbol_code_embedding.py similarity index 92% rename from automata/core/memory_store/symbol_code_embedding.py rename to automata/memory_store/symbol_code_embedding.py index df8fb8c8..869df776 100644 --- a/automata/core/memory_store/symbol_code_embedding.py +++ b/automata/memory_store/symbol_code_embedding.py @@ -1,12 +1,12 @@ import logging -from automata.core.symbol.base import Symbol -from automata.core.symbol_embedding.base import ( +from automata.symbol.base import Symbol +from automata.symbol_embedding.base import ( JSONSymbolEmbeddingVectorDatabase, SymbolCodeEmbedding, SymbolEmbeddingHandler, ) -from automata.core.symbol_embedding.builders import SymbolCodeEmbeddingBuilder +from automata.symbol_embedding.builders import SymbolCodeEmbeddingBuilder logger = logging.getLogger(__name__) diff --git a/automata/core/memory_store/symbol_doc_embedding.py b/automata/memory_store/symbol_doc_embedding.py similarity index 92% rename from automata/core/memory_store/symbol_doc_embedding.py rename to automata/memory_store/symbol_doc_embedding.py index a78e7dd0..27833d69 100644 --- a/automata/core/memory_store/symbol_doc_embedding.py +++ b/automata/memory_store/symbol_doc_embedding.py @@ -1,12 +1,12 @@ import logging -from automata.core.symbol.base import Symbol, SymbolDescriptor -from automata.core.symbol_embedding.base import ( +from automata.symbol.base import Symbol, SymbolDescriptor +from automata.symbol_embedding.base import ( JSONSymbolEmbeddingVectorDatabase, SymbolDocEmbedding, SymbolEmbeddingHandler, ) -from automata.core.symbol_embedding.builders import SymbolDocEmbeddingBuilder +from automata.symbol_embedding.builders import SymbolDocEmbeddingBuilder logger = logging.getLogger(__name__) diff --git a/automata/core/navigation/__init__.py b/automata/navigation/__init__.py similarity index 100% rename from automata/core/navigation/__init__.py rename to automata/navigation/__init__.py diff --git a/automata/core/navigation/directory.py b/automata/navigation/directory.py similarity index 100% rename from automata/core/navigation/directory.py rename to automata/navigation/directory.py diff --git a/automata/core/navigation/py/dot_path_map.py b/automata/navigation/py/dot_path_map.py similarity index 100% rename from automata/core/navigation/py/dot_path_map.py rename to automata/navigation/py/dot_path_map.py diff --git a/automata/core/navigation/py/navigation_utils.py b/automata/navigation/py/navigation_utils.py similarity index 98% rename from automata/core/navigation/py/navigation_utils.py rename to automata/navigation/py/navigation_utils.py index a85bb9f7..531baa55 100644 --- a/automata/core/navigation/py/navigation_utils.py +++ b/automata/navigation/py/navigation_utils.py @@ -13,7 +13,7 @@ RedBaron, ) -from automata.core.navigation.py.dot_path_map import DotPathMap +from automata.navigation.py.dot_path_map import DotPathMap logger = logging.getLogger(__name__) diff --git a/automata/core/retrievers/__init__.py b/automata/retrievers/__init__.py similarity index 100% rename from automata/core/retrievers/__init__.py rename to automata/retrievers/__init__.py diff --git a/automata/core/retrievers/py/__init__.py b/automata/retrievers/py/__init__.py similarity index 100% rename from automata/core/retrievers/py/__init__.py rename to automata/retrievers/py/__init__.py diff --git a/automata/core/retrievers/py/context.py b/automata/retrievers/py/context.py similarity index 97% rename from automata/core/retrievers/py/context.py rename to automata/retrievers/py/context.py index f5a5db90..2ba48833 100644 --- a/automata/core/retrievers/py/context.py +++ b/automata/retrievers/py/context.py @@ -6,15 +6,12 @@ import tiktoken from redbaron import RedBaron +from automata.code_handling.py.reader import PyReader from automata.core.base.database.vector import VectorDatabaseProvider -from automata.core.code_handling.py.reader import PyReader -from automata.core.symbol.base import Symbol -from automata.core.symbol.graph import SymbolGraph -from automata.core.symbol.symbol_utils import ( - convert_to_fst_object, - get_rankable_symbols, -) from automata.core.utils import get_root_py_fpath +from automata.symbol.base import Symbol +from automata.symbol.graph import SymbolGraph +from automata.symbol.symbol_utils import convert_to_fst_object, get_rankable_symbols logger = logging.getLogger(__name__) diff --git a/automata/core/singletons/dependency_factory.py b/automata/singletons/dependency_factory.py similarity index 89% rename from automata/core/singletons/dependency_factory.py rename to automata/singletons/dependency_factory.py index cf49860b..97f595ad 100644 --- a/automata/core/singletons/dependency_factory.py +++ b/automata/singletons/dependency_factory.py @@ -4,37 +4,34 @@ import networkx as nx +from automata.agent.agent import AgentToolkitNames +from automata.agent.error import AgentGeneralError, UnknownToolError +from automata.code_handling.py.reader import PyReader +from automata.code_handling.py.writer import PyWriter from automata.config.base import ConfigCategory -from automata.core.agent.agent import AgentToolkitNames -from automata.core.agent.error import AgentGeneralError, UnknownToolError -from automata.core.base.patterns.singleton import Singleton -from automata.core.code_handling.py.reader import PyReader -from automata.core.code_handling.py.writer import PyWriter -from automata.core.context_providers.symbol_synchronization import ( +from automata.context_providers.symbol_synchronization import ( SymbolProviderSynchronizationContext, ) -from automata.core.embedding.base import EmbeddingSimilarityCalculator -from automata.core.experimental.search.rank import SymbolRank, SymbolRankConfig -from automata.core.experimental.search.symbol_search import SymbolSearch -from automata.core.llm.providers.openai import ( +from automata.core.base.patterns.singleton import Singleton +from automata.core.utils import get_config_fpath +from automata.embedding.base import EmbeddingSimilarityCalculator +from automata.experimental.search.rank import SymbolRank, SymbolRankConfig +from automata.experimental.search.symbol_search import SymbolSearch +from automata.llm.providers.openai import ( OpenAIChatCompletionProvider, OpenAIEmbeddingProvider, ) -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler -from automata.core.retrievers.py.context import ( - PyContextRetriever, - PyContextRetrieverConfig, -) -from automata.core.symbol.base import ISymbolProvider -from automata.core.symbol.graph import SymbolGraph -from automata.core.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase -from automata.core.symbol_embedding.builders import ( +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler +from automata.retrievers.py.context import PyContextRetriever, PyContextRetrieverConfig +from automata.symbol.base import ISymbolProvider +from automata.symbol.graph import SymbolGraph +from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase +from automata.symbol_embedding.builders import ( SymbolCodeEmbeddingBuilder, SymbolDocEmbeddingBuilder, ) -from automata.core.tools.factory import AgentToolFactory, logger -from automata.core.utils import get_config_fpath +from automata.tools.factory import AgentToolFactory, logger class DependencyFactory(metaclass=Singleton): diff --git a/automata/core/singletons/py_module_loader.py b/automata/singletons/py_module_loader.py similarity index 99% rename from automata/core/singletons/py_module_loader.py rename to automata/singletons/py_module_loader.py index aee3bf22..23f14df2 100644 --- a/automata/core/singletons/py_module_loader.py +++ b/automata/singletons/py_module_loader.py @@ -8,8 +8,8 @@ from redbaron import RedBaron from automata.core.base.patterns.singleton import Singleton -from automata.core.navigation.py.dot_path_map import DotPathMap from automata.core.utils import get_root_fpath, get_root_py_fpath +from automata.navigation.py.dot_path_map import DotPathMap logger = logging.getLogger(__name__) diff --git a/automata/core/singletons/toolkit_registries.py b/automata/singletons/toolkit_registries.py similarity index 88% rename from automata/core/singletons/toolkit_registries.py rename to automata/singletons/toolkit_registries.py index d226609a..0e1a98dc 100644 --- a/automata/core/singletons/toolkit_registries.py +++ b/automata/singletons/toolkit_registries.py @@ -1,7 +1,7 @@ import pkgutil from typing import List, Set, Type -from automata.core.agent.providers import OpenAIAgentToolkitBuilder +from automata.agent.providers import OpenAIAgentToolkitBuilder from automata.core.base.patterns.singleton import Singleton @@ -35,10 +35,10 @@ def initialize(): if OpenAIAutomataAgentToolkitRegistry._is_initialized: return # Import all builder modules to ensure the classes get registered - import automata.core.tools.builders as builder_package + import automata.tools.builders as builder_package for _, module_name, _ in pkgutil.iter_modules(builder_package.__path__): - __import__(f"automata.core.tools.builders.{module_name}", fromlist=[""]) + __import__(f"automata.tools.builders.{module_name}", fromlist=[""]) # Mark the registry as initialized OpenAIAutomataAgentToolkitRegistry._is_initialized = True diff --git a/automata/core/symbol/__init__.py b/automata/symbol/__init__.py similarity index 100% rename from automata/core/symbol/__init__.py rename to automata/symbol/__init__.py diff --git a/automata/core/symbol/base.py b/automata/symbol/base.py similarity index 96% rename from automata/core/symbol/base.py rename to automata/symbol/base.py index 3c73c5bf..a63c4a07 100644 --- a/automata/core/symbol/base.py +++ b/automata/symbol/base.py @@ -4,7 +4,7 @@ from enum import Enum from typing import Any, Dict, List, Optional, Tuple -from automata.core.symbol.scip_pb2 import Descriptor as DescriptorProto # type: ignore +from automata.symbol.scip_pb2 import Descriptor as DescriptorProto # type: ignore class SymbolDescriptor: @@ -147,14 +147,14 @@ class Symbol: ::= any UTF-8 character, escape backticks with double backtick. Examples - - from automata.core.experimental.search.symbol_parser import parse_symbol + from automata.experimental.search.symbol_parser import parse_symbol symbol_class = parse_symbol( - "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.agent.agent_enums`/ActionIndicator#" + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#" ) symbol_method = parse_symbol( - "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.tools.base`/ToolNotFoundError#__init__()." + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.tools.base`/ToolNotFoundError#__init__()." ) """ @@ -246,7 +246,7 @@ def from_string(cls, symbol_str: str) -> "Symbol": raise ValueError(f"Invalid symbol_str: {symbol_str}") uri, _, __, ___ = match.groups() # In current implementation, only the uri is used in re-construcing the symbol - from automata.core.symbol.parser import parse_symbol + from automata.symbol.parser import parse_symbol return parse_symbol(uri) diff --git a/automata/core/symbol/graph.py b/automata/symbol/graph.py similarity index 98% rename from automata/core/symbol/graph.py rename to automata/symbol/graph.py index a1e62376..68ed095c 100644 --- a/automata/core/symbol/graph.py +++ b/automata/symbol/graph.py @@ -10,20 +10,17 @@ from tqdm import tqdm from automata.config import MAX_WORKERS -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.symbol.base import ( +from automata.core.utils import filter_multi_digraph_by_symbols +from automata.singletons.py_module_loader import py_module_loader +from automata.symbol.base import ( ISymbolProvider, Symbol, SymbolDescriptor, SymbolReference, ) -from automata.core.symbol.parser import parse_symbol -from automata.core.symbol.scip_pb2 import Index, SymbolRole # type: ignore -from automata.core.symbol.symbol_utils import ( - convert_to_fst_object, - get_rankable_symbols, -) -from automata.core.utils import filter_multi_digraph_by_symbols +from automata.symbol.parser import parse_symbol +from automata.symbol.scip_pb2 import Index, SymbolRole # type: ignore +from automata.symbol.symbol_utils import convert_to_fst_object, get_rankable_symbols logger = logging.getLogger(__name__) diff --git a/automata/core/symbol/parser.py b/automata/symbol/parser.py similarity index 98% rename from automata/core/symbol/parser.py rename to automata/symbol/parser.py index 0329d0d1..64ecc5dc 100644 --- a/automata/core/symbol/parser.py +++ b/automata/symbol/parser.py @@ -1,7 +1,7 @@ import re from typing import List, Optional -from automata.core.symbol.base import Symbol, SymbolDescriptor, SymbolPackage +from automata.symbol.base import Symbol, SymbolDescriptor, SymbolPackage class _SymbolParser: diff --git a/automata/core/symbol/scip_pb2.py b/automata/symbol/scip_pb2.py similarity index 100% rename from automata/core/symbol/scip_pb2.py rename to automata/symbol/scip_pb2.py diff --git a/automata/core/symbol/symbol_utils.py b/automata/symbol/symbol_utils.py similarity index 95% rename from automata/core/symbol/symbol_utils.py rename to automata/symbol/symbol_utils.py index 0b5cceda..d0a92ba4 100644 --- a/automata/core/symbol/symbol_utils.py +++ b/automata/symbol/symbol_utils.py @@ -2,8 +2,8 @@ from redbaron import RedBaron -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.symbol.base import Symbol, SymbolDescriptor +from automata.singletons.py_module_loader import py_module_loader +from automata.symbol.base import Symbol, SymbolDescriptor def convert_to_fst_object(symbol: Symbol) -> RedBaron: diff --git a/automata/core/symbol_embedding/__init__.py b/automata/symbol_embedding/__init__.py similarity index 100% rename from automata/core/symbol_embedding/__init__.py rename to automata/symbol_embedding/__init__.py diff --git a/automata/core/symbol_embedding/base.py b/automata/symbol_embedding/base.py similarity index 96% rename from automata/core/symbol_embedding/base.py rename to automata/symbol_embedding/base.py index e7b8cd92..8f6cf4ff 100644 --- a/automata/core/symbol_embedding/base.py +++ b/automata/symbol_embedding/base.py @@ -4,8 +4,8 @@ import numpy as np from automata.core.base.database.vector import JSONVectorDatabase -from automata.core.embedding.base import Embedding, EmbeddingBuilder, EmbeddingHandler -from automata.core.symbol.base import ISymbolProvider, Symbol +from automata.embedding.base import Embedding, EmbeddingBuilder, EmbeddingHandler +from automata.symbol.base import ISymbolProvider, Symbol class SymbolEmbedding(Embedding): diff --git a/automata/core/symbol_embedding/builders.py b/automata/symbol_embedding/builders.py similarity index 89% rename from automata/core/symbol_embedding/builders.py rename to automata/symbol_embedding/builders.py index 461cad9a..1b1426d7 100644 --- a/automata/core/symbol_embedding/builders.py +++ b/automata/symbol_embedding/builders.py @@ -2,15 +2,15 @@ from jinja2 import Template +from automata.code_handling.py.reader import PyReader from automata.config.prompt.doc_generation import DEFAULT_DOC_GENERATION_PROMPT -from automata.core.code_handling.py.reader import PyReader -from automata.core.embedding.base import EmbeddingBuilder, EmbeddingVectorProvider -from automata.core.experimental.search.symbol_search import SymbolSearch -from automata.core.llm.foundation import LLMChatCompletionProvider -from automata.core.retrievers.py.context import PyContextRetriever -from automata.core.symbol.base import Symbol -from automata.core.symbol.symbol_utils import convert_to_fst_object -from automata.core.symbol_embedding.base import SymbolCodeEmbedding, SymbolDocEmbedding +from automata.embedding.base import EmbeddingBuilder, EmbeddingVectorProvider +from automata.experimental.search.symbol_search import SymbolSearch +from automata.llm.foundation import LLMChatCompletionProvider +from automata.retrievers.py.context import PyContextRetriever +from automata.symbol.base import Symbol +from automata.symbol.symbol_utils import convert_to_fst_object +from automata.symbol_embedding.base import SymbolCodeEmbedding, SymbolDocEmbedding class SymbolCodeEmbeddingBuilder(EmbeddingBuilder): @@ -59,10 +59,10 @@ def build(self, source_code: str, symbol: Symbol) -> SymbolDocEmbedding: specific agent requirements. Related Symbols --------------- - - ``automata.core.agent.instances.OpenAIAutomataAgentInstance.Config`` + - ``automata.agent.instances.OpenAIAutomataAgentInstance.Config`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_default_config`` - ``automata.tests.unit.test_task_environment.TestURL`` - - ``automata.core.agent.agent.AgentInstance.Config`` + - ``automata.agent.agent.AgentInstance.Config`` Example ------- The following example demonstrates how to create a custom agent diff --git a/automata/core/tasks/__init__.py b/automata/tasks/__init__.py similarity index 100% rename from automata/core/tasks/__init__.py rename to automata/tasks/__init__.py diff --git a/automata/core/tasks/agent_database.py b/automata/tasks/agent_database.py similarity index 96% rename from automata/core/tasks/agent_database.py rename to automata/tasks/agent_database.py index 2d952ff7..2a98c2e0 100644 --- a/automata/core/tasks/agent_database.py +++ b/automata/tasks/agent_database.py @@ -4,11 +4,11 @@ import jsonpickle +from automata.agent.error import AgentTaskGeneralError, AgentTaskStateError from automata.config import TASK_DB_PATH -from automata.core.agent.error import AgentTaskGeneralError, AgentTaskStateError from automata.core.base.database.relational import SQLDatabase -from automata.core.tasks.base import TaskStatus -from automata.core.tasks.tasks import AutomataTask +from automata.tasks.base import TaskStatus +from automata.tasks.tasks import AutomataTask logger = logging.getLogger(__name__) diff --git a/automata/core/tasks/base.py b/automata/tasks/base.py similarity index 100% rename from automata/core/tasks/base.py rename to automata/tasks/base.py diff --git a/automata/core/tasks/environment.py b/automata/tasks/environment.py similarity index 93% rename from automata/core/tasks/environment.py rename to automata/tasks/environment.py index 87b23c72..cf3e741e 100644 --- a/automata/core/tasks/environment.py +++ b/automata/tasks/environment.py @@ -2,10 +2,10 @@ import logging.config import os -from automata.core.agent.error import AgentTaskGeneralError, AgentTaskStateError -from automata.core.github_management.client import GitHubClient -from automata.core.tasks.base import Task, TaskEnvironment, TaskStatus -from automata.core.tasks.tasks import AutomataTask +from automata.agent.error import AgentTaskGeneralError, AgentTaskStateError +from automata.github_management.client import GitHubClient +from automata.tasks.base import Task, TaskEnvironment, TaskStatus +from automata.tasks.tasks import AutomataTask logger = logging.getLogger(__name__) diff --git a/automata/core/tasks/executor.py b/automata/tasks/executor.py similarity index 93% rename from automata/core/tasks/executor.py rename to automata/tasks/executor.py index e613ff3c..8b14695e 100644 --- a/automata/core/tasks/executor.py +++ b/automata/tasks/executor.py @@ -2,11 +2,11 @@ import logging.config import time +from automata.agent.error import AgentTaskGeneralError, AgentTaskStateError +from automata.agent.providers import OpenAIAutomataAgent from automata.config.openai_agent import OpenAIAutomataAgentConfigBuilder -from automata.core.agent.error import AgentTaskGeneralError, AgentTaskStateError -from automata.core.agent.providers import OpenAIAutomataAgent -from automata.core.tasks.base import ITaskExecution, Task, TaskStatus -from automata.core.tasks.tasks import AutomataTask +from automata.tasks.base import ITaskExecution, Task, TaskStatus +from automata.tasks.tasks import AutomataTask logger = logging.getLogger(__name__) diff --git a/automata/core/tasks/tasks.py b/automata/tasks/tasks.py similarity index 95% rename from automata/core/tasks/tasks.py rename to automata/tasks/tasks.py index 371e37c4..c4639fea 100644 --- a/automata/core/tasks/tasks.py +++ b/automata/tasks/tasks.py @@ -2,9 +2,9 @@ import logging.config import os -from automata.core.agent.error import AgentTaskInstructions -from automata.core.tasks.base import Task +from automata.agent.error import AgentTaskInstructions from automata.core.utils import get_logging_config, get_root_fpath, get_root_py_fpath +from automata.tasks.base import Task logger = logging.getLogger(__name__) diff --git a/automata/core/tools/__init__.py b/automata/tools/__init__.py similarity index 100% rename from automata/core/tools/__init__.py rename to automata/tools/__init__.py diff --git a/automata/core/tools/base.py b/automata/tools/base.py similarity index 100% rename from automata/core/tools/base.py rename to automata/tools/base.py diff --git a/automata/core/tools/builders/context_oracle.py b/automata/tools/builders/context_oracle.py similarity index 89% rename from automata/core/tools/builders/context_oracle.py rename to automata/tools/builders/context_oracle.py index 638293fe..8a6dc940 100644 --- a/automata/core/tools/builders/context_oracle.py +++ b/automata/tools/builders/context_oracle.py @@ -2,18 +2,16 @@ import textwrap from typing import List +from automata.agent.agent import AgentToolkitBuilder, AgentToolkitNames +from automata.agent.providers import OpenAIAgentToolkitBuilder from automata.config.base import LLMProvider -from automata.core.agent.agent import AgentToolkitBuilder, AgentToolkitNames -from automata.core.agent.providers import OpenAIAgentToolkitBuilder -from automata.core.embedding.base import EmbeddingSimilarityCalculator -from automata.core.experimental.search.symbol_search import SymbolSearch -from automata.core.llm.providers.openai import OpenAITool -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler -from automata.core.singletons.toolkit_registries import ( - OpenAIAutomataAgentToolkitRegistry, -) -from automata.core.tools.base import Tool +from automata.embedding.base import EmbeddingSimilarityCalculator +from automata.experimental.search.symbol_search import SymbolSearch +from automata.llm.providers.openai import OpenAITool +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler +from automata.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry +from automata.tools.base import Tool logger = logging.getLogger(__name__) diff --git a/automata/core/tools/builders/py_reader.py b/automata/tools/builders/py_reader.py similarity index 92% rename from automata/core/tools/builders/py_reader.py rename to automata/tools/builders/py_reader.py index 8f93e703..98df727b 100644 --- a/automata/core/tools/builders/py_reader.py +++ b/automata/tools/builders/py_reader.py @@ -1,15 +1,13 @@ import logging from typing import List, Optional +from automata.agent.agent import AgentToolkitBuilder, AgentToolkitNames +from automata.agent.providers import OpenAIAgentToolkitBuilder +from automata.code_handling.py.reader import PyReader from automata.config.base import LLMProvider -from automata.core.agent.agent import AgentToolkitBuilder, AgentToolkitNames -from automata.core.agent.providers import OpenAIAgentToolkitBuilder -from automata.core.code_handling.py.reader import PyReader -from automata.core.llm.providers.openai import OpenAITool -from automata.core.singletons.toolkit_registries import ( - OpenAIAutomataAgentToolkitRegistry, -) -from automata.core.tools.base import Tool +from automata.llm.providers.openai import OpenAITool +from automata.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry +from automata.tools.base import Tool logger = logging.getLogger(__name__) diff --git a/automata/core/tools/builders/py_writer.py b/automata/tools/builders/py_writer.py similarity index 91% rename from automata/core/tools/builders/py_writer.py rename to automata/tools/builders/py_writer.py index dc75f1db..07bc1afe 100644 --- a/automata/core/tools/builders/py_writer.py +++ b/automata/tools/builders/py_writer.py @@ -1,15 +1,13 @@ import logging from typing import List, Optional +from automata.agent.agent import AgentToolkitBuilder, AgentToolkitNames +from automata.agent.providers import OpenAIAgentToolkitBuilder +from automata.code_handling.py.writer import PyWriter from automata.config.base import LLMProvider -from automata.core.agent.agent import AgentToolkitBuilder, AgentToolkitNames -from automata.core.agent.providers import OpenAIAgentToolkitBuilder -from automata.core.code_handling.py.writer import PyWriter -from automata.core.llm.providers.openai import OpenAITool -from automata.core.singletons.toolkit_registries import ( - OpenAIAutomataAgentToolkitRegistry, -) -from automata.core.tools.base import Tool +from automata.llm.providers.openai import OpenAITool +from automata.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry +from automata.tools.base import Tool logger = logging.getLogger(__name__) diff --git a/automata/core/tools/builders/symbol_search.py b/automata/tools/builders/symbol_search.py similarity index 90% rename from automata/core/tools/builders/symbol_search.py rename to automata/tools/builders/symbol_search.py index a68a9f60..2cbeb7a5 100644 --- a/automata/core/tools/builders/symbol_search.py +++ b/automata/tools/builders/symbol_search.py @@ -1,22 +1,20 @@ from enum import Enum from typing import List, Optional, Union +from automata.agent.agent import AgentToolkitBuilder, AgentToolkitNames +from automata.agent.error import UnknownToolError +from automata.agent.providers import OpenAIAgentToolkitBuilder from automata.config.base import LLMProvider -from automata.core.agent.agent import AgentToolkitBuilder, AgentToolkitNames -from automata.core.agent.error import UnknownToolError -from automata.core.agent.providers import OpenAIAgentToolkitBuilder -from automata.core.experimental.search.symbol_search import ( +from automata.experimental.search.symbol_search import ( ExactSearchResult, SourceCodeResult, SymbolRankResult, SymbolReferencesResult, SymbolSearch, ) -from automata.core.llm.providers.openai import OpenAITool -from automata.core.singletons.toolkit_registries import ( - OpenAIAutomataAgentToolkitRegistry, -) -from automata.core.tools.base import Tool +from automata.llm.providers.openai import OpenAITool +from automata.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry +from automata.tools.base import Tool class SearchTool(Enum): diff --git a/automata/core/tools/factory.py b/automata/tools/factory.py similarity index 75% rename from automata/core/tools/factory.py rename to automata/tools/factory.py index 5be45549..92aca2cf 100644 --- a/automata/core/tools/factory.py +++ b/automata/tools/factory.py @@ -1,16 +1,16 @@ import logging from typing import Any, Dict, List, Sequence, Tuple +from automata.agent.agent import AgentToolkitNames +from automata.agent.error import UnknownToolError +from automata.code_handling.py.reader import PyReader +from automata.code_handling.py.writer import PyWriter from automata.config.base import LLMProvider -from automata.core.agent.agent import AgentToolkitNames -from automata.core.agent.error import UnknownToolError -from automata.core.code_handling.py.reader import PyReader -from automata.core.code_handling.py.writer import PyWriter -from automata.core.embedding.base import EmbeddingSimilarityCalculator -from automata.core.experimental.search.symbol_search import SymbolSearch -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler -from automata.core.tools.base import Tool +from automata.embedding.base import EmbeddingSimilarityCalculator +from automata.experimental.search.symbol_search import SymbolSearch +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler +from automata.tools.base import Tool logger = logging.getLogger(__name__) @@ -33,7 +33,7 @@ class AgentToolFactory: @staticmethod def create_tools_from_builder(agent_tool: AgentToolkitNames, **kwargs) -> Sequence[Tool]: """Uses the Builder Registry to create tools from a given agent tool name.""" - from automata.core.singletons.toolkit_registries import ( # import here for easy mocking + from automata.singletons.toolkit_registries import ( # import here for easy mocking OpenAIAutomataAgentToolkitRegistry, ) diff --git a/docs/agent/agent.rst b/docs/agent/agent.rst new file mode 100644 index 00000000..581117ff --- /dev/null +++ b/docs/agent/agent.rst @@ -0,0 +1,93 @@ +Automata.core.agent.agent.Agent +=============================== + +``Agent`` class is an abstract base class, used as blueprint for +creating autonomous agents that can perform tasks and communicate. +Instantiation and primary operations of the agent are defined within the +class and are often implemented in subclasses. + +Overview +-------- + +The ``Agent`` is an abstract base class that contains several abstract +methods. These methods are ``__iter__``, ``__next__``, ``run`` and +``set_database_provider``. Derived classes that inherit from ``Agent`` +must provide implementations for these methods. + +Import Statement +---------------- + +.. code:: python + + from automata.agent.agent import Agent + +Methods +------- + +- ``__init__ (self, instructions: str) -> None``: + + Constructor method that initializes an agent with a set of + instructions and sets task completion status and + ``database_provider`` to None. + +- ``__iter__ (self) -> None``: + + An abstract method that should be overridden in subclasses, and used + for iterating over the agent. + +- ``__next__ (self) -> LLMIterationResult``: + + Abstract method used to move the agent one step forward in its task. + Result of this operation is returned as an instance of + ``LLMIterationResult``, or None if task either completed or isn’t + initialized. + +- ``run (self) -> str``: + + Abstract method that should be overridden in subclasses. Designed to + execute the agent’s task until it’s complete - meaning, until + ``__next__`` method returns None. May raise an ``AgentError`` if an + attempt is made to run a task that has already been completed or + exceeds the permissible number of iterations. + +- ``set_database_provider (self, provider: LLMConversationDatabaseProvider) -> None``: + + Abstract method that should be overridden in subclasses. Used to set + the iteration provider for the database. If an agent fails to set a + database provider, ``AgentDatabaseError`` is raised. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` +- ``automata.tests.unit.test_automata_agent.test_build_initial_messages`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` +- ``automata.agent.error.AgentResultError`` +- ``automata.tests.conftest.task`` +- ``automata.tests.unit.sample_modules.sample2.PythonAgentToolkit.python_agent_python_task`` +- ``automata.agent.error.AgentGeneralError`` +- ``automata.tests.conftest.automata_agent_config_builder`` +- ``automata.agent.error.AgentDatabaseError`` + +Dependencies +------------ + +- ``automata.llm.foundation.LLMConversationDatabaseProvider`` + +Limitations +----------- + +The ``Agent`` class provides a foundation for creating classes for +specific autonomous agents. However, as it is an abstract base class, it +cannot be instantiated or used on its own. It must be subclassed and its +methods must be implemented according to the specific requirements of +the derived classes. + +Follow-up Questions: +-------------------- + +- What are some common agents that can be implemented from this base + class? +- Can we further expand the ``Agent`` class to include additional + optional base functionalities? diff --git a/docs/agent/agent/config.rst b/docs/agent/agent/config.rst new file mode 100644 index 00000000..4498aafd --- /dev/null +++ b/docs/agent/agent/config.rst @@ -0,0 +1,58 @@ +AgentInstance +============= + +``AgentInstance`` is an abstract class used for implementing a specific +instance of an agent. An instance of an agent can be used to perform a +set of instructions multiple times without having to reinitialize the +agent each time. + +Overview +-------- + +The agent instance object is created by ``create`` class method of +``AgentInstance`` by passing a config_name and description. It can be +run multiple times without having to reinitialize the agent each time. + +Related Symbols +--------------- + +- ``automata.agent.agent.Agent`` +- ``automata.agent.agent.AgentInstance.Config`` +- ``automata.agent.agent.AgentInstance.create`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance`` +- ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` + +Example +------- + +As ``AgentInstance`` is an abstract class, it can’t be instantiated +directly. However, you can create an instance of a class that inherits +from ``AgentInstance``. Here is how you can create an instance of +``OpenAIAutomataAgentInstance``. + +.. code:: python + + from automata.agent.instances import OpenAIAutomataAgentInstance + from automata.agent.config_enums import AgentConfigName + + config_name = AgentConfigName.TEST + description = "This is a test instance" + + agent_instance = OpenAIAutomataAgentInstance.create(config_name=config_name, description=description) + +Limitations +----------- + +A critical limitation of ``AgentInstance`` is that it cannot handle +interactive instructions where user input may modify the subsequent +instructions. Also, as this is an abstract class, only classes that +inherit from ``AgentInstance`` can be instantiated and used. + +Follow-up Questions: +-------------------- + +- What are the responsibilities of the AgentInstance? +- Can one create an instance of custom Agent that inherits from + AgentInstance? +- How does one implement their own version of ``AgentInstance``? diff --git a/docs/agent/agent/index.rst b/docs/agent/agent/index.rst new file mode 100644 index 00000000..c5d573f3 --- /dev/null +++ b/docs/agent/agent/index.rst @@ -0,0 +1,23 @@ +agent +===== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + config + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/agent/agent_database_error.rst b/docs/agent/agent_database_error.rst new file mode 100644 index 00000000..45235708 --- /dev/null +++ b/docs/agent/agent_database_error.rst @@ -0,0 +1,66 @@ +AgentDatabaseError +================== + +``AgentDatabaseError`` is an exception class derived from Python’s +built-in ``Exception`` class and is raised when an ``AutomataAgent`` is +unable to set the database provider. + +Overview +-------- + +In the ``AutomataAgent``, the database provider allows the agent to +connect to a specific type of database to retrieve and store data +related to tasks and conversations. While setting up the agent, if the +database provider fails to set or implement correctly, the +``AgentDatabaseError`` is raised. This data flow and error handling +aspect of ``AgentDatabaseError`` is closely tied up with various other +entities including but not limited to ``AutomataAgentTaskDatabase``, +``AgentConversationDatabase``, and ``AutomataTaskRegistry``. + +Related Symbols +--------------- + +- ``automata.agent.providers.OpenAIAutomataAgent.set_database_provider`` +- ``automata.tasks.agent_database.AutomataTaskRegistry.__init__`` +- ``automata.tasks.agent_database.AutomataAgentTaskDatabase`` +- ``automata.tests.unit.test_conversation_database.db`` +- ``automata.tests.unit.test_task_database.db`` +- ``automata.agent.error.AgentGeneralError`` + +Examples +-------- + +Here is a basic workflow showing how the ``AgentDatabaseError`` might be +utilized within an agent setup process. + +.. code:: python + + # Assuming we have a provider and an agent instance + try: + agent.set_database_provider(provider) + except automata.agent.error.AgentDatabaseError as e: + print(f"Failed to set the database provider: {e}") + +Note: In the above example, it’s assumed that the ``provider`` and +``agent`` variables have been properly initialized, which isn’t shown in +the example. + +Limitations +----------- + +The primary limitation of ``AgentDatabaseError`` relates more to how and +where the exception is raised rather than the exception class itself. +While developers can handle this exception, it is ultimately dependent +on the underlying implementation of how an ``AutomataAgent`` initializes +its database provider. + +Follow-up Questions: +-------------------- + +1. It would be helpful to get more details on what common reasons might + cause ``AgentDatabaseError`` to be raised. +2. How can developers mitigate these issues to ensure that + ``AgentDatabaseError`` is not thrown? +3. How is ``AgentDatabaseError`` different from ``AgentGeneralError`` + and are there any specific scenarios where one is preferred over the + other? diff --git a/docs/agent/agent_general_error.rst b/docs/agent/agent_general_error.rst new file mode 100644 index 00000000..7bb95a08 --- /dev/null +++ b/docs/agent/agent_general_error.rst @@ -0,0 +1,86 @@ +AgentGeneralError +================= + +Overview +-------- + +``AgentGeneralError`` is an exception class in the +``automata.agent.error`` module of the Automata library. This exception +is raised when a general error arises while the automata agent is in +operation. It’s a part of a series of custom exceptions designed to +handle errors specific to the agent’s operations. + +Related Symbols +--------------- + +1. ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` + + A unit test function to validate the initialization of + ``AutomataAgent``. + +2. ``automata.agent.error.AgentTaskGeneralError`` + + An exception raised when a general error occurs during task + execution. + +3. ``automata.agent.error.AgentTaskGitError`` + + An exception raised when the task encounters a git error. + +4. ``automata.agent.error.AgentResultError`` + + An exception raised when the agent fails to produce a result. + +5. ``automata.agent.error.AgentDatabaseError`` + + An exception raised when the agent fails to set the database + provider. + +Examples +-------- + +This exception, like any other, can be raised with a custom error +message as shown below: + +.. code:: python + + try: + # some agent operations + pass + except Exception as e: + raise AgentGeneralError("A general error occurred during agent operation") from e + +This is a generic example that doesn’t contain specific operations since +the ``AgentGeneralError`` is a general error class. + +However, within a more specific context, for instance, during an +operation related to an ``AutomataAgent``, it can be used as follows: + +.. code:: python + + from automata.agent.error import AgentGeneralError + from automata.agent.agent import AutomataAgent + + try: + agent = AutomataAgent() + agent.run() + except Exception as e: + raise AgentGeneralError("A general error occurred while running the agent") from e + +Limitations +----------- + +As ``AgentGeneralError`` is a general exception class, it lacks detailed +information about possible causes of errors compared to more specific +exceptions like ``AgentTaskGitError`` or ``AgentDatabaseError``. +Therefore, it should be used when no other more specific exception is +applicable. + +Follow-up Questions: +-------------------- + +- What are the common scenarios where this error is usually thrown? +- What is the hierarchy of custom exception classes in the + ``automata.agent.error`` module? Does ``AgentGeneralError`` serve as + a parent class to any other exceptions? If not, is there a reason why + not? diff --git a/docs/agent/agent_instance.rst b/docs/agent/agent_instance.rst new file mode 100644 index 00000000..4048e205 --- /dev/null +++ b/docs/agent/agent_instance.rst @@ -0,0 +1,69 @@ +AgentInstance +============= + +``AgentInstance`` is an abstract class used to implement a unique +occurrence of an agent. + +Overview +-------- + +An AgentInstance is used for creating dynamic agent instances based on +specific agent configurations. It provides a blueprint for creating +multiple agent instances while also facilitating a means to run these +instances. The AgentInstance should be inherited to implement the +``run`` method which can determine the operational logic of the agent. + +Import Statements +----------------- + +.. code:: python + + from abc import ABC, abstractmethod + from automata.config.base import AgentConfigName + +Related Symbols +--------------- + +- ``config.config_enums.AgentConfigName`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` +- ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance`` + +Example +------- + +This example shows how to use the ``AgentInstance.create`` method to +create an agent instance. Inherit the ``AgentInstance`` abstract class +and implement the ``run`` method to create a custom agent instance. + +.. code:: python + + from automata.config.base import AgentConfigName + from automata.agent.agent import AgentInstance + + class MyAgent(AgentInstance): + def run(self, instructions: str) -> str: + return "Hello, World!" + + config_name = AgentConfigName.TEST + agent = MyAgent.create(config_name) + print(agent.run("Hello, World!")) # Outputs: Hello, World! + +Limitations +----------- + +The ``AgentInstance`` class lacks default implementations of its core +functionalities. Therefore, it cannot be directly instantiated and must +be subclassed, providing concrete implementations of its abstract +methods. + +Follow-up Questions +------------------- + +- How does the ``create`` class method interact with the implementation + of ``run``? +- What explicit configurations does ``AgentConfigName`` provide to the + ``create`` method? +- How are different agent behaviors handled when building multiple + instances of the same agent? diff --git a/docs/agent/agent_max_iter_error.rst b/docs/agent/agent_max_iter_error.rst new file mode 100644 index 00000000..0f7bc6b7 --- /dev/null +++ b/docs/agent/agent_max_iter_error.rst @@ -0,0 +1,70 @@ +AgentMaxIterError +================= + +``AgentMaxIterError`` is an exception class in automata.agent.error +module that is raised when an agent exceeds the maximum number of +iterations during its execution. + +Overview +-------- + +``AgentMaxIterError`` can be used to handle errors when the execution of +an agent’s tasks doesn’t complete within the maximum number of +iterations allowed by the agent’s configuration. This prevents the agent +from being stuck in an infinite loop if a task isn’t producing the +expected results or isn’t reaching completion. + +Related Symbols +--------------- + +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.config.base.AgentConfigBuilder.with_max_iterations`` +- ``automata.agent.error.AgentStopIteration`` + +Example +------- + +The ``AgentMaxIterError`` can be used to gracefully handle exceptions +when running an agent. Here is an illustrative example: + +.. code:: python + + from automata.agent.error import AgentMaxIterError + from automata.agent.providers import OpenAIAutomataAgent + from automata.config.base import AgentConfigBuilder + + # Instantiate a config builder and set max_iterations + config_builder = AgentConfigBuilder() + config_builder = config_builder.with_max_iterations(5) + + # Instantiate an agent with the above configuration + my_agent = OpenAIAutomataAgent("Instructions to the agent", config_builder.build()) + + # Run the agent and catch the exception if it exceeds maximum iterations + try: + my_agent.run() + except AgentMaxIterError: + print("The agent has exceeded the maximum number of iterations allowed.") + +Limitations +----------- + +One of the limitations of the ``AgentMaxIterError`` is that it depends +on the maximum number of iterations set in the agent configuration. If +the maximum iterations are set too high, it could result in an agent +running for an excessively long time before the error is raised. +Conversely, if it’s set too low, normal processes might be prematurely +interrupted by the error. + +Follow-up Questions: +-------------------- + +- How is the ideal maximum number of iterations determined for + different types of agents? +- How will the system behave if the maximum number of iterations isn’t + set in the agent configuration? + +*This documentation is based on the code context provided and some +assumptions might have been made. For example, it’s assumed that ‘agent’ +mentioned in the docstrings refers to instances of +``OpenAIAutomataAgent``.* diff --git a/docs/agent/agent_result_error.rst b/docs/agent/agent_result_error.rst new file mode 100644 index 00000000..5d197c4f --- /dev/null +++ b/docs/agent/agent_result_error.rst @@ -0,0 +1,66 @@ +AgentResultError +================ + +Overview +-------- + +``AgentResultError`` is an exception class in the +``automata.agent.error`` module. This exception is raised when an +instance of an agent fails to produce a result during the execution +process. It’s typically thrown if there’s an issue with the method call +of an agent. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_automata_agent.test_run_with_no_completion`` +- ``automata.tests.unit.test_automata_agent.mock_openai_response_with_completion_message`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.tests.unit.test_automata_agent.test_iter_step_without_api_call`` +- ``automata.agent.error.AgentTaskStateError`` +- ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` +- ``automata.agent.agent.Agent`` +- ``automata/tests/unit/test_automata_agent.test_build_initial_messages`` +- ``automata.agent.error.AgentTaskGeneralError`` +- ``automata.tests.conftest.task`` + +Example +------- + +The following is an example demonstrating how to handle the +``AgentResultError`` exception when using an agent: + +.. code:: python + + from automata.agent.providers import OpenAIAutomataAgent + from automata.agent.error import AgentResultError, AgentMaxIterError + + try: + agent = OpenAIAutomataAgent( + "Test Instructions", + config=UserDefinedConfig() + ) + agent.run() + except (AgentResultError, AgentMaxIterError) as error: + print(str(error)) + +Here, we’ve created an instance of OpenAIAutomataAgent and called the +``run()`` method, set within a try-catch block to catch +``AgentResultError`` or ``AgentMaxIterError`` exceptions. + +Limitations +----------- + +The ``AgentResultError`` provides a general exception case, but detailed +debugging may become complex due to less layer-specific error +information. More specific exceptions can help in identifying the issue +faster, without tracing through the entire execution. + +Follow-Up Questions +------------------- + +- What are the common reasons for the agent to fail to produce a + result? +- How can we better handle ``AgentResultError`` and + ``AgentMaxIterError`` exceptions to prevent abrupt termination of the + program? diff --git a/docs/agent/agent_stop_iteration.rst b/docs/agent/agent_stop_iteration.rst new file mode 100644 index 00000000..6ab9e725 --- /dev/null +++ b/docs/agent/agent_stop_iteration.rst @@ -0,0 +1,92 @@ +automata.agent.error.AgentStopIteration +======================================= + +Overview +-------- + +``AgentStopIteration`` is a built-in exception class in the ``automata`` +library. It is raised when the agent stops iterating in the program +execution process. It provides useful debugging information if a running +agent stops iterating prematurely for some reason. + +The ``AgentStopIteration`` exception is mostly used within classes that +implement the Python iterable and iterator protocols. It serves as a +signal to the agent’s iterator to stop the iteration process. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_automata_agent.test_run_with_no_completion``: + This unit test uses the ``AgentStopIteration`` exception to ensure + the ``automata_agent`` stops iterating when no completion is present. + +- ``automata.tests.unit.test_automata_agent.test_iter_step_without_api_call``: + In this unit test, ``AgentStopIteration`` reflects the expected + behavior when manually feeding next(…) calls to the automata agent + without an API call. + +- ``automata.agent.error.AgentMaxIterError``: This is another exception + class used when the agent exceeds the maximum number of allowed + iterations. + +- ``automata.agent.agent.Agent.__iter__``: The ``__iter__`` method of + the ``Agent`` class calls upon the ``AgentStopIteration`` when the + agent stops iterating. + +- ``automata.agent.providers.OpenAIAutomataAgent``: The + ``OpenAIAutomataAgent``, designed to execute instructions and + interact with various tools, uses the ``AgentStopIteration`` + exception to handle situations where the agent ceases to iterate. + +- ``automata.agent.providers.OpenAIAutomataAgent.__iter__``: The + ``__iter__`` method in the ``OpenAIAutomataAgent`` class handles the + ``AgentStopIteration`` exception when the iteration process is + stopped. + +Example +------- + +There’s no directly instantiable example of ``AgentStopIteration`` as it +is raised when an iteration is stopped in a running agent. However, +below is an example of a possible use case in context of +``OpenAIAutomataAgent``. Please note mock situations have been +represented without the actual underlying object: + +.. code:: python + + from unittest.mock import patch + from automata.agent.providers import OpenAIAutomataAgent + from automata.agent.error import AgentMaxIterError + + @patch("openai.ChatCompletion.create") + def test_agent_stops_iteration(mock_openai_chatcompletion_create, automata_agent): + automata_agent = OpenAIAutomataAgent('instructions', 'config') + # Mock the API response + mock_openai_chatcompletion_create.return_value = { + "choices": [{"message": {"content": "...", "role": "assistant"}}] + } + + try: + automata_agent.run() # runs the agent + except AgentStopIteration: + print("Agent has stopped iterating.") + +In this code snippet, ``AgentStopIteration`` is expected to be raised +when ``automata_agent.run()`` is called. If the agent stops, the +exception is caught and it prints “Agent has stopped iterating.” + +Limitations +----------- + +The ``AgentStopIteration`` exception is raised when the agent stops +iterating. However, it does not provide information regarding why the +agent stopped iterating. Determining the agents stopping reasoning +requires additional debugging or error checks within the code. + +Follow-up Questions +------------------- + +- What specific conditions in the agent’s operations trigger + ``AgentStopIteration``? +- Can we handle and resume from ``AgentStopIteration`` in certain + contexts? diff --git a/docs/agent/agent_task_general_error.rst b/docs/agent/agent_task_general_error.rst new file mode 100644 index 00000000..ff2dd124 --- /dev/null +++ b/docs/agent/agent_task_general_error.rst @@ -0,0 +1,73 @@ +AgentTaskGeneralError +===================== + +``AgentTaskGeneralError`` is an exception class that is raised whenever +a general type of error arises during task execution in an Automata +agent. This error may encompass a wide range of issues, from coding or +logical errors in the tasks to unforeseen scenarios causing an +exception. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_task_executor.test_execute_automata_task_fail`` +- ``automata.tests.unit.test_task_environment.test_commit_task`` +- ``automata.agent.error.AgentGeneralError`` +- ``automata.tests.unit.test_task.test_task_inital_state`` +- ``automata.agent.error.AgentTaskGitError`` +- ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` +- ``automata.agent.error.AgentTaskInstructions`` +- ``automata.tests.unit.test_task_environment.TestURL`` +- ``automata.agent.error.AgentTaskStateError`` +- ``automata.tests.unit.test_task_executor.TestExecuteBehavior`` + +Example +------- + +The following example demonstrates how the ``AgentTaskGeneralError`` +exception could be used in a test case scenario. + +.. code:: python + + from unittest.mock import patch, MagicMock + from automata.agent.error import AgentTaskGeneralError + import pytest + + @patch("logging.config.dictConfig", return_value=None) + def test_execute_automata_task_fail(_, module_loader, task, environment, registry): + registry.register(task) + environment.setup(task) + + execution = MagicMock() + task_executor = AutomataTaskExecutor(execution) + task_executor.execution.execute.side_effect = AgentTaskGeneralError("Execution failed") + + with pytest.raises(AgentTaskGeneralError, match="Execution failed"): + task_executor.execute(task) + + assert task.status == TaskStatus.FAILED + assert task.error == "Execution failed" + +Limitations +----------- + +The ``AgentTaskGeneralError`` class correlates directly with the type +definition provided by Python’s native exception handling system. Hence, +it inherits the limitations from Python’s exception system. Also, as it +is a general error, it might not provide the specific error details +needed for debugging. + +Follow-up Questions: +-------------------- + +- What types of errors specifically fall under + ``AgentTaskGeneralError``? +- What are the common types of general errors encountered during task + execution? +- What details are generally encompassed in the error message of + ``AgentTaskGeneralError``? + +Please note that while ``Mock`` objects are significantly featured in +the presented examples, they are primarily used for testing and +simplifying interactions with complex objects. Please replace mocks with +actual objects during real implementation. diff --git a/docs/agent/agent_task_git_error.rst b/docs/agent/agent_task_git_error.rst new file mode 100644 index 00000000..c2b55a9c --- /dev/null +++ b/docs/agent/agent_task_git_error.rst @@ -0,0 +1,71 @@ +AgentTaskGitError +================= + +``AgentTaskGitError`` is an exception class that gets raised when there +is an error encountered with git operations in the task. + +Related Symbols +--------------- + +- ``automata.tests.conftest.MockRepositoryClient`` +- ``automata.tests.unit.test_task_environment.test_commit_task`` +- ``automata.github_management.client.GitHubClient`` +- ``automata.tests.conftest.environment`` +- ``automata.github_management.client.GitHubClient.clone_repository`` +- ``automata.tests.conftest.MockRepositoryClient.clone_repository`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tests.conftest.MockRepositoryClient.checkout_branch`` +- ``automata.github_management.client.GitHubClient.__init__`` +- ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` + +Using AgentTaskGitError +----------------------- + +Due to the nature of this exception, its usage is not as straightforward +as other classes. It will be raised when an error is encountered while +performing Git operations on a task. Here’s an example of how such a +scenario might occur: + +.. code:: python + + def test_commit_task(task, mocker, environment): + # Setup + os.makedirs(task.task_dir, exist_ok=True) + task.status = TaskStatus.SUCCESS + mocker.spy(environment.github_manager, "create_branch") + # Execution + try: + environment.commit_task( + task, + commit_message="This is a commit message", + pull_title="This is a test", + pull_body="I am testing this...", + pull_branch_name="test_branch__ZZ__", + ) + except AgentTaskGitError as e: + print(f"An error occurred: {e}") + +In the scenario above, we are testing the ``commit_task`` method, and +``AgentTaskGitError`` may be raised if there’s an error with any of the +git operations like creating a branch, checking out a branch, staging +all changes, committing and pushing changes, or creating a pull request. + +Limitations +----------- + +``AgentTaskGitError``, being an exception class, has its purpose solely +to signal the occurrence of an event that disrupts normal operation. It +doesn’t perform any operation regarding solving the problem or avoiding +it instead it exists just to signal it. The limitation regarding error +handling rests on the underlying git operations and methods that lead to +this exception being thrown. + +Follow-up Questions: +-------------------- + +- Can we specify the types of Git errors that could lead to + ``AgentTaskGitError`` being raised? +- Are there certain Git operations more likely to raise this error than + others? +- Are there specific ways to handle ``AgentTaskGitError`` effectively + within tasks? diff --git a/docs/agent/agent_task_instructions.rst b/docs/agent/agent_task_instructions.rst new file mode 100644 index 00000000..f87a944a --- /dev/null +++ b/docs/agent/agent_task_instructions.rst @@ -0,0 +1,63 @@ +AgentTaskInstructions +===================== + +``AgentTaskInstructions`` is an exception class that is raised when +there is an error with the instructions for a given task. This class is +primarily used in the context of ``AutomataTask`` and its methods to +ensure proper task setup and execution. + +Overview +-------- + +``AgentTaskInstructions`` is an integral part of validation of task +execution. Instances of ``AutomataTask`` are created with detailed +instructions, which serve as requirements for any given task to be +executed by the TaskExecutor. If instructions are either not provided or +are empty, the ``AgentTaskInstructions`` exception is raised to halt +execution and signal the error. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_task_database.task`` +- ``automata.tests.conftest.task`` +- ``automata.tasks.tasks.AutomataTask`` +- ``automata.tests.unit.test_automata_agent.test_build_initial_messages`` +- ``automata.tasks.tasks.AutomataTask.__init__`` +- ``automata.tests.unit.test_task_executor.TestExecuteBehavior`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.tests.unit.test_task_executor.TestExecuteBehavior.execute`` +- ``automata.agent.agent.AgentInstance.run`` +- ``automata.tests.unit.sample_modules.sample2.PythonAgentToolkit.python_agent_python_task`` + +Example +------- + +The following is an example demonstrating how an +``AgentTaskInstructions`` exception is raised when instructions are +missing or empty for an ``AutomataTask`` instance. + +.. code:: python + + from automata.tasks.tasks import AutomataTask + + try: + task = AutomataTask("") # Empty instructions + except AgentTaskInstructions: + print("AgentTaskInstructions exception raised. Task instructions cannot be empty.") + +Limitations +----------- + +One important limitation of ``AgentTaskInstructions`` is its dependence +on developer vigilance. That is, if the developer correctly provides +task instructions every time an ``AutomataTask`` instance is created, +this exception would never need to be raised. Conversely, in the absence +of this, the system can come to a halt if instructions are missing. + +Follow-up Questions: +-------------------- + +- Does ``AgentTaskInstructions`` support multi-language error messages? +- Can a different mechanism be used to check instructions validity to + avoid system halt? diff --git a/docs/agent/agent_task_state_error.rst b/docs/agent/agent_task_state_error.rst new file mode 100644 index 00000000..4113777a --- /dev/null +++ b/docs/agent/agent_task_state_error.rst @@ -0,0 +1,74 @@ +AgentTaskStateError +=================== + +Overview +-------- + +``AgentTaskStateError`` is an exception class in +``automata.agent.error`` module that is raised when the task is not in +the correct state for the operation. This class deals with erroneous +cases where, for instance, an action is being performed on a task but +its state is not correctly set for that particular action. + +Related Symbols +--------------- + +- ``automata.tasks.base.TaskStatus``: Refers to various statuses a task + can have, like ``CREATED``, ``RETRYING``, ``FAILED``, ``SUCCESS``, + etc. +- ``automata.tests.unit.test_task.test_task_inital_state``: A unit test + that asserts if the initial status of the task is ``CREATED``. +- ``automata.tests.unit.test_task.test_status_setter``: A unit test to + check if the task status can be set to ``RETRYING``. +- ``automata.agent.error.AgentTaskGitError``: An exception raised when + the task encounters a git related error. +- ``automata.agent.error.AgentTaskGeneralError``: An exception raised + when a general error occurs during task execution. +- ``automata.agent.error.AgentTaskInstructions``: An exception raised + when there is an error with the task instructions. + +Example +------- + +The following is a simplified example demonstrating how +``AgentTaskStateError`` could be used: + +.. code:: python + + from automata.agent.error import AgentTaskStateError + from automata.tasks.base import TaskStatus, AutomataTask + + # Creating a Mock Task + task = AutomataTask() + + # Simulating a condition where task is being executed without setting its status to 'EXECUTING' + try: + if task.status != TaskStatus.EXECUTING: + raise AgentTaskStateError('Task status is not set to EXECUTING.') + except AgentTaskStateError as e: + print(str(e)) + +In the above example, an ``AgentTaskStateError`` is raised if an attempt +is made to execute a task, ``task``, without changing its status to +``EXECUTING``. + +Note: Mocks are used in the above example for demonstration. In actual +usage, replace the ``AutomataTask()`` with the actual Operation to be +performed. + +Limitations +----------- + +The ``AgentTaskStateError`` class on its own doesn’t have limitations as +it is simply a description of a specific type of error that could occur. +The limitations would rather be on the workflow scale where +mismanagement or lack of proper checks on the task’s state could lead to +such errors. + +Follow-up Questions: +-------------------- + +- How does the execution pipeline ensure that the tasks go through the + proper state changes? +- Could there be any adverse effects if the state of a task is not + managed properly? diff --git a/docs/agent/agent_toolkit_builder.rst b/docs/agent/agent_toolkit_builder.rst new file mode 100644 index 00000000..3fe5e30c --- /dev/null +++ b/docs/agent/agent_toolkit_builder.rst @@ -0,0 +1,94 @@ +AgentToolkitBuilder +=================== + +``AgentToolkitBuilder`` is an abstract class used for building tools for +various providers. These tools, once built, are associated with the +respective ``AgentToolkitNames``. + +Overview +-------- + +The fundamental purpose of ``AgentToolkitBuilder`` is to offer a +standardized way to create a collection of tools that can be used with +different types of agents, as defined by the ``AgentToolkitNames``. + +Given the abstract nature of this class, it doesn’t instantiate any +object on its own, but outlines the requirements for +sub-classes/offspring of the ``AgentToolkitBuilder``. + +Related Symbols +--------------- + +Here are some related classes that build upon or interact with +``AgentToolkitBuilder``: + +- ``ContextOracleOpenAIToolkitBuilder`` +- ``SymbolSearchOpenAIToolkitBuilder`` +- ``PythonAgentToolkit`` +- ``OpenAIAgentToolkitBuilder`` +- ``PyWriterOpenAIToolkitBuilder`` + +Mandatory Methods +----------------- + +The ``AgentToolkitBuilder`` possesses an abstract method named +``build``: + +.. code:: python + + @abstractmethod + def build(self) -> List[Tool]: + pass + +This method, once implemented in the subclasses, is expected to return a +list of ``Tool`` objects. + +Example +------- + +Let’s provide an example of a class ``PythonAgentToolkit`` which +inherits from ``AgentToolkitBuilder``. + +.. code:: python + + from automata.tools.base import Tool + + class PythonAgentToolkit: + def __init__(self, python_agent: PythonAgent): + self.python_agent = python_agent + + def build(self) -> List[Tool]: + def python_agent_python_task(): + pass + + tools = [ + Tool( + "automata-task", + python_agent_python_task, + "Execute a Python task using the PythonAgent. Provide the task description in plain English.", + ) + ] + return tools + +In this example, the subclass ``PythonAgentToolkit`` implements the +``build`` method to generate a list of ``Tool`` items. + +Limitations and Considerations +------------------------------ + +Since ``AgentToolkitBuilder`` is an abstract class, it should not be +instantiated directly. Instead, create a subclass that implements the +``build`` method. The usage and appropriateness of this class and its +subclasses will depend on the corresponding agent context where this +toolkit would be used. + +Follow-up Questions: +-------------------- + +- Are there existing subclasses of ``AgentToolkitBuilder`` apart from + the ones identified? +- Are there any additional methods that could be part of the + ``AgentToolkitBuilder``, to be implemented by subclasses? +- Any specific structures to be maintained in the ``Tool`` objects + built by the subclasses? How are these ``Tool`` objects expected to + interact with agents? diff --git a/docs/agent/agent_toolkit_names.rst b/docs/agent/agent_toolkit_names.rst new file mode 100644 index 00000000..6d728b80 --- /dev/null +++ b/docs/agent/agent_toolkit_names.rst @@ -0,0 +1,57 @@ +AgentToolkitNames +================= + +``AgentToolkitNames`` is an enumeration class that represents different +types of agent tools in the ``automata.agent.agent`` package. This class +helps manage a collection of agent tools that can be used for distinct +tasks. Each named enum member corresponds to a particular type of agent +tool. The builders for these tools are located in the +``automata/core/agent/builder/`` directory. + +Related Symbols +--------------- + +- ``automata.tests.unit.sample_modules.sample2.PythonAgentToolkit``: A + class for building tools to interact with a PythonAgent. +- ``automata.tests.unit.test_automata_agent_builder.test_builder_accepts_all_fields``: + A test function that demonstrates the use of the builder. +- ``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder``: + Builds tools for Open AI. +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``: + Builds tools for Context Oracle. +- ``automata.tools.factory.AgentToolFactory``: A factory class for + creating tools from a given agent tool name. +- ``automata.agent.agent.AgentToolkitBuilder``: an abstract class for + building tools. + +Example +------- + +Below is a brief example of how you can use ``AgentToolkitNames``: + +.. code:: python + + from automata.agent.agent import AgentToolkitNames + + # Get a specific toolkit name + toolkit_name = AgentToolkitNames.PYTHON + + # You can also list all toolkit names + all_toolkit_names = list(AgentToolkitNames) + +Limitations +----------- + +The ``AgentToolkitNames`` enum is limited to the tool names it defines; +you can’t add new names to the enum after it’s defined. If a new tool is +to be supported, its name must be added to this enum class. Remember to +also create a corresponding builder in ``automata/core/agent/builder/``. + +Follow-up Questions: +-------------------- + +- What specific toolkits exist under each ``AgentToolkitNames``? +- How are the builders for each ``AgentToolkitNames`` written and + maintained? +- Are there any best practices or guidelines when adding new toolkit + names and their corresponding builders? diff --git a/docs/agent/index.rst b/docs/agent/index.rst new file mode 100644 index 00000000..600dbff0 --- /dev/null +++ b/docs/agent/index.rst @@ -0,0 +1,41 @@ +agent +===== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + agent + agent_database_error + agent_general_error + agent_instance + agent_max_iter_error + agent_result_error + agent_stop_iteration + agent_task_general_error + agent_task_git_error + agent_task_instructions + agent_task_state_error + agent_toolkit_builder + agent_toolkit_names + open_ai_agent_toolkit_builder + open_ai_automata_agent + open_ai_automata_agent_instance + unknown_tool_error + agent/index + instances/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/agent/instances/config.rst b/docs/agent/instances/config.rst new file mode 100644 index 00000000..4a10c418 --- /dev/null +++ b/docs/agent/instances/config.rst @@ -0,0 +1,66 @@ +OpenAIAutomataAgentInstance +=========================== + +The ``OpenAIAutomataAgentInstance`` is a class that stores the +instructions and configuration for an ``OpenAIAutomataAgent`` such that +it can be run multiple times without having to reinitialize the agent +each time. This class ensures reusability and efficient handling of the +``OpenAIAutomataAgent``. + +Overview +-------- + +The ``OpenAIAutomataAgentInstance`` has the ability to store both the +instructions and the config of an agent while also providing a method to +run the agent using those stored instructions. Due to this, the same +instance of an agent can be reused for multiple runs, improving +efficiency and system performance. + +Related Symbols +--------------- + +- ``automata.agent.providers.OpenAIAutomataAgent``: The agent that this + class holds an instance of. +- ``automata.config.openai_agent.OpenAIAutomataAgentConfig``: The + configuration used by the agent. +- ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init``: + A test checking the initialization of the agent. +- ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance``: + A test confirming a proper instance creation of the agent. + +Example +------- + +Here is an example of how to use the ``OpenAIAutomataAgentInstance``: + +.. code:: python + + from automata.config.openai_agent import OpenAIAutomataAgentConfig + from automata.config.config_enums import AgentConfigName + from automata.agent.instances import OpenAIAutomataAgentInstance + + # load configuration + config = OpenAIAutomataAgentConfig.load(AgentConfigName.TEST) + + # Create instance of OpenAIAutomataAgent + agent_instance = OpenAIAutomataAgentInstance(config) + + # Use the run method with instructions + result = agent_instance.run("Enter your instructions here") + +Limitations +----------- + +The ``OpenAIAutomataAgentInstance`` depends on ``OpenAIAutomataAgent`` +and ``OpenAIAutomataAgentConfig``. Hence, it’s functionality is largely +dependent on these classes. Also, initialization of +``OpenAIAutomataAgentInstance`` requires configuration details which may +limit its usability. + +Follow-Up Questions: +-------------------- + +- How can we modify ``OpenAIAutomataAgentInstance`` to be more + independent and less configuration-dependent? +- Can there be a default configuration for + ``OpenAIAutomataAgentInstance`` to improve its usability? diff --git a/docs/agent/instances/index.rst b/docs/agent/instances/index.rst new file mode 100644 index 00000000..f3bc5234 --- /dev/null +++ b/docs/agent/instances/index.rst @@ -0,0 +1,23 @@ +instances +========= + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + config + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/agent/open_ai_agent_toolkit_builder.rst b/docs/agent/open_ai_agent_toolkit_builder.rst new file mode 100644 index 00000000..836037eb --- /dev/null +++ b/docs/agent/open_ai_agent_toolkit_builder.rst @@ -0,0 +1,64 @@ +OpenAIAgentToolkitBuilder +========================= + +``OpenAIAgentToolkitBuilder`` is an abstract class for building OpenAI +agent tools. It is used to define ``build_for_open_ai`` and +``can_handle`` as abstract methods. Developers intending to use OpenAI +for agents should subclass from ``OpenAIAgentToolkitBuilder`` and +provide implementations for these methods. + +Overview +-------- + +Some classes that have implemented the ``OpenAIAgentToolkitBuilder`` +abstract class include +``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``, +``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder``, +and ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` +among others. Every implementing class must define the +``build_for_open_ai`` method which returns a list of ``OpenAITool`` +objects, and the ``can_handle`` method which checks if the class can +handle a given tool manager. + +Related Symbols +--------------- + +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.agent.agent.AgentToolkitBuilder`` +- ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` +- ``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` + +Example +------- + +.. code:: python + + from automata.tools.builders.context_oracle import ContextOracleOpenAIToolkitBuilder + + class MyOpenAIToolkitBuilder(ContextOracleOpenAIToolkitBuilder): + TOOL_TYPE = "my-type" + + def build_for_open_ai(self): + # Create a list of OpenAITools here + openai_tools = [OpenAITool(...), OpenAITool(...)] + return openai_tools + +The above example creates a subclass of +``ContextOracleOpenAIToolkitBuilder`` that builds OpenAI tools for the +``"my-type"`` toolkit. + +Limitations +----------- + +As ``OpenAIAgentToolkitBuilder`` is an abstract class, it cannot be +instantiated directly and must be subclassed with implementation +provided for the ``build_for_open_ai`` and ``can_handle`` methods. + +Follow-up Questions: +-------------------- + +- What happens if the subclass does not provide implementation for the + ``build_for_open_ai`` and ``can_handle`` methods? +- Can there be multiple ways to implement the ``build_for_open_ai`` + method or is there a particular way it should be done? diff --git a/docs/agent/open_ai_automata_agent.rst b/docs/agent/open_ai_automata_agent.rst new file mode 100644 index 00000000..e0e682b1 --- /dev/null +++ b/docs/agent/open_ai_automata_agent.rst @@ -0,0 +1,75 @@ +OpenAIAutomataAgent +=================== + +``OpenAIAutomataAgent`` is an autonomous agent used to execute +instructions and report the results back to the main system. It +communicates with the OpenAI API to generate responses based on given +instructions and manages interactions with various tools. + +Overview +-------- + +``OpenAIAutomataAgent`` uses OpenAI API to iterate over instructions and +generates user and assistant messages using the +``get_next_user_response`` and ``get_next_assistant_completion`` methods +from the OpenAI’s chat completion provider, respectively. + +``OpenAIAutomataAgent`` carries an OpenAI conversation database to store +messages and other operational data during its life cycle. The agent is +made to operate in iterations and stop iterating when it completes its +task or exceeds the maximum iterations set in the configuration. + +``OpenAIAutomataAgent`` uses tools that are instance of ``OpenAITool``. +Each ``OpenAIFunction`` associated with an ``OpenAITool`` represents +specific capabilities of the agent. + +Usage: +------ + +The basic usage of ``OpenAIAutomataAgent`` involves initialization with +instructions and configuration, iteration over instructions and +execution of tasks. For example: + +.. code:: python + + from automata.agent.providers import OpenAIAutomataAgent + from automata.config.openai_agent import OpenAIAutomataAgentConfig + # Create OpenAIAutomataAgentConfig + config = OpenAIAutomataAgentConfig() + # Initialize OpenAIAutomataAgent + agent = OpenAIAutomataAgent('your_instructions', config) + # Iterate over instructions + for message in agent: + print(message) + # Run the agent + result = agent.run() + +Related Symbols and Dependencies: +--------------------------------- + +- ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` +- ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` +- ``automata.config.openai_agent.OpenAIAutomataAgentConfig`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance`` +- ``automata.tests.conftest.automata_agent_config_builder`` +- ``automata.config.openai_agent.OpenAIAutomataAgentConfigBuilder`` +- ``automata.tests.unit.test_automata_agent.test_build_initial_messages`` +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.agent.error.AgentResultError`` + +Limitations +----------- + +Full functionality of ``OpenAIAutomataAgent`` depends on the integration +with OpenAI API requirements and limitations. For instance, the +``OpenAIAutomataAgent`` class might need improvements in logging and +exception handling. Additionally, it currently does not support multiple +assistants. + +Follow-up Questions: +-------------------- + +- How can the iteration process in ``OpenAIAutomataAgent`` be improved? +- Can multiple assistants be implemented in ``OpenAIAutomataAgent``? +- How can the logging and exception handling in ``OpenAIAutomataAgent`` + be made more robust? diff --git a/docs/agent/open_ai_automata_agent_instance.rst b/docs/agent/open_ai_automata_agent_instance.rst new file mode 100644 index 00000000..6ae5a9d5 --- /dev/null +++ b/docs/agent/open_ai_automata_agent_instance.rst @@ -0,0 +1,62 @@ +OpenAIAutomataAgentInstance +=========================== + +``OpenAIAutomataAgentInstance`` provides an interface for running an +instance of an Automata OpenAI agent multiple times without needing to +reinitialize the agent each time. + +Overview +-------- + +The class stores instructions and configuration for an automata agent, +allowing it to execute those instructions, leveraging the OpenAI API. By +providing instruction configuration, this class enables consistent +responses from the AI agent across multiple runs, thus boosting +performance and efficiency. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.config.openai_agent.OpenAIAutomataAgentConfigBuilder`` + +Example +------- + +In the following example, an instance of ``OpenAIAutomataAgentInstance`` +is created by providing instructions. The instance executes the +instructions and returns the result. + +.. code:: python + + from automata.agent.instances import OpenAIAutomataAgentInstance + from automata.config.base import AgentConfigName + + config_name = AgentConfigName.AUTOMATA_MAIN + instructions = "Hello, this is a test instruction" + + agent_instance = OpenAIAutomataAgentInstance(config_name=config_name) + + result = agent_instance.run(instructions) + +Limitations +----------- + +Currently, the ``run`` method raises a generic Exception for any error +that occurs during agent execution. More specific exceptions could offer +better insight into what could go wrong during execution. + +Another limitation is that there is no explicit feature to save or load +previously created instances. Saving and restoring instances would allow +for better reusability and faster startup times. + +Follow-up Questions: +-------------------- + +- Can the exception handling be more specific, for instance, by + throwing different types of exceptions based on different error + conditions? +- Is there a possibility to implement functionality for saving and + loading previously created instances? +- Does the agent have a limit on the number of times it can be run? diff --git a/docs/agent/unknown_tool_error.rst b/docs/agent/unknown_tool_error.rst new file mode 100644 index 00000000..f9a6a111 --- /dev/null +++ b/docs/agent/unknown_tool_error.rst @@ -0,0 +1,69 @@ +UnknownToolError +================ + +Overview +-------- + +``UnknownToolError`` is an exception class in the +``automata.agent.error`` module. This exception is raised when an +unknown tool type is provided to the framework. + +In broad terms, a tool in this context refers to a callable +functionality of the system (such as ``TestTool`` or any class +inheriting from ``Tool``), which can be invoked with a certain input to +produce a certain output. + +For instance, when building tools for an agent like this +``AgentToolFactory.create_tools_from_builder(agent_tool: AgentToolkitNames, **kwargs)``, +if an unrecognized ``agent_tool`` is provided, ``UnknownToolError`` is +raised. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_tool.test_tool_instantiation`` +- ``automata.tests.unit.test_tool.TestTool`` +- ``automata.tests.unit.test_tool.test_tool_run`` +- ``automata.tools.base.Tool`` +- ``automata.tests.unit.test_context_oracle_tool.test_init`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder.can_handle`` +- ``automata.tests.unit.test_tool.test_tool`` +- ``automata.tools.factory.AgentToolFactory.create_tools_from_builder`` +- ``automata.tests.unit.test_context_oracle_tool.test_build`` +- ``automata.agent.agent.AgentToolkitBuilder.build`` + +Usage Example +------------- + +.. code:: python + + from automata.tools.factory import AgentToolFactory + from automata.agent.error import UnknownToolError + + try: + tool = AgentToolFactory.create_tools_from_builder("NonExistentTool") + except UnknownToolError as e: + print(str(e)) # Will print error message about unknown tool type. + +Limitations +----------- + +``UnknownToolError`` is a basic extension of Python’s built-in +``Exception`` class, and thus shares the same limitations. It’s sole +purpose is to provide meaningful error information when an unrecognized +tool type is provided to the framework. It is not designed to handle +additional error processing or functionality. + +As a part of error handling in the ``automata`` library, efficient usage +of this error class assumes that developers using this library have a +handle on the tool types that are permitted to be used. + +Follow-up Questions +------------------- + +- What are the specific conditions which may lead to this error beyond + the tool being unknown or unrecognized? +- Does this exception handle other edge cases such as the input type + not matching the expected tool type? +- Besides the tool name, are there any other parameters or information + that could be helpful to include in the error message? diff --git a/docs/agent_guide.rst b/docs/agent_guide.rst index 2ea83eb1..c0c8ccb4 100644 --- a/docs/agent_guide.rst +++ b/docs/agent_guide.rst @@ -44,7 +44,7 @@ Usage .. code-block:: python - from automata.core.agent.providers import OpenAIAutomataAgent + from automata.agent.providers import OpenAIAutomataAgent from automata.config.openai_agent import OpenAIAutomataAgentConfig # Create OpenAIAutomataAgentConfig diff --git a/docs/code_handling/index.rst b/docs/code_handling/index.rst new file mode 100644 index 00000000..44bdce5f --- /dev/null +++ b/docs/code_handling/index.rst @@ -0,0 +1,23 @@ +code_handling +============= + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + py/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/code_handling/py/index.rst b/docs/code_handling/py/index.rst new file mode 100644 index 00000000..3501fc47 --- /dev/null +++ b/docs/code_handling/py/index.rst @@ -0,0 +1,26 @@ +py +== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + py_doc_writer + py_reader + py_writer + writer/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/code_handling/py/py_doc_writer.rst b/docs/code_handling/py/py_doc_writer.rst new file mode 100644 index 00000000..f2796e5c --- /dev/null +++ b/docs/code_handling/py/py_doc_writer.rst @@ -0,0 +1,115 @@ +PyDocWriter +=========== + +``PyDocWriter`` is a class designed to handle the automatic generation +of documentation for Python modules. It offers utility functions for +cleaning and preparing the content, as well as preparing the directory +structure for the generated documentation. This class is a tool to +automate the manual task and reduce the effort required to generate +readable and well-structured documentations. + +Overview +-------- + +The primary purpose of the ``PyDocWriter`` class is to parse Python +files and generate corresponding RestructuredText (.rst) documentation +files. It provides functionalities including converting camel case to +snake case, checking if a string is in camel case, generating index +files, generating module summaries, and generating rst files. + +Related Symbols +--------------- + +- ``PyReader``: A utilitarian class for extracting syntax tree from + python code. +- ``DirectoryManager``: Handles operations related to directory + manipulation like getting subdirectories, ensuring existence of a + directory etc. +- ``PyWriter``: A utility class for writing Python code along abstract + syntax tree (AST) nodes. +- ``Symbol``: A representation of Python classes, methods, or local + variables. +- ``PyReader``: Code retriever for fetching python source code and + associated docstrings. + +Import Statements +----------------- + +.. code:: python + + import logging + import os + import re + import subprocess + import numpy as np + import pypandoc + from typing import Dict, List, Optional, Union, cast + from redbaron import ClassNode, DefNode, Node, NodeList, RedBaron + from automata.code_handling.py.reader import PyReader + from automata.navigation.directory import DirectoryManager + +Methods +------- + +.. code:: python + + def __init__(self, base_path: str) -> None: + self.base_path = base_path + self.directory_manager = DirectoryManager(base_path) + + + @staticmethod + def check_camel_case(text: str) -> bool: + return text != text.lower() and text != text.upper() and "_" not in text + + + def generate_index_files(self, docs_dir: str) -> None: + # Implementation... + + def generate_rst_files(self, docs: Dict[Symbol, SymbolDocEmbedding], symbols: List[Symbol], docs_dir: str) -> None: + # Implementation... + + def write_documentation(self, docs: Dict[Symbol, SymbolDocEmbedding], symbols: List[Symbol], docs_dir: str) -> None: + self.generate_rst_files(docs, symbols, docs_dir) + self.generate_index_files(docs_dir) + +Example Usage +------------- + +.. code:: python + + from automata.code_handling.py.writer import PyDocWriter + from typing import Dict, List + from automata.symbol_embedding.base import SymbolDocEmbedding + from automata.symbol.base import Symbol + + symbol1 = Symbol.from_string(symbol_str='package1 ClassA# method1().') + symbol2 = Symbol.from_string(symbol_str='package2 ClassB# method2().') + + doc1 = SymbolDocEmbedding(symbol=symbol1, document='doc1', vector=np.array([1, 2, 3])) + doc2 = SymbolDocEmbedding(symbol=symbol2, document='doc2', vector=np.array([4, 5, 6])) + + symbol_doc_pairs = {symbol1: doc1, symbol2: doc2} + symbols = [symbol1, symbol2] + + py_doc_writer = PyDocWriter(base_path='/path/to/project') + py_doc_writer.write_documentation(symbol_doc_pairs, symbols, docs_dir='/path/to/output') + +Follow-up Questions +------------------- + +- What are the error handling mechanisms in PyDocWriter class methods? +- Is there a way to customize the way PyDocWriter handles or formats + the content of the documentation according to user preference? +- How does PyDocWriter handle optional dependendencies like ‘pypandoc’ + if not present in the user’s environment? +- What are the consequences of duplicated or repeated symbol keys for + ‘write_documentation’ method? How can such a scenario be prevented? +- How does PyDocWriter handle Python files that contain both underscore + and camel case naming conventions? +- Does the tool support generating documentation for private methods + (those that start with underscore ’\_’) and how does it handle name + mangling for private attributes/methods in Python? +- Is the class designed to be used as part of any specific workflows + for automating documentation generation? If so, how would a typical + workflow look like? diff --git a/docs/code_handling/py/py_reader.rst b/docs/code_handling/py/py_reader.rst new file mode 100644 index 00000000..1e673431 --- /dev/null +++ b/docs/code_handling/py/py_reader.rst @@ -0,0 +1,74 @@ +PyReader +======== + +``PyReader`` is a class built for fetching and handling python code. It +primarily provides functionality to get python source code and +documentation from specified modules, classes, or functions/methods. It +also supports the removal of docstrings from python source code it +fetches. + +Overview +-------- + +The ``PyReader`` interacts with the python module loader to fetch +specific modules based on the given dot-path format e.g., +``package.module``. This class also contains methods to retrieve +docstrings from nodes or python code objects by interacting with the +syntax trees of these objects directly. + +Related Symbols +--------------- + +- ``PyWriter``: A utility class for writing Python code along AST + nodes. +- ``PyModuleLoader``: Class for loading python modules. +- ``PyReaderToolkitBuilder``: A class for arranging components of + ``PyReader``. + +Example +------- + +The following example demonstrates how to create an instance of +``PyReader`` and fetch python source code of specific modules: + +.. code:: python + + from automata.code_handling.py.reader import PyReader + + py_reader = PyReader() + module_dotpath = "package.module" + object_path = "ClassName.method_name" + + source_code = py_reader.get_source_code(module_dotpath, object_path) + print(source_code) + +Limitations +----------- + +The ``PyReader`` fetches python source code and docstrings based on the +provided module, class, function, or method paths. It may encounter +issues accurately fetching source code if the provided paths do not +directly correspond to valid python modules, classes, functions, or +methods. + +Also, the quality of fetched results depends on the actual source code +in question. As such, if the source code is not well-formatted or lacks +standard python constructs (e.g., no docstrings, poorly structured +classes or methods), the ``PyReader`` may not provide optimal results. + +One additional limitation is its dependence on external packages such as +‘redbaron’ and ‘typing’. The performance of this class is tied to the +performance of these external dependencies. + +Follow-up Questions: +-------------------- + +- How can this class handle exceptions that occur during source code + fetching? +- What strategies can be put in place to mitigate issues related to + poorly constructed source code? +- How does this class interact with other components in the Automata + codebase? +- What’s the use case for removing docstrings from code? +- Are there constraints linked to the types and formats of modules, + classes, and methods that ``PyReader`` can handle? diff --git a/docs/code_handling/py/py_writer.rst b/docs/code_handling/py/py_writer.rst new file mode 100644 index 00000000..656e2eee --- /dev/null +++ b/docs/code_handling/py/py_writer.rst @@ -0,0 +1,66 @@ +PyWriter +======== + +The ``PyWriter`` class is a utility designed for the task of writing +Python code along with its Abstract Syntax Tree (AST) nodes. Namely, +``PyWriter`` provides the foundational structure and tools for creating, +deleting, and updating Python modules. + +This class allows for the modification of code within modules, such as +the insertion of new code, deletion of code segments, and updates to +existing modules. Several functionalities of ``PyWriter`` include +creating a new module from source code and writing updates to disk +output when called upon. + +``PyWriter`` is typically initialized with a ``PyReader`` object to +assist in reading and writing Python source code. + +Related Symbols +--------------- + +- ``PyReader`` +- ``PyModuleLoader`` +- ``PyWriterToolkitBuilder`` + +Example +------- + +The following is an example illustrating the usage of ``PyWriter``. + +.. code:: python + + from automata.code_handling.py.reader import PyReader + from automata.code_handling.py.writer import PyWriter + + # Initialize a PyReader and PyWriter instances + py_reader = PyReader() + py_writer = PyWriter(py_reader) + + # Create a new module + code = 'print("Hello World!")' + module_name = 'sample_module' + py_writer.create_new_module(module_name, code, do_write=True) + + # Update existing module + updated_code = 'print("Hello again, World!")' + py_writer.update_existing_module(module_name, updated_code) + +In the example above, a ``PyWriter`` instance is initialized and then +used to create and update a Python module. + +Limitations +----------- + +``PyWriter`` depends on the ``PyReader`` instance for reading Python +code. Consequently, the performance and functioning of ``PyWriter`` are +tied to the ``PyReader`` object it has been initialized with. +Additionally, errors in the Python source code or lack of write +permissions could pose potential limitations while trying to write new +modules or update existing ones. + +Follow-up Questions +------------------- + +- How are Syntax Errors handled while creating or updating modules? +- Can ``PyWriter`` support writing and updating of Individual methods + or classes in a module? diff --git a/docs/code_handling/py/writer/class_or_function_not_found.rst b/docs/code_handling/py/writer/class_or_function_not_found.rst new file mode 100644 index 00000000..98b5fa06 --- /dev/null +++ b/docs/code_handling/py/writer/class_or_function_not_found.rst @@ -0,0 +1,72 @@ +PyWriter +======== + +``PyWriter`` is a utility class that facilitates the writing of Python +code along AST (Abstract Syntax Tree) nodes. It offers various +functionalities such as creating new Python modules, updating existing +modules, and deleting from existing modules, among others. It leverages +a ``PyReader`` instance, which fetches Python code, to initialize and +carry out its operations. + +In addition to the primary ``PyWriter`` class, this document makes +reference to additional closely related symbols such as ``PyReader``, +``PyWriterToolkitBuilder``, ``PyWriter.ClassOrFunctionNotFound``, and so +on. + +Related Symbols +--------------- + +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder`` +- ``automata.code_handling.py.writer.PyWriter.ClassOrFunctionNotFound`` +- ``automata.tests.unit.test_py_writer.py_writer`` +- ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder`` +- ``automata.tests.unit.test_py_writer_tool.test_init`` +- ``automata.tests.unit.test_py_reader.getter`` +- ``automata.tests.unit.test_py_writer.test_create_update_write_module`` + +Example +------- + +An indicative Python session using ``PyWriter`` would look something +like the following: + +.. code:: python + + from automata.code_handling.py.reader import PyReader + from automata.code_handling.py.writer import PyWriter + + py_reader = PyReader() # Creating an instance of PyReader + py_writer = PyWriter(py_reader) # Initializing PyWriter with a PyReader instance + + source_code = """ + def greet(name): + return f"Hello, {name}!" + """ # Python code that we aim to insert into a module + + module_dotpath = "module.name" # The module into which we want to insert Python code + + # The following line will insert 'source_code' into the python file specified by 'module_dotpath' + py_writer.create_new_module(module_dotpath, source_code, do_write=True) + +Note: If the Python file specified by ``module_dotpath`` does not exist, +it will be created in the process. + +Limitations +----------- + +The primary constraint of ``PyWriter`` is that it relies on the +``PyReader`` instance passed to it during initialization for fetching +Python code. If the ``PyReader`` instance is associated with incorrect +or inaccessible Python modules, ``PyWriter`` might fail. + +Follow-up Questions: +-------------------- + +1. How does ``PyWriter`` handle class hierarchy and nested classes when + writing to AST nodes? +2. What are the limitations of using ``PyWriter`` on different types of + Python modules, such as those containing metaclasses, dynamically + generated code, etc.? +3. Can the ``PyWriter`` class handle conflict resolution in case of + module name clashes? diff --git a/docs/code_handling/py/writer/index.rst b/docs/code_handling/py/writer/index.rst new file mode 100644 index 00000000..e37714f6 --- /dev/null +++ b/docs/code_handling/py/writer/index.rst @@ -0,0 +1,25 @@ +writer +====== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + class_or_function_not_found + invalid_arguments + module_not_found + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/code_handling/py/writer/invalid_arguments.rst b/docs/code_handling/py/writer/invalid_arguments.rst new file mode 100644 index 00000000..67880c8d --- /dev/null +++ b/docs/code_handling/py/writer/invalid_arguments.rst @@ -0,0 +1,68 @@ +PyWriter +======== + +``PyWriter`` is a utility class in Automata used for writing Python code +along Abstract Syntax Tree (AST) nodes. PyWriter is initialized with an +instance of ``PyReader`` which fetches the Python code. Once +initialized, there are methods available to create, update, and delete +from Python modules. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_py_writer.py_writer`` +- ``automata.code_handling.py.writer.PyWriter`` +- ``automata.tests.unit.test_py_writer_tool.test_init`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_py_writer`` +- ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder.__init__`` +- ``automata.tests.unit.test_py_reader.getter`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder`` +- ``automata.tests.unit.test_py_writer.test_create_update_write_module`` +- ``automata.code_handling.py.reader.PyReader`` + +Usage Example +------------- + +Below is an example illustrating the creation of a new Python module +using ``PyWriter``. + +.. code:: python + + from automata.code_handling.py.writer import PyWriter + from automata.code_handling.py.reader import PyReader + + # Initializing PyWriter + py_reader = PyReader() + py_writer = PyWriter(py_reader) + + # Creating a new Python module + py_writer.create_new_module( + module_dotpath="sample_module", + source_code="print('Hello, world!')", + do_write=True + ) + +In this example, ``create_new_module`` accepts a module path along with +source code as strings, and a boolean indicating whether to write these +changes to disk. The module’s path is given through dot notation (i.e., +‘sample_module’). + +Limitations +----------- + +While the ``PyWriter`` class provides a useful way to modify Python code +programmatically, it has certain limitations. For instance, improper +manipulation of Python code may lead to syntax errors or unexpected +behaviour in the code. Additionally, the automatic writing of changes to +disk may, in some cases, lead to data loss if not used carefully. + +Follow-up Questions: +-------------------- + +- How does ``PyWriter`` handle potential errors and exceptions when + writing Python code? +- How does ``PyWriter`` interact with other Automata components and + dependencies? +- What are the best practices to ensure safe and effective usage of + ``PyWriter``? diff --git a/docs/code_handling/py/writer/module_not_found.rst b/docs/code_handling/py/writer/module_not_found.rst new file mode 100644 index 00000000..7ba838f2 --- /dev/null +++ b/docs/code_handling/py/writer/module_not_found.rst @@ -0,0 +1,87 @@ +PyWriter +======== + +Overview +-------- + +``PyWriter`` is a utility class that aids in writing Python code along +with abstract syntax tree (AST) nodes. It is designed to write or modify +Python code using directives from code objects. It provides capabilities +to create and update Python modules, among other functions. To use +``PyWriter``, supply an instance of ``PyReader`` to ``PyWriter`` when it +is instantiated. + +‘PyWriter.ModuleNotFound’ is an exception raised when a module is not +found in the module dictionary. + +Related Symbols +--------------- + +- ``automata.code_handling.py.writer.PyWriter`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.tests.unit.test_py_writer.py_writer`` +- ``automata.tests.unit.test_py_writer_tool.test_init`` +- ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_py_writer`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder`` +- ``automata.tests.unit.test_py_writer.test_create_update_write_module`` + +Example +------- + +This documentation provides an excerpt from a test of ``PyWriter`` +functionality. The purpose is to show how to instantiate and use the +``PyWriter``: + +.. code:: python + + # MockCodeGenerator is a hypothetical class and its instance generates the source code for testing PyWriter + from automata.tests.unit.test_py_writer import PyWriter, MockCodeGenerator + from automata.code_handling.py.reader import PyReader + import os + + py_writer = PyWriter(PyReader()) + mock_generator = MockCodeGenerator( + has_class=True, has_class_docstring=True, has_function=True, has_function_docstring=True + ) + source_code = mock_generator.generate_code() + py_writer.create_new_module("sample_modules.sample_module_write", source_code, do_write=True) + + assert os.path.exists("sample_module_write.py") + + mock_generator_2 = MockCodeGenerator( + has_class=True, has_class_docstring=True, has_function=True, has_function_docstring=True + ) + source_code_2 = mock_generator_2.generate_code() + + py_writer.update_existing_module( + source_code=source_code_2, + module_dotpath="sample_modules.sample_module_write", + do_write=True, + ) + +To comprehend this example fully, note that an object called +``MockCodeGenerator()`` is utilized. This is likely a mock unit used in +testing to replace a more complex code generator class. If you’re +attempting this in a non-testing scenario, replace this with the +appropriate mechanism to generate or retrieve your source code. + +Limitations +----------- + +Source code must in be in the correct format as expected by the +``PyWriter`` when creating or updating a Python code file. Any errors in +the source code will likely result in faulty Python files. Another +limitation is that this tool assumes Python AST node objects—it may not +be compatible with customized AST node objects or AST node objects +generated by code parsers other than Python’s built-in. + +Follow-up Questions: +-------------------- + +- How can PyWriter handle additional exception cases for not found + entities other than modules? +- Are there any constraints when using PyWriter in terms of Python + versions compatibility or code structure? +- What happens if PyWriter tries to edit an existing Python file which + is in read-only mode? diff --git a/docs/config/agent_config.rst b/docs/config/agent_config.rst index b0e51780..a2b7ba6e 100644 --- a/docs/config/agent_config.rst +++ b/docs/config/agent_config.rst @@ -48,9 +48,9 @@ Related Symbols - ``automata.config.base.AgentConfigName`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_default_config`` -- ``automata.core.agent.agent.AgentInstance.Config`` +- ``automata.agent.agent.AgentInstance.Config`` - ``automata.tests.unit.test_task_environment.TestURL`` -- ``automata.core.agent.instances.OpenAIAutomataAgentInstance.Config`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance.Config`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` Example Usage diff --git a/docs/config/agent_config_builder.rst b/docs/config/agent_config_builder.rst index 64f2118e..086e189f 100644 --- a/docs/config/agent_config_builder.rst +++ b/docs/config/agent_config_builder.rst @@ -29,11 +29,11 @@ Related Symbols - ``automata.config.openai_agent.OpenAIAutomataAgentConfigBuilder`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_provided_parameters_override_defaults`` -- ``automata.core.agent.agent.AgentInstance.Config`` +- ``automata.agent.agent.AgentInstance.Config`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_accepts_all_fields`` -- ``automata.core.agent.instances.OpenAIAutomataAgentInstance.Config`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance.Config`` - ``automata.config.base.AgentConfigName`` -- ``automata.core.tools.base.Tool`` +- ``automata.tools.base.Tool`` Usage Example ------------- diff --git a/docs/config/agent_config_name.rst b/docs/config/agent_config_name.rst index 65406a2e..4dfec1f8 100644 --- a/docs/config/agent_config_name.rst +++ b/docs/config/agent_config_name.rst @@ -50,14 +50,14 @@ directory. Related Symbols --------------- -- ``automata.core.agent.agent.AgentInstance.Config``: A class for +- ``automata.agent.agent.AgentInstance.Config``: A class for configuring the agent instance arbitrary types allowed. - ``automata.tests.unit.test_automata_agent_builder.test_config_loading_different_versions``: A test function that iterates over all ``AgentConfigName``, skips the DEFAULT, loads the config and checks its type. - ``automata.tests.conftest.automata_agent_config_builder``: A pytest fixture to construct ``OpenAIAutomataAgentConfig``. -- ``automata.core.agent.instances.OpenAIAutomataAgentInstance.Config``: +- ``automata.agent.instances.OpenAIAutomataAgentInstance.Config``: Class for configuring the OpenAI automata agent instance. - ``automata.config.base.AgentConfig.Config``: Class for configuring the Agent, where arbitrary types are allowed and defines a provider. diff --git a/docs/config/base/config.rst b/docs/config/base/config.rst index 860d1f58..a021e9ee 100644 --- a/docs/config/base/config.rst +++ b/docs/config/base/config.rst @@ -26,9 +26,8 @@ automata environment. The attributes set in ``AgentConfig`` include: Related Symbols --------------- -- ``automata.core.agent.agent.AgentInstance.Config``: Specifies that as - part of an agent instance, the ``AgentConfig`` allows arbitrary - types. +- ``automata.agent.agent.AgentInstance.Config``: Specifies that as part + of an agent instance, the ``AgentConfig`` allows arbitrary types. - ``automata.tests.unit.test_automata_agent_builder.test_builder_default_config``: Demonstrates how to build a default configuration. - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance``: @@ -39,8 +38,8 @@ Related Symbols - ``automata.config.openai_agent.OpenAIAutomataAgentConfig``: An expanded class of ``AgentConfig`` that also includes instructional templates and formatters. -- ``automata.core.tools.base.Tool.Config``: Defines an additional class - for tool-specific Configuration that also allows arbitrary types but +- ``automata.tools.base.Tool.Config``: Defines an additional class for + tool-specific Configuration that also allows arbitrary types but forbids extra parameters. Example diff --git a/docs/config/base/index.rst b/docs/config/base/index.rst index ccbd6738..26413653 100644 --- a/docs/config/base/index.rst +++ b/docs/config/base/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/config/config_category.rst b/docs/config/config_category.rst index d033e7b0..f6c09b93 100644 --- a/docs/config/config_category.rst +++ b/docs/config/config_category.rst @@ -17,11 +17,11 @@ Related Symbols - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` - ``automata.tests.unit.sample_modules.sample.EmptyClass`` -- ``automata.core.agent.agent.AgentInstance.Config`` +- ``automata.agent.agent.AgentInstance.Config`` - ``automata.tests.unit.test_task_environment.TestURL`` -- ``automata.core.agent.instances.OpenAIAutomataAgentInstance.Config`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance.Config`` - ``automata.tests.unit.test_py_writer.MockCodeGenerator`` -- ``automata.core.tools.base.Tool.Config`` +- ``automata.tools.base.Tool.Config`` - ``automata.config.base.AgentConfig.Config`` - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU.__init__`` diff --git a/docs/config/index.rst b/docs/config/index.rst index 4ab4d5ad..20fa6dfd 100644 --- a/docs/config/index.rst +++ b/docs/config/index.rst @@ -18,6 +18,8 @@ how to :ref:`installation` the project. + + .. AUTO-GENERATED CONTENT START .. diff --git a/docs/config/llm_provider.rst b/docs/config/llm_provider.rst index 7612b375..ee01ad83 100644 --- a/docs/config/llm_provider.rst +++ b/docs/config/llm_provider.rst @@ -19,8 +19,8 @@ Related Symbols sample function used in unit testing. - ``automata.config.base.AgentConfig.get_llm_provider``: Method to get the LLM (Language Learning Model) Provider for the Automata agent. -- ``automata.core.agent.agent.Agent.set_database_provider``: Method to - set the database provider, where potential LLM conversations may be +- ``automata.agent.agent.Agent.set_database_provider``: Method to set + the database provider, where potential LLM conversations may be stored. - ``automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder``: A test fixture that builds and returns a context oracle toolkit. @@ -28,9 +28,9 @@ Related Symbols Method to get the LLM Provider specifically for an OpenAI agent. - ``automata.tests.unit.test_py_reader.getter``: A test fixture that creates and returns an instance of ``PyReader``. -- ``automata.core.llm.foundation.LLMConversationDatabaseProvider``: - Abstract base class for different types of database providers - specifically for LLM conversation. +- ``automata.llm.foundation.LLMConversationDatabaseProvider``: Abstract + base class for different types of database providers specifically for + LLM conversation. Usage Example ------------- diff --git a/docs/config/open_ai_automata_agent_config.rst b/docs/config/open_ai_automata_agent_config.rst index 21411bc2..6a814d06 100644 --- a/docs/config/open_ai_automata_agent_config.rst +++ b/docs/config/open_ai_automata_agent_config.rst @@ -37,9 +37,9 @@ Related Symbols - ``automata.tests.conftest.automata_agent_config_builder``: This is a fixture that provides a builder for the OpenAIAutomataAgentConfig class. -- ``automata.core.agent.providers.OpenAIAutomataAgent``: This class - utilizes the OpenAIAutomataAgentConfig for operational settings - during its instantiation and behavior. +- ``automata.agent.providers.OpenAIAutomataAgent``: This class utilizes + the OpenAIAutomataAgentConfig for operational settings during its + instantiation and behavior. - ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init``: This method tests the initialization of the AutomataAgent with the corresponding configuration. diff --git a/docs/config/open_ai_automata_agent_config_builder.rst b/docs/config/open_ai_automata_agent_config_builder.rst index 5e223d3d..7864fb34 100644 --- a/docs/config/open_ai_automata_agent_config_builder.rst +++ b/docs/config/open_ai_automata_agent_config_builder.rst @@ -35,9 +35,9 @@ Related Symbols fixture that sets up a mocked ``OpenAIAutomataAgentConfigBuilder``. - ``automata.config.openai_agent.OpenAIAutomataAgentConfig``: Holds the configuration for the Automata OpenAI Agent. -- ``automata.core.agent.providers.OpenAIAutomataAgent``: An autonomous - agent designed to execute instructions and report the results back to - the main system with interactions with OpenAI API. +- ``automata.agent.providers.OpenAIAutomataAgent``: An autonomous agent + designed to execute instructions and report the results back to the + main system with interactions with OpenAI API. Example ------- diff --git a/docs/config/openai_agent/config.rst b/docs/config/openai_agent/config.rst index 5be58517..e41f596b 100644 --- a/docs/config/openai_agent/config.rst +++ b/docs/config/openai_agent/config.rst @@ -26,7 +26,7 @@ Related Symbols - ``automata.config.openai_agent.OpenAIAutomataAgentConfig`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.providers.OpenAIAutomataAgent`` - ``automata.config.openai_agent.OpenAIAutomataAgentConfigBuilder`` - ``automata.tests.unit.test_automata_agent_builder.test_config_loading_different_versions`` diff --git a/docs/config/openai_agent/index.rst b/docs/config/openai_agent/index.rst index 7e3e4bbe..cf75674d 100644 --- a/docs/config/openai_agent/index.rst +++ b/docs/config/openai_agent/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/config/openai_agent/template_formatter.rst b/docs/config/openai_agent/template_formatter.rst index 4f45261e..68a730f5 100644 --- a/docs/config/openai_agent/template_formatter.rst +++ b/docs/config/openai_agent/template_formatter.rst @@ -49,7 +49,7 @@ The following example demonstrates how to create an instance of from automata.config.openai_agent import OpenAIAutomataAgentConfig from config.config_enums import AgentConfigName - from automata.core.experimental.search.rank import SymbolRank + from automata.experimental.search.rank import SymbolRank config = OpenAIAutomataAgentConfig.load(AgentConfigName.AUTOMATA_MAIN) symbol_rank = SymbolRank() diff --git a/docs/context_providers/index.rst b/docs/context_providers/index.rst new file mode 100644 index 00000000..e3066eb5 --- /dev/null +++ b/docs/context_providers/index.rst @@ -0,0 +1,24 @@ +context_providers +================= + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + symbol_provider_registry + symbol_provider_synchronization_context + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/context_providers/symbol_provider_registry.rst b/docs/context_providers/symbol_provider_registry.rst new file mode 100644 index 00000000..c4761c83 --- /dev/null +++ b/docs/context_providers/symbol_provider_registry.rst @@ -0,0 +1,73 @@ +SymbolProviderRegistry +====================== + +Overview +-------- + +``SymbolProviderRegistry`` is a central registry management class which +keeps track of the multiple symbol providers in the system. The primary +role of the ``SymbolProviderRegistry`` is to synchronize the symbols +supported by several symbol providers and maintain them in a sorted +order. It ensures that only the common symbols across the system are +taken into account by the application. + +This class operates primarily on singleton methods to maintain and +provide a single central registry. + +Related Symbols +--------------- + +- ``automata.symbol.base.Symbol`` +- ``automata.symbol.base.ISymbolProvider`` +- ``automata.tests.unit.test_symbol_graph.test_get_all_symbols`` +- ``automata.tests.unit.test_symbol_graph.test_build_real_graph`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext.register_provider`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext.synchronize`` + +Usage Example +------------- + +.. code:: python + + from automata.symbol.base import ISymbolProvider, Symbol + from automata.context_providers.symbol_synchronization import SymbolProviderRegistry + + # Define a custom symbol provider + class CustomSymbolProvider(ISymbolProvider): + ... + + custom_provider = CustomSymbolProvider() + + # Register your custom provider + SymbolProviderRegistry.register_provider(custom_provider) + + # Synchronize the symbols across all providers + SymbolProviderRegistry.synchronize() + + # Get the sorted list of supported symbols + symbols = SymbolProviderRegistry.get_sorted_supported_symbols() + + # Your code with the symbol + ... + +Limitations +----------- + +``SymbolProviderRegistry`` relies on the symbol providers in the system +implementing the ``ISymbolProvider`` interface correctly. If a symbol +provider provides incorrect or incomplete information about supported +symbols, it may introduce errors in the sorted symbols list. +Additionally, the registry assumes that all symbol providers will be +registered before any get or synchronize operation is performed. If a +new symbol provider is added after synchronization, it will not be +considered until the next synchronization. + +Follow-up Questions +------------------- + +- How does adding a new symbol provider after synchronization affect + the result? Is there a watch mechanism or notification setup in + symbol providers when new symbols get added? +- What precautions or considerations should be taken while implementing + a custom symbol provider to ensure compatibility with + ``SymbolProviderRegistry``? diff --git a/docs/context_providers/symbol_provider_synchronization_context.rst b/docs/context_providers/symbol_provider_synchronization_context.rst new file mode 100644 index 00000000..06f9a6fc --- /dev/null +++ b/docs/context_providers/symbol_provider_synchronization_context.rst @@ -0,0 +1,86 @@ +SymbolProviderSynchronizationContext +==================================== + +``SymbolProviderSynchronizationContext`` acts as a manager class for +handling the operations pertaining to an instance of +``ISymbolProvider``. It ensures that all the symbols from a provider are +correctly synchronized for processes that require it. The class +encapsulates the synchronization process, preventing unsafe operations +in a multi-threading environment. + +Overview +-------- + +The ``SymbolProviderSynchronizationContext`` class is used to manage and +coordinate the synchronization of symbols provided by an instance (or +instances) of ``ISymbolProvider``. Specifically, it allows for the +registration of a provider and guarantees successful synchronization +through its ``__exit__`` method. It implicitly tracks whether +synchronization has been attempted with the ``_was_synchronized`` +attribute. + +Related Symbols +--------------- + +- ``automata.symbol.base.ISymbolProvider`` +- ``automata.tests.unit.test_symbol_graph.test_get_all_symbols`` +- ``automata.tests.unit.test_symbol_graph.test_build_real_graph`` +- ``automata.tests.unit.test_symbol_graph.test_build_real_graph_and_subgraph`` +- ``automata.tests.unit.test_synchronizer.test_build_graph_and_handler_and_synchronize`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderRegistry`` + +Example +------- + +The following examples illustrate the basic usage of +``SymbolProviderSynchronizationContext`` in different scenarios. + +Example 1: Synchronizing a SymbolProvider + +.. code:: python + + from automata.context_providers.symbol_synchronization import SymbolProviderSynchronizationContext + from automata.symbol.base import ISymbolProvider + + provider = ISymbolProvider() # an instance of ISymbolProvider + + with SymbolProviderSynchronizationContext() as synchronization_context: + synchronization_context.register_provider(provider) + synchronization_context.synchronize() + +Example 2: Using a SynchronizationContext in a unit test + +.. code:: python + + def test_get_all_symbols(symbol_graph_static_test): + with SymbolProviderSynchronizationContext() as synchronization_context: + synchronization_context.register_provider(symbol_graph_static_test) + synchronization_context.synchronize() + + graph_symbols = symbol_graph_static_test.get_sorted_supported_symbols() + assert isinstance(graph_symbols, list) + assert all(isinstance(s, Symbol) for s in graph_symbols) + +Limitations +----------- + +The primary limitation is in the ``__exit__`` method, where a +RuntimeError is thrown if the symbols have not been synchronized. Hence, +it’s important to ensure that all providers are registered and +synchronized before the context is exited. + +Follow-up Questions: +-------------------- + +- Under what precise condition might the ``__exit__`` method throw a + RuntimeError? +- What is the expected behavior of the + ``SymbolProviderSynchronizationContext`` in a multi-threading + environment? +- What happens when multiple providers are registered within the same + ``SymbolProviderSynchronizationContext``? + +Note: The ``automata.tests.unit`` classes mentioned here contain mock +objects. Actual use of ``SymbolProviderSynchronizationContext`` may +involve real instances of the appropriate classes rather than these mock +objects. diff --git a/docs/core/agent/agent.rst b/docs/core/agent/agent.rst index 4f9ae158..581117ff 100644 --- a/docs/core/agent/agent.rst +++ b/docs/core/agent/agent.rst @@ -19,7 +19,7 @@ Import Statement .. code:: python - from automata.core.agent.agent import Agent + from automata.agent.agent import Agent Methods ------- @@ -61,19 +61,19 @@ Related Symbols - ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` - ``automata.tests.unit.test_automata_agent.test_build_initial_messages`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.providers.OpenAIAutomataAgent`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` -- ``automata.core.agent.error.AgentResultError`` +- ``automata.agent.error.AgentResultError`` - ``automata.tests.conftest.task`` - ``automata.tests.unit.sample_modules.sample2.PythonAgentToolkit.python_agent_python_task`` -- ``automata.core.agent.error.AgentGeneralError`` +- ``automata.agent.error.AgentGeneralError`` - ``automata.tests.conftest.automata_agent_config_builder`` -- ``automata.core.agent.error.AgentDatabaseError`` +- ``automata.agent.error.AgentDatabaseError`` Dependencies ------------ -- ``automata.core.llm.foundation.LLMConversationDatabaseProvider`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider`` Limitations ----------- diff --git a/docs/core/agent/agent/config.rst b/docs/core/agent/agent/config.rst index 02286d04..4498aafd 100644 --- a/docs/core/agent/agent/config.rst +++ b/docs/core/agent/agent/config.rst @@ -16,11 +16,11 @@ run multiple times without having to reinitialize the agent each time. Related Symbols --------------- -- ``automata.core.agent.agent.Agent`` -- ``automata.core.agent.agent.AgentInstance.Config`` -- ``automata.core.agent.agent.AgentInstance.create`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` -- ``automata.core.agent.instances.OpenAIAutomataAgentInstance`` +- ``automata.agent.agent.Agent`` +- ``automata.agent.agent.AgentInstance.Config`` +- ``automata.agent.agent.AgentInstance.create`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` Example @@ -33,8 +33,8 @@ from ``AgentInstance``. Here is how you can create an instance of .. code:: python - from automata.core.agent.instances import OpenAIAutomataAgentInstance - from automata.core.agent.config_enums import AgentConfigName + from automata.agent.instances import OpenAIAutomataAgentInstance + from automata.agent.config_enums import AgentConfigName config_name = AgentConfigName.TEST description = "This is a test instance" diff --git a/docs/core/agent/agent/index.rst b/docs/core/agent/agent/index.rst index ea56f0ee..e337790a 100644 --- a/docs/core/agent/agent/index.rst +++ b/docs/core/agent/agent/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/agent/agent_database_error.rst b/docs/core/agent/agent_database_error.rst index 670fb38d..45235708 100644 --- a/docs/core/agent/agent_database_error.rst +++ b/docs/core/agent/agent_database_error.rst @@ -20,12 +20,12 @@ entities including but not limited to ``AutomataAgentTaskDatabase``, Related Symbols --------------- -- ``automata.core.agent.providers.OpenAIAutomataAgent.set_database_provider`` -- ``automata.core.tasks.agent_database.AutomataTaskRegistry.__init__`` -- ``automata.core.tasks.agent_database.AutomataAgentTaskDatabase`` +- ``automata.agent.providers.OpenAIAutomataAgent.set_database_provider`` +- ``automata.tasks.agent_database.AutomataTaskRegistry.__init__`` +- ``automata.tasks.agent_database.AutomataAgentTaskDatabase`` - ``automata.tests.unit.test_conversation_database.db`` - ``automata.tests.unit.test_task_database.db`` -- ``automata.core.agent.error.AgentGeneralError`` +- ``automata.agent.error.AgentGeneralError`` Examples -------- @@ -38,7 +38,7 @@ utilized within an agent setup process. # Assuming we have a provider and an agent instance try: agent.set_database_provider(provider) - except automata.core.agent.error.AgentDatabaseError as e: + except automata.agent.error.AgentDatabaseError as e: print(f"Failed to set the database provider: {e}") Note: In the above example, it’s assumed that the ``provider`` and diff --git a/docs/core/agent/agent_general_error.rst b/docs/core/agent/agent_general_error.rst index 763b5210..3a1e8be3 100644 --- a/docs/core/agent/agent_general_error.rst +++ b/docs/core/agent/agent_general_error.rst @@ -5,7 +5,7 @@ Overview -------- ``AgentGeneralError`` is an exception class in the -``automata.core.agent.error`` module of the Automata library. This +``automata.agent.error`` module of the Automata library. This exception is raised when a general error arises while the automata agent is in operation. It’s a part of a series of custom exceptions designed to handle errors specific to the agent’s operations. @@ -18,20 +18,20 @@ Related Symbols A unit test function to validate the initialization of ``AutomataAgent``. -2. ``automata.core.agent.error.AgentTaskGeneralError`` +2. ``automata.agent.error.AgentTaskGeneralError`` An exception raised when a general error occurs during task execution. -3. ``automata.core.agent.error.AgentTaskGitError`` +3. ``automata.agent.error.AgentTaskGitError`` An exception raised when the task encounters a git error. -4. ``automata.core.agent.error.AgentResultError`` +4. ``automata.agent.error.AgentResultError`` An exception raised when the agent fails to produce a result. -5. ``automata.core.agent.error.AgentDatabaseError`` +5. ``automata.agent.error.AgentDatabaseError`` An exception raised when the agent fails to set the database provider. @@ -58,8 +58,8 @@ operation related to an ``AutomataAgent``, it can be used as follows: .. code:: python - from automata.core.agent.error import AgentGeneralError - from automata.core.agent.agent import AutomataAgent + from automata.agent.error import AgentGeneralError + from automata.agent.agent import AutomataAgent try: agent = AutomataAgent() @@ -81,6 +81,6 @@ Follow-up Questions: - What are the common scenarios where this error is usually thrown? - What is the hierarchy of custom exception classes in the - ``automata.core.agent.error`` module? Does ``AgentGeneralError`` + ``automata.agent.error`` module? Does ``AgentGeneralError`` serve as a parent class to any other exceptions? If not, is there a reason why not? diff --git a/docs/core/agent/agent_instance.rst b/docs/core/agent/agent_instance.rst index d5e7afd7..4048e205 100644 --- a/docs/core/agent/agent_instance.rst +++ b/docs/core/agent/agent_instance.rst @@ -25,10 +25,10 @@ Related Symbols --------------- - ``config.config_enums.AgentConfigName`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.providers.OpenAIAutomataAgent`` - ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` -- ``automata.core.agent.instances.OpenAIAutomataAgentInstance`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance`` Example ------- @@ -40,7 +40,7 @@ and implement the ``run`` method to create a custom agent instance. .. code:: python from automata.config.base import AgentConfigName - from automata.core.agent.agent import AgentInstance + from automata.agent.agent import AgentInstance class MyAgent(AgentInstance): def run(self, instructions: str) -> str: diff --git a/docs/core/agent/agent_max_iter_error.rst b/docs/core/agent/agent_max_iter_error.rst index b16ba996..0f7bc6b7 100644 --- a/docs/core/agent/agent_max_iter_error.rst +++ b/docs/core/agent/agent_max_iter_error.rst @@ -1,7 +1,7 @@ AgentMaxIterError ================= -``AgentMaxIterError`` is an exception class in automata.core.agent.error +``AgentMaxIterError`` is an exception class in automata.agent.error module that is raised when an agent exceeds the maximum number of iterations during its execution. @@ -17,9 +17,9 @@ expected results or isn’t reaching completion. Related Symbols --------------- -- ``automata.core.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.providers.OpenAIAutomataAgent`` - ``automata.config.base.AgentConfigBuilder.with_max_iterations`` -- ``automata.core.agent.error.AgentStopIteration`` +- ``automata.agent.error.AgentStopIteration`` Example ------- @@ -29,8 +29,8 @@ when running an agent. Here is an illustrative example: .. code:: python - from automata.core.agent.error import AgentMaxIterError - from automata.core.agent.providers import OpenAIAutomataAgent + from automata.agent.error import AgentMaxIterError + from automata.agent.providers import OpenAIAutomataAgent from automata.config.base import AgentConfigBuilder # Instantiate a config builder and set max_iterations diff --git a/docs/core/agent/agent_result_error.rst b/docs/core/agent/agent_result_error.rst index 6fec93fa..5d197c4f 100644 --- a/docs/core/agent/agent_result_error.rst +++ b/docs/core/agent/agent_result_error.rst @@ -5,7 +5,7 @@ Overview -------- ``AgentResultError`` is an exception class in the -``automata.core.agent.error`` module. This exception is raised when an +``automata.agent.error`` module. This exception is raised when an instance of an agent fails to produce a result during the execution process. It’s typically thrown if there’s an issue with the method call of an agent. @@ -15,13 +15,13 @@ Related Symbols - ``automata.tests.unit.test_automata_agent.test_run_with_no_completion`` - ``automata.tests.unit.test_automata_agent.mock_openai_response_with_completion_message`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.providers.OpenAIAutomataAgent`` - ``automata.tests.unit.test_automata_agent.test_iter_step_without_api_call`` -- ``automata.core.agent.error.AgentTaskStateError`` +- ``automata.agent.error.AgentTaskStateError`` - ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` -- ``automata.core.agent.agent.Agent`` +- ``automata.agent.agent.Agent`` - ``automata/tests/unit/test_automata_agent.test_build_initial_messages`` -- ``automata.core.agent.error.AgentTaskGeneralError`` +- ``automata.agent.error.AgentTaskGeneralError`` - ``automata.tests.conftest.task`` Example @@ -32,8 +32,8 @@ The following is an example demonstrating how to handle the .. code:: python - from automata.core.agent.providers import OpenAIAutomataAgent - from automata.core.agent.error import AgentResultError, AgentMaxIterError + from automata.agent.providers import OpenAIAutomataAgent + from automata.agent.error import AgentResultError, AgentMaxIterError try: agent = OpenAIAutomataAgent( diff --git a/docs/core/agent/agent_stop_iteration.rst b/docs/core/agent/agent_stop_iteration.rst index fc6fcb70..5187c8bd 100644 --- a/docs/core/agent/agent_stop_iteration.rst +++ b/docs/core/agent/agent_stop_iteration.rst @@ -1,4 +1,4 @@ -automata.core.agent.error.AgentStopIteration +automata.agent.error.AgentStopIteration ============================================ Overview @@ -25,20 +25,20 @@ Related Symbols behavior when manually feeding next(…) calls to the automata agent without an API call. -- ``automata.core.agent.error.AgentMaxIterError``: This is another +- ``automata.agent.error.AgentMaxIterError``: This is another exception class used when the agent exceeds the maximum number of allowed iterations. -- ``automata.core.agent.agent.Agent.__iter__``: The ``__iter__`` method +- ``automata.agent.agent.Agent.__iter__``: The ``__iter__`` method of the ``Agent`` class calls upon the ``AgentStopIteration`` when the agent stops iterating. -- ``automata.core.agent.providers.OpenAIAutomataAgent``: The +- ``automata.agent.providers.OpenAIAutomataAgent``: The ``OpenAIAutomataAgent``, designed to execute instructions and interact with various tools, uses the ``AgentStopIteration`` exception to handle situations where the agent ceases to iterate. -- ``automata.core.agent.providers.OpenAIAutomataAgent.__iter__``: The +- ``automata.agent.providers.OpenAIAutomataAgent.__iter__``: The ``__iter__`` method in the ``OpenAIAutomataAgent`` class handles the ``AgentStopIteration`` exception when the iteration process is stopped. @@ -55,8 +55,8 @@ represented without the actual underlying object: .. code:: python from unittest.mock import patch - from automata.core.agent.providers import OpenAIAutomataAgent - from automata.core.agent.error import AgentMaxIterError + from automata.agent.providers import OpenAIAutomataAgent + from automata.agent.error import AgentMaxIterError @patch("openai.ChatCompletion.create") def test_agent_stops_iteration(mock_openai_chatcompletion_create, automata_agent): diff --git a/docs/core/agent/agent_task_general_error.rst b/docs/core/agent/agent_task_general_error.rst index 95d0c3e9..ff2dd124 100644 --- a/docs/core/agent/agent_task_general_error.rst +++ b/docs/core/agent/agent_task_general_error.rst @@ -12,13 +12,13 @@ Related Symbols - ``automata.tests.unit.test_task_executor.test_execute_automata_task_fail`` - ``automata.tests.unit.test_task_environment.test_commit_task`` -- ``automata.core.agent.error.AgentGeneralError`` +- ``automata.agent.error.AgentGeneralError`` - ``automata.tests.unit.test_task.test_task_inital_state`` -- ``automata.core.agent.error.AgentTaskGitError`` +- ``automata.agent.error.AgentTaskGitError`` - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` -- ``automata.core.agent.error.AgentTaskInstructions`` +- ``automata.agent.error.AgentTaskInstructions`` - ``automata.tests.unit.test_task_environment.TestURL`` -- ``automata.core.agent.error.AgentTaskStateError`` +- ``automata.agent.error.AgentTaskStateError`` - ``automata.tests.unit.test_task_executor.TestExecuteBehavior`` Example @@ -30,7 +30,7 @@ exception could be used in a test case scenario. .. code:: python from unittest.mock import patch, MagicMock - from automata.core.agent.error import AgentTaskGeneralError + from automata.agent.error import AgentTaskGeneralError import pytest @patch("logging.config.dictConfig", return_value=None) diff --git a/docs/core/agent/agent_task_git_error.rst b/docs/core/agent/agent_task_git_error.rst index 4d5b5c57..c2b55a9c 100644 --- a/docs/core/agent/agent_task_git_error.rst +++ b/docs/core/agent/agent_task_git_error.rst @@ -9,13 +9,13 @@ Related Symbols - ``automata.tests.conftest.MockRepositoryClient`` - ``automata.tests.unit.test_task_environment.test_commit_task`` -- ``automata.core.github_management.client.GitHubClient`` +- ``automata.github_management.client.GitHubClient`` - ``automata.tests.conftest.environment`` -- ``automata.core.github_management.client.GitHubClient.clone_repository`` +- ``automata.github_management.client.GitHubClient.clone_repository`` - ``automata.tests.conftest.MockRepositoryClient.clone_repository`` -- ``automata.core.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` - ``automata.tests.conftest.MockRepositoryClient.checkout_branch`` -- ``automata.core.github_management.client.GitHubClient.__init__`` +- ``automata.github_management.client.GitHubClient.__init__`` - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` Using AgentTaskGitError diff --git a/docs/core/agent/agent_task_instructions.rst b/docs/core/agent/agent_task_instructions.rst index fc6936b4..f87a944a 100644 --- a/docs/core/agent/agent_task_instructions.rst +++ b/docs/core/agent/agent_task_instructions.rst @@ -21,13 +21,13 @@ Related Symbols - ``automata.tests.unit.test_task_database.task`` - ``automata.tests.conftest.task`` -- ``automata.core.tasks.tasks.AutomataTask`` +- ``automata.tasks.tasks.AutomataTask`` - ``automata.tests.unit.test_automata_agent.test_build_initial_messages`` -- ``automata.core.tasks.tasks.AutomataTask.__init__`` +- ``automata.tasks.tasks.AutomataTask.__init__`` - ``automata.tests.unit.test_task_executor.TestExecuteBehavior`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.providers.OpenAIAutomataAgent`` - ``automata.tests.unit.test_task_executor.TestExecuteBehavior.execute`` -- ``automata.core.agent.agent.AgentInstance.run`` +- ``automata.agent.agent.AgentInstance.run`` - ``automata.tests.unit.sample_modules.sample2.PythonAgentToolkit.python_agent_python_task`` Example @@ -39,7 +39,7 @@ missing or empty for an ``AutomataTask`` instance. .. code:: python - from automata.core.tasks.tasks import AutomataTask + from automata.tasks.tasks import AutomataTask try: task = AutomataTask("") # Empty instructions diff --git a/docs/core/agent/agent_task_state_error.rst b/docs/core/agent/agent_task_state_error.rst index f7c9170a..af4b5b31 100644 --- a/docs/core/agent/agent_task_state_error.rst +++ b/docs/core/agent/agent_task_state_error.rst @@ -5,7 +5,7 @@ Overview -------- ``AgentTaskStateError`` is an exception class in -``automata.core.agent.error`` module that is raised when the task is not +``automata.agent.error`` module that is raised when the task is not in the correct state for the operation. This class deals with erroneous cases where, for instance, an action is being performed on a task but its state is not correctly set for that particular action. @@ -13,18 +13,18 @@ its state is not correctly set for that particular action. Related Symbols --------------- -- ``automata.core.tasks.base.TaskStatus``: Refers to various statuses a +- ``automata.tasks.base.TaskStatus``: Refers to various statuses a task can have, like ``CREATED``, ``RETRYING``, ``FAILED``, ``SUCCESS``, etc. - ``automata.tests.unit.test_task.test_task_inital_state``: A unit test that asserts if the initial status of the task is ``CREATED``. - ``automata.tests.unit.test_task.test_status_setter``: A unit test to check if the task status can be set to ``RETRYING``. -- ``automata.core.agent.error.AgentTaskGitError``: An exception raised +- ``automata.agent.error.AgentTaskGitError``: An exception raised when the task encounters a git related error. -- ``automata.core.agent.error.AgentTaskGeneralError``: An exception +- ``automata.agent.error.AgentTaskGeneralError``: An exception raised when a general error occurs during task execution. -- ``automata.core.agent.error.AgentTaskInstructions``: An exception +- ``automata.agent.error.AgentTaskInstructions``: An exception raised when there is an error with the task instructions. Example @@ -35,8 +35,8 @@ The following is a simplified example demonstrating how .. code:: python - from automata.core.agent.error import AgentTaskStateError - from automata.core.tasks.base import TaskStatus, AutomataTask + from automata.agent.error import AgentTaskStateError + from automata.tasks.base import TaskStatus, AutomataTask # Creating a Mock Task task = AutomataTask() diff --git a/docs/core/agent/agent_toolkit_builder.rst b/docs/core/agent/agent_toolkit_builder.rst index 20ef9a90..3fe5e30c 100644 --- a/docs/core/agent/agent_toolkit_builder.rst +++ b/docs/core/agent/agent_toolkit_builder.rst @@ -51,7 +51,7 @@ inherits from ``AgentToolkitBuilder``. .. code:: python - from automata.core.tools.base import Tool + from automata.tools.base import Tool class PythonAgentToolkit: def __init__(self, python_agent: PythonAgent): diff --git a/docs/core/agent/agent_toolkit_names.rst b/docs/core/agent/agent_toolkit_names.rst index bed388fc..348f3499 100644 --- a/docs/core/agent/agent_toolkit_names.rst +++ b/docs/core/agent/agent_toolkit_names.rst @@ -2,7 +2,7 @@ AgentToolkitNames ================= ``AgentToolkitNames`` is an enumeration class that represents different -types of agent tools in the ``automata.core.agent.agent`` package. This +types of agent tools in the ``automata.agent.agent`` package. This class helps manage a collection of agent tools that can be used for distinct tasks. Each named enum member corresponds to a particular type of agent tool. The builders for these tools are located in the @@ -15,13 +15,13 @@ Related Symbols class for building tools to interact with a PythonAgent. - ``automata.tests.unit.test_automata_agent_builder.test_builder_accepts_all_fields``: A test function that demonstrates the use of the builder. -- ``automata.core.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder``: +- ``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder``: Builds tools for Open AI. -- ``automata.core.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``: +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``: Builds tools for Context Oracle. -- ``automata.core.tools.factory.AgentToolFactory``: A factory class for +- ``automata.tools.factory.AgentToolFactory``: A factory class for creating tools from a given agent tool name. -- ``automata.core.agent.agent.AgentToolkitBuilder``: an abstract class +- ``automata.agent.agent.AgentToolkitBuilder``: an abstract class for building tools. Example @@ -31,7 +31,7 @@ Below is a brief example of how you can use ``AgentToolkitNames``: .. code:: python - from automata.core.agent.agent import AgentToolkitNames + from automata.agent.agent import AgentToolkitNames # Get a specific toolkit name toolkit_name = AgentToolkitNames.PYTHON diff --git a/docs/core/agent/index.rst b/docs/core/agent/index.rst index ca685343..d6a046a2 100644 --- a/docs/core/agent/index.rst +++ b/docs/core/agent/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/agent/instances/config.rst b/docs/core/agent/instances/config.rst index e48fe67f..46110b95 100644 --- a/docs/core/agent/instances/config.rst +++ b/docs/core/agent/instances/config.rst @@ -19,7 +19,7 @@ efficiency and system performance. Related Symbols --------------- -- ``automata.core.agent.providers.OpenAIAutomataAgent``: The agent that +- ``automata.agent.providers.OpenAIAutomataAgent``: The agent that this class holds an instance of. - ``automata.config.openai_agent.OpenAIAutomataAgentConfig``: The configuration used by the agent. @@ -37,7 +37,7 @@ Here is an example of how to use the ``OpenAIAutomataAgentInstance``: from automata.config.openai_agent import OpenAIAutomataAgentConfig from automata.config.config_enums import AgentConfigName - from automata.core.agent.instances import OpenAIAutomataAgentInstance + from automata.agent.instances import OpenAIAutomataAgentInstance # load configuration config = OpenAIAutomataAgentConfig.load(AgentConfigName.TEST) diff --git a/docs/core/agent/instances/index.rst b/docs/core/agent/instances/index.rst index 4d49d033..aa429b50 100644 --- a/docs/core/agent/instances/index.rst +++ b/docs/core/agent/instances/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/agent/open_ai_agent_toolkit_builder.rst b/docs/core/agent/open_ai_agent_toolkit_builder.rst index a23339fb..68fd6ccf 100644 --- a/docs/core/agent/open_ai_agent_toolkit_builder.rst +++ b/docs/core/agent/open_ai_agent_toolkit_builder.rst @@ -12,10 +12,10 @@ Overview Some classes that have implemented the ``OpenAIAgentToolkitBuilder`` abstract class include -``automata.core.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``, -``automata.core.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder``, +``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``, +``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder``, and -``automata.core.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` +``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` among others. Every implementing class must define the ``build_for_open_ai`` method which returns a list of ``OpenAITool`` objects, and the ``can_handle`` method which checks if the class can @@ -24,18 +24,18 @@ handle a given tool manager. Related Symbols --------------- -- ``automata.core.llm.providers.openai.OpenAITool`` -- ``automata.core.agent.agent.AgentToolkitBuilder`` +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.agent.agent.AgentToolkitBuilder`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` -- ``automata.core.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` -- ``automata.core.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` +- ``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` Example ------- .. code:: python - from automata.core.tools.builders.context_oracle import ContextOracleOpenAIToolkitBuilder + from automata.tools.builders.context_oracle import ContextOracleOpenAIToolkitBuilder class MyOpenAIToolkitBuilder(ContextOracleOpenAIToolkitBuilder): TOOL_TYPE = "my-type" diff --git a/docs/core/agent/open_ai_automata_agent.rst b/docs/core/agent/open_ai_automata_agent.rst index ac472280..e0e682b1 100644 --- a/docs/core/agent/open_ai_automata_agent.rst +++ b/docs/core/agent/open_ai_automata_agent.rst @@ -32,7 +32,7 @@ execution of tasks. For example: .. code:: python - from automata.core.agent.providers import OpenAIAutomataAgent + from automata.agent.providers import OpenAIAutomataAgent from automata.config.openai_agent import OpenAIAutomataAgentConfig # Create OpenAIAutomataAgentConfig config = OpenAIAutomataAgentConfig() @@ -50,12 +50,12 @@ Related Symbols and Dependencies: - ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` - ``automata.config.openai_agent.OpenAIAutomataAgentConfig`` -- ``automata.core.agent.instances.OpenAIAutomataAgentInstance`` +- ``automata.agent.instances.OpenAIAutomataAgentInstance`` - ``automata.tests.conftest.automata_agent_config_builder`` - ``automata.config.openai_agent.OpenAIAutomataAgentConfigBuilder`` - ``automata.tests.unit.test_automata_agent.test_build_initial_messages`` -- ``automata.core.llm.providers.openai.OpenAITool`` -- ``automata.core.agent.error.AgentResultError`` +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.agent.error.AgentResultError`` Limitations ----------- diff --git a/docs/core/agent/open_ai_automata_agent_instance.rst b/docs/core/agent/open_ai_automata_agent_instance.rst index af66627c..6ae5a9d5 100644 --- a/docs/core/agent/open_ai_automata_agent_instance.rst +++ b/docs/core/agent/open_ai_automata_agent_instance.rst @@ -18,7 +18,7 @@ Related Symbols --------------- - ``automata.tests.unit.test_automata_agent_builder.test_builder_creates_proper_instance`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.providers.OpenAIAutomataAgent`` - ``automata.config.openai_agent.OpenAIAutomataAgentConfigBuilder`` Example @@ -30,7 +30,7 @@ instructions and returns the result. .. code:: python - from automata.core.agent.instances import OpenAIAutomataAgentInstance + from automata.agent.instances import OpenAIAutomataAgentInstance from automata.config.base import AgentConfigName config_name = AgentConfigName.AUTOMATA_MAIN diff --git a/docs/core/agent/unknown_tool_error.rst b/docs/core/agent/unknown_tool_error.rst index 003d5bac..f9a6a111 100644 --- a/docs/core/agent/unknown_tool_error.rst +++ b/docs/core/agent/unknown_tool_error.rst @@ -5,7 +5,7 @@ Overview -------- ``UnknownToolError`` is an exception class in the -``automata.core.agent.error`` module. This exception is raised when an +``automata.agent.error`` module. This exception is raised when an unknown tool type is provided to the framework. In broad terms, a tool in this context refers to a callable @@ -24,21 +24,21 @@ Related Symbols - ``automata.tests.unit.test_tool.test_tool_instantiation`` - ``automata.tests.unit.test_tool.TestTool`` - ``automata.tests.unit.test_tool.test_tool_run`` -- ``automata.core.tools.base.Tool`` +- ``automata.tools.base.Tool`` - ``automata.tests.unit.test_context_oracle_tool.test_init`` -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder.can_handle`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder.can_handle`` - ``automata.tests.unit.test_tool.test_tool`` -- ``automata.core.tools.factory.AgentToolFactory.create_tools_from_builder`` +- ``automata.tools.factory.AgentToolFactory.create_tools_from_builder`` - ``automata.tests.unit.test_context_oracle_tool.test_build`` -- ``automata.core.agent.agent.AgentToolkitBuilder.build`` +- ``automata.agent.agent.AgentToolkitBuilder.build`` Usage Example ------------- .. code:: python - from automata.core.tools.factory import AgentToolFactory - from automata.core.agent.error import UnknownToolError + from automata.tools.factory import AgentToolFactory + from automata.agent.error import UnknownToolError try: tool = AgentToolFactory.create_tools_from_builder("NonExistentTool") diff --git a/docs/core/base/database/index.rst b/docs/core/base/database/index.rst index 93e17066..1e07f92d 100644 --- a/docs/core/base/database/index.rst +++ b/docs/core/base/database/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/base/database/relational_database.rst b/docs/core/base/database/relational_database.rst index 847c9952..2edcb273 100644 --- a/docs/core/base/database/relational_database.rst +++ b/docs/core/base/database/relational_database.rst @@ -23,11 +23,11 @@ Related Symbols - ``automata.tests.unit.test_conversation_database.db`` - ``automata.core.base.database.relational.SQLDatabase`` - ``automata.tests.unit.test_task_database.test_database_lifecycle`` -- ``automata.core.llm.foundation.LLMConversationDatabaseProvider`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider`` - ``automata.tests.unit.test_conversation_database.test_get_last_interaction_id_when_no_interactions`` -- ``automata.core.tasks.agent_database.AutomataAgentTaskDatabase`` +- ``automata.tasks.agent_database.AutomataAgentTaskDatabase`` - ``automata.tests.unit.test_task_database.test_get_tasks_by_query`` -- ``automata.core.memory_store.agent_conversation_database.AgentConversationDatabase`` +- ``automata.memory_store.agent_conversation_database.AgentConversationDatabase`` - ``automata.tests.unit.test_task_database.test_contains`` Example diff --git a/docs/core/base/database/sql_database.rst b/docs/core/base/database/sql_database.rst index 05347b2d..59b02f57 100644 --- a/docs/core/base/database/sql_database.rst +++ b/docs/core/base/database/sql_database.rst @@ -30,9 +30,9 @@ Related Symbols - ``automata.tests.unit.test_task_database.db`` - ``automata.tests.unit.test_conversation_database.db`` -- ``automata.core.tasks.agent_database.AutomataAgentTaskDatabase`` +- ``automata.tasks.agent_database.AutomataAgentTaskDatabase`` - ``automata.core.base.database.relational.RelationalDatabase`` -- ``automata.core.memory_store.agent_conversation_database.AgentConversationDatabase`` +- ``automata.memory_store.agent_conversation_database.AgentConversationDatabase`` Example ------- diff --git a/docs/core/base/database/vector_database_provider.rst b/docs/core/base/database/vector_database_provider.rst index 2d6e47cc..7fbe55f4 100644 --- a/docs/core/base/database/vector_database_provider.rst +++ b/docs/core/base/database/vector_database_provider.rst @@ -13,9 +13,9 @@ need to be implemented in the concrete classes inheriting from the Related Symbols --------------- -- ``automata.core.symbol_embedding.base.JSONSymbolEmbeddingVectorDatabase`` +- ``automata.symbol_embedding.base.JSONSymbolEmbeddingVectorDatabase`` - ``automata.core.base.database.vector.JSONVectorDatabase`` -- ``automata.core.embedding.base.EmbeddingVectorProvider`` +- ``automata.embedding.base.EmbeddingVectorProvider`` Example ------- @@ -27,7 +27,7 @@ inheriting this class. One of the example concrete classes is .. code:: python - from automata.core.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase class ExampleVectorDatabase(JSONSymbolEmbeddingVectorDatabase): def __init__(self, file_path: str): diff --git a/docs/core/base/index.rst b/docs/core/base/index.rst index 27d1cb60..fc8d744f 100644 --- a/docs/core/base/index.rst +++ b/docs/core/base/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/base/patterns/index.rst b/docs/core/base/patterns/index.rst index 17149b7f..ab095bc0 100644 --- a/docs/core/base/patterns/index.rst +++ b/docs/core/base/patterns/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/base/patterns/observer.rst b/docs/core/base/patterns/observer.rst index 979c64bb..3d0bd4a1 100644 --- a/docs/core/base/patterns/observer.rst +++ b/docs/core/base/patterns/observer.rst @@ -18,13 +18,13 @@ Related Symbols - ``automata.tests.unit.test_task.test_callback`` - ``automata.tests.unit.sample_modules.sample.Person`` -- ``automata.core.llm.foundation.LLMConversation.register_observer`` +- ``automata.llm.foundation.LLMConversation.register_observer`` - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` - ``automata.tests.conftest.MockRepositoryClient`` -- ``automata.core.llm.foundation.LLMConversation.unregister_observer`` -- ``automata.core.llm.foundation.LLMConversation.notify_observers`` +- ``automata.llm.foundation.LLMConversation.unregister_observer`` +- ``automata.llm.foundation.LLMConversation.notify_observers`` - ``automata.tests.unit.test_py_reader.getter`` -- ``automata.core.llm.foundation.LLMConversationDatabaseProvider`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider`` Example ------- diff --git a/docs/core/base/patterns/singleton.rst b/docs/core/base/patterns/singleton.rst index fb539618..1e7a84a1 100644 --- a/docs/core/base/patterns/singleton.rst +++ b/docs/core/base/patterns/singleton.rst @@ -26,18 +26,18 @@ Related Symbols unit test sample module. - ``automata.tests.unit.sample_modules.sample.EmptyClass``, a unit test sample module with an empty class. -- ``automata.core.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext``, +- ``automata.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext``, a context provider for symbol synchronization. - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU.__init__``, initializer for the ``CsSWU`` class. - ``automata.tests.unit.sample_modules.sample.Person``, a sample class for unit testing. -- ``automata.core.symbol.base.ISymbolProvider.__init__``, initializer - for the ``ISymbolProvider`` Interface. +- ``automata.symbol.base.ISymbolProvider.__init__``, initializer for + the ``ISymbolProvider`` Interface. - ``automata.tests.unit.sample_modules.sample.OuterClass``, a sample outer class with an inner class for unit testing. -- ``automata.core.symbol.base.Symbol``, core class for creating, - managing, and manipulating symbols. +- ``automata.symbol.base.Symbol``, core class for creating, managing, + and manipulating symbols. - ``automata.tests.unit.sample_modules.sample.OuterClass.InnerClass``, a sample inner class located within an outer class for unit testing. diff --git a/docs/core/code_handling/index.rst b/docs/core/code_handling/index.rst index 8a515f20..da3d8104 100644 --- a/docs/core/code_handling/index.rst +++ b/docs/core/code_handling/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/code_handling/py/index.rst b/docs/core/code_handling/py/index.rst index 4f29887a..09cd4d0e 100644 --- a/docs/core/code_handling/py/index.rst +++ b/docs/core/code_handling/py/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/code_handling/py/py_doc_writer.rst b/docs/core/code_handling/py/py_doc_writer.rst index 5dd8d577..f2796e5c 100644 --- a/docs/core/code_handling/py/py_doc_writer.rst +++ b/docs/core/code_handling/py/py_doc_writer.rst @@ -45,8 +45,8 @@ Import Statements import pypandoc from typing import Dict, List, Optional, Union, cast from redbaron import ClassNode, DefNode, Node, NodeList, RedBaron - from automata.core.code_handling.py.reader import PyReader - from automata.core.navigation.directory import DirectoryManager + from automata.code_handling.py.reader import PyReader + from automata.navigation.directory import DirectoryManager Methods ------- @@ -78,10 +78,10 @@ Example Usage .. code:: python - from automata.core.code_handling.py.writer import PyDocWriter + from automata.code_handling.py.writer import PyDocWriter from typing import Dict, List - from automata.core.symbol_embedding.base import SymbolDocEmbedding - from automata.core.symbol.base import Symbol + from automata.symbol_embedding.base import SymbolDocEmbedding + from automata.symbol.base import Symbol symbol1 = Symbol.from_string(symbol_str='package1 ClassA# method1().') symbol2 = Symbol.from_string(symbol_str='package2 ClassB# method2().') diff --git a/docs/core/code_handling/py/py_reader.rst b/docs/core/code_handling/py/py_reader.rst index 72b949bb..1e673431 100644 --- a/docs/core/code_handling/py/py_reader.rst +++ b/docs/core/code_handling/py/py_reader.rst @@ -33,7 +33,7 @@ The following example demonstrates how to create an instance of .. code:: python - from automata.core.code_handling.py.reader import PyReader + from automata.code_handling.py.reader import PyReader py_reader = PyReader() module_dotpath = "package.module" diff --git a/docs/core/code_handling/py/py_writer.rst b/docs/core/code_handling/py/py_writer.rst index 8713b94b..656e2eee 100644 --- a/docs/core/code_handling/py/py_writer.rst +++ b/docs/core/code_handling/py/py_writer.rst @@ -29,8 +29,8 @@ The following is an example illustrating the usage of ``PyWriter``. .. code:: python - from automata.core.code_handling.py.reader import PyReader - from automata.core.code_handling.py.writer import PyWriter + from automata.code_handling.py.reader import PyReader + from automata.code_handling.py.writer import PyWriter # Initialize a PyReader and PyWriter instances py_reader = PyReader() diff --git a/docs/core/code_handling/py/writer/class_or_function_not_found.rst b/docs/core/code_handling/py/writer/class_or_function_not_found.rst index a9252e97..98b5fa06 100644 --- a/docs/core/code_handling/py/writer/class_or_function_not_found.rst +++ b/docs/core/code_handling/py/writer/class_or_function_not_found.rst @@ -16,9 +16,9 @@ on. Related Symbols --------------- -- ``automata.core.code_handling.py.reader.PyReader`` -- ``automata.core.tools.builders.py_writer.PyWriterToolkitBuilder`` -- ``automata.core.code_handling.py.writer.PyWriter.ClassOrFunctionNotFound`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder`` +- ``automata.code_handling.py.writer.PyWriter.ClassOrFunctionNotFound`` - ``automata.tests.unit.test_py_writer.py_writer`` - ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder`` - ``automata.tests.unit.test_py_writer_tool.test_init`` @@ -33,8 +33,8 @@ like the following: .. code:: python - from automata.core.code_handling.py.reader import PyReader - from automata.core.code_handling.py.writer import PyWriter + from automata.code_handling.py.reader import PyReader + from automata.code_handling.py.writer import PyWriter py_reader = PyReader() # Creating an instance of PyReader py_writer = PyWriter(py_reader) # Initializing PyWriter with a PyReader instance diff --git a/docs/core/code_handling/py/writer/index.rst b/docs/core/code_handling/py/writer/index.rst index 034e5cea..2cd50d65 100644 --- a/docs/core/code_handling/py/writer/index.rst +++ b/docs/core/code_handling/py/writer/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/code_handling/py/writer/invalid_arguments.rst b/docs/core/code_handling/py/writer/invalid_arguments.rst index 0468cd91..67880c8d 100644 --- a/docs/core/code_handling/py/writer/invalid_arguments.rst +++ b/docs/core/code_handling/py/writer/invalid_arguments.rst @@ -11,15 +11,15 @@ Related Symbols --------------- - ``automata.tests.unit.test_py_writer.py_writer`` -- ``automata.core.code_handling.py.writer.PyWriter`` +- ``automata.code_handling.py.writer.PyWriter`` - ``automata.tests.unit.test_py_writer_tool.test_init`` -- ``automata.core.singletons.dependency_factory.DependencyFactory.create_py_writer`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_py_writer`` - ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder`` -- ``automata.core.tools.builders.py_writer.PyWriterToolkitBuilder.__init__`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder.__init__`` - ``automata.tests.unit.test_py_reader.getter`` -- ``automata.core.tools.builders.py_writer.PyWriterToolkitBuilder`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder`` - ``automata.tests.unit.test_py_writer.test_create_update_write_module`` -- ``automata.core.code_handling.py.reader.PyReader`` +- ``automata.code_handling.py.reader.PyReader`` Usage Example ------------- @@ -29,8 +29,8 @@ using ``PyWriter``. .. code:: python - from automata.core.code_handling.py.writer import PyWriter - from automata.core.code_handling.py.reader import PyReader + from automata.code_handling.py.writer import PyWriter + from automata.code_handling.py.reader import PyReader # Initializing PyWriter py_reader = PyReader() diff --git a/docs/core/code_handling/py/writer/module_not_found.rst b/docs/core/code_handling/py/writer/module_not_found.rst index 29c0c0de..7ba838f2 100644 --- a/docs/core/code_handling/py/writer/module_not_found.rst +++ b/docs/core/code_handling/py/writer/module_not_found.rst @@ -17,13 +17,13 @@ found in the module dictionary. Related Symbols --------------- -- ``automata.core.code_handling.py.writer.PyWriter`` -- ``automata.core.code_handling.py.reader.PyReader`` +- ``automata.code_handling.py.writer.PyWriter`` +- ``automata.code_handling.py.reader.PyReader`` - ``automata.tests.unit.test_py_writer.py_writer`` - ``automata.tests.unit.test_py_writer_tool.test_init`` - ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder`` -- ``automata.core.singletons.dependency_factory.DependencyFactory.create_py_writer`` -- ``automata.core.tools.builders.py_writer.PyWriterToolkitBuilder`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_py_writer`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder`` - ``automata.tests.unit.test_py_writer.test_create_update_write_module`` Example @@ -37,7 +37,7 @@ functionality. The purpose is to show how to instantiate and use the # MockCodeGenerator is a hypothetical class and its instance generates the source code for testing PyWriter from automata.tests.unit.test_py_writer import PyWriter, MockCodeGenerator - from automata.core.code_handling.py.reader import PyReader + from automata.code_handling.py.reader import PyReader import os py_writer = PyWriter(PyReader()) diff --git a/docs/core/context_providers/index.rst b/docs/core/context_providers/index.rst index e7b9aeb2..d3d35536 100644 --- a/docs/core/context_providers/index.rst +++ b/docs/core/context_providers/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/context_providers/symbol_provider_registry.rst b/docs/core/context_providers/symbol_provider_registry.rst index c345e6bc..c4761c83 100644 --- a/docs/core/context_providers/symbol_provider_registry.rst +++ b/docs/core/context_providers/symbol_provider_registry.rst @@ -17,20 +17,20 @@ provide a single central registry. Related Symbols --------------- -- ``automata.core.symbol.base.Symbol`` -- ``automata.core.symbol.base.ISymbolProvider`` +- ``automata.symbol.base.Symbol`` +- ``automata.symbol.base.ISymbolProvider`` - ``automata.tests.unit.test_symbol_graph.test_get_all_symbols`` - ``automata.tests.unit.test_symbol_graph.test_build_real_graph`` -- ``automata.core.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext.register_provider`` -- ``automata.core.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext.synchronize`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext.register_provider`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext.synchronize`` Usage Example ------------- .. code:: python - from automata.core.symbol.base import ISymbolProvider, Symbol - from automata.core.context_providers.symbol_synchronization import SymbolProviderRegistry + from automata.symbol.base import ISymbolProvider, Symbol + from automata.context_providers.symbol_synchronization import SymbolProviderRegistry # Define a custom symbol provider class CustomSymbolProvider(ISymbolProvider): diff --git a/docs/core/context_providers/symbol_provider_synchronization_context.rst b/docs/core/context_providers/symbol_provider_synchronization_context.rst index 1486a3c1..06f9a6fc 100644 --- a/docs/core/context_providers/symbol_provider_synchronization_context.rst +++ b/docs/core/context_providers/symbol_provider_synchronization_context.rst @@ -22,12 +22,12 @@ attribute. Related Symbols --------------- -- ``automata.core.symbol.base.ISymbolProvider`` +- ``automata.symbol.base.ISymbolProvider`` - ``automata.tests.unit.test_symbol_graph.test_get_all_symbols`` - ``automata.tests.unit.test_symbol_graph.test_build_real_graph`` - ``automata.tests.unit.test_symbol_graph.test_build_real_graph_and_subgraph`` - ``automata.tests.unit.test_synchronizer.test_build_graph_and_handler_and_synchronize`` -- ``automata.core.context_providers.symbol_synchronization.SymbolProviderRegistry`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderRegistry`` Example ------- @@ -39,8 +39,8 @@ Example 1: Synchronizing a SymbolProvider .. code:: python - from automata.core.context_providers.symbol_synchronization import SymbolProviderSynchronizationContext - from automata.core.symbol.base import ISymbolProvider + from automata.context_providers.symbol_synchronization import SymbolProviderSynchronizationContext + from automata.symbol.base import ISymbolProvider provider = ISymbolProvider() # an instance of ISymbolProvider diff --git a/docs/core/embedding/embedding.rst b/docs/core/embedding/embedding.rst index d6a35bba..af968938 100644 --- a/docs/core/embedding/embedding.rst +++ b/docs/core/embedding/embedding.rst @@ -21,17 +21,17 @@ Related Symbols Primary Symbol ~~~~~~~~~~~~~~ -- automata.core.embedding.base.Embedding +- automata.embedding.base.Embedding Others ~~~~~~ - automata.core.base.database.vector.VectorDatabaseProvider -- automata.core.symbol.base.Symbol -- automata.core.symbol.symbol_utils.convert_to_fst_object -- automata.core.symbol_embedding.base.SymbolCodeEmbedding -- automata.core.symbol_embedding.base.SymbolDocEmbedding -- automata.core.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler +- automata.symbol.base.Symbol +- automata.symbol.symbol_utils.convert_to_fst_object +- automata.symbol_embedding.base.SymbolCodeEmbedding +- automata.symbol_embedding.base.SymbolDocEmbedding +- automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler - automata.tests.unit.test_symbol_embedding.test_update_embeddings - automata.tests.unit.test_database_vector.test_load diff --git a/docs/core/embedding/embedding_builder.rst b/docs/core/embedding/embedding_builder.rst index 0784a972..92cb2c91 100644 --- a/docs/core/embedding/embedding_builder.rst +++ b/docs/core/embedding/embedding_builder.rst @@ -9,7 +9,7 @@ embeddings. Overview -------- -``EmbeddingBuilder`` is an important part of the automata.core.embedding +``EmbeddingBuilder`` is an important part of the automata.embedding module. It provides the foundation for building symbol embeddings in an abstract way, allowing for different methods of building embeddings to be developed and used interchangeably. The class contains abstract @@ -19,10 +19,10 @@ Related Symbols --------------- - ``automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder`` -- ``automata.core.symbol_embedding.builders.SymbolCodeEmbeddingBuilder`` -- ``automata.core.symbol_embedding.builders.SymbolDocEmbeddingBuilder`` -- ``automata.core.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler.__init__`` -- ``automata.core.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler.__init`` +- ``automata.symbol_embedding.builders.SymbolCodeEmbeddingBuilder`` +- ``automata.symbol_embedding.builders.SymbolDocEmbeddingBuilder`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler.__init__`` +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler.__init`` Example ------- @@ -54,9 +54,9 @@ symbol recognition. Dependencies ------------ -- ``automata.core.embedding.base.EmbeddingVectorProvider`` -- ``automata.core.symbol.base.Symbol`` -- ``automata.core.symbol.symbol_utils.convert_to_fst_object`` +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.symbol.base.Symbol`` +- ``automata.symbol.symbol_utils.convert_to_fst_object`` Follow-up Questions: -------------------- diff --git a/docs/core/embedding/embedding_handler.rst b/docs/core/embedding/embedding_handler.rst index e280207e..273f6603 100644 --- a/docs/core/embedding/embedding_handler.rst +++ b/docs/core/embedding/embedding_handler.rst @@ -22,11 +22,11 @@ Related Symbols --------------- - ``automata.core.base.database.vector.VectorDatabaseProvider`` -- ``automata.core.embedding.base.EmbeddingBuilder`` -- ``automata.core.symbol.base.Symbol`` -- ``automata.core.symbol_embedding.base.SymbolEmbeddingHandler`` -- ``automata.core.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` -- ``automata.core.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` +- ``automata.embedding.base.EmbeddingBuilder`` +- ``automata.symbol.base.Symbol`` +- ``automata.symbol_embedding.base.SymbolEmbeddingHandler`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` Methods ------- diff --git a/docs/core/embedding/embedding_norm_type.rst b/docs/core/embedding/embedding_norm_type.rst index e839194e..9aba0cd1 100644 --- a/docs/core/embedding/embedding_norm_type.rst +++ b/docs/core/embedding/embedding_norm_type.rst @@ -27,8 +27,8 @@ that instance. Related Symbols --------------- -- ``automata.core.symbol_embedding.base.SymbolCodeEmbedding`` -- ``automata.core.embedding.base.EmbeddingSimilarityCalculator`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.embedding.base.EmbeddingSimilarityCalculator`` - ``automata.core.base.database.vector.VectorDatabaseProvider`` - ``automata.tests.unit.test_symbol_similarity.test_get_nearest_symbols_for_query`` @@ -37,8 +37,8 @@ Example .. code:: python - from automata.core.embedding.base import EmbeddingNormType, EmbeddingSimilarityCalculator - from automata.core.symbol_embedding.base import SymbolCodeEmbedding + from automata.embedding.base import EmbeddingNormType, EmbeddingSimilarityCalculator + from automata.symbol_embedding.base import SymbolCodeEmbedding from automata.core.base.database.vector import JSONSymbolEmbeddingVectorDatabase # Assuming you have a set of symbol embeddings stored in a JSON database. diff --git a/docs/core/embedding/embedding_similarity_calculator.rst b/docs/core/embedding/embedding_similarity_calculator.rst index 7a8f973d..c03ed697 100644 --- a/docs/core/embedding/embedding_similarity_calculator.rst +++ b/docs/core/embedding/embedding_similarity_calculator.rst @@ -2,7 +2,7 @@ EmbeddingSimilarityCalculator ============================= ``EmbeddingSimilarityCalculator`` is a class in the -``automata.core.embedding.base`` module. It takes an instance of +``automata.embedding.base`` module. It takes an instance of ``EmbeddingVectorProvider`` and calculates the similarity score between a query text and symbol embeddings. @@ -29,11 +29,11 @@ optionally sorts the dictionary. Related Symbols --------------- -- ``automata.core.embedding.base.EmbeddingVectorProvider`` -- ``automata.core.embedding.base.EmbeddingNormType`` -- ``automata.core.embedding.base.Embedding`` +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.embedding.base.EmbeddingNormType`` +- ``automata.embedding.base.Embedding`` - ``automata.core.base.database.vector.VectorDatabaseProvider`` -- ``automata.core.symbol.base.Symbol`` +- ``automata.symbol.base.Symbol`` Example: -------- @@ -43,8 +43,8 @@ the symbol most similar to a given query text: .. code:: python - from automata.core.embedding.base import EmbeddingSimilarityCalculator, EmbeddingVectorProvider - from automata.core.symbol.base import Symbol + from automata.embedding.base import EmbeddingSimilarityCalculator, EmbeddingVectorProvider + from automata.symbol.base import Symbol from numpy import array # Create an instance of the class diff --git a/docs/core/embedding/embedding_vector_provider.rst b/docs/core/embedding/embedding_vector_provider.rst index 139ff248..a67842d2 100644 --- a/docs/core/embedding/embedding_vector_provider.rst +++ b/docs/core/embedding/embedding_vector_provider.rst @@ -25,10 +25,10 @@ associated unit testing files. Related Symbols --------------- -- ``automata.core.embedding.base.EmbeddingBuilder`` -- ``automata.core.llm.providers.openai.OpenAIEmbeddingProvider`` -- ``automata.core.symbol_embedding.base.JSONSymbolEmbeddingVectorDatabase`` -- ``automata.core.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.embedding.base.EmbeddingBuilder`` +- ``automata.llm.providers.openai.OpenAIEmbeddingProvider`` +- ``automata.symbol_embedding.base.JSONSymbolEmbeddingVectorDatabase`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` - ``automata.tests.unit.test_symbol_embedding`` Example @@ -42,7 +42,7 @@ Here is an example involving the ``OpenAIEmbeddingProvider``: .. code:: python - from automata.core.llm.providers.openai import OpenAIEmbeddingProvider + from automata.llm.providers.openai import OpenAIEmbeddingProvider embed_provider = OpenAIEmbeddingProvider() diff --git a/docs/core/embedding/index.rst b/docs/core/embedding/index.rst index 7d6626b3..b388a323 100644 --- a/docs/core/embedding/index.rst +++ b/docs/core/embedding/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/experimental/index.rst b/docs/core/experimental/index.rst index 78e2670b..a6ae58c9 100644 --- a/docs/core/experimental/index.rst +++ b/docs/core/experimental/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/experimental/search/index.rst b/docs/core/experimental/search/index.rst index cfb9aa27..5ab0c33f 100644 --- a/docs/core/experimental/search/index.rst +++ b/docs/core/experimental/search/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/experimental/search/symbol_rank.rst b/docs/core/experimental/search/symbol_rank.rst index 76a075ef..7b222c25 100644 --- a/docs/core/experimental/search/symbol_rank.rst +++ b/docs/core/experimental/search/symbol_rank.rst @@ -46,8 +46,8 @@ Examples .. code:: python - from automata.core.symbol.base import Symbol - from automata.core.experimental.search.rank import SymbolRank, SymbolRankConfig + from automata.symbol.base import Symbol + from automata.experimental.search.rank import SymbolRank, SymbolRankConfig import networkx as nx # create a graph @@ -66,9 +66,9 @@ Examples Related Modules --------------- -- automata.core.symbol.base.Symbol -- automata.core.experimental.search.symbol_search.SymbolSearch -- automata.core.tools.builders.symbol_search.SymbolSearchToolkitBuilder +- automata.symbol.base.Symbol +- automata.experimental.search.symbol_search.SymbolSearch +- automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder Limitations ----------- diff --git a/docs/core/experimental/search/symbol_rank_config.rst b/docs/core/experimental/search/symbol_rank_config.rst index 20baa315..0487c15d 100644 --- a/docs/core/experimental/search/symbol_rank_config.rst +++ b/docs/core/experimental/search/symbol_rank_config.rst @@ -27,15 +27,15 @@ bounds, it raises a ValueError. Related Symbols --------------- -- ``automata.core.experimental.search.rank.SymbolRank`` +- ``automata.experimental.search.rank.SymbolRank`` - ``automata.tests.unit.test_symbol_rank.test_get_ranks`` - ``automata.tests.unit.test_symbol_rank.test_get_ranks_small_graph`` -- ``automata.core.experimental.search.symbol_search.SymbolSearch.symbol_rank`` +- ``automata.experimental.search.symbol_search.SymbolSearch.symbol_rank`` - ``automata.tests.unit.test_symbol_rank.test_prepare_initial_ranks`` -- ``automata.core.singletons.dependency_factory.DependencyFactory.create_symbol_rank`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_symbol_rank`` - ``automata.tests.unit.test_symbol_search_tool.test_symbol_rank_search`` - ``automata.tests.unit.test_symbol_rank.test_pagerank_config_validation`` -- ``automata.core.singletons.dependency_factory.DependencyFactory.create_symbol_search`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_symbol_search`` - ``automata.tests.regression.test_symbol_searcher_regression.test_symbol_rank_search_on_symbol`` Example @@ -46,7 +46,7 @@ SymbolRankConfig. .. code:: python - from automata.core.experimental.search.rank import SymbolRankConfig + from automata.experimental.search.rank import SymbolRankConfig config = SymbolRankConfig(alpha=0.5, max_iterations=100, tolerance=1.0e-6) config.validate_config(config) diff --git a/docs/core/experimental/search/symbol_search.rst b/docs/core/experimental/search/symbol_search.rst index aae6a4ca..e6afc20a 100644 --- a/docs/core/experimental/search/symbol_search.rst +++ b/docs/core/experimental/search/symbol_search.rst @@ -11,13 +11,13 @@ Related Symbols --------------- - ``automata.tests.unit.test_symbol_search.test_exact_search`` -- ``automata.core.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` - ``automata.tests.unit.test_symbol_search_tool.test_symbol_rank_search`` -- ``automata.core.tools.builders.symbol_search.SearchTool`` +- ``automata.tools.builders.symbol_search.SearchTool`` - ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` -- ``automata.core.symbol.base.Symbol`` +- ``automata.symbol.base.Symbol`` - ``automata.tests.unit.test_symbol_search_tool.test_init`` -- ``automata.core.tools.builders.symbol_search.SymbolSearchToolkitBuilder._exact_search_processor`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder._exact_search_processor`` - ``automata.tests.unit.test_symbol_search.test_retrieve_source_code_by_symbol`` Methods @@ -123,11 +123,11 @@ follows: .. code:: python - from automata.core.experimental.search.symbol_search import SymbolSearch - from automata.core.symbol.graph import SymbolGraph - from automata.core.experimental.search.rank import SymbolRankConfig - from automata.core.symbol_embedding.base import SymbolEmbeddingHandler - from automata.core.embedding.base import EmbeddingSimilarityCalculator + from automata.experimental.search.symbol_search import SymbolSearch + from automata.symbol.graph import SymbolGraph + from automata.experimental.search.rank import SymbolRankConfig + from automata.symbol_embedding.base import SymbolEmbeddingHandler + from automata.embedding.base import EmbeddingSimilarityCalculator symbol_graph = SymbolGraph() symbol_rank_config = SymbolRankConfig() diff --git a/docs/core/github_management/git_hub_client.rst b/docs/core/github_management/git_hub_client.rst index a7e0ae27..ecf84b2b 100644 --- a/docs/core/github_management/git_hub_client.rst +++ b/docs/core/github_management/git_hub_client.rst @@ -5,7 +5,7 @@ Overview -------- ``GitHubClient`` is a class under the -``automata.core.github_management.client`` package that provides an +``automata.github_management.client`` package that provides an interface for interacting with GitHub repositories. Its main function is to manage operations directly related to the GitHub repository, such as creating new branches, checking out branches, staging all changes to the @@ -22,13 +22,13 @@ Related Symbols - ``automata.tests.conftest.MockRepositoryClient`` - ``automata.tests.conftest.environment`` -- ``automata.core.tasks.environment.AutomataTaskEnvironment.__init__`` +- ``automata.tasks.environment.AutomataTaskEnvironment.__init__`` - ``automata.tests.unit.test_task_environment.test_commit_task`` - ``automata.tests.conftest.task`` -- ``automata.core.github_management.client.RepositoryClient`` +- ``automata.github_management.client.RepositoryClient`` - ``automata.tests.unit.test_py_reader_tool.test_tool_execution`` - ``automata.tests.unit.test_py_writer.MockCodeGenerator`` -- ``automata.core.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` - ``automata.tests.unit.test_task_environment.TestURL`` Example diff --git a/docs/core/github_management/index.rst b/docs/core/github_management/index.rst index 6933fa4b..48f2bfa7 100644 --- a/docs/core/github_management/index.rst +++ b/docs/core/github_management/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/github_management/repository_client.rst b/docs/core/github_management/repository_client.rst index e637715c..8cd7724e 100644 --- a/docs/core/github_management/repository_client.rst +++ b/docs/core/github_management/repository_client.rst @@ -14,7 +14,7 @@ class must implement these methods as per their specific logic. Related Symbols --------------- -- ``automata.core.github_management.client.GitHubClient`` +- ``automata.github_management.client.GitHubClient`` - ``automata.tests.conftest.MockRepositoryClient`` Dependencies diff --git a/docs/core/index.rst b/docs/core/index.rst index b0170085..2476ee50 100644 --- a/docs/core/index.rst +++ b/docs/core/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/llm/foundation/index.rst b/docs/core/llm/foundation/index.rst index cfea26b1..9946bd10 100644 --- a/docs/core/llm/foundation/index.rst +++ b/docs/core/llm/foundation/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/llm/foundation/llm_empty_conversation_error.rst b/docs/core/llm/foundation/llm_empty_conversation_error.rst index f80d1eb8..b39b7d5c 100644 --- a/docs/core/llm/foundation/llm_empty_conversation_error.rst +++ b/docs/core/llm/foundation/llm_empty_conversation_error.rst @@ -3,7 +3,7 @@ LLMConversation ``LLMConversation`` is an abstract base class designed to represent different types of LLM (Language Learning Module) conversations. It is a -part of the library, ``automata.core.llm.foundation``. +part of the library, ``automata.llm.foundation``. Overview -------- @@ -21,11 +21,11 @@ an empty conversation. Related Symbols --------------- -- ``automata.core.llm.foundation.LLMConversation.get_latest_message`` -- ``automata.core.llm.providers.openai.OpenAIConversation.get_latest_message`` -- ``automata.core.llm.foundation.LLMChatMessage`` -- ``automata.core.llm.foundation.LLMConversationDatabaseProvider`` -- ``automata.core.llm.providers.openai.OpenAIConversation`` +- ``automata.llm.foundation.LLMConversation.get_latest_message`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.foundation.LLMChatMessage`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider`` +- ``automata.llm.providers.openai.OpenAIConversation`` Example ------- @@ -37,7 +37,7 @@ subclass: .. code:: python - from automata.core.llm.foundation.LLMConversation import LLMEmptyConversationError, LLMChatMessage + from automata.llm.foundation.LLMConversation import LLMEmptyConversationError, LLMChatMessage from automata.core.base.patterns.observer import Observer class CustomConversation(LLMConversation): diff --git a/docs/core/llm/index.rst b/docs/core/llm/index.rst index de8575bb..2a321014 100644 --- a/docs/core/llm/index.rst +++ b/docs/core/llm/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/llm/llm_chat_completion_provider.rst b/docs/core/llm/llm_chat_completion_provider.rst index 434267cb..afe68478 100644 --- a/docs/core/llm/llm_chat_completion_provider.rst +++ b/docs/core/llm/llm_chat_completion_provider.rst @@ -48,8 +48,8 @@ an example of how to use it: .. code:: python - from automata.core.llm.providers.openai import OpenAIChatCompletionProvider - from automata.core.llm.foundation import LLMChatMessage + from automata.llm.providers.openai import OpenAIChatCompletionProvider + from automata.llm.foundation import LLMChatMessage provider = OpenAIChatCompletionProvider() diff --git a/docs/core/llm/llm_chat_message.rst b/docs/core/llm/llm_chat_message.rst index 492b6e2e..cb90c54c 100644 --- a/docs/core/llm/llm_chat_message.rst +++ b/docs/core/llm/llm_chat_message.rst @@ -24,9 +24,9 @@ and in test scenarios. Related Symbols --------------- -- ``automata.core.llm.providers.openai.OpenAIChatMessage`` -- ``automata.core.llm.providers.openai.OpenAIConversation.get_latest_message`` -- ``automata.core.llm.foundation.LLMConversation.get_latest_message`` +- ``automata.llm.providers.openai.OpenAIChatMessage`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.foundation.LLMConversation.get_latest_message`` Examples -------- @@ -36,7 +36,7 @@ The following is an example demonstrating how to create an instance of .. code:: python - from automata.core.llm.foundation import LLMChatMessage + from automata.llm.foundation import LLMChatMessage # Create a LLMChatMessage instance message = LLMChatMessage(role="user", content="Hello, how are you?") @@ -50,7 +50,7 @@ interaction to a database. .. code:: python - from automata.core.llm.foundation import LLMChatMessage + from automata.llm.foundation import LLMChatMessage from automata.core.base.database.relational import SQLDatabase # Given a SQL database instance and a conversation interaction diff --git a/docs/core/llm/llm_completion_result.rst b/docs/core/llm/llm_completion_result.rst index 832abbeb..346a69d2 100644 --- a/docs/core/llm/llm_completion_result.rst +++ b/docs/core/llm/llm_completion_result.rst @@ -10,14 +10,14 @@ Related Symbols --------------- - ``automata.tests.unit.test_automata_agent.mock_openai_response_with_completion_message`` -- ``automata.core.llm.foundation.LLMConversation.get_latest_message`` -- ``automata.core.llm.providers.openai.OpenAIChatCompletionResult`` +- ``automata.llm.foundation.LLMConversation.get_latest_message`` +- ``automata.llm.providers.openai.OpenAIChatCompletionResult`` - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` - ``automata.config.base.LLMProvider`` -- ``automata.core.llm.providers.openai.OpenAIConversation.get_latest_message`` -- ``automata.core.llm.providers.openai.OpenAIChatMessage`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.providers.openai.OpenAIChatMessage`` - ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` -- ``automata.core.llm.foundation.LLMChatCompletionProvider.get_next_assistant_completion`` +- ``automata.llm.foundation.LLMChatCompletionProvider.get_next_assistant_completion`` - ``automata.tests.unit.sample_modules.sample.EmptyClass`` Example @@ -29,7 +29,7 @@ example illustrating its functionality. .. code:: python - from automata.core.llm.foundation import LLMCompletionResult + from automata.llm.foundation import LLMCompletionResult # create an instance of LLMCompletionResult with defined role and content attributes completion_result = LLMCompletionResult(content="content of the completion result", role="assistant") diff --git a/docs/core/llm/llm_conversation.rst b/docs/core/llm/llm_conversation.rst index 4c6f0e1e..ce40676c 100644 --- a/docs/core/llm/llm_conversation.rst +++ b/docs/core/llm/llm_conversation.rst @@ -19,12 +19,12 @@ and must be subclassed to be utilized. Related Symbols --------------- -- ``automata.core.llm.providers.openai.OpenAIConversation.get_latest_message`` -- ``automata.core.llm.foundation.LLMChatMessage`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.foundation.LLMChatMessage`` - ``automata.tests.unit.test_conversation_database.test_put_message_increments_interaction_id`` - ``automata.tests.unit.test_conversation_database.test_get_messages_returns_all_messages_for_session`` -- ``automata.core.llm.providers.openai.OpenAIConversation`` -- ``automata.core.memory_store.agent_conversation_database.AgentConversationDatabase`` +- ``automata.llm.providers.openai.OpenAIConversation`` +- ``automata.memory_store.agent_conversation_database.AgentConversationDatabase`` - ``automata.core.base.patterns.observer.Observer`` Example @@ -35,7 +35,7 @@ designed: .. code:: python - from automata.core.llm.foundation import LLMConversation, LLMChatMessage + from automata.llm.foundation import LLMConversation, LLMChatMessage from automata.core.base.patterns.observer import Observer class CustomConversation(LLMConversation): diff --git a/docs/core/llm/llm_conversation_database_provider.rst b/docs/core/llm/llm_conversation_database_provider.rst index 8a3f72e7..0dbb5cb0 100644 --- a/docs/core/llm/llm_conversation_database_provider.rst +++ b/docs/core/llm/llm_conversation_database_provider.rst @@ -20,9 +20,9 @@ respectively. Additionally, the ``update`` method, inherited from the Related Symbols --------------- -- ``automata.core.llm.foundation.LLMConversation.get_latest_message`` -- ``automata.core.memory_store.agent_conversation_database.AgentConversationDatabase`` -- ``automata.core.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.foundation.LLMConversation.get_latest_message`` +- ``automata.memory_store.agent_conversation_database.AgentConversationDatabase`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` Usage example ------------- diff --git a/docs/core/llm/providers/function_call.rst b/docs/core/llm/providers/function_call.rst index 2e2c560f..e6e19bd5 100644 --- a/docs/core/llm/providers/function_call.rst +++ b/docs/core/llm/providers/function_call.rst @@ -2,7 +2,7 @@ FunctionCall ============ ``FunctionCall`` is a class representing a function call to be made by -the OpenAI agent within the ``automata.core.llm.providers.openai`` +the OpenAI agent within the ``automata.llm.providers.openai`` module. Overview @@ -19,15 +19,15 @@ convert a function call into a dictionary representation (``to_dict``). Related Symbols --------------- -- ``automata.core.llm.providers.openai.OpenAIChatCompletionResult.get_function_call`` -- ``automata.core.llm.providers.openai.OpenAIChatMessage.__init__`` +- ``automata.llm.providers.openai.OpenAIChatCompletionResult.get_function_call`` +- ``automata.llm.providers.openai.OpenAIChatMessage.__init__`` - ``automata.tests.unit.sample_modules.sample.Person`` - ``automata.tests.unit.sample_modules.sample.Person.run`` - ``automata.tests.unit.sample_modules.sample.EmptyClass`` -- ``automata.core.tasks.base.ITaskExecution.execute`` +- ``automata.tasks.base.ITaskExecution.execute`` - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` - ``automata.tests.unit.sample_modules.sample.sample_function`` -- ``automata.core.code_handling.py.writer.PyWriter.InvalidArguments`` +- ``automata.code_handling.py.writer.PyWriter.InvalidArguments`` Examples -------- @@ -37,7 +37,7 @@ Below is a simple example to demonstrate interaction with .. code:: python - from automata.core.llm.providers.openai import FunctionCall + from automata.llm.providers.openai import FunctionCall # Creating an instance of FunctionCall fn_call = FunctionCall(name="functionName", arguments={"arg1":"value1", "arg2":"value2"}) diff --git a/docs/core/llm/providers/index.rst b/docs/core/llm/providers/index.rst index 98661c5c..96aedde4 100644 --- a/docs/core/llm/providers/index.rst +++ b/docs/core/llm/providers/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/llm/providers/open_ai_chat_completion_provider.rst b/docs/core/llm/providers/open_ai_chat_completion_provider.rst index 215774cd..3bf92ad3 100644 --- a/docs/core/llm/providers/open_ai_chat_completion_provider.rst +++ b/docs/core/llm/providers/open_ai_chat_completion_provider.rst @@ -17,10 +17,10 @@ getting completion messages from the AI, and resetting conversations. Related Symbols --------------- -- ``automata.core.llm.providers.openai.OpenAIChatCompletionResult`` -- ``automata.core.llm.providers.openai.OpenAIChatMessage`` -- ``automata.core.llm.foundation.LLMConversation`` -- ``automata.core.llm.foundation.LLMChatCompletionProvider`` +- ``automata.llm.providers.openai.OpenAIChatCompletionResult`` +- ``automata.llm.providers.openai.OpenAIChatMessage`` +- ``automata.llm.foundation.LLMConversation`` +- ``automata.llm.foundation.LLMChatCompletionProvider`` Example ------- @@ -30,7 +30,7 @@ The following is an example demonstrating how to instantiate and use the .. code:: python - from automata.core.llm.providers.openai import OpenAIChatCompletionProvider, LLMChatMessage + from automata.llm.providers.openai import OpenAIChatCompletionProvider, LLMChatMessage model = "gpt-4" conversation = OpenAIChatCompletionProvider(model) diff --git a/docs/core/llm/providers/open_ai_chat_completion_result.rst b/docs/core/llm/providers/open_ai_chat_completion_result.rst index 6f98f776..ac5c724a 100644 --- a/docs/core/llm/providers/open_ai_chat_completion_result.rst +++ b/docs/core/llm/providers/open_ai_chat_completion_result.rst @@ -28,7 +28,7 @@ raw data and assigns it to class variables. .. code:: python - from automata.core.llm.providers.openai import OpenAIChatCompletionResult + from automata.llm.providers.openai import OpenAIChatCompletionResult # Example raw data from OpenAI chat API raw_data = { @@ -67,7 +67,7 @@ instance and printing it out using the ``__str__`` method: .. code:: python # Import necessary classes - from automata.core.llm.providers.openai import OpenAIChatCompletionResult + from automata.llm.providers.openai import OpenAIChatCompletionResult # Create an instance using the `from_args` class method completion_result = OpenAIChatCompletionResult.from_args("assistant", "Hello, how can I assist you today?", None) diff --git a/docs/core/llm/providers/open_ai_chat_message.rst b/docs/core/llm/providers/open_ai_chat_message.rst index a4fa06f0..6c091a06 100644 --- a/docs/core/llm/providers/open_ai_chat_message.rst +++ b/docs/core/llm/providers/open_ai_chat_message.rst @@ -9,17 +9,17 @@ message TO or FROM the OpenAI LLM Chat API. It provides convenient methods to parse and generate messages compatible with the OpenAI Chat API. -This class is a part of the ``automata.core.llm.providers.openai`` +This class is a part of the ``automata.llm.providers.openai`` module and extends the ``LLMChatMessage`` base class, adding unique fields and methods suitable for communication with the OpenAI API. Related Symbols --------------- -- ``automata.core.llm.providers.openai.OpenAIChatCompletionResult`` -- ``automata.core.llm.providers.openai.OpenAIConversation`` -- ``automata.core.llm.providers.openai.OpenAIChatCompletionProvider`` -- ``automata.core.llm.foundation.LLMChatMessage`` +- ``automata.llm.providers.openai.OpenAIChatCompletionResult`` +- ``automata.llm.providers.openai.OpenAIConversation`` +- ``automata.llm.providers.openai.OpenAIChatCompletionProvider`` +- ``automata.llm.foundation.LLMChatMessage`` Example ------- @@ -29,7 +29,7 @@ dictionary, and retrieving it from a completion result: .. code:: python - from automata.core.llm.providers.openai import FunctionCall, OpenAIChatCompletionResult, OpenAIChatMessage + from automata.llm.providers.openai import FunctionCall, OpenAIChatCompletionResult, OpenAIChatMessage # The function call function_call = FunctionCall.from_response_dict({ diff --git a/docs/core/llm/providers/open_ai_conversation.rst b/docs/core/llm/providers/open_ai_conversation.rst index 3f83cc8a..17445f6c 100644 --- a/docs/core/llm/providers/open_ai_conversation.rst +++ b/docs/core/llm/providers/open_ai_conversation.rst @@ -23,10 +23,10 @@ can be retrieved when required. An important aspect is that the Related Symbols --------------- -- ``automata.core.llm.providers.openai.OpenAIChatMessage`` -- ``automata.core.llm.providers.openai.OpenAIChatCompletionProvider`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` -- ``automata.core.llm.foundation.LLMChatMessage`` +- ``automata.llm.providers.openai.OpenAIChatMessage`` +- ``automata.llm.providers.openai.OpenAIChatCompletionProvider`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.llm.foundation.LLMChatMessage`` Example ------- @@ -36,7 +36,7 @@ Here is an example demonstrating how to create and manage messages in an .. code:: python - from automata.core.llm.providers.openai import OpenAIConversation, OpenAIChatMessage + from automata.llm.providers.openai import OpenAIConversation, OpenAIChatMessage # create conversation conversation = OpenAIConversation() diff --git a/docs/core/llm/providers/open_ai_embedding_provider.rst b/docs/core/llm/providers/open_ai_embedding_provider.rst index c7a634b6..e5efbfc1 100644 --- a/docs/core/llm/providers/open_ai_embedding_provider.rst +++ b/docs/core/llm/providers/open_ai_embedding_provider.rst @@ -22,14 +22,14 @@ the time of object initialization, and the default engine used is Related Symbols --------------- -- ``automata.core.embedding.base.EmbeddingVectorProvider`` -- ``automata.core.llm.foundation.LLMChatCompletionProvider`` -- ``automata.core.llm.foundation.LLMChatMessage`` -- ``automata.core.llm.foundation.LLMCompletionResult`` -- ``automata.core.llm.foundation.LLMConversation`` -- ``automata.core.singletons.dependency_factory.DependencyFactory`` +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.llm.foundation.LLMChatCompletionProvider`` +- ``automata.llm.foundation.LLMChatMessage`` +- ``automata.llm.foundation.LLMCompletionResult`` +- ``automata.llm.foundation.LLMConversation`` +- ``automata.singletons.dependency_factory.DependencyFactory`` - ``automata.config.base.LLMProvider`` -- ``automata.core.tools.base.Tool`` +- ``automata.tools.base.Tool`` Example ------- @@ -39,7 +39,7 @@ Below is an example demonstrating how to use the .. code:: python - from automata.core.llm.providers.openai import OpenAIEmbeddingProvider + from automata.llm.providers.openai import OpenAIEmbeddingProvider import numpy as np # Create an instance of OpenAIEmbeddingProvider diff --git a/docs/core/llm/providers/open_ai_function.rst b/docs/core/llm/providers/open_ai_function.rst index d4c65329..86148674 100644 --- a/docs/core/llm/providers/open_ai_function.rst +++ b/docs/core/llm/providers/open_ai_function.rst @@ -20,10 +20,10 @@ Related Symbols - ``automata.tests.unit.sample_modules.sample.sample_function``: An example of a function that can be represented by ``OpenAIFunction``. -- ``automata.core.agent.providers.OpenAIAutomataAgent.functions``: A +- ``automata.agent.providers.OpenAIAutomataAgent.functions``: A method that returns a list of ``OpenAIFunction`` instances representing the available functions for the agent. -- ``automata.core.llm.providers.openai.OpenAITool``: A class +- ``automata.llm.providers.openai.OpenAITool``: A class representing a tool that can be used by the OpenAI agent which utilizes ``OpenAIFunction``. @@ -36,7 +36,7 @@ The following is an example demonstrating how to create an instance of .. code:: python - from automata.core.llm.providers.openai import OpenAIFunction + from automata.llm.providers.openai import OpenAIFunction # Initialize OpenAIFunction object function = OpenAIFunction( diff --git a/docs/core/llm/providers/open_ai_incorrect_message_type_error.rst b/docs/core/llm/providers/open_ai_incorrect_message_type_error.rst index 0ea08d34..71a42a33 100644 --- a/docs/core/llm/providers/open_ai_incorrect_message_type_error.rst +++ b/docs/core/llm/providers/open_ai_incorrect_message_type_error.rst @@ -18,13 +18,13 @@ Related Symbols 1. ``automata.tests.unit.test_automata_agent.mock_openai_response_with_completion_message`` 2. ``automata.tests.unit.test_automata_agent.test_run_with_completion_message`` 3. ``automata.tests.unit.test_automata_agent.test_run_with_no_completion`` -4. ``automata.core.llm.providers.openai.OpenAIConversation`` +4. ``automata.llm.providers.openai.OpenAIConversation`` 5. ``automata.tests.unit.test_automata_agent.test_build_initial_messages`` -6. ``automata.core.llm.providers.openai.OpenAIConversation.add_message`` +6. ``automata.llm.providers.openai.OpenAIConversation.add_message`` 7. ``automata.tests.unit.test_automata_agent.test_iter_step_without_api_call`` -8. ``automata.core.agent.providers.OpenAIAutomataAgent`` +8. ``automata.agent.providers.OpenAIAutomataAgent`` 9. ``automata.tests.unit.test_automata_agent_builder.test_builder_invalid_input_types`` -10. ``automata.core.llm.providers.openai.OpenAIConversation.__init__`` +10. ``automata.llm.providers.openai.OpenAIConversation.__init__`` Example ------- @@ -36,7 +36,7 @@ error is raised. .. code:: python - from automata.core.llm.providers.openai import OpenAIConversation, OpenAIIncorrectMessageTypeError + from automata.llm.providers.openai import OpenAIConversation, OpenAIIncorrectMessageTypeError try: conversation = OpenAIConversation() diff --git a/docs/core/llm/providers/open_ai_tool.rst b/docs/core/llm/providers/open_ai_tool.rst index 5ccdd407..46a73a5f 100644 --- a/docs/core/llm/providers/open_ai_tool.rst +++ b/docs/core/llm/providers/open_ai_tool.rst @@ -19,12 +19,12 @@ and ``SymbolSearchOpenAIToolkitBuilder``, to create lists of Related Symbols --------------- -- ``automata.core.embedding.base.EmbeddingVectorProvider`` -- ``automata.core.llm.foundation.LLMChatCompletionProvider`` -- ``automata.core.llm.foundation.LLMChatMessage`` -- ``automata.core.llm.foundation.LLMCompletionResult`` -- ``automata.core.llm.foundation.LLMConversation`` -- ``automata.core.tools.base.Tool`` +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.llm.foundation.LLMChatCompletionProvider`` +- ``automata.llm.foundation.LLMChatMessage`` +- ``automata.llm.foundation.LLMCompletionResult`` +- ``automata.llm.foundation.LLMConversation`` +- ``automata.tools.base.Tool`` - ``automata.tests.unit.test_tool.TestTool`` Example @@ -36,7 +36,7 @@ response” irrespective of the input provided. .. code:: python - from automata.core.llm.providers.openai import OpenAITool + from automata.llm.providers.openai import OpenAITool from automata.tests.unit.test_tool import TestTool tool = TestTool( diff --git a/docs/core/memory_store/agent_conversation_database.rst b/docs/core/memory_store/agent_conversation_database.rst index e33b17f7..10a1081b 100644 --- a/docs/core/memory_store/agent_conversation_database.rst +++ b/docs/core/memory_store/agent_conversation_database.rst @@ -16,15 +16,15 @@ for the methods ``get_messages`` and ``save_message``. Related Symbols --------------- -- ``automata.core.llm.providers.openai.OpenAIChatCompletionProvider.reset`` +- ``automata.llm.providers.openai.OpenAIChatCompletionProvider.reset`` - ``automata.config.CONVERSATION_DB_PATH`` - ``automata.core.base.database.relational.SQLDatabase.connect`` - ``automata.tests.unit.test_conversation_database.db`` - ``automata.tests.unit.test_conversation_database.test_get_messages_returns_all_messages_for_session`` - ``automata.tests.unit.test_conversation_database.test_put_message_increments_interaction_id`` -- ``automata.core.llm.foundation.LLMConversationDatabaseProvider.get_messages`` -- ``automata.core.llm.foundation.LLMConversationDatabaseProvider.save_message`` -- ``automata.core.agent.providers.OpenAIAutomataAgent.set_database_provider`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider.get_messages`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider.save_message`` +- ``automata.agent.providers.OpenAIAutomataAgent.set_database_provider`` Example ------- @@ -34,8 +34,8 @@ The following is an example demonstrating how to create an instance of .. code:: python - from automata.core.memory_store.agent_conversation_database import AgentConversationDatabase - from automata.core.llm.foundation import LLMChatMessage + from automata.memory_store.agent_conversation_database import AgentConversationDatabase + from automata.llm.foundation import LLMChatMessage # Initialize a database path and session id db_path = 'path/to/db' diff --git a/docs/core/memory_store/index.rst b/docs/core/memory_store/index.rst index b5cfaa9d..9ba232bd 100644 --- a/docs/core/memory_store/index.rst +++ b/docs/core/memory_store/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/memory_store/symbol_code_embedding_handler.rst b/docs/core/memory_store/symbol_code_embedding_handler.rst index 58ca4ea1..c7bacdcf 100644 --- a/docs/core/memory_store/symbol_code_embedding_handler.rst +++ b/docs/core/memory_store/symbol_code_embedding_handler.rst @@ -23,14 +23,14 @@ Related Symbols --------------- - ``automata.tests.unit.test_symbol_similarity.test_get_nearest_symbols_for_query`` -- ``automata.core.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` - ``automata.tests.unit.test_symbol_embedding.test_get_embedding`` - ``automata.tests.unit.test_synchronizer.test_build_graph_and_handler_and_synchronize`` -- ``automata.core.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` - ``automata.tests.unit.test_database_vector.test_load`` -- ``automata.core.singletons.dependency_factory.DependencyFactory.create_symbol_code_embedding_handler`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_symbol_code_embedding_handler`` - ``automata.tests.unit.test_database_vector.test_lookup_symbol`` -- ``automata.core.symbol_embedding.builders.SymbolCodeEmbeddingBuilder`` +- ``automata.symbol_embedding.builders.SymbolCodeEmbeddingBuilder`` - ``automata.tests.unit.test_database_vector.test_add_symbols`` Method Details @@ -75,10 +75,10 @@ Consider the following code snippet, where we use .. code:: python - from automata.core.symbol.base import Symbol - from automata.core.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase, SymbolCodeEmbedding - from automata.core.symbol_embedding.base import SymbolCodeEmbeddingHandler - from automata.core.symbol_embedding.builders import SymbolCodeEmbeddingBuilder + from automata.symbol.base import Symbol + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase, SymbolCodeEmbedding + from automata.symbol_embedding.base import SymbolCodeEmbeddingHandler + from automata.symbol_embedding.builders import SymbolCodeEmbeddingBuilder from unittest.mock import MagicMock # Mock symbols and their embeddings diff --git a/docs/core/memory_store/symbol_doc_embedding_handler.rst b/docs/core/memory_store/symbol_doc_embedding_handler.rst index 4980b310..366115a1 100644 --- a/docs/core/memory_store/symbol_doc_embedding_handler.rst +++ b/docs/core/memory_store/symbol_doc_embedding_handler.rst @@ -15,12 +15,12 @@ Related Symbols --------------- - automata.tests.unit.sample_modules.sample.OuterClass.InnerClass -- automata.core.symbol_embedding.base.SymbolDocEmbedding +- automata.symbol_embedding.base.SymbolDocEmbedding - automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder -- automata.core.singletons.dependency_factory.DependencyFactory.create_symbol_doc_embedding_handler -- automata.core.symbol_embedding.builders.SymbolDocEmbeddingBuilder +- automata.singletons.dependency_factory.DependencyFactory.create_symbol_doc_embedding_handler +- automata.symbol_embedding.builders.SymbolDocEmbeddingBuilder - automata.tests.unit.test_symbol_embedding.test_get_embedding -- automata.core.tools.builders.context_oracle.ContextOracleToolkitBuilder.\__init\_\_ +- automata.tools.builders.context_oracle.ContextOracleToolkitBuilder.\__init\_\_ - automata.tests.unit.test_py_reader.test_get_docstring_nested_class_method Example @@ -30,9 +30,9 @@ The following example demonstrates how to use SymbolDocEmbeddingHandler: .. code:: python - from automata.core.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase, SymbolDocEmbedding, SymbolEmbeddingHandler - from automata.core.symbol_embedding.builders import SymbolDocEmbeddingBuilder - from automata.core.symbol.base import Symbol + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase, SymbolDocEmbedding, SymbolEmbeddingHandler + from automata.symbol_embedding.builders import SymbolDocEmbeddingBuilder + from automata.symbol.base import Symbol # Initialize database and builder embedding_db = JSONSymbolEmbeddingVectorDatabase('path_to_embedding_db') diff --git a/docs/core/navigation/directory.rst b/docs/core/navigation/directory.rst index 59a4c29d..995a7e49 100644 --- a/docs/core/navigation/directory.rst +++ b/docs/core/navigation/directory.rst @@ -1,4 +1,4 @@ -automata.core.navigation.directory.Directory +automata.navigation.directory.Directory ============================================ The ``Directory`` class is a part of the ``automata`` library, primarily @@ -27,7 +27,7 @@ are needed: import logging import os from typing import Dict, List, Optional - from automata.core.navigation.directory import Directory + from automata.navigation.directory import Directory Key Methods ----------- @@ -66,7 +66,7 @@ Usage Example .. code:: python - from automata.core.navigation.directory import Directory + from automata.navigation.directory import Directory # instantiate root_dir = Directory("root") @@ -88,7 +88,7 @@ Usage Example print(root_dir.is_leaf_dir()) # False Please note that for this example to run you have to import ``File`` -from the ``automata.core.navigation.directory`` module. +from the ``automata.navigation.directory`` module. Related Symbols --------------- diff --git a/docs/core/navigation/directory_manager.rst b/docs/core/navigation/directory_manager.rst index e6c2e1cc..ebb3a733 100644 --- a/docs/core/navigation/directory_manager.rst +++ b/docs/core/navigation/directory_manager.rst @@ -9,7 +9,7 @@ obtain list of subdirectories inside a particular directory. Overview -------- -``DirectoryManager``, part of ``automata.core.navigation.directory``, +``DirectoryManager``, part of ``automata.navigation.directory``, conducts operations related to directory structure. It initiates with a base path and contains a ``root`` attribute representing the root directory of the structure, as an instance of ``Directory``. @@ -26,12 +26,12 @@ DirectoryManager provides several methods including: Related Symbols --------------- -- ``automata.core.navigation.directory.Directory``: Represents a +- ``automata.navigation.directory.Directory``: Represents a directory that contains child nodes which can be either files or directories. -- ``automata.core.github_management.client.GitHubClient``: Provides an +- ``automata.github_management.client.GitHubClient``: Provides an interface for interacting with GitHub repositories. -- ``automata.core.tasks.environment.AutomataTaskEnvironment``: The +- ``automata.tasks.environment.AutomataTaskEnvironment``: The environment in which the Automata tasks are conducted. - ``automata.tests.unit.test_directory_manager``: Contains unit tests for the DirectoryManager methods. @@ -45,7 +45,7 @@ instantiated and used. .. code:: python # Import the necessary modules - from automata.core.navigation.directory import DirectoryManager + from automata.navigation.directory import DirectoryManager # Define the base directory base_dir = "/home/user/documents" diff --git a/docs/core/navigation/file.rst b/docs/core/navigation/file.rst index 013040be..17eb19c3 100644 --- a/docs/core/navigation/file.rst +++ b/docs/core/navigation/file.rst @@ -7,7 +7,7 @@ structure. Overview -------- -``File`` is positioned within the ``automata.core.navigation.directory`` +``File`` is positioned within the ``automata.navigation.directory`` module of the Automata Library. It acts as a symbol that stands for a file in a tree-like directory structure. This class gets instantiated with a name and an optional parent node. It inherits properties and @@ -16,7 +16,7 @@ behavior from the ``Node`` class. Related Symbols --------------- -- ``automata.core.navigation.directory.Node`` +- ``automata.navigation.directory.Node`` Examples -------- @@ -26,7 +26,7 @@ The following example demonstrates how to create an instance of .. code:: python - from automata.core.navigation.directory import File, Node + from automata.navigation.directory import File, Node root = Node('root') file = File('file1', parent=root) diff --git a/docs/core/navigation/index.rst b/docs/core/navigation/index.rst index d95d1f2c..abfc9f66 100644 --- a/docs/core/navigation/index.rst +++ b/docs/core/navigation/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/navigation/node.rst b/docs/core/navigation/node.rst index 831081b8..fa75151d 100644 --- a/docs/core/navigation/node.rst +++ b/docs/core/navigation/node.rst @@ -5,7 +5,7 @@ Overview -------- The ``Node`` class is an abstract base class used in the creation of a -file tree in the ``automata.core.navigation.directory`` module. Each +file tree in the ``automata.navigation.directory`` module. Each node can represent a file or a directory within this file tree. It is primarily used in the construction of trees for file or directory navigation within the Automata project. Each instance of the ``Node`` @@ -18,14 +18,14 @@ Related Symbols - ``automata.tests.unit.sample_modules.sample.EmptyClass`` - ``automata.tests.unit.test_directory_manager.test_get_node_for_path`` -- ``automata.core.navigation.directory.File`` +- ``automata.navigation.directory.File`` - ``automata.tests.unit.sample_modules.sample.OuterClass`` -- ``automata.core.navigation.directory.Directory`` +- ``automata.navigation.directory.Directory`` - ``automata.tests.unit.test_py_writer.MockCodeGenerator`` - ``automata.tests.conftest.MockRepositoryClient`` -- ``automata.core.symbol.base.Symbol`` +- ``automata.symbol.base.Symbol`` - ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` -- ``automata.core.code_handling.py.writer.PyWriter`` +- ``automata.code_handling.py.writer.PyWriter`` Example ------- @@ -37,7 +37,7 @@ subclasses like ``File`` and ``Directory``. In the example below, a .. code:: python - from automata.core.navigation.directory import File + from automata.navigation.directory import File file = File("sample_file", None) diff --git a/docs/core/navigation/py/dot_path_map.rst b/docs/core/navigation/py/dot_path_map.rst index 4fdb426b..c46b68d1 100644 --- a/docs/core/navigation/py/dot_path_map.rst +++ b/docs/core/navigation/py/dot_path_map.rst @@ -20,7 +20,7 @@ corresponding filepaths. A counterpart map, Related Symbols --------------- -- ``automata.core.singletons.py_module_loader.PyModuleLoader`` +- ``automata.singletons.py_module_loader.PyModuleLoader`` - ``automata.tests.unit.test_directory_manager.test_get_node_for_path`` - ``automata.tests.unit.test_database_vector.test_lookup_symbol`` @@ -29,7 +29,7 @@ Example .. code:: python - from automata.core.navigation.py.dot_path_map import DotPathMap + from automata.navigation.py.dot_path_map import DotPathMap # Initialize a new DotPathMap dpm = DotPathMap('/path/to/your/module/root', 'prefix') diff --git a/docs/core/navigation/py/index.rst b/docs/core/navigation/py/index.rst index ad254655..fa7270a7 100644 --- a/docs/core/navigation/py/index.rst +++ b/docs/core/navigation/py/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/retrievers/index.rst b/docs/core/retrievers/index.rst index 66587e16..c9f423c7 100644 --- a/docs/core/retrievers/index.rst +++ b/docs/core/retrievers/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/retrievers/py/context/indent_manager.rst b/docs/core/retrievers/py/context/indent_manager.rst index 68a02410..0841bdf4 100644 --- a/docs/core/retrievers/py/context/indent_manager.rst +++ b/docs/core/retrievers/py/context/indent_manager.rst @@ -1,2 +1,2 @@ Symbol: -automata.core.retrievers.py.context.PyContextRetriever.IndentManager +automata.retrievers.py.context.PyContextRetriever.IndentManager diff --git a/docs/core/retrievers/py/context/index.rst b/docs/core/retrievers/py/context/index.rst index 578a8d0d..27cb597e 100644 --- a/docs/core/retrievers/py/context/index.rst +++ b/docs/core/retrievers/py/context/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/retrievers/py/index.rst b/docs/core/retrievers/py/index.rst index 25f9ae4e..646e08f0 100644 --- a/docs/core/retrievers/py/index.rst +++ b/docs/core/retrievers/py/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/retrievers/py/py_context_retriever.rst b/docs/core/retrievers/py/py_context_retriever.rst index 21950c1f..12c92a33 100644 --- a/docs/core/retrievers/py/py_context_retriever.rst +++ b/docs/core/retrievers/py/py_context_retriever.rst @@ -20,11 +20,11 @@ Related Symbols --------------- - ``automata.core.base.database.vector.VectorDatabaseProvider`` -- ``automata.core.code_handling.py.reader.PyReader`` -- ``automata.core.symbol.base.Symbol`` -- ``automata.core.symbol.graph.SymbolGraph`` -- ``automata.core.symbol.symbol_utils.convert_to_fst_object`` -- ``automata.core.symbol.symbol_utils.get_rankable_symbols`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.symbol.base.Symbol`` +- ``automata.symbol.graph.SymbolGraph`` +- ``automata.symbol.symbol_utils.convert_to_fst_object`` +- ``automata.symbol.symbol_utils.get_rankable_symbols`` - ``automata.core.utils.get_root_py_fpath`` Example @@ -36,9 +36,9 @@ project. .. code:: python - from automata.core.retrievers.py.context import PyContextRetriever - from automata.core.symbol.graph import SymbolGraph - from automata.core.symbol.base import Symbol + from automata.retrievers.py.context import PyContextRetriever + from automata.symbol.graph import SymbolGraph + from automata.symbol.base import Symbol graph = SymbolGraph(index_path="my_index_path") symbol = Symbol.from_string(symbol_str="my_symbol") diff --git a/docs/core/retrievers/py/py_context_retriever_config.rst b/docs/core/retrievers/py/py_context_retriever_config.rst index 28e2f4b1..02192989 100644 --- a/docs/core/retrievers/py/py_context_retriever_config.rst +++ b/docs/core/retrievers/py/py_context_retriever_config.rst @@ -22,9 +22,9 @@ retrieval and parsing process of source code, such as ``PyReader``, Related Symbols --------------- -- ``automata.core.retrievers.py.context.PyContextRetriever`` -- ``automata.core.code_handling.py.reader.PyReader`` -- ``automata.core.singletons.dependency_factory.DependencyFactory.create_py_context_retriever`` +- ``automata.retrievers.py.context.PyContextRetriever`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_py_context_retriever`` - ``automata.tests.unit.test_py_reader_tool.python_retriever_tool_builder`` Usage Example @@ -32,7 +32,7 @@ Usage Example .. code:: python - from automata.core.retrievers.py.context import PyContextRetrieverConfig + from automata.retrievers.py.context import PyContextRetrieverConfig config = PyContextRetrieverConfig( spacer=" ", diff --git a/docs/core/root_dict.rst b/docs/core/root_dict.rst index 0cc75f70..49beace8 100644 --- a/docs/core/root_dict.rst +++ b/docs/core/root_dict.rst @@ -14,7 +14,7 @@ RootDict import yaml from copy import deepcopy from typing import Any, Dict, List, Optional, TypedDict, Union, cast - from automata.core.symbol.base import Symbol + from automata.symbol.base import Symbol from automata.config import OPENAI_API_KEY **Class Docstring**: ``RootDict`` is a dictionary representing the root @@ -69,11 +69,11 @@ Related Symbols: 6. ``automata.tests.unit.test_directory_manager.test_load_directory_structure`` -7. ``automata.core.llm.foundation.LLMChatMessage.to_dict`` +7. ``automata.llm.foundation.LLMChatMessage.to_dict`` 8. ``automata.tests.unit.sample_modules.sample.OuterClass`` -9. ``automata.core.llm.providers.openai.OpenAIChatMessage.to_dict`` +9. ``automata.llm.providers.openai.OpenAIChatMessage.to_dict`` 10. ``automata.tests.unit.test_task_environment.TestURL`` diff --git a/docs/core/singletons/dependency_factory.rst b/docs/core/singletons/dependency_factory.rst index 25527f97..874efc73 100644 --- a/docs/core/singletons/dependency_factory.rst +++ b/docs/core/singletons/dependency_factory.rst @@ -2,7 +2,7 @@ DependencyFactory ================= ``DependencyFactory`` is a source class found in -**automata.core.singleton.dependency_factory** that is utilized in the +**automata.singleton.dependency_factory** that is utilized in the creation of dependencies for input Tool construction. The main functionality of ``DependencyFactory`` is to ensure that the @@ -26,31 +26,31 @@ dependencies to import, from functools import lru_cache from typing import Any, Dict, List, Set, Tuple from automata.config.base import ConfigCategory - from automata.core.agent.agent import AgentToolkitNames - from automata.core.agent.error import AgentGeneralError, UnknownToolError + from automata.agent.agent import AgentToolkitNames + from automata.agent.error import AgentGeneralError, UnknownToolError from automata.core.base.patterns.singleton import Singleton - from automata.core.code_handling.py.reader import PyReader - from automata.core.code_handling.py.writer import PyWriter - from automata.core.embedding.base import EmbeddingSimilarityCalculator - from automata.core.experimental.search.rank import SymbolRank, SymbolRankConfig - from automata.core.experimental.search.symbol_search import SymbolSearch - from automata.core.llm.providers.openai import ( + from automata.code_handling.py.reader import PyReader + from automata.code_handling.py.writer import PyWriter + from automata.embedding.base import EmbeddingSimilarityCalculator + from automata.experimental.search.rank import SymbolRank, SymbolRankConfig + from automata.experimental.search.symbol_search import SymbolSearch + from automata.llm.providers.openai import ( OpenAIChatCompletionProvider, OpenAIEmbeddingProvider, ) - from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler - from automata.core.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler - from automata.core.retrievers.py.context import ( + from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler + from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler + from automata.retrievers.py.context import ( PyContextRetriever, PyContextRetrieverConfig, ) - from automata.core.symbol.graph import SymbolGraph - from automata.core.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase - from automata.core.symbol_embedding.builders import ( + from automata.symbol.graph import SymbolGraph + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase + from automata.symbol_embedding.builders import ( SymbolCodeEmbeddingBuilder, SymbolDocEmbeddingBuilder, ) - from automata.core.tools.factory import AgentToolFactory, logger + from automata.tools.factory import AgentToolFactory, logger from automata.core.utils import get_config_fpath Usage Example @@ -60,7 +60,7 @@ Here is an example that showcases how ``DependencyFactory`` is used: .. code:: python - from automata.core.singletons.dependency_factory import DependencyFactory + from automata.singletons.dependency_factory import DependencyFactory # Create a DependencyFactory object setting the overrides dep_factory = DependencyFactory(py_context_retriever_config=PyContextRetrieverConfig()) diff --git a/docs/core/singletons/index.rst b/docs/core/singletons/index.rst index f657009d..7736e847 100644 --- a/docs/core/singletons/index.rst +++ b/docs/core/singletons/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/singletons/open_ai_automata_agent_toolkit_registry.rst b/docs/core/singletons/open_ai_automata_agent_toolkit_registry.rst index 3c2f6910..067db941 100644 --- a/docs/core/singletons/open_ai_automata_agent_toolkit_registry.rst +++ b/docs/core/singletons/open_ai_automata_agent_toolkit_registry.rst @@ -21,13 +21,13 @@ load all the registered builders when the system starts. Related Symbols --------------- -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder``: This is +- ``automata.agent.providers.OpenAIAgentToolkitBuilder``: This is the base class for all toolkit builders. Each specific toolkit builder must subclass this and implement its methods. -- ``automata.core.tools.builders.PyReaderOpenAIToolkitBuilder``: This +- ``automata.tools.builders.PyReaderOpenAIToolkitBuilder``: This is an example of a specific toolkit builder. It is responsible for building ``PyReader`` tools for the OpenAI agent. -- ``automata.core.tools.builders.PyWriterOpenAIToolkitBuilder``: This +- ``automata.tools.builders.PyWriterOpenAIToolkitBuilder``: This is another example of a specific toolkit builder. It is responsible for building ``PyWriter`` tools for the OpenAI agent. @@ -36,8 +36,8 @@ Usage Example .. code:: python - from automata.core.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry - from automata.core.tools.builders.py_reader import PyReaderOpenAIToolkitBuilder + from automata.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry + from automata.tools.builders.py_reader import PyReaderOpenAIToolkitBuilder # registering a builder OpenAIAutomataAgentToolkitRegistry.register_tool_manager(PyReaderOpenAIToolkitBuilder) diff --git a/docs/core/singletons/py_module_loader.rst b/docs/core/singletons/py_module_loader.rst index dac8dd73..d0ef8072 100644 --- a/docs/core/singletons/py_module_loader.rst +++ b/docs/core/singletons/py_module_loader.rst @@ -42,7 +42,7 @@ Example .. code:: python - from automata.core.singletons.py_module_loader import PyModuleLoader + from automata.singletons.py_module_loader import PyModuleLoader from automata.core.utils import get_root_fpath, get_root_py_fpath # Initialize the loader @@ -57,18 +57,18 @@ Example Related Symbols --------------- -- ``automata.core.navigation.py.dot_path_map.DotPathMap`` +- ``automata.navigation.py.dot_path_map.DotPathMap`` - ``automata.core.base.patterns.singleton.Singleton`` -- ``automata.core.navigation.py.dot_path_map.DotPathMap`` -- ``automata.core.navigation.py.dot_path_map.DotPathMap.contains_dotpath`` +- ``automata.navigation.py.dot_path_map.DotPathMap`` +- ``automata.navigation.py.dot_path_map.DotPathMap.contains_dotpath`` - ``automata.core.utils.get_root_fpath`` - ``automata.core.utils.get_root_py_fpath`` Dependencies ------------ -- ``automata.core.navigation.py.dot_path_map.DotPathMap.put_module`` -- ``automata.core.navigation.py.dot_path_map.DotPathMap.get_module_dotpath_by_fpath`` +- ``automata.navigation.py.dot_path_map.DotPathMap.put_module`` +- ``automata.navigation.py.dot_path_map.DotPathMap.get_module_dotpath_by_fpath`` Limitations ----------- diff --git a/docs/core/symbol/base/index.rst b/docs/core/symbol/base/index.rst index 81ee1645..8cd33440 100644 --- a/docs/core/symbol/base/index.rst +++ b/docs/core/symbol/base/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/symbol/base/py_kind.rst b/docs/core/symbol/base/py_kind.rst index d9552a9b..11fcb56a 100644 --- a/docs/core/symbol/base/py_kind.rst +++ b/docs/core/symbol/base/py_kind.rst @@ -24,11 +24,11 @@ from a descriptor to its original format. Related Symbols --------------- -- ``automata.core.symbol.scip_pb2.Descriptor`` - the protobuf format of +- ``automata.symbol.scip_pb2.Descriptor`` - the protobuf format of descriptor used to interact with descriptors -- ``automata.core.symbol.base.Symbol`` - the base class for symbols for +- ``automata.symbol.base.Symbol`` - the base class for symbols for which ``SymbolDescriptor`` provides description functionality -- ``automata.core.symbol.parser`` - where the ``parse_symbol`` method +- ``automata.symbol.parser`` - where the ``parse_symbol`` method utilizes ``SymbolDescriptor`` Example @@ -39,8 +39,8 @@ The following is an example demonstrating how to create an instance of .. code:: python - from automata.core.symbol.scip_pb2 import Descriptor as DescriptorProto - from automata.core.symbol.base import SymbolDescriptor + from automata.symbol.scip_pb2 import Descriptor as DescriptorProto + from automata.symbol.base import SymbolDescriptor descriptor_suffix = DescriptorProto.NAME # example value name = 'test_name' @@ -51,9 +51,9 @@ symbol - .. code:: python - from automata.core.experimental.search.symbol_parser import parse_symbol + from automata.experimental.search.symbol_parser import parse_symbol symbol_method = parse_symbol( - "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.tools.base`/ToolNotFoundError#__init__()." + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.tools.base`/ToolNotFoundError#__init__()." ) # SymbolDescriptor is used internally in this process diff --git a/docs/core/symbol/graph_builder.rst b/docs/core/symbol/graph_builder.rst index 2b61a45b..4d60ede1 100644 --- a/docs/core/symbol/graph_builder.rst +++ b/docs/core/symbol/graph_builder.rst @@ -1,7 +1,7 @@ GraphBuilder ============ -``GraphBuilder`` is a class within the ``automata.core.symbol.graph`` +``GraphBuilder`` is a class within the ``automata.symbol.graph`` module that constructs a directed multi-graph, called a ``SymbolGraph``, from a corresponding Index. The ``SymbolGraph`` incorporates and represents the relationship between symbols in a python codebase. @@ -20,8 +20,8 @@ adds edges representing relationships, references, and calls between Related Symbols --------------- -- ``automata.core.symbol.graph.SymbolGraph`` -- ``automata.core.symbol.parser.parse_symbol`` +- ``automata.symbol.graph.SymbolGraph`` +- ``automata.symbol.parser.parse_symbol`` - ``automata.core.utils.filter_multi_digraph_by_symbols`` Example @@ -32,8 +32,8 @@ from the context, here is a conceptual example: .. code:: python - from automata.core.symbol.graph import GraphBuilder - from automata.core.symbol.scip_pb2 import Index # Some test index + from automata.symbol.graph import GraphBuilder + from automata.symbol.scip_pb2 import Index # Some test index index = Index() # Object of type Index builder = GraphBuilder(index, build_caller_relationships=True) diff --git a/docs/core/symbol/graph_processor.rst b/docs/core/symbol/graph_processor.rst index fc1d2cbb..f8c40dd6 100644 --- a/docs/core/symbol/graph_processor.rst +++ b/docs/core/symbol/graph_processor.rst @@ -21,10 +21,10 @@ The ``GraphProcessor`` provides the following method: Related Symbols --------------- -- ``automata.core.symbol.graph.SymbolGraph`` -- ``automata.core.symbol.graph._CallerCalleeProcessor`` -- ``automata.core.symbol.graph._ReferenceProcessor`` -- ``automata.core.symbol.graph.GraphBuilder`` +- ``automata.symbol.graph.SymbolGraph`` +- ``automata.symbol.graph._CallerCalleeProcessor`` +- ``automata.symbol.graph._ReferenceProcessor`` +- ``automata.symbol.graph.GraphBuilder`` These classes interact with ``GraphProcessor`` in different ways. The ``SymbolGraph`` class represents a graph of symbols and their @@ -42,7 +42,7 @@ example could be: .. code:: python from networkx import MultiDiGraph - from automata.core.symbol.graph._ReferenceProcessor import ReferenceProcessor + from automata.symbol.graph._ReferenceProcessor import ReferenceProcessor graph = MultiDiGraph() graph_processor = ReferenceProcessor(graph, document) diff --git a/docs/core/symbol/i_symbol_provider.rst b/docs/core/symbol/i_symbol_provider.rst index b03efe97..3a059093 100644 --- a/docs/core/symbol/i_symbol_provider.rst +++ b/docs/core/symbol/i_symbol_provider.rst @@ -44,7 +44,7 @@ Some symbolic classes and methods that are related to - ``automata.tests.unit.test_symbol_graph.test_get_all_symbols`` - ``automata.tests.unit.test_symbol_graph.test_build_real_graph`` -- ``automata.core.context_providers.symbol_synchronization.SymbolProviderRegistry`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderRegistry`` - ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` Example diff --git a/docs/core/symbol/index.rst b/docs/core/symbol/index.rst index df853196..d3e9ef05 100644 --- a/docs/core/symbol/index.rst +++ b/docs/core/symbol/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/symbol/symbol.rst b/docs/core/symbol/symbol.rst index 111342f5..fc11a793 100644 --- a/docs/core/symbol/symbol.rst +++ b/docs/core/symbol/symbol.rst @@ -44,14 +44,14 @@ Here is an example of how you can use the ``Symbol`` class: .. code:: python - from automata.core.experimental.search.symbol_parser import parse_symbol + from automata.experimental.search.symbol_parser import parse_symbol symbol_class = parse_symbol( - "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.agent.agent_enums`/ActionIndicator#" + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#" ) symbol_method = parse_symbol( - "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.tools.base`/ToolNotFoundError#__init__()." + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.tools.base`/ToolNotFoundError#__init__()." ) Related Symbols @@ -61,9 +61,9 @@ The following are the related symbols: - ``automata.tests.unit.test_database_vector.test_lookup_symbol`` - ``automata.tests.unit.test_symbol_parser.test_parse_symbol`` -- ``automata.core.symbol_embedding.base.SymbolEmbedding.symbol`` +- ``automata.symbol_embedding.base.SymbolEmbedding.symbol`` - ``automata.tests.unit.test_database_vector.test_delete_symbol`` -- ``automata.core.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` - ``automata.tests.unit.test_symbol_parser.test_is_local_symbol`` Limitations @@ -76,7 +76,7 @@ especially when dealing with special characters. Dependencies ------------ -- ``automata.core.symbol.parser.parse_symbol``: This parses a +- ``automata.symbol.parser.parse_symbol``: This parses a ``Symbol`` given a URI. Follow-up Questions: diff --git a/docs/core/symbol/symbol_descriptor.rst b/docs/core/symbol/symbol_descriptor.rst index a7186137..d9471cf2 100644 --- a/docs/core/symbol/symbol_descriptor.rst +++ b/docs/core/symbol/symbol_descriptor.rst @@ -16,14 +16,14 @@ Related Symbols - ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` - ``automata.tests.unit.test_symbol_parser.test_parse_symbol`` -- ``automata.core.symbol.base.Symbol`` +- ``automata.symbol.base.Symbol`` - ``automata.tests.unit.test_symbol_search_tool.test_symbol_references`` - ``automata.tests.regression.test_symbol_searcher_regression.get_top_n_results_desc_name`` -- ``automata.core.symbol.parser._SymbolParser.parse_descriptors`` +- ``automata.symbol.parser._SymbolParser.parse_descriptors`` - ``automata.tests.unit.test_symbol_search_tool.test_init`` -- ``automata.core.symbol.base.Symbol.__repr__`` +- ``automata.symbol.base.Symbol.__repr__`` - ``automata.tests.unit.test_symbol_search.test_symbol_references`` -- ``automata.core.symbol.parser.new_local_symbol`` +- ``automata.symbol.parser.new_local_symbol`` Example ------- @@ -32,8 +32,8 @@ Here is an example of ``SymbolDescriptor`` utilization: .. code:: python - from automata.core.symbol.base import SymbolDescriptor - from automata.core.symbol.scip_pb2 import Descriptor as DescriptorProto + from automata.symbol.base import SymbolDescriptor + from automata.symbol.scip_pb2 import Descriptor as DescriptorProto symbol_descriptor = SymbolDescriptor('name', DescriptorProto.Type, 'disambiguator') assert str(symbol_descriptor) == "Descriptor(name, Type, disambiguator)" diff --git a/docs/core/symbol/symbol_graph.rst b/docs/core/symbol/symbol_graph.rst index 20ddb952..5bc2383f 100644 --- a/docs/core/symbol/symbol_graph.rst +++ b/docs/core/symbol/symbol_graph.rst @@ -22,8 +22,8 @@ Related Symbols - ``automata.tests.unit.test_symbol_graph.test_build_real_graph`` - ``automata.tests.unit.test_symbol_graph.test_build_real_graph_and_subgraph`` -- ``automata.core.symbol.base.Symbol`` -- ``automata.core.singletons.dependency_factory.DependencyFactory.create_symbol_graph`` +- ``automata.symbol.base.Symbol`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_symbol_graph`` Methods ------- diff --git a/docs/core/symbol/symbol_package.rst b/docs/core/symbol/symbol_package.rst index 6cc76564..6c98414a 100644 --- a/docs/core/symbol/symbol_package.rst +++ b/docs/core/symbol/symbol_package.rst @@ -15,24 +15,24 @@ Import Statement .. code:: python - from automata.core.symbol.base import SymbolPackage + from automata.symbol.base import SymbolPackage Related Symbols --------------- -- ``automata.core.symbol.scip_pb2.Descriptor as DescriptorProto`` -- ``automata.core.symbol.parser.parse_symbol`` +- ``automata.symbol.scip_pb2.Descriptor as DescriptorProto`` +- ``automata.symbol.parser.parse_symbol`` - ``automata.core.utils.is_sorted`` -- ``automata.core.symbol.base.Symbol`` +- ``automata.symbol.base.Symbol`` - ``automata.tests.unit.test_symbol_parser.test_parse_symbol`` - ``automata.tests.unit.sample_modules.sample.EmptyClass`` - ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` - ``automata.tests.unit.test_symbol_search.test_retrieve_source_code_by_symbol`` -- ``automata.core.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` - ``automata.tests.unit.test_symbol_search.test_exact_search`` -- ``automata.core.symbol.base.Symbol.__repr__`` +- ``automata.symbol.base.Symbol.__repr__`` - ``automata.tests.unit.sample_modules.sample.OuterClass`` -- ``automata.core.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext`` Example ------- @@ -42,10 +42,10 @@ The following is an example demonstrating how to generate .. code:: python - from automata.core.symbol.parser import parse_symbol + from automata.symbol.parser import parse_symbol symbol_class = parse_symbol( - "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.agent.agent_enums`/ActionIndicator#" + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#" ) print(f"Package: {symbol_class.package}") diff --git a/docs/core/symbol/symbol_reference.rst b/docs/core/symbol/symbol_reference.rst index dc392705..3cb458c3 100644 --- a/docs/core/symbol/symbol_reference.rst +++ b/docs/core/symbol/symbol_reference.rst @@ -1,7 +1,7 @@ SymbolReference =============== -``SymbolReference`` is a class in the ``automata.core.symbol.base`` +``SymbolReference`` is a class in the ``automata.symbol.base`` module that represents a reference to a symbol in a file. It is particularly useful in complex code structures where the same symbol can be used in different parts of the code, and these references need to be @@ -39,9 +39,9 @@ location. Related Symbols --------------- -- ``automata.core.symbol.base.Symbol`` -- ``automata.core.symbol.graph.SymbolGraph`` -- ``automata.core.symbol.parser.parse_symbol`` +- ``automata.symbol.base.Symbol`` +- ``automata.symbol.graph.SymbolGraph`` +- ``automata.symbol.parser.parse_symbol`` - ``automata.tests.unit.test_symbol_search.test_symbol_references`` - ``automata.tests.unit.test_symbol_search_tool.test_symbol_references`` @@ -53,10 +53,10 @@ The following is an example demonstrating how to create an instance of .. code:: python - from automata.core.symbol.base import Symbol, SymbolReference - from automata.core.symbol.parser import parse_symbol + from automata.symbol.base import Symbol, SymbolReference + from automata.symbol.parser import parse_symbol - symbol_uri = "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.agent.agent_enums`/ActionIndicator#" + symbol_uri = "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#" symbol = parse_symbol(symbol_uri) symbol_ref_1 = SymbolReference(symbol=symbol, line_number=10, column_number=20) diff --git a/docs/core/symbol_embedding/index.rst b/docs/core/symbol_embedding/index.rst index b710df3f..70f0aa5a 100644 --- a/docs/core/symbol_embedding/index.rst +++ b/docs/core/symbol_embedding/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/symbol_embedding/json_symbol_embedding_vector_database.rst b/docs/core/symbol_embedding/json_symbol_embedding_vector_database.rst index f3fb505d..9c903926 100644 --- a/docs/core/symbol_embedding/json_symbol_embedding_vector_database.rst +++ b/docs/core/symbol_embedding/json_symbol_embedding_vector_database.rst @@ -2,7 +2,7 @@ JSONSymbolEmbeddingVectorDatabase ================================= ``JSONSymbolEmbeddingVectorDatabase`` is a concrete class under -``automata.core.symbol_embedding.base`` module used to map symbols to +``automata.symbol_embedding.base`` module used to map symbols to their vector representation in a JSON file. This class is an extension of the ``automata.core.base.database.vector.JSONVectorDatabase`` class, it provides similar functionality with additional methods to handle @@ -15,10 +15,10 @@ embeddings in a JSON file. Related Symbols --------------- -- ``automata.core.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` - ``automata.core.base.database.vector.JSONVectorDatabase`` -- ``automata.core.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` -- ``automata.core.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` Overview -------- @@ -45,7 +45,7 @@ Below are example usages extracted mainly from the unit test functions: .. code:: python - from automata.core.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase vector_database = JSONSymbolEmbeddingVectorDatabase("path_to_your_json_file") @@ -53,8 +53,8 @@ Below are example usages extracted mainly from the unit test functions: .. code:: python - from automata.core.symbol_embedding.base import SymbolCodeEmbedding - from automata.core.symbol.base import Symbol + from automata.symbol_embedding.base import SymbolCodeEmbedding + from automata.symbol.base import Symbol symbol1 = Symbol("symbol_1") symbol2 = Symbol("symbol_2") diff --git a/docs/core/symbol_embedding/symbol_code_embedding.rst b/docs/core/symbol_embedding/symbol_code_embedding.rst index 138e0af0..d382271a 100644 --- a/docs/core/symbol_embedding/symbol_code_embedding.rst +++ b/docs/core/symbol_embedding/symbol_code_embedding.rst @@ -3,7 +3,7 @@ SymbolCodeEmbedding ``SymbolCodeEmbedding`` is a concrete class used for creating embeddings for source code symbols. It is part of the -``automata.core.symbol_embedding.base`` package. +``automata.symbol_embedding.base`` package. Overview -------- @@ -17,14 +17,14 @@ string representation of the object. Related Symbols --------------- -- ``automata.core.symbol_embedding.builders.SymbolCodeEmbeddingBuilder``: +- ``automata.symbol_embedding.builders.SymbolCodeEmbeddingBuilder``: A class that builds ``Symbol`` source code embeddings. -- ``automata.core.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler``: +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler``: Handles a database for ``Symbol`` source code embeddings. - ``automata.core.base.database.vector.JSONVectorDatabase``: A class that provides the database for storing and retrieving the vector embeddings. -- ``automata.core.symbol.base.Symbol``: A class which contains +- ``automata.symbol.base.Symbol``: A class which contains associated logic for a Symbol. Example @@ -36,8 +36,8 @@ need a numpy array for the vector representation. Below is an example: .. code:: python - from automata.core.symbol.base import Symbol - from automata.core.symbol_embedding.base import SymbolCodeEmbedding + from automata.symbol.base import Symbol + from automata.symbol_embedding.base import SymbolCodeEmbedding import numpy as np symbol = Symbol("URIsymbol") diff --git a/docs/core/symbol_embedding/symbol_code_embedding_builder.rst b/docs/core/symbol_embedding/symbol_code_embedding_builder.rst index 94e4060e..05a5eca2 100644 --- a/docs/core/symbol_embedding/symbol_code_embedding_builder.rst +++ b/docs/core/symbol_embedding/symbol_code_embedding_builder.rst @@ -29,14 +29,14 @@ symbol, and the embedding vector to build a ``SymbolCodeEmbedding``. Related Symbols --------------- -- ``automata.core.embedding.base.EmbeddingBuilder``: An abstract class +- ``automata.embedding.base.EmbeddingBuilder``: An abstract class to build embeddings, from which ``SymbolCodeEmbeddingBuilder`` inherits. -- ``automata.core.embedding.base.EmbeddingVectorProvider``: An abstract +- ``automata.embedding.base.EmbeddingVectorProvider``: An abstract class that provides a standard API for creating embedding vectors. -- ``automata.core.symbol_embedding.base.SymbolCodeEmbedding``: A class +- ``automata.symbol_embedding.base.SymbolCodeEmbedding``: A class for symbol code embeddings. -- ``automata.core.symbol.base.Symbol``: A class which contains the +- ``automata.symbol.base.Symbol``: A class which contains the associated logic for a Symbol. Example @@ -48,9 +48,9 @@ This is an example demonstrating how to create an instance of .. code:: python # Required imports - from automata.core.symbol_embedding.builders import SymbolCodeEmbeddingBuilder - from automata.core.symbol.base import Symbol - from automata.core.embedding.base import EmbeddingVectorProvider + from automata.symbol_embedding.builders import SymbolCodeEmbeddingBuilder + from automata.symbol.base import Symbol + from automata.embedding.base import EmbeddingVectorProvider # Instantiate embedding vector provider embedding_provider = EmbeddingVectorProvider() # Replace with specific instance of embedding vector provider. diff --git a/docs/core/symbol_embedding/symbol_doc_embedding.rst b/docs/core/symbol_embedding/symbol_doc_embedding.rst index 3cefcb6a..2cddcdce 100644 --- a/docs/core/symbol_embedding/symbol_doc_embedding.rst +++ b/docs/core/symbol_embedding/symbol_doc_embedding.rst @@ -21,11 +21,11 @@ Related Symbols - ``automata.tests.unit.sample_modules.sample.OuterClass.InnerClass`` - ``automata.tests.unit.sample_modules.sample.OuterClass`` - ``automata.tests.unit.sample_modules.sample.OuterClass.InnerClass.inner_method`` -- ``automata.core.symbol_embedding.builders.SymbolDocEmbeddingBuilder`` +- ``automata.symbol_embedding.builders.SymbolDocEmbeddingBuilder`` - ``automata.tests.unit.test_py_reader.test_get_docstring_nested_class_method`` -- ``automata.core.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler.get_embedding`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler.get_embedding`` - ``automata.tests.unit.test_py_reader.test_get_docstring_nested_class`` -- ``automata.core.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` - ``automata.tests.unit.test_py_reader.test_get_docstring_no_docstring_class`` Example @@ -36,8 +36,8 @@ The following is an example demonstrating how to create an instance of .. code:: python - from automata.core.symbol_embedding.base import SymbolDocEmbedding - from automata.core.symbol.base import Symbol + from automata.symbol_embedding.base import SymbolDocEmbedding + from automata.symbol.base import Symbol import numpy as np symbol = Symbol.from_string('scip-python python automata') @@ -63,8 +63,8 @@ Dependencies ~~~~~~~~~~~~ This class relies on the -``automata.core.symbol_embedding.base.SymbolEmbedding`` and -``automata.core.symbol.base.Symbol`` classes. +``automata.symbol_embedding.base.SymbolEmbedding`` and +``automata.symbol.base.Symbol`` classes. Follow-up Questions: -------------------- diff --git a/docs/core/symbol_embedding/symbol_doc_embedding_builder.rst b/docs/core/symbol_embedding/symbol_doc_embedding_builder.rst index abba9f19..bfede487 100644 --- a/docs/core/symbol_embedding/symbol_doc_embedding_builder.rst +++ b/docs/core/symbol_embedding/symbol_doc_embedding_builder.rst @@ -3,7 +3,7 @@ SymbolDocEmbeddingBuilder ``SymbolDocEmbeddingBuilder`` is a class that creates documentation embeddings for a given ``Symbol``. This class exists in the -``automata.core.symbol_embedding.builders`` package. It is crucial in +``automata.symbol_embedding.builders`` package. It is crucial in understanding and building the context surrounding primary symbols in the code. @@ -21,12 +21,12 @@ other classes such as ``EmbeddingVectorProvider``, Related Symbols --------------- -- ``automata.core.embedding.base.EmbeddingBuilder`` -- ``automata.core.embedding.base.EmbeddingVectorProvider`` -- ``automata.core.retrievers.py.context.PyContextRetriever`` -- ``automata.core.llm.foundation.LLMChatCompletionProvider`` -- ``automata.core.experimental.search.symbol_search.SymbolSearch`` -- ``automata.core.symbol_embedding.base.SymbolDocEmbedding`` +- ``automata.embedding.base.EmbeddingBuilder`` +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.retrievers.py.context.PyContextRetriever`` +- ``automata.llm.foundation.LLMChatCompletionProvider`` +- ``automata.experimental.search.symbol_search.SymbolSearch`` +- ``automata.symbol_embedding.base.SymbolDocEmbedding`` Examples -------- @@ -37,11 +37,11 @@ embeddings for a symbol. .. code:: python - from automata.core.symbol_embedding.builders import SymbolDocEmbeddingBuilder - from automata.core.embedding.base.EmbeddingVectorProvider import MyEmbeddingVectorProvider - from automata.core.llm.foundation import MyLLMChatCompletionProvider - from automata.core.experimental.search.symbol_search import MySymbolSearch - from automata.core.retrievers.py.context import PyContextRetriever + from automata.symbol_embedding.builders import SymbolDocEmbeddingBuilder + from automata.embedding.base.EmbeddingVectorProvider import MyEmbeddingVectorProvider + from automata.llm.foundation import MyLLMChatCompletionProvider + from automata.experimental.search.symbol_search import MySymbolSearch + from automata.retrievers.py.context import PyContextRetriever embedding_provider = MyEmbeddingVectorProvider(...) completion_provider = MyLLMChatCompletionProvider(...) diff --git a/docs/core/symbol_embedding/symbol_embedding.rst b/docs/core/symbol_embedding/symbol_embedding.rst index d91f6cea..c6f9dd8d 100644 --- a/docs/core/symbol_embedding/symbol_embedding.rst +++ b/docs/core/symbol_embedding/symbol_embedding.rst @@ -45,7 +45,7 @@ abstract class, it can’t be instantiated directly. .. code:: python - from automata.core.symbol_embedding.base import SymbolEmbedding, Symbol + from automata.symbol_embedding.base import SymbolEmbedding, Symbol import numpy as np class SymbolCodeEmbedding(SymbolEmbedding): @@ -59,7 +59,7 @@ Create an instance of ``SymbolCodeEmbedding``: .. code:: python - from automata.core.symbol.base import Symbol + from automata.symbol.base import Symbol symbol = Symbol.from_string("Sample symbol string") vector = np.array([1, 0, 0, 0]) embedding_instance = SymbolCodeEmbedding(symbol, "source code", vector) diff --git a/docs/core/tasks/automata_agent_task_database.rst b/docs/core/tasks/automata_agent_task_database.rst index 72f57702..0b62b4c0 100644 --- a/docs/core/tasks/automata_agent_task_database.rst +++ b/docs/core/tasks/automata_agent_task_database.rst @@ -18,13 +18,13 @@ Related Symbols - ``automata.tests.unit.test_task_database.db`` - ``automata.tests.conftest.task`` -- ``automata.core.tasks.agent_database.AutomataTaskRegistry.__init__`` +- ``automata.tasks.agent_database.AutomataTaskRegistry.__init__`` - ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` -- ``automata.core.tasks.agent_database.AutomataTaskRegistry`` +- ``automata.tasks.agent_database.AutomataTaskRegistry`` - ``automata.tests.unit.test_task.test_deterministic_task_id`` -- ``automata.core.memory_store.agent_conversation_database.AgentConversationDatabase`` +- ``automata.memory_store.agent_conversation_database.AgentConversationDatabase`` - ``automata.tests.unit.test_task_database.task`` -- ``automata.core.tasks.tasks.AutomataTask`` +- ``automata.tasks.tasks.AutomataTask`` - ``automata.tests.unit.test_conversation_database.db`` Method Details @@ -70,8 +70,8 @@ usage: .. code:: python - from automata.core.tasks.agent_database import AutomataAgentTaskDatabase - from automata.core.tasks.tasks import AutomataTask + from automata.tasks.agent_database import AutomataAgentTaskDatabase + from automata.tasks.tasks import AutomataTask # Instantiate AutomataTask task = AutomataTask( diff --git a/docs/core/tasks/automata_task.rst b/docs/core/tasks/automata_task.rst index c855659c..cdbc968f 100644 --- a/docs/core/tasks/automata_task.rst +++ b/docs/core/tasks/automata_task.rst @@ -12,15 +12,15 @@ Overview properties and validating its instructions. It also manages the logging for the task by creating a log file in the task directory and fetches log content. The class utilizes parent class ``Task`` from -``automata.core.tasks.base`` to handle the underlying procedures. +``automata.tasks.base`` to handle the underlying procedures. Related Symbols --------------- -- ``automata.core.tasks.environment.AutomataTaskEnvironment`` -- ``automata.core.tasks.agent_database.AutomataTaskRegistry.get_all_tasks`` -- ``automata.core.tasks.agent_database.AutomataAgentTaskDatabase.insert_task`` -- ``automata.core.tasks.executor.IAutomataTaskExecution`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tasks.agent_database.AutomataTaskRegistry.get_all_tasks`` +- ``automata.tasks.agent_database.AutomataAgentTaskDatabase.insert_task`` +- ``automata.tasks.executor.IAutomataTaskExecution`` Example ------- @@ -29,13 +29,13 @@ Examples on how to create instances of ``AutomataTask``: .. code:: python - from automata.core.tasks.tasks import AutomataTask + from automata.tasks.tasks import AutomataTask task = AutomataTask("task1", instructions="instruction1") .. code:: python - from automata.core.tasks.tasks import AutomataTask + from automata.tasks.tasks import AutomataTask from tests.mocks import MockRepositoryClient from config.config_enums import AgentConfigName diff --git a/docs/core/tasks/automata_task_environment.rst b/docs/core/tasks/automata_task_environment.rst index e4953231..2b507e3c 100644 --- a/docs/core/tasks/automata_task_environment.rst +++ b/docs/core/tasks/automata_task_environment.rst @@ -21,13 +21,13 @@ Related Symbols - ``automata.tests.conftest.environment`` - ``automata.tests.unit.test_task_database.task`` -- ``automata.core.tasks.tasks.AutomataTask`` +- ``automata.tasks.tasks.AutomataTask`` - ``automata.tests.conftest.task`` -- ``automata.core.tasks.base.TaskEnvironment`` +- ``automata.tasks.base.TaskEnvironment`` - ``automata.tests.unit.test_task_executor.test_execute_automata_task_success`` -- ``automata.core.tasks.executor.IAutomataTaskExecution`` +- ``automata.tasks.executor.IAutomataTaskExecution`` - ``automata.tests.unit.test_task_executor.test_execute_automata_task_fail`` -- ``automata.core.agent.providers.OpenAIAutomataAgent`` +- ``automata.agent.providers.OpenAIAutomataAgent`` - ``automata.tests.unit.test_task.test_callback`` Example @@ -38,9 +38,9 @@ commit ``AutomataTask``: .. code:: python - from automata.core.github_management.client import GitHubClient - from automata.core.tasks.environment import AutomataTaskEnvironment - from automata.core.tasks.tasks import AutomataTask + from automata.github_management.client import GitHubClient + from automata.tasks.environment import AutomataTaskEnvironment + from automata.tasks.tasks import AutomataTask github_manager = GitHubClient(access_token = "your_access_token_here", remote_name = "your_remote_name_here", primary_branch = "main") task_env = AutomataTaskEnvironment(github_manager) diff --git a/docs/core/tasks/automata_task_executor.rst b/docs/core/tasks/automata_task_executor.rst index 30f46b2e..bd92883e 100644 --- a/docs/core/tasks/automata_task_executor.rst +++ b/docs/core/tasks/automata_task_executor.rst @@ -36,8 +36,8 @@ The following is an example demonstrating how to use .. code:: python - from automata.core.tasks.executor import AutomataTaskExecutor - from automata.core.tasks.tasks import AutomataTask + from automata.tasks.executor import AutomataTaskExecutor + from automata.tasks.tasks import AutomataTask from automata.tests.unit.test_task_executor import TestExecuteBehavior # Create an AutomataTask instance diff --git a/docs/core/tasks/automata_task_registry.rst b/docs/core/tasks/automata_task_registry.rst index e09ba799..d89305b7 100644 --- a/docs/core/tasks/automata_task_registry.rst +++ b/docs/core/tasks/automata_task_registry.rst @@ -25,7 +25,7 @@ Example .. code:: python - from automata.core.tasks.agent_database import AutomataTaskRegistry + from automata.tasks.agent_database import AutomataTaskRegistry from automata.tests.unit.test_task_database import task # Creating a task diff --git a/docs/core/tasks/i_automata_task_execution.rst b/docs/core/tasks/i_automata_task_execution.rst index 265ab684..c7f754cb 100644 --- a/docs/core/tasks/i_automata_task_execution.rst +++ b/docs/core/tasks/i_automata_task_execution.rst @@ -39,8 +39,8 @@ Usage Example .. code:: python - from automata.core.tasks.executor import IAutomataTaskExecution - from automata.core.tasks.tasks import AutomataTask + from automata.tasks.executor import IAutomataTaskExecution + from automata.tasks.tasks import AutomataTask # Construct an Automata Task task = AutomataTask(name="custom_task", instructions="execute something") diff --git a/docs/core/tasks/i_task_execution.rst b/docs/core/tasks/i_task_execution.rst index 2e268cf4..caa7f18a 100644 --- a/docs/core/tasks/i_task_execution.rst +++ b/docs/core/tasks/i_task_execution.rst @@ -2,7 +2,7 @@ ITaskExecution ============== ``ITaskExecution`` is an interface specifying the behavior for task -execution in the ``automata.core.tasks`` module. It provides an abstract +execution in the ``automata.tasks`` module. It provides an abstract method ``execute`` which defines how a task object should be executed. Overview @@ -18,10 +18,10 @@ Related Symbols --------------- - ``automata.tests.unit.test_task_executor.TestExecuteBehavior`` -- ``automata.core.tasks.executor.AutomataTaskExecutor`` -- ``automata.core.tasks.executor.IAutomataTaskExecution`` -- ``automata.core.tasks.base.Task`` -- ``automata.core.tasks.base.TaskStatus`` +- ``automata.tasks.executor.AutomataTaskExecutor`` +- ``automata.tasks.executor.IAutomataTaskExecution`` +- ``automata.tasks.base.Task`` +- ``automata.tasks.base.TaskStatus`` Example ------- @@ -32,7 +32,7 @@ implementation of the ``execute`` method. .. code:: python - from automata.core.tasks.base import ITaskExecution, Task + from automata.tasks.base import ITaskExecution, Task class TestExecuteBehavior(ITaskExecution): """ diff --git a/docs/core/tasks/index.rst b/docs/core/tasks/index.rst index 236b1331..d01bb98b 100644 --- a/docs/core/tasks/index.rst +++ b/docs/core/tasks/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/tasks/task.rst b/docs/core/tasks/task.rst index 636eb02c..b71d3394 100644 --- a/docs/core/tasks/task.rst +++ b/docs/core/tasks/task.rst @@ -27,13 +27,13 @@ Related Symbols - ``automata.tests.unit.test_task_database.task`` - ``automata.tests.unit.test_task_environment.test_commit_task`` -- ``automata.core.tasks.tasks.AutomataTask`` +- ``automata.tasks.tasks.AutomataTask`` - ``automata.tests.unit.test_task_database.test_get_tasks_by_query`` -- ``automata.core.tasks.base.ITaskExecution.execute`` +- ``automata.tasks.base.ITaskExecution.execute`` - ``automata.tests.unit.test_task_database.test_update_task`` - ``automata.tests.unit.test_task_database.test_database_lifecycle`` - ``automata.tests.unit.test_task_database.test_insert_task`` -- ``automata.core.tasks.base.ITaskExecution`` +- ``automata.tasks.base.ITaskExecution`` - ``automata.tests.conftest.registry`` Usage Example @@ -41,7 +41,7 @@ Usage Example .. code:: python - from automata.core.tasks.base import Task + from automata.tasks.base import Task task = Task(priority=1, max_retries=5) print(f"ID of the created task: {task.task_id}") diff --git a/docs/core/tasks/task_environment.rst b/docs/core/tasks/task_environment.rst index ca7a25eb..870bc6bb 100644 --- a/docs/core/tasks/task_environment.rst +++ b/docs/core/tasks/task_environment.rst @@ -15,13 +15,13 @@ Related Symbols - ``automata.tests.conftest.environment`` - ``automata.tests.unit.test_task_environment.test_commit_task`` -- ``automata.core.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` - ``automata.tests.conftest.task`` - ``automata.tests.unit.test_task_database.db`` -- ``automata.core.tasks.environment.AutomataTaskEnvironment.teardown`` +- ``automata.tasks.environment.AutomataTaskEnvironment.teardown`` - ``automata.tests.unit.test_task_executor.test_execute_automata_task_success`` - ``automata.tests.unit.test_task_executor.test_execute_automata_task_fail`` -- ``automata.core.tasks.base.Task`` +- ``automata.tasks.base.Task`` Example ------- @@ -31,7 +31,7 @@ implements its abstract methods: .. code:: python - from automata.core.tasks.base import TaskEnvironment + from automata.tasks.base import TaskEnvironment class MyEnvironment(TaskEnvironment): diff --git a/docs/core/tasks/task_status.rst b/docs/core/tasks/task_status.rst index 4885de6b..c75b35ba 100644 --- a/docs/core/tasks/task_status.rst +++ b/docs/core/tasks/task_status.rst @@ -22,11 +22,11 @@ Related Symbols - ``automata.tests.unit.test_task.test_status_setter`` - ``automata.tests.unit.test_task.test_task_inital_state`` -- ``automata.core.tasks.base.Task.status`` +- ``automata.tasks.base.Task.status`` - ``automata.tests.unit.test_task_database.test_update_task`` -- ``automata.core.tasks.base.Task`` +- ``automata.tasks.base.Task`` - ``automata.tests.unit.test_task_database.test_database_lifecycle`` -- ``automata.core.tasks.tasks.AutomataTask`` +- ``automata.tasks.tasks.AutomataTask`` - ``automata.tests.unit.test_task.test_register_task`` Example @@ -37,8 +37,8 @@ status of a ``Task``. .. code:: python - from automata.core.tasks.base import Task - from automata.core.tasks.base import TaskStatus + from automata.tasks.base import Task + from automata.tasks.base import TaskStatus task = Task("Task1", "", priority=1) print(task.status) # Should print: TaskStatus.CREATED diff --git a/docs/core/tools/agent_tool_factory.rst b/docs/core/tools/agent_tool_factory.rst index a1cad8bd..8a63cb31 100644 --- a/docs/core/tools/agent_tool_factory.rst +++ b/docs/core/tools/agent_tool_factory.rst @@ -31,7 +31,7 @@ Related Symbols - ``automata.tests.unit.test_tool.test_tool`` - ``automata.tests.unit.test_tool.test_tool_instantiation`` -- ``automata.core.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry.register_tool_manager`` +- ``automata.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry.register_tool_manager`` - ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder`` Usage Example @@ -39,8 +39,8 @@ Usage Example .. code:: python - from automata.core.tools.factory import AgentToolFactory - from automata.core.agent.agent import AgentToolkitNames + from automata.tools.factory import AgentToolFactory + from automata.agent.agent import AgentToolkitNames toolkit_list = ["tool_name1", "tool_name2"] tools = AgentToolFactory.build_tools(toolkit_list) diff --git a/docs/core/tools/base/config.rst b/docs/core/tools/base/config.rst index b163a462..0d26791d 100644 --- a/docs/core/tools/base/config.rst +++ b/docs/core/tools/base/config.rst @@ -19,15 +19,15 @@ Related Symbols a test tool for testing purposes. - ``automata.tests.unit.test_tool.TestTool``: A subclass of ``Tool`` used for testing purposes. -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder.can_handle``: +- ``automata.agent.providers.OpenAIAgentToolkitBuilder.can_handle``: A method that checks if a tool can be handled. - ``automata.tests.unit.test_tool.test_tool_run``: A function that tests the ``run`` method of a tool. -- ``automata.core.llm.providers.openai.OpenAITool``: A subclass of +- ``automata.llm.providers.openai.OpenAITool``: A subclass of ``Tool`` that is designed for use by the OpenAI agent. -- ``automata.core.agent.agent.AgentToolkitBuilder.build``: A method +- ``automata.agent.agent.AgentToolkitBuilder.build``: A method that builds a list of tools. -- ``automata.core.tools.builders.symbol_search.SymbolSearchToolkitBuilder.build``: +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder.build``: A method that builds a list of symbol search toolkits. Example diff --git a/docs/core/tools/base/index.rst b/docs/core/tools/base/index.rst index ccbd6738..26413653 100644 --- a/docs/core/tools/base/index.rst +++ b/docs/core/tools/base/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/tools/builders/context_oracle_open_ai_toolkit_builder.rst b/docs/core/tools/builders/context_oracle_open_ai_toolkit_builder.rst index 5fc3862b..48d9d5c1 100644 --- a/docs/core/tools/builders/context_oracle_open_ai_toolkit_builder.rst +++ b/docs/core/tools/builders/context_oracle_open_ai_toolkit_builder.rst @@ -15,14 +15,14 @@ Import Statements import textwrap from typing import List from automata.config.base import LLMProvider - from automata.core.agent.agent import AgentToolkitBuilder, AgentToolkitNames - from automata.core.agent.providers import OpenAIAgentToolkitBuilder - from automata.core.embedding.base import EmbeddingSimilarityCalculator - from automata.core.llm.providers.openai import OpenAITool - from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler - from automata.core.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler - from automata.core.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry - from automata.core.tools.base import Tool + from automata.agent.agent import AgentToolkitBuilder, AgentToolkitNames + from automata.agent.providers import OpenAIAgentToolkitBuilder + from automata.embedding.base import EmbeddingSimilarityCalculator + from automata.llm.providers.openai import OpenAITool + from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler + from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler + from automata.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry + from automata.tools.base import Tool Methods ------- @@ -63,10 +63,10 @@ Usage Example .. code:: python - from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler - from automata.core.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler - from automata.core.embedding.base import EmbeddingSimilarityCalculator - from automata.core.tools.builders.context_oracle import ContextOracleOpenAIToolkitBuilder + from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler + from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler + from automata.embedding.base import EmbeddingSimilarityCalculator + from automata.tools.builders.context_oracle import ContextOracleOpenAIToolkitBuilder symbol_doc_embedding_handler = SymbolDocEmbeddingHandler() symbol_code_embedding_handler = SymbolCodeEmbeddingHandler() @@ -86,13 +86,13 @@ Related Symbols - ``automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder`` - ``automata.tests.unit.test_context_oracle_tool.test_init`` -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder`` - ``automata.tests.unit.test_context_oracle_tool.test_build`` -- ``automata.core.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` - ``automata.tests.unit.test_py_reader_tool.python_retriever_tool_builder`` -- ``automata.core.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` +- ``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` - ``automata.tests.unit.test_symbol_search_tool.symbol_search_tool_builder`` -- ``automata.core.tools.builders.context_oracle.ContextOracleToolkitBuilder`` +- ``automata.tools.builders.context_oracle.ContextOracleToolkitBuilder`` - ``automata.tests.unit.test_automata_agent_builder.test_builder_accepts_all_fields`` Limitations diff --git a/docs/core/tools/builders/context_oracle_toolkit_builder.rst b/docs/core/tools/builders/context_oracle_toolkit_builder.rst index e03e333d..99fc6be9 100644 --- a/docs/core/tools/builders/context_oracle_toolkit_builder.rst +++ b/docs/core/tools/builders/context_oracle_toolkit_builder.rst @@ -14,29 +14,29 @@ available symbols. Related Symbols --------------- -- ``automata.core.agent.agent.AgentToolkitBuilder`` +- ``automata.agent.agent.AgentToolkitBuilder`` - ``automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder`` - ``automata.tests.unit.test_context_oracle_tool.test_build`` - ``automata.tests.unit.test_context_oracle_tool.test_init`` -- ``automata.core.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` Dependencies ------------ -- ``automata.core.embedding.base.EmbeddingSimilarityCalculator`` -- ``automata.core.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` -- ``automata.core.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` -- ``automata.core.tools.base.Tool`` +- ``automata.embedding.base.EmbeddingSimilarityCalculator`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` +- ``automata.tools.base.Tool`` Example ------- .. code:: python - from automata.core.tools.builders.context_oracle import ContextOracleToolkitBuilder - from automata.core.embedding.base import EmbeddingSimilarityCalculator - from automata.core.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler - from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler + from automata.tools.builders.context_oracle import ContextOracleToolkitBuilder + from automata.embedding.base import EmbeddingSimilarityCalculator + from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler + from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler symbol_doc_embedding_handler = SymbolDocEmbeddingHandler() symbol_code_embedding_handler = SymbolCodeEmbeddingHandler() diff --git a/docs/core/tools/builders/index.rst b/docs/core/tools/builders/index.rst index 720c323f..d18f3bb9 100644 --- a/docs/core/tools/builders/index.rst +++ b/docs/core/tools/builders/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/tools/builders/py_reader_open_ai_toolkit.rst b/docs/core/tools/builders/py_reader_open_ai_toolkit.rst index 5982c446..4f5fb472 100644 --- a/docs/core/tools/builders/py_reader_open_ai_toolkit.rst +++ b/docs/core/tools/builders/py_reader_open_ai_toolkit.rst @@ -18,15 +18,15 @@ properties and requirements provided within the method. Related Symbols --------------- -- ``automata.core.code_handling.py.reader.PyReader`` -- ``automata.core.llm.providers.openai.OpenAITool`` -- ``automata.core.agent.agent.AgentToolkitBuilder`` -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.agent.agent.AgentToolkitBuilder`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder`` - ``automata.config.base.LLMProvider`` -- ``automata.core.tools.builders.py_reader.PyReaderToolkitBuilder.build`` -- ``automata.core.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry`` -- ``automata.core.agent.agent.AgentToolkitNames`` -- ``automata.core.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder.build_for_open_ai`` +- ``automata.tools.builders.py_reader.PyReaderToolkitBuilder.build`` +- ``automata.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry`` +- ``automata.agent.agent.AgentToolkitNames`` +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder.build_for_open_ai`` Example ------- @@ -39,8 +39,8 @@ scope of this document. .. code:: python from unittest.mock import MagicMock - from automata.core.code_handling.py.reader import PyReader - from automata.core.tools.builders.py_reader import PyReaderOpenAIToolkit + from automata.code_handling.py.reader import PyReader + from automata.tools.builders.py_reader import PyReaderOpenAIToolkit # Initialize a mock PyReader object py_reader = MagicMock(spec=PyReader) diff --git a/docs/core/tools/builders/py_reader_toolkit_builder.rst b/docs/core/tools/builders/py_reader_toolkit_builder.rst index ad1af50a..2a6ca9b1 100644 --- a/docs/core/tools/builders/py_reader_toolkit_builder.rst +++ b/docs/core/tools/builders/py_reader_toolkit_builder.rst @@ -20,18 +20,18 @@ descriptions. Related Symbols --------------- -- ``automata.core.tools.builders.py_reader.PyReaderOpenAIToolkit`` -- ``automata.core.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` -- ``automata.core.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` -- ``automata.core.tools.builders.py_writer.PyWriterToolkitBuilder`` -- ``automata.core.agent.agent.AgentToolkitBuilder`` +- ``automata.tools.builders.py_reader.PyReaderOpenAIToolkit`` +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder`` +- ``automata.agent.agent.AgentToolkitBuilder`` Dependencies ------------ -- ``automata.core.code_handling.py.reader.PyReader`` -- ``automata.core.tools.base.Tool`` -- ``automata.core.agent.agent.AgentToolkitBuilder`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.tools.base.Tool`` +- ``automata.agent.agent.AgentToolkitBuilder`` Usage Example ------------- @@ -42,8 +42,8 @@ tools related to the retrieval of Python code: .. code:: python - from automata.core.code_handling.py.reader import PyReader - from automata.core.tools.builders.py_reader import PyReaderToolkitBuilder + from automata.code_handling.py.reader import PyReader + from automata.tools.builders.py_reader import PyReaderToolkitBuilder # Instantiate the PyReader object python_code_retriever = PyReader() diff --git a/docs/core/tools/builders/py_writer_open_ai_toolkit_builder.rst b/docs/core/tools/builders/py_writer_open_ai_toolkit_builder.rst index f1d8ae73..31587ee1 100644 --- a/docs/core/tools/builders/py_writer_open_ai_toolkit_builder.rst +++ b/docs/core/tools/builders/py_writer_open_ai_toolkit_builder.rst @@ -20,9 +20,9 @@ builds are used by the OpenAI agent to modify python files. Related Symbols --------------- -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder``: The base +- ``automata.agent.providers.OpenAIAgentToolkitBuilder``: The base class this builder extends from. -- ``automata.core.llm.providers.openai.OpenAITool``: This class +- ``automata.llm.providers.openai.OpenAITool``: This class represents tools that ``PyWriterOpenAIToolkitBuilder`` builds. Example @@ -33,8 +33,8 @@ PyWriterOpenAIToolkitBuilder: .. code:: python - from automata.core.code_handling.py.writer import PyWriter - from automata.core.tools.builders.py_writer import PyWriterOpenAIToolkitBuilder + from automata.code_handling.py.writer import PyWriter + from automata.tools.builders.py_writer import PyWriterOpenAIToolkitBuilder py_writer = PyWriter() toolkit_builder = PyWriterOpenAIToolkitBuilder(py_writer) diff --git a/docs/core/tools/builders/py_writer_toolkit_builder.rst b/docs/core/tools/builders/py_writer_toolkit_builder.rst index 80de27d1..ae9898da 100644 --- a/docs/core/tools/builders/py_writer_toolkit_builder.rst +++ b/docs/core/tools/builders/py_writer_toolkit_builder.rst @@ -24,7 +24,7 @@ Its ``build`` method provides two functionalities: Related Symbols --------------- -- ``automata.core.tools.base.Tool``: The ``Tool`` class exposes a +- ``automata.tools.base.Tool``: The ``Tool`` class exposes a function or coroutine directly which is then used by ``PyWriterToolkitBuilder`` to implement its methods. @@ -32,11 +32,11 @@ Related Symbols This tests the ``PyWriterToolkitBuilder`` and asserts its instance type as ``Tool``. -- ``automata.core.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder``: +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder``: Provides similar method to ``build()`` in ``PyWriterToolkitBuilder`` to build Python toolkit for OpenAI. -- ``automata.core.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``: +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``: Builds toolkit for handling of context Oracle within OpenAI. Usage Example @@ -44,8 +44,8 @@ Usage Example .. code:: python - from automata.core.code_handling.py.writer import PyWriter - from automata.core.tools.builders.py_writer import PyWriterToolkitBuilder + from automata.code_handling.py.writer import PyWriter + from automata.tools.builders.py_writer import PyWriterToolkitBuilder py_writer = PyWriter(py_reader) py_toolkit_builder = PyWriterToolkitBuilder(py_writer=py_writer) diff --git a/docs/core/tools/builders/search_tool.rst b/docs/core/tools/builders/search_tool.rst index b6ddacce..66f8bacd 100644 --- a/docs/core/tools/builders/search_tool.rst +++ b/docs/core/tools/builders/search_tool.rst @@ -2,7 +2,7 @@ SearchTool ========== ``SearchTool`` is a class contained within the -``automata.core.tools.builders.symbol_search`` module. It is one of the +``automata.tools.builders.symbol_search`` module. It is one of the available tools for search operations, as its name implies. It is mainly used for building ``SymbolSearchToolkitBuilder`` objects. This class enables interaction with ``SymbolSearch`` API, which is capable of @@ -17,7 +17,7 @@ statements: .. code:: python from enum import Enum - from automata.core.tools.builders.symbol_search import SearchTool + from automata.tools.builders.symbol_search import SearchTool Overview -------- @@ -30,10 +30,10 @@ values - Related Symbols --------------- -- ``automata.core.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` -- ``automata.core.tools.base.Tool`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` +- ``automata.tools.base.Tool`` - ``automata.tests.unit.test_symbol_search_tool.symbol_search_tool_builder`` -- ``automata.core.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` +- ``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` - ``automata.tests.unit.test_tool.TestTool`` Example @@ -44,8 +44,8 @@ creating the ``SymbolSearchToolkitBuilder`` object – .. code:: python - from automata.core.tools.builders.symbol_search import SearchTool, SymbolSearchToolkitBuilder - from automata.core.experimental.search.symbol_search import SymbolSearch + from automata.tools.builders.symbol_search import SearchTool, SymbolSearchToolkitBuilder + from automata.experimental.search.symbol_search import SymbolSearch symbol_search = SymbolSearch(index="my_python_index") builder = SymbolSearchToolkitBuilder(symbol_search=symbol_search, search_tools=[SearchTool.EXACT, SearchTool.RANK]) diff --git a/docs/core/tools/builders/symbol_search_open_ai_toolkit_builder.rst b/docs/core/tools/builders/symbol_search_open_ai_toolkit_builder.rst index 206c8b76..af5e859a 100644 --- a/docs/core/tools/builders/symbol_search_open_ai_toolkit_builder.rst +++ b/docs/core/tools/builders/symbol_search_open_ai_toolkit_builder.rst @@ -20,13 +20,13 @@ Related Symbols - ``automata.tests.unit.test_symbol_search_tool.symbol_search_tool_builder`` - ``automata.tests.unit.test_symbol_search_tool.test_init`` -- ``automata.core.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` - ``automata.tests.unit.test_symbol_search_tool.test_build`` -- ``automata.core.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` - ``automata.tests.unit.test_symbol_search_tool.test_exact_search`` -- ``automata.core.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` - ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` -- ``automata.core.tools.builders.py_reader.PyReaderOpenAIToolkit`` +- ``automata.tools.builders.py_reader.PyReaderOpenAIToolkit`` - ``automata.tests.unit.test_symbol_search_tool.test_symbol_references`` Example @@ -37,8 +37,8 @@ The following example demonstrates how to build OpenAI tools using the .. code:: python - from automata.core.tools.builders.symbol_search import SymbolSearchOpenAIToolkitBuilder - from automata.core.experimental.search.symbol_search import SymbolSearch + from automata.tools.builders.symbol_search import SymbolSearchOpenAIToolkitBuilder + from automata.experimental.search.symbol_search import SymbolSearch symbol_search = SymbolSearch(index_name="your-index-name") builder = SymbolSearchOpenAIToolkitBuilder(symbol_search=symbol_search) @@ -63,10 +63,10 @@ Limitations Dependencies ------------ -- ``automata.core.llm.providers.openai.OpenAITool`` -- ``automata.core.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry`` -- ``automata.core.agent.agent.AgentToolkitNames`` -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder`` +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry`` +- ``automata.agent.agent.AgentToolkitNames`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder`` Follow-up Questions: -------------------- diff --git a/docs/core/tools/builders/symbol_search_toolkit_builder.rst b/docs/core/tools/builders/symbol_search_toolkit_builder.rst index 01b32f57..57bf85ea 100644 --- a/docs/core/tools/builders/symbol_search_toolkit_builder.rst +++ b/docs/core/tools/builders/symbol_search_toolkit_builder.rst @@ -38,8 +38,8 @@ snippet: .. code:: python # assuming symbolGraph and other dependencies are based on existing contextual data - from automata.core.experimental.search.symbol_search import SymbolSearch, SymbolSearchConfig - from automata.core.tools.builders.symbol_search import SymbolSearchToolkitBuilder, SearchTool + from automata.experimental.search.symbol_search import SymbolSearch, SymbolSearchConfig + from automata.tools.builders.symbol_search import SymbolSearchToolkitBuilder, SearchTool # Construct the Symbol Search symbol_search = SymbolSearch(symbolGraph, SymbolSearchConfig.default()) diff --git a/docs/core/tools/index.rst b/docs/core/tools/index.rst index d6860901..e8385398 100644 --- a/docs/core/tools/index.rst +++ b/docs/core/tools/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/core/tools/tool.rst b/docs/core/tools/tool.rst index 703809b3..842b071c 100644 --- a/docs/core/tools/tool.rst +++ b/docs/core/tools/tool.rst @@ -3,7 +3,7 @@ Tool ``Tool`` directly exposes a function or coroutine. It takes inputs in the form of dictionary in a run method. The ``Tool`` class is part of -the automata.core.tools.base module. +the automata.tools.base module. Overview -------- @@ -22,13 +22,13 @@ Related Symbols - ``automata.tests.unit.test_tool.test_tool`` - ``automata.tests.unit.test_tool.TestTool`` -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder.can_handle`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder.can_handle`` - ``automata.tests.unit.test_tool.test_tool_run`` -- ``automata.core.llm.providers.openai.OpenAITool`` +- ``automata.llm.providers.openai.OpenAITool`` - ``automata.tests.unit.test_tool.TestTool.run`` -- ``automata.core.agent.agent.AgentToolkitBuilder.build`` +- ``automata.agent.agent.AgentToolkitBuilder.build`` - ``automata.tests.unit.test_tool.test_tool_instantiation`` -- ``automata.core.tools.builders.symbol_search.SymbolSearchToolkitBuilder.build`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder.build`` - ``automata.tests.unit.test_symbol_search_tool.test_build`` Example @@ -39,7 +39,7 @@ and running it with an input. .. code:: python - from automata.core.tools.base import Tool + from automata.tools.base import Tool test_tool = Tool( name="TestTool", diff --git a/docs/embedding/embedding.rst b/docs/embedding/embedding.rst new file mode 100644 index 00000000..af968938 --- /dev/null +++ b/docs/embedding/embedding.rst @@ -0,0 +1,75 @@ +Embedding +========= + +Overview +-------- + +``Embedding`` is an abstract base class that lays the groundwork for +different embedding objects in the Automata codebase. This class manages +the embedding vector and provides methods to convert the instance to a +string, and vice versa. + +The ``Embedding`` class is typically used as a base class that specific +types of embeddings inherit from. An embedding takes an input object and +transforms it into a vector form that can be easily manipulated by +machine learning models. The class holds a key, an input object, and its +corresponding vector representation. + +Related Symbols +--------------- + +Primary Symbol +~~~~~~~~~~~~~~ + +- automata.embedding.base.Embedding + +Others +~~~~~~ + +- automata.core.base.database.vector.VectorDatabaseProvider +- automata.symbol.base.Symbol +- automata.symbol.symbol_utils.convert_to_fst_object +- automata.symbol_embedding.base.SymbolCodeEmbedding +- automata.symbol_embedding.base.SymbolDocEmbedding +- automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler +- automata.tests.unit.test_symbol_embedding.test_update_embeddings +- automata.tests.unit.test_database_vector.test_load + +Example +------- + +As an abstract base class, ``Embedding`` is not directly instantiated in +most cases. Instead, it is extended by other classes, which implement +the specific type of embedding. Here is an example of a hypothetical +class ``ExampleEmbedding`` that extends ``Embedding``: + +.. code:: python + + class ExampleEmbedding(Embedding): + def __init__(self, key: Any, input_object: str, vector: np.ndarray): + super().__init__(key, input_object, vector) + + def __str__(self): + description = f'Example Embedding for the object {self.input_object} with key {self.key}' + return description + +Limitations +----------- + +As an abstract base class, ``Embedding`` doesn’t provide any +implementations. The ``__str__`` method is expected to be overridden in +child classes since it’s decorated with ``@abc.abstractmethod``. It’s +also assumed the embedding vector will be of the type numpy.ndarray, +though this isn’t enforced in the Embedding class itself. + +Follow-up Questions +------------------- + +- What are the requirements for the key and input_object during the + initialization of the Embedding object? +- What practical implementations are used in the Automata codebase, and + what are specific use-cases? +- What error handling is used if the vector object passed during + initialization is not a numpy.ndarray? +- Are there size or dimension requirements for the array, or can it be + of any shape? diff --git a/docs/embedding/embedding_builder.rst b/docs/embedding/embedding_builder.rst new file mode 100644 index 00000000..92cb2c91 --- /dev/null +++ b/docs/embedding/embedding_builder.rst @@ -0,0 +1,67 @@ +EmbeddingBuilder +================ + +``EmbeddingBuilder`` is an abstract class that defines interfaces for +building embeddings for symbols. It is typically extended by other +classes that provide specific implementations for building the +embeddings. + +Overview +-------- + +``EmbeddingBuilder`` is an important part of the automata.embedding +module. It provides the foundation for building symbol embeddings in an +abstract way, allowing for different methods of building embeddings to +be developed and used interchangeably. The class contains abstract +methods that are intended to be implemented by child classes. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder`` +- ``automata.symbol_embedding.builders.SymbolCodeEmbeddingBuilder`` +- ``automata.symbol_embedding.builders.SymbolDocEmbeddingBuilder`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler.__init__`` +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler.__init`` + +Example +------- + +Here’s an example of how a class might implement ``EmbeddingBuilder`` +providing the actual implementation for the ``build`` method. + +.. code:: python + + class ConcreteEmbeddingBuilder(EmbeddingBuilder): + def build(self, source_text: str, symbol: Symbol) -> Any: + # concrete implementaion of building the embedding. + pass + +Please note that this is a mock example. Replace +‘ConcreteEmbeddingBuilder’ with the actual class that you want to use as +an ``EmbeddingBuilder``. + +Limitations +----------- + +As an abstract base class, ``EmbeddingBuilder`` does not provide any +functionality itself, it merely outlines the methods that need to be +implemented by any concrete subclasses. It involves designing these +subclasses to actually build the embeddings, and the design of these +subclasses can significantly affect the performance and accuracy of +symbol recognition. + +Dependencies +------------ + +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.symbol.base.Symbol`` +- ``automata.symbol.symbol_utils.convert_to_fst_object`` + +Follow-up Questions: +-------------------- + +- When creating subclasses of ``EmbeddingBuilder``, what are the common + pitfalls that one should be mindful of? +- What are the typical strategies to build a good embedding and how do + we evaluate the effectiveness of the strategies? diff --git a/docs/embedding/embedding_handler.rst b/docs/embedding/embedding_handler.rst new file mode 100644 index 00000000..273f6603 --- /dev/null +++ b/docs/embedding/embedding_handler.rst @@ -0,0 +1,93 @@ +EmbeddingHandler +================ + +``EmbeddingHandler`` is an abstract base class designed to handle +embeddings in the Automata library. It acts as an interface that +dictates the basic functions an embedding handler must implement. + +Overview +-------- + +The ``EmbeddingHandler`` symbol provides a standardised interface for +embedding handling. It is designed to be used as a base class for other +specific implementations like ``SymbolEmbeddingHandler`` and +``SymbolDocEmbeddingHandler``. + +It handles the interaction with both the ``embedding_db`` +(VectorDatabaseProvider instance) and ``embedding_builder`` +(EmbeddingBuilder instance), requiring these as parameters during the +class initialisation. + +Related Symbols +--------------- + +- ``automata.core.base.database.vector.VectorDatabaseProvider`` +- ``automata.embedding.base.EmbeddingBuilder`` +- ``automata.symbol.base.Symbol`` +- ``automata.symbol_embedding.base.SymbolEmbeddingHandler`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` + +Methods +------- + +``__init__`` +~~~~~~~~~~~~ + +This is the constructor method for the ``EmbeddingHandler`` and it is +responsible for initialising the instance with the provided +``embedding_db`` and ``embedding_builder``. As an abstract method, it +simply sets these two properties without any further processing. + +.. code:: python + + def __init__(self, embedding_db: VectorDatabaseProvider, embedding_builder: EmbeddingBuilder) -> None: + self.embedding_db = embedding_db + self.embedding_builder = embedding_builder + +``get_embedding`` +~~~~~~~~~~~~~~~~~ + +This abstract method is designed to return the embedding for a specific +symbol. The specific implementation will be dependent on the child +class. + +.. code:: python + + @abc.abstractmethod + def get_embedding(self, symbol: Symbol) -> Any: + pass + +``process_embedding`` +~~~~~~~~~~~~~~~~~~~~~ + +This abstract method is designed to process the embedding for a specific +symbol. The specific implementation will be dependent on the child +class. + +.. code:: python + + @abc.abstractmethod + def process_embedding(self, symbol: Symbol) -> None: + pass + +Limitations +----------- + +As ``EmbeddingHandler`` is an abstract class, it can’t be instantiated +directly. Instead, it must be subclassed, and at least ``get_embedding`` +and ``process_embedding`` methods must be implemented in the child +class. + +Follow-up Questions: +-------------------- + +- How is the ``get_embedding`` method expected to behave? Does it + always access live data, cache results, or some combination of the + two? +- How is the ``process_embedding`` method expected to behave? What sort + of preprocessing might it do? +- Are there expected side-effects to either the ``get_embedding`` or + ``process_embedding`` methods? +- What is the expected type of the returned embeddings? +- How are symbols identified for embedding processing? diff --git a/docs/embedding/embedding_norm_type.rst b/docs/embedding/embedding_norm_type.rst new file mode 100644 index 00000000..9aba0cd1 --- /dev/null +++ b/docs/embedding/embedding_norm_type.rst @@ -0,0 +1,86 @@ +EmbeddingNormType +================= + +``EmbeddingNormType`` is an enumeration class that provides different +methods to normalize the embeddings vectors in the Automata’s core +functionalities. It is used in the process of comparing and ranking +symbol embeddings based on their similarity to a query. + +Overview +-------- + +``EmbeddingNormType`` supports ``L1`` and ``L2`` methods. When used in +an embedding similarity calculator instance, this setting determines how +the distance between the query embedding vector and symbol embeddings +are calculated. + +- ``L1``: Calculates the L1 norm (Manhattan distance) between two + vectors. +- ``L2``: Calculates the L2 norm (Euclidean Distance) between two + vectors. + +``EmbeddingNormType`` is supplied as an argument to the +``EmbeddingSimilarityCalculator`` class during initialization, +determining the norm method used for all similarity calculations within +that instance. + +Related Symbols +--------------- + +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.embedding.base.EmbeddingSimilarityCalculator`` +- ``automata.core.base.database.vector.VectorDatabaseProvider`` +- ``automata.tests.unit.test_symbol_similarity.test_get_nearest_symbols_for_query`` + +Example +------- + +.. code:: python + + from automata.embedding.base import EmbeddingNormType, EmbeddingSimilarityCalculator + from automata.symbol_embedding.base import SymbolCodeEmbedding + from automata.core.base.database.vector import JSONSymbolEmbeddingVectorDatabase + + # Assuming you have a set of symbol embeddings stored in a JSON database. + database_path = "path_to_your_database.json" + embedding_db = JSONSymbolEmbeddingVectorDatabase(database_path) + + # Assume we have a mock embedding provider + mock_provider = MockEmbeddingProvider() + + # Instantiate an EmbeddingSimilarityCalculator with L1 norm. + similarity_calculator = EmbeddingSimilarityCalculator( + embedding_provider=mock_provider, + norm_type=EmbeddingNormType.L1, + ) + + # Get ordered embeddings from database and compute similarity of a query_text + ordered_embeddings = embedding_db.get_ordered_embeddings() + query_text = 'def initialize(x, y):' + similarity_dict = similarity_calculator.calculate_query_similarity_dict(ordered_embeddings, query_text) + + # The keys of the returned dictionary are the symbols and the values are the similarity scores. + most_similar_symbol = max(similarity_dict, key=similarity_dict.get) + + print(f"Symbol most similar to the query is {most_similar_symbol}") + +Limitations +----------- + +The ``EmbeddingNormType`` only supports L1 and L2 norm methods. While +these methods cover typical use cases in calculating document +similarity, there are other distance measurement norms which could be +useful in different contexts, such as cosine similarity or Hamming +distance. + +Other limitations would be that the user must ensure to match the norm +type to the nature of the embeddings used - as certain norm types may +not be suitable or produce the desired results given the type or +characteristics of the embedding vectors. + +Follow-up Questions: +-------------------- + +- How could other norm types be added to the ``EmbeddingNormType``? +- Could the norm type be dynamically set or changed for running + instances of ``EmbeddingSimilarityCalculator``? diff --git a/docs/embedding/embedding_similarity_calculator.rst b/docs/embedding/embedding_similarity_calculator.rst new file mode 100644 index 00000000..c03ed697 --- /dev/null +++ b/docs/embedding/embedding_similarity_calculator.rst @@ -0,0 +1,84 @@ +EmbeddingSimilarityCalculator +============================= + +``EmbeddingSimilarityCalculator`` is a class in the +``automata.embedding.base`` module. It takes an instance of +``EmbeddingVectorProvider`` and calculates the similarity score between +a query text and symbol embeddings. + +Overview +-------- + +``EmbeddingSimilarityCalculator`` leverages embeddings representation to +quantify the similarity between code symbols and a given query text. It +uses the dot product of the query embedding and the symbol embeddings. +If required, the resulting similarity scores can be sorted in descending +order by default. + +Every instance of ``EmbeddingSimilarityCalculator`` is initialized with +an ``EmbeddingVectorProvider`` and a type of norm for vector +normalization (``EmbeddingNormType``). Initially, it sets these +parameters with the corresponding values. + +The main method in this class is ``calculate_query_similarity_dict``. +This method retrieves the embedding for a provided query text, +calculates the similarity scores with the existing symbol embeddings, +constructs a dictionary with these scores indexed by the symbols and +optionally sorts the dictionary. + +Related Symbols +--------------- + +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.embedding.base.EmbeddingNormType`` +- ``automata.embedding.base.Embedding`` +- ``automata.core.base.database.vector.VectorDatabaseProvider`` +- ``automata.symbol.base.Symbol`` + +Example: +-------- + +In this example, ``EmbeddingSimilarityCalculator`` is utilized to find +the symbol most similar to a given query text: + +.. code:: python + + from automata.embedding.base import EmbeddingSimilarityCalculator, EmbeddingVectorProvider + from automata.symbol.base import Symbol + from numpy import array + + # Create an instance of the class + mock_provider = EmbeddingVectorProvider() + embedding_sim_calc = EmbeddingSimilarityCalculator(mock_provider) + + # Define query_text, and embeddings + query_text = "symbol1" + ordered_embeddings = [Embedding(Symbol('symbol1'), 'symbol1', array([1,0,0,0])), + Embedding(Symbol('symbol2'), 'symbol2', array([0,1,0,0])), + Embedding(Symbol('symbol3'), 'symbol3', array([0,0,1,0]))] + + # Use the calculate_query_similarity_dict method + result = embedding_sim_calc.calculate_query_similarity_dict(ordered_embeddings, query_text) + + print(result) + +**Note:** In real scenario ``EmbeddingVectorProvider`` would be an +instance of class that provides actual embeddings like +``OpenAIEmbedding``. + +Limitations +----------- + +The accuracy of ``EmbeddingSimilarityCalculator`` heavily depends on the +quality of the embeddings produced by ``EmbeddingVectorProvider``. Poor +embeddings can result in inaccurate similarity scores. Additionally, it +does not inherently handle cases where symbols might have the same +embedding values. + +Follow-up Questions: +-------------------- + +- If two symbols end up having the same embedding, how does the + ``EmbeddingSimilarityCalculator`` differentiate between them? +- How are the results affected if a different norm type + (``EmbeddingNormType``) is used? diff --git a/docs/embedding/embedding_vector_provider.rst b/docs/embedding/embedding_vector_provider.rst new file mode 100644 index 00000000..a67842d2 --- /dev/null +++ b/docs/embedding/embedding_vector_provider.rst @@ -0,0 +1,73 @@ +EmbeddingVectorProvider +======================= + +``EmbeddingVectorProvider`` is an abstract base class that provides a +way to create embedding vectors for specified symbols in the automata +library. This vector provider returns vector embeddings in numpy array +format, which get utilized in both the OpenAI API and the internal +automata embedding layer. + +Overview +-------- + +As an abstract base class, ``EmbeddingVectorProvider`` doesn’t provide a +specific implementation. Instead, it defines a standardized interface +for all types of embedding vector providers. These providers process +symbols to convert them into embedding vectors. The class mainly defines +one method, ``build_embedding_vector``, which needs to be implemented by +any subclasses. + +Key symbols in relation to ``EmbeddingVectorProvider`` include +``EmbeddingBuilder``, ``OpenAIEmbeddingProvider``, +``JSONSymbolEmbeddingVectorDatabase``, ``SymbolCodeEmbedding``, and +associated unit testing files. + +Related Symbols +--------------- + +- ``automata.embedding.base.EmbeddingBuilder`` +- ``automata.llm.providers.openai.OpenAIEmbeddingProvider`` +- ``automata.symbol_embedding.base.JSONSymbolEmbeddingVectorDatabase`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.tests.unit.test_symbol_embedding`` + +Example +------- + +``EmbeddingVectorProvider`` is an abstract base class and is thus not +directly usable. However, library classes that make use of +``EmbeddingVectorProvider`` (for example, the ``EmbeddingBuilder`` or +``OpenAIEmbeddingProvider``), provide more concrete examples of usage. +Here is an example involving the ``OpenAIEmbeddingProvider``: + +.. code:: python + + from automata.llm.providers.openai import OpenAIEmbeddingProvider + + embed_provider = OpenAIEmbeddingProvider() + + symbol_source = "Text from which to generate the embedding" + embedding_vector = embed_provider.build_embedding_vector(symbol_source) + +This example requires proper configuration of the OpenAI API and +importing the required objects. + +Limitations +----------- + +The primary limitations of ``EmbeddingVectorProvider`` stem from it +being an abstract base class. It does not provide a practical +implementation by itself. Also, the extent to which it can generate +effective embeddings heavily depends on the algorithms and libraries +used in the implementation of its subclasses. + +Follow-up Questions: +-------------------- + +- In testing cases where ``EmbeddingVectorProvider`` is used, it seems + that mock examples are being used. Are there certain assumptions or + configurations that should be considered when designing tests for it, + considering that it’s a mock object? +- Are there specific providers that are known to perform better or + worse with certain types of symbols or classes? If so, are there ways + to optimize these situations? diff --git a/docs/embedding/index.rst b/docs/embedding/index.rst new file mode 100644 index 00000000..8b034a32 --- /dev/null +++ b/docs/embedding/index.rst @@ -0,0 +1,28 @@ +embedding +========= + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + embedding + embedding_builder + embedding_handler + embedding_norm_type + embedding_similarity_calculator + embedding_vector_provider + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/experimental/index.rst b/docs/experimental/index.rst new file mode 100644 index 00000000..3daff4a4 --- /dev/null +++ b/docs/experimental/index.rst @@ -0,0 +1,23 @@ +experimental +============ + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + search/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/experimental/search/index.rst b/docs/experimental/search/index.rst new file mode 100644 index 00000000..b2607891 --- /dev/null +++ b/docs/experimental/search/index.rst @@ -0,0 +1,25 @@ +search +====== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + symbol_rank + symbol_rank_config + symbol_search + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/experimental/search/symbol_rank.rst b/docs/experimental/search/symbol_rank.rst new file mode 100644 index 00000000..7b222c25 --- /dev/null +++ b/docs/experimental/search/symbol_rank.rst @@ -0,0 +1,99 @@ +SymbolRank +========== + +SymbolRank class applies the PageRank algorithm on a graph to rank +symbols such as methods and classes based on their semantic context and +structural relationships within a software. + +Symbols are the classes, methods or other elements in a code corpus. A +SymbolGraph is constructed where each symbol forms a node and +dependencies between symbols form edges. This SymbolGraph maps +structural information from the codebase and helps explore symbol +dependencies, relationships and hierarchy. + +Finally, a prepared similarity dictionary between symbols is used in +combination with the SymbolGraph to compute their SymbolRanks. This is +performed using an iterative computation analogous to Google’s PageRank +algorithm, considering symbols’ similarity scores and their connectivity +within the graph. + +For this a SymbolRankConfig is required which provides the necessary +parameters for the computations. + +Methods +------- + +``__init__(self, graph: nx.DiGraph, config: SymbolRankConfig) -> None:`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Initializes a SymbolRank instance with a given graph and a +SymbolRankConfig. If config is not provided, a default SymbolRankConfig +is initialized. + +``get_ranks(self,query_to_symbol_similarity: Optional[Dict[Symbol, float]] = None,initial_weights: Optional[Dict[Symbol, float]] = None,dangling: Optional[Dict[Symbol, float]] = None,) -> List[Tuple[Symbol, float]]:`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Calculate the SymbolRanks of each node in the graph. + +``get_top_symbols(self, n: int) -> List[Tuple[str, float]]:`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the top ‘n’ symbols as per their ranks. Returns a list of tuples, +where each tuple contains the dotpath of a symbol and its rank. + +Examples +-------- + +.. code:: python + + from automata.symbol.base import Symbol + from automata.experimental.search.rank import SymbolRank, SymbolRankConfig + import networkx as nx + + # create a graph + G = nx.DiGraph() + G.add_edge(1, 2) + G.add_edge(2, 3) + G.add_edge(3, 1) + + # initialize SymbolRankConfig and SymbolRank + config = SymbolRankConfig() + sr = SymbolRank(G, config) + + # retrieve SymbolRanks + ranks = sr.get_ranks() + +Related Modules +--------------- + +- automata.symbol.base.Symbol +- automata.experimental.search.symbol_search.SymbolSearch +- automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder + +Limitations +----------- + +- The SymbolRank class assumes that every node in the graph is a symbol + from an application’s corpus. Therefore, the graph should be prepared + accordingly. +- SymbolRank uses an algorithm similar to the PageRank algorithm which + is iterative in nature. Hence, it may take significant time for large + graphs. +- As the ranks depend on both the graph structure and symbol + similarity, inaccurate results can be returned when the graph is not + properly constructed or appropriate symbol similarity is not used. + +Follow-up Questions: +-------------------- + +- What is default value of ``SymbolRankConfig`` if not provided while + initializing ``SymbolRank``? +- Are there any specific assumptions or requirements for the format or + structure of ``Query_symbol_similarity`` , ``initial_weights`` , + ``dangling``? +- What is the depth up to which symbol dependencies are considered + while constructing the SymbolGraph? +- How are the weights of the edges in the SymbolGraph determined? +- How is the similarity between symbols computed? +- What happens if the ``get_ranks`` method does not converge in + ``max_iterations``? What approaches can be used to mitigate this? diff --git a/docs/experimental/search/symbol_rank_config.rst b/docs/experimental/search/symbol_rank_config.rst new file mode 100644 index 00000000..0487c15d --- /dev/null +++ b/docs/experimental/search/symbol_rank_config.rst @@ -0,0 +1,69 @@ +SymbolRankConfig +================ + +``SymbolRankConfig`` is a configuration class for the SymbolRank object. +It is derived from the BaseModel class and is used to set up +configurations such as alpha, max_iterations, tolerance, and weight_key +for SymbolRank. + +Overview +-------- + +``SymbolRankConfig`` allows for the setup of various parameters: + +- alpha: It affects the damping factor used in the calculation of the + SymbolRank. Default value is 0.25. +- max_iterations: Sets the maximum number of iterations for the + SymbolRank calculation. Default value is 100. +- tolerance: Specifies the tolerance for error in the SymbolRank + calculations. The default is 1.0e-6. +- weight_key: Specifies the key for accessing edge weights. The default + is “weight”. + +An instance of ``SymbolRankConfig`` then validates these values to +ensure that they are within certain bounds. If they fall outside these +bounds, it raises a ValueError. + +Related Symbols +--------------- + +- ``automata.experimental.search.rank.SymbolRank`` +- ``automata.tests.unit.test_symbol_rank.test_get_ranks`` +- ``automata.tests.unit.test_symbol_rank.test_get_ranks_small_graph`` +- ``automata.experimental.search.symbol_search.SymbolSearch.symbol_rank`` +- ``automata.tests.unit.test_symbol_rank.test_prepare_initial_ranks`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_symbol_rank`` +- ``automata.tests.unit.test_symbol_search_tool.test_symbol_rank_search`` +- ``automata.tests.unit.test_symbol_rank.test_pagerank_config_validation`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_symbol_search`` +- ``automata.tests.regression.test_symbol_searcher_regression.test_symbol_rank_search_on_symbol`` + +Example +------- + +Below is a simple example on instantiation and validation of +SymbolRankConfig. + +.. code:: python + + from automata.experimental.search.rank import SymbolRankConfig + config = SymbolRankConfig(alpha=0.5, max_iterations=100, tolerance=1.0e-6) + config.validate_config(config) + +Limitations +----------- + +``SymbolRankConfig`` is currently constrained to validate only alpha and +tolerance parameters. However, validation for other parameters such as +max_iterations and weight_key can also be crucial depending upon the +nature of graph and its edges. + +Follow-up Questions: +-------------------- + +- Are there plans to add any further parameters or configurations in + the ``SymbolRankConfig`` class? +- Is there any specific reason to keep the default value of weight_key + as “weight”? +- What kind of use cases are typically supported by the + ``SymbolRankConfig`` class? diff --git a/docs/experimental/search/symbol_search.rst b/docs/experimental/search/symbol_search.rst new file mode 100644 index 00000000..e6afc20a --- /dev/null +++ b/docs/experimental/search/symbol_search.rst @@ -0,0 +1,172 @@ +SymbolSearch +============ + +``SymbolSearch`` is a class which exposes various search methods for +symbols. It is designed to provide seamless and robust functionality for +searching symbols within an indexed codebase. This class uses +``SymbolGraph``, ``SymbolRankConfig``, ``SymbolEmbeddingHandler``, and +``EmbeddingSimilarityCalculator`` to perform its operations. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_symbol_search.test_exact_search`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` +- ``automata.tests.unit.test_symbol_search_tool.test_symbol_rank_search`` +- ``automata.tools.builders.symbol_search.SearchTool`` +- ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` +- ``automata.symbol.base.Symbol`` +- ``automata.tests.unit.test_symbol_search_tool.test_init`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder._exact_search_processor`` +- ``automata.tests.unit.test_symbol_search.test_retrieve_source_code_by_symbol`` + +Methods +------- + +exact_search +~~~~~~~~~~~~ + +Searches for exact matches across the indexed codebase. + +.. code:: python + + def exact_search(self, pattern: str) -> ExactSearchResult: + """Performs a exact search across the indexed codebase.""" + return self._find_pattern_in_modules(pattern) + +For example, to search for an exact pattern ‘pattern1’: + +.. code:: python + + result = symbol_search.exact_search("pattern1") + +A test for the ``exact_search`` functionality can be seen in +``automata.tests.unit.test_symbol_search.test_exact_search``. + +process_query +~~~~~~~~~~~~~ + +Processes an NLP-formatted query and returns the results of the +appropriate downstream search. + +.. code:: python + + def process_query( + self, query: str + ) -> Union[SymbolReferencesResult, SymbolRankResult, SourceCodeResult, ExactSearchResult,]: + + """ + Processes an NLP-formatted query and returns the results of the appropriate downstream search. + Raises: + ValueError: If the query is not formatted correctly + """ + ... + +retrieve_source_code_by_symbol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Finds the raw text of a module, class, method, or standalone function. + +.. code:: python + + def retrieve_source_code_by_symbol(self, symbol_uri: str) -> SourceCodeResult: + """Finds the raw text of a module, class, method, or standalone function.""" + ... + +shifted_z_score_powered +~~~~~~~~~~~~~~~~~~~~~~~ + +Calculates the z-score, shifts them to be positive, and then raises the +values to the specified power. + +.. code:: python + + @staticmethod + def shifted_z_score_powered( + values: Union[List[float], np.ndarray], power: int = 4 + ) -> np.ndarray: + """ + Calculates the z-score, shifts them to be positive, + and then raises the values to the specified power. + """ + ... + +symbol_rank_search +~~~~~~~~~~~~~~~~~~ + +Fetches the list of the SymbolRank similar symbols ordered by rank. + +.. code:: python + + def symbol_rank_search(self, query: str) -> SymbolRankResult: + """Fetches the list of the SymbolRank similar symbols ordered by rank.""" + ... + +symbol_references +~~~~~~~~~~~~~~~~~ + +Finds all references to a module, class, method, or standalone function. + +.. code:: python + + def symbol_references(self, symbol_uri: str) -> SymbolReferencesResult: + """ + Finds all references to a module, class, method, or standalone function. + """ + ... + +Example +------- + +The functionality of the SymbolSearch class can be approached as +follows: + +.. code:: python + + from automata.experimental.search.symbol_search import SymbolSearch + from automata.symbol.graph import SymbolGraph + from automata.experimental.search.rank import SymbolRankConfig + from automata.symbol_embedding.base import SymbolEmbeddingHandler + from automata.embedding.base import EmbeddingSimilarityCalculator + + symbol_graph = SymbolGraph() + symbol_rank_config = SymbolRankConfig() + search_embedding_handler = SymbolEmbeddingHandler() + embedding_similarity_calculator = EmbeddingSimilarityCalculator() + + symbol_search = SymbolSearch( + symbol_graph, + symbol_rank_config, + search_embedding_handler, + embedding_similarity_calculator + ) + + # perform exact search + result = symbol_search.exact_search("pattern1") + + # process a query + result = symbol_search.process_query("query1") + +Follow-up Questions: +-------------------- + +- How does ``_find_pattern_in_modules()`` work and what does it return? +- What is the appropriate format for the query in the ``process_query`` + method? +- What are the possible query formats other than ‘symbol_references’, + ‘symbol_rank’, ‘exact’, and ‘source’ in the ``process_query`` method? +- How is symbol rank determined in ``symbol_rank_search`` method? +- Are references parsed in ``symbol_references`` method or do they need + to be parsed prior to use? +- The ``_find_pattern_in_modules()`` is mentioned in the exact search + implementation but there is no information about this method. Could + you provide more documentation or context for this function? +- What does the ``retrieve_source_code_by_symbol`` return when the + symbol does not exist? +- How can we use the ``shifted_z_score_powered`` and + ``transform_dict_values`` function? What can be the possible + use-cases for these functions? +- The functionality of the property ``symbol_rank`` is not clear, and + it appears to instantiate SymbolRank. Could you provide more clarity + on what it does and how it ties in with the rest of the functions in + the class? diff --git a/docs/faq.json b/docs/faq.json index 2622ae85..c4fed8c3 100644 --- a/docs/faq.json +++ b/docs/faq.json @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:19d577037bc818edc44ae20ae8c27656829f99cd078d1c01fd17fe8489aa00cf -size 6131 +oid sha256:20fedfbaa3d55eb8b961750ba11bbe1316e179604d26f4270f7a166e678f42eb +size 6116 diff --git a/docs/faq.rst b/docs/faq.rst index e2d9c32b..09e32845 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -21,7 +21,7 @@ Frequently Asked Questions Here's an example of its use: ```python - from automata.core.llm.providers.openai import OpenAIEmbeddingProvider + from automata.llm.providers.openai import OpenAIEmbeddingProvider import numpy as np embedding_provider = OpenAIEmbeddingProvider(engine="text-embedding-ada-002") @@ -49,9 +49,9 @@ Frequently Asked Questions A URI for a Symbol is composed of a scheme, package, and descriptor. The scheme consists of any UTF-8 characters. The package specifies the manager, package name, and version. Descriptors define a namespace, type, term, method, type-parameter, parameter, meta, or macro. Example: - ```from automata.core.experimental.search.symbol_parser import parse_symbol + ```from automata.experimental.search.symbol_parser import parse_symbol symbol_class = parse_symbol( - "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.core.agent.agent_enums`/ActionIndicator#"``` + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#"``` .. dropdown:: Q: How does `SymbolRank` work? :container: + shadow diff --git a/docs/github_management/git_hub_client.rst b/docs/github_management/git_hub_client.rst new file mode 100644 index 00000000..448c558d --- /dev/null +++ b/docs/github_management/git_hub_client.rst @@ -0,0 +1,111 @@ +GitHubClient +============ + +Overview +-------- + +``GitHubClient`` is a class under the +``automata.github_management.client`` package that provides an interface +for interacting with GitHub repositories. Its main function is to manage +operations directly related to the GitHub repository, such as creating +new branches, checking out branches, staging all changes to the +repository, committing changes, pushing changes to the repository, +creating pull requests, and others. + +This powerful and flexible client can be used to wrap all interactions +with GitHub, allowing for clean and maintainable code. It accomplishes +its tasks using the ``GitHub API``, alongside libraries ``gitpython`` +and ``PyGitHub``. + +Related Symbols +--------------- + +- ``automata.tests.conftest.MockRepositoryClient`` +- ``automata.tests.conftest.environment`` +- ``automata.tasks.environment.AutomataTaskEnvironment.__init__`` +- ``automata.tests.unit.test_task_environment.test_commit_task`` +- ``automata.tests.conftest.task`` +- ``automata.github_management.client.RepositoryClient`` +- ``automata.tests.unit.test_py_reader_tool.test_tool_execution`` +- ``automata.tests.unit.test_py_writer.MockCodeGenerator`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tests.unit.test_task_environment.TestURL`` + +Example +------- + +Assume you’ve initialized a ``GitHubClient`` instance using your GitHub +``access_token``, the ``remote_name`` of your repository and +``primary_branch`` name: + +.. code:: python + + access_token = "" + remote_name = "" + primary_branch = "main" + github_client = GitHubClient(access_token, remote_name, primary_branch) + +One can check if a branch exists in the repository as follows: + +.. code:: python + + branch_name = "feature_branch" + print(github_client.branch_exists(branch_name)) + +If you need to clone a repository to a local path: + +.. code:: python + + local_path = "" + github_client.clone_repository(local_path) + +The methods of the ``GitHubClient`` class can be conveniently combined +to perform complex tasks. For example, you could create a new branch, +checkout that branch, stage all changes, commit and push changes: + +.. code:: python + + repo_local_path = "" + branch_name = "feature_branch" + commit_message = "Initial commit" + + # Checking out a new branch and performing some changes + github_client.create_branch(branch_name) + github_client.checkout_branch(repo_local_path, branch_name) + + # Stage all changes and commit them + github_client.stage_all_changes(repo_local_path) + github_client.commit_and_push_changes(repo_local_path, branch_name, commit_message) + +You can even create a pull request: + +.. code:: python + + title = "Feature pull request" + body = "This is a description of the changes introduced by this pull request" + github_client.create_pull_request(branch_name, title, body) + +Limitations +----------- + +While ``GitHubClient`` provides a very convenient way to interact with +GitHub repositories, it does not cover all the possible interactions +that GitHub’s REST API v3 offers. + +It only provides a limited number of functions and is not meant to be a +complete replacement for the functionality provided by the official +GitHub API. + +It also lacks the capability to manage organizations, users, and other +entities beyond repositories. + +The ``GitHubClient`` does not provide support for handling rate limits, +pagination, or retries on failure. + +Follow-up Questions: +-------------------- + +- Can we extend ``GitHubClient`` to provide comprehensive coverage of + GitHub’s REST API v3? +- Are there plans to include support for handling rate limits, + pagination, or retries on failure? diff --git a/docs/github_management/index.rst b/docs/github_management/index.rst new file mode 100644 index 00000000..f1c84ccd --- /dev/null +++ b/docs/github_management/index.rst @@ -0,0 +1,24 @@ +github_management +================= + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + git_hub_client + repository_client + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/github_management/repository_client.rst b/docs/github_management/repository_client.rst new file mode 100644 index 00000000..8cd7724e --- /dev/null +++ b/docs/github_management/repository_client.rst @@ -0,0 +1,78 @@ +RepositoryClient +================ + +Overview +-------- + +``RepositoryClient`` is an abstract class designed for managing +repositories. Its methods provide essential functionalities for working +with repositories, including checking branch existence, branching, +cloning, committing, pushing changes, creating pull requests, fetching +issues, and staging changes. Other classes that extend this abstract +class must implement these methods as per their specific logic. + +Related Symbols +--------------- + +- ``automata.github_management.client.GitHubClient`` +- ``automata.tests.conftest.MockRepositoryClient`` + +Dependencies +------------ + +- ``abc.ABC`` +- ``abc.abstractmethod`` +- ``typing.Any`` +- ``typing.Optional`` +- ``git.Git`` +- ``git.Repo`` +- ``github.Github`` +- ``github.PullRequest.PullRequest`` +- ``github.Issue.Issue`` + +Usage +----- + +Given that ``RepositoryClient`` is an abstract class, it should not be +instantiated directly. Instead, it should be subclassed. For instance, +``MockRepositoryClient`` and ``GitHubClient`` are examples of subclasses +of ``RepositoryClient``. + +.. code:: python + + class MockRepositoryClient(RepositoryClient): + def clone_repository(self, local_path: str): + pass + + # ... + # The other methods from the `RepositoryClient` should be implemented here. + +Limitations +----------- + +As ``RepositoryClient`` is an abstract class, it can’t be instantiated +on its own. One has to write the implementation for each of the abstract +methods when subclassing it, making it somewhat less convenient to use +if only a subset of the methods are required. + +Follow-up Questions: +-------------------- + +- Will we need a default implementation for any of these methods in the + future? +- Is it possible to provide some default implementations for common + operations to reduce boilerplate in subclasses? + +Context Footnotes +----------------- + +1. The ``MockRepositoryClient`` mentioned here is an object specifically + designed for testing purposes, mimicking the behavior of + ``RepositoryClient`` without executing the actual underlying logic. + Therefore, it’s not presented as a fully viable example of a subclass + per se. + +2. Methods like ``checkout_branch`` or ``stash_all_changes`` in + ``MockRepositoryClient`` are intentionally shown not returning + anything, this could be modified to suit your specific test case or + implementation. diff --git a/docs/index.rst b/docs/index.rst index c6998013..946e7910 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -83,6 +83,8 @@ The following module documents are auto-generated via the run-doc-embedding pipe + + .. AUTO-GENERATED CONTENT START .. @@ -95,9 +97,24 @@ The following module documents are auto-generated via the run-doc-embedding pipe setup_guide _build/index _static/index + agent/index + code_handling/index config/index + context_providers/index core/index + embedding/index + experimental/index + github_management/index + llm/index + memory_store/index + navigation/index + retrievers/index + singletons/index + symbol/index + symbol_embedding/index + tasks/index tests/index + tools/index .. AUTO-GENERATED CONTENT END .. diff --git a/docs/llm/foundation/index.rst b/docs/llm/foundation/index.rst new file mode 100644 index 00000000..67451ee1 --- /dev/null +++ b/docs/llm/foundation/index.rst @@ -0,0 +1,23 @@ +foundation +========== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + llm_empty_conversation_error + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/llm/foundation/llm_empty_conversation_error.rst b/docs/llm/foundation/llm_empty_conversation_error.rst new file mode 100644 index 00000000..b39b7d5c --- /dev/null +++ b/docs/llm/foundation/llm_empty_conversation_error.rst @@ -0,0 +1,79 @@ +LLMConversation +=============== + +``LLMConversation`` is an abstract base class designed to represent +different types of LLM (Language Learning Module) conversations. It is a +part of the library, ``automata.llm.foundation``. + +Overview +-------- + +``LLMConversation`` is an outline or blueprint for implementing +different conversation types. As an abstract base class, it lays out a +set of methods that should be implemented in the child classes. Some of +the methods specified by this class involve getting the latest message, +registering observers, and managing messages within a conversation. + +One of the exceptions managed by this module is the +``LLMEmptyConversationError``, raised when an operation is invoked for +an empty conversation. + +Related Symbols +--------------- + +- ``automata.llm.foundation.LLMConversation.get_latest_message`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.foundation.LLMChatMessage`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider`` +- ``automata.llm.providers.openai.OpenAIConversation`` + +Example +------- + +Below is a sample implementation of ``LLMConversation`` and usage of +``LLMEmptyConversationError``. As ``LLMConversation`` is an abstract +base class, we need to first implement all abstract methods in a +subclass: + +.. code:: python + + from automata.llm.foundation.LLMConversation import LLMEmptyConversationError, LLMChatMessage + from automata.core.base.patterns.observer import Observer + + class CustomConversation(LLMConversation): + def __init__(self): + self._observers: Set[Observer] = set() + self.messages: List[LLMChatMessage] = [] + + def get_latest_message(self) -> LLMChatMessage: + try: + return self.messages[-1] + except IndexError: + raise LLMEmptyConversationError() + + # Note: Similarly implement the rest of the abstract methods here... + + # Usage + conversation = CustomConversation() + + try: + latest_message = conversation.get_latest_message() + except LLMEmptyConversationError: + print("Conversation is currently empty.") + +Limitations +----------- + +This class is an abstract base class, so it cannot be instantiated +directly. Additionally, it does not provide default implementations for +its abstract methods requiring subclasses to provide their own specific +implementations. Also, error handling for empty conversations is a +responsibility of the class’s consumers. + +Follow-up Questions: +-------------------- + +- Are there any specifications on how the other abstract methods (like + ``__len__``, ``get_messages_for_next_completion``, and + ``notify_observers``) should be implemented? +- How are observers expected to interact with this class? diff --git a/docs/llm/index.rst b/docs/llm/index.rst new file mode 100644 index 00000000..d33a8a13 --- /dev/null +++ b/docs/llm/index.rst @@ -0,0 +1,29 @@ +llm +=== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + llm_chat_completion_provider + llm_chat_message + llm_completion_result + llm_conversation + llm_conversation_database_provider + foundation/index + providers/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/llm/llm_chat_completion_provider.rst b/docs/llm/llm_chat_completion_provider.rst new file mode 100644 index 00000000..afe68478 --- /dev/null +++ b/docs/llm/llm_chat_completion_provider.rst @@ -0,0 +1,79 @@ +LLMChatCompletionProvider +========================= + +``LLMChatCompletionProvider`` is an abstract base class used to +structure different types of Language Learning Model (LLM) chat +completion providers. The class contains four essential methods that +should be implemented by any subclass. These methods include adding new +chat messages and retrieving the next assistant’s completion from a chat +provider. Additionally, the chat provider can be reset, and it can +operate as a standalone output supplier for the LLM. + +Its main function is to form the fundamental structure for various chat +completion providers in the LLM by standardizing their core methods. + +Overview +-------- + +The ``LLMChatCompletionProvider`` class provides a blueprint for LLM +chat completion providers. It comprises two primary operations – sending +and receiving messages from the chat provider and managing the chat +session. This is especially crucial in controlling the flow of data in +and out of the chat provider, paired with the functionality to control +and manipulate the chat buffer. + +Related Symbols +--------------- + +- ``LLMChatMessage``: This is a base class for different types of chat + messages that are used by LLM and can be provided to the + LLMChatCompletionProvider to add new messages to the chat buffer. +- ``LLMCompletionResult``: This provides the structure for different + types of completion results received from the + ``LLMChatCompletionProvider``. +- ``OpenAIChatCompletionProvider``: This is a subclass of + ``LLMChatCompletionProvider`` that uses the OpenAI API to provide + chat messages. This class has implemented the abstract methods of the + ``LLMChatCompletionProvider`` and can operate as functional + completion provider. + +Example +------- + +As ``LLMChatCompletionProvider`` is an abstract base class, you cannot +instantiate it or use it as is. Instead, you use subclasses of +``LLMChatCompletionProvider`` that have implemented the abstract +methods. One such subclass is ``OpenAIChatCompletionProvider``. Below is +an example of how to use it: + +.. code:: python + + from automata.llm.providers.openai import OpenAIChatCompletionProvider + from automata.llm.foundation import LLMChatMessage + + provider = OpenAIChatCompletionProvider() + + # Add a new message to the provider's buffer + provider.add_message(LLMChatMessage(content="Hello World", channel="general")) + + # Get the next assistant completion from the LLM. + next_message = provider.get_next_assistant_completion() + print(next_message.content) # Prints the content of the next assistant completion message + +Limitations +----------- + +The LLMChatCompletionProvider only provides an abstract structure and +does not implement the methods which limits its direct usage. Subclasses +are required to implement the where necessary for interacting with +different LLM chat completion providers. + +It also assumes that a unique message can be added to the provider’s +buffer and that the provider can be queried for the next assistant +completion at any time. This may not align with the actual behavior of +all chat completion providers. + +Follow-up Questions +------------------- + +- Can this class be refactored further for more versatile usage? diff --git a/docs/llm/llm_chat_message.rst b/docs/llm/llm_chat_message.rst new file mode 100644 index 00000000..cb90c54c --- /dev/null +++ b/docs/llm/llm_chat_message.rst @@ -0,0 +1,76 @@ +LLMChatMessage +============== + +``LLMChatMessage`` is a base class representing different types of Lower +Level Model (LLM) chat messages. This class structures the chat messages +that are processed to and from an LLM. It is used widely throughout the +linked conversational module talks, and plays a critical role in +structuring and storing various chat interactions for retrieval later. + +Overview +-------- + +The ``LLMChatMessage`` class provides a way to structure conversations +in a conversational user interface with an LLM. Each instance of the +class represents one message in the chat. The ``LLMChatMessage`` class +encapsulates the role and content of a chat message and provides a +uniform interface in the form of the ``to_dict()`` method for converting +the message to a dictionary object. + +The ``LLMChatMessage`` class is included in the interaction with the +chat API, the chat message completion providers, the chat conversations, +and in test scenarios. + +Related Symbols +--------------- + +- ``automata.llm.providers.openai.OpenAIChatMessage`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.foundation.LLMConversation.get_latest_message`` + +Examples +-------- + +The following is an example demonstrating how to create an instance of +``LLMChatMessage`` and use it in conversation. + +.. code:: python + + from automata.llm.foundation import LLMChatMessage + + # Create a LLMChatMessage instance + message = LLMChatMessage(role="user", content="Hello, how are you?") + + # Convert the message to a dict + message_dict = message.to_dict() + print(message_dict) # Prints: {'role': 'user', 'content': 'Hello, how are you?'} + +The following is an example demonstrating how to save a conversation +interaction to a database. + +.. code:: python + + from automata.llm.foundation import LLMChatMessage + from automata.core.base.database.relational import SQLDatabase + + # Given a SQL database instance and a conversation interaction + db = SQLDatabase() + interaction = {"role": "user", "content": "Good morning!"} + + # Save the message to the database + db.save_message(LLMChatMessage(**interaction)) + +Limitations +----------- + +``LLMChatMessage`` is essentially a structure providing interface for a +chat message object. It does not check the validity of the chat message +or analyze its text. Additional limitations depend on the +implementations in the related symbols. + +##Follow-up Questions: + +- What are the valid values for the ``role`` attribute in + ``LLMChatMessage``? +- Is there a limit on the ``content`` length for a chat message? If so, + how is a message beyond this limit handled? diff --git a/docs/llm/llm_completion_result.rst b/docs/llm/llm_completion_result.rst new file mode 100644 index 00000000..346a69d2 --- /dev/null +++ b/docs/llm/llm_completion_result.rst @@ -0,0 +1,63 @@ +LLMCompletionResult +=================== + +``LLMCompletionResult`` is a base class designed to manage different +types of LLM completion results. With two principal methods: +``get_content()`` and ``get_role()``, this class aids in fetching the +content and role associated with a completion result. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_automata_agent.mock_openai_response_with_completion_message`` +- ``automata.llm.foundation.LLMConversation.get_latest_message`` +- ``automata.llm.providers.openai.OpenAIChatCompletionResult`` +- ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` +- ``automata.config.base.LLMProvider`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.providers.openai.OpenAIChatMessage`` +- ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` +- ``automata.llm.foundation.LLMChatCompletionProvider.get_next_assistant_completion`` +- ``automata.tests.unit.sample_modules.sample.EmptyClass`` + +Example +------- + +In situations where it’s required to extract the content or role from a +completion result, ``LLMCompletionResult`` is applicable. Below is an +example illustrating its functionality. + +.. code:: python + + from automata.llm.foundation import LLMCompletionResult + + # create an instance of LLMCompletionResult with defined role and content attributes + completion_result = LLMCompletionResult(content="content of the completion result", role="assistant") + + # fetch the content + content = completion_result.get_content() + print(content) # output should be "content of the completion result" + + # fetch the role + role = completion_result.get_role() + print(role) # output should be "assistant" + +Limitations +----------- + +This class serves as a base class and it may not provide any specific +functionality beyond providing an interface for subclasses. Hence, if a +feature is not supported in this class, check the subclasses to see if +they have the feature needed. + +Follow-up Questions: +-------------------- + +- What are some practical use-cases of the ``LLMCompletionResult``? +- Are there specific types of completion results this class can’t + handle? If so, what alternative methods or classes should we use for + such cases? +- Are there any constraints or prerequisites for the content or the + role of the completion result? +- How does the ``LLMCompletionResult`` integrate with other components + of Automata? What’s its role in the broader scheme? diff --git a/docs/llm/llm_conversation.rst b/docs/llm/llm_conversation.rst new file mode 100644 index 00000000..ce40676c --- /dev/null +++ b/docs/llm/llm_conversation.rst @@ -0,0 +1,102 @@ +LLMConversation +=============== + +``LLMConversation`` is an abstract base class for different types of +Language-Learning Model (LLM) conversations in the Automata framework. +It provides a blueprint for managing multiple conversations with +different observers in a multithreaded application scenario. + +Overview +-------- + +``LLMConversation`` uses the Observer design pattern to manage updates +to the state of the conversation. It contains abstract methods that +provide the structure for handling different types of LLM chat messages +and can be expanded and customized for specific implementations. As an +abstract base class, ``LLMConversation`` cannot be instantiated directly +and must be subclassed to be utilized. + +Related Symbols +--------------- + +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` +- ``automata.llm.foundation.LLMChatMessage`` +- ``automata.tests.unit.test_conversation_database.test_put_message_increments_interaction_id`` +- ``automata.tests.unit.test_conversation_database.test_get_messages_returns_all_messages_for_session`` +- ``automata.llm.providers.openai.OpenAIConversation`` +- ``automata.memory_store.agent_conversation_database.AgentConversationDatabase`` +- ``automata.core.base.patterns.observer.Observer`` + +Example +------- + +Below is an example of how a subclass of ``LLMConversation`` might be +designed: + +.. code:: python + + from automata.llm.foundation import LLMConversation, LLMChatMessage + from automata.core.base.patterns.observer import Observer + + class CustomConversation(LLMConversation): + def __init__(self): + super().__init__() + self.messages = [] + + def __len__(self): + return len(self.messages) + + def get_latest_message(self) -> LLMChatMessage: + return self.messages[-1] + + def get_messages_for_next_completion(self): + return self.messages + + def reset_conversation(self) -> None: + self.messages = [] + + # Subscribing an observer to the custom conversation + class CustomObserver(Observer): + def update(self, subject: LLMConversation) -> None: + print(f"Observer notified. Latest message: {subject.get_latest_message().to_dict()}") + + conversation = CustomConversation() + observer = CustomObserver() + conversation.register_observer(observer) + + # Create and add a message to the conversation + message = LLMChatMessage(role="user", content="Hello!") + conversation.messages.append(message) + # Notify observers of the change + conversation.notify_observers() + +In this script: 1. A custom conversation class is built by subclassing +``LLMConversation`` and defining the required methods. 2. An observer +class is built by subclassing ``Observer`` and implementing the +``update`` method. 3. An instance of the custom conversation is created +and an observer is registered. 4. A new message is created and added to +the conversation, and the ``notify_observers`` method is called to +update all registered observers. + +Limitations +----------- + +``LLMConversation`` is an abstract class and cannot be used until all +its abstract methods are implemented in the subclass. The +responsibilities attached to the abstract methods should be +well-understood before implementing a subclass. + +Follow-up Questions: +-------------------- + +- Are there any performance considerations to keep in mind while + implementing the abstract methods, especially when conversations get + too long? +- What is the underlying infrastructure to support notifications to a + possibly large number of observers? Is there a limit on the number of + observers that can be registered to an instance of + ``LLMConversation``? +- What additional functionality might be useful to include in the base + ``LLMConversation`` class that would be universal across all types of + chatbot conversations? Can this be extended to include multimedia + messages along with text? diff --git a/docs/llm/llm_conversation_database_provider.rst b/docs/llm/llm_conversation_database_provider.rst new file mode 100644 index 00000000..0dbb5cb0 --- /dev/null +++ b/docs/llm/llm_conversation_database_provider.rst @@ -0,0 +1,74 @@ +LLMConversationDatabaseProvider +=============================== + +``LLMConversationDatabaseProvider`` is an abstract base class for +different types of database providers intended to be used in an automata +environment. It contains methods that allow for the retrieval and +storage of messages. + +Overview +-------- + +The ``LLMConversationDatabaseProvider`` class is a crucial component in +automata’s conversation functionality. It includes two abstract methods, +``get_messages`` and ``save_message``, which must be implemented by any +concrete class inheriting from it to retrieve and store messages +respectively. Additionally, the ``update`` method, inherited from the +``Observer`` pattern, is implemented to update the database when the +``LLMConversation`` changes. + +Related Symbols +--------------- + +- ``automata.llm.foundation.LLMConversation.get_latest_message`` +- ``automata.memory_store.agent_conversation_database.AgentConversationDatabase`` +- ``automata.llm.providers.openai.OpenAIConversation.get_latest_message`` + +Usage example +------------- + +The following is a simple example demonstrating a concept of how +``LLMConversationDatabaseProvider`` may be used. + +.. code:: python + + class ExampleDatabaseProvider(LLMConversationDatabaseProvider): + def __init__(self): + # some potential implementation for a specific type of database + pass + + def get_messages(self) -> List[LLMChatMessage]: + """Fetches all messages from the implemented database.""" + pass + + def save_message(self, message: LLMChatMessage) -> None: + """Saves a message to the implemented database.""" + pass + +The above example replaces the abstract methods of +``LLMConversationDatabaseProvider`` with simple illustrations. In an +actual deployment scenario, a specific database technology (like SQLite, +PostgreSQL, etc.) would be implemented in the +``ExampleDatabaseProvider``. + +Limitations +----------- + +The ``LLMConversationDatabaseProvider`` class does not include any +implementation details, as it is an abstract base class. The +effectiveness, efficiency, and abilities of any concrete class that +inherits ``LLMConversationDatabaseProvider`` would depend on its +implementation. + +Follow-up Questions: +-------------------- + +- What are the actual implementations provided for the + ``LLMConversationDatabaseProvider`` in the system? +- How do specific implementations handle potential database versioning, + migration, or recovery scenarios? +- In what scenarios is the ``update`` method called to reflect changes + in the LLM conversation? +- How is concurrency managed in the database operations? +- Are there any specific databases that work better or worse with the + system this class is part of? diff --git a/docs/llm/providers/function_call.rst b/docs/llm/providers/function_call.rst new file mode 100644 index 00000000..6893592d --- /dev/null +++ b/docs/llm/providers/function_call.rst @@ -0,0 +1,62 @@ +FunctionCall +============ + +``FunctionCall`` is a class representing a function call to be made by +the OpenAI agent within the ``automata.llm.providers.openai`` module. + +Overview +-------- + +``FunctionCall`` allows the OpenAI agent to perform a function call +within a conversation. It does this by encapsulating the name of the +function to be called and the arguments to be passed in the +conversation, if any. The class provides methods to create an instance +from the response dictionary received (``from_response_dict``), to +handle termination of a function call (``handle_termination``), and to +convert a function call into a dictionary representation (``to_dict``). + +Related Symbols +--------------- + +- ``automata.llm.providers.openai.OpenAIChatCompletionResult.get_function_call`` +- ``automata.llm.providers.openai.OpenAIChatMessage.__init__`` +- ``automata.tests.unit.sample_modules.sample.Person`` +- ``automata.tests.unit.sample_modules.sample.Person.run`` +- ``automata.tests.unit.sample_modules.sample.EmptyClass`` +- ``automata.tasks.base.ITaskExecution.execute`` +- ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` +- ``automata.tests.unit.sample_modules.sample.sample_function`` +- ``automata.code_handling.py.writer.PyWriter.InvalidArguments`` + +Examples +-------- + +Below is a simple example to demonstrate interaction with +``FunctionCall``. + +.. code:: python + + from automata.llm.providers.openai import FunctionCall + + # Creating an instance of FunctionCall + fn_call = FunctionCall(name="functionName", arguments={"arg1":"value1", "arg2":"value2"}) + + # Printing function call as dictionary + print(fn_call.to_dict()) + +Discussion +---------- + +The class relies on JSON for serialization. One of the limitations of +``FunctionCall`` is the method ``handle_termination`` while parsing the +return format, especially with Markdown where JSON decode errors may +occur. This solution is considered hacky and needs to be more robust and +generalizable. + +Follow-up Questions +------------------- + +- What is the exact role of ``FunctionCall`` in managing conversational + flow, especially in terms of error recovery and edge cases? +- How can ``FunctionCall`` be extended or customized for different + conversation control models? diff --git a/docs/llm/providers/index.rst b/docs/llm/providers/index.rst new file mode 100644 index 00000000..e47e9b2e --- /dev/null +++ b/docs/llm/providers/index.rst @@ -0,0 +1,31 @@ +providers +========= + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + function_call + open_ai_chat_completion_provider + open_ai_chat_completion_result + open_ai_chat_message + open_ai_conversation + open_ai_embedding_provider + open_ai_function + open_ai_incorrect_message_type_error + open_ai_tool + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/llm/providers/open_ai_chat_completion_provider.rst b/docs/llm/providers/open_ai_chat_completion_provider.rst new file mode 100644 index 00000000..3bf92ad3 --- /dev/null +++ b/docs/llm/providers/open_ai_chat_completion_provider.rst @@ -0,0 +1,58 @@ +OpenAIChatCompletionProvider +============================ + +``OpenAIChatCompletionProvider`` is a class that provides chat messages +from OpenAI API. It utilizes the OpenAI ChatCompletion method to +interact with AI agents and manage conversations. + +Overview +-------- + +``OpenAIChatCompletionProvider`` allows developers to interact with AI +agents through chat. The class takes in several parameters, such as +``model``, ``temperature``, ``stream`` and ``functions``. The class also +provides methods to manage conversations, including adding messages, +getting completion messages from the AI, and resetting conversations. + +Related Symbols +--------------- + +- ``automata.llm.providers.openai.OpenAIChatCompletionResult`` +- ``automata.llm.providers.openai.OpenAIChatMessage`` +- ``automata.llm.foundation.LLMConversation`` +- ``automata.llm.foundation.LLMChatCompletionProvider`` + +Example +------- + +The following is an example demonstrating how to instantiate and use the +``OpenAIChatCompletionProvider``: + +.. code:: python + + from automata.llm.providers.openai import OpenAIChatCompletionProvider, LLMChatMessage + + model = "gpt-4" + conversation = OpenAIChatCompletionProvider(model) + conversation.add_message(LLMChatMessage(role="user", content="Hello!")) + response_message = conversation.get_next_assistant_completion() + print(response_message.content) + +Limitations +----------- + +The ``OpenAIChatCompletionProvider``\ ’s +``get_approximate_tokens_consumed`` method is an approximation and may +not exactly represent the total tokens consumed by the generated chat +instance. Additionally, the ``standalone_call`` method requires an empty +conversation, so the ``reset`` method needs to be called prior to using +``standalone_call`` if there are existing messages in the conversation. + +Follow-up Questions: +-------------------- + +- What would be the impact on the conversation history if the ``reset`` + method is called, particularly in an ongoing conversation? +- Do we need to manage token limits on our applications to avoid + reaching OpenAI API’s token limit in a relatively shorter timespan? + Can this be automatically managed? diff --git a/docs/llm/providers/open_ai_chat_completion_result.rst b/docs/llm/providers/open_ai_chat_completion_result.rst new file mode 100644 index 00000000..ac5c724a --- /dev/null +++ b/docs/llm/providers/open_ai_chat_completion_result.rst @@ -0,0 +1,94 @@ +``OpenAIChatCompletionResult`` +============================== + +Overview +-------- + +``OpenAIChatCompletionResult`` is a class that represents a chat +response from the OpenAI API. This class takes in raw messages from the +chat API and structures them for further use. Apart from regular chat +message contents, it can also include function calls which the API may +return during an ongoing chat. + +Related Symbols +--------------- + +- ``LLMChatCompletionProvider`` +- ``LLMChatMessage`` +- ``FunctionCall`` +- ``OpenAIChatMessage`` +- ``OpenAIChatCompletionProvider`` + +Initialization +-------------- + +``OpenAIChatCompletionResult`` class can be initialized by providing the +raw data from OpenAI chat API. The ``__init__`` function processes the +raw data and assigns it to class variables. + +.. code:: python + + from automata.llm.providers.openai import OpenAIChatCompletionResult + + # Example raw data from OpenAI chat API + raw_data = { + "choices": [ + { + "message": { + "role": "assistant", + "content": "Hello, how can I assist you today?", + "function_call": None + } + } + ] + } + + completion_result = OpenAIChatCompletionResult(raw_data) + +Methods +------- + +``OpenAIChatCompletionResult`` class has a few methods for handling and +representing the data it encapsulates: + +- ``__str__``: Produces a string representation of the completion + result. +- ``from_args``: A class method for creating an instance of + ``OpenAIChatCompletionResult``. +- ``get_function_call``: Returns the ``FunctionCall`` object if + present. If no function call is present, it returns None. + +Usage Example +------------- + +Following is an example of a using ``from_args`` method to create an +instance and printing it out using the ``__str__`` method: + +.. code:: python + + # Import necessary classes + from automata.llm.providers.openai import OpenAIChatCompletionResult + + # Create an instance using the `from_args` class method + completion_result = OpenAIChatCompletionResult.from_args("assistant", "Hello, how can I assist you today?", None) + + # Use the `__str__` method to print the instance + print(completion_result) + +Limitations +----------- + +One possible limitation of the ``OpenAIChatCompletionResult`` is its +strict reliance on the OpenAI API’s ``choices`` output structure. Any +changes in the API’s response structure can potentially break the +functionality of this class. + +Follow-Up Questions: +-------------------- + +- What happens if the OpenAI API changes the response structure? Do we + have a mechanism to handle these changes? +- Is there a validation step to check the integrity and format of the + raw data received from the OpenAI API before it’s processed? +- Is there a way to handle other roles besides “assistant”? Are other + roles anticipated in the future? diff --git a/docs/llm/providers/open_ai_chat_message.rst b/docs/llm/providers/open_ai_chat_message.rst new file mode 100644 index 00000000..15103471 --- /dev/null +++ b/docs/llm/providers/open_ai_chat_message.rst @@ -0,0 +1,75 @@ +OpenAIChatMessage +================= + +Overview +-------- + +``OpenAIChatMessage`` is a class that represents a processed chat +message TO or FROM the OpenAI LLM Chat API. It provides convenient +methods to parse and generate messages compatible with the OpenAI Chat +API. + +This class is a part of the ``automata.llm.providers.openai`` module and +extends the ``LLMChatMessage`` base class, adding unique fields and +methods suitable for communication with the OpenAI API. + +Related Symbols +--------------- + +- ``automata.llm.providers.openai.OpenAIChatCompletionResult`` +- ``automata.llm.providers.openai.OpenAIConversation`` +- ``automata.llm.providers.openai.OpenAIChatCompletionProvider`` +- ``automata.llm.foundation.LLMChatMessage`` + +Example +------- + +Below is an example of creating a message, converting it to a +dictionary, and retrieving it from a completion result: + +.. code:: python + + from automata.llm.providers.openai import FunctionCall, OpenAIChatCompletionResult, OpenAIChatMessage + + # The function call + function_call = FunctionCall.from_response_dict({ + "name": "call_termination", + "arguments": '{"result": "Success"}', + }) + + # Create an OpenAI Chat Message instance + message = OpenAIChatMessage(role="assistant", function_call=function_call) + + # Convert message to dictionary + message_dict = message.to_dict() + + # Create a mock OpenAI Chat Completion Result + completion_result = OpenAIChatCompletionResult.from_args( + role="assistant", + content=None, + function_call=function_call + ) + + # Retrieve the OpenAI Chat Message from the completion result + retrieved_message = OpenAIChatMessage.from_completion_result(completion_result) + +Limitations +----------- + +This class assumes that the ``OpenAIChatCompletionResult`` already has +the required fields parsed in the expected format. Consequently, if the +OpenAI API changes its response format, the ``from_completion_result`` +method may not function as expected. + +Machines created from ``OpenAIChatMessage`` may not contain a +``function_call`` field if the processed message does not instruct a +function call. + +Follow-up Questions: +-------------------- + +- How does ``OpenAIChatMessage`` handle unexpected + ``OpenAIChatCompletionResult`` structures? +- Are there safety measures in place to ensure ``OpenAIChatMessage`` + instances are created correctly when a ``function_call`` field is + missing from a message? diff --git a/docs/llm/providers/open_ai_conversation.rst b/docs/llm/providers/open_ai_conversation.rst new file mode 100644 index 00000000..17445f6c --- /dev/null +++ b/docs/llm/providers/open_ai_conversation.rst @@ -0,0 +1,76 @@ +OpenAIConversation +================== + +``OpenAIConversation`` is a class that represents a conversation with +the OpenAI API. It manages the series of messages that are part of the +conversation flow. The class includes methods to add messages, get the +latest message, get all messages for the next completion, and reset the +conversation. The OpenAIConversation class is heavily used in +interactions within the agent classes. + +Overview +-------- + +``OpenAIConversation`` provides a way to manage and manipulate the +conversation of an agent with the OpenAI API. Each message in the +conversation is an instance of OpenAIChatMessage. The primary purpose of +``OpenAIConversation`` is to keep track of the series of messages in the +conversation. Each new message is appended to the list of messages and +can be retrieved when required. An important aspect is that the +``OpenAIConversation`` only accepts messages of type +``OpenAIChatMessage``. + +Related Symbols +--------------- + +- ``automata.llm.providers.openai.OpenAIChatMessage`` +- ``automata.llm.providers.openai.OpenAIChatCompletionProvider`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.llm.foundation.LLMChatMessage`` + +Example +------- + +Here is an example demonstrating how to create and manage messages in an +``OpenAIConversation``: + +.. code:: python + + from automata.llm.providers.openai import OpenAIConversation, OpenAIChatMessage + + # create conversation + conversation = OpenAIConversation() + + # create a message and add it into the conversation + message = OpenAIChatMessage(role="assistant", content="Hello, I am an assistant.") + conversation.add_message(message) + + # retrieve the latest message + latest_message = conversation.get_latest_message() + print(latest_message) # OpenAIChatMessage object + + # retrieve all messages for next completion + messages_for_completion = conversation.get_messages_for_next_completion() + print(messages_for_completion) # list of messages + + # reset the conversation + conversation.reset_conversation() + # checking the length of conversation after reset + print(len(conversation)) # Output: 0 + +Limitations +----------- + +One limitation of ``OpenAIConversation`` is that it only accepts +messages of the type ``OpenAIChatMessage``. This could make it less +flexible if a different message class needs to be used in certain +situations. + +Follow-up Questions: +-------------------- + +- Is there a way to extend the OpenAIConversation to handle more types + of chat messages? +- How does the class interact with other parts, like agent classes or + completion providers, to contribute to the overall functionality of + the Automata library? diff --git a/docs/llm/providers/open_ai_embedding_provider.rst b/docs/llm/providers/open_ai_embedding_provider.rst new file mode 100644 index 00000000..e5efbfc1 --- /dev/null +++ b/docs/llm/providers/open_ai_embedding_provider.rst @@ -0,0 +1,77 @@ +OpenAIEmbeddingProvider +======================= + +``OpenAIEmbeddingProvider`` is a class in the Automata codebase that is +used to generate embeddings from the OpenAI API. The class works by +passing a given source text to the OpenAI API, which then returns an +embedding in the form of a numpy array. + +Overview +-------- + +``OpenAIEmbeddingProvider`` implements ``EmbeddingVectorProvider``, and +uses the OpenAI API to generate embeddings for given input text. This +class relies heavily on OpenAI’s API and therefore, a key feature of +this embedding provider is its flexibility as the capability of the +provider will extend with any future enhancements made to the core API. + +In this class, the engine used for generating embeddings is specified at +the time of object initialization, and the default engine used is +“text-embedding-ada-002”. + +Related Symbols +--------------- + +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.llm.foundation.LLMChatCompletionProvider`` +- ``automata.llm.foundation.LLMChatMessage`` +- ``automata.llm.foundation.LLMCompletionResult`` +- ``automata.llm.foundation.LLMConversation`` +- ``automata.singletons.dependency_factory.DependencyFactory`` +- ``automata.config.base.LLMProvider`` +- ``automata.tools.base.Tool`` + +Example +------- + +Below is an example demonstrating how to use the +``OpenAIEmbeddingProvider``: + +.. code:: python + + from automata.llm.providers.openai import OpenAIEmbeddingProvider + import numpy as np + + # Create an instance of OpenAIEmbeddingProvider + embedding_provider = OpenAIEmbeddingProvider(engine="text-embedding-ada-002") + + # Generate the embedding for a text + source_text = "This is an example text." + embedding = embedding_provider.build_embedding_vector(source_text) + + # Make sure the embedding is a numpy array + assert isinstance(embedding, np.ndarray) + +Limitations +----------- + +One of the main limitations of the ``OpenAIEmbeddingProvider`` is that +its performance and capabilities are directly linked to the OpenAI API. +This means that any limitations in the API, such as maximum input text +size or rate limits, will also apply to the ``OpenAIEmbeddingProvider``. + +For testing purposes, ``OpenAIEmbeddingProvider`` makes use of mocking +to simulate the behavior of actual objects. The mock objects are +instances of the ``Mock`` or ``MagicMock`` class in the +``unittest.mock`` module, which is a built-in module for constructing +mock objects in Python. + +Follow-up Questions: +-------------------- + +- How does ``OpenAIEmbeddingProvider`` handle potential rate limit + restrictions from the OpenAI API? +- What are the specific error handling strategies in place for API + failures? +- How can customization be introduced to enhance the use of different + ‘engine’ types for different requirements? diff --git a/docs/llm/providers/open_ai_function.rst b/docs/llm/providers/open_ai_function.rst new file mode 100644 index 00000000..8947a987 --- /dev/null +++ b/docs/llm/providers/open_ai_function.rst @@ -0,0 +1,79 @@ +OpenAIFunction +============== + +``OpenAIFunction`` represents a callable function in the OpenAI agent. +It encapsulates required information related to a function such as its +name, description, properties, and optional parameters. + +Detailed Description +-------------------- + +The ``OpenAIFunction`` class encapsulates the necessary details needed +to define a function that can be used by the OpenAI agent. The +information includes the name, description, properties, and a list of +required properties for the function. The class also provides the +``to_dict`` method to get the information about the function in a +dictionary format. + +Related Symbols +--------------- + +- ``automata.tests.unit.sample_modules.sample.sample_function``: An + example of a function that can be represented by ``OpenAIFunction``. +- ``automata.agent.providers.OpenAIAutomataAgent.functions``: A method + that returns a list of ``OpenAIFunction`` instances representing the + available functions for the agent. +- ``automata.llm.providers.openai.OpenAITool``: A class representing a + tool that can be used by the OpenAI agent which utilizes + ``OpenAIFunction``. + +Usage Example +------------- + +The following is an example demonstrating how to create an instance of +``OpenAIFunction`` and get its data in dictionary format using +``to_dict`` method: + +.. code:: python + + from automata.llm.providers.openai import OpenAIFunction + + # Initialize OpenAIFunction object + function = OpenAIFunction( + name="Sample Function", + description="This is a sample function", + properties={"Parameter 1": {"description": "Description for parameter 1"}}, + required=["Parameter 1"] + ) + + # Get function information in a dictionary format + function_info = function.to_dict() + print(function_info) + +In the above example, we first import the ``OpenAIFunction`` class. We +then create an instance of ``OpenAIFunction`` named ``function``, +providing its necessary details such as the name, description, +properties, and the list of required properties. Finally, we get the +information about ``function`` in the form of a dictionary using the +``to_dict`` method, and print this information. + +Limitations +----------- + +The main limitation of ``OpenAIFunction`` is that it strictly assumes +the defined function resides in the OpenAI agent. Externally defined +functions cannot be passed directly, and need to be encapsulated in +``OpenAIFunction`` for the agent to use them. + +Next, note that the ``properties`` argument in +``OpenAIFunction.__init__()`` expects a dictionary where each key-value +pair defines a parameter. We can probably make this more specific to +provide better context about the parameters. + +Follow-up Questions: +-------------------- + +- Can we include an example demonstrating how to define a function that + can be utilized by ``OpenAIFunction``? +- What are the specific attributes that should be included in the + ``properties`` argument when defining an ``OpenAIFunction`` instance? diff --git a/docs/llm/providers/open_ai_incorrect_message_type_error.rst b/docs/llm/providers/open_ai_incorrect_message_type_error.rst new file mode 100644 index 00000000..71a42a33 --- /dev/null +++ b/docs/llm/providers/open_ai_incorrect_message_type_error.rst @@ -0,0 +1,65 @@ +OpenAIIncorrectMessageTypeError +=============================== + +``OpenAIIncorrectMessageTypeError`` is an error class that is raised +when the type of message provided is not of the expected +``OpenAIChatMessage`` type. + +Overview +-------- + +The class is used in various methods in OpenAI-based classes, where it +helps in maintaining the correct type of data being used for the +communication with the OpenAI API. + +Related Symbols +--------------- + +1. ``automata.tests.unit.test_automata_agent.mock_openai_response_with_completion_message`` +2. ``automata.tests.unit.test_automata_agent.test_run_with_completion_message`` +3. ``automata.tests.unit.test_automata_agent.test_run_with_no_completion`` +4. ``automata.llm.providers.openai.OpenAIConversation`` +5. ``automata.tests.unit.test_automata_agent.test_build_initial_messages`` +6. ``automata.llm.providers.openai.OpenAIConversation.add_message`` +7. ``automata.tests.unit.test_automata_agent.test_iter_step_without_api_call`` +8. ``automata.agent.providers.OpenAIAutomataAgent`` +9. ``automata.tests.unit.test_automata_agent_builder.test_builder_invalid_input_types`` +10. ``automata.llm.providers.openai.OpenAIConversation.__init__`` + +Example +------- + +The following is an example demonstrating a likely use case for +``OpenAIIncorrectMessageTypeError``. This example supposes a case where +a message to OpenAIConversation of incorrect type is passed and the +error is raised. + +.. code:: python + + from automata.llm.providers.openai import OpenAIConversation, OpenAIIncorrectMessageTypeError + + try: + conversation = OpenAIConversation() + message = "This is a sample message." # Should be of type OpenAIChatMessage + + conversation.add_message(message) # Adds message to the conversation + except OpenAIIncorrectMessageTypeError: + print("Incorrect message type provided.") + +Limitations +----------- + +The ``OpenAIIncorrectMessageTypeError`` class does not provide methods +to automatically correct the type of the message and thus places the +responsibility of ensuring correct message type on the user. + +Follow-up Questions +------------------- + +- Is there a specific reason for not including automatic type + correction within the ``OpenAIIncorrectMessageTypeError`` class? +- Could the design of the ``OpenAIIncorrectMessageTypeError`` class be + improved to allow for more user-friendly data type handling? +- Are there other similar type error classes within the OpenAI suite of + APIs and does ``OpenAIIncorrectMessageTypeError`` interact with them + in any way? diff --git a/docs/llm/providers/open_ai_tool.rst b/docs/llm/providers/open_ai_tool.rst new file mode 100644 index 00000000..46a73a5f --- /dev/null +++ b/docs/llm/providers/open_ai_tool.rst @@ -0,0 +1,77 @@ +OpenAITool +========== + +Overview +-------- + +``OpenAITool`` is a class intended to represent a tool that can be +implemented by the OpenAI agent. This class mainly provides +functionalities for initializing OpenAI tools with specific functions, +names, descriptions, properties, and requirements. The initialization +process of ``OpenAITool`` involves invoking the ``OpenAIFunction`` +class. + +This class is primarily used by OpenAI’s toolkit builders, such as +``ContextOracleOpenAIToolkitBuilder``, ``PyWriterOpenAIToolkitBuilder``, +and ``SymbolSearchOpenAIToolkitBuilder``, to create lists of +``OpenAITool`` instances for OpenAI. + +Related Symbols +--------------- + +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.llm.foundation.LLMChatCompletionProvider`` +- ``automata.llm.foundation.LLMChatMessage`` +- ``automata.llm.foundation.LLMCompletionResult`` +- ``automata.llm.foundation.LLMConversation`` +- ``automata.tools.base.Tool`` +- ``automata.tests.unit.test_tool.TestTool`` + +Example +------- + +Below is an example of how to instantiate an ``OpenAITool`` using the +test tool as a function, which simply returns a string “TestTool +response” irrespective of the input provided. + +.. code:: python + + from automata.llm.providers.openai import OpenAITool + from automata.tests.unit.test_tool import TestTool + + tool = TestTool( + name="TestTool", + description="A test tool for testing purposes", + function=lambda x: "TestTool response", + ) + + openai_tool = OpenAITool( + function=tool.run, + name=tool.name, + description=tool.description, + properties={'test_prop': {'description': 'A test property', 'type': 'string'}}, + ) + +Here the ``run`` method of the ``TestTool`` instance ``tool`` is passed +as the ``function`` parameter to ``OpenAITool``. The ``properties`` is a +dictionary that includes additional data about the tool, such as a +description and type for each property. The ``name`` and ``description`` +are self-explanatory. + +Limitations +----------- + +The OpenAITool provides a basic framework to facilitate the creation and +usage of tools for the OpenAI agent. The actual functionality of the +tool would largely depend on the function passed during its +instantiation. Also, even though it provides a property variable for +additional data storage, it does not inherently provide methods to +handle or manipulate these properties. + +Follow-up Questions: +-------------------- + +- How are the properties of the OpenAITool used in the toolkit builders + and eventually by the OpenAI agent? +- Are there any specific requirements or constraints for the function + that is passed during the initialisation of an OpenAITool? diff --git a/docs/memory_store/agent_conversation_database.rst b/docs/memory_store/agent_conversation_database.rst new file mode 100644 index 00000000..10a1081b --- /dev/null +++ b/docs/memory_store/agent_conversation_database.rst @@ -0,0 +1,80 @@ +AgentConversationDatabase +========================= + +Overview +-------- + +``AgentConversationDatabase`` is a class that manages the interactions +of a given conversation with the Automata agent. Its main +functionalities are connecting to the conversation database, creating +and managing the interaction’s table in the database, and saving, +retrieving and ordering the messages of a given conversation session. +This class inherits from the abstract base class +``LLMConversationDatabaseProvider`` and thus provides an implementation +for the methods ``get_messages`` and ``save_message``. + +Related Symbols +--------------- + +- ``automata.llm.providers.openai.OpenAIChatCompletionProvider.reset`` +- ``automata.config.CONVERSATION_DB_PATH`` +- ``automata.core.base.database.relational.SQLDatabase.connect`` +- ``automata.tests.unit.test_conversation_database.db`` +- ``automata.tests.unit.test_conversation_database.test_get_messages_returns_all_messages_for_session`` +- ``automata.tests.unit.test_conversation_database.test_put_message_increments_interaction_id`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider.get_messages`` +- ``automata.llm.foundation.LLMConversationDatabaseProvider.save_message`` +- ``automata.agent.providers.OpenAIAutomataAgent.set_database_provider`` + +Example +------- + +The following is an example demonstrating how to create an instance of +``AgentConversationDatabase``, save a message and then retrieve it. + +.. code:: python + + from automata.memory_store.agent_conversation_database import AgentConversationDatabase + from automata.llm.foundation import LLMChatMessage + + # Initialize a database path and session id + db_path = 'path/to/db' + session_id = 'a_unique_session_id' + + # Create an instance of AgentConversationDatabase + db = AgentConversationDatabase(session_id, db_path) + + # Create a message + message = LLMChatMessage(role='system', content='Hello, world!') + + # Save the message to the database + db.save_message(message) + + # Retrieve all messages from the database + messages = db.get_messages() + +In this example, the ‘messages’ object should now contain the previously +saved LLMChatMessage. + +Limitations +----------- + +One of the limitations of ``AgentConversationDatabase`` is it’s heavily +reliant on the underlying SQL database implementation, thus requiring +careful handling of database connections and queries to prevent +potential data corruption. The current implementation also lacks support +for efficiently handling function call conversations, as stated in the +TODO comment found in the ``save_message`` method. + +Certain aspects are pending improvements, including additional testing +around the ``get_messages`` method and better handling of function calls +in ``save_message``. This is evidenced by the presence of “TODO” +comments in the codebase for this class. + +Follow-up Questions: +-------------------- + +- How can we expand the functionality to handle additional forms of + conversation such as function calls more efficiently? +- What kind of additional testing and validation is required around the + ``get_messages`` method? diff --git a/docs/memory_store/index.rst b/docs/memory_store/index.rst new file mode 100644 index 00000000..5aac9eeb --- /dev/null +++ b/docs/memory_store/index.rst @@ -0,0 +1,25 @@ +memory_store +============ + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + agent_conversation_database + symbol_code_embedding_handler + symbol_doc_embedding_handler + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/memory_store/symbol_code_embedding_handler.rst b/docs/memory_store/symbol_code_embedding_handler.rst new file mode 100644 index 00000000..c7bacdcf --- /dev/null +++ b/docs/memory_store/symbol_code_embedding_handler.rst @@ -0,0 +1,132 @@ +SymbolCodeEmbeddingHandler +========================== + +``SymbolCodeEmbeddingHandler`` is a class within the Automata framework +for handling the storage and retrieval of symbol source code embeddings. +In machine learning applications, embedding is the process of taking raw +data and converting it to a vector of numbers. Within this context, the +handler is used to store and retrieve embeddings of symbols, which are +encoded representations of Python classes, methods, or local variables. + +Overview +-------- + +``SymbolCodeEmbeddingHandler`` interacts with a database of +``JSONSymbolEmbeddingVectorDatabase``, which stores symbol code +embeddings. You can retrieve an existing embedding for a ``Symbol`` with +the ``get_embedding`` method. The handler is also equipped to process an +embedding by comparing its source code with the one in the database. If +there are updates or changes, it will accordingly update the existing +embedding. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_symbol_similarity.test_get_nearest_symbols_for_query`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.tests.unit.test_symbol_embedding.test_get_embedding`` +- ``automata.tests.unit.test_synchronizer.test_build_graph_and_handler_and_synchronize`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.tests.unit.test_database_vector.test_load`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_symbol_code_embedding_handler`` +- ``automata.tests.unit.test_database_vector.test_lookup_symbol`` +- ``automata.symbol_embedding.builders.SymbolCodeEmbeddingBuilder`` +- ``automata.tests.unit.test_database_vector.test_add_symbols`` + +Method Details +-------------- + +**``__init__``**: This function initializes the class with a +``JSONSymbolEmbeddingVectorDatabase`` object (embedding_db) and +``SymbolCodeEmbeddingBuilder`` object (embedding_builder). + +.. code:: python + + def __init__(self, embedding_db: JSONSymbolEmbeddingVectorDatabase, embedding_builder: SymbolCodeEmbeddingBuilder) -> None: + +**``get_embedding``**: Returns the embedding for a given ``Symbol`` from +the database. + +.. code:: python + + def get_embedding(self, symbol: Symbol) -> SymbolCodeEmbedding: + +**``process_embedding``**: If the source code has changed, then it +processes the embedding by creating a new one or updating the existing +one. + +.. code:: python + + def process_embedding(self, symbol: Symbol) -> None: + +**``update_existing_embedding``**: It checks for differences between the +source code of the symbol and the source code of the existing embedding. +If there are differences, it updates the embedding. + +.. code:: python + + def update_existing_embedding(self, source_code: str, symbol: Symbol) -> None: + +Example +------- + +Consider the following code snippet, where we use +``SymbolCodeEmbeddingHandler`` for symbol1, symbol2, and symbol3. + +.. code:: python + + from automata.symbol.base import Symbol + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase, SymbolCodeEmbedding + from automata.symbol_embedding.base import SymbolCodeEmbeddingHandler + from automata.symbol_embedding.builders import SymbolCodeEmbeddingBuilder + from unittest.mock import MagicMock + + # Mock symbols and their embeddings + symbol1 = ... + symbol2 = ... + symbol3 = ... + + embedding1 = SymbolCodeEmbedding(symbol=symbol1, vector=np.array([1, 0, 0, 0]), source_code="symbol1") + embedding2 = SymbolCodeEmbedding(symbol=symbol2, vector=np.array([0, 1, 0, 0]), source_code="symbol2") + embedding3 = SymbolCodeEmbedding(symbol=symbol3, vector=np.array([0, 0, 1, 0]), source_code="symbol3") + + # JSONSymbolEmbeddingVectorDatabase methods + embedding_db = JSONSymbolEmbeddingVectorDatabase('path_to_file') + embedding_db.add(embedding1) + embedding_db.add(embedding2) + embedding_db.add(embedding3) + + # Create an instance of the class + mock_builder = MagicMock(SymbolCodeEmbeddingBuilder) + cem = SymbolCodeEmbeddingHandler(embedding_db=embedding_db, embedding_builder=mock_builder) + +In this example, we have created symbols and their embeddings. We then +create a JSONSymbolEmbeddingVectorDatabase with a given file path and +add the embeddings to the database. Next, we create an instance of +SymbolCodeEmbeddingHandler and pass the database and a mock builder +instance to it. + +Drawbacks +--------- + +The handling, storage, and retrieval of symbol embeddings are dependent +on the correctness and updated status of the +``JSONSymbolEmbeddingVectorDatabase`` database. If the database is not +correctly maintained or updated, the embeddings may not accurately +represent the symbols. More testing and validation steps may be needed +to ascertain embedding changes are accurately detected and handled. + +Another limitation is that ``SymbolCodeEmbeddingHandler`` class cannot +load custom databases. It assumes a specific structure for the database +files and expects them to be in a certain format. + +Follow-up Questions: +-------------------- + +- How does the ``SymbolCodeEmbeddingHandler`` handle embeddings for + symbols that are not found within the + ``JSONSymbolEmbeddingVectorDatabase``? +- How scalable is the use of this class when dealing with large code + bases and many different symbols? +- How are changes propagated in the database when multiple instances of + ``SymbolCodeEmbeddingHandler`` use the same database? diff --git a/docs/memory_store/symbol_doc_embedding_handler.rst b/docs/memory_store/symbol_doc_embedding_handler.rst new file mode 100644 index 00000000..366115a1 --- /dev/null +++ b/docs/memory_store/symbol_doc_embedding_handler.rst @@ -0,0 +1,77 @@ +SymbolDocEmbeddingHandler +========================= + +Overview +-------- + +SymbolDocEmbeddingHandler is a class that handles the process of +embedding symbols. Its core functionalities include retrieving an +existing embedding for a symbol, processing the embedding for a symbol, +and updating the existing embedding. Under the hood, it uses a database +of symbol embeddings (JSONSymbolEmbeddingVectorDatabase) and a builder +for symbol document embeddings (SymbolDocEmbeddingBuilder). + +Related Symbols +--------------- + +- automata.tests.unit.sample_modules.sample.OuterClass.InnerClass +- automata.symbol_embedding.base.SymbolDocEmbedding +- automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder +- automata.singletons.dependency_factory.DependencyFactory.create_symbol_doc_embedding_handler +- automata.symbol_embedding.builders.SymbolDocEmbeddingBuilder +- automata.tests.unit.test_symbol_embedding.test_get_embedding +- automata.tools.builders.context_oracle.ContextOracleToolkitBuilder.\__init\_\_ +- automata.tests.unit.test_py_reader.test_get_docstring_nested_class_method + +Example +------- + +The following example demonstrates how to use SymbolDocEmbeddingHandler: + +.. code:: python + + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase, SymbolDocEmbedding, SymbolEmbeddingHandler + from automata.symbol_embedding.builders import SymbolDocEmbeddingBuilder + from automata.symbol.base import Symbol + + # Initialize database and builder + embedding_db = JSONSymbolEmbeddingVectorDatabase('path_to_embedding_db') + embedding_builder = SymbolDocEmbeddingBuilder(embedding_provider, symbol_search, retriever) + + # Create SymbolDocEmbeddingHandler instance + embedding_handler = SymbolDocEmbeddingHandler(embedding_db, embedding_builder) + + # Use a sample symbol from your project + symbol = Symbol.from_string("your_symbol_string") + + # Process and get the embedding for symbol + embedding_handler.process_embedding(symbol) + embedding = embedding_handler.get_embedding(symbol) + +Please note that “your_symbol_string” and other variables would be +replaced according to your project. + +Limitations +----------- + +The SymbolDocEmbeddingHandler assumes that all the symbols have source +code available to be embedded. If a symbol’s source code is not +available, a ValueError is raised. Also, the current implementation does +nothing if the symbol is already contained in the database and its +source code has not changed. + +Follow-up Questions: +-------------------- + +- How is the SymbolDocEmbeddingBuilder configured in a real scenario? + The example uses a placeholder, but a concrete example would be + helpful. +- What are some common use cases for using the + update_existing_embedding method? +- Could you provide more clarity around what the embedding process + entails and how it’s utilized in general? +- How are the generated embeddings typically used downstream? +- Are there plans to handle the case where a symbol already exists in + the database but its source code has changed more proactively? +- How well does the current implementation scale with large numbers of + symbols or large-sized symbols? diff --git a/docs/navigation/directory.rst b/docs/navigation/directory.rst new file mode 100644 index 00000000..617410bf --- /dev/null +++ b/docs/navigation/directory.rst @@ -0,0 +1,124 @@ +automata.navigation.directory.Directory +======================================= + +The ``Directory`` class is a part of the ``automata`` library, primarily +used for manipulating and navigating directory like structures. +``Directory`` class represents a directory and provides functionalities +such as adding a child node (or file) to itself, getting file names from +the directory, obtaining a list of subdirectories, checking if we are at +the root or leaf directory, etc. + +Overview +-------- + +``Directory`` is an important class for managing structures and +hierarchy of directories and files. The class provides several methods +to efficiently manage the nodes (or files) and directories within the +project’s framework. + +Import Statements +----------------- + +To begin using the ``Directory`` class, the following import statements +are needed: + +.. code:: python + + import logging + import os + from typing import Dict, List, Optional + from automata.navigation.directory import Directory + +Key Methods +----------- + +``Directory`` features several key methods for managing directory +structures: + +- ``__init__(self, name: str, parent: Optional["Node"] = None) -> None:`` + + This method initializes a new instance of the Directory class. + +- ``add_child(self, child: "Node") -> None:`` + + Method to add a child node to this directory + +- ``get_file_names(self) -> List[str]:`` + + Fetches a list of file names in the current directory. + +- ``get_subdirectories(self) -> List[str]:`` + + Fetches a list of the subdirectories present within the current + directory. + +- ``is_leaf_dir(self) -> bool:`` + + Checks if the current directory is a leaf directory, i.e., if it has + no subdirectories. + +- ``is_root_dir(self) -> bool:`` + + Checks if the current directory is the root directory. + +Usage Example +------------- + +.. code:: python + + from automata.navigation.directory import Directory + + # instantiate + root_dir = Directory("root") + + # add child directories and files + root_dir.add_child(Directory("dir1", root_dir)) + root_dir.add_child(File("file1", root_dir)) + + # check if root directory + print(root_dir.is_root_dir()) # True + + # get file names + print(root_dir.get_file_names()) # ['file1'] + + # get subdirectories + print(root_dir.get_subdirectories()) # ['dir1'] + + # check if leaf directory + print(root_dir.is_leaf_dir()) # False + +Please note that for this example to run you have to import ``File`` +from the ``automata.navigation.directory`` module. + +Related Symbols +--------------- + +Here are some test functions related to the ``Directory`` class: + +- ``automata.tests.unit.test_directory_manager.test_load_directory_structure`` + — Checks if a test directory gets properly loaded. +- ``automata.tests.unit.test_directory_manager.test_get_files_in_dir`` + — Tests the action of getting files from a directory. +- ``automata.tests.unit.test_directory_manager.test_get_subdirectories`` + — Checks if a list of subdirectories from a directory can be + retrieved. +- ``automata.tests.unit.test_directory_manager.test_get_node_for_path`` + — Validates that a node from the path can be retrieved. + +Limitations +----------- + +One limitation is that the ``Directory`` class is currently designed to +work with directories and files represented as a tree of node objects, +which means that it can’t handle file systems with symbolic links that +create cycles in the directory structure. Also, it currently doesn’t +handle any system-specific file and directory attributes. + +Follow-up Questions +------------------- + +- How can this class be extended to handle symbolic links and cycles in + the directory structure? +- How could we handle system-specific file and directory attributes? +- Is it possible to add a functionality to move files around, or would + this be beyond the scope of the Node class? diff --git a/docs/navigation/directory_manager.rst b/docs/navigation/directory_manager.rst new file mode 100644 index 00000000..cd49383b --- /dev/null +++ b/docs/navigation/directory_manager.rst @@ -0,0 +1,85 @@ +DirectoryManager +================ + +The ``DirectoryManager`` is a utility class providing functionalities +related to operations with a directory structure. This class offers +methods to create directories, retrieve files inside a directory, and +obtain list of subdirectories inside a particular directory. + +Overview +-------- + +``DirectoryManager``, part of ``automata.navigation.directory``, +conducts operations related to directory structure. It initiates with a +base path and contains a ``root`` attribute representing the root +directory of the structure, as an instance of ``Directory``. + +DirectoryManager provides several methods including: + +- ``ensure_directory_exists(directory_path: str) -> None:`` Creates a + new directory only if it does not exist already. +- ``get_files_in_dir(path: str) -> List[str]:`` Returns a list of files + in the specified directory. +- ``get_subdirectories(path: str) -> List[str]:`` Yields a list of + subdirectories in the given directory. + +Related Symbols +--------------- + +- ``automata.navigation.directory.Directory``: Represents a directory + that contains child nodes which can be either files or directories. +- ``automata.github_management.client.GitHubClient``: Provides an + interface for interacting with GitHub repositories. +- ``automata.tasks.environment.AutomataTaskEnvironment``: The + environment in which the Automata tasks are conducted. +- ``automata.tests.unit.test_directory_manager``: Contains unit tests + for the DirectoryManager methods. + +Example +------- + +Here is an example of how the ``DirectoryManager`` class can be +instantiated and used. + +.. code:: python + + # Import the necessary modules + from automata.navigation.directory import DirectoryManager + + # Define the base directory + base_dir = "/home/user/documents" + + # Instantiate the DirectoryManager object + dir_manager = DirectoryManager(base_dir) + + # Ensure a new directory exists in the base directory + dir_manager.ensure_directory_exists(base_dir + "/new_directory") + + # Get the files in the new directory + files = dir_manager.get_files_in_dir(base_dir + "/new_directory") + print(files) # Returns an empty list if no files exist + + # Get the subdirectories in the base directory + subdirs = dir_manager.get_subdirectories(base_dir) + print(subdirs) # Returns a list of subdirectories in the base directory + +Limitations +----------- + +One of the limitations of the ``DirectoryManager`` class is that it only +works with directories that the current user context has permissions to +manage. Therefore, attempting to manipulate directories that the user +does not have sufficient permissions to work with will result in errors. + +Additionally, the ``DirectoryManager`` class operates only on the +existing file system and cannot manage or interact with remote/mounted +directories. + +Follow-up Questions: +-------------------- + +- Is there a feature or method for interacting with remote directories + in DirectoryManager? +- What happens when attempting to create a directory that already + exists in the file system? +- How does DirectoryManager handle concurrent directory changes? diff --git a/docs/navigation/file.rst b/docs/navigation/file.rst new file mode 100644 index 00000000..17eb19c3 --- /dev/null +++ b/docs/navigation/file.rst @@ -0,0 +1,52 @@ +File +==== + +``File`` is a class that embodies a file in a hierarchical tree +structure. + +Overview +-------- + +``File`` is positioned within the ``automata.navigation.directory`` +module of the Automata Library. It acts as a symbol that stands for a +file in a tree-like directory structure. This class gets instantiated +with a name and an optional parent node. It inherits properties and +behavior from the ``Node`` class. + +Related Symbols +--------------- + +- ``automata.navigation.directory.Node`` + +Examples +-------- + +The following example demonstrates how to create an instance of +``File``. + +.. code:: python + + from automata.navigation.directory import File, Node + + root = Node('root') + file = File('file1', parent=root) + +In this example, ‘file1’ is a ``File`` instance that is a child of the +‘root’ node. + +Limitations +----------- + +While the ``File`` class provides an abstract representation of a file +in a directory tree, it does not provide functionalities associated with +the actual file systems such as reading, writing or performing other I/O +operations on the file. It does not possess any understanding or context +of the contents of the actual file represented. + +Follow-up Questions: +-------------------- + +- Can the ``File`` class be extended to include methods for interacting + with the actual file system? +- How does the ``File`` class interact with other components of the + Automata Library? diff --git a/docs/navigation/index.rst b/docs/navigation/index.rst new file mode 100644 index 00000000..e2a2df30 --- /dev/null +++ b/docs/navigation/index.rst @@ -0,0 +1,27 @@ +navigation +========== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + directory + directory_manager + file + node + py/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/navigation/node.rst b/docs/navigation/node.rst new file mode 100644 index 00000000..3be46275 --- /dev/null +++ b/docs/navigation/node.rst @@ -0,0 +1,60 @@ +Node +==== + +Overview +-------- + +The ``Node`` class is an abstract base class used in the creation of a +file tree in the ``automata.navigation.directory`` module. Each node can +represent a file or a directory within this file tree. It is primarily +used in the construction of trees for file or directory navigation +within the Automata project. Each instance of the ``Node`` class +represents a node of the tree and has attributes ``name`` and ``parent`` +corresponding to the name of the node and its parent node respectively. + +Related Symbols +--------------- + +- ``automata.tests.unit.sample_modules.sample.EmptyClass`` +- ``automata.tests.unit.test_directory_manager.test_get_node_for_path`` +- ``automata.navigation.directory.File`` +- ``automata.tests.unit.sample_modules.sample.OuterClass`` +- ``automata.navigation.directory.Directory`` +- ``automata.tests.unit.test_py_writer.MockCodeGenerator`` +- ``automata.tests.conftest.MockRepositoryClient`` +- ``automata.symbol.base.Symbol`` +- ``automata.tests.unit.sample_modules.sample_module_write.CsSWU`` +- ``automata.code_handling.py.writer.PyWriter`` + +Example +------- + +The ``Node`` class is an abstract class, hence there can’t be an +instantiation of it. However, it serves as a base class for its +subclasses like ``File`` and ``Directory``. In the example below, a +``File`` object is created. + +.. code:: python + + from automata.navigation.directory import File + + file = File("sample_file", None) + +Note: In the above example, ``sample_file`` is the name of the file and +``None`` represents that the file has no parent node. + +Limitations +----------- + +Since ``Node`` is an abstract base class, it can’t be instantiated on +its own. It doesn’t contain any method to manipulate its attributes +``name`` and ``parent``, hence, these should be handled carefully in the +subclasses. + +Follow-up Questions +------------------- + +- Are additional methods required in the ``Node`` class to manipulate + its attributes i.e., ``name`` or ``parent``? +- Given ``Node`` is an abstract base class, what are the contract + details, i.e., the methods subclasses are expected to implement? diff --git a/docs/navigation/py/dot_path_map.rst b/docs/navigation/py/dot_path_map.rst new file mode 100644 index 00000000..c46b68d1 --- /dev/null +++ b/docs/navigation/py/dot_path_map.rst @@ -0,0 +1,84 @@ +DotPathMap +========== + +``DotPathMap`` is a class that establishes a map between module +*dotpaths* and module *filepaths*. Dotpath is a representation of file +structure in dot notation, for example: ``dir_1.dir_2.file``. This +mapping is useful in handling python modules, which often use dotpaths +for import operations, while the file system uses filepaths. + +Overview +-------- + +The ``DotPathMap`` class is initialized with a path and a prefix. The +path is the absolute root of the module tree, and the prefix is added to +the dotpath of each module. Using these, it constructs a +``_module_dotpath_to_fpath_map``, which maps dotpaths to their +corresponding filepaths. A counterpart map, +``_module_fpath_to_dotpath_map``, maps filepaths back to their dotpaths. + +Related Symbols +--------------- + +- ``automata.singletons.py_module_loader.PyModuleLoader`` +- ``automata.tests.unit.test_directory_manager.test_get_node_for_path`` +- ``automata.tests.unit.test_database_vector.test_lookup_symbol`` + +Example +------- + +.. code:: python + + from automata.navigation.py.dot_path_map import DotPathMap + + # Initialize a new DotPathMap + dpm = DotPathMap('/path/to/your/module/root', 'prefix') + + # Check if a dotpath is in the map + contains_dotpath = dpm.contains_dotpath('prefix.module_subpath') + + # Check if a filepath is in the map + contains_fpath = dpm.contains_fpath('/path/to/your/module/root/module_subpath.py') + + # Get the module dotpath given its filepath + module_dotpath = dpm.get_module_dotpath_by_fpath('/path/to/your/module/root/module_subpath.py') + + # Get the filepath given module dotpath + module_fpath = dpm.get_module_fpath_by_dotpath('prefix.module_subpath') + + # Add a new module to the map + dpm.put_module('prefix.new_module') + +Discussions +----------- + +Limitations +~~~~~~~~~~~ + +The ``DotPathMap`` has been designed to track and manage modules within +a directory structure, mapping dotpaths to filepaths and vice versa. +However, the class does not support any structural or naming changes to +the existing modules in the directory after the map is created. In such +cases, an exception may be raised or incorrect filepaths may be +returned. Furthermore, when adding a new module to the map with +``put_module``, it assumes that the dotpath does not already exist in +the map and raises an exception if it does. + +Other uses +~~~~~~~~~~ + +``DotPathMap`` is a fairly generic class that might be useful in other +contexts where the mapping between a dot-separated path representation +and a file system path is needed. + +Follow-up Questions: +-------------------- + +- What happens if I attempt to add a module using a dotpath that + already exists in the directory structure? +- What is the behaviour if I manually add a module to the directory and + then attempt to retrieve its dotpath or filepath from the + ``DotPathMap``? +- What is the expected behaviour if the module files or structure + changes post the initialization of the ``DotPathMap`` object? Does it + dynamically update or does it require re-initializing? diff --git a/docs/navigation/py/index.rst b/docs/navigation/py/index.rst new file mode 100644 index 00000000..91c20014 --- /dev/null +++ b/docs/navigation/py/index.rst @@ -0,0 +1,23 @@ +py +== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + dot_path_map + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/retrievers/index.rst b/docs/retrievers/index.rst new file mode 100644 index 00000000..aed39f8d --- /dev/null +++ b/docs/retrievers/index.rst @@ -0,0 +1,23 @@ +retrievers +========== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + py/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/retrievers/py/context/indent_manager.rst b/docs/retrievers/py/context/indent_manager.rst new file mode 100644 index 00000000..e6f51093 --- /dev/null +++ b/docs/retrievers/py/context/indent_manager.rst @@ -0,0 +1 @@ +Symbol: automata.retrievers.py.context.PyContextRetriever.IndentManager diff --git a/docs/retrievers/py/context/index.rst b/docs/retrievers/py/context/index.rst new file mode 100644 index 00000000..13e8c37d --- /dev/null +++ b/docs/retrievers/py/context/index.rst @@ -0,0 +1,23 @@ +context +======= + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + indent_manager + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/retrievers/py/index.rst b/docs/retrievers/py/index.rst new file mode 100644 index 00000000..93971560 --- /dev/null +++ b/docs/retrievers/py/index.rst @@ -0,0 +1,25 @@ +py +== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + py_context_retriever + py_context_retriever_config + context/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/retrievers/py/py_context_retriever.rst b/docs/retrievers/py/py_context_retriever.rst new file mode 100644 index 00000000..12c92a33 --- /dev/null +++ b/docs/retrievers/py/py_context_retriever.rst @@ -0,0 +1,68 @@ +PyContextRetriever +================== + +``PyContextRetriever`` is a class that retrieves the context of a symbol +from a Python project. It interacts with ``SymbolGraph``, +``VectorDatabaseProvider``, and ``tiktoken.Encoding`` objects to manage +and manipulate this context. + +Overview +-------- + +``PyContextRetriever`` provides methods to manage indentation, process +import statements, docstrings, documentation, and methods for specific +symbols, and can reset its internal states to a default setting. The +context it retrieves for a particular symbol includes all related +symbols and dependencies, with a restriction on the maximum number of +each to process, specified in the config. + +Related Symbols +--------------- + +- ``automata.core.base.database.vector.VectorDatabaseProvider`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.symbol.base.Symbol`` +- ``automata.symbol.graph.SymbolGraph`` +- ``automata.symbol.symbol_utils.convert_to_fst_object`` +- ``automata.symbol.symbol_utils.get_rankable_symbols`` +- ``automata.core.utils.get_root_py_fpath`` + +Example +------- + +The following is an example demonstrating how to use +``PyContextRetriever`` to retrieve the context of a symbol from a Python +project. + +.. code:: python + + from automata.retrievers.py.context import PyContextRetriever + from automata.symbol.graph import SymbolGraph + from automata.symbol.base import Symbol + + graph = SymbolGraph(index_path="my_index_path") + symbol = Symbol.from_string(symbol_str="my_symbol") + + context_retriever = PyContextRetriever(graph=graph) + context_retriever.process_symbol(symbol=symbol) + +Limitations +----------- + +``PyContextRetriever`` is dependent on the ``SymbolGraph`` and the +``VectorDatabaseProvider`` objects for many of its operations. This can +limit its usability in scenarios where these objects are not accessible +or not as comprehensive as required. Moreover, its comprehensive context +retrieval can be limited by the number of symbols specified in the +config. + +Follow-up Questions: +-------------------- + +- Is it possible to modify the process of retrieving context as per + some user-defined guidelines? +- How does the context retrieval fail in scenarios where the + ``SymbolGraph`` or ``VectorDatabaseProvider`` is not up to date? +- How does ``PyContextRetriever`` decide which symbols are important + enough to fetch while trying not to exceed the maximum number + specified in the config? diff --git a/docs/retrievers/py/py_context_retriever_config.rst b/docs/retrievers/py/py_context_retriever_config.rst new file mode 100644 index 00000000..02192989 --- /dev/null +++ b/docs/retrievers/py/py_context_retriever_config.rst @@ -0,0 +1,65 @@ +PyContextRetrieverConfig +======================== + +The ``PyContextRetrieverConfig`` is a configuration class for the +``PyContextRetriever``, which helps retrieve symbol context in a Python +project. Providing an interface with adjustable parameters such as +``spacer``, ``max_dependencies_to_process``, +``max_related_symbols_to_process``, and ``max_context``. + +Overview +-------- + +``PyContextRetrieverConfig`` is designed to limit and control the extent +of information retrieval during the processing of source code. It +configures the behavior of ``PyContextRetriever`` and has a direct +impact on the information it extracts. These extraction tasks are +typically run in the background and can be complex, hence the need for +control parameters. It is closely related to other components in the +retrieval and parsing process of source code, such as ``PyReader``, +``PyWriter`` and ``PyContextRetriever``. + +Related Symbols +--------------- + +- ``automata.retrievers.py.context.PyContextRetriever`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_py_context_retriever`` +- ``automata.tests.unit.test_py_reader_tool.python_retriever_tool_builder`` + +Usage Example +------------- + +.. code:: python + + from automata.retrievers.py.context import PyContextRetrieverConfig + + config = PyContextRetrieverConfig( + spacer=" ", + max_dependencies_to_process=20, + max_related_symbols_to_process=20, + max_context=7_000, + ) + +In this example, we create an instance of ``PyContextRetrieverConfig`` +with custom parameters. The ``max_dependencies_to_process``, +``max_related_symbols_to_process``, and ``max_context`` are set to 20, +20 and 7000 respectively. + +Limitations +----------- + +The main limitation is that the ``PyContextRetrieverConfig`` operates +within the parameters listed above. Therefore, it may not be adaptable +to all code parsing requirements. Also, increases in +``max_dependencies_to_process`` and ``max_related_symbols_to_process`` +could potentially increase processing times. + +Follow-up Questions: +-------------------- + +- How are the parameters used in the subsequent code retrieval process? +- What implications do their values have on the efficiency and result + of the code retrieval operation? +- Can there be integrations for automatic parameter adjustments based + on the complexity and size of the source code? diff --git a/docs/singletons/dependency_factory.rst b/docs/singletons/dependency_factory.rst new file mode 100644 index 00000000..874efc73 --- /dev/null +++ b/docs/singletons/dependency_factory.rst @@ -0,0 +1,91 @@ +DependencyFactory +================= + +``DependencyFactory`` is a source class found in +**automata.singleton.dependency_factory** that is utilized in the +creation of dependencies for input Tool construction. + +The main functionality of ``DependencyFactory`` is to ensure that the +dependencies required by any given set of tools are created and made +available for use. + +The ``DependencyFactory`` class implements singleton design pattern, +means there will only be one instance of this class and all the required +dependencies are created on this single instance. + +Import Statements: +------------------ + +When making use of the ``DependencyFactory`` class, below are the +dependencies to import, + +.. code:: python + + import os + import networkx as nx + from functools import lru_cache + from typing import Any, Dict, List, Set, Tuple + from automata.config.base import ConfigCategory + from automata.agent.agent import AgentToolkitNames + from automata.agent.error import AgentGeneralError, UnknownToolError + from automata.core.base.patterns.singleton import Singleton + from automata.code_handling.py.reader import PyReader + from automata.code_handling.py.writer import PyWriter + from automata.embedding.base import EmbeddingSimilarityCalculator + from automata.experimental.search.rank import SymbolRank, SymbolRankConfig + from automata.experimental.search.symbol_search import SymbolSearch + from automata.llm.providers.openai import ( + OpenAIChatCompletionProvider, + OpenAIEmbeddingProvider, + ) + from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler + from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler + from automata.retrievers.py.context import ( + PyContextRetriever, + PyContextRetrieverConfig, + ) + from automata.symbol.graph import SymbolGraph + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase + from automata.symbol_embedding.builders import ( + SymbolCodeEmbeddingBuilder, + SymbolDocEmbeddingBuilder, + ) + from automata.tools.factory import AgentToolFactory, logger + from automata.core.utils import get_config_fpath + +Usage Example +------------- + +Here is an example that showcases how ``DependencyFactory`` is used: + +.. code:: python + + from automata.singletons.dependency_factory import DependencyFactory + + # Create a DependencyFactory object setting the overrides + dep_factory = DependencyFactory(py_context_retriever_config=PyContextRetrieverConfig()) + + # To get the instance of a created dependency use 'get' method + symbol_ranker = dep_factory.get('symbol_rank') + + # After using the instances, do not forget to reset overrides + dep_factory.set_overrides() + +Limitations +----------- + +The DependencyFactory class doesn’t handle concurrent requests. +Therefore it is not suitable for a multi-threaded or a multi-processed +environment. + +To build more complex dependencies, the DependencyFactory class can +become a bit bloated and difficult to manage as the number of +dependencies increases. + +Follow-up Questions: +-------------------- + +- What are some of the solutions to handle concurrent requests for + building dependencies? +- How to manage DependencyFactory when number of dependencies + increases? diff --git a/docs/singletons/index.rst b/docs/singletons/index.rst new file mode 100644 index 00000000..154003a1 --- /dev/null +++ b/docs/singletons/index.rst @@ -0,0 +1,25 @@ +singletons +========== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + dependency_factory + open_ai_automata_agent_toolkit_registry + py_module_loader + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/singletons/open_ai_automata_agent_toolkit_registry.rst b/docs/singletons/open_ai_automata_agent_toolkit_registry.rst new file mode 100644 index 00000000..f6322397 --- /dev/null +++ b/docs/singletons/open_ai_automata_agent_toolkit_registry.rst @@ -0,0 +1,75 @@ +OpenAIAutomataAgentToolkitRegistry +================================== + +The ``OpenAIAutomataAgentToolkitRegistry`` is a Singleton [1]_ class +that is responsible for managing and providing access to all the +registered OpenAI agent toolkit builders. This allows different parts of +the system to retrieve the correct toolkit builder when needed, without +needing to have direct knowledge of the specifics of each builder. + +Overview +-------- + +The ``OpenAIAutomataAgentToolkitRegistry`` class has three main +responsibilities: 1. It maintains a list of all registered toolkit +builders. This is done using the ``register_tool_manager`` static method +that accepts a class of type ``OpenAIAgentToolkitBuilder`` and adds it +to a list. 2. It provides a method, ``get_all_builders``, to retrieve +all the registered builders. 3. It provides an ``initialize`` method to +load all the registered builders when the system starts. + +Related Symbols +--------------- + +- ``automata.agent.providers.OpenAIAgentToolkitBuilder``: This is the + base class for all toolkit builders. Each specific toolkit builder + must subclass this and implement its methods. +- ``automata.tools.builders.PyReaderOpenAIToolkitBuilder``: This is an + example of a specific toolkit builder. It is responsible for building + ``PyReader`` tools for the OpenAI agent. +- ``automata.tools.builders.PyWriterOpenAIToolkitBuilder``: This is + another example of a specific toolkit builder. It is responsible for + building ``PyWriter`` tools for the OpenAI agent. + +Usage Example +------------- + +.. code:: python + + from automata.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry + from automata.tools.builders.py_reader import PyReaderOpenAIToolkitBuilder + + # registering a builder + OpenAIAutomataAgentToolkitRegistry.register_tool_manager(PyReaderOpenAIToolkitBuilder) + + # retrieving all builders + builders = OpenAIAutomataAgentToolkitRegistry.get_all_builders() + + for builder in builders: + print(builder) + +Limitations +----------- + +The ``OpenAIAutomataAgentToolkitRegistry`` class assumes that all +toolkit builders are subclasses of ``OpenAIAgentToolkitBuilder`` and +implement its interface. If a class does not implement this interface +correctly, ``OpenAIAutomataAgentToolkitRegistry`` may not work correctly +with that class. + +Follow-up Questions: +-------------------- + +- What if we need to support additional types of builders that do not + subclass ``OpenAIAgentToolkitBuilder``? + +Over time, we may need to support additional types of toolkits for new +agent models. Given this class’s current design, we would need to create +a new toolkit builder base class for each new type, and then modify +``OpenAIAutomataAgentToolkitRegistry`` to support instances of that new +class. + +.. [1] + A singleton is a design pattern that restricts a class to a single + instance. In other words, there can only ever be one instance of the + singleton class in the application. diff --git a/docs/singletons/py_module_loader.rst b/docs/singletons/py_module_loader.rst new file mode 100644 index 00000000..d0ef8072 --- /dev/null +++ b/docs/singletons/py_module_loader.rst @@ -0,0 +1,89 @@ +PyModuleLoader +============== + +``PyModuleLoader`` is a Singleton class that provides a reliable and +efficient way to load, cache and maintain in memory Python modules +specifically in the form of ``RedBaron`` FST objects. The class aims to +map modules from their corresponding dotpaths as they are accessed. + +Overview +-------- + +Conversion to ``RedBaron`` FST objects helps with the advantage of it +being a full syntax tree, which gives a more detailed representation of +the source code, preserving details like the whitespace and comments +that would be discarded by a simple Abstract Syntax Tree (AST). + +Throughout its methods, ``PyModuleLoader`` ensures initialization status +thereby maintaining the Singleton pattern. It also checks for module’s +dotpath presence to do selective loading of requested modules and offers +a variety of ways to fetch the module, depending on use-case. + +Initialization +-------------- + +Initialization is performed by calling the ``initialize`` function, +passing in root_fpath and py_fpath, which default to ``get_root_fpath`` +and ``get_root_py_fpath`` respectively if they’re not provided. The +initialize method raises an Exception if paths have already been +initialized, preventing any overriding of root directories. + +Core Methods +------------ + +The ``_fetch_module`` fetches a specific module, ``_put_module`` puts a +module in the directory and the ``_fetch_existing_module_dotpath`` and +``_fetch_existing_module_fpath_by_dotpath`` return module file and dot +paths respectively. The ``_items`` method returns a dictionary listing +all modules. The ``__contains__`` checks if a module exists. + +Example +------- + +.. code:: python + + from automata.singletons.py_module_loader import PyModuleLoader + from automata.core.utils import get_root_fpath, get_root_py_fpath + + # Initialize the loader + PyModuleLoader.initialize(root_fpath=get_root_fpath(), py_fpath=get_root_py_fpath()) + + # Fetch a module + module = PyModuleLoader.fetch_module('automata.core.base') + + # Inspect the module + print(module) + +Related Symbols +--------------- + +- ``automata.navigation.py.dot_path_map.DotPathMap`` +- ``automata.core.base.patterns.singleton.Singleton`` +- ``automata.navigation.py.dot_path_map.DotPathMap`` +- ``automata.navigation.py.dot_path_map.DotPathMap.contains_dotpath`` +- ``automata.core.utils.get_root_fpath`` +- ``automata.core.utils.get_root_py_fpath`` + +Dependencies +------------ + +- ``automata.navigation.py.dot_path_map.DotPathMap.put_module`` +- ``automata.navigation.py.dot_path_map.DotPathMap.get_module_dotpath_by_fpath`` + +Limitations +----------- + +One limitation is the dependency on ``DotPathMap`` to manage directories +and files with assurance on initialization. There is also a need to +manually ensure initialization with ``_assert_initialized`` in every +method. + +Follow-up Questions: +-------------------- + +- How can we handle module’s existence checks better to prevent + redundant file accesses? +- How can we enhance the Singleton design pattern application to not + manually ensure initialization in every context? +- Is there a way to optimize or remove the type-ignoring comments which + are present now to suppress warnings? diff --git a/docs/symbol/base/index.rst b/docs/symbol/base/index.rst new file mode 100644 index 00000000..9a1e0eab --- /dev/null +++ b/docs/symbol/base/index.rst @@ -0,0 +1,23 @@ +base +==== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + py_kind + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/symbol/base/py_kind.rst b/docs/symbol/base/py_kind.rst new file mode 100644 index 00000000..11fcb56a --- /dev/null +++ b/docs/symbol/base/py_kind.rst @@ -0,0 +1,75 @@ +SymbolDescriptor +================ + +``SymbolDescriptor`` is a class to represent the description component +of a Symbol URI. A Symbol URI is a standardized string representation of +a Python class, method, or a local variable. ``SymbolDescriptor`` +encapsulates the key aspect of a symbol - its unique descriptor. This +class recognizes that each Symbol URI has a unique descriptor, that +represents its unique identity within the package. + +Overview +-------- + +``SymbolDescriptor`` takes ``name``, ``suffix`` and optionally +``disambiguator`` during its initialization and it provides several +methods to interact with and manipulate these attributes. The class +implements a ``__repr__`` method for generating a string representation +of the instance. The ``convert_scip_to_python_suffix`` is a crucial +method that maps a descriptor suffix from the SCIP protocol to the +Python-specific kind of that descriptor. In addition, it provides +methods to generate a URI-ready version of a name and to unparse a name +from a descriptor to its original format. + +Related Symbols +--------------- + +- ``automata.symbol.scip_pb2.Descriptor`` - the protobuf format of + descriptor used to interact with descriptors +- ``automata.symbol.base.Symbol`` - the base class for symbols for + which ``SymbolDescriptor`` provides description functionality +- ``automata.symbol.parser`` - where the ``parse_symbol`` method + utilizes ``SymbolDescriptor`` + +Example +------- + +The following is an example demonstrating how to create an instance of +``SymbolDescriptor``. + +.. code:: python + + from automata.symbol.scip_pb2 import Descriptor as DescriptorProto + from automata.symbol.base import SymbolDescriptor + + descriptor_suffix = DescriptorProto.NAME # example value + name = 'test_name' + desc_obj = SymbolDescriptor(name, descriptor_suffix) + +A descriptive example of using ``SymbolDescriptor`` is when we parse a +symbol - + +.. code:: python + + from automata.experimental.search.symbol_parser import parse_symbol + symbol_method = parse_symbol( + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.tools.base`/ToolNotFoundError#__init__()." + ) + # SymbolDescriptor is used internally in this process + +Limitations +----------- + +The primary limitation of ``SymbolDescriptor`` is that it only supports +descriptors that follow the SCIP standard. Therefore, while it provides +a flexible way to create, manage, and interact with descriptors, it may +not be able to accurately work with descriptors that are not in SCIP +standard. + +Follow-up Questions +------------------- + +- Are there plans to support parsing symbols with descriptors that do + not follow the SCIP standard? +- How are errors handled when a descriptor not following SCIP standard + is passed to the ``SymbolDescriptor`` class? diff --git a/docs/symbol/graph_builder.rst b/docs/symbol/graph_builder.rst new file mode 100644 index 00000000..2498a584 --- /dev/null +++ b/docs/symbol/graph_builder.rst @@ -0,0 +1,66 @@ +GraphBuilder +============ + +``GraphBuilder`` is a class within the ``automata.symbol.graph`` module +that constructs a directed multi-graph, called a ``SymbolGraph``, from a +corresponding Index. The ``SymbolGraph`` incorporates and represents the +relationship between symbols in a python codebase. + +Overview +-------- + +Upon instantiation, the ``GraphBuilder`` takes in an Index and a boolean +flag indicating whether to build caller relationships or not. This class +has one public method, ``build_graph``, which loops over all the +``Documents`` in the index of the graph initiating the construction of +the graph by adding corresponding ``Symbol`` nodes to the graph. It also +adds edges representing relationships, references, and calls between +``Symbol`` nodes. + +Related Symbols +--------------- + +- ``automata.symbol.graph.SymbolGraph`` +- ``automata.symbol.parser.parse_symbol`` +- ``automata.core.utils.filter_multi_digraph_by_symbols`` + +Example +------- + +While no direct foundational example of ``GraphBuilder`` is available +from the context, here is a conceptual example: + +.. code:: python + + from automata.symbol.graph import GraphBuilder + from automata.symbol.scip_pb2 import Index # Some test index + + index = Index() # Object of type Index + builder = GraphBuilder(index, build_caller_relationships=True) + graph = builder.build_graph() # build the graph + +The above example is a simplification, as in practice, you would +populate the ``Index`` instance with the actual index data. + +Limitations +----------- + +While ``GraphBuilder`` helps in extracting desired relationships and +references between ``Symbol`` nodes, its performance can be a hit for +very large Indices, resulting in slow graph construction times. Another +limitation is that it only supports the construction of directed +multigraphs. + +Follow-up Questions: +-------------------- + +- What is the specific role of the boolean flag + ``build_caller_relationships`` in the construction of the graph? +- Are there any special type requirements for ``Document`` in the + ``Index``? +- How does the construction of the ``SymbolGraph`` differ when + ``build_caller_relationships`` is set to ``True`` vs ``False``? +- Is there an optimal way to construct the graph in terms of the + density or sparsity of the Index document relationships? +- Could you provide example index data to use for a more concrete usage + example of ``GraphBuilder``? diff --git a/docs/symbol/graph_processor.rst b/docs/symbol/graph_processor.rst new file mode 100644 index 00000000..f8c40dd6 --- /dev/null +++ b/docs/symbol/graph_processor.rst @@ -0,0 +1,68 @@ +GraphProcessor +============== + +Overview +-------- + +The ``GraphProcessor`` class is an abstract base class for processing +edges in the ``MultiDiGraph``. This class provides a framework for +adding new edges of some specified type to the graph. As an abstract +base class, ``GraphProcessor`` can’t be directly instantiated. It must +be subclassed, and its ``process`` method must be overwritten. + +Method details +-------------- + +The ``GraphProcessor`` provides the following method: + +- ``process()``: An abstract method that subclasses must override. When + called, it adds new edges of the specified type to the graph. + +Related Symbols +--------------- + +- ``automata.symbol.graph.SymbolGraph`` +- ``automata.symbol.graph._CallerCalleeProcessor`` +- ``automata.symbol.graph._ReferenceProcessor`` +- ``automata.symbol.graph.GraphBuilder`` + +These classes interact with ``GraphProcessor`` in different ways. The +``SymbolGraph`` class represents a graph of symbols and their +relationships. The other classes (``_CallerCalleeProcessor``, +``_ReferenceProcessor``, and ``GraphBuilder``) are examples of types +that can be used to process (add edges to) a graph. + +Usage Example +------------- + +Assuming an implementation of the GraphProcessor ``process`` method that +adds edges defined by the ‘contains’ relationship between nodes, a usage +example could be: + +.. code:: python + + from networkx import MultiDiGraph + from automata.symbol.graph._ReferenceProcessor import ReferenceProcessor + + graph = MultiDiGraph() + graph_processor = ReferenceProcessor(graph, document) + graph_processor.process() + +In this example, ``_ReferenceProcessor`` is a concrete class inheriting +from ``GraphProcessor`` that adds reference relationship edges to the +graph. + +Limitations +----------- + +Because the ``GraphProcessor`` is an abstract base class, it cannot be +used directly to protect the MultiDiGraph. A specific subclass of +``GraphProcessor`` must implement the ``process`` method to provide +practical functionality. + +Follow-up Questions: +-------------------- + +- What are some use cases for ``GraphProcessor``? +- How would you use multiple graph processor subclasses to process a + graph? diff --git a/docs/symbol/i_symbol_provider.rst b/docs/symbol/i_symbol_provider.rst new file mode 100644 index 00000000..3a059093 --- /dev/null +++ b/docs/symbol/i_symbol_provider.rst @@ -0,0 +1,89 @@ +ISymbolProvider +=============== + +``ISymbolProvider`` is an abstract base class that provides an interface +for classes that work with a collection of symbols. It contains several +methods aimed at managing, updating, and retrieving symbols. + +Overview +-------- + +``ISymbolProvider`` is an abstract base class in the Automata library. +Its main purpose is to enforce a standard interface for classes that +manage symbolic representations in the library. It includes methods to +filter, sort, and manipulate symbols, as well as methods to mark symbol +collection as synchronized. ``ISymbolProvider`` is instantiated +indirectly via a child class. + +Methods +------- + +The core methods in the ``ISymbolProvider`` class include: + +- ``__init__``: Initializes a new instance of an ``ISymbolProvider`` + subclass with the ``is_synchronized`` flag set to ``False``. + +- ``filter_symbols``: An abstract method that needs to be implemented + by any subclass. It is designed to filter the set of symbols managed + by the class. + +- ``get_sorted_supported_symbols``: This method retrieves a list of + sorted symbols. If the ``is_synchronized`` flag is ``False``, a + ``RuntimeError`` is raised. It checks that the symbols are properly + sorted. + +- ``set_synchronized``: This method sets the ``is_synchronized`` flag + to the provided value. This method is used to update the state of the + ``ISymbolProvider`` instance. + +Related Symbols +--------------- + +Some symbolic classes and methods that are related to +``ISymbolProvider`` include: + +- ``automata.tests.unit.test_symbol_graph.test_get_all_symbols`` +- ``automata.tests.unit.test_symbol_graph.test_build_real_graph`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderRegistry`` +- ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` + +Example +------- + +As ``ISymbolProvider`` is an abstract class, it cannot be directly +instantiated. A subclass implementing the ``filter_symbols`` function +must be created: + +.. code:: python + + class SymbolProviderExample(ISymbolProvider): + def filter_symbols(self, sorted_supported_symbols: List[Symbol]) -> None: + self.sorted_supported_symbols = sorted_supported_symbols + +Limitations +----------- + +One major limitation of ``ISymbolProvider`` is that it is an abstract +class. This means it cannot be directly instantiated. Instead, +developers must subclass ``ISymbolProvider`` and provide an +implementation for the ``filter_symbols`` method. + +Another potential limitation is the synchronization requirement, where +the ``is_synchronized`` flag needs to be set prior to attempting to +retrieve symbols. This could potentially lead to runtime exceptions +depending on the order of operations. + +Follow-up Questions: +-------------------- + +1. How are subclasses of ``ISymbolProvider`` intended to implement the + ``filter_symbols`` method? What criteria should they use to filter + symbols? +2. Are there any performance implications associated with the checks + performed in the ``get_sorted_supported_symbols`` method? +3. What happens if the sorted_symbols list is not correctly sorted? How + does this impact the performance and reliability of the symbol + provider? +4. Can there be multiple instances of a child class of + ``ISymbolProvider`` working with different sets of symbols? If so, + how is the synchronization managed across different instances? diff --git a/docs/symbol/index.rst b/docs/symbol/index.rst new file mode 100644 index 00000000..b09298ef --- /dev/null +++ b/docs/symbol/index.rst @@ -0,0 +1,31 @@ +symbol +====== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + graph_builder + graph_processor + i_symbol_provider + symbol + symbol_descriptor + symbol_graph + symbol_package + symbol_reference + base/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/symbol/symbol.rst b/docs/symbol/symbol.rst new file mode 100644 index 00000000..9fe5b46e --- /dev/null +++ b/docs/symbol/symbol.rst @@ -0,0 +1,90 @@ +Symbol +====== + +The ``Symbol`` class in Automata is used to represent a reference to a +Python object in a standardized format. This could be a class, method, +or a local variable. The ``Symbol`` is specified by a Uniform Resource +Identifier (URI) with a defined syntax. + +Overview +-------- + +The ``Symbol`` class primarily works with the concept of a URI. A URI +for a Symbol is composed of a ``scheme``, ``package``, and +``descriptor``. The ``scheme`` consists of any UTF-8 characters, and +spaces within this portion of the URI need to be escaped using a double +space. The ``package`` specifies the ``manager``, ``package-name``, and +``version``. The ``descriptors`` define the ``namespace``, ``type``, +``term``, ``method``, ``type-parameter``, ``parameter``, ``meta``, or +``macro``. + +Useful methods offered by the ``Symbol`` class include: + +- ``__eq__()``: Compares the current symbol to another to determine + equivalence. +- ``__hash__()``: Calculates the hash value of a symbol. +- ``__repr__()``: Returns the string representation of the Symbol + instance. +- ``dotpath()``: Returns the dotpath of the symbol. +- ``from_string()``: Creates a ``Symbol`` instance from a string + representation. +- ``is_local()``, ``is_meta()``, ``is_parameter()``, ``is_protobuf()``: + These methods help determine the type of symbol based on the + descriptor attributes. +- ``module_name()``: Returns the module name of the symbol. +- ``parent()``: Returns the parent symbol of the current symbol. +- ``symbol_kind_by_suffix()``, ``symbol_raw_kind_by_suffix()``: The two + methods convert the suffix of the URI into PyKind and DescriptorProto + respectively, which help determine the type of symbol. + +Examples +-------- + +Here is an example of how you can use the ``Symbol`` class: + +.. code:: python + + from automata.experimental.search.symbol_parser import parse_symbol + + symbol_class = parse_symbol( + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#" + ) + + symbol_method = parse_symbol( + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.tools.base`/ToolNotFoundError#__init__()." + ) + +Related Symbols +--------------- + +The following are the related symbols: + +- ``automata.tests.unit.test_database_vector.test_lookup_symbol`` +- ``automata.tests.unit.test_symbol_parser.test_parse_symbol`` +- ``automata.symbol_embedding.base.SymbolEmbedding.symbol`` +- ``automata.tests.unit.test_database_vector.test_delete_symbol`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.tests.unit.test_symbol_parser.test_is_local_symbol`` + +Limitations +----------- + +Given that the ``Symbol`` class relies on formatting a URI with a +specific syntax, it is important to follow the symbol syntax strictly, +especially when dealing with special characters. + +Dependencies +------------ + +- ``automata.symbol.parser.parse_symbol``: This parses a ``Symbol`` + given a URI. + +Follow-up Questions: +-------------------- + +- What happens if the supplied URI for the ``Symbol`` doesn’t match the + specified format? +- What if the ``scheme`` or ``package`` supplied in the URI doesn’t + exist? +- Is there any way to validate if the ``Symbol`` created maps to a + valid Python object? diff --git a/docs/symbol/symbol_descriptor.rst b/docs/symbol/symbol_descriptor.rst new file mode 100644 index 00000000..d9471cf2 --- /dev/null +++ b/docs/symbol/symbol_descriptor.rst @@ -0,0 +1,59 @@ +SymbolDescriptor +================ + +Overview +-------- + +``SymbolDescriptor`` is a class that helps in representing the +description component of a Symbol URI. A Symbol URI contains necessary +details about a symbol, including its name, suffix, and an optional +disambiguator. The key functionalities of this class include +initialization of symbol properties, formatting of object representation +strings, and parsing symbol names. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` +- ``automata.tests.unit.test_symbol_parser.test_parse_symbol`` +- ``automata.symbol.base.Symbol`` +- ``automata.tests.unit.test_symbol_search_tool.test_symbol_references`` +- ``automata.tests.regression.test_symbol_searcher_regression.get_top_n_results_desc_name`` +- ``automata.symbol.parser._SymbolParser.parse_descriptors`` +- ``automata.tests.unit.test_symbol_search_tool.test_init`` +- ``automata.symbol.base.Symbol.__repr__`` +- ``automata.tests.unit.test_symbol_search.test_symbol_references`` +- ``automata.symbol.parser.new_local_symbol`` + +Example +------- + +Here is an example of ``SymbolDescriptor`` utilization: + +.. code:: python + + from automata.symbol.base import SymbolDescriptor + from automata.symbol.scip_pb2 import Descriptor as DescriptorProto + + symbol_descriptor = SymbolDescriptor('name', DescriptorProto.Type, 'disambiguator') + assert str(symbol_descriptor) == "Descriptor(name, Type, disambiguator)" + +Limitations +----------- + +The ``SymbolDescriptor`` class is mostly used for representing internal +symbol structures and might not have direct use cases in applications. +Also, it’s highly dependent on specific kinds of suffix descriptors, +making it less flexible. + +Follow-up Questions: +-------------------- + +- Can ``SymbolDescriptor`` be extended to support more types of + languages or symbol structures? +- What happens if ``SymbolDescriptor`` encounters an unrecognized + suffix descriptor? +- Is there any specific reason to limit the name of + ``SymbolDescriptor`` to a given set of characters? +- Can the disambiguator handle more complex structures rather than just + strings? diff --git a/docs/symbol/symbol_graph.rst b/docs/symbol/symbol_graph.rst new file mode 100644 index 00000000..5bc2383f --- /dev/null +++ b/docs/symbol/symbol_graph.rst @@ -0,0 +1,96 @@ +SymbolGraph +=========== + +Overview +-------- + +The ``SymbolGraph`` class is a core part of the Automata package. It +constructs and manipulates a graph representing the symbols and their +relationships. This graph can be used to visualize and analyze the +structures and relationships of symbols. + +Nodes in the SymbolGraph represent files and symbols, and the edges +between them signify different types of relationships such as +“contains”, “reference”, “relationship”, “caller”, or “callee”. + +This graph is capable of powerful analysis and manipulation tasks such +as identifying potential symbol callees and callers, getting references +to a symbol and building sub-graphs based on certain criteria. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_symbol_graph.test_build_real_graph`` +- ``automata.tests.unit.test_symbol_graph.test_build_real_graph_and_subgraph`` +- ``automata.symbol.base.Symbol`` +- ``automata.singletons.dependency_factory.DependencyFactory.create_symbol_graph`` + +Methods +------- + +The ``SymbolGraph`` class includes several methods for navigating and +querying the constructed graph: + +- ``get_potential_symbol_callees(self, symbol: Symbol) -> Dict[Symbol, SymbolReference]``: + This method retrieves the potential callees of a given symbol. This + means, it extracts the symbols which the given symbol might be + calling. It’s important to note that downstream filtering must be + applied to remove non-callee relationships. + +- ``get_potential_symbol_callers(self, symbol: Symbol) -> Dict[SymbolReference, Symbol]``: + Similar to the previous method, except it retrieves potential callers + of the input symbol instead of callees. Downstream filtering must + also be applied to remove non-call relationships. + +- ``get_references_to_symbol(self, symbol: Symbol) -> Dict[str, List[SymbolReference]]``: + This function is used to get all references to a particular symbol. + +- ``get_symbol_dependencies(self, symbol: Symbol) -> Set[Symbol]``: + This method retrieves all dependencies of a specified input + ``Symbol``. + +- ``get_symbol_relationships(self, symbol: Symbol) -> Set[Symbol]``: It + retrieves a set of symbols that have relationships with the input + symbol. + +Example +------- + +Given the complexity of the ``SymbolGraph`` and its inherent dependence +on the underlying codebase, the precise usage example would be highly +dependent on the specific use case. Here is a simplified example: + +.. code:: python + + # Assuming that index_path is the path to a valid index protobuf file + symbol_graph = SymbolGraph(index_path) + + # Now `symbol_graph` can be used to perform operations like: + potential_callees = symbol_graph.get_potential_symbol_callees(my_symbol) + +Replace ``index_path`` with the path to your index protobuf file and +``my_symbol`` with the symbol you want to investigate. + +Limitations +----------- + +The main limitation to ``SymbolGraph`` implementation is that its +reliability and effectiveness are intrinsically linked to the underlying +codebase. Therefore, any significant change in the codebase may disrupt +the functionality of the ``SymbolGraph``. + +Moreover, parsing a large codebase may lead to high memory usage and the +need for efficient hardware. + +Follow-up Questions: +-------------------- + +- How would one handle symbols that have both callee and caller + relationships? +- How does the ``SymbolGraph`` handle version changes in imported + packages? +- Is it possible to have nested ``SymbolGraphs``, i.e., a + ``SymbolGraph`` itself represented as a node inside a larger + ``SymbolGraph``? +- What are the runtime implications of building the ``SymbolGraph``, + especially in case of a large codebase? diff --git a/docs/symbol/symbol_package.rst b/docs/symbol/symbol_package.rst new file mode 100644 index 00000000..6c98414a --- /dev/null +++ b/docs/symbol/symbol_package.rst @@ -0,0 +1,82 @@ +SymbolPackage +============= + +Overview +-------- + +``SymbolPackage`` is a class representing the package component of a +Symbol URI in Python. A Symbol URI is a standardized string +representation for a python class, method, or local variable. With +``SymbolPackage``, you can easily manage the packages associated with +your Symbols. + +Import Statement +---------------- + +.. code:: python + + from automata.symbol.base import SymbolPackage + +Related Symbols +--------------- + +- ``automata.symbol.scip_pb2.Descriptor as DescriptorProto`` +- ``automata.symbol.parser.parse_symbol`` +- ``automata.core.utils.is_sorted`` +- ``automata.symbol.base.Symbol`` +- ``automata.tests.unit.test_symbol_parser.test_parse_symbol`` +- ``automata.tests.unit.sample_modules.sample.EmptyClass`` +- ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` +- ``automata.tests.unit.test_symbol_search.test_retrieve_source_code_by_symbol`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.tests.unit.test_symbol_search.test_exact_search`` +- ``automata.symbol.base.Symbol.__repr__`` +- ``automata.tests.unit.sample_modules.sample.OuterClass`` +- ``automata.context_providers.symbol_synchronization.SymbolProviderSynchronizationContext`` + +Example +------- + +The following is an example demonstrating how to generate +``SymbolPackage``. + +.. code:: python + + from automata.symbol.parser import parse_symbol + + symbol_class = parse_symbol( + "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#" + ) + + print(f"Package: {symbol_class.package}") + +Limitations +----------- + +Although ``SymbolPackage`` representation is string-friendly to work +with, it fails to capture the package structure or the hierarchical +relationship between packages and sub-packages, which could be crucial +in complex systems. + +Methods Documentation +--------------------- + +``unparse(self) -> str:`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This method converts the SymbolPackage object back to its original URI +string form. + +``__repr__(self) -> str:`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This method generates a string representation of class blueprint. + +Follow-up Questions: +-------------------- + +- Can the ``SymbolPackage`` class representation be updated to capture + hierarchical relationships in packaging structures? +- How does ``SymbolPackage`` handle versioning in its string + representation? Especially in situations where multiple versions of + the same package exist in the system. diff --git a/docs/symbol/symbol_reference.rst b/docs/symbol/symbol_reference.rst new file mode 100644 index 00000000..1ff9d26f --- /dev/null +++ b/docs/symbol/symbol_reference.rst @@ -0,0 +1,74 @@ +SymbolReference +=============== + +``SymbolReference`` is a class in the ``automata.symbol.base`` module +that represents a reference to a symbol in a file. It is particularly +useful in complex code structures where the same symbol can be used in +different parts of the code, and these references need to be identified +or compared. + +Overview +-------- + +The ``SymbolReference`` class has two magic methods ``__eq__`` and +``__hash__`` which are used to evaluate equality and generate an +immutable hash, respectively. The class is used to compare instances of +``SymbolReference`` and check the equality of the ``uri``, +``line_number`` and ``column_number`` of the symbol reference. They are +also important for the usage of ``SymbolReference`` instances in sets or +dictionaries, where hash values are required. + +Methods +------- + +The class ``SymbolReference`` contains the following methods: + +- ``__eq__(self, other) -> bool`` : It checks the equality of two + instances of ``SymbolReference`` by comparing the ``uri``, + ``line_number`` and ``column_number`` of the ``SymbolReference`` + instances. + +- ``__hash__(self) -> int`` : This method creates a hash value for the + instance of ``SymbolReference`` using the ``uri``, ``line_number`` + and ``column_number``. + +It should be noted that the ``__hash__`` method could cause collisions +if the same symbol is referenced in different files at the same +location. + +Related Symbols +--------------- + +- ``automata.symbol.base.Symbol`` +- ``automata.symbol.graph.SymbolGraph`` +- ``automata.symbol.parser.parse_symbol`` +- ``automata.tests.unit.test_symbol_search.test_symbol_references`` +- ``automata.tests.unit.test_symbol_search_tool.test_symbol_references`` + +Examples +-------- + +The following is an example demonstrating how to create an instance of +``SymbolReference`` and how to use the ``__eq__`` method. + +.. code:: python + + from automata.symbol.base import Symbol, SymbolReference + from automata.symbol.parser import parse_symbol + + symbol_uri = "scip-python python automata 75482692a6fe30c72db516201a6f47d9fb4af065 `automata.agent.agent_enums`/ActionIndicator#" + symbol = parse_symbol(symbol_uri) + + symbol_ref_1 = SymbolReference(symbol=symbol, line_number=10, column_number=20) + symbol_ref_2 = SymbolReference(symbol=symbol, line_number=10, column_number=20) + + print(symbol_ref_1 == symbol_ref_2) # Will output: True + +Follow-Up Questions: +-------------------- + +- How are instances of ``SymbolReference`` generated in the system? +- What are the likely scenarios where symbol collisions can occur and + how are these handled? +- Potential limitations or drawbacks of the ``__hash__`` implementation + weren’t specified, can these be determined and documented? diff --git a/docs/symbol_embedding/index.rst b/docs/symbol_embedding/index.rst new file mode 100644 index 00000000..5bcbb327 --- /dev/null +++ b/docs/symbol_embedding/index.rst @@ -0,0 +1,29 @@ +symbol_embedding +================ + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + json_symbol_embedding_vector_database + symbol_code_embedding + symbol_code_embedding_builder + symbol_doc_embedding + symbol_doc_embedding_builder + symbol_embedding + symbol_embedding_handler + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/symbol_embedding/json_symbol_embedding_vector_database.rst b/docs/symbol_embedding/json_symbol_embedding_vector_database.rst new file mode 100644 index 00000000..504d4adc --- /dev/null +++ b/docs/symbol_embedding/json_symbol_embedding_vector_database.rst @@ -0,0 +1,93 @@ +JSONSymbolEmbeddingVectorDatabase +================================= + +``JSONSymbolEmbeddingVectorDatabase`` is a concrete class under +``automata.symbol_embedding.base`` module used to map symbols to their +vector representation in a JSON file. This class is an extension of the +``automata.core.base.database.vector.JSONVectorDatabase`` class, it +provides similar functionality with additional methods to handle symbol +embeddings. + +The ``JSONSymbolEmbeddingVectorDatabase`` class is typically used in +operations where there is a need to store, retrieve and manage symbol +embeddings in a JSON file. + +Related Symbols +--------------- + +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.core.base.database.vector.JSONVectorDatabase`` +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` + +Overview +-------- + +Below are the most relevant methods in +``JSONSymbolEmbeddingVectorDatabase``: + +- ``__init__(self, file_path: str)``: This method is responsible for + initializing an instance of the class. The ``file_path`` parameter + specifies the location of the JSON file. + +- ``entry_to_key(self, entry: SymbolEmbedding) -> str``: This method + generates a simple hashable key from a Symbol. + +- ``get_ordered_embeddings(self) -> List[SymbolEmbedding]``: This + method returns the SymbolEmbedding entries sorted by their keys. + +Usage Examples +-------------- + +Below are example usages extracted mainly from the unit test functions: + +1. **Instantiating ``JSONSymbolEmbeddingVectorDatabase``**: + +.. code:: python + + from automata.symbol_embedding.base import JSONSymbolEmbeddingVectorDatabase + + vector_database = JSONSymbolEmbeddingVectorDatabase("path_to_your_json_file") + +2. **Adding embeddings to ``JSONSymbolEmbeddingVectorDatabase``**: + +.. code:: python + + from automata.symbol_embedding.base import SymbolCodeEmbedding + from automata.symbol.base import Symbol + + symbol1 = Symbol("symbol_1") + symbol2 = Symbol("symbol_2") + embedding1 = SymbolCodeEmbedding(symbol1, "code_1", [1, 2, 3]) + embedding2 = SymbolCodeEmbedding(symbol2, "code_2", [4, 5, 6]) + + vector_database.add(embedding1) + vector_database.add(embedding2) + +3. **Saving the embeddings to the database**: + +.. code:: python + + vector_database.save() + +4. **Loading embeddings from database**: + +.. code:: python + + vector_database.load() + +Limitations +----------- + +The ``JSONSymbolEmbeddingVectorDatabase`` class does not support +parallel reads and writes to the JSON file. This might pose a problem +when working with large datasets or in multi-threaded environments. + +Follow-up Questions +------------------- + +- How does the ``JSONSymbolEmbeddingVectorDatabase`` class handle + concurrency? +- Can it work with big datasets efficiently? +- Can you add versioning or transaction support to handle potential + read-write conflicts? diff --git a/docs/symbol_embedding/symbol_code_embedding.rst b/docs/symbol_embedding/symbol_code_embedding.rst new file mode 100644 index 00000000..b012cd30 --- /dev/null +++ b/docs/symbol_embedding/symbol_code_embedding.rst @@ -0,0 +1,67 @@ +SymbolCodeEmbedding +=================== + +``SymbolCodeEmbedding`` is a concrete class used for creating embeddings +for source code symbols. It is part of the +``automata.symbol_embedding.base`` package. + +Overview +-------- + +``SymbolCodeEmbedding`` is used to embed source code symbols in an +N-dimensional space. It inherits from ``SymbolEmbedding``, which is an +abstract class for symbol code embeddings. The class mainly has a +constructor for initialization and a ``__str__`` method which returns a +string representation of the object. + +Related Symbols +--------------- + +- ``automata.symbol_embedding.builders.SymbolCodeEmbeddingBuilder``: A + class that builds ``Symbol`` source code embeddings. +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler``: + Handles a database for ``Symbol`` source code embeddings. +- ``automata.core.base.database.vector.JSONVectorDatabase``: A class + that provides the database for storing and retrieving the vector + embeddings. +- ``automata.symbol.base.Symbol``: A class which contains associated + logic for a Symbol. + +Example +------- + +For creating an instance of ``SymbolCodeEmbedding``, you first need to +have a ``Symbol`` and a ``source_code`` associated with it. You also +need a numpy array for the vector representation. Below is an example: + +.. code:: python + + from automata.symbol.base import Symbol + from automata.symbol_embedding.base import SymbolCodeEmbedding + import numpy as np + + symbol = Symbol("URIsymbol") + source_code = "def test():\n\treturn" + vector = np.array([0.1, 0.2, 0.3, 0.4, 0.5]) + + # Initialize SymbolCodeEmbedding + embed = SymbolCodeEmbedding(symbol, source_code, vector) + + # Print the SymbolCodeEmbedding + print(embed) + +Limitations +----------- + +There might limitations around the dimensionality of the numpy vector as +the complexity and size of source code symbols can impose storage and +computation issues. + +Follow-up Questions: +-------------------- + +- What is the dimension of the numpy vectors which are standard in this + context? +- How are the numpy vectors generated or trained from the source code? +- Are there any implicit limitations or assumptions on the type of + symbol or source code that can be embedded? diff --git a/docs/symbol_embedding/symbol_code_embedding_builder.rst b/docs/symbol_embedding/symbol_code_embedding_builder.rst new file mode 100644 index 00000000..fa4c1326 --- /dev/null +++ b/docs/symbol_embedding/symbol_code_embedding_builder.rst @@ -0,0 +1,93 @@ +SymbolCodeEmbeddingBuilder +========================== + +``SymbolCodeEmbeddingBuilder`` is a builder class that constructs +``Symbol`` source code embeddings. An embedding is essentially a +mathematical representation of the symbol’s source code and is used to +measure the similarity between different symbols. The +``SymbolCodeEmbeddingBuilder`` specifically creates the +``SymbolCodeEmbedding`` from the source code and the ``Symbol``, both of +which are provided as input arguments. + +``SymbolCodeEmbeddingBuilder`` plays a critical role in understanding +and processing python codes in a way that allows more sophisticated +operations, like similarity measurement and recommending pieces of codes +based on existing ones. This is achieved by transforming the code from +its primitive form to numerical representations (vectors) that can be +differentiated and compared. + +Overview +-------- + +The ``SymbolCodeEmbeddingBuilder`` uses an ``EmbeddingVectorProvider`` +to build an embedding vector from the source code. The embedding vector +captures the syntactical and perhaps some semantic essence of the code, +and in effect, creates a numerical representation for it. The +``SymbolCodeEmbeddingBuilder`` then leverages the source code, the +symbol, and the embedding vector to build a ``SymbolCodeEmbedding``. + +Related Symbols +--------------- + +- ``automata.embedding.base.EmbeddingBuilder``: An abstract class to + build embeddings, from which ``SymbolCodeEmbeddingBuilder`` inherits. +- ``automata.embedding.base.EmbeddingVectorProvider``: An abstract + class that provides a standard API for creating embedding vectors. +- ``automata.symbol_embedding.base.SymbolCodeEmbedding``: A class for + symbol code embeddings. +- ``automata.symbol.base.Symbol``: A class which contains the + associated logic for a Symbol. + +Example +------- + +This is an example demonstrating how to create an instance of +``SymbolCodeEmbedding`` using ``SymbolCodeEmbeddingBuilder``. + +.. code:: python + + # Required imports + from automata.symbol_embedding.builders import SymbolCodeEmbeddingBuilder + from automata.symbol.base import Symbol + from automata.embedding.base import EmbeddingVectorProvider + + # Instantiate embedding vector provider + embedding_provider = EmbeddingVectorProvider() # Replace with specific instance of embedding vector provider. + + # Instantiate SymbolCodeEmbeddingBuilder + embedding_builder = SymbolCodeEmbeddingBuilder(embedding_provider) + + # Define the source code and symbol + source_code = "def hello_world():\n print('Hello, world!')" + symbol = Symbol.from_string("scip-python python HelloWorld 1a2b3c HelloWorld#") + + # Build the SymbolCodeEmbedding + code_embedding = embedding_builder.build(source_code, symbol) + +Limitations +----------- + +One limitation with the ``SymbolCodeEmbeddingBuilder`` is that the +quality of the ``SymbolCodeEmbedding`` that it builds is highly +dependent on the ``EmbeddingVectorProvider`` used. Different providers +may create different quality embeddings. + +Another limitation is that word, line, symbol, variable or class usages +that span across different files or projects may not be embedded or +tracked correctly. + +Follow-up Questions: +-------------------- + +- What makes a good ``EmbeddingVectorProvider``? +- What are the trade-offs of relying on ``SymbolCodeEmbedding`` vs + simpler forms of text representations such as Bag of Words or TF-IDF? +- How does the builder handle different scopes in python source code + (i.e. local, global, nonlocal, class scopes)? + +Note: +----- + +This example assumes there’s an implementation of +EmbeddingVectorProvider available. In actuality, you might need to +implement a specific Embedding Provider or use a third-party library. diff --git a/docs/symbol_embedding/symbol_doc_embedding.rst b/docs/symbol_embedding/symbol_doc_embedding.rst new file mode 100644 index 00000000..2cddcdce --- /dev/null +++ b/docs/symbol_embedding/symbol_doc_embedding.rst @@ -0,0 +1,79 @@ +SymbolDocEmbedding +================== + +``SymbolDocEmbedding`` is a class in Automata for embedding documents +related to symbols. Each instance of ``SymbolDocEmbedding`` represents a +specific symbol document embedding, with a given symbol, document, +vector, and optional source code, summary, and context. + +Overview +-------- + +``SymbolDocEmbedding`` helps with connecting metadata about symbols, for +example, linking documentation or source code to the symbol. This +process aids in maintaining semantic associations between pieces of +code, enhancing document retrieval and category analysis functions in +the Automata system. + +Related Symbols +--------------- + +- ``automata.tests.unit.sample_modules.sample.OuterClass.InnerClass`` +- ``automata.tests.unit.sample_modules.sample.OuterClass`` +- ``automata.tests.unit.sample_modules.sample.OuterClass.InnerClass.inner_method`` +- ``automata.symbol_embedding.builders.SymbolDocEmbeddingBuilder`` +- ``automata.tests.unit.test_py_reader.test_get_docstring_nested_class_method`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler.get_embedding`` +- ``automata.tests.unit.test_py_reader.test_get_docstring_nested_class`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.tests.unit.test_py_reader.test_get_docstring_no_docstring_class`` + +Example +------- + +The following is an example demonstrating how to create an instance of +``SymbolDocEmbedding``. + +.. code:: python + + from automata.symbol_embedding.base import SymbolDocEmbedding + from automata.symbol.base import Symbol + import numpy as np + + symbol = Symbol.from_string('scip-python python automata') + document = 'Sample document' + vector = np.array([1,2,3]) + source_code = 'def sample(): pass' + summary = 'Sample function' + + embedding = SymbolDocEmbedding(symbol, document, vector, source_code, summary) + +Limitations +----------- + +``SymbolDocEmbedding`` class requires connection to a running instance +of the Automata system as it connects to its database to retrieve and +process embedding vector and metadata. It may not offer versatility to +work with other database or storage methods. + +Moreover, it is reliant on the numpy library for vector storage, and may +not adapt to alternative vector representations out of the box. + +Dependencies +~~~~~~~~~~~~ + +This class relies on the +``automata.symbol_embedding.base.SymbolEmbedding`` and +``automata.symbol.base.Symbol`` classes. + +Follow-up Questions: +-------------------- + +- What functionality does ``SymbolDocEmbedding`` offer for error + checking or handling missing metadata elements? +- How would the ``SymbolDocEmbedding`` handle embeddings for symbols + sourced from external Python libraries outside Automata’s codebase? +- What considerations should be made if we want to use a different + library other than numpy for vector representation and manipulation? +- How would the ``SymbolDocEmbedding`` work in an environment without a + database or when disconnected from the Automata system? diff --git a/docs/symbol_embedding/symbol_doc_embedding_builder.rst b/docs/symbol_embedding/symbol_doc_embedding_builder.rst new file mode 100644 index 00000000..bfede487 --- /dev/null +++ b/docs/symbol_embedding/symbol_doc_embedding_builder.rst @@ -0,0 +1,89 @@ +SymbolDocEmbeddingBuilder +========================= + +``SymbolDocEmbeddingBuilder`` is a class that creates documentation +embeddings for a given ``Symbol``. This class exists in the +``automata.symbol_embedding.builders`` package. It is crucial in +understanding and building the context surrounding primary symbols in +the code. + +Overview +-------- + +``SymbolDocEmbeddingBuilder`` is used to build an embedding for a +symbol’s documentation. It generates a search list for related context, +accumulates documentation from retrieval sources, and then creates an +embedding from the final document. This class works in combination with +other classes such as ``EmbeddingVectorProvider``, +``LLMChatCompletionProvider``, ``SymbolSearch``, and +``PyContextRetriever``. + +Related Symbols +--------------- + +- ``automata.embedding.base.EmbeddingBuilder`` +- ``automata.embedding.base.EmbeddingVectorProvider`` +- ``automata.retrievers.py.context.PyContextRetriever`` +- ``automata.llm.foundation.LLMChatCompletionProvider`` +- ``automata.experimental.search.symbol_search.SymbolSearch`` +- ``automata.symbol_embedding.base.SymbolDocEmbedding`` + +Examples +-------- + +The following is a basic example demonstrating how the +``SymbolDocEmbeddingBuilder`` would be used to create documentation +embeddings for a symbol. + +.. code:: python + + from automata.symbol_embedding.builders import SymbolDocEmbeddingBuilder + from automata.embedding.base.EmbeddingVectorProvider import MyEmbeddingVectorProvider + from automata.llm.foundation import MyLLMChatCompletionProvider + from automata.experimental.search.symbol_search import MySymbolSearch + from automata.retrievers.py.context import PyContextRetriever + + embedding_provider = MyEmbeddingVectorProvider(...) + completion_provider = MyLLMChatCompletionProvider(...) + symbol_search = MySymbolSearch(...) + retriever = PyContextRetriever(...) + + builder = SymbolDocEmbeddingBuilder( + embedding_provider=embedding_provider, + completion_provider=completion_provider, + symbol_search=symbol_search, + retriever=retriever + ) + + source_code = """ + def my_func(): + \"\"\"This is a sample function.\"\"\" + return 5 + """ + + symbol = Symbol.from_string(...) + result = builder.build(source_code, symbol) + +Where all the ``My...`` objects are various classes of those types. + +Please note that the actual class names and instantiation will depend on +the specific embedding provider, completion provider, symbol_search, and +retriever that you use. + +Limitations +----------- + +While extremely useful for creating documentation embeddings, +``SymbolDocEmbeddingBuilder`` should be used with due consideration of +its potential limitations. The quality and accuracy of the embeddings +depend heavily on the underlying ``EmbeddingVectorProvider`` and +``LLMChatCompletionProvider`` used. + +Follow-up Questions: +-------------------- + +- What is the expected format and content of the ``Symbol`` object? +- How does the ``SymbolSearch`` class affect the output of + ``SymbolDocEmbeddingBuilder``? +- How can we optimize the source code to XML transformation in + ``PyContextRetriever`` for better results? diff --git a/docs/symbol_embedding/symbol_embedding.rst b/docs/symbol_embedding/symbol_embedding.rst new file mode 100644 index 00000000..c6f9dd8d --- /dev/null +++ b/docs/symbol_embedding/symbol_embedding.rst @@ -0,0 +1,88 @@ +SymbolEmbedding +=============== + +``SymbolEmbedding`` is an abstract base class designed for the handling +of symbol code embeddings within the Automata framework. In machine +learning and natural language processing, embeddings represent data such +as words, sentences, or symbols as vectors in high-dimensional space. +These vector representations capture the inherent relationships and +features of the original data in a format that can be efficiently +processed by machine learning algorithms. The ``SymbolEmbedding`` class +abstracts the embedding process for code symbols, representing them as +vectors that can be further used for tasks such as code analysis, +search, or semantic reasoning. + +Overview +-------- + +The ``SymbolEmbedding`` class defines a standard interface for symbol +embeddings by providing an initiation method and an abstract string +representation method. It provides property and setter methods for the +symbol key, allowing for flexible usage and the potential for future +extensions. This class needs to be inherited and the abstract methods +need to be implemented to make a concrete class for specific types of +symbol embeddings. + +Related Symbols +--------------- + +- ``SymbolEmbedding`` is the base class for ``SymbolCodeEmbedding`` and + ``SymbolDocEmbedding``, which are concrete implementations of symbol + embeddings for code symbols and document symbols respectively. + +- ``SymbolCodeEmbeddingHandler`` is a class that handles the embedding + of code symbols, which uses ``SymbolCodeEmbedding``. + +- ``SymbolDocEmbeddingHandler`` is a class to handle the embedding of + document symbols, which uses ``SymbolDocEmbedding``. + +Usage Example +------------- + +Here’s an example of how a subclass ``SymbolCodeEmbedding`` inherits +from ``SymbolEmbedding``. Note that as ``SymbolEmbedding`` is an +abstract class, it can’t be instantiated directly. + +.. code:: python + + from automata.symbol_embedding.base import SymbolEmbedding, Symbol + import numpy as np + + class SymbolCodeEmbedding(SymbolEmbedding): + def __init__(self, symbol: Symbol, source_code: str, vector: np.ndarray): + super().__init__(symbol, source_code, vector) + + def __str__(self) -> str: + return f"SymbolCodeEmbedding for Symbol: {self.symbol}, with vector: {self.vector}" + +Create an instance of ``SymbolCodeEmbedding``: + +.. code:: python + + from automata.symbol.base import Symbol + symbol = Symbol.from_string("Sample symbol string") + vector = np.array([1, 0, 0, 0]) + embedding_instance = SymbolCodeEmbedding(symbol, "source code", vector) + +Print Embedding: + +.. code:: python + + print(embedding_instance) + +Limitations +----------- + +The class in itself does not perform any computations for symbol +embedding, but it sets an interface for what methods an embedding class +should implement. Therefore, the actual effectiveness of the embedding +is dependent on the concrete implementation of methods in the subclasses +like ``SymbolCodeEmbedding`` and ``SymbolDocEmbedding``. + +Follow-up Questions: +-------------------- + +- What specific implementations are possible or planned for this + abstract class in the automata project itself? +- Are there any planned methods or enhancements for these embeddings, + such as embedding update or real-time learning of embeddings? diff --git a/docs/symbol_embedding/symbol_embedding_handler.rst b/docs/symbol_embedding/symbol_embedding_handler.rst new file mode 100644 index 00000000..5e164e03 --- /dev/null +++ b/docs/symbol_embedding/symbol_embedding_handler.rst @@ -0,0 +1,86 @@ +SymbolEmbeddingHandler +====================== + +``SymbolEmbeddingHandler`` is an abstract class in Automata’s codebase +that deals with handling the symbol embeddings. Symbols in this context +could refer to various elements of Python code like a class, a method or +a local variable. Embedding, in machine learning, refers to the +conversion of these symbols into a form that can be processed by machine +learning algorithms. + +The ``SymbolEmbeddingHandler`` class primarily consists of abstract +methods that need to be implemented by the specific child classes. This +class lays out the signature of the key methods that any symbol +embedding handler should implement. + +Overview +-------- + +The core methods in this class include an abstract constructor for +initial settings of the embedding database and embedding builder, a +method to filter symbols based on given sets, and methods to get and +process symbols’ embeddings. The class also fetches embeddings in the +order they were added through ``get_ordered_embeddings()``. + +It must be noted that ``get_embedding()`` and ``process_embedding()`` +are abstract methods that are intended to be overridden by the child +classes, hence the actual functionality would depend on the specific +implementation in those classes. + +Related Symbols +--------------- + +- ``JSONSymbolEmbeddingVectorDatabase``: A database handler class for + symbol embeddings with a JSON backend. +- ``EmbeddingBuilder``: An abstract class meant to build embeddings. It + must be implemented in child classes to give actual embeddings. +- ``SymbolDocEmbeddingHandler``: A child class that handles the + database of SymbolDoc embeddings. +- ``SymbolCodeEmbeddingHandler``: Another child class that manages a + database for ``Symbol`` source code embeddings. + +Example +------- + +While the ``SymbolEmbeddingHandler`` class cannot be instantiated +directly as it is an abstract class, the child classes such as +``SymbolDocEmbeddingHandler`` or ``SymbolCodeEmbeddingHandler`` can be +instantiated and used in a similar manner as shown below: + +.. code:: python + + # Mock EmbeddingBuilder and JSONSymbolEmbeddingVectorDatabase + mock_provider = Mock(EmbeddingBuilder) + mock_db = MagicMock(JSONSymbolEmbeddingVectorDatabase) + + # Create an instance of SymbolCodeEmbeddingHandler + embedding_handler = SymbolCodeEmbeddingHandler(embedding_builder=mock_provider, embedding_db=mock_db) + + # Use the get_embedding method + symbol_embedding = embedding_handler.get_embedding(Symbol("test")) + +Please note in this above example, ``Mock`` and ``MagicMock`` are +placeholders and for an actual implementation, you would substitute +``EmbeddingBuilder`` and ``JSONSymbolEmbeddingVectorDatabase`` with +their actual implementations. + +Limitations +----------- + +- As ``SymbolEmbeddingHandler`` is an abstract class, it doesn’t have + direct functionality and can’t be instantiated. The child classes + provide actual functionality. +- The specific embeddings for a symbol and the operations for + processing it completely depend on the actual implementation provided + in child classes. Therefore, the quality and performance of these + encodings would depend on the specific child classes and their + implementation. + +Follow-up Questions +------------------- + +- What specific child classes are implemented for + ``SymbolEmbeddingHandler`` and how do they differ in their + functionalities? +- How are the embeddings stored and processed in the database in the + current implementations? diff --git a/docs/tasks/automata_agent_task_database.rst b/docs/tasks/automata_agent_task_database.rst new file mode 100644 index 00000000..0b62b4c0 --- /dev/null +++ b/docs/tasks/automata_agent_task_database.rst @@ -0,0 +1,111 @@ +AutomataAgentTaskDatabase +========================= + +``AutomataAgentTaskDatabase`` is a class that provides the ability to +manage tasks in a local storage database. + +Overview +-------- + +The ``AutomataAgentTaskDatabase`` class, inherited from ``SQLDatabase``, +serves as a local storage for all ``AutomataTask`` objects. It features +functionality to check if a particular task exists in the database, +retrieve tasks based on a given query, insert new tasks, and update +existing tasks. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_task_database.db`` +- ``automata.tests.conftest.task`` +- ``automata.tasks.agent_database.AutomataTaskRegistry.__init__`` +- ``automata.tests.unit.test_automata_agent_builder.test_automata_agent_init`` +- ``automata.tasks.agent_database.AutomataTaskRegistry`` +- ``automata.tests.unit.test_task.test_deterministic_task_id`` +- ``automata.memory_store.agent_conversation_database.AgentConversationDatabase`` +- ``automata.tests.unit.test_task_database.task`` +- ``automata.tasks.tasks.AutomataTask`` +- ``automata.tests.unit.test_conversation_database.db`` + +Method Details +-------------- + +\__init\_\_(db_path: str = TASK_DB_PATH) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Connects to the SQL database at the provided database path. +- Creates a new table, if not existing, with a defined schema in the + connected database. + +contains(task: AutomataTask) -> bool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Checks if the task exists in the database. +- Returns ``True`` if the task exists, otherwise ``False``. + +get_tasks_by_query(query: str, params: Tuple = ()) -> List[AutomataTask] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Retrieves list of tasks by applying the specified SQL query. +- Returns a list of ``AutomataTask`` objects. + +insert_task(task: AutomataTask) -> None +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Inserts a new task into the database. + +update_task(task: AutomataTask) -> None +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Updates an existing task in the database. + +Example +------- + +This Python library does not provide direct examples of +``AutomataAgentTaskDatabase`` usage. However, the usage of this class is +indirectly shown through its use in test fixtures and various other +parts of the code. Here is a constructed example demonstrating a basic +usage: + +.. code:: python + + from automata.tasks.agent_database import AutomataAgentTaskDatabase + from automata.tasks.tasks import AutomataTask + + # Instantiate AutomataTask + task = AutomataTask( + repo_manager=None, + config_to_load="TEST", + generate_deterministic_id=False, + instructions="This is a test." + ) + + # Initialize Task Database + db = AutomataAgentTaskDatabase() + + # Insert task + db.insert_task(task) + + # Verify insertion + assert db.contains(task) == True + +Limitations +----------- + +The primary limitation of ``AutomataAgentTaskDatabase`` is that it is +reliant on the ``AutomataTask`` object structure. Any changes in the +``AutomataTask`` definition may require changes in this class. + +Also, operations like getting tasks by query may fail in complex +scenarios due to data serialization. A more robust error checking +mechanism might be required. + +Follow-up Questions: +-------------------- + +- It would be beneficial to provide a mechanism to delete tasks from + the database, is there a plan for this feature? +- Handling the exception in ``get_tasks_by_query`` function currently + only logs the error. Would it make sense to propagate the error to + the caller? diff --git a/docs/tasks/automata_task.rst b/docs/tasks/automata_task.rst new file mode 100644 index 00000000..cdbc968f --- /dev/null +++ b/docs/tasks/automata_task.rst @@ -0,0 +1,68 @@ +AutomataTask +============ + +``AutomataTask`` class is designed to be executed by the TaskExecutor. +The tasks initiated by this class are set up with instructions and a +path to a root python folder. + +Overview +-------- + +``AutomataTask`` manages tasks to be executed by initializing its +properties and validating its instructions. It also manages the logging +for the task by creating a log file in the task directory and fetches +log content. The class utilizes parent class ``Task`` from +``automata.tasks.base`` to handle the underlying procedures. + +Related Symbols +--------------- + +- ``automata.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tasks.agent_database.AutomataTaskRegistry.get_all_tasks`` +- ``automata.tasks.agent_database.AutomataAgentTaskDatabase.insert_task`` +- ``automata.tasks.executor.IAutomataTaskExecution`` + +Example +------- + +Examples on how to create instances of ``AutomataTask``: + +.. code:: python + + from automata.tasks.tasks import AutomataTask + + task = AutomataTask("task1", instructions="instruction1") + +.. code:: python + + from automata.tasks.tasks import AutomataTask + from tests.mocks import MockRepositoryClient + from config.config_enums import AgentConfigName + + repo_manager = MockRepositoryClient() + + task = AutomataTask( + repo_manager, + config_to_load=AgentConfigName.TEST.value, + generate_deterministic_id=False, + instructions="This is a test.", + ) + +Limitations +----------- + +``task_id`` generated here can take either a deterministic form based on +the hash of hashable keyword arguments or a random ``uuid`` depending on +the ``generate_deterministic_id`` flag. There’s no way to provide a +custom method of generating task_id. + +``AutomataTask`` assumes the python folder is in the root folder, which +can limit the extraction of python files if the directory structure +changes. + +Follow-up Questions +------------------- + +- Can a custom task_id generation method be facilitated? +- Can the assumption of the python folder being in the root folder be + eliminated, making it more robust? diff --git a/docs/tasks/automata_task_environment.rst b/docs/tasks/automata_task_environment.rst new file mode 100644 index 00000000..2b507e3c --- /dev/null +++ b/docs/tasks/automata_task_environment.rst @@ -0,0 +1,81 @@ +AutomataTaskEnvironment +======================= + +``AutomataTaskEnvironment`` is a concrete implementation of the Abstract +``TaskEnvironment`` specifically for automating task management in a +GitHub repository. + +Overview +-------- + +``AutomataTaskEnvironment`` is built on a task management environment +that is integrated with the GitHub repository system making it ideal for +managing and supervising ``AutomataTask`` objects. It provides +functionalities such as committing tasks to a remote repository, setting +up the environment by cloning the needed repository, as well as several +methods that await implementation like resetting, validating and tearing +down the environment. + +Related Symbols +--------------- + +- ``automata.tests.conftest.environment`` +- ``automata.tests.unit.test_task_database.task`` +- ``automata.tasks.tasks.AutomataTask`` +- ``automata.tests.conftest.task`` +- ``automata.tasks.base.TaskEnvironment`` +- ``automata.tests.unit.test_task_executor.test_execute_automata_task_success`` +- ``automata.tasks.executor.IAutomataTaskExecution`` +- ``automata.tests.unit.test_task_executor.test_execute_automata_task_fail`` +- ``automata.agent.providers.OpenAIAutomataAgent`` +- ``automata.tests.unit.test_task.test_callback`` + +Example +------- + +The following is an example of how to use ``AutomataTaskEnvironment`` to +commit ``AutomataTask``: + +.. code:: python + + from automata.github_management.client import GitHubClient + from automata.tasks.environment import AutomataTaskEnvironment + from automata.tasks.tasks import AutomataTask + + github_manager = GitHubClient(access_token = "your_access_token_here", remote_name = "your_remote_name_here", primary_branch = "main") + task_env = AutomataTaskEnvironment(github_manager) + + task = AutomataTask("task_name", instructions="list_of_instructions") + + commit_message = "task commit" + pull_title = "pull request title" + pull_body = "pull request body" + pull_branch_name = "branch name" + + # commit the task. + task_env.commit_task(task, commit_message, pull_title, pull_body, pull_branch_name) + + # If successful, the method returns the pull request URL. + +Please note that this code assumes that you have API access to a GitHub +repository, and you can get an access token from GitHub’s settings under +the developer settings -> Personal access tokens. + +Limitations +----------- + +The ``AutomataTaskEnvironment`` class currently has several methods +unimplemented like resetting, validating and tearing down the +environment which leads to reduced functionality. Additionally, it is +also dependant on the GitHub manager leading to potential problems with +other types of repositories. + +Follow-up Questions: +-------------------- + +- Will the missing methods like ``reset``, ``validate``, ``teardown`` + be implemented in future versions of this class? +- How can we accommodate other types of repositories apart from GitHub + in this class? +- Can we enhance the error handling mechanism to provide more specific + feedback on failure? diff --git a/docs/tasks/automata_task_executor.rst b/docs/tasks/automata_task_executor.rst new file mode 100644 index 00000000..bd92883e --- /dev/null +++ b/docs/tasks/automata_task_executor.rst @@ -0,0 +1,82 @@ +AutomataTaskExecutor +==================== + +``AutomataTaskExecutor`` is a class that adopts ``ITaskExecution`` +behavior for executing an ``AutomataTask``. It executes the task +following the behavior specified in the execution instance provided +during the initialization of ``AutomataTaskExecutor``. The task +execution can go through multiple stages with different ``TaskStatus`` +such as ``PENDING``, ``RUNNING``, ``SUCCESS``, etc. If a task fails and +does not exceed the maximum retries, it will be retried after a period +of ‘exponential backoff’ time. + +Overview +-------- + +AutomataTaskExecutor is intended to execute an ``AutomataTask`` +following the ``ITaskExecution`` interface standards. The execution of +the task is carried out by the ``execute`` method of the task execution +instance, which raises exceptions if the task is not in the ``PENDING`` +status or if the task fails exceeding the maximum retries. + +Related Symbols +--------------- + +- ``ITaskExecution`` +- ``TaskStatus`` +- ``AutomataTask`` +- ``AutomataTaskEnvironment`` +- ``AutomataTaskRegistry`` + +Example +------- + +The following is an example demonstrating how to use +``AutomataTaskExecutor`` to execute an ``AutomataTask``. + +.. code:: python + + from automata.tasks.executor import AutomataTaskExecutor + from automata.tasks.tasks import AutomataTask + from automata.tests.unit.test_task_executor import TestExecuteBehavior + + # Create an AutomataTask instance + my_task = AutomataTask( + title="Task 1", + instructions="Perform task 1", + max_retries=5 + ) + + # Create a TestExecuteBehavior instance + test_execution_behavior = TestExecuteBehavior() + + # Create an AutomataTaskExecutor instance + task_executor = AutomataTaskExecutor(test_execution_behavior) + + # Execute the task + task_executor.execute(my_task) + +This will execute the ``AutomataTask`` with the behavior specified in +``TestExecuteBehavior``. + +Limitations +----------- + +``AutomataTaskExecutor`` relies heavily on the provided +``ITaskExecution`` behavior passed during its instantiation. If the +execution behavior doesn’t correctly implement the ``execute`` method, +the task execution might not work as intended. + +``AutomataTaskExecutor`` also requires the task to be in a ``PENDING`` +status to be successfully executed. Therefore, tasks that aren’t in the +``PENDING`` status would require explicit modification before the +execution. + +Follow-up Questions: +-------------------- + +- How do we handle exceptions raised by other parts of the + ``ITaskExecution`` process? +- Are there specific rules for exponential backoff time? +- Can tasks in other states (like ``SUCCESS``, ``FAILED``, etc.) be + re-executed? diff --git a/docs/tasks/automata_task_registry.rst b/docs/tasks/automata_task_registry.rst new file mode 100644 index 00000000..d89305b7 --- /dev/null +++ b/docs/tasks/automata_task_registry.rst @@ -0,0 +1,64 @@ +AutomataTaskRegistry +==================== + +Overview +-------- + +``AutomataTaskRegistry`` is a manager class that manages storing and +fetching tasks. It interacts with an instance of +``AutomataAgentTaskDatabase`` to fetch task by id, perform operations +like registering a task, getting all tasks, and updating a task in +registry. It also ensures that tasks are in the correct state to be +executed. + +Related Symbols +--------------- + +- ``AutomataAgentTaskDatabase`` +- ``AgentTaskGeneralError`` +- ``AgentTaskStateError`` +- ``TaskStatus`` +- ``AutomataTask`` + +Example +------- + +.. code:: python + + from automata.tasks.agent_database import AutomataTaskRegistry + from automata.tests.unit.test_task_database import task + + # Creating a task + task = task() + + # Fetching a task using registry + registry = AutomataTaskRegistry(db_path) + fetched_task = registry.fetch_task_by_id(task.task_id) + + # Getting all tasks using registry + all_tasks = registry.get_all_tasks() + + # Registering a task using registry + registry.register(task) + + # Updating task using registry + registry.update_task(task) + +Note: We assume that ``db_path`` is a string indicating the correct path +to the task database. + +Limitations +----------- + +While ``AutomataTaskRegistry`` is capable of managing tasks, the user +must ensure that the tasks are in the correct state to be executed +(e.g., registered and not in a errored state). If a task is flagged as +errored, it would be necessary to manually change the task’s state. + +Follow-up Questions: +-------------------- + +- How should error-handling be incorporated during the task execution + process to avoid corrupted or faulty tasks? +- How should tasks be retrieved if a faulty task has been inserted into + the database? diff --git a/docs/tasks/i_automata_task_execution.rst b/docs/tasks/i_automata_task_execution.rst new file mode 100644 index 00000000..c7f754cb --- /dev/null +++ b/docs/tasks/i_automata_task_execution.rst @@ -0,0 +1,91 @@ +IAutomataTaskExecution +====================== + +Overview +-------- + +``IAutomataTaskExecution`` is a class designed for executing general +tasks by creating and running an ``AutomataAgent``. It implements the +``execute`` method from the ``ITaskExecution`` interface, and is used to +manage the execution process of a given task, handle failures and update +task’s status. + +Related Symbols +--------------- + +1. ``AutomataTask``: A task object that is consumed by the + ``IAutomataTaskExecution`` for execution. ``AutomataTask`` is a form + of ``Task`` which is built to be executed by ``TaskExecutor``. + +2. ``OpenAIAutomataAgent``: An autonomous agent designed to execute + instructions and report the results back to the main system. It + communicates with the OpenAI API to generate responses based on given + instructions. + +3. ``TaskStatus``: Enum representing the status of a task (RUNNING, + COMPLETED, ERROR, etc.) It is used by ``IAutomataTaskExecution`` to + mark the status of the task at different stages of its execution. + +4. ``AutomataTaskExecutor``: A class for using + ``IAutomataTaskExecution`` behavior to execute a task. It essentially + executes the ``AutomataTask`` with the given + ``IAutomataTaskExecution`` implementation. + +5. ``AgentTaskGeneralError``: An exception raised when a general error + occurs during task execution. + +Usage Example +------------- + +.. code:: python + + from automata.tasks.executor import IAutomataTaskExecution + from automata.tasks.tasks import AutomataTask + + # Construct an Automata Task + task = AutomataTask(name="custom_task", instructions="execute something") + + # Instantiate IAutomataTaskExecution and execute task + task_execution = IAutomataTaskExecution() + task_execution.execute(task) + +Discussion +---------- + +``IAutomataTaskExecution`` manages the execution of a given +``AutomataTask``. It attempts to run an ``OpenAIAutomataAgent`` with the +``AutomataTask``, updating the task’s status throughout the execution. +If the execution of the task fails, the task’s retry count is +incremented. Once the maximum number of retries is reached, the task is +then marked as failed. + +When a task is passed to the ``execute`` method, an ``AutomataAgent`` is +built, and set to run the task. If the task execution succeeds, the +task’s status is set to ‘SUCCESS’ and the task’s result attribute is +populated by the result of the ``AutomataAgent`` run. If an exception +occurs, the task’s status is set to ‘FAILED’, its error attribute is +populated with the error message, its retry count incremented, and the +exception is raised. + +It is important to note that ``IAutomataTaskExecution`` requires a +``AutomataTask``, if a different type is passed it will throw an +``AgentTaskGeneralError``. + +Limitations +----------- + +``IAutomataTaskExecution`` depends on ``AutomataTask`` class for tasks, +thus cannot consume tasks created by other types of ``Task`` classes. It +also depends heavily on ``OpenAIAutomataAgent`` for executing tasks, +providing limited flexibility for running tasks using different types of +agents. + +Follow-up Questions: +-------------------- + +- What happens when the ``AutomataTask`` execution continues to fail + even after maximum retry attempts? Is there a system in place to + handle this scenario? +- How is the maximum retry count decided and can it be customized? +- Can ``IAutomataTaskExecution`` support other types of tasks apart + from ``AutomataTask`` in the future? diff --git a/docs/tasks/i_task_execution.rst b/docs/tasks/i_task_execution.rst new file mode 100644 index 00000000..caa7f18a --- /dev/null +++ b/docs/tasks/i_task_execution.rst @@ -0,0 +1,66 @@ +ITaskExecution +============== + +``ITaskExecution`` is an interface specifying the behavior for task +execution in the ``automata.tasks`` module. It provides an abstract +method ``execute`` which defines how a task object should be executed. + +Overview +-------- + +As an abstract base class (ABC), ``ITaskExecution`` does not include any +concrete implementations. Instead, it presents a method signature for +``execute`` to guide and enforce interface in inheriting classes. This +class ensures that all task execution behaviors adhere to a standard +protocol facilitating code reuse, modularity, and comprehensibility. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_task_executor.TestExecuteBehavior`` +- ``automata.tasks.executor.AutomataTaskExecutor`` +- ``automata.tasks.executor.IAutomataTaskExecution`` +- ``automata.tasks.base.Task`` +- ``automata.tasks.base.TaskStatus`` + +Example +------- + +Inheriting classes must implement the ``execute`` method. Below is an +example of the ``TestExecuteBehavior`` class that provides a concrete +implementation of the ``execute`` method. + +.. code:: python + + from automata.tasks.base import ITaskExecution, Task + + class TestExecuteBehavior(ITaskExecution): + """ + Class for executing test tasks. + """ + + def execute(self, task: Task): + # execution logic goes here + task.result = "Test result" + +In this example, the ``execute`` method modifies the ``result`` +attribute of the ``task`` argument. Typical cases would differ depending +on the complexity and requirements of the task to be executed. + +Limitation +---------- + +The primary limitation of ``ITaskExecution`` is that it only stipulates +how to handle task execution but does not provide any concrete +implementation. Thus, it relies on the classes that implement the +interface to provide the actual task execution behavior. This includes +the error handling and reporting strategy during the execution of tasks. + +Follow-up Questions +------------------- + +- What kind of tasks are the ``ITaskExecution`` and its children + classes meant to handle? +- How can error handling be standardized across all classes that + implement this interface? Is there a need for a standard strategy or + should error handling be left to the concrete implementation? diff --git a/docs/tasks/index.rst b/docs/tasks/index.rst new file mode 100644 index 00000000..1afb4e30 --- /dev/null +++ b/docs/tasks/index.rst @@ -0,0 +1,32 @@ +tasks +===== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + automata_agent_task_database + automata_task + automata_task_environment + automata_task_executor + automata_task_registry + i_automata_task_execution + i_task_execution + task + task_environment + task_status + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/tasks/task.rst b/docs/tasks/task.rst new file mode 100644 index 00000000..b71d3394 --- /dev/null +++ b/docs/tasks/task.rst @@ -0,0 +1,73 @@ +Task +==== + +``Task`` is a primary object used by ``TaskExecutor`` in the Automata +library. The ``Task`` object is responsible for storing the task id, +priority, max retries, and delivering task-oriented action to the +respective task function when the task is executed. In addition to +these, it also contains a method to generate a deterministic task id +which is based on the hash of the hashable keyword arguments. + +Overview +-------- + +The ``Task`` plays a pivotal role in task execution by storing the +necessary details about the task. By default, it assigns unique +identifiers generated by the universally unique identifier (uuid) +module. However, you have the option to generate a deterministic id +based on the hash of the hashable keyword arguments. + +Note that the task status will be noted by ``TaskExecutor`` as it +proceeds to execute different stages. This task status is retrievable +using the status property of the class. Furthermore, you can set the +status of the task using the status setter property. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_task_database.task`` +- ``automata.tests.unit.test_task_environment.test_commit_task`` +- ``automata.tasks.tasks.AutomataTask`` +- ``automata.tests.unit.test_task_database.test_get_tasks_by_query`` +- ``automata.tasks.base.ITaskExecution.execute`` +- ``automata.tests.unit.test_task_database.test_update_task`` +- ``automata.tests.unit.test_task_database.test_database_lifecycle`` +- ``automata.tests.unit.test_task_database.test_insert_task`` +- ``automata.tasks.base.ITaskExecution`` +- ``automata.tests.conftest.registry`` + +Usage Example +------------- + +.. code:: python + + from automata.tasks.base import Task + + task = Task(priority=1, max_retries=5) + print(f"ID of the created task: {task.task_id}") + +Limitations +----------- + +The current design does not allow to retrieve the task id, priority and +max retries once the task object is initialized. If you need to retrieve +these properties, you will need to capture these values during task +initialization. + +If a task status is set to ``RETRYING``, and if the maximum retries set +is exceeded, the task status will be marked ``FAILED``. In case, the +application logic requires further retries despite the retry limit, you +will need to create a new Task instance with the required parameters and +execute it as a fresh task. + +Follow-up Questions +------------------- + +- Can we include mechanism that would enable us to retrieve the initial + properties of Task object, such as task id, priority and max_retries + once initialized? +- Should we allow indefinite retries despite exceeding the maximum + retry limit? If yes, what would be the best approach to implement + this feature? +- Should there be an option to reset the status of the task back to its + original state in case of failure in execution? diff --git a/docs/tasks/task_environment.rst b/docs/tasks/task_environment.rst new file mode 100644 index 00000000..870bc6bb --- /dev/null +++ b/docs/tasks/task_environment.rst @@ -0,0 +1,85 @@ +TaskEnvironment +=============== + +Overview +-------- + +The TaskEnvironment is an abstract base class which provides an +interface for defining a context in which tasks are executed. It has +four abstract methods - ``reset``, ``setup``, ``teardown`` and +``validate``. As an abstract base class, it must be subclassed and its +methods implemented. + +Related Symbols +--------------- + +- ``automata.tests.conftest.environment`` +- ``automata.tests.unit.test_task_environment.test_commit_task`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tests.conftest.task`` +- ``automata.tests.unit.test_task_database.db`` +- ``automata.tasks.environment.AutomataTaskEnvironment.teardown`` +- ``automata.tests.unit.test_task_executor.test_execute_automata_task_success`` +- ``automata.tests.unit.test_task_executor.test_execute_automata_task_fail`` +- ``automata.tasks.base.Task`` + +Example +------- + +The following is a class that extends from TaskEnvironment and +implements its abstract methods: + +.. code:: python + + from automata.tasks.base import TaskEnvironment + + class MyEnvironment(TaskEnvironment): + + def reset(self): + """Reset the environment to its initial state.""" + pass + + def setup(self, task): + """Set up the environment.""" + pass + + def teardown(self): + """Tear down the environment.""" + pass + + def validate(self): + """Validate the environment.""" + pass + +After creating the subclass, you can use it to create an object and call +its methods: + +.. code:: python + + env = MyEnvironment() + env.setup(task) + # Do some operations... + env.teardown() + +Note: In the real implementation, you would likely put some real logic +into the methods ``reset``, ``setup``, ``teardown``, and ``validate``. + +Limitations +----------- + +The TaskEnvironment class is only useful as a superclass for other +classes. It does not offer any functionality on its own because it only +defines an interface without any concrete implementation. The +limitations of a TaskEnvironment will therefore depend on the specific +subclass that implements its methods. + +Follow-up Questions +------------------- + +- Are there any expectations or requirements for the implementations of + the ``setup`` and ``teardown`` methods? +- Are there any specific conditions which would make the ``validate`` + method return False? +- There seems to be test setup data included in the context, though + it’s not clear how or if it should be included in the final + documentation. diff --git a/docs/tasks/task_status.rst b/docs/tasks/task_status.rst new file mode 100644 index 00000000..c75b35ba --- /dev/null +++ b/docs/tasks/task_status.rst @@ -0,0 +1,71 @@ +TaskStatus +========== + +``TaskStatus`` is a crucial component of the ``Task`` object which +represents its current status or stage in the task management process. +This enum value is updated by the task executor as the task progresses +and changes state. Multiple states ``TaskStatus`` can represent include +``CREATED``, ``REGISTERED``, ``RETRYING``, ``SUCCESS`` and others. + +Overview +-------- + +A ``Task`` object’s status is set initially to ``TaskStatus.CREATED`` +and as the task is processed by the task executor or the automata +environment, its status gets updated to indicates its progress. Status +like ``RETRYING`` is used when a task failure occurs and a retry attempt +is being made, ``SUCCESS`` when the task completes successfully, +``REGISTERED`` when the task is registered into the system. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_task.test_status_setter`` +- ``automata.tests.unit.test_task.test_task_inital_state`` +- ``automata.tasks.base.Task.status`` +- ``automata.tests.unit.test_task_database.test_update_task`` +- ``automata.tasks.base.Task`` +- ``automata.tests.unit.test_task_database.test_database_lifecycle`` +- ``automata.tasks.tasks.AutomataTask`` +- ``automata.tests.unit.test_task.test_register_task`` + +Example +------- + +The following is an example demonstrating how to set and change the +status of a ``Task``. + +.. code:: python + + from automata.tasks.base import Task + from automata.tasks.base import TaskStatus + + task = Task("Task1", "", priority=1) + print(task.status) # Should print: TaskStatus.CREATED + + task.status = TaskStatus.REGISTERED + print(task.status) # Should print: TaskStatus.REGISTERED + + task.status = TaskStatus.SUCCESS + print(task.status) # Should print: TaskStatus.SUCCESS + +Limitations +----------- + +There are no known limitations for ``TaskStatus``. It represents the +state of a task as it is processed, and has enough values to represent +important stages in a task’s lifecycle. + +Follow-up Questions: +-------------------- + +- What are the exact definitions and implications of each + ``TaskStatus``? +- Are there any considerations if new status values need to be added to + ``TaskStatus`` in the future? +- How are status transitions managed, ensuring a task status can’t + directly jump between non-sequential states (like from ``CREATED`` to + ``SUCCESS``)? (Note: Unit tests are often setup using ``mock`` + objects for complex operations like database interactions, network + calls etc. In some examples, these mocks are swapped with actual + objects as far as possible.) diff --git a/docs/tests/index.rst b/docs/tests/index.rst index b05e545a..21727bfa 100644 --- a/docs/tests/index.rst +++ b/docs/tests/index.rst @@ -19,6 +19,8 @@ how to :ref:`installation` the project. + + .. AUTO-GENERATED CONTENT START .. diff --git a/docs/tests/mock_repository_client.rst b/docs/tests/mock_repository_client.rst index eace626d..cbaaca34 100644 --- a/docs/tests/mock_repository_client.rst +++ b/docs/tests/mock_repository_client.rst @@ -20,12 +20,12 @@ tests for functionalities that involve interactions with a Related Symbols --------------- -- ``automata.core.github_management.client.RepositoryClient`` -- ``automata.core.github_management.client.GitHubClient`` +- ``automata.github_management.client.RepositoryClient`` +- ``automata.github_management.client.GitHubClient`` - ``automata.tests.conftest.environment`` - ``automata.tests.conftest.task`` -- ``automata.core.tasks.environment.AutomataTaskEnvironment`` -- ``automata.core.tasks.tasks.AutomataTask`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tasks.tasks.AutomataTask`` - ``automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder`` Example diff --git a/docs/tests/unit/index.rst b/docs/tests/unit/index.rst index 0ebdfee4..884c68bc 100644 --- a/docs/tests/unit/index.rst +++ b/docs/tests/unit/index.rst @@ -26,6 +26,8 @@ how to :ref:`installation` the project. + + diff --git a/docs/tests/unit/mock_code_generator.rst b/docs/tests/unit/mock_code_generator.rst index ff082bf2..86123378 100644 --- a/docs/tests/unit/mock_code_generator.rst +++ b/docs/tests/unit/mock_code_generator.rst @@ -55,9 +55,9 @@ Methods Related Symbols --------------- -- ``automata.core.code_handling.py.reader.PyReader`` -- ``automata.core.symbol_embedding.base.SymbolCodeEmbedding`` -- ``automata.core.code_handling.py.writer.PyWriter`` +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.symbol_embedding.base.SymbolCodeEmbedding`` +- ``automata.code_handling.py.writer.PyWriter`` Example ------- diff --git a/docs/tests/unit/test_execute_behavior.rst b/docs/tests/unit/test_execute_behavior.rst index b27b4b41..d74e2dc4 100644 --- a/docs/tests/unit/test_execute_behavior.rst +++ b/docs/tests/unit/test_execute_behavior.rst @@ -19,15 +19,15 @@ module file. Related Symbols --------------- -- ``automata.core.tasks.base.ITaskExecution`` +- ``automata.tasks.base.ITaskExecution`` - ``automata.tests.unit.test_task_executor.test_execute_automata_task_success`` - ``automata.tests.unit.test_task_executor.test_execute_automata_task_fail`` -- ``automata.core.tasks.executor.AutomataTaskExecutor`` -- ``automata.core.tasks.base.TaskStatus`` -- ``automata.core.tasks.tasks.AutomataTask`` -- ``automata.core.tasks.base.ITaskExecution.execute`` -- ``automata.core.code_handling.py.writer.PyWriter.create_new_module`` -- ``automata.core.tasks.base.Task`` +- ``automata.tasks.executor.AutomataTaskExecutor`` +- ``automata.tasks.base.TaskStatus`` +- ``automata.tasks.tasks.AutomataTask`` +- ``automata.tasks.base.ITaskExecution.execute`` +- ``automata.code_handling.py.writer.PyWriter.create_new_module`` +- ``automata.tasks.base.Task`` Example ------- @@ -37,8 +37,8 @@ execute a task in an Automata task executor. .. code:: python - from automata.core.tasks.base import Task - from automata.core.tasks.executor import AutomataTaskExecutor + from automata.tasks.base import Task + from automata.tasks.executor import AutomataTaskExecutor from automata.tests.unit.test_task_executor import TestExecuteBehavior # define a Task diff --git a/docs/tests/unit/test_tool.rst b/docs/tests/unit/test_tool.rst index 3e04c48b..ff5a34b4 100644 --- a/docs/tests/unit/test_tool.rst +++ b/docs/tests/unit/test_tool.rst @@ -18,15 +18,15 @@ Related Symbols --------------- - ``automata.tests.unit.test_tool.test_tool`` -- ``automata.core.tools.base.Tool`` +- ``automata.tools.base.Tool`` - ``automata.tests.unit.test_tool.test_tool_run`` -- ``automata.core.agent.providers.OpenAIAgentToolkitBuilder.can_handle`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder.can_handle`` - ``automata.tests.unit.test_tool.test_tool_instantiation`` -- ``automata.core.tasks.base.TaskStatus`` -- ``automata.core.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` -- ``automata.core.tools.builders.symbol_search.SearchTool`` +- ``automata.tasks.base.TaskStatus`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` +- ``automata.tools.builders.symbol_search.SearchTool`` - ``automata.tests.unit.test_symbol_search_tool.test_build`` -- ``automata.core.code_handling.py.reader.PyReader`` +- ``automata.code_handling.py.reader.PyReader`` Usage Example ------------- diff --git a/docs/tests/unit/test_url.rst b/docs/tests/unit/test_url.rst index adf533bc..e24deda3 100644 --- a/docs/tests/unit/test_url.rst +++ b/docs/tests/unit/test_url.rst @@ -16,15 +16,15 @@ arena, mostly for task committing operations. Related Symbols --------------- -- ``automata.core.tasks.base.TaskStatus`` +- ``automata.tasks.base.TaskStatus`` - ``automata.tests.unit.test_task_environment.test_commit_task`` -- ``automata.core.tools.base.Tool`` +- ``automata.tools.base.Tool`` - ``automata.tests.unit.test_tool.test_tool`` -- ``automata.core.tasks.tasks.AutomataTask`` +- ``automata.tasks.tasks.AutomataTask`` - ``automata.tests.unit.test_tool.test_tool_run`` -- ``automata.core.tasks.environment.AutomataTaskEnvironment.validate`` +- ``automata.tasks.environment.AutomataTaskEnvironment.validate`` - ``automata.tests.unit.test_tool.TestTool`` -- ``automata.core.tasks.environment.AutomataTaskEnvironment`` +- ``automata.tasks.environment.AutomataTaskEnvironment`` - ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` Example diff --git a/docs/tools/agent_tool_factory.rst b/docs/tools/agent_tool_factory.rst new file mode 100644 index 00000000..8a63cb31 --- /dev/null +++ b/docs/tools/agent_tool_factory.rst @@ -0,0 +1,73 @@ +AgentToolFactory +================ + +Overview +-------- + +The ``AgentToolFactory`` class is responsible for creating tools from a +given agent tool name. It leverages the system of agent tool names and +the registry of OpenAI Automata Agent toolkit builders to create and +manage tools. The primary methods of the ``AgentToolFactory`` are +``build_tools`` and ``create_tools_from_builder``, which are used for +generating tools and creating tools from builders respectively. + +Methods +------- + +The ``build_tools`` method creates a collection of tools given a list of +``toolkit_list`` tool names. It loops through the list of available tool +names, for each of them checks whether the agent tool manager can handle +it, and then applies the ``create_tools_from_builder`` function to +create the corresponding tool. + +The ``create_tools_from_builder`` function creates tools from a given +``agent_tool`` tool name. This tool name is passed into the builder’s +``can_handle`` function to confirm if the builder can create the +requested tool. Once verified, the tool is created using the builder’s +corresponding build function. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_tool.test_tool`` +- ``automata.tests.unit.test_tool.test_tool_instantiation`` +- ``automata.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry.register_tool_manager`` +- ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder`` + +Usage Example +------------- + +.. code:: python + + from automata.tools.factory import AgentToolFactory + from automata.agent.agent import AgentToolkitNames + + toolkit_list = ["tool_name1", "tool_name2"] + tools = AgentToolFactory.build_tools(toolkit_list) + +Limitations +----------- + +The ``AgentToolFactory`` is limited by the builders registered in the +``OpenAIAutomataAgentToolkitRegistry``. If a builder for a desired tool +isn’t registered yet or doesn’t exist, the ``AgentToolFactory`` won’t be +able to create that tool. + +Dependencies +------------ + +Some key dependencies include: + +- OpenAIAutomataAgentToolkitRegistry for querying the builder’s + registry. +- AgentToolkitNames for managing and validating tool names. +- OpenAIAgentToolkitBuilder for building the tools for the OpenAI + agent. + +Follow-up Questions: +-------------------- + +- How can we extend the ``AgentToolFactory`` to handle a wider range of + tools or to handle custom tools? +- Could there be a more efficient way to create enums from the tool + names instead of handling them as plan strings? diff --git a/docs/tools/base/config.rst b/docs/tools/base/config.rst new file mode 100644 index 00000000..b7401a4a --- /dev/null +++ b/docs/tools/base/config.rst @@ -0,0 +1,71 @@ +Tool +==== + +``Tool`` is a class that exposes a function or coroutine directly. It +can be used throughout the Automata System and is highly customizable +and versatile. + +Overview +-------- + +The ``Tool`` class in Automata includes a method ``run`` that takes a +dictionary input and returns a string. In simple terms, a ``Tool`` +performs specific tasks or operations, given some input. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_tool.test_tool``: A fixture that produces + a test tool for testing purposes. +- ``automata.tests.unit.test_tool.TestTool``: A subclass of ``Tool`` + used for testing purposes. +- ``automata.agent.providers.OpenAIAgentToolkitBuilder.can_handle``: A + method that checks if a tool can be handled. +- ``automata.tests.unit.test_tool.test_tool_run``: A function that + tests the ``run`` method of a tool. +- ``automata.llm.providers.openai.OpenAITool``: A subclass of ``Tool`` + that is designed for use by the OpenAI agent. +- ``automata.agent.agent.AgentToolkitBuilder.build``: A method that + builds a list of tools. +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder.build``: + A method that builds a list of symbol search toolkits. + +Example +------- + +The following are examples demonstrating the use of ``Tool``: + +Example of defining a ``Tool``: + +.. code:: python + + class TestTool(Tool): + def run(self, tool_input: Dict[str, str]) -> str: + return "TestTool response" + +Example of using a ``Tool``: + +.. code:: python + + tool_input = {"test": "test"} + response = test_tool.run(tool_input) + assert response == "TestTool response" + +Limitations +----------- + +``Tool`` is a highly abstract class that by itself does not do much. +It’s supposed to be extended to perform specific tasks. When subclassing +``Tool``, the implementation of some methods is required. + +Follow-up Questions: +-------------------- + +- Providing more specialized examples of ``Tool`` subclasses may help + users to understand the concept behind this class better, but such + examples are not found in the provided context. Could we get these + examples? +- How can custom ``Tool`` classes be integrated into the Automata + system? +- Are there specific rules or recommendations when implementing the + ``run`` method of a ``Tool`` subclass? diff --git a/docs/tools/base/index.rst b/docs/tools/base/index.rst new file mode 100644 index 00000000..883cc4ef --- /dev/null +++ b/docs/tools/base/index.rst @@ -0,0 +1,23 @@ +base +==== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + config + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/tools/builders/context_oracle_open_ai_toolkit_builder.rst b/docs/tools/builders/context_oracle_open_ai_toolkit_builder.rst new file mode 100644 index 00000000..48d9d5c1 --- /dev/null +++ b/docs/tools/builders/context_oracle_open_ai_toolkit_builder.rst @@ -0,0 +1,112 @@ +ContextOracleOpenAIToolkitBuilder +================================= + +``ContextOracleOpenAIToolkitBuilder`` is a class that’s specifically +used to build tools for the OpenAI agent. The class provides the +necessary infrastructure to create the tools that can be utilized by the +OpenAI agent in the Automata framework. + +Import Statements +----------------- + +.. code:: python + + import logging + import textwrap + from typing import List + from automata.config.base import LLMProvider + from automata.agent.agent import AgentToolkitBuilder, AgentToolkitNames + from automata.agent.providers import OpenAIAgentToolkitBuilder + from automata.embedding.base import EmbeddingSimilarityCalculator + from automata.llm.providers.openai import OpenAITool + from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler + from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler + from automata.singletons.toolkit_registries import OpenAIAutomataAgentToolkitRegistry + from automata.tools.base import Tool + +Methods +------- + +Here’s the unique method ``build_for_open_ai()`` of +``ContextOracleOpenAIToolkitBuilder``: + +.. code:: python + + def build_for_open_ai(self) -> List[OpenAITool]: + tools = super().build() + + # Predefined properties and required parameters + properties = { + "query": {"type": "string", "description": "The query string to search for."}, + "max_additional_related_symbols": { + "type": "integer", + "description": "The maximum number of additional related symbols to return documentation for.", + }, + } + required = ["query"] + + openai_tools = [] + for tool in tools: + openai_tool = OpenAITool( + function=tool.function, + name=tool.name, + description=tool.description, + properties=properties, + required=required, + ) + openai_tools.append(openai_tool) + + return openai_tools + +Usage Example +------------- + +.. code:: python + + from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler + from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler + from automata.embedding.base import EmbeddingSimilarityCalculator + from automata.tools.builders.context_oracle import ContextOracleOpenAIToolkitBuilder + + symbol_doc_embedding_handler = SymbolDocEmbeddingHandler() + symbol_code_embedding_handler = SymbolCodeEmbeddingHandler() + embedding_similarity_calculator = EmbeddingSimilarityCalculator() + + context_oracle_open_ai_toolkit_builder = ContextOracleOpenAIToolkitBuilder( + symbol_doc_embedding_handler=symbol_doc_embedding_handler, + symbol_code_embedding_handler=symbol_code_embedding_handler, + embedding_similarity_calculator=embedding_similarity_calculator, + ) + + # Build the OpenAI tools + openai_tools = context_oracle_open_ai_toolkit_builder.build_for_open_ai() + +Related Symbols +--------------- + +- ``automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder`` +- ``automata.tests.unit.test_context_oracle_tool.test_init`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder`` +- ``automata.tests.unit.test_context_oracle_tool.test_build`` +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` +- ``automata.tests.unit.test_py_reader_tool.python_retriever_tool_builder`` +- ``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` +- ``automata.tests.unit.test_symbol_search_tool.symbol_search_tool_builder`` +- ``automata.tools.builders.context_oracle.ContextOracleToolkitBuilder`` +- ``automata.tests.unit.test_automata_agent_builder.test_builder_accepts_all_fields`` + +Limitations +----------- + +The main limitation is that ``ContextOracleOpenAIToolkitBuilder`` is +tightly coupled to the structure of ``OpenAITool``. Any changes in +``OpenAITool`` might require corresponding changes in +``ContextOracleOpenAIToolkitBuilder`` as well. + +Follow-up Questions: +-------------------- + +- How flexible is the ``ContextOracleOpenAIToolkitBuilder`` in terms of + supporting different tools aside from the predefined ones? +- How do we plan to handle the changes if ``OpenAITool`` diverges + significantly in structure or properties in future updates? diff --git a/docs/tools/builders/context_oracle_toolkit_builder.rst b/docs/tools/builders/context_oracle_toolkit_builder.rst new file mode 100644 index 00000000..99fc6be9 --- /dev/null +++ b/docs/tools/builders/context_oracle_toolkit_builder.rst @@ -0,0 +1,72 @@ +ContextOracleToolkitBuilder +=========================== + +Overview +-------- + +The ``ContextOracleToolkitBuilder`` class is part of the Automata SDK +and provides tools which translate natural language processing (NLP) +queries into relevant context. It is a specialized toolkit builder +responsible for providing context to a given query by computing the +semantic similarity between the query, documentation, and code of all +available symbols. + +Related Symbols +--------------- + +- ``automata.agent.agent.AgentToolkitBuilder`` +- ``automata.tests.unit.test_context_oracle_tool.context_oracle_tool_builder`` +- ``automata.tests.unit.test_context_oracle_tool.test_build`` +- ``automata.tests.unit.test_context_oracle_tool.test_init`` +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` + +Dependencies +------------ + +- ``automata.embedding.base.EmbeddingSimilarityCalculator`` +- ``automata.memory_store.symbol_doc_embedding.SymbolDocEmbeddingHandler`` +- ``automata.memory_store.symbol_code_embedding.SymbolCodeEmbeddingHandler`` +- ``automata.tools.base.Tool`` + +Example +------- + +.. code:: python + + from automata.tools.builders.context_oracle import ContextOracleToolkitBuilder + from automata.embedding.base import EmbeddingSimilarityCalculator + from automata.memory_store.symbol_doc_embedding import SymbolDocEmbeddingHandler + from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler + + symbol_doc_embedding_handler = SymbolDocEmbeddingHandler() + symbol_code_embedding_handler = SymbolCodeEmbeddingHandler() + embedding_similarity_calculator = EmbeddingSimilarityCalculator() + + context_oracle_tool_builder = ContextOracleToolkitBuilder( + symbol_doc_embedding_handler=symbol_doc_embedding_handler, + symbol_code_embedding_handler=symbol_code_embedding_handler, + embedding_similarity_calculator=embedding_similarity_calculator, + ) + + tools = context_oracle_tool_builder.build() + for tool in tools: + print(tool.name) + +Limitations +----------- + +The ``ContextOracleToolkitBuilder`` is reliant on various interfaces and +classes including ``EmbeddingSimilarityCalculator``, +``SymbolDocEmbeddingHandler``, and ``SymbolCodeEmbeddingHandler``. +Limitations of these classes will inherently limit the functionality or +performance of ``ContextOracleToolkitBuilder``. + +Follow-up Questions +------------------- + +1. Is there a way to specify custom similarity calculators or embedding + handlers? +2. How does the ``ContextOracleToolkitBuilder`` handle situations when a + similarity score is not available? +3. How is the context for a query optimized? Can we specify the number + of most similar symbols for which we want to include the context? diff --git a/docs/tools/builders/index.rst b/docs/tools/builders/index.rst new file mode 100644 index 00000000..d87f0a41 --- /dev/null +++ b/docs/tools/builders/index.rst @@ -0,0 +1,31 @@ +builders +======== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + context_oracle_open_ai_toolkit_builder + context_oracle_toolkit_builder + py_reader_open_ai_toolkit + py_reader_toolkit_builder + py_writer_open_ai_toolkit_builder + py_writer_toolkit_builder + search_tool + symbol_search_open_ai_toolkit_builder + symbol_search_toolkit_builder + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/tools/builders/py_reader_open_ai_toolkit.rst b/docs/tools/builders/py_reader_open_ai_toolkit.rst new file mode 100644 index 00000000..4f5fb472 --- /dev/null +++ b/docs/tools/builders/py_reader_open_ai_toolkit.rst @@ -0,0 +1,73 @@ +PyReaderOpenAIToolkit +===================== + +Overview +-------- + +``PyReaderOpenAIToolkit`` is a class within the Automata framework that +allows for the retrieval and manipulation of python code from specified +paths or objects. This tool is beneficial for working with OpenAI and +builds on the functionality provided by the ``PyReader`` class. + +It contains a single method, +``build_for_open_ai(self) -> List[OpenAITool]``, which uses the +``PyReader`` class to create an array of ``OpenAITool`` objects. Each +tool is built with the same function, name and description, but with +properties and requirements provided within the method. + +Related Symbols +--------------- + +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.agent.agent.AgentToolkitBuilder`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder`` +- ``automata.config.base.LLMProvider`` +- ``automata.tools.builders.py_reader.PyReaderToolkitBuilder.build`` +- ``automata.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry`` +- ``automata.agent.agent.AgentToolkitNames`` +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder.build_for_open_ai`` + +Example +------- + +Below is a basic example of initializing ``PyReaderOpenAIToolkit``\ and +using its ``build_for_open_ai`` method. In our example, we will use a +mock version of the ``PyReader`` class as it’s complex and not under the +scope of this document. + +.. code:: python + + from unittest.mock import MagicMock + from automata.code_handling.py.reader import PyReader + from automata.tools.builders.py_reader import PyReaderOpenAIToolkit + + # Initialize a mock PyReader object + py_reader = MagicMock(spec=PyReader) + + # Initialize PyReaderOpenAIToolkit + py_reader_openAI = PyReaderOpenAIToolkit(py_reader) + + # Build tools for OpenAI + openAI_tools = py_reader_openAI.build_for_open_ai() + +Limitations +----------- + +``PyReaderOpenAIToolkit``\ ’s primary limitation arises from its core +dependency on the ``PyReader`` class for retrieving python code. If the +path or object specified is incorrectly formatted or does not exist, +``PyReader`` will not be able to retrieve the code, causing potential +errors. Additionally, it currently only supports generating +``OpenAITool`` objects, limiting its usability to OpenAI applications. + +Follow-up questions: +-------------------- + +- How can PyReaderOpenAIToolkit handle non-existent or improperly + formatted paths? +- Can PyReaderOpenAIToolkit be adapted to generate tools compatible + with providers other than OpenAI? +- Is there any additional functionality that could be included in + PyReaderOpenAIToolkit to enhance its usage within the Automata + framework? diff --git a/docs/tools/builders/py_reader_toolkit_builder.rst b/docs/tools/builders/py_reader_toolkit_builder.rst new file mode 100644 index 00000000..2a6ca9b1 --- /dev/null +++ b/docs/tools/builders/py_reader_toolkit_builder.rst @@ -0,0 +1,94 @@ +PyReaderToolkitBuilder +====================== + +Overview +-------- + +The ``PyReaderToolkitBuilder`` class, a part of the Automata’s toolkit, +interacts with the PythonIndexer API to access and retrieve Python code. +The class includes tools attached to the Python code retrieval process +such as ``py-retriever-retrieve-code``, +``py-retriever-retrieve-docstring``, and +``py-retriever-retrieve-raw-code``. + +The class utilizes the ``PyReader`` object for operation and +automatically builds the tools for retrieving code upon calling the +``build`` function. The ``build`` function, on execution, delivers +``Tool`` objects encompassing functional capabilities and their +descriptions. + +Related Symbols +--------------- + +- ``automata.tools.builders.py_reader.PyReaderOpenAIToolkit`` +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` +- ``automata.tools.builders.py_writer.PyWriterToolkitBuilder`` +- ``automata.agent.agent.AgentToolkitBuilder`` + +Dependencies +------------ + +- ``automata.code_handling.py.reader.PyReader`` +- ``automata.tools.base.Tool`` +- ``automata.agent.agent.AgentToolkitBuilder`` + +Usage Example +------------- + +Below illustrated is an example demonstrating the instantiation of +``PyReaderToolkitBuilder`` using a ``PyReader`` object and how to build +tools related to the retrieval of Python code: + +.. code:: python + + from automata.code_handling.py.reader import PyReader + from automata.tools.builders.py_reader import PyReaderToolkitBuilder + + # Instantiate the PyReader object + python_code_retriever = PyReader() + + # Instantiate the PyReaderToolkitBuilder object with the PyReader + toolkit_builder = PyReaderToolkitBuilder(py_reader=python_code_retriever) + + # Start the build process + tools = toolkit_builder.build() + +In this example, ``tools`` will contain a list of ``Tool`` objects each +one described as follows: + +- ``py-retriever-retrieve-code``: This tool returns the code of the + Python file. +- ``py-retriever-retrieve-docstring``: Similar to the + ``py-retriever-retrieve-code`` tool, but returns the docstring + instead of raw code. +- ``py-retriever-retrieve-raw-code``: Similar to the + ``py-retriever-retrieve-code`` tool but returns raw text, i.e., code + along with docstrings. + +Limitations +----------- + +This class is associated with the potential limitation of retrieving +only the Python code, not supporting any other programming languages. It +inherits from ``AgentToolkitBuilder`` which implies that the developer +needs to ensure the compatibility with ``AgentToolkitBuilder`` when +planning to make any changes. + +Follow-up Questions: +-------------------- + +- How are tool functions like ``_run_indexer_retrieve_code``, + ``_run_indexer_retrieve_docstring``, and + ``_run_indexer_retrieve_raw_code`` used? +- How does PyReaderToolkitBuilder compare to other Toolkit builders + like PyWriterToolkitBuilder and ContextOracleOpenAIToolkitBuilder? +- Is it possible to extend the functionality of this class beyond + Python code retrieval? + +Please note certain points require follow-up for clarity and +confirmation. As per the context provided, there is no concrete +information available on functions starting with ``_run_indexer_*``. +They are anticipated to be private methods within the +``PyReaderToolkitBuilder`` class but are not explicitly mentioned in the +context provided. diff --git a/docs/tools/builders/py_writer_open_ai_toolkit_builder.rst b/docs/tools/builders/py_writer_open_ai_toolkit_builder.rst new file mode 100644 index 00000000..8913b794 --- /dev/null +++ b/docs/tools/builders/py_writer_open_ai_toolkit_builder.rst @@ -0,0 +1,66 @@ +PyWriterOpenAIToolkitBuilder +============================ + +``PyWriterOpenAIToolkitBuilder`` is a component of Automata’s toolkit +for building configurations for OpenAI agent tools. It’s primarily +designed to assist in writing or modifying python source files such as +scripts or jupyter notebooks. + +Overview +-------- + +``PyWriterOpenAIToolkitBuilder`` extends from the base +``OpenAIAgentToolkitBuilder``. It provides a method +``build_for_open_ai`` which returns a list of OpenAI tools. These tools +are expected to contain functions, descriptions and properties and are +represented by instances of the ``OpenAITool`` class. The main +characteristic of ``PyWriterOpenAIToolkitBuilder`` is that the tools it +builds are used by the OpenAI agent to modify python files. + +Related Symbols +--------------- + +- ``automata.agent.providers.OpenAIAgentToolkitBuilder``: The base + class this builder extends from. +- ``automata.llm.providers.openai.OpenAITool``: This class represents + tools that ``PyWriterOpenAIToolkitBuilder`` builds. + +Example +------- + +Here’s an illustrative example of how to use the +PyWriterOpenAIToolkitBuilder: + +.. code:: python + + from automata.code_handling.py.writer import PyWriter + from automata.tools.builders.py_writer import PyWriterOpenAIToolkitBuilder + + py_writer = PyWriter() + toolkit_builder = PyWriterOpenAIToolkitBuilder(py_writer) + + openai_tools = toolkit_builder.build_for_open_ai() # Returns a list of OpenAITool instances + +Here, ``openai_tools`` is a list of ``OpenAITool``\ s that can be +utilized in your OpenAI agent. + +Limitations +----------- + +The ``PyWriterOpenAIToolkitBuilder`` is largely dependent on the +``PyWriter`` tool, which operates on an abstraction layer, meaning the +writer might not be perfect in handling all edge cases of modifying +python code. + +Furthermore, the ``PyWriterOpenAIToolkitBuilder`` currently only +requires the ``module_dotpath`` and ``code`` properties to be present in +the tools. These might not be sufficient for complex manipulations of +python code. + +Follow-up Questions: +-------------------- + +- Is there a way to handle more complex code manipulations that require + additional properties? +- Are there any safety measures taken while writing or modifying python + files to ensure no breaking changes are introduced? diff --git a/docs/tools/builders/py_writer_toolkit_builder.rst b/docs/tools/builders/py_writer_toolkit_builder.rst new file mode 100644 index 00000000..ce3e1693 --- /dev/null +++ b/docs/tools/builders/py_writer_toolkit_builder.rst @@ -0,0 +1,74 @@ +PyWriterToolkitBuilder +====================== + +``PyWriterToolkitBuilder`` is a class that provides functionalities for +manipulating Python code by interacting with the PythonWriter API. + +Overview +-------- + +``PyWriterToolkitBuilder`` allows you to modify existing Python code or +create new modules. Initialization of an instance requires an instance +of the ``PyWriter`` class, and an optional boolean argument ``do_write`` +that defines whether the module is written to disk after updating. + +Its ``build`` method provides two functionalities: + +1. ``py-writer-update-module``: This inserts or updates python code of a + function, class, method in an existing module. It can create new + objects, modify existing code, or even introduce new import + statements. +2. ``py-writer-create-new-module``: It creates a new module at a given + path with the given code. + +Related Symbols +--------------- + +- ``automata.tools.base.Tool``: The ``Tool`` class exposes a function + or coroutine directly which is then used by + ``PyWriterToolkitBuilder`` to implement its methods. + +- ``automata.tests.unit.test_py_writer_tool.python_writer_tool_builder``: + This tests the ``PyWriterToolkitBuilder`` and asserts its instance + type as ``Tool``. + +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder``: + Provides similar method to ``build()`` in ``PyWriterToolkitBuilder`` + to build Python toolkit for OpenAI. + +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder``: + Builds toolkit for handling of context Oracle within OpenAI. + +Usage Example +------------- + +.. code:: python + + from automata.code_handling.py.writer import PyWriter + from automata.tools.builders.py_writer import PyWriterToolkitBuilder + + py_writer = PyWriter(py_reader) + py_toolkit_builder = PyWriterToolkitBuilder(py_writer=py_writer) + tools = py_toolkit_builder.build() + + for tool in tools: + print(f"Tool Name: {tool.name}") + print(f"Tool Description: {tool.description}") + +Limitations +----------- + +The ``PyWriterToolkitBuilder`` is restricted to working with Python code +only. Additionally, it requires an existing ``PyWriter`` instance during +initialization. + +Follow-up Questions: +-------------------- + +- Can ``PyWriterToolkitBuilder`` handle non-python code as well? +- What could be some potential security risks associated with modifying + python code or creating new modules? +- What safeguards have been put in to avoid these potential security + risks? +- Is there a way to initiate ``PyWriterToolkitBuilder`` without having + to pass in a ``PyWriter`` instance during initialization? diff --git a/docs/tools/builders/search_tool.rst b/docs/tools/builders/search_tool.rst new file mode 100644 index 00000000..66f8bacd --- /dev/null +++ b/docs/tools/builders/search_tool.rst @@ -0,0 +1,74 @@ +SearchTool +========== + +``SearchTool`` is a class contained within the +``automata.tools.builders.symbol_search`` module. It is one of the +available tools for search operations, as its name implies. It is mainly +used for building ``SymbolSearchToolkitBuilder`` objects. This class +enables interaction with ``SymbolSearch`` API, which is capable of +searching through an indexed Python codebase. + +Import Statements +----------------- + +To make use of the ``SearchTool`` class, include the following import +statements: + +.. code:: python + + from enum import Enum + from automata.tools.builders.symbol_search import SearchTool + +Overview +-------- + +``SearchTool`` does not contain any methods. It is an enumeration used +to represent various available search tools during the instantiation of +a ``SymbolSearchToolkitBuilder`` object. Following are the enumerated +values - + +Related Symbols +--------------- + +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` +- ``automata.tools.base.Tool`` +- ``automata.tests.unit.test_symbol_search_tool.symbol_search_tool_builder`` +- ``automata.tools.builders.symbol_search.SymbolSearchOpenAIToolkitBuilder`` +- ``automata.tests.unit.test_tool.TestTool`` + +Example +------- + +Below is an example to demonstrate how ``SearchTool`` enum is used while +creating the ``SymbolSearchToolkitBuilder`` object – + +.. code:: python + + from automata.tools.builders.symbol_search import SearchTool, SymbolSearchToolkitBuilder + from automata.experimental.search.symbol_search import SymbolSearch + + symbol_search = SymbolSearch(index="my_python_index") + builder = SymbolSearchToolkitBuilder(symbol_search=symbol_search, search_tools=[SearchTool.EXACT, SearchTool.RANK]) + +In the above example, ``EXACT`` and ``RANK`` are two available search +tools part of the ``SearchTool`` enumeration. + +Limitations +----------- + +``SearchTool`` is an enum class providing the available search tools. +Thus, it does not possess any functionality itself, but rather specifies +options for other classes’ methods or constructors that require a search +tool. + +Follow-up Questions +------------------- + +- Are there any plans to extend the existing enum with additional + search tools? +- How are these search tools interconnected with the rest of the + codebase? For instance, how do they impact the search results? + +Note: The context included references to ‘Mock’ objects in test files. +These aren’t actual underlying objects but are simplified objects used +for testing purposes. diff --git a/docs/tools/builders/symbol_search_open_ai_toolkit_builder.rst b/docs/tools/builders/symbol_search_open_ai_toolkit_builder.rst new file mode 100644 index 00000000..af5e859a --- /dev/null +++ b/docs/tools/builders/symbol_search_open_ai_toolkit_builder.rst @@ -0,0 +1,78 @@ +SymbolSearchOpenAIToolkitBuilder +================================ + +``SymbolSearchOpenAIToolkitBuilder`` is a class for building OpenAI +tools using the Symbol Search API which provides functionality to search +an indexed python codebase. + +Overview +-------- + +``SymbolSearchOpenAIToolkitBuilder`` provides an interface to create +OpenAI tools based on the functionality of the Symbol Search. The Symbol +Search API allows you to search python codebase indexed under Automata. +The symbols can be a specific python function, class, method, or +property. The ``build_for_open_ai`` method builds a list of OpenAI tools +to be used by the Automata Agent. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_symbol_search_tool.symbol_search_tool_builder`` +- ``automata.tests.unit.test_symbol_search_tool.test_init`` +- ``automata.tools.builders.context_oracle.ContextOracleOpenAIToolkitBuilder`` +- ``automata.tests.unit.test_symbol_search_tool.test_build`` +- ``automata.tools.builders.py_writer.PyWriterOpenAIToolkitBuilder`` +- ``automata.tests.unit.test_symbol_search_tool.test_exact_search`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder`` +- ``automata.tests.unit.test_symbol_search_tool.test_retrieve_source_code_by_symbol`` +- ``automata.tools.builders.py_reader.PyReaderOpenAIToolkit`` +- ``automata.tests.unit.test_symbol_search_tool.test_symbol_references`` + +Example +------- + +The following example demonstrates how to build OpenAI tools using the +``SymbolSearchOpenAIToolkitBuilder`` class. + +.. code:: python + + from automata.tools.builders.symbol_search import SymbolSearchOpenAIToolkitBuilder + from automata.experimental.search.symbol_search import SymbolSearch + + symbol_search = SymbolSearch(index_name="your-index-name") + builder = SymbolSearchOpenAIToolkitBuilder(symbol_search=symbol_search) + + openai_tools = builder.build_for_open_ai() + for tool in openai_tools: + print(type(tool), tool.name) + +Please replace “your-index-name” with the actual name of your index. + +Limitations +----------- + +- ``SymbolSearchOpenAIToolkitBuilder`` is limited to only building + tools that work with the Symbol Search API. +- The builder must be initialized with a valid ``SymbolSearch`` + instance. +- The builder’s functionality is closely tied to the ``SymbolSearch`` + implementation, and any changes in that implementation may require + changes in the builder as well. + +Dependencies +------------ + +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.singletons.toolkit_registries.OpenAIAutomataAgentToolkitRegistry`` +- ``automata.agent.agent.AgentToolkitNames`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder`` + +Follow-up Questions: +-------------------- + +- What are the specific use-cases for + ``SymbolSearchOpenAIToolkitBuilder`` and when should it be preferred + over other builder types? +- How does the builder handle exceptions and errors that may occur + during tool creation? diff --git a/docs/tools/builders/symbol_search_toolkit_builder.rst b/docs/tools/builders/symbol_search_toolkit_builder.rst new file mode 100644 index 00000000..57bf85ea --- /dev/null +++ b/docs/tools/builders/symbol_search_toolkit_builder.rst @@ -0,0 +1,75 @@ +SymbolSearchToolkitBuilder +========================== + +The ``SymbolSearchToolkitBuilder`` is an overarching connector to the +SymbolSearch API. It offers functionality to comb through an indexed +Python codebase and execute searches therein. Thoroughly integrated, it +permits to search symbols, fetch their references, return the source +code corresponding to a certain symbol, and perform exact matches. + +Overview +-------- + +``SymbolSearchToolkitBuilder``, fundamentally, is an intermediary agent +that binds together various tools designed to search the indexed +codebase. It enables the creation of tools for the purpose of ranking +symbols, fetching their references, and retrieving source code. It also +allows for exact pattern searches across the codebase. + +The class initiates with a symbol search and a list of optional search +tools. It can build single tools or a complete suite of tools for +searching the codebase. With the ``process_query()`` method, it enables +the processing of a query by routing it directly to its sub-tool. + +Related Symbols +--------------- + +- ``SymbolSearchOpenAIToolkitBuilder`` +- ``ContextOracleOpenAIToolkitBuilder`` +- ``ContextOracleToolkitBuilder`` +- ``SearchTool`` + +Example +------- + +To construct the ``SymbolSearchToolkitBuilder``, here is an example +snippet: + +.. code:: python + + # assuming symbolGraph and other dependencies are based on existing contextual data + from automata.experimental.search.symbol_search import SymbolSearch, SymbolSearchConfig + from automata.tools.builders.symbol_search import SymbolSearchToolkitBuilder, SearchTool + + # Construct the Symbol Search + symbol_search = SymbolSearch(symbolGraph, SymbolSearchConfig.default()) + + # Define the toolkit and the search tools required + toolkit = SymbolSearchToolkitBuilder(symbol_search, [SearchTool.EXACT_SEARCH]) + + # Build the tools required + tools = toolkit.build() + +In this example, the toolkit uses the SymbolSearch class to perform an +exact search for the given pattern in the Python codebase. + +Limitations +----------- + +One significant caveat with ``SymbolSearchToolkitBuilder`` is that the +processors currently available are basic implementations. While +functioning, they can be refined further to concretise their +performance. + +The class’s design relies heavily on the enum SearchTool; if an invalid +or unrecognized tool is provided, it raises an ``UnknownToolError``. + +Follow-Up Questions +------------------- + +- What mechanisms exist to extend the capabilities of StatusCodeBuilder + beyond ‘simple implementations’? +- How could the functionality be extended to include other programming + languages beyond Python? +- What would be the process of adding new search tools or extending the + capabilities of existing ones in practice? diff --git a/docs/tools/index.rst b/docs/tools/index.rst new file mode 100644 index 00000000..7b70dba9 --- /dev/null +++ b/docs/tools/index.rst @@ -0,0 +1,26 @@ +tools +===== + +**Automata** is a Python library for autonomous providers. + +Check out the :doc:`usage` section for further information, including +how to :ref:`installation` the project. + + + +.. AUTO-GENERATED CONTENT START +.. + + .. toctree:: + :maxdepth: 1 + + agent_tool_factory + tool + base/index + builders/index + +.. AUTO-GENERATED CONTENT END +.. + + + diff --git a/docs/tools/tool.rst b/docs/tools/tool.rst new file mode 100644 index 00000000..842b071c --- /dev/null +++ b/docs/tools/tool.rst @@ -0,0 +1,71 @@ +Tool +==== + +``Tool`` directly exposes a function or coroutine. It takes inputs in +the form of dictionary in a run method. The ``Tool`` class is part of +the automata.tools.base module. + +Overview +-------- + +In the larger context of the Automata software architecture, ``Tool`` is +an abstraction that represents a tool or functionality. It encapsulates +a function or routine, exposing it through a ``run`` method that accepts +inputs in form of a dictionary. + +The principle use-case is to encapsulate tasks that involve fetching, +processing, or generating data summarized into a single callable method +``run``. + +Related Symbols +--------------- + +- ``automata.tests.unit.test_tool.test_tool`` +- ``automata.tests.unit.test_tool.TestTool`` +- ``automata.agent.providers.OpenAIAgentToolkitBuilder.can_handle`` +- ``automata.tests.unit.test_tool.test_tool_run`` +- ``automata.llm.providers.openai.OpenAITool`` +- ``automata.tests.unit.test_tool.TestTool.run`` +- ``automata.agent.agent.AgentToolkitBuilder.build`` +- ``automata.tests.unit.test_tool.test_tool_instantiation`` +- ``automata.tools.builders.symbol_search.SymbolSearchToolkitBuilder.build`` +- ``automata.tests.unit.test_symbol_search_tool.test_build`` + +Example +------- + +The following is an example use-case of creating a ``Tool`` instance, +and running it with an input. + +.. code:: python + + from automata.tools.base import Tool + + test_tool = Tool( + name="TestTool", + description="A test tool for testing purposes", + function=lambda x: "TestTool response") + + # Running the tool + tool_input = {"test": "test"} + response = test_tool.run(tool_input) + # Outputs: "TestTool response" + +Limitations +----------- + +The ``Tool`` class is designed to execute individually encapsulated +tasks, and is not suitable for managing tasks that involve significant +inter-dependence or require coordination between multiple tasks. + +While ``Tool`` instances can be used simultaneously they lack built-in +mechanisms for sharing information between one another, which might +limit application in more complex, real-world scenarios. + +Follow-up Questions +------------------- + +- How can ``Tool`` instances communicate with each other when running + in parallel? +- Is there a way to make the ``Tool`` capable of handling inter-task + dependencies? diff --git a/requirements.txt b/requirements.txt index 22afae96..adb6d162 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,7 +8,7 @@ jsonpickle==3.0.1 jsonschema==4.17.3 matplotlib==3.7.1 networkx==3.1 -numpy==1.23.5 +numpy==1.25.0 openai==0.27.8 pandas==2.0.3 plotly==5.15.0 diff --git a/scripts/regenerate_docs.sh b/scripts/regenerate_docs.sh index 2938af10..79bc40c3 100755 --- a/scripts/regenerate_docs.sh +++ b/scripts/regenerate_docs.sh @@ -15,6 +15,6 @@ python3 generate_faq.py # Return to working dir cd - -# Optional command to build docs locally - 'sphinx-build -a automata/docs ../docs' +# Optional command to build docs locally - 'sphinx-build -a ../docs ../../docs' deactivate diff --git a/tests/conftest.py b/tests/conftest.py index e2766dfe..ee4d934d 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -6,22 +6,22 @@ import numpy as np import pytest +from automata.agent.agent import AgentToolkitNames +from automata.agent.providers import OpenAIAutomataAgent from automata.config.base import AgentConfigName from automata.config.openai_agent import OpenAIAutomataAgentConfigBuilder -from automata.core.agent.agent import AgentToolkitNames -from automata.core.agent.providers import OpenAIAutomataAgent -from automata.core.embedding.base import EmbeddingSimilarityCalculator -from automata.core.experimental.search.rank import SymbolRankConfig -from automata.core.experimental.search.symbol_search import SymbolSearch -from automata.core.github_management.client import GitHubClient, RepositoryClient -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.singletons.dependency_factory import dependency_factory -from automata.core.symbol.graph import SymbolGraph -from automata.core.symbol.parser import parse_symbol -from automata.core.tasks.agent_database import AutomataTaskRegistry -from automata.core.tasks.environment import AutomataTaskEnvironment -from automata.core.tasks.tasks import AutomataTask -from automata.core.tools.factory import AgentToolFactory +from automata.embedding.base import EmbeddingSimilarityCalculator +from automata.experimental.search.rank import SymbolRankConfig +from automata.experimental.search.symbol_search import SymbolSearch +from automata.github_management.client import GitHubClient, RepositoryClient +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.singletons.dependency_factory import dependency_factory +from automata.symbol.graph import SymbolGraph +from automata.symbol.parser import parse_symbol +from automata.tasks.agent_database import AutomataTaskRegistry +from automata.tasks.environment import AutomataTaskEnvironment +from automata.tasks.tasks import AutomataTask +from automata.tools.factory import AgentToolFactory @pytest.fixture diff --git a/tests/regression/test_symbol_searcher_regression.py b/tests/regression/test_symbol_searcher_regression.py index 01c79549..ad0f4a04 100644 --- a/tests/regression/test_symbol_searcher_regression.py +++ b/tests/regression/test_symbol_searcher_regression.py @@ -1,6 +1,6 @@ import pytest -from automata.core.singletons.py_module_loader import py_module_loader +from automata.singletons.py_module_loader import py_module_loader from ..utils.factories import symbol_search_live # noqa @@ -37,7 +37,7 @@ def check_hits(expected_in_top_hits, found_top_hits): ], ), ("LLM", ["LLMProvider", "LLMChatMessage", "LLMConversation", "LLMCompletionResult"]), - ("Symbol", ["Symbol", "SymbolGraph", "JSONSymbolEmbeddingVectorDatabase"]), + ("Symbol", ["Symbol", "SymbolGraph"]), ], ) def test_symbol_rank_search_on_symbol( @@ -54,12 +54,12 @@ def test_symbol_rank_search_on_symbol( EXACT_CALLS_TO_HITS = { "OpenAIAutomataAgent": [ "automata.cli.scripts.run_agent", - "automata.core.agent.providers", - "automata.core.singletons.toolkit_registries", + "automata.agent.providers", + "automata.singletons.toolkit_registries", ], "SymbolRank": [ - "automata.core.experimental.search.symbol_search", - "automata.core.experimental.search.rank", + "automata.experimental.search.symbol_search", + "automata.experimental.search.rank", ], } @@ -72,15 +72,15 @@ def test_symbol_rank_search_on_symbol( "OpenAIAutomataAgent", [ "automata.cli.scripts.run_agent", - "automata.core.agent.providers", - "automata.core.singletons.toolkit_registries", + "automata.agent.providers", + "automata.singletons.toolkit_registries", ], ), ( "SymbolRank", [ - "automata.core.experimental.search.symbol_search", - "automata.core.experimental.search.rank", + "automata.experimental.search.symbol_search", + "automata.experimental.search.rank", ], ), ], diff --git a/tests/unit/test_automata_agent.py b/tests/unit/test_automata_agent.py index 5af96b69..c74ef2fc 100644 --- a/tests/unit/test_automata_agent.py +++ b/tests/unit/test_automata_agent.py @@ -2,8 +2,8 @@ import pytest -from automata.core.agent.error import AgentMaxIterError -from automata.core.agent.providers import OpenAIAutomataAgent +from automata.agent.error import AgentMaxIterError +from automata.agent.providers import OpenAIAutomataAgent def test_build_initial_messages(automata_agent): diff --git a/tests/unit/test_automata_agent_builder.py b/tests/unit/test_automata_agent_builder.py index 508485a9..4ab8540f 100644 --- a/tests/unit/test_automata_agent_builder.py +++ b/tests/unit/test_automata_agent_builder.py @@ -4,7 +4,7 @@ from automata.config.base import AgentConfigName from automata.config.openai_agent import OpenAIAutomataAgentConfig -from automata.core.tools.factory import AgentToolFactory +from automata.tools.factory import AgentToolFactory def test_automata_agent_init(automata_agent): @@ -47,8 +47,8 @@ def test_builder_provided_parameters_override_defaults(automata_agent_config_bui def test_builder_accepts_all_fields(automata_agent_config_builder): toolkit_list = ["py-reader", "py-writer"] - from automata.core.code_handling.py.reader import PyReader - from automata.core.code_handling.py.writer import PyWriter + from automata.code_handling.py.reader import PyReader + from automata.code_handling.py.writer import PyWriter tools = AgentToolFactory.build_tools( toolkit_list, diff --git a/tests/unit/test_context_oracle_tool.py b/tests/unit/test_context_oracle_tool.py index 29f858d5..af90e792 100644 --- a/tests/unit/test_context_oracle_tool.py +++ b/tests/unit/test_context_oracle_tool.py @@ -2,8 +2,8 @@ import pytest -from automata.core.tools.base import Tool -from automata.core.tools.builders.context_oracle import ContextOracleToolkitBuilder +from automata.tools.base import Tool +from automata.tools.builders.context_oracle import ContextOracleToolkitBuilder @pytest.fixture diff --git a/tests/unit/test_conversation_database.py b/tests/unit/test_conversation_database.py index 7dd21039..9fdad1a0 100644 --- a/tests/unit/test_conversation_database.py +++ b/tests/unit/test_conversation_database.py @@ -2,10 +2,8 @@ import pytest -from automata.core.llm.foundation import LLMChatMessage -from automata.core.memory_store.agent_conversation_database import ( - AgentConversationDatabase, -) +from automata.llm.foundation import LLMChatMessage +from automata.memory_store.agent_conversation_database import AgentConversationDatabase @pytest.fixture(scope="module", autouse=True) diff --git a/tests/unit/test_database_vector.py b/tests/unit/test_database_vector.py index 0c91962c..ec26a0ac 100644 --- a/tests/unit/test_database_vector.py +++ b/tests/unit/test_database_vector.py @@ -1,6 +1,6 @@ import pytest -from automata.core.symbol_embedding.base import ( +from automata.symbol_embedding.base import ( JSONSymbolEmbeddingVectorDatabase, SymbolCodeEmbedding, ) diff --git a/tests/unit/test_directory_manager.py b/tests/unit/test_directory_manager.py index 610e07c2..b6f3baa4 100644 --- a/tests/unit/test_directory_manager.py +++ b/tests/unit/test_directory_manager.py @@ -1,4 +1,4 @@ -from automata.core.navigation.directory import DirectoryManager +from automata.navigation.directory import DirectoryManager def create_test_dir_structure(tmp_path): diff --git a/tests/unit/test_py_reader.py b/tests/unit/test_py_reader.py index 5919487a..c6b37c27 100644 --- a/tests/unit/test_py_reader.py +++ b/tests/unit/test_py_reader.py @@ -2,8 +2,8 @@ import pytest -from automata.core.code_handling.py.reader import PyReader -from automata.core.singletons.py_module_loader import py_module_loader +from automata.code_handling.py.reader import PyReader +from automata.singletons.py_module_loader import py_module_loader @pytest.fixture(autouse=True) diff --git a/tests/unit/test_py_reader_tool.py b/tests/unit/test_py_reader_tool.py index e87116eb..03e39eec 100644 --- a/tests/unit/test_py_reader_tool.py +++ b/tests/unit/test_py_reader_tool.py @@ -3,11 +3,11 @@ import pytest -from automata.core.code_handling.py.reader import PyReader -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.tools.base import Tool -from automata.core.tools.builders.py_reader import PyReaderToolkitBuilder +from automata.code_handling.py.reader import PyReader from automata.core.utils import get_root_py_fpath +from automata.singletons.py_module_loader import py_module_loader +from automata.tools.base import Tool +from automata.tools.builders.py_reader import PyReaderToolkitBuilder @pytest.fixture(autouse=True) diff --git a/tests/unit/test_py_writer.py b/tests/unit/test_py_writer.py index ebbcfcf0..683688cc 100644 --- a/tests/unit/test_py_writer.py +++ b/tests/unit/test_py_writer.py @@ -14,10 +14,10 @@ StringNode, ) -from automata.core.code_handling.py.reader import PyReader -from automata.core.code_handling.py.writer import PyWriter -from automata.core.navigation.py.navigation_utils import find_syntax_tree_node -from automata.core.singletons.py_module_loader import py_module_loader +from automata.code_handling.py.reader import PyReader +from automata.code_handling.py.writer import PyWriter +from automata.navigation.py.navigation_utils import find_syntax_tree_node +from automata.singletons.py_module_loader import py_module_loader class MockCodeGenerator: diff --git a/tests/unit/test_py_writer_tool.py b/tests/unit/test_py_writer_tool.py index a8bb1508..5b93cc29 100644 --- a/tests/unit/test_py_writer_tool.py +++ b/tests/unit/test_py_writer_tool.py @@ -4,12 +4,12 @@ import pytest -from automata.core.code_handling.py.reader import PyReader -from automata.core.code_handling.py.writer import PyWriter -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.tools.base import Tool -from automata.core.tools.builders.py_writer import PyWriterToolkitBuilder +from automata.code_handling.py.reader import PyReader +from automata.code_handling.py.writer import PyWriter from automata.core.utils import get_root_fpath +from automata.singletons.py_module_loader import py_module_loader +from automata.tools.base import Tool +from automata.tools.builders.py_writer import PyWriterToolkitBuilder # TODO - Unify module loader fixture @@ -140,7 +140,7 @@ def test_extend_module_with_documented_new_class(python_writer_tool_builder): '''from typing import List -from automata.core.tools.base import Tool +from automata.tools.base import Tool from automata.tools.python_tools.python_agent import PythonAgent diff --git a/tests/unit/test_symbol_embedding.py b/tests/unit/test_symbol_embedding.py index ed05fc31..3a55e9c0 100644 --- a/tests/unit/test_symbol_embedding.py +++ b/tests/unit/test_symbol_embedding.py @@ -2,9 +2,9 @@ import numpy as np -from automata.core.embedding.base import EmbeddingBuilder -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.symbol_embedding.base import ( +from automata.embedding.base import EmbeddingBuilder +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.symbol_embedding.base import ( JSONSymbolEmbeddingVectorDatabase, SymbolCodeEmbedding, ) @@ -17,7 +17,7 @@ def test_update_embeddings( mock_simple_class_symbols, ): monkeypatch.setattr( - "automata.core.symbol.symbol_utils.convert_to_fst_object", + "automata.symbol.symbol_utils.convert_to_fst_object", lambda args: "symbol_source", ) @@ -76,7 +76,7 @@ def test_get_embedding( def test_add_new_embedding(monkeypatch, mock_simple_method_symbols): # Test exception in build_embedding_vector function monkeypatch.setattr( - "automata.core.symbol.symbol_utils.convert_to_fst_object", + "automata.symbol.symbol_utils.convert_to_fst_object", lambda args: "symbol_source", ) @@ -101,7 +101,7 @@ def test_add_new_embedding(monkeypatch, mock_simple_method_symbols): def test_update_embedding(monkeypatch, mock_simple_method_symbols): # Test exception in build_embedding_vector function monkeypatch.setattr( - "automata.core.symbol.symbol_utils.convert_to_fst_object", + "automata.symbol.symbol_utils.convert_to_fst_object", lambda args: "symbol_source", ) @@ -121,7 +121,7 @@ def test_update_embedding(monkeypatch, mock_simple_method_symbols): # If exception occurs during the get_embedding operation, the database should not contain any new entries cem.process_embedding(mock_simple_method_symbols[0]) monkeypatch.setattr( - "automata.core.symbol.symbol_utils.convert_to_fst_object", + "automata.symbol.symbol_utils.convert_to_fst_object", lambda args: "xx", ) @@ -141,7 +141,7 @@ def test_update_embedding(monkeypatch, mock_simple_method_symbols): def test_get_embedding_exception(monkeypatch, mock_simple_method_symbols): # Test exception in build_embedding_vector function monkeypatch.setattr( - "automata.core.symbol.symbol_utils.convert_to_fst_object", + "automata.symbol.symbol_utils.convert_to_fst_object", lambda args: "symbol_source", ) diff --git a/tests/unit/test_symbol_graph.py b/tests/unit/test_symbol_graph.py index fe8889eb..7ab8a348 100644 --- a/tests/unit/test_symbol_graph.py +++ b/tests/unit/test_symbol_graph.py @@ -1,9 +1,9 @@ -from automata.core.context_providers.symbol_synchronization import ( +from automata.context_providers.symbol_synchronization import ( SymbolProviderSynchronizationContext, ) -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.symbol.base import Symbol -from automata.core.symbol.graph import SymbolGraph +from automata.singletons.py_module_loader import py_module_loader +from automata.symbol.base import Symbol +from automata.symbol.graph import SymbolGraph from ..utils.factories import symbol_graph_static_test # noqa: F401 @@ -40,6 +40,6 @@ def test_build_real_graph_and_subgraph(symbol_graph_static_test): # noqa: F811 # build the subgraph subgraph = symbol_graph_static_test.default_rankable_subgraph - assert len(subgraph) == 39 + assert len(subgraph) == 36 py_module_loader.initialized = False diff --git a/tests/unit/test_symbol_parser.py b/tests/unit/test_symbol_parser.py index f6307612..9dbf0dd2 100644 --- a/tests/unit/test_symbol_parser.py +++ b/tests/unit/test_symbol_parser.py @@ -1,4 +1,4 @@ -from automata.core.symbol.parser import Symbol, is_global_symbol, is_local_symbol +from automata.symbol.parser import Symbol, is_global_symbol, is_local_symbol def test_parse_symbol(symbols): diff --git a/tests/unit/test_symbol_rank.py b/tests/unit/test_symbol_rank.py index 843929cd..d82df2f6 100644 --- a/tests/unit/test_symbol_rank.py +++ b/tests/unit/test_symbol_rank.py @@ -4,7 +4,7 @@ import pytest from networkx import DiGraph -from automata.core.experimental.search.rank import SymbolRank, SymbolRankConfig +from automata.experimental.search.rank import SymbolRank, SymbolRankConfig def generate_random_graph(nodes, edges): diff --git a/tests/unit/test_symbol_search.py b/tests/unit/test_symbol_search.py index 9fdedd6b..d9c9a8d0 100644 --- a/tests/unit/test_symbol_search.py +++ b/tests/unit/test_symbol_search.py @@ -2,12 +2,12 @@ import pytest -from automata.core.symbol.parser import parse_symbol +from automata.symbol.parser import parse_symbol def test_retrieve_source_code_by_symbol(symbols, symbol_search): with patch( - "automata.core.experimental.search.symbol_search.convert_to_fst_object", + "automata.experimental.search.symbol_search.convert_to_fst_object", return_value="module1", ) as mock_method: result = symbol_search.retrieve_source_code_by_symbol(symbols[0].uri) @@ -26,7 +26,7 @@ def test_symbol_references(symbols, symbol_search, symbol_graph_mock): def test_exact_search(symbol_search): with patch( - "automata.core.experimental.search.symbol_search.SymbolSearch._find_pattern_in_modules", + "automata.experimental.search.symbol_search.SymbolSearch._find_pattern_in_modules", return_value=["file1", "file2"], ): result = symbol_search.exact_search("pattern1") diff --git a/tests/unit/test_symbol_search_tool.py b/tests/unit/test_symbol_search_tool.py index 9016bf24..ab57135b 100644 --- a/tests/unit/test_symbol_search_tool.py +++ b/tests/unit/test_symbol_search_tool.py @@ -2,8 +2,8 @@ import pytest -from automata.core.tools.base import Tool -from automata.core.tools.builders.symbol_search import SymbolSearchToolkitBuilder +from automata.tools.base import Tool +from automata.tools.builders.symbol_search import SymbolSearchToolkitBuilder @pytest.fixture diff --git a/tests/unit/test_symbol_similarity.py b/tests/unit/test_symbol_similarity.py index 83244c69..7c704c5f 100644 --- a/tests/unit/test_symbol_similarity.py +++ b/tests/unit/test_symbol_similarity.py @@ -2,13 +2,13 @@ import numpy as np -from automata.core.embedding.base import ( +from automata.embedding.base import ( EmbeddingBuilder, EmbeddingSimilarityCalculator, EmbeddingVectorProvider, ) -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.symbol_embedding.base import ( +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.symbol_embedding.base import ( JSONSymbolEmbeddingVectorDatabase, SymbolCodeEmbedding, ) diff --git a/tests/unit/test_synchronizer.py b/tests/unit/test_synchronizer.py index d2eea62b..a388fb16 100644 --- a/tests/unit/test_synchronizer.py +++ b/tests/unit/test_synchronizer.py @@ -4,22 +4,22 @@ import networkx as nx import numpy as np -from automata.core.context_providers.symbol_synchronization import ( +from automata.context_providers.symbol_synchronization import ( SymbolProviderSynchronizationContext, ) -from automata.core.embedding.base import EmbeddingBuilder -from automata.core.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler -from automata.core.symbol_embedding.base import ( +from automata.embedding.base import EmbeddingBuilder +from automata.memory_store.symbol_code_embedding import SymbolCodeEmbeddingHandler +from automata.symbol_embedding.base import ( JSONSymbolEmbeddingVectorDatabase, SymbolCodeEmbedding, ) -from ..utils.factories import symbol_graph_static_test # noqa: F811 +from ..utils.factories import symbol_graph_static_test # noqa: F401, F811 def test_build_graph_and_handler_and_synchronize( - temp_output_filename, mock_simple_method_symbols, symbol_graph_static_test -): # noqa: F811 + temp_output_filename, mock_simple_method_symbols, symbol_graph_static_test # noqa: F811 +): symbol1 = mock_simple_method_symbols[0] symbol2 = mock_simple_method_symbols[1] symbol3 = mock_simple_method_symbols[2] @@ -52,7 +52,7 @@ def test_build_graph_and_handler_and_synchronize( symbol_graph_tester.navigator._graph = G with SymbolProviderSynchronizationContext() as synchronization_context: - from automata.core.context_providers.symbol_synchronization import ( + from automata.context_providers.symbol_synchronization import ( SymbolProviderRegistry, ) diff --git a/tests/unit/test_task.py b/tests/unit/test_task.py index c4e85212..3d5c1500 100644 --- a/tests/unit/test_task.py +++ b/tests/unit/test_task.py @@ -4,8 +4,8 @@ import pytest from automata.config.base import AgentConfigName -from automata.core.tasks.base import TaskStatus -from automata.core.tasks.tasks import AutomataTask +from automata.tasks.base import TaskStatus +from automata.tasks.tasks import AutomataTask from ..conftest import MockRepositoryClient diff --git a/tests/unit/test_task_database.py b/tests/unit/test_task_database.py index 1655efe9..c28ea4a9 100644 --- a/tests/unit/test_task_database.py +++ b/tests/unit/test_task_database.py @@ -2,9 +2,9 @@ import pytest -from automata.core.tasks.agent_database import AutomataAgentTaskDatabase -from automata.core.tasks.base import TaskStatus -from automata.core.tasks.tasks import AutomataTask +from automata.tasks.agent_database import AutomataAgentTaskDatabase +from automata.tasks.base import TaskStatus +from automata.tasks.tasks import AutomataTask @pytest.fixture(scope="module") diff --git a/tests/unit/test_task_environment.py b/tests/unit/test_task_environment.py index e31cbf63..90b6c9b8 100644 --- a/tests/unit/test_task_environment.py +++ b/tests/unit/test_task_environment.py @@ -1,7 +1,7 @@ import os from unittest.mock import MagicMock -from automata.core.tasks.base import TaskStatus +from automata.tasks.base import TaskStatus class TestURL: diff --git a/tests/unit/test_task_executor.py b/tests/unit/test_task_executor.py index 659139b4..26393f11 100644 --- a/tests/unit/test_task_executor.py +++ b/tests/unit/test_task_executor.py @@ -2,12 +2,12 @@ import pytest -from automata.core.code_handling.py.reader import PyReader -from automata.core.code_handling.py.writer import PyWriter -from automata.core.singletons.py_module_loader import py_module_loader -from automata.core.tasks.base import Task, TaskStatus -from automata.core.tasks.executor import AutomataTaskExecutor, ITaskExecution +from automata.code_handling.py.reader import PyReader +from automata.code_handling.py.writer import PyWriter from automata.core.utils import get_root_py_fpath +from automata.singletons.py_module_loader import py_module_loader +from automata.tasks.base import Task, TaskStatus +from automata.tasks.executor import AutomataTaskExecutor, ITaskExecution # TODO - Unify module loader fixture diff --git a/tests/unit/test_tool.py b/tests/unit/test_tool.py index 93da84ac..69341ef5 100644 --- a/tests/unit/test_tool.py +++ b/tests/unit/test_tool.py @@ -2,7 +2,7 @@ import pytest -from automata.core.tools.base import Tool +from automata.tools.base import Tool class TestTool(Tool): diff --git a/tests/utils/factories.py b/tests/utils/factories.py index 72bb1789..8cd54813 100644 --- a/tests/utils/factories.py +++ b/tests/utils/factories.py @@ -2,9 +2,9 @@ import pytest -from automata.core.experimental.search.symbol_search import SymbolSearch -from automata.core.singletons.dependency_factory import dependency_factory -from automata.core.symbol.graph import SymbolGraph +from automata.experimental.search.symbol_search import SymbolSearch +from automata.singletons.dependency_factory import dependency_factory +from automata.symbol.graph import SymbolGraph @pytest.fixture