till
fd376bbdce
Neues Swift-Package mit lokalen LLM-Backends für alle nativen mana- e.V.-Apps. Lift der bisher Memoro-eigenen Files in `memoro-native/Sources/Core/AI/` plus zwei neue Layer: ManaSharedModels (App-Group-Container-Helper) und ManaLLM-Facade. Library-Products: - ManaLLM — Backend-Abstraktion (FoundationModels, Gemma 4 E2B/E4B, NoOp), Router mit Priority-Liste, High-Level-Facade `ManaLLM.summarize/generate/classify` mit fast/creative/deep Level. - ManaLLMShared — App-Group `group.ev.mana.models` Container, HF_HUB_CACHE-Setup, Legacy-Fallback wenn Group fehlt. Lift-Anpassungen ggü. memoro: - public-Marker auf protocol + types + actors - generischer `generate(prompt:instructions:maxTokens:)` zu LLMBackend-Protocol hinzu; `summarize` als Default-Impl auf Basis von generate - AppleFMBackend behält optimierten @Generable-Summary-Path - GemmaBackend nutzt ManaSharedModels.effectiveCacheURL() statt eigenen Application-Support-Pfad; allowsCellular kommt jetzt als Initializer-Param statt App-Settings-Lookup - LLMRouter: Memoro-spezifische User-Pref-Store-Logic durch Priority-Liste-API ersetzt - LLMLog-Subsystem `ev.mana.llm` statt App-eigenes `Log.ai` Build: `swift build` clean (76s, MLX-Toolchain-Resolution beim ersten Lauf). 4/4 Parser-Tests grün. Doku: ../mana/docs/MANA_LLM.md (Plattform-SOT), CLAUDE.md (Konventionen + Lift-Tabelle). Folge: L-4 Memoro auf ManaLLM umstellen, L-5 pageta-Pilot. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
114 lines
4.3 KiB
Markdown
114 lines
4.3 KiB
Markdown
# 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
|