From 0da70c0d74f292b10051e776d99eb6151ff4e19d Mon Sep 17 00:00:00 2001 From: Dmytro Nikolaiev Date: Mon, 10 Feb 2025 16:26:23 -0500 Subject: [PATCH 1/3] Update architecture.md --- README.md | 14 ++++++- docs/architecture.md | 96 ++++++-------------------------------------- 2 files changed, 26 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index cdc120df..be91685f 100644 --- a/README.md +++ b/README.md @@ -214,10 +214,22 @@ Check out the `examples/` directory for more complete examples: ### Running Tests ```bash -poetry run pytest +# Run all tests +make all-tests + +# Run specific test suites +make unit-tests +make integration-tests # Requires API keys to be specified ``` ### Code Quality + +The project uses: +- Black for code formatting +- isort for import sorting +- ruff for linting +- mypy for type checking + ```bash # Format code poetry run black . diff --git a/docs/architecture.md b/docs/architecture.md index 62f27088..e7efe374 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,9 +1,9 @@ -# AlphaSwarm Framework - -AlphaSwarm is a framework for building autonomous crypto trading agents. It is currently built with the [smolagents](https://github.com/huggingface/smolagents) framework providing the main agentic loop. AlphaSwarm adds value on top of this in the form of customizable services, tools, and agent configurations geared for trading. +# AlphaSwarm Architecture ## Introduction +AlphaSwarm is currently built with the [smolagents](https://github.com/huggingface/smolagents) framework. AlphaSwarm adds value on top of this in the form of customizable services, tools, and agent configurations geared for trading. + ### About `CodeAgent` AlphaSwarm agents are currently based on the `CodeAgent` from `smolagents`. AlphaSwarm additionally provides specialized tools and configurations for crypto trading. The key benefit of adopting the `CodeAgent` has to do with the way it uses tools: @@ -14,11 +14,6 @@ AlphaSwarm agents are currently based on the `CodeAgent` from `smolagents`. Alph For code execution, we are currently relying on smolagents' [local Python code execution](https://huggingface.co/docs/smolagents/v1.6.0/en/tutorials/secure_code_execution#local-python-interpreter) framework. Secured, remote execution is part of the roadmap. -## Requirements - -- Python 3.11 or higher -- Poetry for dependency management - ## Version Support (Initially Planned) - Uniswap: V2 and V3 protocols @@ -64,16 +59,18 @@ The agent is defined by: All tools in AlphaSwarm extend the smolagents `Tool` base class which requires: ```python -class Tool: - # Required class attributes +from smolagents import Tool + + +class MyTool(Tool): name: str # Name used to reference the tool description: str # Description of functionality inputs: Dict[str, Dict[str, ] # See below for input schema - output_type: str # Output type from AUTHORIZED_TYPES + output_type: str # Output type from authorized types # Required method - def forward(self, *args, **kwargs): # Core implementation - pass + def forward(self, *args, **kwargs): + pass # Core tool implementation ``` The `inputs` dictionary must specify the schema for each input parameter: @@ -83,22 +80,12 @@ inputs = { "type": str, # Must be one of AUTHORIZED_TYPES "description": str, # Agent-readable description "nullable": bool, # Optional, if parameter can be None - "default": ..., # A literal value of the parameter's type + "default": ..., # A literal value of the parameter's type } } ``` -Authorized types are: -- string -- boolean -- integer -- number -- image -- audio -- array -- object -- any -- null +Authorized types are: string, boolean, integer, number, image, audio, array, object, any, null. Tools can be created either by: 1. Subclassing the `Tool` class and implementing the required attributes/methods (preferred) @@ -109,7 +96,7 @@ Please review [tools docs](https://huggingface.co/docs/smolagents/tutorials/tool ## Security - Private keys and API credentials must be handled via environment variables -- Code execution is sandboxed via smolagents +- Code execution is sandboxed via `smolagents` - See SECURITY.md for vulnerability reporting procedures ## Architecture Overview @@ -217,63 +204,6 @@ alphaswarm/ └── config.py # Configuration management ``` -## Configuration - -The framework currently uses a YAML-based configuration system (`config/default.yaml`) with environment variable substitution. Key configuration areas include: - -- LLM settings -- Network environments -- Trading venues -- Chain configurations -- Token definitions - -Environment variables are defined in `.env` (use `.env.example` as a template). - -Configuration files and mechanisms are *subject to change* in the near term. - -## Development Guide - -### Prerequisites - -1. Install Poetry (package manager): -```bash -curl -sSL https://install.python-poetry.org | python3 - -``` - -2. Install dependencies: -```bash -poetry install --with dev -``` - -### Running Tests - -```bash -# Run all tests -make all-tests - -# Run specific test suites -make unit-tests -make integration-tests # Requires API keys to be specified -``` - -### Code Style - -The project uses: -- Black for code formatting -- isort for import sorting -- mypy for type checking -- ruff for linting - -Format and lint code: -```bash -make format -make dev-lint -``` - -## License - -This project is licensed under the MIT License. - ## Future Evolution: Integration with Theoriq Protocol AlphaSwarm could potentially evolve from a standalone agent framework into a key component of the Theoriq protocol ecosystem. The core evolution will involve moving from single agents to a distributed, specialized multi-agent architecture: From 836df55046d4f471e0b9cd2e7d93bd4e4fc13606 Mon Sep 17 00:00:00 2001 From: Dmytro Nikolaiev Date: Tue, 11 Feb 2025 17:15:40 -0500 Subject: [PATCH 2/3] Tweaks to delete ambiguous information --- docs/architecture.md | 73 ++++++++------------------------------------ 1 file changed, 12 insertions(+), 61 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index e7efe374..83dce33d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -20,40 +20,6 @@ For code execution, we are currently relying on smolagents' [local Python code e - Chains: Ethereum, Base, Solana - Test Networks: Ethereum Sepolia -### Agent Creation Example - -Here's a simple example showing the core components of an AlphaSwarm agent: - -```python -from alphaswarm.agent import AlphaSwarmAgent -from alphaswarm.tools import PriceTool, TradeExecutionTool - - -# 1. Initialize tools -tools = [ - PriceTool(), # For price data access - TradeExecutionTool() # For trade execution -] - -# 2. Create the agent -agent = AlphaSwarmAgent( - tools=tools, - model_id="anthropic/claude-3-5-sonnet-latest" - system_prompt="path/to/custom/prompt.txt" # Coming soon -) - -# 3. Interact with the agent -async def example(): - response = await agent.process_message("What's the current price of ETH?") -``` - -The agent is defined by: -1. A set of tools (for accessing data, executing trades, etc.) -2. Any necessary configuration (like API keys) -3. A system prompt (currently using smolagents default) - -> **Coming Soon**: A reference system prompt file will be included in the repository. This will serve as a base template for creating custom system prompts, allowing you to modify the agent's core behavior while maintaining compatibility with the smolagents framework. - ## Tool Interfaces All tools in AlphaSwarm extend the smolagents `Tool` base class which requires: @@ -160,48 +126,33 @@ The architecture consists of three main components: #### Tools Tools define interfaces for how the agent interacts with services and certain interface functions. A tool can be: -- A thin wrapper around a service (e.g., AlchemyPriceHistory) +- A thin wrapper around a service - A composite tool combining multiple services -- A standalone implementation (e.g., PriceTool) +- A standalone implementation #### Services Services contain the core implementation logic decoupled from any specific tool: -- API clients (e.g., AlchemyClient) -- Chain interfaces (e.g., Web3Client) - *moving soon* -- Exchange interfaces (e.g., UniswapClient) - *moving soon* +- API clients +- Chain interfaces +- Exchange interfaces #### Interfaces *Possible* interfaces for interacting with the agent: - CLI - Telegram -- Infinity Studio - Cron Runner +- Infinity Studio ### Current Directory Structure ``` alphaswarm/ -├── agent/ # Agent implementation -├── core/ # Core framework components -├── tools/ # Tool definitions -│ ├── alchemy/ # Alchemy-specific tools -│ ├── strategy_analysis/ # Strategy analysis tools -│ ├── exchanges/ # Exchange-specific tools -│ └── price_tool.py -├── services/ # Service implementations -│ ├── alchemy/ # Alchemy API client -│ ├── chains/ # Blockchain clients -│ │ ├── base.py # Base chain interface -│ │ ├── factory.py # Chain client factory -│ │ ├── evm.py # EVM chain implementation -│ │ └── sol.py # Solana implementation -│ └── exchanges/ # Exchange clients -│ ├── base.py # Base exchange interface -│ ├── factory.py # Exchange client factory -│ ├── jupiter/ # Jupiter DEX implementation -│ └── uniswap/ # Uniswap implementation -├── utils/ # Utility functions and helpers -└── config.py # Configuration management +├── agent/ # Agent and agent clients implementation +├── core/ # Core framework components +├── services/ # Service implementations +├── tools/ # Tool definitions +├── utils/ # Utility functions and helpers +└── config.py # Configuration management ``` ## Future Evolution: Integration with Theoriq Protocol From 97bcb8c871e358aebd25d6556c4f3a6b1799ed63 Mon Sep 17 00:00:00 2001 From: Ethan Date: Wed, 12 Feb 2025 19:52:25 +0000 Subject: [PATCH 3/3] update architecture doc --- docs/architecture.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 83dce33d..b88d134f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,7 +2,7 @@ ## Introduction -AlphaSwarm is currently built with the [smolagents](https://github.com/huggingface/smolagents) framework. AlphaSwarm adds value on top of this in the form of customizable services, tools, and agent configurations geared for trading. +AlphaSwarm is currently built with the [smolagents](https://github.com/huggingface/smolagents) framework. AlphaSwarm adds value on top of this in the form of customizable services, tools, and agent configurations geared for trading and DeFi. ### About `CodeAgent` @@ -153,18 +153,4 @@ alphaswarm/ ├── tools/ # Tool definitions ├── utils/ # Utility functions and helpers └── config.py # Configuration management -``` - -## Future Evolution: Integration with Theoriq Protocol - -AlphaSwarm could potentially evolve from a standalone agent framework into a key component of the Theoriq protocol ecosystem. The core evolution will involve moving from single agents to a distributed, specialized multi-agent architecture: - -### Distributed Agent Architecture - -Instead of having individual agents handle all responsibilities, functionality will be distributed across specialized agent types: - -1. **Observer Agents**: Monitor data and emit messages when specific criteria are met -2. **Cognitive Agents**: Process messages from Observer Agents and generate trading decisions -3. **Action Agents**: Execute intents generated by Cognitive Agents, optimizing execution across venues - -This transition would allow for greater specialization and efficiency, with agents focusing on specific tasks rather than handling everything locally. Initially, AlphaSwarm could maintain a simpler architecture where these functions are implemented as tools within single agents, but the framework is designed with this future evolution in mind. \ No newline at end of file +``` \ No newline at end of file