Skip to content

Commit 20bd394

Browse files
committed
Refactor agent log scorer with comprehensive improvements
- Fix critical bugs: add missing sample_call_log.json, implement error handling and input validation, remove unused datetime import - Add YAML config loader to use flow_validator_checklist.yaml - Implement risk level mapping (LOW/MEDIUM/HIGH/CRITICAL) matching supervisor dashboard expectations - Include placeholder_used in risk calculation formula - Extend keyword lists for price and legal detection (German/multi-currency) - Add comprehensive pytest test suite with 33 tests covering all edge cases - Add requirements.txt with PyYAML and pytest dependencies - Expand README with installation, usage, API docs, and examples - Fix YAML parsing issue with quoted strings
1 parent 21922a5 commit 20bd394

7 files changed

Lines changed: 905 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 181 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,183 @@
11
# Step2Job Cloud Agents
22

3-
Deployment-Template für Supervisor-KI, Log-Auswertung und Dashboard.
3+
Deployment-Template für Supervisor-KI, Log-Auswertung und Dashboard.
4+
5+
## Überblick
6+
7+
Dieses System analysiert Agent-Logs auf potenzielle Risiken und stellt sicher, dass KI-Agenten:
8+
- Keine unerlaubten Preisaussagen machen
9+
- Keine rechtlichen Behauptungen ohne Faktengrundlage aufstellen
10+
- STOP-Mechanismen bei kritischen Fragen korrekt auslösen
11+
- PLACEHOLDER für unbestätigte Informationen verwenden
12+
13+
## Installation
14+
15+
```bash
16+
# Repository klonen
17+
git clone <repository-url>
18+
cd code-cloud-agents
19+
20+
# Abhängigkeiten installieren
21+
pip install -r requirements.txt
22+
```
23+
24+
## Verwendung
25+
26+
### Kommandozeile
27+
28+
```bash
29+
# Standard-Beispiel ausführen
30+
python agents/agent_log_scorer.py
31+
32+
# Eigene Log-Datei analysieren
33+
python agents/agent_log_scorer.py path/to/log.json
34+
35+
# Mit eigener Konfiguration
36+
python agents/agent_log_scorer.py log.json -c config.yaml
37+
38+
# Ausführliche Ausgabe
39+
python agents/agent_log_scorer.py log.json -v
40+
```
41+
42+
### Als Modul
43+
44+
```python
45+
from agents.agent_log_scorer import score_agent_log, load_config
46+
47+
# Log analysieren
48+
log_data = {
49+
"agent_id": "AGENT_001",
50+
"contact_name": "Max Mustermann",
51+
"transcript": [
52+
{"speaker": "customer", "text": "Was kostet das?"},
53+
{"speaker": "agent", "text": "Das kläre ich intern."}
54+
],
55+
"stop_triggered": True,
56+
"result": "STOP_REQUIRED"
57+
}
58+
59+
result = score_agent_log(log_data)
60+
print(f"Risk Level: {result['risk_level']}")
61+
```
62+
63+
## Log-Format
64+
65+
Eingabe-Logs müssen folgendes Format haben:
66+
67+
```json
68+
{
69+
"agent_id": "AGENT_001", // Pflichtfeld
70+
"contact_name": "Max Mustermann",
71+
"timestamp": "2025-12-23T10:30:00",
72+
"transcript": [
73+
{"speaker": "customer", "text": "Nachricht des Kunden"},
74+
{"speaker": "agent", "text": "Antwort des Agenten"}
75+
],
76+
"stop_triggered": true,
77+
"result": "STOP_REQUIRED - Preisfrage erkannt"
78+
}
79+
```
80+
81+
## Ausgabe-Format
82+
83+
```json
84+
{
85+
"agent_id": "AGENT_001",
86+
"contact": "Max Mustermann",
87+
"timestamp": "2025-12-23T10:30:00",
88+
"price_claim": true,
89+
"price_keywords_found": ["kostet"],
90+
"legal_claim": false,
91+
"legal_keywords_found": [],
92+
"stop_triggered": true,
93+
"placeholder_used": true,
94+
"risk": 0,
95+
"risk_level": "LOW"
96+
}
97+
```
98+
99+
## Risk-Level
100+
101+
| Level | Score | Bedeutung |
102+
|-------|-------|-----------|
103+
| LOW | 0 | Kein Risiko erkannt |
104+
| MEDIUM | 1 | Geringes Risiko, Überprüfung empfohlen |
105+
| HIGH | 2 | Hohes Risiko, Aktion erforderlich |
106+
| CRITICAL | 3+ | Kritisch, sofortige Intervention |
107+
108+
## Risiko-Berechnung
109+
110+
```
111+
Risk = price_claim(+1) + legal_claim(+1) - stop_triggered(-1) - placeholder_bonus(-1)
112+
```
113+
114+
- **+1** für jede Preis- oder Rechtsbehauptung
115+
- **-1** wenn STOP korrekt ausgelöst wurde
116+
- **-1** wenn PLACEHOLDER bei Claims verwendet wurde
117+
118+
## Konfiguration
119+
120+
Die Keyword-Listen und Schwellwerte können in `agents/flow_validator_checklist.yaml` angepasst werden:
121+
122+
```yaml
123+
keywords:
124+
price:
125+
- "€"
126+
- "euro"
127+
- "preis"
128+
# ... weitere Keywords
129+
130+
legal:
131+
- "gesetz"
132+
- "rechtlich"
133+
# ... weitere Keywords
134+
135+
risk_thresholds:
136+
low: 0
137+
medium: 1
138+
high: 2
139+
```
140+
141+
## Tests
142+
143+
```bash
144+
# Alle Tests ausführen
145+
pytest tests/ -v
146+
147+
# Mit Coverage-Report
148+
pytest tests/ --cov=agents --cov-report=html
149+
```
150+
151+
## Projektstruktur
152+
153+
```
154+
code-cloud-agents/
155+
├── agents/
156+
│ ├── agent_log_scorer.py # Haupt-Scoring-Logik
157+
│ ├── agent_training_prompts.md # Training-Dokumentation
158+
│ ├── flow_validator_checklist.yaml # Konfiguration & Regeln
159+
│ ├── sample_call_log.json # Beispiel-Log
160+
│ └── supervisor_dashboard_mock.json
161+
├── tests/
162+
│ ├── test_agent_log_scorer.py # Unit Tests
163+
│ └── scorecards/ # Test-Scorecards
164+
├── requirements.txt
165+
└── README.md
166+
```
167+
168+
## Exit-Codes
169+
170+
| Code | Bedeutung |
171+
|------|-----------|
172+
| 0 | LOW Risk |
173+
| 1 | MEDIUM Risk |
174+
| 2 | HIGH Risk |
175+
| 3 | CRITICAL Risk |
176+
| 4 | Datei nicht gefunden |
177+
| 5 | Ungültiges JSON |
178+
| 6 | Validierungsfehler |
179+
| 99 | Unerwarteter Fehler |
180+
181+
## Lizenz
182+
183+
Proprietär - Step2Job GmbH

0 commit comments

Comments
 (0)