# CLAUDE.md — mana-swift-llm

Guidance für Claude Code in diesem Repo.

> **Plattform-SOT:** [`../mana/docs/MANA_LLM.md`](../mana/docs/MANA_LLM.md)
> ist die übergreifende Architektur-Doku. Dieses CLAUDE.md ist die
> Repo-lokale Konventions-Doku.

## Was dieses Repo ist

Swift-Package mit lokalen LLM-Backends für alle nativen mana-e.V.-
Apps. Zwei Library-Products:

- **ManaLLM** — Backend-Abstraktion (FoundationModels, Gemma 4,
  Router) + High-Level-API (`ManaLLM.summarize`, `.classify`,
  `.generate`). Bringt MLX-Swift-LM-Toolchain mit (~30 MB Dep).
- **ManaLLMShared** — App-Group-Container-Helper für gemeinsamen
  HuggingFace-Cache. Schmale Lib ohne MLX-Dep — Apps die nur den
  Container brauchen (z.B. für ein anderes Modell-Setup) konsumieren
  nur das.

Konsumenten heute: `memoro-native`. Geplant: alle 12 native mana-Apps
(siehe Use-Case-Map in `MANA_LLM.md`).

## Architektur-Invarianten

Beschlossen. Nicht ohne explizite Diskussion antasten.

1. **Eigenes Repo statt ManaCore-Erweiterung.** `mana-swift-core`
   bleibt schlank (Architektur-Invariante "genau zwei Products" —
   ManaCore + ManaTokens). LLM-Toolchain ist schwer und hat eigenen
   Versions-Lifecycle (MLX-Swift updates häufig).
2. **MLX-Swift, kein anderer LLM-Stack.** Apple-optimierte Inferenz
   auf Apple Silicon (ANE + GPU + CPU). Keine llama.cpp-Forks, keine
   eigene Python-Bridge, keine ONNX-Runtime.
3. **Foundation Models bevorzugt.** Apple's System-Modell ist
   shared-by-OS, gratis, ANE-accelerated. Apps nutzen FM wo immer
   Capability reicht; Gemma nur wenn FM nicht reicht.
4. **Public API ist `Sendable`.** Swift-6-Strict-Concurrency.
5. **Keine PII in Logs.** OSLog-Subsystem `ev.mana.llm`, alle
   Transcripts/Prompts mit `privacy: .private` markiert. Compliance
   ([`mana/docs/COMPLIANCE.md`](../mana/docs/COMPLIANCE.md)) gilt.

## Konventionen

- **Swift 6.0** strict concurrency
- **iOS 18 / macOS 15** Minimum (für FoundationModels: iOS 26+ —
  ManaLLM checked Availability zur Runtime)
- **MLX-Swift-LM** über `branch: main` (kein stabiler Tag bis MLX
  v1.0 — pin auf branch ist die de-facto-Konvention)
- **Doc-Comments** pflicht auf jedem `public`-Symbol (`///`)

## Versionierung

- Semver mit häufigen Patch-Releases (MLX-Swift bewegt sich)
- Git-Tags nach jedem Sinn-Abschnitt auf `main`
- CHANGELOG.md pflicht — was hat sich geändert, was müssen Apps anpassen

## Lokal entwickeln

```bash
swift build                                # baut beide Targets
swift test                                 # Tests (FM gated auf macOS 15+)
```

Für Integration in eine App (memoro-native, später pageta, etc.):

```yaml
# project.yml
packages:
  ManaLLM:
    path: ../mana-swift-llm                # dev — direktes Path-Dep
    # url: https://git.mana.how/till/mana-swift-llm.git
    # from: "0.1.0"

targets:
  YourApp:
    dependencies:
      - package: ManaLLM
        product: ManaLLM
      - package: ManaLLM
        product: ManaLLMShared
```

## Cross-Repo-Doks

- [`../mana/docs/MANA_LLM.md`](../mana/docs/MANA_LLM.md) —
  Plattform-SOT
- [`../mana/docs/MANA_SWIFT.md`](../mana/docs/MANA_SWIFT.md) —
  Native-Plattform-SOT
- [`../mana/docs/COMPLIANCE.md`](../mana/docs/COMPLIANCE.md) —
  Datenschutz / Telemetrie-Regeln
- [`../mana-swift-core/CLAUDE.md`](../mana-swift-core/CLAUDE.md) —
  Schwester-Package
- [`../memoro-native/Sources/Core/AI/`](../memoro-native/Sources/Core/AI/)
  — Quell-Code-Ursprung (vor Lift)

## Lift-Herkunft

Quelle: `memoro-native/Sources/Core/AI/` (2026-05-18). Files
übernommen + generalisiert:

| Original | Hier | Anpassung |
|---|---|---|
| `LLMBackend.swift` | `Sources/ManaLLM/LLMBackend.swift` | + generische `generate(prompt:maxTokens:)`-Methode, `summarize` als Default-Impl |
| `LLMBackendID.swift` | `Sources/ManaLLM/LLMBackend.swift` | inline |
| `AppleFMBackend.swift` | `Sources/ManaLLM/AppleFMBackend.swift` | identisch |
| `GemmaBackend.swift` | `Sources/ManaLLM/GemmaBackend.swift` | `huggingFaceCacheRoot()` nutzt `ManaSharedModels` |
| `LLMRouter.swift` | `Sources/ManaLLM/LLMRouter.swift` | Memoro-User-Pref-Logic durch capability-basiertes Routing ersetzt |
| `NoOpLLMBackend.swift` | `Sources/ManaLLM/NoOpBackend.swift` | umbenannt, identisch |

Neu hier (nicht aus memoro):
- `ManaLLMShared/ManaSharedModels.swift` — App-Group-Container-Helper
- `ManaLLM/ManaLLM.swift` — High-Level Facade API