Metadata-Version: 2.4
Name: altruan-agenten
Version: 0.1.0
Summary: Schalter und Protokoll fuer die digitalen Mitarbeiter: Aufgaben zur Laufzeit an- und abschalten, Vorschlaege vermerken und ihre Trefferquote messen.
Home-page: https://github.com/Altruan-flows/altruan-agenten
Author: Altruan GmbH
Author-email: admin@altruan.de
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pymongo>=4.6
Provides-Extra: dev
Requires-Dist: twine>=4.0.2; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# altruan-agenten

Schalter und Protokoll fuer die digitalen Mitarbeiter. Zwei Bausteine, die jede
Persona braucht und die keine zweimal bauen sollte.

```
pip install altruan-agenten
```

Beide lesen genau eine Umgebungsvariable, `MONGODB_URI_AGENTEN`, und schreiben in
die Datenbank `agenten`. Ausser `pymongo` haengt nichts dran.

## schalter — eine Aufgabe an- und abschalten, ohne Deploy

Eine Konstante im Code umzulegen heisst: Codeaenderung, Review, Deploy. Fuer eine
Testphase, die schrittweise geoeffnet werden soll, ist das der falsche Takt. Hier
steht der Zustand in `agenten.schalter`, das Cockpit schreibt ihn, der naechste
Lauf liest ihn.

```python
from altruan_agenten import schalter

schalter.katalog_setzen(KATALOG)   # einmal beim Start

if not schalter.aktiv("BEN_MAIL_TRIAGE_AKTIV"):
    return
```

Der **Katalog gehoert in die Anwendung**, nicht in dieses Paket — er beschreibt
ihre Aufgaben im Klartext. Ein Eintrag braucht mindestens `_id`, `persona`,
`aufgabe` und `art` (`ART_AUFGABE` fuer einen eigenen Timer, `ART_TEILSCHRITT`
fuer einen Schritt darin, den man einzeln abstellen koennen will); dazu gehoeren
`titel`, `takt`, `wirkung` und `aus_bedeutet`, weil das Cockpit sie anzeigt.

Zwei Zusagen, an denen alles haengt:

- **Ein Deploy dreht keinen Schalter zurueck.** Die Registrierung ueberschreibt
  bei jedem Kaltstart die Beschreibung, aber nie den Zustand.
- **Faellt Mongo aus, aendert sich nichts.** Jeder Fehlerweg endet bei der
  gleichnamigen App Setting, nicht bei „aus". Eine laufende Persona haelt nicht
  an, eine abgeschaltete geht nicht scharf.

## protokoll — Idempotenz und Trefferquote in einem Datensatz

```python
from altruan_agenten import protokoll

neu = protokoll.vermerken(
    "sven", "delivery_date",
    {"system": "zendesk", "typ": "ticket", "id": str(ticket_id)},
    vorschlag={"antwort": text, "kategorie": kat},
    modell=MODELL, prompt_version="2026-09-05.1",
)
if not neu:
    return          # schon vermerkt — der Doppellauf kostet nichts weiter
```

**Vor** dem Schreiben ins Zielsystem aufrufen und bei `False` abbrechen. Der
Schluessel ist `<persona>|<aufgabe>|<quell-id>` und damit deterministisch; ein
zweiter Einfuegeversuch scheitert am Unique-Index.

Die Trefferquote faellt danach nebenbei ab: ein spaeterer Lauf ruft
`gegenprobe()` mit dem frisch gelesenen Ist-Stand, das Paket setzt
`uebernommen` oder `korrigiert`, und `quote()` rechnet sie je Auspraegung aus.
`promptVersion` ist Pflichtfeld — ohne sie sind zwei Quoten nicht vergleichbar.

## Veroeffentlichen

Version in `setup.py` hochzaehlen, auf `master` pushen. Der Workflow
`Upload to PyPi` baut und laedt hoch. PyPI weist eine bereits vorhandene Version
ab, das Hochzaehlen ist also Pflicht und nicht Geschmack.

## Tests

```
python -m unittest discover -s tests
```

34 Tests, keiner braucht eine Datenbank — die Collection ist nachgebaut.
