Enhance NEAR AI Agent Studio with improved documentation and interact…

…ive features - Updated README.md to provide a clearer overview of the NEAR AI Agent Studio - Refactored chat.py to introduce an enhanced interactive chat assistant with guided tutorials and improved validation for agent creation. - Added new commands for agent configuration and creation, allowing users to specify roles and capabilities directly. - Improved quickstart.sh script to streamline setup instructions and enhance user experience during the initial configuration. - Updated agent templates to include role-specific configurations and capabilities, facilitating easier agent development.
jbarnes850 · Jan 15, 2025 · 5560cf5 · 5560cf5
1 parent eb25afc
commit 5560cf5
Show file tree

Hide file tree

Showing 21 changed files with 1,659 additions and 1,182 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # NEAR AI Agent Studio
 
-A production-ready starter kit for building AI-powered agents and multi-agent swarms on NEAR. This template provides the essential building blocks for creating autonomous agents that can interact with the NEAR blockchain, make decisions using LLMs, and collaborate in swarms.
+A production-ready starter kit for building AI agents and multi-agent swarms on NEAR. This template provides the essential building blocks for creating autonomous agents that can interact with the NEAR blockchain, make decisions using LLMs, and collaborate in swarms. The NEAR AI Agent Studio is an educational and interactive starter kit designed for developers looking to build AI agents and agentic applications on NEAR.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![NEAR](https://img.shields.io/badge/NEAR-Protocol-blue.svg)](https://near.org)
@@ -10,75 +10,7 @@ A production-ready starter kit for building AI-powered agents and multi-agent sw
 [![Hyperbolic](https://img.shields.io/badge/LLM-Hyperbolic-purple.svg)](https://hyperbolic.xyz)
 [![Lava Network](https://img.shields.io/badge/RPC-Lava%20Network-orange.svg)](https://www.lavanet.xyz/get-started/near)
 
-## Table of Contents
-1. [Overview](#overview)
-2. [Features](#features)
-3. [Getting Started](#-getting-started)
-4. [Core Components](#-core-components)
-5. [Interactive Features](#-interactive-features)
-6. [Examples](#-examples)
-7. [Documentation](#-documentation)
-8. [Contributing](#-contributing)
-
-## Overview
-
-The NEAR AI Agent Studio is an educational and interactive starter kit designed for developers looking to build AI-powered applications on NEAR. It combines three powerful paradigms:
-- 🧠 Multi-agent swarm intelligence for collaborative decision-making
-- 🗣️ Voice-powered agents for portfolio management and market analysis
-- 💬 Interactive chat with autonomous agents for onchain actions
-
-## 🔥 Features
-
-### 🧠 Swarm Intelligence
-
-Swarm intelligence enables multiple specialized agents to collaborate for better outcomes:
-
-- **Market Analyzer** agents evaluate price data and trading volumes
-- **Risk Manager** agents assess potential risks and exposure
-- **Strategy Optimizer** agents fine-tune execution parameters
-
-These agents work together through:
-1. Expertise-based evaluation
-2. Confidence scoring
-3. Transparent reasoning
-4. Consensus building
-
-### 🎙️ Interactive Voice Assistant
-
-Natural language interaction with your NEAR portfolio:
-- Real-time market analysis and insights
-- Portfolio balance monitoring
-- Transaction history tracking
-- Voice-powered trading suggestions
-- Market sentiment analysis
-
-### 🤖 Multi-Agent Strategy
-
-Watch specialized AI agents collaborate in real-time:
-
-1. **Market Analysis Phase**
-   - Price trend evaluation
-   - Volume analysis
-   - Market sentiment assessment
-   - Network monitoring
-
-2. **Risk Management Phase**
-   - Transaction risk assessment
-   - Portfolio exposure analysis
-   - Network security validation
-   - Gas optimization
-
-3. **Strategy Optimization Phase**
-   - Parameter fine-tuning
-   - Execution timing
-   - Slippage prediction
-   - Cost-benefit analysis
-
-4. **Consensus Building**
-   - Multi-agent voting
-   - Confidence scoring
-   - Detailed reasoning
-   - Transparent decisions
+![NEAR AI Agent Studio](./public/near-agent-studio.png)
 
 ## ⚡️ Getting Started
 
@@ -105,9 +37,6 @@ Before you begin, ensure you have:
 - Hyperbolic API key for LLM capabilities
   - Sign up at [hyperbolic.xyz](https://hyperbolic.xyz)
   - Free tier available for development
-- ElevenLabs API key for voice features (optional)
-  - Register at [elevenlabs.io](https://elevenlabs.io)
-  - Free tier includes basic voice synthesis
 
 ### Quick Start
 ```bash
@@ -127,6 +56,26 @@ chmod +x scripts/quickstart.sh  # Make script executable
 ./scripts/quickstart.sh
 ```
 
+The quickstart script will:
+1. Set up your development environment
+2. Create a NEAR testnet account
+3. Install example agents
+4. Launch an interactive chat assistant to help you create your first agent
+
+### Interactive Chat
+After setup, you'll enter an interactive chat session where you can:
+- Create new agents with `/create agent <name>`
+- Configure agents with `/config agent <name>`
+- Run multiple agents together with `/run-agents`
+- List available agents with `/list`
+- Get help anytime with `/help`
+
+Start the chat manually anytime:
+```bash
+near-swarm chat  # Regular mode
+near-swarm chat --tutorial create-first-agent  # Guided tutorial
+```
+
 ### Environment Setup
 ```bash
 # Copy environment template
@@ -138,53 +87,7 @@ cp .env.example .env
 # - NEAR_PRIVATE_KEY=your-private-key
 # - LLM_PROVIDER=hyperbolic
 # - LLM_API_KEY=your-api-key
-# Optional:
-# - ELEVENLABS_API_KEY=your-key  # For voice features
-
-# Verify installation
-near-swarm config validate
 ```
-
-### Running Demos
-```bash
-# Run all demos
-python near_swarm/examples/demo.py all
-
-# Run specific components
-python near_swarm/examples/demo.py voice    # Voice assistant
-python near_swarm/examples/demo.py strategy # Multi-agent strategy
-python near_swarm/examples/demo.py chat    # Interactive chat
-
-# Create your first agent
-near-swarm create agent my-agent
-near-swarm plugins list  # View available plugins
-```
-
-### Troubleshooting
-
-If you encounter any issues:
-
-1. Ensure all dependencies are installed:
-```bash
-pip install -e ".[dev]"  # Install with development dependencies
-```
-
-2. Verify your Python version:
-```bash
-python --version  # Should be 3.12 or higher
-```
-
-3. Check your configuration:
-```bash
-near-swarm config show  # View current configuration
-```
-
-4. Common issues:
-- "Command not found": Ensure virtual environment is activated
-- Import errors: Verify installation with `pip list`
-- API errors: Check your API keys in `.env`
-- Git errors: Install git with `apt install git` or `brew install git`
-
 ## Core Components
 
 > **Tip**: Start with modifying the examples in `near_swarm/examples/` to understand the framework.
@@ -197,12 +100,12 @@ near-swarm config show  # View current configuration
 ```mermaid
 graph TB
     %% Core System
-    Core[Plugin System]
+    Core[Agent Framework]
     style Core fill:black,stroke:#00C1DE,stroke-width:3px,color:white
 
     %% Plugin Management
-    Registry[Plugin Registry]
-    Loader[Plugin Loader]
+    Registry[Agent Registry]
+    Loader[Agent Loader]
     Config[Configuration]
     style Registry fill:black,stroke:#00C1DE,stroke-width:2px,color:white
     style Loader fill:black,stroke:#00C1DE,stroke-width:2px,color:white
@@ -259,11 +162,11 @@ graph TB
     SwarmAgent --> Evaluation
 ```
 
-The architecture combines a flexible plugin system with swarm intelligence capabilities:
+The architecture combines a flexible agent framework with swarm intelligence capabilities:
 
-1. **Plugin System Core**
-   - Plugin Registry for managing available plugins
-   - Plugin Loader for dynamic loading/unloading
+1. **Agent Framework Core**
+   - Agent Registry for managing available agents
+   - Agent Loader for dynamic loading/unloading
    - Configuration management with validation
 
 2. **Core Services**
@@ -272,17 +175,17 @@ The architecture combines a flexible plugin system with swarm intelligence capab
    - LLM provider interface
 
 3. **Agent Plugins**
-   - Token Transfer plugin for NEAR transactions
-   - Arbitrage plugin for market opportunities
-   - Custom plugins for specialized strategies
+   - Token Transfer agent for NEAR transactions
+   - Arbitrage agent for market opportunities
+   - Custom agents for specialized strategies
 
 4. **Swarm Intelligence**
    - Swarm Agent for coordinated decision-making
    - Consensus building through multi-agent voting
    - Role-based evaluation with LLM reasoning
 
 This architecture enables:
-- Easy extension through plugins
+- Easy extension through agent plugins
 - Coordinated decision-making via swarm intelligence
 - Secure transaction handling
 - Market-aware operations
@@ -358,42 +261,6 @@ peer_agent = SwarmAgent(config, SwarmConfig(role="risk_manager"))
 await main_agent.join_swarm([peer_agent])
 ```
 
-## 📚 Interactive Features
-
-### Voice Commands
-- Portfolio queries
-- Market analysis
-- Transaction requests
-- Strategy suggestions
-
-### Chat Commands
-- Market Analysis
-  ```bash
-  /market [symbol]  # Get market analysis
-  /trend [timeframe]  # Get trend analysis
-  /volume [symbol]  # Volume analysis
-  ```
-
-- Risk Management
-  ```bash
-  /risk [action]  # Risk assessment
-  /balance  # Check portfolio balance
-  /positions  # List open positions
-  ```
-
-- Strategy
-  ```bash
-  /strategy [action]  # Strategy suggestions
-  /portfolio  # Portfolio overview
-  ```
-
-- Development Tools
-  ```bash
-  /ws  # Manage workspace
-  /env  # Configure environment
-  /config  # View/modify settings
-  ```
-
 ## 📄 Examples
 
 For more examples and reference implementations, check out our [examples directory](near_swarm/examples/):

diff --git a/agents/decision-maker.yaml b/agents/decision-maker.yaml
@@ -0,0 +1,30 @@
+name: decision-maker
+environment: development
+log_level: INFO
+
+llm:
+  provider: hyperbolic
+  api_key: ${LLM_API_KEY}
+  model: ${LLM_MODEL}
+  temperature: 0.7
+  max_tokens: 2000
+  api_url: ${LLM_API_URL}
+
+plugins:
+  - name: decision-maker
+    role: strategy_optimizer
+    capabilities:
+      - strategy_optimization
+      - decision_making
+      - risk_management
+    custom_settings:
+      min_confidence_threshold: 0.8
+      risk_tolerance: medium
+      max_retries: 3
+      timeout: 30
+      decision_interval: 300
+      risk_threshold: 0.1
+
+custom_settings:
+  environment: development
+  log_level: INFO 
diff --git a/agents/price-monitor.yaml b/agents/price-monitor.yaml
@@ -0,0 +1,30 @@
+name: price-monitor
+environment: development
+log_level: INFO
+
+llm:
+  provider: hyperbolic
+  api_key: ${LLM_API_KEY}
+  model: ${LLM_MODEL}
+  temperature: 0.7
+  max_tokens: 2000
+  api_url: ${LLM_API_URL}
+
+plugins:
+  - name: price-monitor
+    role: market_analyzer
+    capabilities:
+      - price_monitoring
+      - trend_analysis
+      - market_assessment
+    custom_settings:
+      min_confidence_threshold: 0.7
+      risk_tolerance: medium
+      max_retries: 3
+      timeout: 30
+      update_interval: 60
+      alert_threshold: 0.05
+
+custom_settings:
+  environment: development
+  log_level: INFO 
diff --git a/near_swarm/agents/decision-maker/__init__.py b/near_swarm/agents/decision-maker/__init__.py
@@ -0,0 +1,7 @@
+"""
+Decision Making Agent Package
+"""
+
+from .plugin import DecisionMakerPlugin
+
+__all__ = ['DecisionMakerPlugin'] 
diff --git a/near_swarm/agents/decision-maker/agent.yaml b/near_swarm/agents/decision-maker/agent.yaml
@@ -0,0 +1,40 @@
+# Decision Maker Agent Configuration
+name: decision-maker
+environment: development
+log_level: INFO
+
+# LLM Configuration
+llm:
+  provider: hyperbolic
+  model: deepseek-ai/DeepSeek-V3
+  api_key: ${LLM_API_KEY}
+  temperature: 0.7
+  max_tokens: 2000
+  api_url: https://api.hyperbolic.xyz/v1
+  system_prompt: |
+    You are a decision-making agent in the NEAR swarm.
+    Evaluate market opportunities and make strategic decisions.
+    Always respond in JSON format with confidence levels.
+
+# Agent Settings
+custom_settings:
+  min_confidence_threshold: 0.7
+  risk_tolerance: medium
+  max_retries: 3
+  timeout: 30
+
+# Plugin Configuration
+plugins:
+  - name: decision-maker
+    role: strategy_optimizer
+    capabilities:
+      - strategy_optimization
+      - decision_making
+      - risk_management
+    custom_settings:
+      min_confidence_threshold: 0.7
+      risk_tolerance: medium
+      max_retries: 3
+      timeout: 30
+      min_profit_threshold: 0.002  # 0.2% minimum profit
+      max_position_size: 10000  # Maximum position size in USD