tony/bubble
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit - BUBBLE decision tracking system

Browse Source 
- Added core BUBBLE architecture with decision envelopes and policy store
- Implemented bundle API with FastAPI skeleton and OpenAPI specification
- Added Go-based storage implementation with SQLite and RocksDB support
- Created integrations for peer sync, vector search, and N8N workflows
- Added comprehensive testing framework and documentation
- Implemented provenance walking and decision checking algorithms

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
2025-08-27 09:35:03 +10:00
commit 013e0dc3f0
50 changed files with 3053 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
BUBBLE-IMPLEMENTATION-REPORT.md Normal file
View File

@@ -0,0 +1,68 @@
# BUBBLE Microservice: Implementation & Integration Report
## 1. Executive Summary
This document details the initial implementation of the **BUBBLE** microservice, a core component of the CHORUS ecosystem. BUBBLE functions as a specialized **Decision Agent**, providing on-demand analysis of decision provenance.
The work accomplished includes:
- **Project Scaffolding:** A complete Go module (`gitea.deepblack.cloud/chorus/bubble`) has been initialized and structured.
- **Blueprint Extraction:** All Python, JSON, SQL, and YAML snippets from the initial design conversation have been extracted and organized into a structured `/src` directory, serving as a clear blueprint for development.
- **Core Data Structures:** Go structs corresponding to the API and data models have been defined in `models/models.go`.
- **Storage Layer:** A flexible storage interface has been defined. A fully functional SQLite implementation has been created for persistence and testing, and a RocksDB implementation has been scaffolded for future high-performance use.
- **API Layer:** A runnable HTTP server using Go's standard library exposes the primary `/decision/bundle` endpoint.
- **Core Logic:** The central `WalkBack` algorithm has been implemented, featuring a breadth-first search (BFS) for graph traversal and a priority queue for scoring and ranking decision records.
- **Testing:** A minimal viable product has been successfully built and tested, confirming the API can serve requests by querying a seeded database.
BUBBLE is now a functional, testable microservice that fulfills its foundational role within the CHORUS architecture.
## 2. Integration with the CHORUS Ecosystem
BUBBLE does not operate in isolation; it is a critical, specialized tool designed to be called by other components, primarily **SLURP**.
### 2.1. Relationship with SLURP
The relationship is that of an orchestrator and a specialized tool:
1. **SLURP is the Orchestrator:** As the "Context Curator," SLURP is the entry point for all new information. When a BZZZ agent submits a Decision Record (DR), SLURP is responsible for the entire enrichment process.
2. **BUBBLE is the Provenance Engine:** SLURP's first step in enrichment is to understand the history behind the new DR. To do this, it makes a synchronous API call to BUBBLE's `/decision/bundle` endpoint.
3. **Data Flow:**
* SLURP sends a `start_id` (the ID of the new DR) and a `role` to BUBBLE.
* BUBBLE performs its high-speed, read-only "walk back" through the historical decision graph stored in its local RocksDB/SQLite database.
* BUBBLE returns a "Decision Dossier" (the `DecisionBundleResponse`), which is a compact, scored, and ranked summary of the most relevant historical DRs.
* SLURP takes this historical context from BUBBLE, combines it with conceptual context from other tools (like a RAG via n8n), and synthesizes the final, enriched context package.
* SLURP then writes this complete package to the DHT using the UCXL protocol.
This architecture correctly places the responsibility of complex, stateful graph traversal on a dedicated service (BUBBLE), allowing SLURP to remain a more stateless orchestrator.
### 2.2. Interaction with BZZZ
BUBBLE has no direct interaction with BZZZ agents. BZZZ agents communicate with SLURP, which in turn uses BUBBLE as a backing service. This maintains a clear separation of concerns.
## 3. Role in Decision Record (DR) Management
BUBBLE is the primary tool for **unlocking the value** of the Decision Records that SLURP curates. While SLURP is the librarian that collects and catalogs the books, BUBBLE is the research assistant that reads them, understands their connections, and provides a concise summary on demand.
### 3.1. Answering "Why?"
By traversing the `influences` and `supersedes` edges in the provenance graph, BUBBLE provides the auditable trail required to answer fundamental questions about a project's history:
- "Why was this technical decision made?"
- "What alternatives were considered?"
- "What prior work influenced this new feature?"
### 3.2. Preventing Rework
The `WalkBack` algorithm, combined with future vector similarity scoring, is the mechanism that addresses the "we tried this already" problem. When SLURP receives a new proposal, it can ask BUBBLE to find semantically similar DRs in the past. If BUBBLE returns a previously `rejected` or `superseded` DR with a high score, SLURP can flag the new proposal as a potential repeat of past failures, saving significant development time.
### 3.3. Enforcing Constraints and Policies
While BUBBLE does not query the Policy Store directly, its output is a critical input for SLURP's policy enforcement. The Decision Dossier provides the historical context that SLURP needs to determine if a new decision violates established budgetary, technical, or security constraints.
## 4. Next Steps & Future Development
The current implementation provides a solid foundation. The following steps will build upon it to realize the full vision of the blueprint:
1. **Full RocksDB Implementation:** Complete the `RocksDBStore` methods to provide a high-performance alternative to SQLite.
2. **Data Seeding/Syncing:** Create a mechanism to sync or replicate the decision graph from the central DHT into BUBBLE's local stores.
3. **Vector Search Integration:** Integrate a vector search client (e.g., FAISS, Milvus) to implement the `sim_score` part of the `WalkBack` algorithm.
4. **Caching Layer:** Implement a caching mechanism (e.g., in-memory LRU or Redis) for frequently requested bundles to further improve performance.
5. **LLM Integration for Summarization:** While SLURP handles most LLM interaction, BUBBLE could potentially use a local model to generate the `summary` field within the `DecisionBundleResponse` for greater accuracy.