# Trixy Core API Documentation

Vollständige API-Referenz für das Trixy Core Framework.

## Module-Übersicht

| Modul | Beschreibung | Dokumentation |
|-------|--------------|---------------|
| `trixy_core.utils` | Utilities, Logging, Decorators, Validation | [utils.md](./utils.md) |
| `trixy_core.service` | Service Container, Lifecycle, Circuit Breaker | [service.md](./service.md) |
| `trixy_core.events` | Event-System, Middleware, Persistence | [events.md](./events.md) |
| `trixy_core.config` | Konfiguration, Secrets, Migration | [config.md](./config.md) |
| `trixy_core.network` | Protokoll, Verschlüsselung, TLS, Security, Retry, KeepAlive, Compression, RPC | [network.md](./network.md) |
| `trixy_core.satellite` | Satellite-Management, Load-Balancing, Capability Discovery, Metrics | [satellite.md](./satellite.md) |
| `trixy_core.plugins` | Plugin-System, Hooks, Hot-Reload | [plugins.md](./plugins.md) |
| `trixy_core.arbitration` | Wakeword-Arbitration, Multi-Satellite | [arbitration.md](./arbitration.md) |

## Architektur-Übersicht

```
┌─────────────────────────────────────────────────────────────────┐
│                     Application Layer                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Server    │  │   Client    │  │ Standalone  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│                      Plugin System                               │
│  ┌─────────┐  ┌──────────┐  ┌───────┐  ┌──────────┐            │
│  │ Hooks   │  │ Registry │  │ Deps  │  │ HotReload│            │
│  └─────────┘  └──────────┘  └───────┘  └──────────┘            │
├─────────────────────────────────────────────────────────────────┤
│                    Satellite Management                          │
│  ┌─────────┐  ┌──────────────┐  ┌──────────┐  ┌────────┐       │
│  │ Groups  │  │ LoadBalancing│  │ Failover │  │ Health │       │
│  └─────────┘  └──────────────┘  └──────────┘  └────────┘       │
│  ┌────────────┐  ┌─────────────┐                               │
│  │ Capability │  │   Metrics   │                               │
│  └────────────┘  └─────────────┘                               │
├─────────────────────────────────────────────────────────────────┤
│                       Event System                               │
│  ┌───────────┐  ┌────────────┐  ┌─────┐  ┌───────────┐         │
│  │ Middleware│  │ Persistence│  │ DLQ │  │ AsyncQueue│         │
│  └───────────┘  └────────────┘  └─────┘  └───────────┘         │
├─────────────────────────────────────────────────────────────────┤
│                      Service Layer                               │
│  ┌───────────┐  ┌───────────────┐  ┌─────────┐  ┌───────┐      │
│  │ Container │  │ CircuitBreaker│  │ Metrics │  │ Scopes│      │
│  └───────────┘  └───────────────┘  └─────────┘  └───────┘      │
├─────────────────────────────────────────────────────────────────┤
│                     Network & Config                             │
│  ┌──────────┐  ┌─────┐  ┌──────────┐  ┌─────────┐              │
│  │ Protocol │  │ TLS │  │ Security │  │ Config  │              │
│  └──────────┘  └─────┘  └──────────┘  └─────────┘              │
│  ┌───────┐  ┌───────────┐  ┌─────────────┐  ┌─────┐           │
│  │ Retry │  │ KeepAlive │  │ Compression │  │ RPC │           │
│  └───────┘  └───────────┘  └─────────────┘  └─────┘           │
├─────────────────────────────────────────────────────────────────┤
│                        Utilities                                 │
│  ┌─────────┐  ┌────────────┐  ┌────────────┐  ┌───────────┐    │
│  │ Logging │  │ Decorators │  │ Validation │  │ RateLimit │    │
│  └─────────┘  └────────────┘  └────────────┘  └───────────┘    │
└─────────────────────────────────────────────────────────────────┘
```

## Schnellstart

### Service erstellen

```python
from trixy_core.service import IService, ServicePriority, ServiceGroup

class MyService(IService):
    PRIORITY = ServicePriority.OPTIONAL
    GROUP = ServiceGroup.UTILITY
    DEPENDENCIES = ["event_manager"]

    async def on_start(self) -> None:
        self.logger.info("Service gestartet")

    async def on_stop(self) -> None:
        self.logger.info("Service gestoppt")
```

### Event-Handler registrieren

```python
from trixy_core.events import TrixyEvent, EventPriority

class MyPlugin:
    @TrixyEvent(["wakeword_received"])
    def on_wakeword(self, event_name: str, event_data: dict) -> None:
        satellite = event_data.get("satellite")
        print(f"Wakeword von {satellite}")

    @TrixyEvent(["speech_recognized"], priority=EventPriority.HIGH)
    async def on_speech(self, event_name: str, event_data: dict) -> None:
        text = event_data.get("text")
        await self.process_command(text)
```

### Plugin entwickeln

```python
from trixy_core.plugins import TrixyPlugin

class MyPlugin(TrixyPlugin):
    NAME = "my_plugin"
    VERSION = "1.0.0"
    DESCRIPTION = "Mein Plugin"

    async def on_start(self) -> None:
        config_value = self.config.get("setting", "default")
        self.application.event_manager.emit("plugin_ready", {"name": self.NAME})

    async def on_stop(self) -> None:
        pass
```

### Decorators verwenden

```python
from trixy_core.utils.decorators import timed, cached, retry, validate

@timed(name="api_call")
@retry(max_attempts=3, backoff=1.0)
async def fetch_data(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

@cached(ttl=300, max_size=100)
def get_user(user_id: int) -> User:
    return database.query(User).get(user_id)

@validate(name=str, age=(int, lambda x: x >= 0))
def create_user(name: str, age: int) -> User:
    return User(name=name, age=age)
```

## Konventionen

- **Sprache**: Alle Kommentare und Dokumentation auf Deutsch
- **Type Hints**: Python 3.10+ Features durchgehend
- **Async**: Async/await für I/O-Operationen
- **Dataclasses**: Für strukturierte Daten
- **Enums**: Für definierte Wertebereiche

## Versionierung

Die API folgt Semantic Versioning (SemVer):

- **Major**: Inkompatible API-Änderungen
- **Minor**: Abwärtskompatible Funktionalität
- **Patch**: Abwärtskompatible Bugfixes

Aktuelle Version: **1.0.0**