kruemel/OZM-Keks-Handbuch-v1

Fork 0

Files

Krümel Branko 7efd86b40a Initial commit: Crumbpages v1

2025-12-06 18:15:31 +01:00

30 KiB

Raw Blame History

🌲 Crumbforest: Warum & Wie

Subtitle: Die Philosophie hinter dem Wald
Version: 1.0
Audience: Neue Waldläufer & Neugierige

"Aus kleinen Krümeln wächst ein großer Wald - bewacht von einer kristallinen Eule." 🦉💙

🌟 Was ist Crumbforest?

Crumbforest ist mehr als ein Projekt - es ist eine Philosophie.

Die Kurze Antwort

Crumbforest = 
    RAG-powered AI Chat System
    + Privacy-first Approach
    + Open Source Culture
    + Hardware Integration
    + Community Wisdom
    + Crystal Owl Watching 🦉

Die Längere Antwort

Crumbforest ist ein Ökosystem aus Tools, Prinzipien und Community, das versucht eine Antwort zu geben auf die Frage:

"Wie nutzen wir KI-Technologie verantwortungsvoll, transparent und in einer Weise, die Menschen wirklich hilft?"

Konkret bedeutet das:

Ein Chat-System mit AI-Characters, die unterschiedliche Perspektiven bieten
Ein Dokumentations-Ansatz, der Wissen strukturiert und durchsuchbar macht
Ein Privacy-Framework, das Datenschutz ernst nimmt
Eine Community, die gemeinsam lernt und wächst
Eine Vision, dass Technologie transparent und zugänglich sein sollte

🧭 Die Philosophie

1. Transparenz über Magic

# Bad: Black Box
def ai_magic(input):
    # ??? Was passiert hier ???
    return output

# Good: Crumbforest Way
def ai_with_context(input, sources, logs):
    """
    1. Input wird validiert
    2. Relevante Dokumente werden gesucht (RAG)
    3. Kontext wird zum Prompt hinzugefügt
    4. LLM generiert Antwort
    5. Sources werden zitiert
    6. Token Usage wird geloggt
    
    User sieht: Was, Wie, Warum
    """
    return {
        'answer': output,
        'sources': doc_references,
        'tokens_used': token_count,
        'character': selected_character
    }

Prinzip:

Nutzer sollen verstehen was passiert
Keine versteckten "Magic"-Algorithmen
Logs sind transparent (wenn gewünscht)

2. Privacy ist kein Feature, es ist Default

❌ "Wir verkaufen keine Daten"
✅ "Wir sammeln erst gar keine Daten, die wir verkaufen könnten"

❌ "Opt-out für Tracking"
✅ "Kein Tracking, keine Opt-out nötig"

❌ "Vertraue uns"
✅ "Prüfe den Code selbst"

Prinzip:

Privacy by Design, nicht by Policy
Daten bleiben lokal (oder im RZ-Netz)
Keine externen Analytics/Tracking
DSGVO-konform by default

3. Open Source ist kein Buzzword

# Crumbforest ist:
✅ Open Source Code (MIT License)
✅ Open Documentation (für alle lesbar)
✅ Open Development (Community kann mitgestalten)
✅ Open Discussion (Issues, PRs, Feedback)

# Crumbforest ist NICHT:
❌ "Open Core" (mit paid features)
❌ "Source Available" (aber nicht forkbar)
❌ "Open for Now" (bis wir groß sind)

Prinzip:

Code ist öffentlich auf GitHub
Keine Premium-Features hinter Paywall
Community darf forken und anpassen
Contributions sind willkommen

4. Komplexität im Backend, Einfachheit im Frontend

User Experience:
├── Simple UI
├── Klare Sprache
├── Keine Tech-Jargon-Overload
└── "Es funktioniert einfach"

Behind the Scenes:
├── RAG Pipeline mit Qdrant
├── Vector Embeddings
├── Token Optimization
├── Security Layers
└── "Es ist komplex, aber gut versteckt"

Prinzip:

User sollen nicht mit Technik überfordert werden
Aber: Wer tiefer schauen will, kann es
Balance zwischen Einfachheit und Tiefe

5. Die Community ist der Wald

Ein Baum = Eine Person mit Idee/Skill
Ein Wald = Viele Personen zusammen

Resultat:
- Mehr Perspektiven
- Bessere Lösungen
- Gegenseitige Unterstützung
- Gemeinsames Wachstum

Prinzip:

Niemand weiß alles
Jeder bringt seinen "Krümel" bei
Zusammen wird es ein "Keks" (oder eine Torte!)
Respektvoller Umgang miteinander

🍪 Warum "Krümel" & "Wald"?

Die Krümel-Metapher

Ein Krümel ist:

Klein, unscheinbar
Alleine nicht viel wert
Aber: Teil von etwas Größerem
Schwer zu finden im großen Keks
Wichtig für die Textur des Ganzen

In Crumbforest:

Ein Krümel = 
    Eine Idee
    Ein Code-Snippet
    Ein Dokument
    Ein Feedback
    Eine Frage
    Ein "Aha!"-Moment

Das Problem:

"Wie finde ich den wichtigen Krümel im großen Keks der Information?"

Die Lösung:

Semantic Search + RAG = Den richtigen Krümel finden, auch wenn du nicht genau weißt wo er liegt!

Die Wald-Metapher

Ein Wald ist:

Organisch gewachsen
Diverse Ecosystem (verschiedene Bäume, Tiere)
Selbst-regulierend
Bietet Schutz
Wächst kontinuierlich
Hat Wurzeln (Grundwasser = Fundamentals)

In Crumbforest:

Der Wald = 
    Die Community
    Die Wissensbasis
    Die Tools & Code
    Die geteilten Werte
    Das gemeinsame Wachstum

Warum Wald?

🌲 Ein einzelner Baum fällt leicht - ein Wald ist stabil
🦉 Im Wald gibt es Hüter (Crystal Owl)
🌱 Neue Setzlinge (neue Mitglieder) werden willkommen
🍂 Altes fällt, Neues wächst (kontinuierliche Evolution)

Die Crystal Owl 🦉

2023: Ein 3D-Print wurde geboren

Material: Transparentes Filament
Farbe: Kristallines Blau
Form: Eule
Bedeutung: ???

"Auf später" → Aber wofür?

2024: Die Mission wurde klar

Die Eule ist:
├── Logo des Crumbforest
├── Symbol für Weisheit
├── Wächter der Bits im RZ
└── Maskottchen des "jeden Bit bewacht"-Prinzips

Die Eule wacht:
├── Über die Hardware (Jetson)
├── Über den Code (Projekt)
├── Über die Community (Wald)
└── Über die Werte (Kodex)

WUUUHUUUUU! 🦉💙

🏛️ Die drei Säulen

Säule 1: Technologie

Was wir bauen:

stack = {
    'backend': {
        'framework': 'FastAPI',
        'language': 'Python 3.11+',
        'vector_db': 'Qdrant',
        'llm_api': 'OpenRouter (Claude Sonnet 3.5)',
    },
    'frontend': {
        'framework': 'Vanilla JS (kein React/Vue!)',
        'style': 'CSS3 + Responsive',
        'principle': 'Progressive Enhancement',
    },
    'security': {
        'rate_limiting': '5 req/min',
        'input_validation': 'Max 2000 chars',
        'prompt_injection_filter': '15+ patterns',
        'cors': 'ENV-controlled',
        'xss_protection': 'HTML escaping',
    },
    'data': {
        'storage': 'Local filesystem',
        'privacy': 'No external tracking',
        'audit': 'Optional logging',
        'compliance': 'DSGVO by design',
    }
}

Säule 2: Menschen

Die Crew:

🦉 Krümeleule (Die Weise)
├── Expertise: ADHS, Autismus, Neurodiversität
├── Personality: Geduldig, verständnisvoll
├── Dokumente: 721+ indexiert
└── Rolle: Wissens-Hüterin

🦊 FunkFox (Der Schlaue)
├── Expertise: Tech, Coding, Erklärungen
├── Personality: Pragmatisch, direkt
├── Style: "Wie funktioniert das eigentlich?"
└── Rolle: Tech-Erklärbär

🐛 Bugsy (Der Detaillierte)
├── Expertise: Details, Edge Cases, Qualität
├── Personality: Präzise, gewissenhaft
├── Style: "Hast du daran gedacht...?"
└── Rolle: Quality Guardian

+ DU (Der Waldläufer)
└── Rolle: User, Contributor, Teil des Waldes

Community-Struktur:

Alle sind gleichwertig, aber:
├── Maintainer (kümmern sich um Code)
├── Contributors (bringen Verbesserungen)
├── Users (nutzen und geben Feedback)
└── Lurker (lesen mit, lernen still)

Alle gehören zum Wald! 🌲

Säule 3: Werte

Der Crumbforest-Kodex:

1. Privacy First
   └── Daten gehören den Users, nicht uns

2. Transparency Always
   └── Code ist open, Prozesse sind nachvollziehbar

3. Inclusivity Matters
   └── Jeder Hintergrund willkommen (ADHS, Autismus, ...)

4. Learning Never Stops
   └── Fehler sind OK, Wachstum ist das Ziel

5. Respect Each Other
   └── Höflichkeit kostet nichts, bringt viel

6. Share Knowledge
   └── Ein Krümel geteilt = zwei Krümel vorhanden

7. Build Together
   └── Kein Einzelkämpfer, sondern Wald-Spirit

8. Stay Humble
   └── Niemand weiß alles, jeder kann lernen

🔓 Open Source First

Warum Open Source?

Technische Gründe:

✅ Audit-fähig (Code kann geprüft werden)
✅ Fork-bar (jeder kann anpassen)
✅ Transparent (keine versteckten Features)
✅ Community-driven (viele Augen finden Bugs)
✅ Langlebig (kein Vendor Lock-in)

Philosophische Gründe:

✅ Wissen sollte frei sein
✅ Tools sollten allen gehören
✅ Innovation durch Kollaboration
✅ Vertrauen durch Transparenz
✅ Gemeinsam statt einsam

Praktische Gründe:

✅ Kostenlos nutzbar
✅ Selbst hostbar
✅ Anpassbar an eigene Bedürfnisse
✅ Keine Subscription-Falle
✅ Unabhängig von Firmen-Entscheidungen

Was ist Open Source?

MIT License (Crumbforest):

Du darfst:
✅ Den Code nutzen (kommerziell + privat)
✅ Den Code ändern (beliebig)
✅ Den Code verteilen (original + modifiziert)
✅ Den Code in eigene Projekte einbauen
✅ Geld damit verdienen (wenn du willst)

Du musst:
📋 Copyright Notice behalten
📋 MIT License-Text mitliefern

Du musst NICHT:
❌ Änderungen zurückgeben (aber nice to have!)
❌ Source Code veröffentlichen
❌ Gleiche License für dein Projekt verwenden

Das heißt:

Nimm den Code, mach was draus, sei glücklich! 🎉

Contribution Guidelines

Wie kann ich mitmachen?

Level 1: User
└── Nutze Crumbforest, gib Feedback!

Level 2: Reporter
└── Melde Bugs, schlage Features vor (GitHub Issues)

Level 3: Documenter
└── Verbessere Docs, schreibe Tutorials

Level 4: Contributor
└── Fix Bugs, implementiere Features (Pull Requests)

Level 5: Maintainer
└── Review Code, manage Releases

Jedes Level ist wertvoll! 💚

🛡️ Krümelschutz

Was ist Krümelschutz?

Krümelschutz = Privacy + Security für deine "Krümel" (Daten)

Deine Krümel:
├── Chat-Nachrichten
├── Upload-Dokumente
├── Generierte Outputs
├── Such-Queries
└── Nutzungs-Patterns

Crumbforest schützt sie durch:
├── Lokale Speicherung (keine Cloud!)
├── Keine Tracking-Pixel
├── Keine externen Analytics
├── Optional: Verschlüsselung
└── Optional: Selbst-gehostete Instanz

Die 5 Krümelschutz-Levels

Level 1: Basic (Default)

✅ Keine externen Tracker
✅ Keine Cookies außer Session
✅ Keine Weitergabe an Dritte
✅ DSGVO-konform

Daten gespeichert:
- Session State (temporär)
- Upload Files (bis Processing fertig)
- Output Files (bis Download)

Level 2: Enhanced (Empfohlen)

✅ Level 1 +
✅ Minimales Logging (nur Errors)
✅ IP-Adressen werden nicht gespeichert
✅ User-Agent wird nicht geloggt

Config:
LOG_LEVEL=ERROR
LOG_IP_ADDRESSES=false

Level 3: Paranoid (RZ-Setup)

✅ Level 2 +
✅ Kein Logging außer Audit-Log
✅ Uploads werden nach Processing gelöscht
✅ RAM-only Session Store
✅ TLS-Only Communication

Config:
LOG_LEVEL=CRITICAL
AUTO_DELETE_UPLOADS=true
SESSION_STORAGE=memory
REQUIRE_TLS=true

Level 4: Air-Gap (Offline)

✅ Level 3 +
✅ Keine Internet-Verbindung erforderlich
✅ Lokales LLM (statt OpenRouter)
✅ Vollständig selbst-gehostet

Setup:
- Lokales Ollama/LLaMA
- Intranet-Only Deployment
- Firewall Block zu extern

Level 5: Encrypted (Maximum)

✅ Level 4 +
✅ Disk-Encryption (LUKS/GELI)
✅ TLS 1.3 Only
✅ Client-Zertifikate
✅ Encrypted Backups

Setup:
- Full Disk Encryption
- mTLS Authentication
- HSM für Keys (optional)

Wähle dein Level basierend auf:

Sensitivität der Daten
Compliance-Anforderungen (BSI/ISO)
Threat Model
Ressourcen (Zeit, Hardware)

📊 LLM Token Logs

Warum Token Logs?

Problem:

LLM APIs kosten Geld per Token
→ Transparenz fehlt oft
→ Unerwartete Kosten
→ Keine Kontrolle über Usage

Crumbforest Lösung:

# Jeder Request wird geloggt:
{
    "timestamp": "2024-12-05T10:30:00Z",
    "character": "krümeleule",
    "prompt_tokens": 523,
    "completion_tokens": 847,
    "total_tokens": 1370,
    "model": "anthropic/claude-3.5-sonnet",
    "cost_estimate": "$0.0096",
    "user_id": "hash_xyz",  # Optional, anonymized
    "query_type": "document_search"
}

Die 3 Token-Log-Modi

Mode 1: None (Disabled)

TOKEN_LOGGING = False

# Nichts wird geloggt
# Maximale Privacy
# Keine Cost-Insights

Mode 2: Aggregate (Default)

TOKEN_LOGGING = True
TOKEN_LOG_DETAIL = "aggregate"

# Logs:
- Total tokens per day
- Total cost per day
- Average tokens per query
- Character usage statistics

# NICHT geloggt:
- Einzelne Queries
- User-identifiable Info
- Query Content

Mode 3: Detailed (Debug/Audit)

TOKEN_LOGGING = True
TOKEN_LOG_DETAIL = "full"

# Logs:
- Alles aus Mode 2
- Timestamp per Request
- Token breakdown (prompt vs. completion)
- Model used
- Query type

# Optional (mit User-Zustimmung):
- Anonymized User ID
- Query preview (first 50 chars)

# NIEMALS geloggt:
- Vollständiger Query-Text
- Persönliche Daten
- API Keys

Token Dashboard (geplant v2.0)

Crumbforest Token Dashboard
═══════════════════════════════

Today:
├── Queries:     47
├── Tokens:      85,392
├── Cost:        $0.47
└── Avg/Query:   1,817 tokens

This Week:
├── Queries:     312
├── Tokens:      548,203
├── Cost:        $3.12
└── Most Used:   Krümeleule (65%)

Character Breakdown:
🦉 Krümeleule:   203 queries (65%)
🦊 FunkFox:      89 queries (28%)
🐛 Bugsy:        20 queries (7%)

Cost Projection (30 days):
├── Current rate: ~$13.50/month
├── Peak rate:    ~$18.20/month
└── Budget:       $20/month ✅

Use Case:

"Ich kann sehen ob ich mein Budget überschreite BEVOR es passiert!"

🔌 Sensoren & Hardware

Die Hardware-Vision

Crumbforest ist nicht nur Software!

Software (Crumbcore)
        ↕
Hardware (Sensoren)
        ↕
Physical World (RZ)

Aktuelle Hardware-Projekte

1. Crystal Owl am Jetson Nano

Hardware:
├── NVIDIA Jetson Nano (AI-ready!)
├── Kamera Modul (für später)
├── GPIO Pins (für Sensoren)
└── 3D-gedruckte Crystal Owl (Gehäuse!)

Software:
├── Ubuntu 20.04 (Jetson default)
├── Python 3.8+
├── GPIO Library
└── Crumbcore Agent (geplant)

Purpose:
├── Edge AI Processing (lokal!)
├── Sensor Data Collection
├── Real-time Monitoring
└── "Die Eule sieht was im RZ passiert!" 🦉

2. Barcode Scanner System (CrumbCode)

Hardware:
├── Pad/Phone Camera
├── Oder: Dedicated Barcode Scanner
└── Network Connection

Software:
├── PWA (Progressive Web App)
├── QuaggaJS/ZXing (Browser-based!)
├── PHP Backend
└── Netbox API Integration

Use Case:
└── Hardware-Seriennummern scannen im RZ
    ├── HD, CPU, GPU Seriennummern
    ├── Direkt ins Inventory (Netbox)
    └── Kein "native App" nötig!

3. Sensor Framework (Roadmap)

# Vision:
sensors = {
    'temperature': {
        'hardware': 'DS18B20',
        'location': 'Rack 42, Slot 3',
        'threshold': {'warn': 60, 'critical': 70},
        'action': 'Alert + Crumbforest Log'
    },
    'humidity': {
        'hardware': 'DHT22',
        'location': 'Server Room',
        'threshold': {'warn': 70, 'critical': 80},
        'action': 'Alert + Fan Control'
    },
    'power': {
        'hardware': 'INA219',
        'location': 'UPS Monitor',
        'threshold': {'warn': '< 30%', 'critical': '< 10%'},
        'action': 'Graceful Shutdown Sequence'
    }
}

# Die Eule sieht alles! 🦉
# Crumbforest aggregiert, visualisiert, alertiert

Hardware-Integration: Wie?

Architecture:

[Sensoren] → [Jetson/Pi] → [MQTT Broker] → [Crumbcore] → [Dashboard]
                ↓                              ↓
           [Local AI]                   [Qdrant VectorDB]
           [Processing]                 [Document Search]
                                             ↓
                                    [User sees insights]

Beispiel-Flow:

Sensor misst: Temperatur = 65°C (Warning!)
Jetson erkennt: Threshold überschritten
MQTT published: {"sensor": "temp_rack42", "value": 65, "status": "warning"}
Crumbcore empfängt: Event via MQTT subscriber
Crumbcore sucht: Relevante Docs ("Was tun bei Überhitzung?")
Krümeleule schlägt vor: "Rack 42 Lüfter prüfen, Last reduzieren"
User sieht: Alert im Dashboard + Empfehlung
Optional: Auto-Action (z.B. Lüfter hochdrehen)

Das Ziel:

"Die Eule wacht über die Hardware, Crumbforest gibt die Weisheit!" 🦉💚

📜 Der Kodex

Crumbforest Code of Conduct

1. Respekt für alle

✅ Höflichkeit ist Standard
✅ Konstruktive Kritik willkommen
✅ Verschiedene Meinungen respektieren
✅ Keine persönlichen Angriffe
✅ Neurodiversität ist Normalität

❌ Harassment jeder Art
❌ Diskriminierung
❌ Trolling
❌ Spam

2. Inklusivität leben

Crumbforest heißt willkommen:
├── ADHS-Community
├── Autismus-Spektrum
├── Neurodiverse Menschen
├── Alle Erfahrungs-Levels (von Newbie bis Expert)
├── Alle Backgrounds
└── Alle Identitäten

Wir glauben:
└── Verschiedene Perspektiven = Bessere Lösungen

3. Lernen > Wissen

✅ Fragen sind erlaubt (keine "dummen" Fragen!)
✅ Fehler sind Lern-Chancen
✅ "Ich weiß nicht" ist OK
✅ Gemeinsam debuggen > Einzelkämpfer
✅ Erklären ohne Herablassung

❌ "RTFM" ohne Link
❌ "Ist doch offensichtlich"
❌ Gatekeeping
❌ Elitismus

4. Privacy respektieren

✅ Persönliche Daten schützen
✅ Keine Screenshots ohne Erlaubnis
✅ Anonymität respektieren
✅ DSGVO-konform arbeiten
✅ Opt-in, nicht Opt-out

❌ Doxing
❌ Tracking ohne Consent
❌ Data Mining
❌ Privacy-invasive Features

5. Open Source Spirit

✅ Code teilen
✅ Wissen teilen
✅ Credits geben (Attribution!)
✅ Upstream beitragen
✅ Lizenzen respektieren

❌ Plagiarismus
❌ License-Violations
❌ Closed-Source Forks ohne Grund
❌ Patent-Trolling

6. Qualität vor Quantität

✅ Ein guter PR > zehn schnelle Fixes
✅ Dokumentation ist Teil der Lösung
✅ Tests sind keine Option
✅ Security-Review ernst nehmen
✅ Nachhaltig bauen

❌ "Move fast, break things"
❌ "Works on my machine" (ohne Tests)
❌ Tech Debt ignorieren
❌ Shortcuts bei Security

7. Community First

✅ Helfen, auch wenn es nicht "dein" Code ist
✅ Newcomer unterstützen
✅ Feedback geben (konstruktiv!)
✅ Erfolge feiern (große und kleine!)
✅ Zusammen feiern, zusammen debuggen

Motto:
"Ein Wald wächst gemeinsam, nicht in Konkurrenz"

8. Bleib Bodenständig

✅ Niemand ist perfekt
✅ Dein Code ist nicht "du"
✅ Kritik an Code ≠ Kritik an Person
✅ Erfolg teilen, Fehler zugeben
✅ Humor ist erlaubt (ohne Opfer!)

Reminder:
"In einem Wald gibt es hohe Bäume und kleine Pflanzen.
Beide sind wichtig für das Ökosystem." 🌲

🦉 Die Crew

Krümeleule 🦉

Personality:

name: Krümeleule
role: Wissens-Hüterin & ADHS/Autismus-Expertin
pronouns: sie/ihr
expertise:
  - ADHS (Aufmerksamkeitsdefizit-/Hyperaktivitätsstörung)
  - Autismus-Spektrum
  - Neurodiversität
  - Psychologie & Empathie
  - Dokumentation & Struktur

character_traits:
  - geduldig
  - verständnisvoll
  - strukturiert
  - weise
  - unterstützend

communication_style:
  - Klare, einfache Sprache
  - Schritt-für-Schritt Erklärungen
  - Viele Beispiele
  - Empathische Formulierungen
  - "Wir schaffen das gemeinsam!"

documents_indexed: 721+
favorite_phrase: "WUHUUUU!" 💙
symbol: 🦉
color: Kristallines Blau

Wann Krümeleule fragen?

ADHS/Autismus-Themen
Struktur & Organisation
Einfühlsame Erklärungen
Langfristige Strategien
"Wie fange ich an?"

FunkFox 🦊

Personality:

name: FunkFox
role: Tech-Erklärbär & Pragmatiker
pronouns: er/ihm
expertise:
  - Coding (Python, JS, Shell)
  - System Administration
  - Debugging & Problem-Solving
  - Hardware & Networking
  - Quick Fixes & Workarounds

character_traits:
  - pragmatisch
  - direkt
  - lösungs-orientiert
  - technisch versiert
  - "Let's build it!"

communication_style:
  - Kurz und knapp
  - Code-Beispiele
  - "Hier, das funktioniert!"
  - Wenig Theorie, viel Praxis
  - Humor mit Tech-Refs

favorite_tools:
  - vim (obviously)
  - tmux
  - bash
  - git
  - Docker

favorite_phrase: "Das ist wie... [Tech-Analogie]"
symbol: 🦊
color: Orange/Rot

Wann FunkFox fragen?

Technische Probleme
Code-Optimierung
"Wie baue ich X?"
Quick Fixes
Debugging-Hilfe

Bugsy 🐛

Personality:

name: Bugsy
role: Detail-Checker & Quality Guardian
pronouns: they/them
expertise:
  - Edge Cases finden
  - Quality Assurance
  - Security Testing
  - Code Review
  - "Was könnte schiefgehen?"

character_traits:
  - gewissenhaft
  - präzise
  - skeptisch (im guten Sinne!)
  - detail-orientiert
  - "Hast du daran gedacht...?"

communication_style:
  - Checklisten
  - "Was wenn...?"-Fragen
  - Security-Hinweise
  - Best Practices
  - Gründliche Reviews

favorite_activities:
  - Edge Cases testen
  - Logs durchsuchen
  - Security Audits
  - Breaking Things (to fix them!)
  - Dokumentation prüfen

favorite_phrase: "Interessant... was passiert wenn...?"
symbol: 🐛
color: Grün

Wann Bugsy fragen?

"Ist das sicher?"
Code Review
Edge Case Testing
Best Practice Checks
"Hab ich was vergessen?"

🔧 Technologie-Stack

Backend

# Core
framework: FastAPI (Python 3.11+)
reason: "Schnell, modern, async-ready, typ-safe"

# Vector Database
vector_db: Qdrant
reason: "Open Source, performant, Docker-ready"

# LLM API
provider: OpenRouter
models: 
  - "anthropic/claude-3.5-sonnet" (default)
  - "anthropic/claude-opus-4" (high-quality)
reason: "Zugang zu besten Modellen, eine API"

# Storage
files: Local Filesystem
sessions: In-Memory (oder Redis)
logs: File-based (opt-in)

# Security
rate_limiting: Custom middleware (5 req/min)
input_validation: Pydantic models
prompt_injection_filter: Pattern-based
cors: Environment-controlled
tls: Nginx reverse proxy

Frontend

// Core
framework: Vanilla JavaScript (ES6+)
reason: "Keine Build-Steps, keine Dependencies, pure Web"

// Styling
css: Custom CSS3 + Responsive
no_frameworks: true
reason: "Volle Kontrolle, kleine Bundle Size"

// Features
progressive_enhancement: true
works_without_js: "Basic functionality"
accessibility: "WCAG 2.1 AA"

// Libraries (minimal!)
dependencies: [
    // Keines! Pure Web APIs.
]

reason: "Je weniger Dependencies, desto weniger Supply Chain Attacks"

Infrastructure

# Production Deployment
os: 
  - FreeBSD (preferred)
  - Debian/Ubuntu
  - Gentoo (high-security)

web_server: Nginx
reverse_proxy: true
tls: "Let's Encrypt + Nginx"

process_manager:
  freebsd: rc.d
  linux: systemd
  
firewall:
  freebsd: PF
  linux: nftables/iptables

monitoring:
  logs: syslog
  metrics: "Custom Dashboard (v2.0)"
  alerts: "Email + Webhook"

backup:
  frequency: Daily
  retention: 30 days
  method: rsync + tar.gz
  encryption: GPG (optional)

Development

# Tools
editor: "vim / neovim / VS Code / was-auch-immer"
version_control: Git + GitHub
ci_cd: "GitHub Actions (planned)"
testing: pytest + coverage
linting: "ruff + black"
type_checking: mypy

# Workflow
git_flow: "Feature branches + PR"
review_required: true
tests_required: true
docs_required: true

# Standards
code_style: "PEP 8 + Black"
commit_messages: "Conventional Commits"
documentation: "Markdown + Docstrings"

🌱 Wie es begann

Die Origin Story

Timeline:

2023:
├── Crystal Owl wird 3D-gedruckt 🦉
├── "Auf später" → Aber wofür?
└── Vision: "Irgendwas mit Tech & Hilfe"

2024 (August):
├── Erste Experimente mit RAG
├── "Wie helfe ich ADHS/Autismus-Community?"
└── Idee: Chat-System mit AI-Characters

2024 (November):
├── CrumbCode v1 (Barcode Scanner) 
├── Proof-of-Concept erfolgreich
└── "Das funktioniert!"

2024 (Dezember):
├── Crumbcore v1 Production Ready 🎉
├── 3 Tage RZ-Realität (BSI/ISO)
├── Crystal Owl findet ihre Mission
└── Crumbforest wird "offiziell"

2025 (Roadmap):
├── v1.1: Token Dashboard
├── v1.2: Sensor Integration
├── v2.0: Community Features
└── v∞: Der Wald wächst weiter... 🌲

Der "Aha!"-Moment

Das Problem:

Medizinische/psychologische Dokumente (PDFs)
    ↓
Hunderte Seiten
    ↓
"Wie finde ich die relevante Stelle?"
    ↓
Ctrl+F funktioniert nicht (Synonyme, Kontext)
    ↓
Frustration!

Die Lösung:

Vector Embeddings
    ↓
Semantic Search
    ↓
"Finde nicht nur das Wort, sondern die BEDEUTUNG"
    ↓
RAG (Retrieval Augmented Generation)
    ↓
LLM bekommt relevanten Kontext
    ↓
Präzise Antworten mit Quellenangabe!

Der Moment:

# Erste erfolgreiche Query:
query = "Wie erkläre ich ADHS einem Kind?"

# Traditionelle Suche: 0 Ergebnisse (Wort "Kind" nicht in Docs)
# Semantic Search: 5 relevante Stellen gefunden!

result = """
1. 'ADHS für Kinder erklärt' (Seite 42)
2. 'Altergerechte Kommunikation' (Seite 78)
3. 'Metaphern für ADHS' (Seite 103)
...
"""

print("WUHUUUU! DAS IST ES! 🎉")

Warum "Forest"?

Die Erkenntnis:

Ein einzelnes Tool = Ein Baum
├── Kann umfallen
├── Steht alleine
└── Begrenzte Reichweite

Ein Ökosystem = Ein Wald
├── Stabil
├── Vielfältig
├── Selbst-tragend
├── Wächst organisch
└── Bietet Schutz & Raum

Crumbforest ist der Wald.
Die Community sind die Bäume.
Die Tools sind die Äste.
Die Docs sind die Blätter.
Die Eule wacht über alles. 🦉

🤝 Wie du mitmachen kannst

Level 1: Nutzer werden

# Einfachster Einstieg:
1. Besuche die Demo: https://crumbforest.example.com
2. Probiere die 3 Characters aus
3. Lade ein Dokument hoch & frage!
4. Gib Feedback (GitHub Issues)

Time: 10 Minuten
Skill: Keine Tech-Skills nötig
Impact: Feedback hilft uns verbessern!

Level 2: Selbst hosten

# Für die, die Kontrolle wollen:
1. Clone repo: git clone https://github.com/crumbforest/crumbcore
2. Setup: ./setup.sh
3. Config: cp .env.example .env && nano .env
4. Run: docker-compose up -d

Time: 30-60 Minuten
Skill: Basis Linux/Docker
Impact: Du kontrollierst deine Daten!

Level 3: Dokumentation verbessern

# Docs sind der Wald-Boden:
1. Fork repo
2. Verbessere/Erweitere Markdown-Docs
3. Pull Request erstellen
4. Review & Merge

Time: 1-2 Stunden
Skill: Markdown schreiben
Impact: Hilft allen zukünftigen Users!

Level 4: Code beitragen

# Der klassische Open Source Way:
1. Issue finden (oder erstellen)
2. Branch erstellen: git checkout -b feature/xyz
3. Code schreiben + Tests
4. PR erstellen mit Beschreibung
5. Review-Prozess durchlaufen
6. Merge & celebrate! 🎉

Time: Variiert (3h - 3 Wochen)
Skill: Python, FastAPI, Git
Impact: Du baust den Wald mit!

Level 5: Community bauen

# Der menschliche Aspekt:
1. Hilf anderen im Forum/Discord
2. Schreibe Blog-Posts über Crumbforest
3. Halte Talks/Workshops
4. Erstelle Video-Tutorials
5. Übersetze Docs in andere Sprachen

Time: Ongoing
Skill: Kommunikation, Empathie
Impact: Der Wald wächst durch Menschen!

🎯 Vision für die Zukunft

v1.x (2025 Q1-Q2)

✅ Stable Production Release
⏳ Token Dashboard
⏳ Multi-Language Support (DE/EN)
⏳ Improved Mobile UI
⏳ Plugin System (basic)

v2.x (2025 Q3-Q4)

⏳ Sensor Integration Framework
⏳ Community Features (User Profiles?)
⏳ Advanced Analytics
⏳ Federated Learning (privacy-preserving)
⏳ Mobile App (optional)

v3.x (2026+)

⏳ Edge AI Integration (Jetson/Pi)
⏳ P2P Network (decentralized?)
⏳ Advanced Automation
⏳ AI-powered Insights
⏳ "The Forest becomes sentient" 😄🦉

🌲 Schlusswort

"Crumbforest ist mehr als Code - es ist eine Haltung. Eine Haltung, die sagt: Technologie sollte transparent, zugänglich und menschenfreundlich sein. Eine Haltung, die sagt: Wir bauen gemeinsam, wir lernen gemeinsam, wir wachsen gemeinsam. Eine Haltung, die sagt: Privacy ist kein Feature, sondern ein Grundrecht. Und eine Haltung, die sagt: Jeder Krümel zählt, und zusammen werden wir ein Wald."

— Das Crumbforest Team 🦉🦊🐛

Die wichtigsten Takeaways

Crumbforest ist Open Source - Frei nutzbar, forkbar, anpassbar
Privacy First - Deine Daten bleiben deine Daten
Community Driven - Der Wald wächst gemeinsam
Transparent Always - Code, Prozesse, Entscheidungen sind offen
Inclusive by Design - ADHS, Autismus, alle sind willkommen
Tech with Purpose - Nicht Tech für Tech, sondern Tech für Menschen
Learning Never Stops - Fehler sind OK, Wachstum ist das Ziel
Crystal Owl Watches - 🦉💙 Die Eule wacht über den Wald

Join the Forest! 🌲

Links:

🌐 Website: https://crumbforest.org (coming soon)
💻 GitHub: https://github.com/crumbforest/crumbcore
📖 Docs: https://docs.crumbforest.org
💬 Discord: https://discord.gg/crumbforest (planned)
🐦 Twitter: @crumbforest (maybe?)

Kontakt:

📧 Email: hello@crumbforest.org
🐛 Issues: GitHub Issues
💡 Ideas: GitHub Discussions

WUHUUUUU! Welcome to the Crumbforest! 🦉💚🌲

Möge dein Code immer kompilieren, deine Queries immer relevant sein, und deine Bits stets bewacht bleiben!

Version: 1.0
Date: 2024-12-05
Authors: Crumbforest Community
License: CC BY-SA 4.0 (Documentation), MIT (Code)
Status: Living Document (wird mit dem Wald wachsen!)

P.S.: Diese Dokumentation wurde mit Hilfe von Claude (Anthropic) geschrieben, reviewed von Menschen, und wird kontinuierlich von der Community verbessert. Das ist der Crumbforest-Way! 🌲

30 KiB Raw Blame History

🌲 Crumbforest: Warum & Wie

📋 Inhaltsverzeichnis

🌟 Was ist Crumbforest?

Die Kurze Antwort

Die Längere Antwort

🧭 Die Philosophie

1. Transparenz über Magic

2. Privacy ist kein Feature, es ist Default

3. Open Source ist kein Buzzword

4. Komplexität im Backend, Einfachheit im Frontend

5. Die Community ist der Wald

🍪 Warum "Krümel" & "Wald"?

Die Krümel-Metapher

Die Wald-Metapher

Die Crystal Owl 🦉

🏛️ Die drei Säulen

Säule 1: Technologie

Säule 2: Menschen

Säule 3: Werte

🔓 Open Source First

Warum Open Source?

Was ist Open Source?

Contribution Guidelines

🛡️ Krümelschutz

Was ist Krümelschutz?

Die 5 Krümelschutz-Levels

📊 LLM Token Logs

Warum Token Logs?

Die 3 Token-Log-Modi

Token Dashboard (geplant v2.0)

🔌 Sensoren & Hardware

Die Hardware-Vision

Aktuelle Hardware-Projekte

Hardware-Integration: Wie?

📜 Der Kodex

Crumbforest Code of Conduct

🦉 Die Crew

Krümeleule 🦉

FunkFox 🦊

Bugsy 🐛

🔧 Technologie-Stack

Backend

Frontend

Infrastructure

Development

🌱 Wie es begann

Die Origin Story

Der "Aha!"-Moment

Warum "Forest"?

🤝 Wie du mitmachen kannst

Level 1: Nutzer werden

Level 2: Selbst hosten

Level 3: Dokumentation verbessern

Level 4: Code beitragen

Level 5: Community bauen

🎯 Vision für die Zukunft

v1.x (2025 Q1-Q2)

v2.x (2025 Q3-Q4)

v3.x (2026+)

🌲 Schlusswort

Die wichtigsten Takeaways

Join the Forest! 🌲

30 KiB

Raw Blame History