|
1 | | -# Step2Job Cloud Agents |
| 1 | +# Code Cloud Agents |
| 2 | + |
| 3 | +## Frontend (Figma UI) |
| 4 | + |
| 5 | +React + Vite + TypeScript Dashboard für Agent-Management. |
| 6 | + |
| 7 | +```bash |
| 8 | +npm install |
| 9 | +npm run dev |
| 10 | +``` |
| 11 | + |
| 12 | +## Backend (Python) |
2 | 13 |
|
3 | 14 | Deployment-Template für Supervisor-KI, Log-Auswertung und Dashboard. |
4 | 15 |
|
5 | | -## Features |
| 16 | +### Features |
6 | 17 |
|
7 | 18 | - **Risikobewertung**: Automatische Erkennung von Preis- und Rechtsbehauptungen |
8 | 19 | - **Batch-Verarbeitung**: Mehrere Log-Dateien parallel verarbeiten |
9 | 20 | - **Report-Export**: JSON, CSV und HTML Reports |
10 | 21 | - **Dashboard-Generierung**: Live Supervisor-Dashboard |
11 | 22 | - **Alert-System**: Automatische Warnungen bei kritischen Vorfällen |
12 | 23 | - **Agent-Statistiken**: Performance-Tracking pro Agent |
13 | | -- **CI/CD Pipeline**: Automatische Tests mit GitHub Actions |
14 | 24 |
|
15 | | -## Installation |
| 25 | +### Installation |
16 | 26 |
|
17 | 27 | ```bash |
18 | | -# Repository klonen |
19 | | -git clone <repository-url> |
20 | | -cd code-cloud-agents |
21 | | - |
22 | | -# Abhängigkeiten installieren |
23 | 28 | pip install -r requirements.txt |
24 | | - |
25 | | -# Optional: Pre-commit Hooks aktivieren |
26 | | -pip install pre-commit |
27 | | -pre-commit install |
28 | 29 | ``` |
29 | 30 |
|
30 | | -## Verwendung |
31 | | - |
32 | | -### Einzelne Datei analysieren |
| 31 | +### Verwendung |
33 | 32 |
|
34 | 33 | ```bash |
| 34 | +# Einzelne Datei analysieren |
35 | 35 | python agents/agent_log_scorer.py sample_call_log.json |
36 | | -``` |
37 | | - |
38 | | -### Batch-Verarbeitung |
39 | | - |
40 | | -```bash |
41 | | -# Alle JSON-Dateien in einem Verzeichnis |
42 | | -python agents/agent_log_scorer.py --batch ./logs/ |
43 | | - |
44 | | -# Mit HTML-Report |
45 | | -python agents/agent_log_scorer.py --batch ./logs/ --html report.html |
46 | | - |
47 | | -# Mit CSV-Export |
48 | | -python agents/agent_log_scorer.py --batch ./logs/ --csv results.csv |
49 | | - |
50 | | -# Dashboard generieren |
51 | | -python agents/agent_log_scorer.py --batch ./logs/ --dashboard |
52 | | - |
53 | | -# Agent-Statistiken anzeigen |
54 | | -python agents/agent_log_scorer.py --batch ./logs/ --stats |
55 | | - |
56 | | -# Asynchrone Verarbeitung (schneller bei vielen Dateien) |
57 | | -python agents/agent_log_scorer.py --batch ./logs/ --async |
58 | | -``` |
59 | | - |
60 | | -### Als Python-Modul |
61 | | - |
62 | | -```python |
63 | | -from agents.agent_log_scorer import ( |
64 | | - AgentLogScorer, |
65 | | - ReportGenerator, |
66 | | - DashboardGenerator, |
67 | | - AlertSystem, |
68 | | - RiskLevel |
69 | | -) |
70 | | - |
71 | | -# Scorer initialisieren |
72 | | -scorer = AgentLogScorer() |
73 | | - |
74 | | -# Einzelnes Log analysieren |
75 | | -log = { |
76 | | - "agent_id": "AGENT_001", |
77 | | - "transcript": [{"text": "Das kostet 500 Euro"}], |
78 | | - "stop_triggered": False |
79 | | -} |
80 | | -result = scorer.score_log(log) |
81 | | -print(f"Risk: {result.risk_level.value}") # "MEDIUM" |
82 | 36 |
|
83 | 37 | # Batch-Verarbeitung |
84 | | -results = scorer.score_directory("./logs/") |
85 | | -summary = scorer.get_summary(results) |
86 | | - |
87 | | -# Reports exportieren |
88 | | -ReportGenerator.to_html(results, summary, "report.html") |
89 | | -ReportGenerator.to_csv(results, "results.csv") |
90 | | - |
91 | | -# Dashboard generieren |
92 | | -stats = scorer.get_agent_statistics() |
93 | | -dashboard = DashboardGenerator.generate(results, stats) |
94 | | - |
95 | | -# Alert-System nutzen |
96 | | -alerts = AlertSystem(threshold=RiskLevel.HIGH) |
97 | | -for r in results: |
98 | | - if alerts.check(r): |
99 | | - print(f"ALERT: {r.agent_id} - {r.risk_level.value}") |
100 | | -``` |
101 | | - |
102 | | -## Log-Format |
103 | | - |
104 | | -```json |
105 | | -{ |
106 | | - "agent_id": "AGENT_001", |
107 | | - "contact_name": "Max Mustermann", |
108 | | - "timestamp": "2025-12-23T10:30:00", |
109 | | - "transcript": [ |
110 | | - {"speaker": "customer", "text": "Was kostet das?"}, |
111 | | - {"speaker": "agent", "text": "Das kläre ich intern."} |
112 | | - ], |
113 | | - "stop_triggered": true, |
114 | | - "result": "STOP_REQUIRED - Preisfrage erkannt" |
115 | | -} |
116 | | -``` |
117 | | - |
118 | | -## Ausgabe-Format |
119 | | - |
120 | | -```json |
121 | | -{ |
122 | | - "agent_id": "AGENT_001", |
123 | | - "contact": "Max Mustermann", |
124 | | - "timestamp": "2025-12-23T10:30:00", |
125 | | - "price_claim": true, |
126 | | - "price_keywords_found": ["kostet"], |
127 | | - "legal_claim": false, |
128 | | - "legal_keywords_found": [], |
129 | | - "stop_triggered": true, |
130 | | - "placeholder_used": true, |
131 | | - "risk": 0, |
132 | | - "risk_level": "LOW", |
133 | | - "violations": [] |
134 | | -} |
135 | | -``` |
136 | | - |
137 | | -## Risk-Level |
138 | | - |
139 | | -| Level | Score | Bedeutung | |
140 | | -|-------|-------|-----------| |
141 | | -| LOW | 0 | Kein Risiko erkannt | |
142 | | -| MEDIUM | 1 | Geringes Risiko, Überprüfung empfohlen | |
143 | | -| HIGH | 2 | Hohes Risiko, Aktion erforderlich | |
144 | | -| CRITICAL | 3+ | Kritisch, sofortige Intervention | |
145 | | - |
146 | | -## Risiko-Berechnung |
147 | | - |
148 | | -``` |
149 | | -Risk = price_claim(+1) + legal_claim(+1) - stop_triggered(-1) - placeholder_bonus(-1) |
150 | | -``` |
151 | | - |
152 | | -## Konfiguration |
153 | | - |
154 | | -Die Keywords und Schwellwerte werden aus `agents/flow_validator_checklist.yaml` geladen: |
155 | | - |
156 | | -```yaml |
157 | | -keywords: |
158 | | - price: |
159 | | - - "€" |
160 | | - - "euro" |
161 | | - - "preis" |
162 | | - - "kostet" |
163 | | - legal: |
164 | | - - "gesetz" |
165 | | - - "rechtlich" |
166 | | - - "erlaubt" |
167 | | - |
168 | | -risk_thresholds: |
169 | | - low: 0 |
170 | | - medium: 1 |
171 | | - high: 2 |
172 | | - |
173 | | -scoring: |
174 | | - placeholder_bonus: -1 |
175 | | -``` |
176 | | -
|
177 | | -## Tests |
178 | | -
|
179 | | -```bash |
180 | | -# Alle Tests ausführen |
181 | | -pytest tests/ -v |
182 | | - |
183 | | -# Mit Coverage |
184 | | -pytest tests/ --cov=agents --cov-report=html |
185 | | - |
186 | | -# Nur schnelle Tests |
187 | | -pytest tests/ -v -m "not slow" |
188 | | -``` |
189 | | - |
190 | | -## CI/CD |
191 | | - |
192 | | -Das Projekt enthält eine GitHub Actions Pipeline (`.github/workflows/ci.yml`): |
193 | | - |
194 | | -- **Test Matrix**: Python 3.10, 3.11, 3.12 |
195 | | -- **Linting**: ruff |
196 | | -- **Type Checking**: mypy |
197 | | -- **Coverage**: Codecov Integration |
198 | | -- **Security**: bandit Scan |
199 | | - |
200 | | -## Projektstruktur |
201 | | - |
202 | | -``` |
203 | | -code-cloud-agents/ |
204 | | -├── .github/ |
205 | | -│ └── workflows/ |
206 | | -│ └── ci.yml # CI/CD Pipeline |
207 | | -├── agents/ |
208 | | -│ ├── agent_log_scorer.py # Haupt-Scoring-Logik |
209 | | -│ ├── agent_training_prompts.md # Training-Dokumentation |
210 | | -│ ├── flow_validator_checklist.yaml # Konfiguration |
211 | | -│ ├── sample_call_log.json # Beispiel-Log |
212 | | -│ └── supervisor_dashboard_mock.json |
213 | | -├── tests/ |
214 | | -│ ├── test_agent_log_scorer.py # Unit Tests |
215 | | -│ ├── scorecards/ # Test-Scorecards (Output) |
216 | | -│ └── test_input_logs/ # Test-Input-Logs |
217 | | -├── .pre-commit-config.yaml # Pre-commit Hooks |
218 | | -├── requirements.txt |
219 | | -└── README.md |
220 | | -``` |
221 | | - |
222 | | -## Klassen-Übersicht |
223 | | - |
224 | | -| Klasse | Beschreibung | |
225 | | -|--------|--------------| |
226 | | -| `AgentLogScorer` | Hauptklasse für Log-Bewertung | |
227 | | -| `ScoringConfig` | Konfiguration aus YAML laden | |
228 | | -| `ScoreResult` | Strukturiertes Bewertungsergebnis | |
229 | | -| `RiskLevel` | Enum für Risiko-Level | |
230 | | -| `AgentStatistics` | Performance-Statistiken pro Agent | |
231 | | -| `ReportGenerator` | Export in JSON/CSV/HTML | |
232 | | -| `DashboardGenerator` | Supervisor-Dashboard erstellen | |
233 | | -| `AlertSystem` | Warnungen bei kritischen Vorfällen | |
234 | | - |
235 | | -## CLI-Optionen |
236 | | - |
237 | | -``` |
238 | | -usage: agent_log_scorer.py [-h] [-c CONFIG] [-b] [-o OUTPUT] [--csv CSV] |
239 | | - [--html HTML] [--dashboard] [--stats] [-v] [--async] |
240 | | - [input] |
241 | | -
|
242 | | -positional arguments: |
243 | | - input Log-Datei oder Verzeichnis |
244 | | -
|
245 | | -optional arguments: |
246 | | - -h, --help Hilfe anzeigen |
247 | | - -c, --config CONFIG YAML-Konfigurationsdatei |
248 | | - -b, --batch Batch-Modus für Verzeichnisse |
249 | | - -o, --output OUTPUT JSON-Export Datei |
250 | | - --csv CSV CSV-Report exportieren |
251 | | - --html HTML HTML-Report exportieren |
252 | | - --dashboard Supervisor-Dashboard generieren |
253 | | - --stats Agent-Statistiken anzeigen |
254 | | - -v, --verbose Ausführliche Ausgabe |
255 | | - --async Asynchrone Verarbeitung |
| 38 | +python agents/agent_log_scorer.py --batch ./logs/ |
256 | 39 | ``` |
257 | 40 |
|
258 | | -## Exit-Codes |
259 | | - |
260 | | -| Code | Bedeutung | |
261 | | -|------|-----------| |
262 | | -| 0 | LOW Risk / Erfolg | |
263 | | -| 1 | MEDIUM Risk / Kritische Vorfälle | |
264 | | -| 2 | HIGH Risk | |
265 | | -| 3 | CRITICAL Risk | |
266 | | -| 4 | Datei nicht gefunden | |
267 | | -| 5 | Ungültiges JSON | |
268 | | -| 6 | Validierungsfehler | |
269 | | -| 99 | Unerwarteter Fehler | |
270 | | - |
271 | 41 | ## Lizenz |
272 | 42 |
|
273 | 43 | Proprietär - Step2Job GmbH |
0 commit comments