# Portabilität: UNIVERSAL
# Zuletzt validiert: 2026-05-17
# Nächste Prüfung: 2027-05-17
# Quellen: [ARCHITECTURE.md, SKILL.md, core/, bach_api.py]

BACH ARCHITEKTUR (Personal Agentic OS)
======================================

DEFINITION
BACH ist ein hierarchisches System zur Orchestrierung von KI-Modellen.
Es sitzt als "Nervensystem" zwischen Infrastruktur (Compute) und Anwendung.

SCHICHTEN-MODELL
----------------

0. CORE LAYER (core/, bach_api.py)
   Registry-Based Auto-Discovery: Automatisches Laden aller Handler aus hub/
   App Container: Lightweight DI mit lazy-initialized DB + Registry
   Library-API: Programmatischer Zugriff ohne CLI (bach_api.py)
   Base Types: Result, ParsedArgs, OpDef - einheitliche Contracts

1. ORCHESTRATION LAYER (bach.py, Partner-System, Headless API)
   Koordiniert Multi-LLM Zusammenarbeit (Claude, Gemini, Ollama).
   Verwaltet Tasks, Rollen und Delegation via Message-System.
   REST-API: Port 8001 für programmatischen Zugriff (headless.py)

2. COGNITIVE MEMORY LAYER (memory_*, Consolidation-Engine)
   5 Memory-Typen (Working, Episodisch, Semantisch, Prozedural, Assoziativ).
   Aktive Konsolidierung (Decay, Boost, nächtliche Komprimierung).

3. LOGIC & SKILL LAYER (hub/, skills/, Hierarchy-JSON)
   60+ Auto-Discovered Handler (hub/) und dynamische Skills-Hierarchie.
   Das Skills Board (GUI) steuert die Zuweisung von Experten zu Agenten.
   Queue-Processor: hub/_services/connector/ für asynchrone Verarbeitung

4. EXECUTION LAYER (tools/)
   290+ spezialisierte Python-Scripts für Dateisystem, Steuer, Analyse etc.
   Standardisiertes Interface (c_ prefix) für AI-Kompatibilität.

5. DATA & PERSISTENCE (bach.db, data/logs/)
   SQLite-Grundlage mit 210+ Tabellen (Zentralisierte Datenhaltung).
   Tracking von Tokens, Sessions, Erfolg und Directory Truth.
   Logs konsolidiert in data/logs/ (system/logs/ DEPRECATED)

PROJEKTSTRUKTUR
---------------

system/
├── bach.py .................... CLI-Zentrale (Orchestrator)
├── bach_api.py ................ Library-API (Programmatischer Zugriff)
├── bach_legacy.py ............. Backup (vor Registry-Refactor)
├── core/ ...................... Foundation Layer
│   ├── base.py ................ Result, ParsedArgs, OpDef
│   ├── registry.py ............ Auto-Discovery + Command Routing
│   ├── app.py ................. App Container (DI)
│   ├── db.py .................. Database Wrapper
│   ├── adapter.py ............. Legacy Bridge
│   └── aliases.py ............. Command Aliases (mem -> memory)
├── data/
│   ├── bach.db ................ SQLite (210+ Tabellen) - "Das Gedächtnis"
│   └── logs/ .................. Konsolidierte Logs (NUR HIER)
├── db/
│   └── schema.sql ............. Single Source of Truth (DDL)
├── hub/ ....................... Handler-Module (Auto-Discovered)
│   ├── bach_paths.py .......... Pfad-Management (Governance)
│   └── _services/ ............. Hintergrund-Services
│       ├── connector/ ......... Queue-Processor (async)
│       └── document/ .......... Report-Workflows
├── tools/ ..................... Python-Scripts (290+ Werkzeuge)
├── docs/help/ ...................... Hilfe-System (.txt)
├── agents/ ............ Agenten-Profile (Rollen)
├── partners/ .......... LLM-Konfigurationen (KONSOLIDIERT)
├── docs/ ...................... Dokumentation & Konzepte
├── gui/ ....................... Web-Dashboard (FastAPI)
│   └── api/ ................... REST-APIs
│       ├── headless.py ........ Port 8001 (Pure JSON API)
│       └── messages_api.py .... Message-Router
└── user/ ...................... User-Daten & Exporte

ARCHITEKTUR-DIAGRAMM (Registry v2.0)
------------------------------------

┌─────────────────────────────────────────────────────────────────┐
│ ZUGRIFFS-LAYER                                                  │
├───────────────────┬─────────────────────┬───────────────────────┤
│ CLI (bach.py)     │ Library (bach_api)  │ REST (headless.py)    │
│ sys.argv routing  │ Direct function     │ Port 8001 JSON API    │
└───────────────────┴─────────────────────┴───────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ CORE LAYER (core/)                                              │
├───────────────────┬─────────────────────┬───────────────────────┤
│ App Container     │ HandlerRegistry     │ Database (db.py)      │
│ DI + Lazy Init    │ Auto-Discovery      │ Schema + Migrations   │
└───────────────────┴─────────────────────┴───────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ HANDLER LAYER (hub/)                                            │
│ 60+ BaseHandler Subklassen - Automatisch Registriert           │
├───────────────────┬─────────────────────┬───────────────────────┤
│ task.py           │ memory.py           │ partner.py            │
│ steuer.py         │ backup.py           │ lesson.py             │
│ ...               │ ...                 │ ...                   │
└───────────────────┴─────────────────────┴───────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ SERVICE LAYER (hub/_services/)                                  │
├───────────────────┬─────────────────────┬───────────────────────┤
│ connector/        │ document/           │ daemon/               │
│ Queue-Processor   │ Report-Workflows    │ Background Tasks      │
└───────────────────┴─────────────────────┴───────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ EXECUTION LAYER (tools/)                                        │
│ 290+ Python-Scripts mit standardisiertem c_ Interface          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ PERSISTENCE LAYER                                               │
├───────────────────┬─────────────────────┬───────────────────────┤
│ bach.db           │ data/logs/          │ user/                 │
│ 210+ Tabellen     │ Konsolidierte Logs  │ Exports & Berichte    │
└───────────────────┴─────────────────────┴───────────────────────┘

CORE KONZEPTE
-------------

* REGISTRY-BASED: Auto-Discovery statt hardcodierter Handler-Map.
  Neue Handler brauchen NUR eine Datei in hub/ (keine Registrierung).

* DUAL-ACCESS: CLI (python bach.py task list) UND Library-API (bach_api.task.list()).
  Beide nutzen dieselben Handler + DB - Zero Overhead.

* MULTI-PARTNER: Nicht ein Agent, sondern ein Netzwerk mit specialized roles.

* KOGNITIVES GEDÄCHTNIS: Informationen werden nicht nur gespeichert, sondern
  aktiv gewichtet und "verdaut" (Konsolidierung).

* PORTABLE & LOKAL: Das gesamte System ist in einem Ordner gekapselt und
  funktioniert ohne Cloud-Zwang (z.B. mit Ollama).

* SELF-HEALING: Automatische Korrektur von Pfaden und Registry-Einträgen.

* HEADLESS API: REST-Interface auf Port 8001 für externe Integration
  (getrennt vom GUI-Server Port 8000).

SIEHE AUCH
----------
docs/help/bach_info.txt       Was ist BACH?
docs/help/memory.txt          Das Gedaechtnis-System
docs/help/partner.txt         Zusammenarbeit der KIs
wiki/was_ist_bach.txt  Ausführliche Synopse
