till/mana-swift-llm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mana-swift-llm/CLAUDE.md
till fd376bbdce L-1+L-2+L-3: mana-swift-llm Initial — lift aus memoro-native 
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>
2026-05-18 22:55:32 +02:00

4.3 KiB
Raw Permalink Blame History

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

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