mana-swift-llm/CLAUDE.md

CLAUDE.md — mana-swift-llm

Guidance für Claude Code in diesem Repo.

Plattform-SOT: ../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- 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) 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

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.):

# 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 — Plattform-SOT
• ../mana/docs/MANA_SWIFT.md — Native-Plattform-SOT
• ../mana/docs/COMPLIANCE.md — Datenschutz / Telemetrie-Regeln
• ../mana-swift-core/CLAUDE.md — Schwester-Package
• ../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