Demos & Docs #42

Merged
Berack96 merged 8 commits from demos into main 2025-10-27 12:42:59 +01:00
Showing only changes of commit b33389c4b6 - Show all commits

View File

@@ -4,37 +4,82 @@
``` ```
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
🌐 GRADIO UI 🌐 INTERFACCE UTENTE
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ ┌───────────────────────────────────────────────────────────┐ │
│ │ User Input Provider │ │ Style │ │ 💬 Gradio Web Interface │ │
│ │ (Query) │ │ (Model) │ │ (Conservative/ │ │ ┌──────────┐ ┌──────────┐ ┌───────────────────────┐ │ │
│ │ │ │ │ │ Aggressive) │ │ │ Chat │ │ Model │ │ Strategy (Strategy) │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ History │ │Dropdown │ │ - Conservative │ │
│ │ │ │ │ │ │ - Aggressive │ │ │
│ │ └──────────┘ └──────────┘ └───────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 📱 Telegram Bot Interface │ │
│ │ (Mini App con integrazione Gradio) │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘ └─────────────────────────┬───────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
🔧 TOOL AGENT 🎯 CHAT MANAGER
(Central Orchestrator) (Gestione Conversazioni)
┌─────────────────────────────────────────────────────────┐
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ - Mantiene storico messaggi (history) │
│ │ 1. Collect Data │ │ 2. Analyze │ │ 3. Predict & │ │ │ │ - Gestisce input Pipeline (PipelineInputs)
│ │ │ │ Sentiment Recommend │ │ - Salva/Carica chat (JSON)
└─────────────────┘ └─────────────────┘ └─────────────────┘ │ - Interfaccia Gradio (gradio_build_interface) │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘ └─────────────────────────┬───────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
📊 AGENT ECOSYSTEM 🔄 AGNO WORKFLOW PIPELINE
│ (Orchestrazione Asincrona) │
│ │ │ │
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ Step 1: 🔍 Query Check → Verifica query crypto
│ MARKET │ NEWS SOCIAL │ │ PREDICTOR │ Step 2: 🤔 Condition Check → Valida se procedere
│ AGENT AGENT AGENT │ │ AGENT │ Step 3: 📊 Info Recovery → Team di raccolta dati
│ │ │ │ │ │ │ │ Step 4: 📝 Report Generation → Genera report finale
│ 📈 Coinbase │ │ 📰 News API │ │ 🐦 Social │ │ 🤖 LLM │
│ 📊 CryptoCmp│ │ │ Media │ │ Analysis │ Pipeline Events: QUERY_CHECK | QUERY_ANALYZER |
│ 🟡 Binance │ │ │ │ │ INFO_RECOVERY | REPORT_GENERATION |
└─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ TOOL_USED | RUN_FINISHED
└─────────────────────────┬───────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 🤖 AGNO AGENT ECOSYSTEM │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 👔 TEAM LEADER (Agno Team) │ │
│ │ - Coordina Market, News, Social Agents │ │
│ │ - Tools: ReasoningTools, PlanMemoryTool, │ │
│ │ CryptoSymbolsTools │ │
│ │ - Model: Configurabile (team_leader_model) │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ MARKET │ │ NEWS │ │ SOCIAL │ │
│ │ AGENT │ │ AGENT │ │ AGENT │ │
│ │ (Agno) │ │ (Agno) │ │ (Agno) │ │
│ │ │ │ │ │ │ │
│ │ Tool: │ │ Tool: │ │ Tool: │ │
│ │ MarketAPIs │ │ NewsAPIs │ │ SocialAPIs │ │
│ │ Tool │ │ Tool │ │ Tool │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ <20> QUERY CHECK AGENT (Agno Agent) │ │
│ │ - Valida se la query è relativa a crypto │ │
│ │ - Output Schema: QueryOutputs (is_crypto: bool) │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 📋 REPORT GENERATOR AGENT (Agno Agent) │ │
│ │ - Genera report finale basato su dati raccolti │ │
│ │ - Applica strategia (Conservative/Aggressive) │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────┘
``` ```
@@ -45,211 +90,548 @@
│ "Analizza Bitcoin con strategia aggressiva" │ "Analizza Bitcoin con strategia aggressiva"
┌─────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────
🔧 TOOL AGENT <20> CHAT MANAGER
│ │ │ │
def interact(query, provider, style): - Riceve messaggio utente
- Gestisce history della conversazione
├── 📊 market_data = market_agent.analyze(query) - Prepara PipelineInputs con:
├── 📰 news_sentiment = news_agent.analyze(query) * user_query: "Analizza Bitcoin..."
├── 🐦 social_sentiment = social_agent.analyze(query) * strategy: "aggressive"
* models: team_leader_model, team_model, etc.
│ └── 🤖 prediction = predictor_agent.predict(...) │ └─────────────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────┘
📊 MARKET AGENT - Parallel Data Collection ┌─────────────────────────────────────────────────────────────────┐
┌─────────────────────────────────────────────────────────────┐ │ 🔄 AGNO WORKFLOW PIPELINE │
│ │ │ │
🔍 Auto-detect Available Providers: Run ID: [3845] Pipeline query: "Analizza Bitcoin..."
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Coinbase │ │ CryptoComp │ │ Binance │ │
│ │ REST │ │ API │ │ Mock │ │
│ │ │ │ │ │ │ │
│ │ ✅ Active │ │ ✅ Active │ │ ✅ Active │ │
│ │ $63,500 BTC │ │ $63,450 BTC │ │ $63,600 BTC │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │
📈 Aggregated Result: ┌──────────────────────────────────────────────────────────┐
│ │ STEP 1: 🔍 QUERY CHECK (Query Check Agent) │ │
│ │ │ │
│ │ Input: QueryInputs(user_query, strategy) │ │
│ │ Agent: query_analyzer_model (Agno Agent) │ │
│ │ Output: QueryOutputs(response, is_crypto: bool) │ │
│ │ │ │
│ │ Result: {"is_crypto": true, "response": "..."} │ │
│ │ Event: QUERY_CHECK completed │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ STEP 2: 🤔 CONDITION CHECK │ │
│ │ │ │
│ │ Valida: previous_step_content.is_crypto │ │
│ │ If False → StopOutput(stop=True) │ │
│ │ If True → Continua al prossimo step │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ STEP 3: 📊 INFO RECOVERY (Team) │ │
│ │ │ │
│ │ 👔 Team Leader coordina: │ │
│ │ ├── 📈 Market Agent → MarketAPIsTool │ │
│ │ ├── 📰 News Agent → NewsAPIsTool │ │
│ │ └── 🐦 Social Agent → SocialAPIsTool │ │
│ │ │ │
│ │ Tools disponibili al Team Leader: │ │
│ │ - ReasoningTools (ragionamento) │ │
│ │ - PlanMemoryTool (memoria del piano) │ │
│ │ - CryptoSymbolsTools (simboli crypto) │ │
│ │ │ │
│ │ Events: TOOL_USED per ogni chiamata tool │ │
│ │ Event: INFO_RECOVERY completed │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ STEP 4: 📝 REPORT GENERATION (Report Generator Agent) │ │
│ │ │ │
│ │ Input: Tutti i dati raccolti da Info Recovery │ │
│ │ Agent: report_generation_model (Agno Agent) │ │
│ │ Strategia: Applicata dal prompt (aggressive) │ │
│ │ │ │
│ │ Output: Report finale con raccomandazioni │ │
│ │ Event: REPORT_GENERATION completed │ │
│ └──────────────────────────────────────────────────────────┘ │
│ Event: RUN_FINISHED │
│ Return: Final report string (rimozione tag <think>) │
└─────────────────────────────────────────────────────────────────┘
📋 FINAL OUTPUT TO USER
┌─────────────────────────────────────────────────────────────────┐
│ 📊 Analisi Bitcoin (BTC) │
│ │
<20> Dati di Mercato: │
│ - Prezzo: $63,516 (aggregato da 4 fonti) │
│ - Volume 24h: $2.1M │
│ - Confidence: 94% │
│ │
│ 📰 Sentiment News: Positivo (istituzionale in crescita) │
│ 🐦 Sentiment Social: Bullish (Reddit/Twitter +15%) │
│ │
│ 🎯 Raccomandazione (Strategia Aggressiva): │
│ STRONG BUY - Allocazione 15-20% del portfolio │
│ │
│ 💭 Ragionamento: [dettagli dell'analisi...] │
└─────────────────────────────────────────────────────────────────┘
```
## 🏛️ Architettura API e Tools
```
┌─────────────────────────────────────────────────────────────────┐
<20> API TOOLS ARCHITECTURE │
│ (Agno Toolkit Integration) │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 📊 MarketAPIsTool (Agno Toolkit) │ │
│ │ │ │
│ │ Tools disponibili: │ │
│ │ - get_product(asset_id) │ │
│ │ - get_products(asset_ids) │ │
│ │ - get_historical_prices(asset_id, limit) │ │
│ │ - get_products_aggregated(asset_ids) │ │
│ │ - get_historical_prices_aggregated(asset_id, limit) │ │
│ │ │ │
│ │ 🔄 WrapperHandler gestisce: │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Binance │ │ YFinance │ │ │
│ │ │ Wrapper │ │ Wrapper │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ CoinBase │ │CryptoCompare │ │ │
│ │ │ Wrapper │ │ Wrapper │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ Retry Logic: 3 tentativi per wrapper, 2s delay │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 📰 NewsAPIsTool (Agno Toolkit) │ │
│ │ │ │
│ │ 🔄 WrapperHandler gestisce: │ │
│ │ - NewsAPI Wrapper │ │
│ │ - GoogleNews Wrapper │ │
│ │ - DuckDuckGo Wrapper │ │
│ │ - CryptoPanic Wrapper │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 🐦 SocialAPIsTool (Agno Toolkit) │ │
│ │ │ │
│ │ 🔄 WrapperHandler gestisce: │ │
│ │ - Reddit Wrapper │ │
│ │ - X (Twitter) Wrapper │ │
│ │ - 4chan Wrapper │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 🔣 CryptoSymbolsTools (Agno Toolkit) │ │
│ │ - Gestisce simboli e nomi delle criptovalute │ │
│ │ - Carica da resources/cryptos.csv │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## <20> WrapperHandler Pattern
```
┌─────────────────────────────────────────────────────────────────┐
<20> WRAPPER HANDLER │
│ (Resilient API Call Management) │
│ │
│ Input: List[WrapperType] │
│ try_per_wrapper: int = 3 │
│ retry_delay: int = 2 │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ def try_call(func: Callable) -> OutputType: │ │
│ │ │ │
│ │ for wrapper in wrappers: │ │
│ │ for attempt in range(try_per_wrapper): │ │
│ │ try: │ │
│ │ result = func(wrapper) │ │
│ │ return result # ✅ Success │ │
│ │ except Exception as e: │ │
│ │ log_error(e) │ │
│ │ sleep(retry_delay) │ │
│ │ continue # <20> Retry │ │
│ │ │ │
│ │ # Switch to next wrapper │ │
│ │ │ │
│ │ raise Exception("All wrappers failed") # ❌ All fail │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ Esempio Flusso: │
│ ┌─────────┐ Fail ┌─────────┐ Fail ┌─────────┐ │
│ │Binance │────────▶│YFinance │────────▶│CoinBase │ ✅ │
│ │(3 tries)│ │(3 tries)│ │(Success)│ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ Features: │
│ ✅ Automatic failover tra providers │
│ ✅ Retry logic configurabile │
│ ✅ Logging dettagliato degli errori │
│ ✅ Type-safe con Generics │
└─────────────────────────────────────────────────────────────────┘
```
## <20> Data Aggregation Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ 📊 PRODUCT INFO AGGREGATION │
│ │
│ Input: dict[provider_name, list[ProductInfo]] │
│ │
│ Provider A: BTC → {price: 63500, volume: 1.2M} │
│ Provider B: BTC → {price: 63450, volume: N/A} │
│ Provider C: BTC → {price: 63600, volume: 2.1M} │
│ Provider D: BTC → {price: 63550, volume: 1.8M} │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Aggregation Logic: │ │
│ │ │ │
│ │ 1. Group by symbol (BTC, ETH, etc.) │ │
│ │ │ │
│ │ 2. Aggregate Volume: │ │
│ │ avg_volume = sum(volumes) / count(providers) │ │
│ │ │ │
│ │ 3. Aggregate Price (weighted by volume): │ │
│ │ weighted_price = sum(price * volume) / sum(volume) │ │
│ │ │ │
│ │ 4. Calculate Confidence: │ │
│ │ - Based on price spread │ │
│ │ - Number of sources │ │
│ │ - Volume consistency │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ Output: list[ProductInfo] │
│ { │ │ { │
│ "aggregated_data": { │ "id": "BTC_AGGREGATED",
"BTC_USD": { "symbol": "BTC",
"price": 63516.67, │ "price": 63516.67, # Weighted average
"confidence": 0.94, "volume_24h": 1.7M, # Average volume
"sources_count": 3 "currency": "USD",
│ "confidence": 0.94 # High confidence (low spread) │
│ } │ │ } │
│ }, │ └─────────────────────────────────────────────────────────────────┘
│ "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..." │
└─────────────────────────────────────────────────────────────┘
```
## 🏛️ Architettura dei Provider (Market Agent)
```
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
📊 MARKET AGENT 📈 HISTORICAL PRICE AGGREGATION
│ │ │ │
🔍 Provider Detection Logic: Input: dict[provider_name, list[Price]]
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ 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: ┌───────────────────────────────────────────────────────────┐
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Aggregation Logic:
│ │ Provider 1 │───▶│ │◀───│ Provider 2 │ │ │
│ │ Coinbase │ │ AGGREGATOR │ │ CryptoComp │ │ │ 1. Align by timestamp (YYYY-MM-DD HH:MM)
│ │ │ │
│ │ Real-time │ │ ┌─────────┐ │ │ Real-time │ │ │ 2. For each timestamp, calculate mean of:
│ │ Market Data │ │ │Confidence│ │ │ Market Data │ │ │ - high │
└─────────────┘ │ │Scoring │ │ └─────────────┘ │ - low │
│ │ │ │ │ - open
┌─────────────┐ │ │ Spread │ │ ┌─────────────┐ │ - close
│ │ Provider 3 │───▶│ │Analysis │ │◀───│ Provider N │ │ │ - volume
│ │ Binance │ │ │ │ Future │ │
│ │ │ │ └─────────┘ │ │ │ 3. Handle missing data gracefully │ │
│ Mock Data │ │ │ │ │ └───────────────────────────────────────────────────────────┘
└─────────────┘ └─────────────┘ └─────────────┘
│ Output: list[Price] (aggregated by timestamp) │
└─────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────┘
``` ```
## 🔧 Signers Architecture ## 🎯 Configuration Architecture
``` ```
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
🔐 SIGNERS ECOSYSTEM ⚙️ APP CONFIG (configs.yaml)
│ │ │ │
📁 src/app/signers/market_signers/ ┌────────────────────────────────────────────────────────┐
│ │ │ │ port: 7860 # Gradio server port │
├── 🏦 coinbase_rest_signer.py │ gradio_share: false # Public sharing
│ ├── 🔑 Uses: CDP_API_KEY_NAME + CDP_API_PRIVATE_KEY └────────────────────────────────────────────────────────┘
│ ├── 📡 RESTClient from coinbase.rest
│ ├── 📊 get_asset_info() → Real Coinbase data ┌────────────────────────────────────────────────────────┐
│ │ └── 📈 get_multiple_assets() → Bulk data │ │ models: # LLM Models Configuration
│ │ │ │ - label: "Qwen 3 (4B)"
├── 📊 cryptocompare_signer.py │ provider: "ollama"
│ │ ├── 🔑 Uses: CRYPTOCOMPARE_API_KEY │ │ model_id: "qwen3:4b"
│ │ ├── 📡 Direct HTTP requests │ │ - label: "Qwen 3 (1.7B)"
│ │ ├── 💰 get_crypto_prices() → Multi-currency │ │ provider: "ollama"
│ │ └── 🏆 get_top_cryptocurrencies() → Market cap │ │ model_id: "qwen3:1.7b"
│ │ │ │ - label: "GPT-4 Turbo"
└── 🟡 binance_signer.py │ provider: "openai"
├── 🔑 Uses: BINANCE_API_KEY (future) model_id: "gpt-4-turbo"
├── 📡 Mock implementation api_key_env: "OPENAI_API_KEY"
├── 🎭 Simulated market data # ... altri modelli (Anthropic, Google, etc.) │
└── 📈 Compatible interface └────────────────────────────────────────────────────────┘
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ strategies: # Investment Strategies │ │
│ │ - label: "Conservative" │ │
│ │ description: "Low risk, stable returns..." │ │
│ │ - label: "Aggressive" │ │
│ │ description: "High risk, high potential..." │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ agents: # Agent-specific configurations │ │
│ │ team_model: "qwen3:4b" │ │
│ │ team_leader_model: "qwen3:4b" │ │
│ │ query_analyzer_model: "qwen3:1.7b" │ │
│ │ report_generation_model: "qwen3:4b" │ │
│ │ strategy: "Conservative" │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ api: # API Configuration │ │
│ │ retry_attempts: 3 │ │
│ │ retry_delay_seconds: 2 │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 🔐 ENVIRONMENT VARIABLES (.env) │
│ │
│ # Market APIs │
│ CDP_API_KEY_NAME=... # Coinbase │
│ CDP_API_PRIVATE_KEY=... # Coinbase │
│ CRYPTOCOMPARE_API_KEY=... # CryptoCompare │
│ BINANCE_API_KEY=... # Binance (future) │
│ │
│ # News APIs │
│ NEWS_API_KEY=... # NewsAPI │
│ CRYPTOPANIC_API_KEY=... # CryptoPanic │
│ │
│ # Social APIs │
│ REDDIT_CLIENT_ID=... # Reddit │
│ REDDIT_CLIENT_SECRET=... # Reddit │
│ X_BEARER_TOKEN=... # Twitter/X │
│ │
│ # LLM Providers │
│ OPENAI_API_KEY=... # OpenAI │
│ ANTHROPIC_API_KEY=... # Anthropic │
│ GOOGLE_API_KEY=... # Google │
│ │
│ # Telegram Bot │
│ TELEGRAM_BOT_TOKEN=... # Telegram Bot │
└─────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────┘
``` ```
## 🚀 Future Enhancement: Async Flow ## 🗂️ Struttura del Progetto
``` ```
📱 USER REQUEST upo-appAI/
├── 📁 src/app/ # Codice principale
🔧 TOOL AGENT (async) ├── __main__.py # Entry point (Gradio + Telegram)
├── configs.py # Gestione configurazioni
┌────────────────┼────────────────┐ │ │
│ ├── 📁 agents/ # Sistema di agenti Agno
│ │ ├── core.py # PipelineInputs, QueryInputs/Outputs
│ │ ├── pipeline.py # Workflow Pipeline con Agno
│ │ ├── plan_memory_tool.py # Tool per memoria del piano
│ │ └── 📁 prompts/ # Prompt per gli agenti
│ │ ├── query_check.txt # Prompt Query Checker
│ │ ├── team_leader.txt # Prompt Team Leader
│ │ ├── team_market.txt # Prompt Market Agent
│ │ ├── team_news.txt # Prompt News Agent
│ │ ├── team_social.txt # Prompt Social Agent
│ │ └── report_generation.txt # Prompt Report Generator
│ │
│ ├── 📁 api/ # Layer API e Wrappers
│ │ ├── wrapper_handler.py # Pattern WrapperHandler generico
│ │ │ │ │ │
▼ ▼ ├── 📁 core/ # Interfacce base e modelli
📊 Market 📰 News 🐦 Social │ │ ├── markets.py # MarketWrapper, ProductInfo, Price
Agent (async) Agent (async) Agent (async) │ │ ├── news.py # NewsWrapper, NewsItem
│ │ │ └── social.py # SocialWrapper, SocialPost
│ │ │ │ │ │
┌────┼────┐ │ │ │ ├── 📁 markets/ # Implementazioni Market API
▼ ▼ ▼ │ │├── binance.py # BinanceWrapper
Coinbase │ Binance │ │ │ │ │ ├── coinbase.py # CoinBaseWrapper
CC │ │ │ │ │ │ ├── cryptocompare.py # CryptoCompareWrapper
▼▼▼ └── yfinance.py # YFinanceWrapper
🔄 Parallel 📰 Sentiment 🐦 Sentiment
Aggregation Analysis Analysis
│ │ │ │ │ │
└────────────────┼────────────────┘ ├── 📁 news/ # Implementazioni News API
├── newsapi.py # NewsAPIWrapper
🤖 PREDICTOR AGENT ├── googlenews.py # GoogleNewsWrapper
(LLM Analysis) ├── duckduckgo.py # DuckDuckGoWrapper
│ │ │ └── cryptopanic_api.py # CryptoPanicWrapper
│ │ │
│ │ ├── 📁 social/ # Implementazioni Social API
│ │ │ ├── reddit.py # RedditWrapper
│ │ │ ├── x.py # XWrapper (Twitter)
│ │ │ └── chan.py # 4ChanWrapper
│ │ │
│ │ └── 📁 tools/ # Agno Toolkits
│ │ ├── market_tool.py # MarketAPIsTool (Agno Toolkit)
│ │ ├── news_tool.py # NewsAPIsTool (Agno Toolkit)
│ │ ├── social_tool.py # SocialAPIsTool (Agno Toolkit)
│ │ └── symbols_tool.py # CryptoSymbolsTools (Agno Toolkit)
│ │
│ └── 📁 interface/ # Interfacce utente
│ ├── chat.py # ChatManager (Gradio)
│ └── telegram_app.py # TelegramApp (Bot)
├── 📁 tests/ # Test suite completa
📋 FINAL RESULT ├── conftest.py # Configurazione pytest
(JSON + Confidence) ├── 📁 agents/ # Test agenti
│ ├── 📁 api/ # Test API wrappers
│ ├── 📁 tools/ # Test tools
│ └── 📁 utils/ # Test utilities
├── 📁 demos/ # Script di esempio
│ ├── agno_agent.py # Demo Agno Agent
│ ├── agno_workflow.py # Demo Agno Workflow
│ ├── coinbase_demo.py # Demo Coinbase API
│ ├── cryptocompare_demo.py # Demo CryptoCompare API
│ └── market_providers_api_demo.py # Demo aggregazione provider
├── 📁 resources/ # Risorse statiche
│ └── cryptos.csv # Database simboli crypto
├── 📁 docs/ # Documentazione
│ ├── App_Architecture_Diagrams.md # Questo file
│ └── Progetto Esame.md # Specifiche progetto
├── configs.yaml # Configurazione app (modelli, strategie)
├── .env # Variabili d'ambiente (API keys)
├── .env.example # Template per .env
├── pyproject.toml # Dipendenze Python (uv/pip)
├── Dockerfile # Container Docker
├── docker-compose.yaml # Orchestrazione Docker
└── README.md # Documentazione principale
``` ```
## 📊 Data Flow Example ## 🔑 Componenti Chiave
### 1. **Agno Framework Integration**
L'applicazione utilizza il framework **Agno** per gestire:
- **Agent**: Singoli agenti con modelli LLM specifici
- **Team**: Coordinazione di più agenti sotto un Team Leader
- **Workflow**: Pipeline asincrone con step condizionali
- **Toolkit**: Integrazione tools con retry logic
- **RunEvent**: Sistema di eventi per monitoraggio
### 2. **WrapperHandler Pattern**
Pattern generico per gestire multiple implementazioni API con:
- Failover automatico tra provider
- Retry logic configurabile
- Type safety con Generics
- Logging dettagliato
### 3. **Data Aggregation**
Sistema sofisticato di aggregazione che:
- Combina dati da multiple fonti
- Calcola confidence score
- Gestisce dati mancanti/inconsistenti
- Fornisce weighted averages
### 4. **Multi-Interface Support**
Due interfacce integrate:
- **Gradio Web UI**: Chat interface con dropdown per modelli/strategie
- **Telegram Bot**: Bot con Mini App integrato
### 5. **Configuration Management**
Sistema a due livelli:
- **configs.yaml**: Configurazioni applicazione (modelli, strategie, agenti)
- **.env**: Secrets e API keys (caricato con dotenv)
## 🚀 Deployment Flow
``` ```
Input: "Analyze Bitcoin aggressive strategy" ┌─────────────────────────────────────────────────────────────────┐
│ 🐳 DOCKER DEPLOYMENT
├── 📊 Market Agent Output: │ │
{ 1. Load .env variables │
"aggregated_data": { 2. Build Docker image (Python 3.11) │
"BTC_USD": {"price": 63516.67, "confidence": 0.94} 3. Install dependencies (pyproject.toml) │
}, 4. Copy src/, configs.yaml, resources/ │
"individual_sources": { 5. Expose port 7860 (Gradio) │
"coinbase": {"price": 63500, "volume": "1.2M"}, 6. Run: python -m src.app │
"cryptocompare": {"price": 63450, "volume": "N/A"},
"binance": {"price": 63600, "volume": "2.1M"} ┌──────────────────────────────────────────────────────────┐ │
}, docker-compose up --build -d │ │
"market_signals": { │ │ │
"spread_analysis": "Low spread (0.24%) - healthy liquidity", Services: │ │
"price_divergence": "Max deviation: 0.24% - Normal range" │ - app: Main application (Gradio + Telegram) │ │
} - Networks: Bridge mode │ │
} │ - Volumes: .env mounted │ │
│ └──────────────────────────────────────────────────────────┘
── 📰 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" ┌─────────────────────────────────────────────────────────────────┐
│ 💻 LOCAL DEVELOPMENT (UV) │
│ │
│ 1. Install uv package manager │
│ 2. uv venv (create virtual environment) │
│ 3. uv pip install -e . (editable install) │
│ 4. uv run src/app (run application) │
│ │
│ Benefits: │
│ ✅ Fast dependency resolution │
│ ✅ Automatic PYTHONPATH setup │
│ ✅ Editable mode for development │
└─────────────────────────────────────────────────────────────────┘
``` ```
## 🎯 Workflow Execution Model
L'applicazione utilizza un modello di esecuzione **Asincrono** basato su Agno Workflow:
```python
# Pipeline di esecuzione
async def interact_async():
workflow = Workflow(steps=[
query_check, # Step 1: Verifica query
condition_query_ok, # Step 2: Condizione
info_recovery, # Step 3: Team di raccolta
report_generation # Step 4: Report finale
])
# Esecuzione con streaming
iterator = await workflow.arun(
query,
stream=True,
stream_intermediate_steps=True
)
# Event handling
async for event in iterator:
if event.event == PipelineEvent.TOOL_USED:
log(f"Tool: {event.tool.tool_name}")
elif event.event == WorkflowRunEvent.step_completed:
log(f"Step: {event.step_name} completed")
```
**Vantaggi:**
- ⚡ Esecuzione asincrona per migliori performance
- 📊 Streaming di eventi intermedi
- 🎯 Gestione condizionale del flusso
- 🔄 Retry automatico sui tools
## 📈 Future Enhancements
Possibili miglioramenti architetturali:
1. **Parallel Tool Execution**: Esecuzione parallela di Market/News/Social agents
2. **Caching Layer**: Redis/Memcached per ridurre chiamate API
3. **Database Integration**: PostgreSQL per storico analisi
4. **Real-time WebSocket**: Aggiornamenti live prezzi
5. **ML Model Integration**: Modelli predittivi custom (LSTM, Transformer)
6. **Advanced Aggregation**: Confidence scoring migliorato con ML
7. **User Profiles**: Personalizzazione strategie per utente
8. **Backtesting Module**: Validazione strategie su dati storici
--- ---
*Diagrammi creati: 2025-09-23* *Documento aggiornato: 2025-10-22*
*Sistema: upo-appAI Market Analysis Platform* *Sistema: upo-appAI Crypto Analysis Platform*
*Framework: Agno (Agentic AI) + Gradio + Telegram*