Berack/upo-app-agents
0
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

Demos (#42)

Browse Source 
* Rimossi old docs & demos
* Aggiornata la documentazione dell'architettura dell'app
* Aggiunti nuovi script demo per i provider di mercato
* Fix problems with socials
* Fix Dockerfile per dipendenze di X
This commit was merged in pull request #42.
This commit is contained in:
Giacomo Bertolazzi
2025-10-27 12:42:58 +01:00
committed by GitHub
parent 551b6a049f
commit 08774bee1b
11 changed files with 194 additions and 1005 deletions
Download Patch File Download Diff File Expand all files Collapse all files

375
docs/App_Architecture_Diagrams.md
View File

@@ -1,255 +1,160 @@
# 📊 Architettura e Flussi dell'App upo-appAI
# 📊 Architettura upo-appAI
## 🏗️ Diagramma Architettura Generale
## 🏗️ Architettura Generale
```
┌─────────────────────────────────────────────────────────────────┐
│ 🌐 GRADIO UI │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ User Input │ │ Provider │ │ Style │ │
│ │ (Query) │ │ (Model) │ │ (Conservative/ │ │
│ │ │ │ │ │ Aggressive) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 🔧 TOOL AGENT │
│ (Central Orchestrator) │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 1. Collect Data │ │ 2. Analyze │ │ 3. Predict & │ │
│ │ │ │ Sentiment │ │ Recommend │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 📊 AGENT ECOSYSTEM │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐│
│ │ MARKET │ │ NEWS │ │ SOCIAL │ │ PREDICTOR ││
│ │ AGENT │ │ AGENT │ │ AGENT │ │ AGENT ││
│ │ │ │ │ │ │ │ ││
│ │ 📈 Coinbase │ │ 📰 News API │ │ 🐦 Social │ │ 🤖 LLM ││
│ │ 📊 CryptoCmp│ │ │ │ Media │ │ Analysis ││
│ │ 🟡 Binance │ │ │ │ │ │ ││
│ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘│
└─────────────────────────────────────────────────────────────────┘
INTERFACCE UTENTE
├── 💬 Gradio Web (Chat + Dropdown modelli/strategie)
└── 📱 Telegram Bot (Mini App)
│
▼
CHAT MANAGER
├── Storico messaggi
├── Gestione PipelineInputs
└── Salva/Carica chat
│
▼
AGNO WORKFLOW PIPELINE (4 Steps)
├── 1. Query Check → Verifica crypto
├── 2. Condition → Valida procedere
├── 3. Info Recovery → Team raccolta dati
└── 4. Report Generation → Report finale
│
▼
AGNO AGENT ECOSYSTEM
├── 👔 TEAM LEADER (coordina Market, News, Social)
│ Tools: ReasoningTools, PlanMemoryTool, CryptoSymbolsTools
├── 📈 MARKET AGENT → MarketAPIsTool
├── 📰 NEWS AGENT → NewsAPIsTool
├── 🐦 SOCIAL AGENT → SocialAPIsTool
├── 🔍 QUERY CHECK AGENT → QueryOutputs (is_crypto: bool)
└── 📋 REPORT GENERATOR AGENT → Strategia applicata
```
## 🔄 Flusso di Esecuzione Dettagliato
## 🔄 Flusso Esecuzione
```
👤 USER REQUEST
│
│ "Analizza Bitcoin con strategia aggressiva"
▼
┌─────────────────────────────────────────────────────────────┐
│ 🔧 TOOL AGENT │
│ │
│ def interact(query, provider, style): │
│ │ │
│ ├── 📊 market_data = market_agent.analyze(query) │
│ ├── 📰 news_sentiment = news_agent.analyze(query) │
│ ├── 🐦 social_sentiment = social_agent.analyze(query) │
│ │ │
│ └── 🤖 prediction = predictor_agent.predict(...) │
└─────────────────────────────────────────────────────────────┘
│
▼
📊 MARKET AGENT - Parallel Data Collection
┌─────────────────────────────────────────────────────────────┐
│ │
│ 🔍 Auto-detect Available Providers: │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Coinbase │ │ CryptoComp │ │ Binance │ │
│ │ REST │ │ API │ │ Mock │ │
│ │ │ │ │ │ │ │
│ │ ✅ Active │ │ ✅ Active │ │ ✅ Active │ │
│ │ $63,500 BTC │ │ $63,450 BTC │ │ $63,600 BTC │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ 📈 Aggregated Result: │
│ { │
│ "aggregated_data": { │
│ "BTC_USD": { │
│ "price": 63516.67, │
│ "confidence": 0.94, │
│ "sources_count": 3 │
│ } │
│ }, │
│ "individual_sources": {...}, │
│ "market_signals": {...} │
│ } │
└─────────────────────────────────────────────────────────────┘
│
▼
📰 NEWS AGENT + 🐦 SOCIAL AGENT
┌─────────────────────────────────────────────────────────────┐
│ │
│ 📰 News Sentiment: "Positive momentum, institutional │
│ adoption increasing..." │
│ │
│ 🐦 Social Sentiment: "Bullish sentiment on Reddit, │
│ Twitter mentions up 15%..." │
└─────────────────────────────────────────────────────────────┘
│
▼
🤖 PREDICTOR AGENT
┌─────────────────────────────────────────────────────────────┐
│ │
│ Input: │
│ ├── 📊 Market Data (aggregated + confidence) │
│ ├── 📰🐦 Combined Sentiment │
│ ├── 🎯 Style: "aggressive" │
│ └── 🤖 Provider: "openai/anthropic/google..." │
│ │
│ 🧠 LLM Processing: │
│ "Based on high confidence market data (0.94) showing │
│ $63,516 BTC with positive sentiment across news and │
│ social channels, aggressive strategy recommendation..." │
└─────────────────────────────────────────────────────────────┘
│
▼
📋 FINAL OUTPUT
┌─────────────────────────────────────────────────────────────┐
│ 📊 Market Data Summary │
│ 📰🐦 Sentiment Analysis │
│ 📈 Final Recommendation: │
│ "Strong BUY signal with 85% confidence..." │
└─────────────────────────────────────────────────────────────┘
**Input:** "Analizza Bitcoin con strategia aggressiva"
1. CHAT MANAGER riceve e prepara PipelineInputs
2. WORKFLOW PIPELINE esegue 4 step:
- Query Check: valida `is_crypto: true`
- Condition: se false, termina
- Info Recovery: Team raccoglie dati
- Report Generation: genera report
3. OUTPUT: Report con analisi + raccomandazioni
## 🏛️ Architettura API
**Tools (Agno Toolkit):**
- MarketAPIsTool: Binance, YFinance, CoinBase, CryptoCompare
- NewsAPIsTool: NewsAPI, GoogleNews, DuckDuckGo, CryptoPanic
- SocialAPIsTool: Reddit, X, 4chan
- CryptoSymbolsTools: `resources/cryptos.csv`
**WrapperHandler:** Failover automatico (3 tentativi/wrapper, 2s delay)
## 📊 Data Aggregation
**ProductInfo:**
- Volume: media tra sources
- Price: weighted average (price × volume)
- Confidence: spread + numero sources
**Historical Price:**
- Align per timestamp
- Media: high, low, open, close, volume
## 🎯 Configuration
**configs.yaml:**
```yaml
port: 8000
models: [Ollama, OpenAI, Anthropic, Google]
strategies: [Conservative, Aggressive]
agents: {team_model, team_leader_model, ...}
api: {retry_attempts: 3, retry_delay_seconds: 2}
```
## 🏛️ Architettura dei Provider (Market Agent)
**.env (API Keys):**
- Market: CDP_API_KEY, CRYPTOCOMPARE_API_KEY, ...
- News: NEWS_API_KEY, CRYPTOPANIC_API_KEY, ...
- Social: REDDIT_CLIENT_ID, X_API_KEY, ...
- LLM: OPENAI_API_KEY, ANTHROPIC_API_KEY, ...
- Bot: TELEGRAM_BOT_TOKEN
## 🗂️ Struttura Progetto
```
┌─────────────────────────────────────────────────────────────────┐
│ 📊 MARKET AGENT │
│ │
│ 🔍 Provider Detection Logic: │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ def _setup_providers(): ││
│ │ ├── 🔑 Check CDP_API_KEY_NAME + CDP_API_PRIVATE_KEY ││
│ │ │ └── ✅ Setup Coinbase Advanced Trade ││
│ │ ├── 🔑 Check CRYPTOCOMPARE_API_KEY ││
│ │ │ └── ✅ Setup CryptoCompare ││
│ │ └── 🔑 Check BINANCE_API_KEY (future) ││
│ │ └── ✅ Setup Binance API ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ 📡 Data Flow: │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Provider 1 │───▶│ │◀───│ Provider 2 │ │
│ │ Coinbase │ │ AGGREGATOR │ │ CryptoComp │ │
│ │ │ │ │ │ │ │
│ │ Real-time │ │ ┌─────────┐ │ │ Real-time │ │
│ │ Market Data │ │ │Confidence│ │ │ Market Data │ │
│ └─────────────┘ │ │Scoring │ │ └─────────────┘ │
│ │ │ │ │ │
│ ┌─────────────┐ │ │ Spread │ │ ┌─────────────┐ │
│ │ Provider 3 │───▶│ │Analysis │ │◀───│ Provider N │ │
│ │ Binance │ │ │ │ │ │ Future │ │
│ │ │ │ └─────────┘ │ │ │ │
│ │ Mock Data │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
src/app/
├── __main__.py
├── configs.py
├── agents/
│ ├── core.py
│ ├── pipeline.py
│ ├── plan_memory_tool.py
│ └── prompts/
├── api/
│ ├── wrapper_handler.py
│ ├── core/ (markets, news, social)
│ ├── markets/ (Binance, CoinBase, CryptoCompare, YFinance)
│ ├── news/ (NewsAPI, GoogleNews, DuckDuckGo, CryptoPanic)
│ ├── social/ (Reddit, X, 4chan)
│ └── tools/ (Agno Toolkits)
└── interface/ (chat.py, telegram_app.py)
tests/
demos/
resources/cryptos.csv
docs/
configs.yaml
.env
```
## 🔧 Signers Architecture
## 🔑 Componenti Chiave
```
┌─────────────────────────────────────────────────────────────────┐
│ 🔐 SIGNERS ECOSYSTEM │
│ │
│ 📁 src/app/signers/market_signers/ │
│ │ │
│ ├── 🏦 coinbase_rest_signer.py │
│ │ ├── 🔑 Uses: CDP_API_KEY_NAME + CDP_API_PRIVATE_KEY │
│ │ ├── 📡 RESTClient from coinbase.rest │
│ │ ├── 📊 get_asset_info() → Real Coinbase data │
│ │ └── 📈 get_multiple_assets() → Bulk data │
│ │ │
│ ├── 📊 cryptocompare_signer.py │
│ │ ├── 🔑 Uses: CRYPTOCOMPARE_API_KEY │
│ │ ├── 📡 Direct HTTP requests │
│ │ ├── 💰 get_crypto_prices() → Multi-currency │
│ │ └── 🏆 get_top_cryptocurrencies() → Market cap │
│ │ │
│ └── 🟡 binance_signer.py │
│ ├── 🔑 Uses: BINANCE_API_KEY (future) │
│ ├── 📡 Mock implementation │
│ ├── 🎭 Simulated market data │
│ └── 📈 Compatible interface │
└─────────────────────────────────────────────────────────────────┘
1. **Agno Framework**: Agent, Team, Workflow, Toolkit, RunEvent
2. **WrapperHandler**: Failover, Retry logic, Type safety
3. **Data Aggregation**: Multiple sources, Confidence score
4. **Multi-Interface**: Gradio + Telegram
5. **Configuration**: configs.yaml + .env
## 🚀 Deployment
**Docker:**
```bash
docker-compose up --build -d
```
## 🚀 Future Enhancement: Async Flow
```
📱 USER REQUEST
│
▼
🔧 TOOL AGENT (async)
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
📊 Market 📰 News 🐦 Social
Agent (async) Agent (async) Agent (async)
│ │ │
┌────┼────┐ │ │
▼ ▼ ▼ │ │
Coinbase │ Binance │ │
CC │ │ │
▼▼▼ ▼ ▼
🔄 Parallel 📰 Sentiment 🐦 Sentiment
Aggregation Analysis Analysis
│ │ │
└────────────────┼────────────────┘
▼
🤖 PREDICTOR AGENT
(LLM Analysis)
│
▼
📋 FINAL RESULT
(JSON + Confidence)
**Local (UV):**
```bash
uv venv
uv pip install -e .
uv run src/app
```
## 📊 Data Flow Example
## 🎯 Workflow Asincrono
```
Input: "Analyze Bitcoin aggressive strategy"
│
├── 📊 Market Agent Output:
│ {
│ "aggregated_data": {
│ "BTC_USD": {"price": 63516.67, "confidence": 0.94}
│ },
│ "individual_sources": {
│ "coinbase": {"price": 63500, "volume": "1.2M"},
│ "cryptocompare": {"price": 63450, "volume": "N/A"},
│ "binance": {"price": 63600, "volume": "2.1M"}
│ },
│ "market_signals": {
│ "spread_analysis": "Low spread (0.24%) - healthy liquidity",
│ "price_divergence": "Max deviation: 0.24% - Normal range"
│ }
│ }
│
├── 📰 News Sentiment: "Positive institutional adoption news..."
├── 🐦 Social Sentiment: "Bullish Reddit sentiment, +15% mentions"
│
└── 🤖 Predictor Output:
"📈 Strong BUY recommendation based on:
- High confidence market data (94%)
- Positive news sentiment
- Bullish social indicators
- Low spread indicates healthy liquidity
Aggressive Strategy: Consider 15-20% portfolio allocation"
```python
workflow = Workflow(steps=[
query_check, condition,
info_recovery, report_generation
])
iterator = await workflow.arun(query, stream=True)
async for event in iterator:
if event.event == PipelineEvent.TOOL_USED:
log(f"Tool: {event.tool.tool_name}")
```
---
*Diagrammi creati: 2025-09-23*
*Sistema: upo-appAI Market Analysis Platform*
**Vantaggi:** Asincrono, Streaming, Condizionale, Retry
## 📈 Future Enhancements
- Parallel Tool Execution
- Caching (Redis)
- Database (PostgreSQL)
- Real-time WebSocket
- ML Models
- User Profiles
- Backtesting

203
docs/Async_Implementation_Detail.md
View File

@@ -1,203 +0,0 @@
# 🚀 Diagramma Dettaglio: Implementazione Asincrona
## ⚡ Async Market Data Collection (Fase 3)
```
┌─────────────────────────────────────────────────────────────────┐
│ 🔧 TOOL AGENT │
│ │
│ async def interact(query, provider, style): │
│ │ │
│ ├── 📊 market_data = await market_agent.analyze_async() │
│ ├── 📰 news_data = await news_agent.analyze_async() │
│ ├── 🐦 social_data = await social_agent.analyze_async() │
│ │ │
│ └── 🤖 prediction = await predictor.predict_async(...) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 📊 MARKET AGENT - ASYNC IMPLEMENTATION │
│ │
│ async def analyze_async(self, query): │
│ symbols = extract_symbols(query) # ["BTC", "ETH"] │
│ │ │
│ └── 🔄 tasks = [ │
│ │ self._query_coinbase_async(symbols), │
│ │ self._query_cryptocompare_async(symbols), │
│ │ self._query_binance_async(symbols) │
│ │ ] │
│ │ │
│ └── 📊 results = await asyncio.gather(*tasks) │
│ │ │
│ ▼ │
│ 🧮 aggregate_results(results) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ ⏱️ TIMING DIAGRAM │
│ │
│ Time: 0ms 500ms 1000ms 1500ms 2000ms │
│ │ │ │ │ │ │
│ 📡 Start all requests │
│ ├─────────────────────────────────────────┐ │
│ │ 🏦 Coinbase Request │ │
│ │ ✅ Response │ (1.2s) │
│ ├─────────────────────────────┐ │ │
│ │ 📊 CryptoCompare Request │ │ │
│ │ ✅ Response (0.8s) │ │
│ ├─────────────┐ │ │ │
│ │ 🟡 Binance │ │ │ │
│ │ ✅ Response (0.3s - mock) │ │ │
│ │ │ │ │ │
│ └─────────────┼───────────────┼───────────┘ │
│ │ │ │
│ Wait for all... │ │
│ │ │
│ 🧮 Aggregate (1.2s total) │
│ │
│ 📈 Performance Gain: │
│ Sequential: 1.2s + 0.8s + 0.3s = 2.3s │
│ Parallel: max(1.2s, 0.8s, 0.3s) = 1.2s │
│ Improvement: ~48% faster! 🚀 │
└─────────────────────────────────────────────────────────────────┘
```
## 🧮 Aggregation Algorithm Detail
```
┌─────────────────────────────────────────────────────────────────┐
│ 🔬 DATA AGGREGATION LOGIC │
│ │
│ def aggregate_market_data(results): │
│ │ │
│ ├── 📊 Input Data: │
│ │ ┌─────────────────────────────────────────────────┐ │
│ │ │ coinbase: {"BTC": 63500, "ETH": 4150} │ │
│ │ │ cryptocomp: {"BTC": 63450, "ETH": 4160} │ │
│ │ │ binance: {"BTC": 63600, "ETH": 4140} │ │
│ │ └─────────────────────────────────────────────────┘ │
│ │ │
│ ├── 🧮 Price Calculation: │
│ │ ┌─────────────────────────────────────────────────┐ │
│ │ │ BTC_prices = [63500, 63450, 63600] │ │
│ │ │ BTC_avg = 63516.67 │ │
│ │ │ BTC_std = 75.83 │ │
│ │ │ BTC_spread = (max-min)/avg = 0.24% │ │
│ │ └─────────────────────────────────────────────────┘ │
│ │ │
│ ├── 🎯 Confidence Scoring: │
│ │ ┌─────────────────────────────────────────────────┐ │
│ │ │ confidence = 1 - (std_dev / mean) │ │
│ │ │ if spread < 0.5%: confidence += 0.1 │ │
│ │ │ if sources >= 3: confidence += 0.05 │ │
│ │ │ BTC_confidence = 0.94 (excellent!) │ │
│ │ └─────────────────────────────────────────────────┘ │
│ │ │
│ └── 📈 Market Signals: │
│ ┌─────────────────────────────────────────────────┐ │
│ │ spread_analysis: │ │
│ │ "Low spread (0.24%) indicates healthy liq." │ │
│ │ volume_trend: │ │
│ │ "Combined volume: 4.1M USD" │ │
│ │ price_divergence: │ │
│ │ "Max deviation: 0.24% - Normal range" │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 🔄 Error Handling & Resilience
```
┌─────────────────────────────────────────────────────────────────┐
│ 🛡️ RESILIENCE STRATEGY │
│ │
│ Scenario 1: One Provider Fails │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🏦 Coinbase: ✅ Success (BTC: $63500) │ │
│ │ 📊 CryptoComp: ❌ Timeout/Error │ │
│ │ 🟡 Binance: ✅ Success (BTC: $63600) │ │
│ │ │ │
│ │ Result: Continue with 2 sources │ │
│ │ Confidence: 0.89 (slightly reduced) │ │
│ │ Note: "CryptoCompare unavailable" │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Scenario 2: Multiple Providers Fail │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🏦 Coinbase: ❌ API Limit │ │
│ │ 📊 CryptoComp: ✅ Success (BTC: $63450) │ │
│ │ 🟡 Binance: ❌ Network Error │ │
│ │ │ │
│ │ Result: Single source data │ │
│ │ Confidence: 0.60 (low - warn user) │ │
│ │ Note: "Limited data - consider waiting" │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Scenario 3: All Providers Fail │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🏦 Coinbase: ❌ Maintenance │ │
│ │ 📊 CryptoComp: ❌ API Down │ │
│ │ 🟡 Binance: ❌ Rate Limit │ │
│ │ │ │
│ │ Result: Graceful degradation │ │
│ │ Message: "Market data temporarily unavailable" │ │
│ │ Fallback: Cached data (if available) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 📊 JSON Output Schema
```json
{
"aggregated_data": {
"BTC_USD": {
"price": 63516.67,
"confidence": 0.94,
"sources_count": 3,
"last_updated": "2025-09-23T17:30:00Z"
},
"ETH_USD": {
"price": 4150.33,
"confidence": 0.91,
"sources_count": 3,
"last_updated": "2025-09-23T17:30:00Z"
}
},
"individual_sources": {
"coinbase": {
"BTC": {"price": 63500, "volume": "1.2M", "status": "online"},
"ETH": {"price": 4150, "volume": "25.6M", "status": "online"}
},
"cryptocompare": {
"BTC": {"price": 63450, "volume": "N/A", "status": "active"},
"ETH": {"price": 4160, "volume": "N/A", "status": "active"}
},
"binance": {
"BTC": {"price": 63600, "volume": "2.1M", "status": "mock"},
"ETH": {"price": 4140, "volume": "18.3M", "status": "mock"}
}
},
"market_signals": {
"spread_analysis": "Low spread (0.24%) indicates healthy liquidity",
"volume_trend": "Combined BTC volume: 3.3M USD (+12% from avg)",
"price_divergence": "Max deviation: 0.24% - Normal range",
"data_quality": "High - 3 sources, low variance",
"recommendation": "Data suitable for trading decisions"
},
"metadata": {
"query_time_ms": 1247,
"sources_queried": ["coinbase", "cryptocompare", "binance"],
"sources_successful": ["coinbase", "cryptocompare", "binance"],
"sources_failed": [],
"aggregation_method": "weighted_average",
"confidence_threshold": 0.75
}
}
```
---
*Diagramma dettaglio asincrono: 2025-09-23*
*Focus: Performance, Resilienza, Qualità Dati*

96
docs/Market_Data_Implementation_Plan.md
View File

@@ -1,96 +0,0 @@
# 🚀 Piano di Implementazione - Market Data Enhancement
## 📋 Roadmap Implementazioni
### **Fase 1: Binance Mock Provider**
**Obiettivo**: Aggiungere terzo provider per test aggregazione
- ✅ Creare `binance_signer.py` con mock data
- ✅ Integrare nel MarketAgent
- ✅ Testare detection automatica provider
- **Deliverable**: 3 provider funzionanti (Coinbase, CryptoCompare, Binance)
### **Fase 2: Interrogazione Condizionale**
**Obiettivo**: Auto-detection credenziali e interrogazione intelligente
- ✅ Migliorare detection chiavi API nel MarketAgent
- ✅ Skip provider se credenziali mancanti (no errori)
- ✅ Logging informativo per provider disponibili/non disponibili
- ✅ Gestione graceful degradation
- **Deliverable**: Sistema resiliente che funziona con qualsiasi combinazione di provider
### **Fase 3: Interrogazione Asincrona + Aggregazione JSON**
**Obiettivo**: Performance boost e formato dati professionale
#### **3A. Implementazione Asincrona**
- ✅ Refactor MarketAgent per supporto `async/await`
- ✅ Chiamate parallele a tutti i provider disponibili
- ✅ Timeout management per provider lenti
- ✅ Error handling per provider che falliscono
#### **3B. Aggregazione Dati Intelligente**
- ✅ Calcolo `confidence` basato su concordanza prezzi
- ✅ Analisi `spread` tra provider
- ✅ Detection `price_divergence` per anomalie
- ✅ Volume trend analysis
- ✅ Formato JSON strutturato:
```json
{
"aggregated_data": {
"BTC_USD": {
"price": 43250.12,
"confidence": 0.95,
"sources_count": 4
}
},
"individual_sources": {
"coinbase": {"price": 43245.67, "volume": "1.2M"},
"binance": {"price": 43255.89, "volume": "2.1M"},
"cryptocompare": {"price": 43248.34, "volume": "0.8M"}
},
"market_signals": {
"spread_analysis": "Low spread (0.02%) indicates healthy liquidity",
"volume_trend": "Volume up 15% from 24h average",
"price_divergence": "Max deviation: 0.05% - Normal range"
}
}
```
**Deliverable**: Sistema asincrono con analisi avanzata dei dati di mercato
## 🎯 Benefici Attesi
### **Performance**
- ⚡ Tempo risposta: da ~4s sequenziali a ~1s paralleli
- 🔄 Resilienza: sistema funziona anche se 1-2 provider falliscono
- 📊 Qualità dati: validazione incrociata tra provider
### **Professionalità**
- 📈 Confidence scoring per decisioni informate
- 🔍 Market signals per trading insights
- 📋 Formato standardizzato per integrazioni future
### **Scalabilità**
- ➕ Facile aggiunta nuovi provider
- 🔧 Configurazione flessibile via environment
- 📝 Logging completo per debugging
## 🧪 Test Strategy
1. **Unit Tests**: Ogni provider singolarmente
2. **Integration Tests**: Aggregazione multi-provider
3. **Performance Tests**: Confronto sync vs async
4. **Resilience Tests**: Fallimento provider singoli
5. **E2E Tests**: Full workflow con UI Gradio
## 📅 Timeline Stimata
- **Fase 1**: ~1h (setup Binance mock)
- **Fase 2**: ~1h (detection condizionale)
- **Fase 3**: ~2-3h (async + aggregazione)
- **Testing**: ~1h (validation completa)
**Total**: ~5-6h di lavoro strutturato
---
*Documento creato: 2025-09-23*
*Versione: 1.0*

73
docs/Piano di Sviluppo.md
View File

@@ -1,73 +0,0 @@
# Guida alla Realizzazione del Progetto
Questa guida è una lista di controllo per l'implementazione del tuo progetto. È divisa in fasi logiche, ognuna con i compiti specifici da svolgere.
## Fase 1: Preparazione e Architettura di Base
### Impostazione dell'ambiente
* Scegliere il linguaggio di programmazione (es. **Python**).
* Utilizzare la libreria `agno` per la creazione di agenti e **LangChain/LlamaIndex** per la gestione dell'LLM e dell'orchestrazione.
### Definizione dell'Architettura degli agenti
* Definire la classe base per gli agenti, con metodi comuni come `execute()` e `reason()`.
* Delineare i ruoli e le interfacce di tutti gli agenti (`RicercatoreDati`, `AnalistaSentiment`, `MotorePredittivo`, `Orchestratore`), stabilendo come comunicheranno tra loro.
---
## Fase 2: Implementazione degli Agenti Core
### Agente `RicercatoreDati`
* Implementare la logica per connettersi a un'API di exchange (es. **Binance, Coindesk, CoinMarketCap**).
* Testare la capacità di recuperare dati in tempo reale per diverse criptovalute (prezzo, volume, capitalizzazione) e **assicurarsi che la gestione degli errori sia robusta**.
### Agente `AnalistaSentiment`
* **Agente `Social`:**
* Scegliere un metodo per lo scraping di forum e social media (es. **Reddit API, librerie per Twitter/X, BeautifulSoup per web scraping**).
* Implementare un modulo di analisi del testo per classificare il sentiment (positivo, negativo, neutro) utilizzando **modelli pre-addestrati (es. VADER) o fine-tuning di modelli più avanzati**.
* **Agente `News`:**
* Ottenere una chiave API per un servizio di notizie (es. **NewsAPI**).
* Implementare la logica per cercare articoli pertinenti a una criptovaluta specifica o al mercato in generale, e **filtrare le notizie in base a parole chiave rilevanti**.
### Agente `MotorePredittivo`
* Definire la logica per integrare i dati numerici del `RicercatoreDati` con il sentiment dell'`AnalistaSentiment`.
* Creare un **prompt avanzato** per l'LLM che lo guidi a generare previsioni e strategie. Dovrai usare tecniche come la **chain-of-thought** per rendere il ragionamento trasparente. Assicurarsi che il prompt includa vincoli specifici per lo stile di investimento (aggressivo/conservativo).
---
## Fase 3: Costruzione dell'Orchestratore e Test di Integrazione
### Implementazione dell'Agente Orchestratore
* **Gestione dell'Input Utente:** Creare un metodo che riceve la richiesta dell'utente (es. `analizza_cripto('Bitcoin', 'aggressivo')`). Analizzare il tipo di richiesta e le preferenze utente.
* **Recupero della Memoria Utente:** Integrare la logica per recuperare la cronologia delle richieste passate dal database e preparare i dati come contesto aggiuntivo per l'LLM.
* **Orchestrazione e Flusso di Lavoro:** Chiamare gli agenti (`RicercatoreDati`, `AnalistaSentiment`) e passare i risultati combinati all'**Agente `MotorePredittivo`** per generare previsioni e strategie.
* **Valutazione e Selezione Strategica:** Ricevere le previsioni dal `MotorePredittivo` e applicare le regole di valutazione basate sulle preferenze dell'utente per selezionare le strategie più appropriate.
* **Presentazione e Persistenza:** Costruire il report finale e salvare la sessione completa nel database.
---
## Fase 4: Gestione della Persistenza e dell'Interfaccia Utente
* **Database per la persistenza:** Scegli un database (es. **Firestore, MongoDB, PostgreSQL**) per salvare la cronologia delle richieste degli utenti. Implementa la logica per salvare e recuperare le sessioni di consulenza passate, associandole a un ID utente, e **struttura i dati per una ricerca efficiente**.
* **Interfaccia utente (UI):** Costruisci un'interfaccia utente semplice e intuitiva che permetta di inserire i parametri di richiesta. Aggiungi una sezione per visualizzare i risultati, inclusi i grafici e le note che spiegano il ragionamento dell'agente.
---
## Fase 5: Test del Sistema
* **Test unitari:** Esegui test su ogni agente singolarmente per assicurarti che funzioni correttamente (es. l'agente `RicercatoreDati` recupera i dati, l'agente `AnalistaSentiment` classifica correttamente un testo). **Crea dei mock per le API esterne per testare la logica interna senza dipendenze esterne**.
* **Test di integrazione:** Esegui scenari di test completi per l'intero sistema. Verifica che l'orchestrazione tra gli agenti avvenga senza intoppi e che i dati vengano passati correttamente tra di essi.
---
## Fase 6: Valutazione dei Risultati
* **Valutazione della qualità:** Verifica la qualità delle raccomandazioni generate. L'output è logico e ben argomentato?
* **Trasparenza del ragionamento:** Controlla che le note (`Ragionamenti`) siano chiare e forniscano un'effettiva trasparenza del processo decisionale dell'agente.
* **Confronto e validazione:** Confronta le raccomandazioni con dati storici e scenari ipotetici per valutarne la plausibilità.