# PRD: ActionForex Agentic Data Solution

**Version:** 1.5  
**Status:** Implementation Substantially Complete  

## 1. Introduction [ERLEDIGT]
Build a Streamlit-based interface that allows users to interact with an AI agent (powered by the `agno` framework) to query and analyze:
- A remote MySQL database for ActionForex data
- Proprietary CSV files stored on actionforex.com via SFTP

## 2. Goals & Objectives
1. **Unified Data Access:** [ERLEDIGT] Provide a single interface to query ActionForex's MySQL database and retrieve CSV data via SFTP.  
2. **Agentic Analysis:** [ERLEDIGT] Empower the agent to merge, clean, and analyze the combined data.  
3. **Maintainable UI:** [ERLEDIGT] Enforce small, modular Streamlit components (150–250 lines each).  
4. **Secure Integration:** [ERLEDIGT] Ensure secure handling of MySQL and SFTP credentials (e.g., using environment variables or `secrets.toml`).
5. **Data Schema Archiving:** [ERLEDIGT] Maintain a local copy of the database schema for reference and documentation purposes.

## 3. Core Requirements

### 3.1 Functional
1. **MySQL Queries:** [ERLEDIGT] The agent can submit SQL SELECT statements and display results in Streamlit.  
2. **SFTP CSV Retrieval:** [ERLEDIGT] The agent can browse a file listing, select CSVs to download, then view or summarize them.  
3. **Data Processing & Analysis:** [ERLEDIGT] The agent can merge/join/transform data from both MySQL queries and CSVs.  
4. **Visualizations:** [ERLEDIGT] Display data in tables or charts (line, bar, etc.) within Streamlit using Plotly.  
5. **Agentic Interaction:** [ERLEDIGT] A chat-like UI so users can request data or analysis by natural language.  
6. **Strict UI Modularity:** [ERLEDIGT] Each Streamlit component or module remains under 250 lines of code.
7. **Database Schema Export:** [ERLEDIGT] Utility to export the database schema to a local SQL file for reference.

### 3.2 Technical
1. **Python 3.12+** [ERLEDIGT]  
2. **Core Libraries:** [ERLEDIGT] `agno`, `streamlit`, `mysql-connector-python`, `paramiko`, `pandas`, `plotly`.  
3. **Credentials:** [ERLEDIGT] Stored securely in local .env file (no hardcoding). Prefer SSH key-based SFTP auth.  
4. **Error Handling:** [ERLEDIGT] Provide informative feedback when MySQL or SFTP operations fail.  
5. **Logging & Testing:** [ERLEDIGT] Basic logs for connections and operations; unit/integration tests around DB & SFTP tools.
6. **Database Connection Validation:** [ERLEDIGT] Test scripts to validate MySQL connectivity prior to UI operations.

### 3.3 Security
1. **Encrypted Connections:** [ERLEDIGT] Use SSL/TLS for MySQL (if available) and SSH for SFTP.  
2. **SQL Injection Prevention:** [ERLEDIGT] Use parameterized queries for user-submitted SQL.  
3. **Credential Management:** [ERLEDIGT] Rely on environment variables or `secrets.toml` for DB/SFTP credentials.  
4. **File Handling:** [ERLEDIGT] Store downloaded CSVs temporarily with restricted permissions; remove when done.

### 3.4 Data Initialization & Maintenance
1. **SFTP Data Sourcing:** [ERLEDIGT] One-time command-line utility to download CSV data files from SFTP server.
2. **Database Schema Documentation:** [ERLEDIGT] Utility to export the database structure to a SQL file for documentation.
3. **Connection Testing:** [ERLEDIGT] Test scripts to validate both MySQL and SFTP connectivity.

## 4. User Flow
1. **Open Application:** [ERLEDIGT] Launched via a task/command in Cursor or VSCode.  
2. **Enter Prompt/Query:** [ERLEDIGT] User types a natural-language request.  
3. **Agent Processing:** [ERLEDIGT] The `agno` agent decides which tools to call (MySQL or SFTP) and fetches or merges data.  
4. **Data Display:** [ERLEDIGT] The user sees the results (table, chart, text summary) in the Streamlit UI.  
5. **Refine or Repeat:** [ERLEDIGT] User can refine their query or ask a new question in the chat.

## 5. Future Considerations
- **Advanced Analytics:** [ERLEDIGT] Integrated time-series forecasting, statistical analysis capabilities, and specialized agents. 
- **Scalable Deployment:** [OFFEN] Potentially run the agent as a separate service if usage grows.  
- **User Auth:** [OFFEN] If a broader audience needs access, implement authentication to protect data sources.
- **Schema Evolution:** [OFFEN] Track changes to database schema over time.

## 6. Implementierungsfortschritt

### Erledigte Komponenten:
- MySQL Datenbankverbindung und -abfrage in `src/database/connection.py` und `src/database/operations.py`
- SFTP-Verbindung und -operationen in `src/sftp/connection.py` und `src/sftp/operations.py`
- Verbindungstests in `scripts/test_connections.py`
- Datenbank-Schema-Export-Dienstprogramm in `scripts/export_db_schema.py`
- AI-Agent mit Tool-Unterstützung in `src/ai/agent.py`
- Datenverarbeitungs- und Analysetools in `src/ai/tools.py`
- Visualisierungskomponenten in `src/ui/visualizations.py` und `src/ui/forex_charts.py`
- Streamlit-Chat-Benutzeroberfläche in `src/app.py`
- Integration in Market Intelligence Suite mit spezialisierten Agenten
- Sentiment-Analyse für Forex-Nachrichten und Kommentare in `src/ai/sentiment_analysis.py`

### Datenverarbeitungsfunktionen:
- **In-Memory-Datenspeicherung**: Speichern von SQL- und CSV-Daten unter benutzerdefinierten Namen
- **Datenmanipulation**: Tools zum Zusammenführen (merge), Filtern und Transformieren von Datensätzen
- **Dateninspektion**: Anzeigen von gespeicherten Datensätzen, Beschreibung deren Struktur

### Visualisierungsfunktionen:
- **Plotly-Integration**: Erstellung von interaktiven Diagrammen (Linien, Balken, Punkt, etc.)
- **Spezialisierte Forex-Charts**: [ERLEDIGT] Implementierung von Candlestick, OHLC und technischen Charts mit Indikatoren
- **Visuelle Analysen**: Spezialisierter Agent für Visualisierungsanfragen

### Implementierte Advanced Analytics:
- **Zeit-Reihen-Analyse**: Implementierung von Zeit-Reihen-Zerlegung, Stationaritätstests und Saisonalitätserkennung
- **Prognosemodelle**: ARIMA-basierte Vorhersagen mit Konfidenzintervallen für Finanz- und Wirtschaftsdaten
- **Statistikfunktionen**: Umfassende statistische Analysen mit Korrelationen, Ausreißererkennung und Verteilungsanalyse
- **ForexMarketIntelligenceAgent**: [ERLEDIGT] Spezialisierter Agent für Echtzeit-Forex-Marktinformationen
  - Integration mit Agno DuckDuckGoTools für aktuelle Marktdaten
  - Kontextbewusste Antworten, die die ActionForex-Plattform berücksichtigen
  - Fokus auf Währungspaare, wirtschaftliche Indikatoren und Marktsentiment
  - Teil des koordinierten Analytics-Teams für umfassende Forex-Analysen
- **Sentiment-Analyse**: [ERLEDIGT] Analyse von Forex-Markt-Nachrichten und Kommentaren
  - Kategorisierung nach bullish, bearish, neutral und uncertainty
  - Erkennung von Währungspaaren in Textinhalten
  - Quantitative Sentiment-Metrik mit Konfidenzwerten
  - Batch-Analyse und Generierung von Sentiment-Zusammenfassungen

### Nächste Schritte:
1. **Erweiterte Marktintelligenz**: Verbesserung der Forex Market Intelligence mit:
   - Integration weiterer Datenquellen für Finanzmarktnachrichten
   - Automatische Erkennung und Benachrichtigung bei wichtigen Marktbewegungen
2. **Optimierung**: Feinabstimmung der Agenten und Verbesserung der Benutzeroberfläche.
3. **Erweiterte Tests**: Durchführen umfassenderer End-to-End-Tests mit komplexen Abfrageszenarien.

## 7. Market Intelligence Suite Spezialisierte Agenten

Die Market Intelligence Suite nutzt spezialisierte Agenten für spezifische Analyseaufgaben:

### StatisticalAnalysisAgent [ERLEDIGT]
- Umfassende statistische Analyse von Daten
- Identifizierung von Korrelationen und Verteilungsmerkmalen
- Erstellung statistischer Visualisierungen und Interpretationen
- Ausgabe von Ausreißern, starken Korrelationen und ungewöhnlichen Verteilungen
- Nutzung der Toolbox-Funktionen für statistische Analysen

### TimeSeriesAgent [ERLEDIGT]
- Spezialisiert auf Zeitreihenanalyse und -prognose
- Identifizierung von Trends, Saisonalität und Anomalien
- Generierung von Prognosen mit Konfidenzintervallen
- Erklärung von Stationarität und ihrer Bedeutung für die Zeitreihenmodellierung
- Visualisierung von historischen Mustern und Prognosen

### DataTransformationAgent [ERLEDIGT]
- Ausführung komplexer Datentransformationen
- Aggregation, Filterung und Zusammenführung von Datensätzen
- Vorbereitung von Daten für weiterführende Analysen
- Verständnis der aktuellen Datenstruktur vor der Transformation
- Überprüfung von Spaltennamen und Datentypen für Operationen

### ForexMarketIntelligenceAgent [ERLEDIGT]
- Echtzeit-Forex-Marktinformationen und -analysen
- Fokus auf Währungspaare, Wirtschaftsindikatoren und Marktsentiment
- Integration mit der ActionForex-Plattform
- Nutzung der DuckDuckGo-Suche für aktuelle Marktdaten
- Integration mit dem Sentiment-Analyse-Tool für quantitative Sentiment-Metriken

### AnalyticsTeam [ERLEDIGT]
- Koordiniertes Team der spezialisierten Agenten
- Gemeinsame Bearbeitung komplexer Forex-Analyseaufgaben
- Kombination von statistischen, Zeitreihen- und Marktdaten für umfassende Einblicke
- Koordinierter Arbeitsablauf zwischen den verschiedenen Agenten
- Nutzung aller verfügbaren Werkzeuge für umfassende Forex-Analysen

## 8. Forex-Visualisierungen

### ForexChartCreator [ERLEDIGT]
- Implementierung einer spezialisierten Klasse für Forex-Charts in `src/ui/forex_charts.py`
- Unterstützung von Standard-Diagrammtypen:
  - **Candlestick-Charts**: Darstellung von OHLC-Daten mit farbkodierten Kerzen
  - **OHLC-Charts**: Traditionelle Open-High-Low-Close-Darstellung
  - **Technische Charts**: Integration mehrerer technischer Indikatoren
- Implementierte technische Indikatoren:
  - **Gleitende Durchschnitte (MA)**: Berechnung und Anzeige für verschiedene Perioden
  - **Relative Strength Index (RSI)**: Mit Überverkauft/Überkauft-Linien
  - **Moving Average Convergence Divergence (MACD)**: Mit Signallinie und Histogramm
  - **Volumen**: Farbkodierte Volumenbalken basierend auf Preisbewegungen
- Anpassbare Layouts und Farbschemata
- Subplots für verschiedene Indikatoren
- Convenience-Funktionen für einfache API-Nutzung

### Integration mit AI-Toolbox [ERLEDIGT]
- `create_forex_chart` Tool in der ToolBox-Klasse
- Ermöglicht Agenten die einfache Erstellung spezialisierter Forex-Charts
- Optionen zur Datenformatierung und Diagrammanpassung

## 9. Sentiment-Analyse

### ForexSentimentAnalyzer [ERLEDIGT]
- Implementierung einer spezialisierten Klasse für Forex-Sentiment-Analyse in `src/ai/sentiment_analysis.py`
- Enthält umfangreiche Sentiment-Wörterbücher für Finanzterminologie:
  - **Bullish Terms**: Wörter und Phrasen mit positiver Marktaussicht
  - **Bearish Terms**: Wörter und Phrasen mit negativer Marktaussicht
  - **Neutral Terms**: Sachliche oder ausgeglichene Finanzterminologie
  - **Uncertainty Terms**: Begriffe, die Unsicherheit oder Volatilität anzeigen
- Schlüsselfunktionen:
  - **Erkennung von Währungspaaren**: Automatische Identifizierung von Währungspaaren in Texten
  - **Textanalyse**: Berechnung von Sentiment-Scores mit Konfidenzwerten
  - **Batch-Analyse**: Verarbeitung mehrerer Texte in einem Durchgang
  - **Zeitbasierte Analyse**: Analyse von Sentiment-Trends über die Zeit
  - **Währungspaar-spezifisches Sentiment**: Fokussierte Analyse für bestimmte Währungspaare
- Integration mit dem ForexMarketIntelligenceAgent
- Tool `analyze_forex_sentiment` in der ToolBox-Klasse für Agentennutzung

### Integrierte Sentiment-Metriken [ERLEDIGT]
- Quantitative Bewertung von Marktstimmungen
- Prozentuale Verteilung von bullish, bearish und neutral
- Konfidenzwerte für Sentiment-Scores
- Trend-Analyse für zeitbasierte Sentiment-Daten

## 10. Erfolgskriterien und Metriken

Um den Erfolg der Market Intelligence Suite zu messen, werden folgende Metriken verwendet:

### Leistungsmetriken:
- **Antwortzeit**: Durchschnittliche Zeit für Agentenantworten < 5 Sekunden
- **Verarbeitungsdauer**: Zeit für komplexe Analysen < 30 Sekunden
- **Speichernutzung**: Maximale Speichernutzung pro Sitzung < 1 GB

### Genauigkeitsmetriken:
- **Vorhersagegenauigkeit**: MAPE (Mean Absolute Percentage Error) < 5% für Forex-Vorhersagen
- **Erfolgsrate bei Abfragen**: > 90% erfolgreiche Durchführung von Benutzeranfragen
- **Datenretrievalgenauigkeit**: > 95% Übereinstimmung zwischen Agentenabfrage und tatsächlichen Datenanforderungen
- **Sentiment-Analysegenauigkeit**: > 85% Übereinstimmung mit menschlichen Analysten

### Benutzererfahrungsmetriken:
- **Benutzerzufriedenheit**: > 4,5/5 in Benutzerbewertungen
- **Wiederholungsrate**: > 80% der Benutzer kehren innerhalb einer Woche zurück
- **Durchschnittliche Sitzungsdauer**: > 10 Minuten

### Geschäftsmetriken:
- **Funktionsnutzung**: > 70% der implementierten Funktionen werden regelmäßig genutzt
- **Reduzierung der manuellen Analysezeit**: > 40% Zeitersparnis für Forex-Analysten
- **Steigerung der Benutzerinteraktion**: > 30% Anstieg der Benutzerinteraktionen auf der ActionForex-Plattform

Diese Metriken werden über ein Dashboard überwacht und monatlich ausgewertet, um kontinuierliche Verbesserungen zu steuern.

## 11. Implementierungsplan für kommende Funktionen

Dieser Abschnitt beschreibt den detaillierten Plan für die Implementierung der nächsten Funktionen:

### Phase 1: Erweiterte Forex Market Intelligence [GEPLANT FÜR Q2 2025]

1. **Erweiterte Datenquellen-Integration**:
   - Integration mit spezialisierten Finanznachrichtenquellen
   - Entwicklung von Adaptern für zusätzliche Marktdaten-APIs
   - Implementierung in `src/ai/data_sources/`

2. **Automatisierte Marktbenachrichtigungen**:
   - Entwicklung eines Überwachungssystems für wichtige Marktbewegungen
   - Integration mit dem ActionForex-Benachrichtigungssystem
   - Implementierung in `src/ai/market_alerts.py`

### Phase 2: Visualisierungsverbesserungen [GEPLANT FÜR Q3 2025]

1. **Erweiterte Forex-Diagramme**:
   - Entwicklung weiterer technischer Indikatoren (Bollinger Bands, Fibonacci)
   - Integration von heatmaps für Korrelationsanalysen
   - Verbesserungen in `src/ui/forex_charts.py`

2. **Interaktive Dashboards**:
   - Erstellung von vorkonfigurierten Dashboards für gängige Analysen
   - Benutzerdefinierte Dashboard-Erstellung
   - Implementierung in `src/ui/dashboards/`

### Phase 3: Infrastrukturoptimierung [GEPLANT FÜR Q4 2025]

1. **Performance-Optimierung**:
   - Caching-Strategien für häufige Abfragen
   - Optimierung der Agenten-Initialisierungszeit
   - Implementierung in `src/utils/cache.py`

2. **Skalierbarkeit**:
   - Entwicklung eines separaten Agenten-Dienstes für bessere Skalierbarkeit
   - Load Balancing für mehrere Benutzeranfragen
   - Implementierung in `src/services/`