Priyanshi Saxena commited on
Commit
81a07ed
Β·
1 Parent(s): 598f07a

Simplify README and force clean rebuild

Browse files
Files changed (2) hide show
  1. README.md +24 -344
  2. README_old.md +431 -0
README.md CHANGED
@@ -9,377 +9,57 @@ app_file: app.py
9
  pinned: false
10
  ---
11
 
12
- # Web3 Research Co-Pilot
13
 
14
- A professional AI-powered cryptocurrency research assistant that provides real-time market analysis, DeFi intelligence, and blockchain insights through an elegant web interface.
15
 
16
- 🌐 **Live Demo**: https://archcoder-web3-copilot.hf.space
17
 
18
- ![Web3 Research Co-Pilot](https://img.shields.io/badge/Web3-Research%20Co--Pilot-0066ff?style=for-the-badge)
19
- ![Python](https://img.shields.io/badge/Python-3.11+-blue?style=for-the-badge&logo=python)
20
- ![FastAPI](https://img.shields.io/badge/FastAPI-Latest-green?style=for-the-badge&logo=fastapi)
21
- ![LangChain](https://img.shields.io/badge/LangChain-0.3.0-purple?style=for-the-badge)
22
 
23
- ## ✨ Features
24
-
25
- - **AI-Powered Research**: Advanced LLM analysis using Google Gemini
26
- - **Real-Time Data**: Live market data from CoinGecko, DeFiLlama, and Etherscan
27
- - **Interactive Visualizations**: Dynamic charts and graphs powered by Plotly
28
- - **Professional UI**: Minimalist, responsive web interface
29
- - **Multi-Chain Support**: Ethereum, DeFi protocols, and Layer 2 solutions
30
- - **Comprehensive Analytics**: Market trends, yield optimization, and risk assessment
31
-
32
- ## πŸš€ Quick Start
33
-
34
- ### Prerequisites
35
-
36
- - Python 3.11+
37
- - Google Gemini API Key (required)
38
- - Optional: CoinGecko API Key (for higher rate limits)
39
- - Optional: Etherscan API Key (for blockchain data)
40
-
41
- ### Installation
42
-
43
- 1. **Clone the repository**
44
- ```bash
45
- git clone https://github.com/Transcendental-Programmer/web3-research-agent.git
46
- cd web3-research-agent
47
- ```
48
-
49
- 2. **Install dependencies**
50
  ```bash
51
  pip install -r requirements.txt
52
  ```
53
 
54
- 3. **Set up environment variables**
55
-
56
- Create a `.env` file in the project root:
57
  ```bash
58
- cp .env.example .env
59
- ```
60
-
61
- Edit `.env` with your API keys:
62
- ```properties
63
- # Required
64
- GEMINI_API_KEY=your_gemini_api_key_here
65
-
66
- # Optional (for enhanced functionality)
67
- COINGECKO_API_KEY=your_coingecko_api_key_here
68
- ETHERSCAN_API_KEY=your_etherscan_api_key_here
69
  ```
70
 
71
- 4. **Run the application**
72
  ```bash
73
  python app.py
74
  ```
75
 
76
- 5. **Access the interface**
77
- - **Local Development**: http://localhost:7860
78
- - **Production/Cloud**: Check your hosting platform's port forwarding
79
- - **Docker**: http://localhost:7860
80
-
81
- ## πŸš€ HuggingFace Spaces Deployment
82
-
83
- This project is configured for HuggingFace Spaces deployment with Docker SDK.
84
-
85
- ### Quick Deploy to HF Spaces
86
-
87
- 1. **Fork/Clone this repository**
88
- 2. **Create a new HuggingFace Space**:
89
- - Go to [HuggingFace Spaces](https://huggingface.co/spaces)
90
- - Click "Create new Space"
91
- - Choose "Docker" as the SDK
92
- - Upload your repository files
93
-
94
- 3. **Configure Environment Variables**:
95
- In your Space settings, add:
96
- ```
97
- GEMINI_API_KEY=your_gemini_api_key
98
- COINGECKO_API_KEY=your_coingecko_api_key
99
- ETHERSCAN_API_KEY=your_etherscan_api_key
100
- ```
101
-
102
- 4. **Deploy via Git**:
103
- ```bash
104
- git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
105
- git push hf main
106
- ```
107
-
108
- ### HF Spaces Configuration
109
-
110
- The project includes a proper `README.md` header for HF Spaces:
111
- ```yaml
112
- title: Web3 Research Co-Pilot
113
- emoji: πŸš€
114
- colorFrom: blue
115
- colorTo: purple
116
- sdk: docker
117
- app_file: app.py
118
- ```
119
-
120
- ## 🐳 Docker Deployment
121
-
122
- ### Local Docker
123
-
124
- ```bash
125
- # Build the image
126
- docker build -t web3-research-copilot .
127
-
128
- # Run the container
129
- docker run -p 7860:7860 \
130
- -e GEMINI_API_KEY=your_key_here \
131
- -e COINGECKO_API_KEY=your_key_here \
132
- -e ETHERSCAN_API_KEY=your_key_here \
133
- web3-research-copilot
134
- ```
135
-
136
- ### HuggingFace Spaces
137
-
138
- This project is optimized for HuggingFace Spaces deployment:
139
 
140
- 1. **Create a new Space**:
141
- - Go to [HuggingFace Spaces](https://huggingface.co/spaces)
142
- - Click "Create new Space"
143
- - Choose "Docker" as the SDK
144
- - Set visibility to "Public" or "Private"
145
-
146
- 2. **Configure Environment Variables**:
147
- In your Space settings, add:
148
- ```
149
- GEMINI_API_KEY=your_gemini_api_key
150
- COINGECKO_API_KEY=your_coingecko_api_key
151
- ETHERSCAN_API_KEY=your_etherscan_api_key
152
- ```
153
-
154
- 3. **Deploy**:
155
- ```bash
156
- git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
157
- git push hf main
158
- ```
159
 
160
- **Live Example**: https://archcoder-web3-copilot.hf.space
 
 
 
161
 
162
- ## πŸ”„ Development Setup
163
 
164
- ### Adding HuggingFace Remote
 
165
 
166
- To deploy to your HuggingFace Space:
167
 
168
  ```bash
169
- # Add HuggingFace remote
170
- git remote add hf https://huggingface.co/spaces/ArchCoder/web3-copilot
171
-
172
- # Or for your own space
173
  git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
174
-
175
- # Deploy to HF Spaces
176
  git push hf main
177
  ```
178
 
179
- ## πŸ“Š Testing
180
-
181
- Run the comprehensive test suite:
182
-
183
- ```bash
184
- python test_suite.py
185
- ```
186
-
187
- Expected output:
188
- ```
189
- πŸš€ Web3 Research Co-Pilot - Test Suite
190
- ==================================================
191
- βœ… All imports successful
192
- βœ… Configuration validated
193
- βœ… Visualizations working
194
- βœ… Tools initialized
195
- βœ… Service functional
196
- βœ… API endpoints healthy
197
- βœ… Performance acceptable
198
-
199
- Tests passed: 7/7
200
- Success rate: 100.0%
201
- πŸŽ‰ All tests passed!
202
- ```
203
-
204
- ## πŸ—οΈ Project Structure
205
-
206
- ```
207
- web3-research-agent/
208
- β”œβ”€β”€ app.py # Main FastAPI application
209
- β”œβ”€β”€ requirements.txt # Python dependencies
210
- β”œβ”€β”€ pyproject.toml # Project configuration
211
- β”œβ”€β”€ uv.lock # Dependency lock file
212
- β”œβ”€β”€ test_suite.py # Comprehensive test suite
213
- β”œβ”€β”€ .env.example # Environment template
214
- β”œβ”€β”€ src/ # Source code
215
- β”‚ β”œβ”€β”€ __init__.py
216
- β”‚ β”œβ”€β”€ research_agent.py # Main agent logic
217
- β”‚ β”œβ”€β”€ enhanced_agent.py # Enhanced agent features
218
- β”‚ β”œβ”€β”€ config.py # Configuration management
219
- β”‚ β”œβ”€β”€ cache_manager.py # Response caching
220
- β”‚ β”œβ”€β”€ api_clients.py # External API clients
221
- β”‚ β”œβ”€β”€ defillama_client.py # DeFiLlama integration
222
- β”‚ β”œβ”€β”€ news_aggregator.py # News and social data
223
- β”‚ β”œβ”€β”€ portfolio_analyzer.py # Portfolio analysis
224
- β”‚ └── visualizations.py # Chart generation
225
- └── README.md # This file
226
- ```
227
-
228
- ## πŸ”§ Configuration
229
-
230
- ### Required Environment Variables
231
-
232
- | Variable | Description | Required |
233
- |----------|-------------|----------|
234
- | `GEMINI_API_KEY` | Google Gemini API key for AI analysis | βœ… |
235
-
236
- ### Optional Environment Variables
237
-
238
- | Variable | Description | Default |
239
- |----------|-------------|---------|
240
- | `COINGECKO_API_KEY` | CoinGecko API key for enhanced rate limits | None |
241
- | `ETHERSCAN_API_KEY` | Etherscan API key for blockchain data | None |
242
- | `AIRAA_WEBHOOK_URL` | AIRAA integration webhook URL | None |
243
- | `AIRAA_API_KEY` | AIRAA API authentication key | None |
244
-
245
- ### Getting API Keys
246
-
247
- 1. **Google Gemini API**:
248
- - Go to [Google AI Studio](https://aistudio.google.com/)
249
- - Create a new API key
250
- - Copy the key to your `.env` file
251
-
252
- 2. **CoinGecko API** (optional):
253
- - Sign up at [CoinGecko](https://www.coingecko.com/api)
254
- - Get your free API key
255
- - Provides higher rate limits
256
-
257
- 3. **Etherscan API** (optional):
258
- - Register at [Etherscan](https://etherscan.io/apis)
259
- - Create a free API key
260
- - Enables blockchain data queries
261
-
262
- ## 🎯 Usage Examples
263
-
264
- ### Market Analysis
265
- ```
266
- "Analyze Bitcoin price trends and institutional adoption patterns"
267
- ```
268
-
269
- ### DeFi Research
270
- ```
271
- "Compare top DeFi protocols by TVL, yield, and risk metrics"
272
- ```
273
-
274
- ### Layer 2 Analysis
275
- ```
276
- "Evaluate Ethereum Layer 2 scaling solutions and adoption metrics"
277
- ```
278
-
279
- ### Yield Optimization
280
- ```
281
- "Identify optimal yield farming strategies across multiple chains"
282
- ```
283
-
284
- ## 🌐 API Endpoints
285
-
286
- | Endpoint | Method | Description |
287
- |----------|--------|-------------|
288
- | `/` | GET | Web interface |
289
- | `/status` | GET | System status and configuration |
290
- | `/query` | POST | Process research queries |
291
- | `/health` | GET | Health check |
292
-
293
- ### Query API Example
294
-
295
- ```bash
296
- curl -X POST "http://localhost:7860/query" \
297
- -H "Content-Type: application/json" \
298
- -d '{"query": "What is the current Bitcoin price?"}'
299
- ```
300
-
301
- ## πŸ› Troubleshooting
302
-
303
- ### Port Access Issues
304
-
305
- **Problem**: Can't access the app on http://localhost:7860 or http://0.0.0.0:7860
306
-
307
- **Solutions**:
308
-
309
- 1. **Check if the app is running**:
310
- ```bash
311
- ps aux | grep "python app.py"
312
- ```
313
-
314
- 2. **Verify port binding**:
315
- ```bash
316
- netstat -tlnp | grep :7860
317
- ```
318
-
319
- 3. **For Development Environments (VS Code, etc.)**:
320
- - Look for port forwarding notifications
321
- - Check your IDE's "Ports" or "Forwarded Ports" tab
322
- - Use the forwarded URL provided by your development environment
323
-
324
- 4. **For Cloud/Remote Environments**:
325
- - The app binds to `0.0.0.0:7860` for external access
326
- - Use your platform's provided URL (not localhost)
327
- - Check firewall rules if on a VPS/server
328
-
329
- 5. **Local Network Access**:
330
- ```bash
331
- # Find your local IP
332
- hostname -I
333
- # Access via: http://YOUR_IP:7860
334
- ```
335
-
336
- ### Common Issues
337
-
338
- 1. **"GEMINI_API_KEY not configured"**
339
- - Ensure you've set the API key in your `.env` file
340
- - Verify the key is valid and has proper permissions
341
-
342
- 2. **"Connection refused" on port 7860**
343
- - Check if another process is using port 7860: `lsof -i :7860`
344
- - Ensure the app started successfully: `python app.py`
345
-
346
- 3. **Import errors**
347
- - Ensure all dependencies are installed: `pip install -r requirements.txt`
348
- - Check Python version compatibility (3.11+)
349
-
350
- 4. **Slow visualization loading**
351
- - Check your internet connection
352
- - API rate limits may be affecting data retrieval
353
-
354
- ### Getting Help
355
-
356
- - Check the test suite: `python test_suite.py`
357
- - Review logs in the terminal output
358
- - Verify API keys are configured correctly
359
- - Open an issue on GitHub with error details
360
-
361
- ## 🀝 Contributing
362
-
363
- 1. Fork the repository
364
- 2. Create a feature branch
365
- 3. Make your changes
366
- 4. Add tests for new functionality
367
- 5. Run the test suite
368
- 6. Submit a pull request
369
-
370
- ## πŸ“„ License
371
-
372
- This project is licensed under the MIT License - see the LICENSE file for details.
373
-
374
- ## πŸ™ Acknowledgments
375
 
376
- - **Google Gemini** for AI capabilities
377
- - **CoinGecko** for comprehensive market data
378
- - **DeFiLlama** for DeFi protocol analytics
379
- - **Etherscan** for blockchain data
380
- - **FastAPI** for the web framework
381
- - **Plotly** for interactive visualizations
382
 
383
  ---
384
 
385
- **Built with ❀️ for the Web3 community**
 
9
  pinned: false
10
  ---
11
 
12
+ # πŸš€ Web3 Research Co-Pilot
13
 
14
+ AI-powered cryptocurrency research assistant with real-time Web3 data analysis.
15
 
16
+ **Live Demo**: https://archcoder-web3-copilot.hf.space
17
 
18
+ ## Quick Start
 
 
 
19
 
20
+ 1. **Install dependencies**:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
21
  ```bash
22
  pip install -r requirements.txt
23
  ```
24
 
25
+ 2. **Set up API key**:
 
 
26
  ```bash
27
+ export GEMINI_API_KEY="your_gemini_api_key"
 
 
 
 
 
 
 
 
 
 
28
  ```
29
 
30
+ 3. **Run**:
31
  ```bash
32
  python app.py
33
  ```
34
 
35
+ 4. **Open**: http://localhost:7860
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
36
 
37
+ ## Features
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
38
 
39
+ - πŸ€– **AI Analysis** with Google Gemini
40
+ - πŸ“Š **Real-time Data** from CoinGecko, DeFiLlama, Etherscan
41
+ - πŸ“ˆ **Interactive Charts** and visualizations
42
+ - πŸ’Ό **Professional UI** with FastAPI
43
 
44
+ ## API Keys
45
 
46
+ - **Required**: [GEMINI_API_KEY](https://aistudio.google.com/)
47
+ - **Optional**: COINGECKO_API_KEY, ETHERSCAN_API_KEY
48
 
49
+ ## Deploy to HuggingFace Spaces
50
 
51
  ```bash
 
 
 
 
52
  git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
 
 
53
  git push hf main
54
  ```
55
 
56
+ ## Usage Examples
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
57
 
58
+ - "What's Bitcoin's current price?"
59
+ - "Show top DeFi protocols by TVL"
60
+ - "Analyze Ethereum gas prices"
61
+ - "Compare BTC vs ETH performance"
 
 
62
 
63
  ---
64
 
65
+ Built with ❀️ for Web3 research
README_old.md ADDED
@@ -0,0 +1,431 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ title: Web3 Research Co-Pilot
3
+ emoji: πŸš€
4
+ colorFrom: blue
5
+ colorTo: purple
6
+ sdk: docker
7
+ sdk_version: "latest"
8
+ app_file: app.py
9
+ pinned: false
10
+ ---
11
+
12
+ # πŸš€ Web3 Research Co-Pilot
13
+
14
+ AI-powered cryptocurrency research assistant with real-time market data and professional analysis.
15
+
16
+ **🌐 Live Demo**: https://archcoder-web3-copilot.hf.space
17
+
18
+ ## ⚑ Quick Start
19
+
20
+ ### 1. Get API Key
21
+ Get your **Google Gemini API key** from [Google AI Studio](https://aistudio.google.com/)
22
+
23
+ ### 2. Run Locally
24
+ ```bash
25
+ git clone https://github.com/Transcendental-Programmer/web3-research-agent.git
26
+ cd web3-research-agent
27
+ pip install -r requirements.txt
28
+
29
+ # Create .env file
30
+ echo "GEMINI_API_KEY=your_api_key_here" > .env
31
+
32
+ # Run the app
33
+ python app.py
34
+ ```
35
+
36
+ ### 3. Access
37
+ Open http://localhost:7860 in your browser
38
+
39
+ ## πŸ”§ Optional Setup
40
+
41
+ Add these to your `.env` for enhanced features:
42
+ ```bash
43
+ COINGECKO_API_KEY=your_coingecko_key # Higher rate limits
44
+ ETHERSCAN_API_KEY=your_etherscan_key # Blockchain data
45
+ ```
46
+
47
+ ## 🐳 Deploy to HuggingFace Spaces
48
+
49
+ 1. Fork this repo
50
+ 2. Create a new [HuggingFace Space](https://huggingface.co/spaces) with Docker SDK
51
+ 3. Set environment variables in Space settings
52
+ 4. Connect your repo and deploy
53
+
54
+ ## ✨ Features
55
+
56
+ - **AI Analysis**: Google Gemini-powered insights
57
+ - **Live Data**: CoinGecko, DeFiLlama, Etherscan APIs
58
+ - **Visualizations**: Interactive charts and graphs
59
+ - **Professional UI**: Clean, responsive interface
60
+ - **Multi-chain**: Ethereum, DeFi, Layer 2 support
61
+
62
+ ## 🎯 Usage Examples
63
+
64
+ - "What's Bitcoin's price and market sentiment?"
65
+ - "Show me top DeFi protocols by TVL"
66
+ - "Analyze Ethereum gas prices"
67
+ - "Compare BTC vs ETH performance"
68
+
69
+ ## οΏ½ Troubleshooting
70
+
71
+ **Can't access localhost:7860?**
72
+ - Check if app is running: `ps aux | grep "python app.py"`
73
+ - Try your local IP: `hostname -I` then http://YOUR_IP:7860
74
+ - In cloud environments, use provided forwarded URL
75
+
76
+ **API errors?**
77
+ - Verify GEMINI_API_KEY in .env file
78
+ - Check API key permissions
79
+
80
+ ## πŸ“ Project Structure
81
+
82
+ ```
83
+ web3-research-agent/
84
+ β”œβ”€β”€ app.py # Main FastAPI app
85
+ β”œβ”€β”€ requirements.txt # Dependencies
86
+ β”œβ”€β”€ Dockerfile # Container config
87
+ β”œβ”€β”€ test_suite.py # Tests
88
+ └── src/ # Source code
89
+ β”œβ”€β”€ research_agent.py
90
+ β”œβ”€β”€ visualizations.py
91
+ └── ...
92
+ ```
93
+
94
+ ---
95
+
96
+ **Built for the Web3 community** ❀️
97
+ pip install -r requirements.txt
98
+ ```
99
+
100
+ 3. **Set up environment variables**
101
+
102
+ Create a `.env` file in the project root:
103
+ ```bash
104
+ cp .env.example .env
105
+ ```
106
+
107
+ Edit `.env` with your API keys:
108
+ ```properties
109
+ # Required
110
+ GEMINI_API_KEY=your_gemini_api_key_here
111
+
112
+ # Optional (for enhanced functionality)
113
+ COINGECKO_API_KEY=your_coingecko_api_key_here
114
+ ETHERSCAN_API_KEY=your_etherscan_api_key_here
115
+ ```
116
+
117
+ 4. **Run the application**
118
+ ```bash
119
+ python app.py
120
+ ```
121
+
122
+ 5. **Access the interface**
123
+ - **Local Development**: http://localhost:7860
124
+ - **Production/Cloud**: Check your hosting platform's port forwarding
125
+ - **Docker**: http://localhost:7860
126
+
127
+ ## πŸš€ HuggingFace Spaces Deployment
128
+
129
+ This project is configured for HuggingFace Spaces deployment with Docker SDK.
130
+
131
+ ### Quick Deploy to HF Spaces
132
+
133
+ 1. **Fork/Clone this repository**
134
+ 2. **Create a new HuggingFace Space**:
135
+ - Go to [HuggingFace Spaces](https://huggingface.co/spaces)
136
+ - Click "Create new Space"
137
+ - Choose "Docker" as the SDK
138
+ - Upload your repository files
139
+
140
+ 3. **Configure Environment Variables**:
141
+ In your Space settings, add:
142
+ ```
143
+ GEMINI_API_KEY=your_gemini_api_key
144
+ COINGECKO_API_KEY=your_coingecko_api_key
145
+ ETHERSCAN_API_KEY=your_etherscan_api_key
146
+ ```
147
+
148
+ 4. **Deploy via Git**:
149
+ ```bash
150
+ git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
151
+ git push hf main
152
+ ```
153
+
154
+ ### HF Spaces Configuration
155
+
156
+ The project includes a proper `README.md` header for HF Spaces:
157
+ ```yaml
158
+ title: Web3 Research Co-Pilot
159
+ emoji: πŸš€
160
+ colorFrom: blue
161
+ colorTo: purple
162
+ sdk: docker
163
+ app_file: app.py
164
+ ```
165
+
166
+ ## 🐳 Docker Deployment
167
+
168
+ ### Local Docker
169
+
170
+ ```bash
171
+ # Build the image
172
+ docker build -t web3-research-copilot .
173
+
174
+ # Run the container
175
+ docker run -p 7860:7860 \
176
+ -e GEMINI_API_KEY=your_key_here \
177
+ -e COINGECKO_API_KEY=your_key_here \
178
+ -e ETHERSCAN_API_KEY=your_key_here \
179
+ web3-research-copilot
180
+ ```
181
+
182
+ ### HuggingFace Spaces
183
+
184
+ This project is optimized for HuggingFace Spaces deployment:
185
+
186
+ 1. **Create a new Space**:
187
+ - Go to [HuggingFace Spaces](https://huggingface.co/spaces)
188
+ - Click "Create new Space"
189
+ - Choose "Docker" as the SDK
190
+ - Set visibility to "Public" or "Private"
191
+
192
+ 2. **Configure Environment Variables**:
193
+ In your Space settings, add:
194
+ ```
195
+ GEMINI_API_KEY=your_gemini_api_key
196
+ COINGECKO_API_KEY=your_coingecko_api_key
197
+ ETHERSCAN_API_KEY=your_etherscan_api_key
198
+ ```
199
+
200
+ 3. **Deploy**:
201
+ ```bash
202
+ git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
203
+ git push hf main
204
+ ```
205
+
206
+ **Live Example**: https://archcoder-web3-copilot.hf.space
207
+
208
+ ## πŸ”„ Development Setup
209
+
210
+ ### Adding HuggingFace Remote
211
+
212
+ To deploy to your HuggingFace Space:
213
+
214
+ ```bash
215
+ # Add HuggingFace remote
216
+ git remote add hf https://huggingface.co/spaces/ArchCoder/web3-copilot
217
+
218
+ # Or for your own space
219
+ git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
220
+
221
+ # Deploy to HF Spaces
222
+ git push hf main
223
+ ```
224
+
225
+ ## πŸ“Š Testing
226
+
227
+ Run the comprehensive test suite:
228
+
229
+ ```bash
230
+ python test_suite.py
231
+ ```
232
+
233
+ Expected output:
234
+ ```
235
+ πŸš€ Web3 Research Co-Pilot - Test Suite
236
+ ==================================================
237
+ βœ… All imports successful
238
+ βœ… Configuration validated
239
+ βœ… Visualizations working
240
+ βœ… Tools initialized
241
+ βœ… Service functional
242
+ βœ… API endpoints healthy
243
+ βœ… Performance acceptable
244
+
245
+ Tests passed: 7/7
246
+ Success rate: 100.0%
247
+ πŸŽ‰ All tests passed!
248
+ ```
249
+
250
+ ## πŸ—οΈ Project Structure
251
+
252
+ ```
253
+ web3-research-agent/
254
+ β”œβ”€β”€ app.py # Main FastAPI application
255
+ β”œβ”€β”€ requirements.txt # Python dependencies
256
+ β”œβ”€β”€ pyproject.toml # Project configuration
257
+ β”œβ”€β”€ uv.lock # Dependency lock file
258
+ β”œβ”€β”€ test_suite.py # Comprehensive test suite
259
+ β”œβ”€β”€ .env.example # Environment template
260
+ β”œβ”€β”€ src/ # Source code
261
+ β”‚ β”œβ”€β”€ __init__.py
262
+ β”‚ β”œβ”€β”€ research_agent.py # Main agent logic
263
+ β”‚ β”œβ”€β”€ enhanced_agent.py # Enhanced agent features
264
+ β”‚ β”œβ”€β”€ config.py # Configuration management
265
+ β”‚ β”œβ”€β”€ cache_manager.py # Response caching
266
+ β”‚ β”œβ”€β”€ api_clients.py # External API clients
267
+ β”‚ β”œβ”€β”€ defillama_client.py # DeFiLlama integration
268
+ β”‚ β”œβ”€β”€ news_aggregator.py # News and social data
269
+ β”‚ β”œβ”€β”€ portfolio_analyzer.py # Portfolio analysis
270
+ β”‚ └── visualizations.py # Chart generation
271
+ └── README.md # This file
272
+ ```
273
+
274
+ ## πŸ”§ Configuration
275
+
276
+ ### Required Environment Variables
277
+
278
+ | Variable | Description | Required |
279
+ |----------|-------------|----------|
280
+ | `GEMINI_API_KEY` | Google Gemini API key for AI analysis | βœ… |
281
+
282
+ ### Optional Environment Variables
283
+
284
+ | Variable | Description | Default |
285
+ |----------|-------------|---------|
286
+ | `COINGECKO_API_KEY` | CoinGecko API key for enhanced rate limits | None |
287
+ | `ETHERSCAN_API_KEY` | Etherscan API key for blockchain data | None |
288
+ | `AIRAA_WEBHOOK_URL` | AIRAA integration webhook URL | None |
289
+ | `AIRAA_API_KEY` | AIRAA API authentication key | None |
290
+
291
+ ### Getting API Keys
292
+
293
+ 1. **Google Gemini API**:
294
+ - Go to [Google AI Studio](https://aistudio.google.com/)
295
+ - Create a new API key
296
+ - Copy the key to your `.env` file
297
+
298
+ 2. **CoinGecko API** (optional):
299
+ - Sign up at [CoinGecko](https://www.coingecko.com/api)
300
+ - Get your free API key
301
+ - Provides higher rate limits
302
+
303
+ 3. **Etherscan API** (optional):
304
+ - Register at [Etherscan](https://etherscan.io/apis)
305
+ - Create a free API key
306
+ - Enables blockchain data queries
307
+
308
+ ## 🎯 Usage Examples
309
+
310
+ ### Market Analysis
311
+ ```
312
+ "Analyze Bitcoin price trends and institutional adoption patterns"
313
+ ```
314
+
315
+ ### DeFi Research
316
+ ```
317
+ "Compare top DeFi protocols by TVL, yield, and risk metrics"
318
+ ```
319
+
320
+ ### Layer 2 Analysis
321
+ ```
322
+ "Evaluate Ethereum Layer 2 scaling solutions and adoption metrics"
323
+ ```
324
+
325
+ ### Yield Optimization
326
+ ```
327
+ "Identify optimal yield farming strategies across multiple chains"
328
+ ```
329
+
330
+ ## 🌐 API Endpoints
331
+
332
+ | Endpoint | Method | Description |
333
+ |----------|--------|-------------|
334
+ | `/` | GET | Web interface |
335
+ | `/status` | GET | System status and configuration |
336
+ | `/query` | POST | Process research queries |
337
+ | `/health` | GET | Health check |
338
+
339
+ ### Query API Example
340
+
341
+ ```bash
342
+ curl -X POST "http://localhost:7860/query" \
343
+ -H "Content-Type: application/json" \
344
+ -d '{"query": "What is the current Bitcoin price?"}'
345
+ ```
346
+
347
+ ## πŸ› Troubleshooting
348
+
349
+ ### Port Access Issues
350
+
351
+ **Problem**: Can't access the app on http://localhost:7860 or http://0.0.0.0:7860
352
+
353
+ **Solutions**:
354
+
355
+ 1. **Check if the app is running**:
356
+ ```bash
357
+ ps aux | grep "python app.py"
358
+ ```
359
+
360
+ 2. **Verify port binding**:
361
+ ```bash
362
+ netstat -tlnp | grep :7860
363
+ ```
364
+
365
+ 3. **For Development Environments (VS Code, etc.)**:
366
+ - Look for port forwarding notifications
367
+ - Check your IDE's "Ports" or "Forwarded Ports" tab
368
+ - Use the forwarded URL provided by your development environment
369
+
370
+ 4. **For Cloud/Remote Environments**:
371
+ - The app binds to `0.0.0.0:7860` for external access
372
+ - Use your platform's provided URL (not localhost)
373
+ - Check firewall rules if on a VPS/server
374
+
375
+ 5. **Local Network Access**:
376
+ ```bash
377
+ # Find your local IP
378
+ hostname -I
379
+ # Access via: http://YOUR_IP:7860
380
+ ```
381
+
382
+ ### Common Issues
383
+
384
+ 1. **"GEMINI_API_KEY not configured"**
385
+ - Ensure you've set the API key in your `.env` file
386
+ - Verify the key is valid and has proper permissions
387
+
388
+ 2. **"Connection refused" on port 7860**
389
+ - Check if another process is using port 7860: `lsof -i :7860`
390
+ - Ensure the app started successfully: `python app.py`
391
+
392
+ 3. **Import errors**
393
+ - Ensure all dependencies are installed: `pip install -r requirements.txt`
394
+ - Check Python version compatibility (3.11+)
395
+
396
+ 4. **Slow visualization loading**
397
+ - Check your internet connection
398
+ - API rate limits may be affecting data retrieval
399
+
400
+ ### Getting Help
401
+
402
+ - Check the test suite: `python test_suite.py`
403
+ - Review logs in the terminal output
404
+ - Verify API keys are configured correctly
405
+ - Open an issue on GitHub with error details
406
+
407
+ ## 🀝 Contributing
408
+
409
+ 1. Fork the repository
410
+ 2. Create a feature branch
411
+ 3. Make your changes
412
+ 4. Add tests for new functionality
413
+ 5. Run the test suite
414
+ 6. Submit a pull request
415
+
416
+ ## πŸ“„ License
417
+
418
+ This project is licensed under the MIT License - see the LICENSE file for details.
419
+
420
+ ## πŸ™ Acknowledgments
421
+
422
+ - **Google Gemini** for AI capabilities
423
+ - **CoinGecko** for comprehensive market data
424
+ - **DeFiLlama** for DeFi protocol analytics
425
+ - **Etherscan** for blockchain data
426
+ - **FastAPI** for the web framework
427
+ - **Plotly** for interactive visualizations
428
+
429
+ ---
430
+
431
+ **Built with ❀️ for the Web3 community**