Demos & Docs #42
@@ -1,637 +1,160 @@
|
|||||||
# 📊 Architettura e Flussi dell'App upo-appAI
|
# 📊 Architettura upo-appAI
|
||||||
|
|
||||||
## 🏗️ Diagramma Architettura Generale
|
## 🏗️ Architettura Generale
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
INTERFACCE UTENTE
|
||||||
│ 🌐 INTERFACCE UTENTE │
|
├── 💬 Gradio Web (Chat + Dropdown modelli/strategie)
|
||||||
│ ┌────────────────────────────────────────────────────────────┐ │
|
└── 📱 Telegram Bot (Mini App)
|
||||||
│ │ 💬 Gradio Web Interface │ │
|
│
|
||||||
│ │ ┌──────────┐ ┌──────────┐ ┌───────────────────────┐ │ │
|
▼
|
||||||
│ │ │ Chat │ │ Model │ │ Strategy (Strategy) │ │ │
|
CHAT MANAGER
|
||||||
│ │ │ History │ │Dropdown │ │ - Conservative │ │ │
|
├── Storico messaggi
|
||||||
│ │ │ │ │ │ │ - Aggressive │ │ │
|
├── Gestione PipelineInputs
|
||||||
│ │ └──────────┘ └──────────┘ └───────────────────────┘ │ │
|
└── Salva/Carica chat
|
||||||
│ └────────────────────────────────────────────────────────────┘ │
|
│
|
||||||
│ ┌────────────────────────────────────────────────────────────┐ │
|
▼
|
||||||
│ │ 📱 Telegram Bot Interface │ │
|
AGNO WORKFLOW PIPELINE (4 Steps)
|
||||||
│ │ (Mini App con integrazione Gradio) │ │
|
├── 1. Query Check → Verifica crypto
|
||||||
│ └────────────────────────────────────────────────────────────┘ │
|
├── 2. Condition → Valida procedere
|
||||||
└─────────────────────────┬───────────────────────────────────────┘
|
├── 3. Info Recovery → Team raccolta dati
|
||||||
│
|
└── 4. Report Generation → Report finale
|
||||||
▼
|
│
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
▼
|
||||||
│ 🎯 CHAT MANAGER │
|
AGNO AGENT ECOSYSTEM
|
||||||
│ (Gestione Conversazioni) │
|
├── 👔 TEAM LEADER (coordina Market, News, Social)
|
||||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
│ Tools: ReasoningTools, PlanMemoryTool, CryptoSymbolsTools
|
||||||
│ │ - Mantiene storico messaggi (history) │ │
|
├── 📈 MARKET AGENT → MarketAPIsTool
|
||||||
│ │ - Gestisce input Pipeline (PipelineInputs) │ │
|
├── 📰 NEWS AGENT → NewsAPIsTool
|
||||||
│ │ - Salva/Carica chat (JSON) │ │
|
├── 🐦 SOCIAL AGENT → SocialAPIsTool
|
||||||
│ │ - Interfaccia Gradio (gradio_build_interface) │ │
|
├── 🔍 QUERY CHECK AGENT → QueryOutputs (is_crypto: bool)
|
||||||
│ └─────────────────────────────────────────────────────────┘ │
|
└── 📋 REPORT GENERATOR AGENT → Strategia applicata
|
||||||
└─────────────────────────┬───────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 🔄 AGNO WORKFLOW PIPELINE │
|
|
||||||
│ (Orchestrazione Asincrona) │
|
|
||||||
│ │
|
|
||||||
│ Step 1: 🔍 Query Check → Verifica query crypto │
|
|
||||||
│ Step 2: 🤔 Condition Check → Valida se procedere │
|
|
||||||
│ Step 3: 📊 Info Recovery → Team di raccolta dati │
|
|
||||||
│ Step 4: 📝 Report Generation → Genera report finale │
|
|
||||||
│ │
|
|
||||||
│ Pipeline Events: QUERY_CHECK | QUERY_ANALYZER | │
|
|
||||||
│ 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) │ │
|
|
||||||
│ └───────────────────────────────────────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔄 Flusso di Esecuzione Dettagliato
|
## 🔄 Flusso Esecuzione
|
||||||
|
|
||||||
```
|
**Input:** "Analizza Bitcoin con strategia aggressiva"
|
||||||
👤 USER REQUEST
|
|
||||||
│
|
1. CHAT MANAGER riceve e prepara PipelineInputs
|
||||||
│ "Analizza Bitcoin con strategia aggressiva"
|
2. WORKFLOW PIPELINE esegue 4 step:
|
||||||
▼
|
- Query Check: valida `is_crypto: true`
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
- Condition: se false, termina
|
||||||
│ <20> CHAT MANAGER │
|
- Info Recovery: Team raccoglie dati
|
||||||
│ │
|
- Report Generation: genera report
|
||||||
│ - Riceve messaggio utente │
|
3. OUTPUT: Report con analisi + raccomandazioni
|
||||||
│ - Gestisce history della conversazione │
|
|
||||||
│ - Prepara PipelineInputs con: │
|
## 🏛️ Architettura API
|
||||||
│ * user_query: "Analizza Bitcoin..." │
|
|
||||||
│ * strategy: "aggressive" │
|
**Tools (Agno Toolkit):**
|
||||||
│ * models: team_leader_model, team_model, etc. │
|
- MarketAPIsTool: Binance, YFinance, CoinBase, CryptoCompare
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
- NewsAPIsTool: NewsAPI, GoogleNews, DuckDuckGo, CryptoPanic
|
||||||
│
|
- SocialAPIsTool: Reddit, X, 4chan
|
||||||
▼
|
- CryptoSymbolsTools: `resources/cryptos.csv`
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 🔄 AGNO WORKFLOW PIPELINE │
|
**WrapperHandler:** Failover automatico (3 tentativi/wrapper, 2s delay)
|
||||||
│ │
|
|
||||||
│ Run ID: [3845] Pipeline query: "Analizza Bitcoin..." │
|
## 📊 Data Aggregation
|
||||||
│ │
|
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
**ProductInfo:**
|
||||||
│ │ STEP 1: 🔍 QUERY CHECK (Query Check Agent) │ │
|
- Volume: media tra sources
|
||||||
│ │ │ │
|
- Price: weighted average (price × volume)
|
||||||
│ │ Input: QueryInputs(user_query, strategy) │ │
|
- Confidence: spread + numero sources
|
||||||
│ │ Agent: query_analyzer_model (Agno Agent) │ │
|
|
||||||
│ │ Output: QueryOutputs(response, is_crypto: bool) │ │
|
**Historical Price:**
|
||||||
│ │ │ │
|
- Align per timestamp
|
||||||
│ │ Result: {"is_crypto": true, "response": "..."} │ │
|
- Media: high, low, open, close, volume
|
||||||
│ │ Event: QUERY_CHECK completed │ │
|
|
||||||
│ └──────────────────────────────────────────────────────────┘ │
|
## 🎯 Configuration
|
||||||
│
|
|
||||||
▼
|
**configs.yaml:**
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
```yaml
|
||||||
│ │ STEP 2: 🤔 CONDITION CHECK │ │
|
port: 8000
|
||||||
│ │ │ │
|
models: [Ollama, OpenAI, Anthropic, Google]
|
||||||
│ │ Valida: previous_step_content.is_crypto │ │
|
strategies: [Conservative, Aggressive]
|
||||||
│ │ If False → StopOutput(stop=True) │ │
|
agents: {team_model, team_leader_model, ...}
|
||||||
│ │ If True → Continua al prossimo step │ │
|
api: {retry_attempts: 3, retry_delay_seconds: 2}
|
||||||
│ └──────────────────────────────────────────────────────────┘ │
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ 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
|
**.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
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
src/app/
|
||||||
│ <20> API TOOLS ARCHITECTURE │
|
├── __main__.py
|
||||||
│ (Agno Toolkit Integration) │
|
├── configs.py
|
||||||
│ │
|
├── agents/
|
||||||
│ ┌────────────────────────────────────────────────────────┐ │
|
│ ├── core.py
|
||||||
│ │ 📊 MarketAPIsTool (Agno Toolkit) │ │
|
│ ├── pipeline.py
|
||||||
│ │ │ │
|
│ ├── plan_memory_tool.py
|
||||||
│ │ Tools disponibili: │ │
|
│ └── prompts/
|
||||||
│ │ - get_product(asset_id) │ │
|
├── api/
|
||||||
│ │ - get_products(asset_ids) │ │
|
│ ├── wrapper_handler.py
|
||||||
│ │ - get_historical_prices(asset_id, limit) │ │
|
│ ├── core/ (markets, news, social)
|
||||||
│ │ - get_products_aggregated(asset_ids) │ │
|
│ ├── markets/ (Binance, CoinBase, CryptoCompare, YFinance)
|
||||||
│ │ - get_historical_prices_aggregated(asset_id, limit) │ │
|
│ ├── news/ (NewsAPI, GoogleNews, DuckDuckGo, CryptoPanic)
|
||||||
│ │ │ │
|
│ ├── social/ (Reddit, X, 4chan)
|
||||||
│ │ 🔄 WrapperHandler gestisce: │ │
|
│ └── tools/ (Agno Toolkits)
|
||||||
│ │ ┌──────────────┐ ┌──────────────┐ │ │
|
└── interface/ (chat.py, telegram_app.py)
|
||||||
│ │ │ 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
|
tests/
|
||||||
|
demos/
|
||||||
```
|
resources/cryptos.csv
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
docs/
|
||||||
│ <20> WRAPPER HANDLER │
|
configs.yaml
|
||||||
│ (Resilient API Call Management) │
|
.env
|
||||||
│ │
|
|
||||||
│ 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] │
|
|
||||||
│ { │
|
|
||||||
│ "id": "BTC_AGGREGATED", │
|
|
||||||
│ "symbol": "BTC", │
|
|
||||||
│ "price": 63516.67, # Weighted average │
|
|
||||||
│ "volume_24h": 1.7M, # Average volume │
|
|
||||||
│ "currency": "USD", │
|
|
||||||
│ "confidence": 0.94 # High confidence (low spread) │
|
|
||||||
│ } │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 📈 HISTORICAL PRICE AGGREGATION │
|
|
||||||
│ │
|
|
||||||
│ Input: dict[provider_name, list[Price]] │
|
|
||||||
│ │
|
|
||||||
│ ┌───────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ Aggregation Logic: │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ 1. Align by timestamp (YYYY-MM-DD HH:MM) │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ 2. For each timestamp, calculate mean of: │ │
|
|
||||||
│ │ - high │ │
|
|
||||||
│ │ - low │ │
|
|
||||||
│ │ - open │ │
|
|
||||||
│ │ - close │ │
|
|
||||||
│ │ - volume │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ 3. Handle missing data gracefully │ │
|
|
||||||
│ └───────────────────────────────────────────────────────────┘ │
|
|
||||||
│ │
|
|
||||||
│ Output: list[Price] (aggregated by timestamp) │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎯 Configuration Architecture
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ ⚙️ APP CONFIG (configs.yaml) │
|
|
||||||
│ │
|
|
||||||
│ ┌────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ port: 7860 # Gradio server port │ │
|
|
||||||
│ │ gradio_share: false # Public sharing │ │
|
|
||||||
│ └────────────────────────────────────────────────────────┘ │
|
|
||||||
│ │
|
|
||||||
│ ┌────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ models: # LLM Models Configuration │ │
|
|
||||||
│ │ - label: "Qwen 3 (4B)" │ │
|
|
||||||
│ │ provider: "ollama" │ │
|
|
||||||
│ │ model_id: "qwen3:4b" │ │
|
|
||||||
│ │ - label: "Qwen 3 (1.7B)" │ │
|
|
||||||
│ │ provider: "ollama" │ │
|
|
||||||
│ │ model_id: "qwen3:1.7b" │ │
|
|
||||||
│ │ - label: "GPT-4 Turbo" │ │
|
|
||||||
│ │ provider: "openai" │ │
|
|
||||||
│ │ model_id: "gpt-4-turbo" │ │
|
|
||||||
│ │ api_key_env: "OPENAI_API_KEY" │ │
|
|
||||||
│ │ # ... altri modelli (Anthropic, Google, etc.) │ │
|
|
||||||
│ └────────────────────────────────────────────────────────┘ │
|
|
||||||
│ │
|
|
||||||
│ ┌────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ 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 │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🗂️ Struttura del Progetto
|
|
||||||
|
|
||||||
```
|
|
||||||
upo-appAI/
|
|
||||||
│
|
|
||||||
├── 📁 src/app/ # Codice principale
|
|
||||||
│ ├── __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
|
|
||||||
│ │ │ ├── markets.py # MarketWrapper, ProductInfo, Price
|
|
||||||
│ │ │ ├── news.py # NewsWrapper, NewsItem
|
|
||||||
│ │ │ └── social.py # SocialWrapper, SocialPost
|
|
||||||
│ │ │
|
|
||||||
│ │ ├── 📁 markets/ # Implementazioni Market API
|
|
||||||
│ │ │ ├── binance.py # BinanceWrapper
|
|
||||||
│ │ │ ├── coinbase.py # CoinBaseWrapper
|
|
||||||
│ │ │ ├── cryptocompare.py # CryptoCompareWrapper
|
|
||||||
│ │ │ └── yfinance.py # YFinanceWrapper
|
|
||||||
│ │ │
|
|
||||||
│ │ ├── 📁 news/ # Implementazioni News API
|
|
||||||
│ │ │ ├── newsapi.py # NewsAPIWrapper
|
|
||||||
│ │ │ ├── googlenews.py # GoogleNewsWrapper
|
|
||||||
│ │ │ ├── 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
|
|
||||||
│ ├── conftest.py # Configurazione pytest
|
|
||||||
│ ├── 📁 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔑 Componenti Chiave
|
## 🔑 Componenti Chiave
|
||||||
|
|
||||||
### 1. **Agno Framework Integration**
|
1. **Agno Framework**: Agent, Team, Workflow, Toolkit, RunEvent
|
||||||
L'applicazione utilizza il framework **Agno** per gestire:
|
2. **WrapperHandler**: Failover, Retry logic, Type safety
|
||||||
- **Agent**: Singoli agenti con modelli LLM specifici
|
3. **Data Aggregation**: Multiple sources, Confidence score
|
||||||
- **Team**: Coordinazione di più agenti sotto un Team Leader
|
4. **Multi-Interface**: Gradio + Telegram
|
||||||
- **Workflow**: Pipeline asincrone con step condizionali
|
5. **Configuration**: configs.yaml + .env
|
||||||
- **Toolkit**: Integrazione tools con retry logic
|
|
||||||
- **RunEvent**: Sistema di eventi per monitoraggio
|
|
||||||
|
|
||||||
### 2. **WrapperHandler Pattern**
|
## 🚀 Deployment
|
||||||
Pattern generico per gestire multiple implementazioni API con:
|
|
||||||
- Failover automatico tra provider
|
|
||||||
- Retry logic configurabile
|
|
||||||
- Type safety con Generics
|
|
||||||
- Logging dettagliato
|
|
||||||
|
|
||||||
### 3. **Data Aggregation**
|
**Docker:**
|
||||||
Sistema sofisticato di aggregazione che:
|
```bash
|
||||||
- Combina dati da multiple fonti
|
docker-compose up --build -d
|
||||||
- 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
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 🐳 DOCKER DEPLOYMENT │
|
|
||||||
│ │
|
|
||||||
│ 1. Load .env variables │
|
|
||||||
│ 2. Build Docker image (Python 3.11) │
|
|
||||||
│ 3. Install dependencies (pyproject.toml) │
|
|
||||||
│ 4. Copy src/, configs.yaml, resources/ │
|
|
||||||
│ 5. Expose port 7860 (Gradio) │
|
|
||||||
│ 6. Run: python -m src.app │
|
|
||||||
│ │
|
|
||||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ docker-compose up --build -d │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ Services: │ │
|
|
||||||
│ │ - app: Main application (Gradio + Telegram) │ │
|
|
||||||
│ │ - Networks: Bridge mode │ │
|
|
||||||
│ │ - Volumes: .env mounted │ │
|
|
||||||
│ └──────────────────────────────────────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 💻 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
|
**Local (UV):**
|
||||||
|
```bash
|
||||||
|
uv venv
|
||||||
|
uv pip install -e .
|
||||||
|
uv run src/app
|
||||||
|
```
|
||||||
|
|
||||||
L'applicazione utilizza un modello di esecuzione **Asincrono** basato su Agno Workflow:
|
## 🎯 Workflow Asincrono
|
||||||
|
|
||||||
```python
|
```python
|
||||||
# Pipeline di esecuzione
|
workflow = Workflow(steps=[
|
||||||
async def interact_async():
|
query_check, condition,
|
||||||
workflow = Workflow(steps=[
|
info_recovery, report_generation
|
||||||
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)
|
||||||
iterator = await workflow.arun(
|
|
||||||
query,
|
|
||||||
stream=True,
|
|
||||||
stream_intermediate_steps=True
|
|
||||||
)
|
|
||||||
|
|
||||||
# Event handling
|
async for event in iterator:
|
||||||
async for event in iterator:
|
if event.event == PipelineEvent.TOOL_USED:
|
||||||
if event.event == PipelineEvent.TOOL_USED:
|
log(f"Tool: {event.tool.tool_name}")
|
||||||
log(f"Tool: {event.tool.tool_name}")
|
|
||||||
elif event.event == WorkflowRunEvent.step_completed:
|
|
||||||
log(f"Step: {event.step_name} completed")
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Vantaggi:**
|
**Vantaggi:** Asincrono, Streaming, Condizionale, Retry
|
||||||
- ⚡ Esecuzione asincrona per migliori performance
|
|
||||||
- 📊 Streaming di eventi intermedi
|
|
||||||
- 🎯 Gestione condizionale del flusso
|
|
||||||
- 🔄 Retry automatico sui tools
|
|
||||||
|
|
||||||
## 📈 Future Enhancements
|
## 📈 Future Enhancements
|
||||||
|
|
||||||
Possibili miglioramenti architetturali:
|
- Parallel Tool Execution
|
||||||
|
- Caching (Redis)
|
||||||
1. **Parallel Tool Execution**: Esecuzione parallela di Market/News/Social agents
|
- Database (PostgreSQL)
|
||||||
2. **Caching Layer**: Redis/Memcached per ridurre chiamate API
|
- Real-time WebSocket
|
||||||
3. **Database Integration**: PostgreSQL per storico analisi
|
- ML Models
|
||||||
4. **Real-time WebSocket**: Aggiornamenti live prezzi
|
- User Profiles
|
||||||
5. **ML Model Integration**: Modelli predittivi custom (LSTM, Transformer)
|
- Backtesting
|
||||||
6. **Advanced Aggregation**: Confidence scoring migliorato con ML
|
|
||||||
7. **User Profiles**: Personalizzazione strategie per utente
|
|
||||||
8. **Backtesting Module**: Validazione strategie su dati storici
|
|
||||||
|
|
||||||
---
|
|
||||||
*Documento aggiornato: 2025-10-22*
|
|
||||||
*Sistema: upo-appAI Crypto Analysis Platform*
|
|
||||||
*Framework: Agno (Agentic AI) + Gradio + Telegram*
|
|
||||||
|
|||||||
Reference in New Issue
Block a user