# APIs und Interfaces

**Revision:** r1
**Source:** CLAUDE.md, Code-Analyse
**Last updated:** 2026-01-31 12:35

---

## IService Interface

```python
class IService(ABC):
    # Klassenattribute
    PRIORITY: ClassVar[ServicePriority] = ServicePriority.OPTIONAL
    GROUP: ClassVar[ServiceGroup] = ServiceGroup.UTILITY
    DEPENDENCIES: ClassVar[list[str]] = []
    NAME: ClassVar[str] = ""

    # Properties
    @property
    def application(self) -> IApplication
    @property
    def state(self) -> ServiceState
    @property
    def name(self) -> str
    @property
    def is_running(self) -> bool

    # Lifecycle Hooks (überschreibbar)
    async def on_pre_start(self) -> None
    async def on_post_start(self) -> None
    async def on_pre_stop(self) -> None
    async def on_post_stop(self) -> None
    async def on_dependency_ready(self, dependency_name: str) -> None

    # Abstrakte Methoden (müssen implementiert werden)
    @abstractmethod
    async def start(self) -> None
    @abstractmethod
    async def stop(self) -> None

    # Optional
    async def health_check(self) -> bool
```

## Event-System API

### EventManager

```python
class EventManager:
    def register(event_name: str, callback: Callable, priority: EventPriority) -> None
    def register_global(callback: Callable, priority: EventPriority) -> None
    def unregister(event_name: str, callback: Callable) -> bool
    def register_object(obj: Any) -> None  # Findet @TrixyEvent Methoden
    def unregister_object(obj: Any) -> int

    async def trigger(event_name: str, event_data: EventData) -> EventData
    def trigger_sync(event_name: str, event_data: EventData) -> EventData

    def has_handlers(event_name: str) -> bool
    def get_registered_events() -> list[str]
    def clear_all() -> None
```

### Event-Dekoratoren

```python
@TrixyEvent(["event1", "event2"], priority=EventPriority.NORMAL)
def on_events(self, event_name: str, event_data: EventData):
    pass

@event_handler(WakewordReceived, priority=EventPriority.HIGH)
async def on_wakeword(self, event: WakewordReceived):
    pass
```

### Standard-Events

| Event-Klasse | event_name() | Beschreibung |
|--------------|--------------|--------------|
| SatelliteConnected | satellite_connected | Satellite verbunden |
| SatelliteDisconnected | satellite_disconnected | Satellite getrennt |
| WakewordReceived | wakeword_received | Wakeword erkannt |
| RawAudioInputReceived | raw_audio_input_received | Audio empfangen |
| SpeechRecognized | speech_recognized | STT-Ergebnis |
| IntentReceived | intent_received | Intent erkannt |
| ConversationStarted | conversation_started | Konversation gestartet |
| ConversationEnded | conversation_ended | Konversation beendet |
| PluginLoaded | plugin_loaded | Plugin geladen |
| SystemShutdown | system_shutdown | System fährt herunter |

## ServiceContainer API

```python
class ServiceContainer:
    def register(service_class: type[T]) -> T
    def register_instance(service: IService) -> None
    def get_service(name: str) -> IService | None
    def get_service_typed(name: str, service_type: type[T]) -> T | None

    # Index-Zugriff
    container["ServiceName"]  # Nach Name
    container[ServiceClass]   # Nach Klasse
    "ServiceName" in container  # Prüfen

    async def start_all() -> None
    async def stop_all() -> None
    async def restart_service(name: str) -> None
```

## TrixyPlugin API

```python
class TrixyPlugin(ABC):
    NAME: str
    VERSION: str
    DESCRIPTION: str
    AUTHOR: str

    @property
    def application(self) -> IApplication
    @property
    def config(self) -> dict[str, Any]
    @property
    def enabled(self) -> bool

    def get_config_value(key: str, default: Any = None) -> Any
    def set_config_value(key: str, value: Any) -> None
    def reload_config() -> bool
    def save_config() -> bool

    @abstractmethod
    async def on_load(self) -> None
    @abstractmethod
    async def on_unload(self) -> None
    async def on_enable(self) -> None
    async def on_disable(self) -> None
```

---

**See also:** [modules.md](modules.md), [integrations.md](integrations.md)