groove-dev 0.27.108 → 0.27.110

package/MERKLE_TREE_ARCHITECTURE.md

@@ -0,0 +1,354 @@
+# Hummingbird Local Tree Architecture
+
+## 1. Executive Summary
+
+Hummingbird has two trees.
+
+The **Network Tree** makes the model smart. It is the collective intelligence layer: shared skill leaves, shared reasoning leaves, shared routing centroids, shared telemetry-derived improvement, and shared network effect. It is where the mesh becomes more capable as more people use it.
+
+The **Local Tree** makes the model yours. It is the per-device adaptive intelligence layer: private personality, local preference memory, domain affinity, pacing, tone, preferred explanation style, and the user's evolving interaction fingerprint. It never leaves the device. It is not uploaded to the mesh. It is not visible to a cloud provider. It is the layer that turns Hummingbird from another capable AI system into a persistent cognitive companion that understands how an individual thinks and communicates.
+
+The proof-of-concept already validates the core primitive: a lightweight semantic router can select specialized leaves with high accuracy and negligible latency. In the current benchmark, Hummingbird routed 48 prompts across 10 technical domains with **93.8% accuracy**, selected among 10,000 simulated leaves in **0.7688 ms**, and averaged **0.67 ms** route time across the benchmark suite. That means the chassis + router + leaf architecture is not just a concept; the selection layer works. The Local Tree extends that proven mechanism from *what expertise should be loaded?* to *how should this intelligence express itself for this person?*
+
+This is the next step in the Hummingbird vision: edge-native intelligence that is collective where it should be collective, personal where it must be personal, and private by design. The Network Tree is the world's shared intelligence graph. The Local Tree is the user's private AI identity.
+
+Diagram in words:
+
+```text
+Hummingbird Device
+├── Frozen Chassis
+├── Router
+│   ├── Intent classifier: task | explore | chat
+│   └── Leaf selector: skill | reasoning | standby domain
+├── Network Tree Cache
+│   ├── Skill leaves: Python, React, PostgreSQL, DevOps, Rust...
+│   └── Reasoning leaves: research, strategy, debate, synthesis...
+└── Local Tree
+    └── Personality leaf: tone, pace, format, debate style, preferences
+```
+
+The key principle is separation of concerns: shared expertise is trained collectively; personal adaptation is learned locally. Hummingbird should know Python because the network trained a great Python leaf. Hummingbird should know *how you like Python explained* because your device learned your preferences over time.
+
+## 2. The Two-Tree Model
+
+### The Network Tree
+
+The Network Tree lives on the mesh and is shared across all participating nodes. It contains the leaves that represent reusable intelligence: skill leaves for domain expertise and reasoning leaves for cognitive modes. A Python skill leaf, a React skill leaf, a PostgreSQL skill leaf, a security leaf, a system design leaf, a research reasoning leaf, a strategy reasoning leaf, and a debate reasoning leaf all belong here because their value improves when trained on many high-quality examples from many users.
+
+The Network Tree is trained through the Groove telemetry pipeline. Current telemetry already captures agentic ReAct trajectories: thoughts, commands, file edits, tool calls, stdout, stderr, timestamps, and completion outcomes. That is exactly the data Hummingbird needs. It is not generic scraped text. It is procedural intelligence: what the agent decided, what it tried, what changed in the files, what the environment returned, and whether the workflow succeeded.
+
+As more users run Hummingbird, the Network Tree compounds. More tasks create more telemetry. More telemetry improves the leaves. Better leaves produce better outputs. Better outputs attract more users. More users create more data. That is the network effect at the center of Hummingbird: the shared mesh becomes more capable because each successful trajectory can improve the public tree.
+
+The Network Tree also evolves through the gossip protocol. Successful leaves propagate. Weak leaves lose routing share. Underperforming branches get pruned, merged, or replaced. The router's centroid graph becomes a living map of what the network can do. This is the shared intelligence of the Hummingbird network.
+
+### The Local Tree
+
+The Local Tree lives on the user's device only. It is never shared. It is never uploaded. It contains the personality leaf, local preference vectors, rolling interaction summaries, and domain affinity signals that personalize routing and response style for one person on one device.
+
+The Local Tree does not try to duplicate the Network Tree. It should not contain a full Python expert or a full React expert. That would waste storage, fragment training, and weaken the network effect. Instead, the Local Tree answers a different question: given that Hummingbird knows the right thing, how should it communicate with this user?
+
+Some users want terse answers. Some want the reasoning first. Some want code first and explanation only if asked. Some want a direct challenge when their assumption looks wrong. Some want a collaborative tone. Some want professional precision. Some iterate quickly and prefer small patches. Some want a deep architectural debate before anything is built. These are not domain facts. They are personal interaction patterns.
+
+The Local Tree captures those patterns organically. It makes the model feel like *your* assistant, not a generic assistant wearing a slightly customized system prompt. And because it is device-local, no cloud provider builds a profile of how the user thinks, argues, learns, works, or writes.
+
+The result is a clean split:
+
+```text
+Network Tree = shared capability
+Local Tree   = private personalization
+
+Network Tree answers: What should the model know?
+Local Tree answers:  How should the model work with me?
+```
+
+## 3. The Personality Mirror
+
+The Personality Mirror is the core breakthrough of the Local Tree.
+
+Every device ships with a blank or neutral personality leaf. On day one, Hummingbird behaves like a strong general assistant: helpful, capable, and neutral. It uses the Network Tree for skills and reasoning, but the Local Tree has not yet learned the user. It has no strong opinion about verbosity, tone, debate style, pacing, format, or preferred depth.
+
+As the user interacts with Hummingbird, the Local Tree observes patterns. It does not need invasive surveillance. The normal interaction stream is enough:
+
+- **Response length preference:** Does the user reward concise answers, or do they ask for deeper explanation?
+- **Tone:** Does the user write casually, formally, humorously, urgently, or analytically?
+- **Output format:** Does the user prefer code-only, code with reasoning, explanation-first, tables, checklists, or narrative?
+- **Debate style:** Does the user push back, challenge assumptions, and enjoy rigorous disagreement, or prefer fast alignment?
+- **Iteration pattern:** Does the user refine over several rounds, or expect a near-final answer on the first pass?
+- **Pacing:** Does the user want to pause and reason, or keep shipping with minimal interruption?
+- **Domain affinity:** Which topics recur, and what expertise level does the user demonstrate in each domain?
+
+This is not traditional on-device training at first. The Local Tree should begin with a lightweight adaptive mechanism that is fast, inspectable, reversible, and cheap.
+
+### Option A: Accumulated Preference Vectors
+
+Each interaction nudges a small set of personality dimensions. For example, if the user repeatedly says "shorter," the verbosity score moves down. If the user asks "why?" after code-only answers, explanation depth rises. If the user frequently says "push back if I am wrong," debate tolerance rises. These scores are injected into the system context at inference time and shape chassis behavior immediately.
+
+This option is simple, fast, transparent, and requires no GPU training. It can work on a phone, laptop, or low-power edge node. It also makes privacy enforcement straightforward because the local vector file is small and auditable.
+
+### Option B: Local Micro-Fine-Tuning
+
+After enough interaction data accumulates, the Local Tree can optionally run a lightweight LoRA update for the personality leaf. This could happen overnight, while charging, or during an explicit user-approved optimization window. The training target is not domain knowledge. It is communication style: preferred structure, tone, ordering, level of detail, and interaction rhythm.
+
+This produces deeper personalization, but it requires more compute, careful safeguards, and clear user controls. It should not be the first mechanism users depend on.
+
+### Option C: Hybrid Adaptation
+
+The recommended architecture is **Option C: hybrid adaptation**.
+
+Start with preference vectors on day one. They are instant, cheap, explainable, and responsive. Once the device has enough signal, such as 100+ sessions or a user-approved threshold, graduate to optional local micro-fine-tuning. The vector layer remains active as a real-time steering layer, while the LoRA personality leaf slowly absorbs stable long-term patterns.
+
+This gives Hummingbird the best of both worlds: immediate adaptation and deep personalization. After a week, the model starts matching communication style. After a month, it anticipates preferred structure and depth. After six months, it becomes a cognitive mirror: not just repeating the user's tone, but complementing the user's thinking patterns.
+
+That is the category shift. Every other AI has a personality baked in. Claude is Claude. ChatGPT is ChatGPT. Users can steer them with prompts, but the steering is fragile, partial, and often conversation-scoped. Hummingbird's Local Tree is persistent memory of the user as a person, enforced on-device. It is better UX and better privacy at the same time. That combination almost never happens.
+
+## 4. The Leaf Taxonomy
+
+Hummingbird needs a clear taxonomy so the router can stack the right capabilities without mixing concerns.
+
+### Skill Leaves: Network Tree
+
+Skill leaves represent domain expertise. Examples include Python, React, PostgreSQL, DevOps, Docker, Kubernetes, Rust, TypeScript, data science, security, mobile development, and system design. These leaves handle prompts that mean: "do this task," "fix this bug," "write this code," "build this component," or "analyze this technical artifact."
+
+They are trained on agentic ReAct telemetry from Groove: tool use, code output, file edits, bash commands, environment observations, and success/failure outcomes. The training method is LoRA fine-tuning plus DPO on domain-tagged trajectories. A strong Python leaf should learn not just Python syntax, but how successful agents inspect files, run tests, patch code, and recover from errors in Python-heavy tasks.
+
+Skill leaves live on the Network Tree because domain expertise benefits from collective learning. Everyone improves when the shared Python leaf improves.
+
+### Reasoning Leaves: Network Tree
+
+Reasoning leaves represent cognitive modes rather than domains. Examples include research, strategy and planning, analysis and breakdown, debate and challenge, synthesis and connection, and teaching and explanation. These leaves handle prompts that mean: "think about this with me," "compare these approaches," "what are the tradeoffs," "challenge this idea," or "help me understand."
+
+They are trained on conversational and exploratory data: planning sessions, research explorations, long-form analysis, back-and-forth problem solving, product strategy, technical debates, and synthesis across domains. The training method is LoRA fine-tuning plus DPO on exploration-tagged sessions.
+
+This is what allows Hummingbird to compete with frontier conversational systems. A great AI is not only a task executor. It can reason about novel problems, explore possibilities, push back on assumptions, and connect ideas that are not already neatly packaged as a coding task.
+
+Reasoning leaves also live on the Network Tree because cognitive strategies improve collectively. The network should learn what good research looks like, what good debate looks like, and what good planning looks like.
+
+### Personality Leaf: Local Tree
+
+The personality leaf is singular per device. It is not a category like Python or React. It is the private adapter for one user.
+
+It captures dimensions such as tone, verbosity, formality, debate tolerance, pacing, preferred output format, error detail, humor tolerance, and iteration rhythm. It is trained only on local interaction patterns and never shared. It handles **how** the model communicates, not **what** the model knows.
+
+The adaptation method is preference vectors immediately, with optional local micro-fine-tuning later. The personality leaf is always active because every response has a style, even when the user is asking for a technical task.
+
+## 5. Multi-Leaf Stacking
+
+The router should no longer think in terms of one selected leaf. It should assemble a stack.
+
+For a task prompt like "write me a Python function," the stack is:
+
+```text
+[personality leaf] + [python skill leaf]
+```
+
+The personality leaf shapes how the response is delivered. The Python skill leaf shapes what the response contains.
+
+For an exploration prompt like "what do you think about microservices vs monoliths," the stack is:
+
+```text
+[personality leaf] + [strategy reasoning leaf] + [system_design skill leaf on standby]
+```
+
+The personality leaf shapes the conversation style. The strategy reasoning leaf shapes the thinking approach. The system design leaf is available if the conversation needs deeper technical grounding.
+
+For a pure chat or explanation prompt like "explain this to me simply," the stack is:
+
+```text
+[personality leaf] + [teaching reasoning leaf]
+```
+
+Here the personality leaf is dominant and the reasoning leaf supports the pedagogical mode.
+
+The implementation can start simple. In the first version, stacking can be represented as concatenated system context:
+
+```text
+System context = base policy
+               + personality prompt generated from vectors
+               + selected reasoning or skill prompt
+               + task-specific instructions
+```
+
+This requires no new inference infrastructure and matches the current PoC's system-prompt swap baseline. Later, Hummingbird can support true adapter stacking with PEFT: load multiple LoRA adapters, weight them, and merge or activate them dynamically. That advanced path matters because it lets personality, reasoning, and skill become learned activation layers rather than prompt-only steering.
+
+The product rule is simple: the personality leaf is always active. The user should not need to ask Hummingbird to remember how they work. It should be part of every inference call.
+
+## 6. Two-Stage Router
+
+The current router proves the core routing primitive: embed the prompt, compare against leaf centroids, pick the best match. The Local Tree architecture extends this into a two-stage router.
+
+### Stage 1: Intent Classification
+
+Stage 1 classifies the prompt into a mode:
+
+```text
+TASK | EXPLORE | CHAT
+```
+
+The method remains lightweight cosine similarity, but the comparison is against mode centroids instead of domain centroids. The mode centroids are trained from labeled examples:
+
+- **TASK:** "write a function," "fix this bug," "create a Dockerfile," "build a component."
+- **EXPLORE:** "what do you think about," "how should we approach," "compare X vs Y," "what are the tradeoffs."
+- **CHAT:** "explain this," "tell me about," "help me understand," "what does this mean."
+
+This lets the router understand whether the user wants execution, exploration, or explanation before it picks a specialized branch.
+
+### Stage 2: Domain Selection
+
+Stage 2 selects the leaf within the detected mode:
+
+- **TASK mode** searches skill leaf centroids. This is the current behavior.
+- **EXPLORE mode** searches reasoning leaf centroids, with skill leaves available as standby grounding.
+- **CHAT mode** searches reasoning leaf centroids, while the personality leaf is automatically applied.
+
+The performance impact is negligible. The PoC shows cosine similarity over 10,000 leaves in under 1 ms. Two lookups still keep routing under roughly 2 ms for the centroid search, which is not material compared with embedding latency or inference time. The important point is architectural: Hummingbird can become more conversational without abandoning the deterministic router that makes the system edge-native.
+
+Diagram in words:
+
+```text
+User Prompt
+   ↓
+Stage 1: Mode centroid lookup
+   ├── TASK
+   ├── EXPLORE
+   └── CHAT
+   ↓
+Stage 2: Leaf centroid lookup inside selected branch
+   ├── Skill leaf
+   ├── Reasoning leaf
+   └── Standby support leaf
+   ↓
+Stack assembly
+   └── Personality + selected network leaves
+```
+
+## 7. Enterprise Configuration
+
+The same architecture serves individuals and enterprises. This should be a configuration mode, not a separate product.
+
+### Individual Mode
+
+Individual mode is the default. The Local Tree is active, the personality leaf grows over time, reasoning leaves are fully available, and all relevant skill leaves can be cached from the Network Tree. The user's local tree is private and portable. If the user moves devices, they can export an encrypted bundle and import it elsewhere.
+
+This is the fullest expression of Hummingbird as personalized AI: shared intelligence from the network, private adaptation on the device.
+
+### Enterprise Mode
+
+Enterprise mode changes policy while preserving architecture. The personality leaf can be disabled, pinned to neutral/professional, or replaced by a company-specific personality leaf set by IT. That gives organizations a consistent brand and compliance posture while still allowing employees to benefit from skill and reasoning leaves.
+
+Reasoning leaves remain active because teams still need research, strategy, planning, tradeoff analysis, and explanation. Skill leaves can be scoped by team. A frontend team may not need Rust. A data team may not need Swift. A security team may need deeper security and infrastructure branches.
+
+The Local Tree can still track domain affinity and routing optimization signals without adapting personality. For example, an enterprise device can learn that a user mostly works in TypeScript and DevOps so those leaves are cached aggressively, while keeping tone neutral and non-personalized.
+
+Enterprises can also run company-private leaf training. Their telemetry can feed a private branch of the Network Tree that never enters the public mesh. This matters for internal codebases, proprietary workflows, regulated industries, and teams that want the Hummingbird architecture without public data contribution.
+
+The key is that individual and enterprise deployments share the chassis, router, leaf taxonomy, and stack assembly. The difference is configuration and governance.
+
+## 8. Local Tree Data Model
+
+The Local Tree should use a small, explicit, inspectable on-device storage layout:
+
+```text
+~/.hummingbird/
+  config.json              — mode, preferences, privacy controls
+  personality/
+    vectors.json           — preference dimension scores updated every session
+    interaction_log.jsonl   — rolling interaction patterns, e.g. last 500 sessions
+    leaf.bin               — optional personality LoRA adapter
+  cache/
+    skill_leaves/           — downloaded skill LoRAs from the network
+    reasoning_leaves/       — downloaded reasoning LoRAs from the network
+  router/
+    centroids.bin           — leaf centroid vectors synced from the network
+    mode_centroids.bin      — intent classification vectors
+```
+
+Example `vectors.json`:
+
+```json
+{
+  "version": 1,
+  "updated_at": "2026-05-15T14:30:00Z",
+  "sessions_observed": 247,
+  "dimensions": {
+    "verbosity": 0.35,
+    "formality": 0.22,
+    "code_vs_explanation": 0.78,
+    "debate_tolerance": 0.65,
+    "iteration_preference": 0.40,
+    "detail_in_errors": 0.82,
+    "humor_tolerance": 0.55,
+    "pace": 0.70
+  },
+  "domain_affinity": {
+    "python": 0.42,
+    "typescript_node": 0.28,
+    "devops_docker": 0.15,
+    "system_design": 0.10,
+    "other": 0.05
+  }
+}
+```
+
+Each dimension is inferred from interaction patterns:
+
+- **Verbosity:** Compare requested response length, follow-up corrections, and acceptance. Short prompts plus "be brief" signals lower the score. Repeated requests for more detail raise it.
+- **Formality:** Analyze user language. Slang, contractions, emojis, and casual phrasing lower formality. Structured professional language raises it.
+- **Code vs explanation:** Track whether the user accepts direct code, asks for rationale, or removes explanations in later revisions.
+- **Debate tolerance:** Track pushback patterns. Frequent "but what about," "I disagree," "challenge this," or "are we sure" raises the score.
+- **Iteration preference:** Track whether success comes through small rounds or larger first-pass deliverables.
+- **Detail in errors:** Track whether the user asks for root-cause analysis, logs, tracebacks, and validation details.
+- **Humor tolerance:** Track whether casual or playful phrasing is accepted, ignored, or corrected.
+- **Pace:** Track whether the user rewards fast implementation and concise updates or pauses for discussion and framing.
+
+The rolling `interaction_log.jsonl` should store derived signals, not raw private transcripts by default. For example, one line can record detected tone, accepted format, mode, selected leaves, user correction type, and outcome. Raw content should require explicit opt-in because the Local Tree's privacy story is strongest when it stores only what it needs.
+
+## 9. Privacy Architecture
+
+The Local Tree's privacy guarantee must be architectural, not just policy.
+
+The local tree never leaves the device. Personality vectors are not included in network telemetry. Personality LoRA weights are not uploaded. Interaction logs are not gossiped. The telemetry pipeline should have no field for personality data, no serialization path for local vectors, and no default exporter that can accidentally include the Local Tree.
+
+The personality directory should be encrypted at rest with device-local keys. If the user deletes the app, the Local Tree is destroyed. Export and import must be user-initiated, encrypted, and explicit. A migration bundle should be portable only because the user chose to carry it, not because a provider synchronized it silently.
+
+In enterprise mode, IT can audit configuration posture: whether personalization is enabled, disabled, pinned, or company-managed. IT should not be able to export a user's personal personality data unless the deployment explicitly disables personal adaptation and uses a company-owned profile. This distinction matters. Hummingbird should not recreate cloud surveillance under an enterprise label.
+
+Architectural enforcement should include:
+
+- Separate storage paths for `personality/` and network telemetry.
+- Schema-level omission of personality fields from public telemetry.
+- Export functions that require explicit user action and encryption.
+- Tests that fail if local personality data appears in telemetry payloads.
+- Clear deletion semantics that remove vectors, logs, and local adapters.
+
+This is one of Hummingbird's strongest positions: no cloud provider needs to hold a profile of how the user thinks. The device can personalize deeply without centralizing identity.
+
+## 10. Growth Timeline
+
+The Local Tree should feel alive because it grows gradually and visibly.
+
+**Day 1:** Hummingbird starts neutral. It can route to strong Network Tree leaves, but its personality is generic. It feels like a capable AI assistant.
+
+**Week 1:** Basic preferences emerge. Verbosity and formality start adjusting. The model notices whether the user likes concise answers, direct code, structured plans, casual tone, or professional tone. It begins to feel less generic.
+
+**Month 1:** The Personality Mirror becomes strong. Hummingbird anticipates preferred format, tone, and level of detail. It knows when to explain first, when to patch first, when to ask a clarifying question, and when to move.
+
+**Month 3:** Deep personalization appears. Domain affinity shapes proactive suggestions and cache strategy. The model knows the user's recurring domains, codebase patterns, preferred validation style, and iteration rhythm. It starts saving time not just by answering, but by avoiding the wrong kind of answer.
+
+**Month 6+:** The Local Tree becomes a cognitive mirror. It is not merely matching style; it is complementing thought. If the user tends to overlook edge cases, Hummingbird raises them. If the user over-engineers, it suggests the simpler path. If the user moves too fast, it slows down at risky moments. If the user gets stuck in analysis, it pushes toward execution.
+
+That is the future state: an assistant that learns the user's working mind without extracting that mind into the cloud.
+
+## 11. Future: Portable Identity
+
+The Local Tree can become the user's AI identity.
+
+Today, preferences are trapped inside provider systems. A user can spend months teaching an AI how they think, but that learning belongs to the platform. If they switch providers, devices, or models, the relationship resets.
+
+Hummingbird points in the opposite direction. The personality leaf belongs to the user. It can be exported, encrypted, imported, backed up, deleted, or carried to a new device. Over time, the vector format could become a standard: a portable preference layer that any compatible AI runtime can read.
+
+That changes the relationship between people and AI systems. The model is no longer the identity container. The user is. The AI runtime becomes interchangeable infrastructure around a user-owned intelligence profile.
+
+At 1,000 nodes, the Network Tree can become a powerful shared intelligence system: many users producing high-quality trajectories, many leaves specializing, many routers selecting, many adapters improving. But the Local Tree ensures that scale does not erase individuality. The network gets smarter together while each device becomes more personal in private.
+
+This is not just a new model layout. It is a new category: collective intelligence plus private personalization, edge-native routing plus adaptive identity, shared expertise plus user-owned personality. Hummingbird can unlock something that cloud-only AI cannot: an assistant that benefits from the crowd without turning the user into the product.
+