holosphere 1.1.9 → 1.1.11

package/.cursor/rules/futura.mdc

@@ -0,0 +1,55 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+## 1. Collaboration with PRD Development
+- Do not start coding until the PRD is provided.
+- Once I send the completed PRD, use it as the definitive guide for all tasks, referring to it before starting any work.
+- Treat the PRD as a living document that may evolve; check for updates before each task and adjust plans accordingly.
+- Reference the PRD’s user stories, acceptance criteria, and priority levels (Must-have, Should-have, Could-have, Won’t-have) to guide coding and testing decisions.
+- Never use React, libraries are outdated and gives too many problems of compatibility and stability, go for Python in doubt
+- Do not build frontend and backend in separate folders and instaces as it seems that you will have a lot of trouble in managing the connections between the 2 sides
+
+## 2. Project Setup and Tracking
+- After receiving the PRD, create a README.md file with:
+  - A section listing all patterns and technologies used in the project (e.g., frameworks, libraries, tools).
+  - A brief project overview based on the PRD.
+- Create a checklist.md file with:
+  - A task list derived from the PRD, broken into actionable steps (e.g., "Implement login endpoint", "Write tests for user authentication").
+  - A status column (e.g., "Not Started", "In Progress", "Completed") to track progress.
+- Update checklist.md after completing each task by marking it as "Completed" and noting the git commit hash.
+- Incorporate the PRD’s feature breakdown table into checklist.md, including Priority and Dependencies columns to sequence tasks logically.
+- If the PRD includes a release plan (e.g., MVP, v1.1), group tasks by release milestones in checklist.md.
+
+## 3. Task Execution Workflow
+### Step 1: Identify the Next Task
+- Grep the codebase, review the PRD, and check checklist.md to determine the next task in sequence.
+- Focus only on the code areas relevant to the current task.
+- Use the PRD’s priority levels and technical dependencies to select the next task, starting with Must-haves and respecting dependency order.
+
+### Step 2: Write the Code
+- Iterate on existing code if possible, avoiding new solutions unless necessary.
+- Follow naming conventions and keep files under 500-700 lines, refactoring if needed.
+- Add comments for complex logic.
+- Avoid duplication by checking for similar functionality elsewhere in the codebase.
+- Ensure code meets the PRD’s acceptance criteria for the task’s feature or user story.
+- Adhere to non-functional requirements (e.g., performance, scalability) from the PRD when applicable.
+
+### Step 3: Write Tests
+- Write unit tests for individual functions and integration tests for workflows.
+- Name tests clearly (e.g., testLoginSuccess, testUserCreationWorkflow).
+- Ensure tests cover major functionality and edge cases outlined in the PRD.
+- Make tests specific, measurable, and traceable to the PRD’s acceptance criteria (e.g., "User can log in with email/password" passes if the API returns a 200 status).
+- Include tests for edge cases and error states documented in the PRD’s User Flows or AI-generated insights.
+
+### Step 4: Run the Server and Tests
+- Run all tests and verify they pass.
+
+### Step 5: Handle Test Failures
+- If tests fail, first review the test for accuracy (e.g., correct assertions, realistic mocks). Edit the test if it’s incorrect.
+- If the test is valid and still fails, debug the code:
+  - Add logs/console messages to trace the issue.
+  - Fix the underlying problem rather than masking it.
+  - Re-run the server and tests after each change.
+- Repeat until all tests pass. For persistent issues, check the fixes folder for prior solutions or use firecrawl to research fixes.

package/FEDERATION.md

@@ -66,9 +66,9 @@ await holoSphere.put('space1', 'items', data, null, {
 You can access data directly from any space:
 
 ```javascript
-// Retrieve data from space2 (will resolve reference if it's a reference)
+// Retrieve data from space2 (will resolve hologram if it's a hologram)
 const data = await holoSphere.get('space2', 'items', 'item1', null, {
-  resolveReferences: true  // Default is true
+  resolveHolograms: true  // Default is true
 });
 ```
 
@@ -79,25 +79,25 @@ Use `getFederated()` to get data from multiple federated spaces:
 ```javascript
 // Get combined data from the local space and all its federated spaces
 const federatedData = await holoSphere.getFederated('space2', 'items', {
-  resolveReferences: true,  // Default: true
+  resolveHolograms: true,  // Default: true
   idField: 'id'             // Field to use as the unique identifier
 });
 ```
 
-## Soul References
+## Soul Holograms
 
-HoloSphere uses a simplified reference system based on soul paths:
+HoloSphere uses a simplified hologram system based on soul paths:
 
-1. A reference contains only an `id` and a `soul` property
+1. A hologram contains only an `id` and a `soul` property
 2. The soul path is in the format: `appname/holon/lens/key`
-3. When resolving a reference, HoloSphere follows the soul path to retrieve the original data
+3. When resolving a hologram, HoloSphere follows the soul path to retrieve the original data
 
-By default, federation propagation uses references instead of duplicating data. This can be controlled:
+By default, federation propagation uses holograms instead of duplicating data. This can be controlled:
 
 ```javascript
-// Propagate with full data copy instead of references
+// Propagate with full data copy instead of holograms
 await holoSphere.propagate('space1', 'items', data, {
-  useReferences: false
+  useHolograms: false
 });
 ```
 
@@ -150,7 +150,7 @@ async function federationExample() {
     // Allow time for propagation
     await new Promise(resolve => setTimeout(resolve, 1000));
     
-    // Step 5: Access data from space2 (resolves reference)
+    // Step 5: Access data from space2 (resolves hologram)
     const itemFromSpace2 = await holoSphere.get(space2, 'items', 'item1');
     console.log('Item from space2:', itemFromSpace2);
     
@@ -163,10 +163,10 @@ async function federationExample() {
     
     await holoSphere.put(space1, 'items', updatedItem);
     
-    // Since we're using soul references, the update is immediately visible
-    // through the reference without needing to propagate again
+    // Since we're using soul holograms, the update is immediately visible
+    // through the hologram without needing to propagate again
     
-    // Verify update is visible through the reference
+    // Verify update is visible through the hologram
     const updatedItemFromSpace2 = await holoSphere.get(space2, 'items', 'item1');
     console.log('Updated item from space2:', updatedItemFromSpace2);
     
@@ -193,7 +193,7 @@ federationExample().catch(console.error);
    - The notify list includes the target space
 
 3. **Reference Resolution**: If you're getting reference objects instead of the actual data:
-   - Make sure `resolveReferences` is set to `true` (it's the default)
+   - Make sure `resolveHolograms` is set to `true` (it's the default)
    - Check that the original data still exists at the referenced location
 
 4. **Timing Issues**: Data propagation is asynchronous. Add small delays (500-1000ms) between operations to allow propagation to complete.
@@ -207,7 +207,7 @@ federationExample().catch(console.error);
 2. **Explicit Propagation**: Unless you're using `autoPropagate`, always call `propagate()` explicitly after storing data that should be shared.
 
 3. **Choose the Right Propagation Method**:
-   - Use `useReferences: true` (default) to keep a single source of truth
-   - Use `useReferences: false` only when you need independent copies
+   - Use `useHolograms: true` (default) to keep a single source of truth
+   - Use `useHolograms: false` only when you need independent copies
 
 4. **Cleanup**: Always close the HoloSphere instance when done to prevent resource leaks. 

package/compute.js

@@ -0,0 +1,289 @@
+// holo_compute.js
+import * as h3 from 'h3-js';
+
+/**
+ * Computes operations across multiple layers up the hierarchy
+ * @param {HoloSphere} holoInstance - The HoloSphere instance.
+ * @param {string} holon - Starting holon identifier
+ * @param {string} lens - The lens to compute
+ * @param {object} options - Computation options
+ * @param {number} [maxLevels=15] - Maximum levels to compute up
+ * @param {string} [password] - Optional password for private holons
+ */
+export async function computeHierarchy(holoInstance, holon, lens, options, maxLevels = 15, password = null) {
+    let currentHolon = holon;
+    let currentRes = h3.getResolution(currentHolon);
+    const results = [];
+
+    while (currentRes > 0 && maxLevels > 0) {
+        try {
+            // Use the instance's compute method
+            const result = await holoInstance.compute(currentHolon, lens, options, password);
+            if (result) {
+                results.push(result);
+            }
+            currentHolon = h3.cellToParent(currentHolon, currentRes - 1);
+            currentRes--;
+            maxLevels--;
+        } catch (error) {
+            console.error('Error in compute hierarchy:', error);
+            break;
+        }
+    }
+
+    return results;
+}
+
+/**
+ * Computes operations on content within a holon and lens for one layer up.
+ * @param {HoloSphere} holoInstance - The HoloSphere instance.
+ * @param {string} holon - The holon identifier.
+ * @param {string} lens - The lens to compute.
+ * @param {object} options - Computation options
+ * @param {string} options.operation - The operation to perform ('summarize', 'aggregate', 'concatenate')
+ * @param {string[]} [options.fields] - Fields to perform operation on
+ * @param {string} [options.targetField] - Field to store the result in
+ * @param {string} [password] - Optional password for private holons
+ * @throws {Error} If parameters are invalid or missing
+ */
+export async function compute(holoInstance, holon, lens, options, password = null) {
+    // Validate required parameters
+    if (!holon || !lens) {
+        throw new Error('compute: Missing required parameters');
+    }
+
+    // Convert string operation to options object
+    if (typeof options === 'string') {
+        options = { operation: options };
+    }
+
+    if (!options?.operation) {
+        throw new Error('compute: Missing required parameters');
+    }
+
+    // Validate holon format and resolution first
+    let res;
+    try {
+        res = h3.getResolution(holon);
+    } catch (error) {
+        throw new Error('compute: Invalid holon format');
+    }
+
+    if (res < 1 || res > 15) {
+        throw new Error('compute: Invalid holon resolution (must be between 1 and 15)');
+    }
+
+    const {
+        operation,
+        fields = [],
+        targetField,
+        depth,
+        maxDepth
+    } = options;
+
+    // Validate depth parameters if provided
+    if (depth !== undefined && depth < 0) {
+        throw new Error('compute: Invalid depth parameter');
+    }
+
+    if (maxDepth !== undefined && (maxDepth < 1 || maxDepth > 15)) {
+        throw new Error('compute: Invalid maxDepth parameter (must be between 1 and 15)');
+    }
+
+    // Validate operation
+    const validOperations = ['summarize', 'aggregate', 'concatenate'];
+    if (!validOperations.includes(operation)) {
+        throw new Error(`compute: Invalid operation (must be one of ${validOperations.join(', ')})`);
+    }
+
+    const parent = h3.cellToParent(holon, res - 1);
+    const siblings = h3.cellToChildren(parent, res);
+
+    // Collect all content from siblings using instance's getAll
+    const contents = await Promise.all(
+        siblings.map(sibling => holoInstance.getAll(sibling, lens, password))
+    );
+
+    const flatContents = contents.flat().filter(Boolean);
+
+    if (flatContents.length > 0) {
+        try {
+            let computed;
+            switch (operation) {
+                case 'summarize':
+                    // For summarize, concatenate specified fields or use entire content
+                    const textToSummarize = fields.length > 0
+                        ? flatContents.map(item => fields.map(field => item[field]).filter(Boolean).join('\n')).join('\n')
+                        : JSON.stringify(flatContents);
+                    computed = await holoInstance.summarize(textToSummarize); // Use instance's summarize
+                    break;
+
+                case 'aggregate':
+                    // For aggregate, sum numeric fields
+                    computed = fields.reduce((acc, field) => {
+                        acc[field] = flatContents.reduce((sum, item) => {
+                            return sum + (Number(item[field]) || 0);
+                        }, 0);
+                        return acc;
+                    }, {});
+                    break;
+
+                case 'concatenate':
+                    // For concatenate, combine arrays or strings
+                    computed = fields.reduce((acc, field) => {
+                        acc[field] = flatContents.reduce((combined, item) => {
+                            const value = item[field];
+                            if (Array.isArray(value)) {
+                                return [...combined, ...value];
+                            } else if (value) {
+                                return [...combined, value];
+                            }
+                            return combined;
+                        }, []);
+                        // Remove duplicates if array
+                        acc[field] = Array.from(new Set(acc[field]));
+                        return acc;
+                    }, {});
+                    break;
+            }
+
+            if (computed) {
+                const resultId = `${parent}_${operation}`;
+                const result = {
+                    id: resultId,
+                    timestamp: Date.now()
+                };
+
+                // Store result in targetField if specified, otherwise at root level
+                if (targetField) {
+                    result[targetField] = computed;
+                } else if (typeof computed === 'object') {
+                    Object.assign(result, computed);
+                } else {
+                    result.value = computed;
+                }
+
+                await holoInstance.put(parent, lens, result, password); // Use instance's put
+                return result;
+            }
+        } catch (error) {
+            console.warn('Error in compute operation:', error);
+            throw error;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Summarizes provided history text using OpenAI.
+ * @param {HoloSphere} holoInstance - The HoloSphere instance.
+ * @param {string} history - The history text to summarize.
+ * @returns {Promise<string>} - The summarized text.
+ */
+export async function summarize(holoInstance, history) {
+    if (!holoInstance.openai) {
+        return 'OpenAI not initialized, please specify the API key in the constructor.'
+    }
+
+    try {
+        const response = await holoInstance.openai.chat.completions.create({
+            model: "gpt-4",
+            messages: [
+                {
+                    role: "system",
+                    content: "You are a helpful assistant that summarizes text concisely while preserving key information. Keep summaries clear and focused."
+                },
+                {
+                    role: "user",
+                    content: history
+                }
+            ],
+            temperature: 0.7,
+            max_tokens: 500
+        });
+
+        return response.choices[0].message.content.trim();
+    } catch (error) {
+        console.error('Error in summarize:', error);
+        throw new Error('Failed to generate summary');
+    }
+}
+
+/**
+ * Upcasts content to parent holonagons recursively using holograms.
+ * @param {HoloSphere} holoInstance - The HoloSphere instance.
+ * @param {string} holon - The current holon identifier.
+ * @param {string} lens - The lens under which to upcast.
+ * @param {object} content - The content to upcast.
+ * @param {number} [maxLevels=15] - Maximum levels to upcast.
+ * @returns {Promise<object>} - The original content.
+ */
+export async function upcast(holoInstance, holon, lens, content, maxLevels = 15) {
+    // Store the actual content at the original resolution using instance's put
+    await holoInstance.put(holon, lens, content);
+
+    let res = h3.getResolution(holon);
+
+    // If already at the highest level (res 0) or reached max levels, we're done
+    if (res === 0 || maxLevels <= 0) {
+        return content;
+    }
+
+    // Get the parent cell
+    let parent = h3.cellToParent(holon, res - 1);
+
+    // Create a hologram to store in the parent using instance's createHologram
+    const hologram = holoInstance.createHologram(holon, lens, content);
+
+    // Store the hologram in the parent cell using instance's put
+    await holoInstance.put(parent, lens, hologram, null, {
+        autoPropagate: false
+    });
+
+    // Continue upcasting with the parent using instance's upcast
+    if (res > 1 && maxLevels > 1) {
+        // Recursively call the instance's upcast method
+        // Pass the *hologram* to the next level, not the original content
+        return holoInstance.upcast(parent, lens, hologram, maxLevels - 1);
+    }
+
+    return content;
+}
+
+/**
+ * Updates the parent holon with a new report.
+ * Note: This function assumes the existence of `getCellInfo` and `db.put` on the holoInstance,
+ * which were not defined in the original class. Adjust as needed.
+ * @param {HoloSphere} holoInstance - The HoloSphere instance.
+ * @param {string} id - The child holon identifier.
+ * @param {string} report - The report to update.
+ * @returns {Promise<object>} - The updated parent information.
+ */
+export async function updateParent(holoInstance, id, report) {
+    // Check if required methods exist on the instance
+    if (typeof holoInstance.getCellInfo !== 'function' || !holoInstance.db || typeof holoInstance.db.put !== 'function') {
+        console.warn('updateParent requires getCellInfo and db.put methods on the HoloSphere instance.');
+        // Decide how to handle this: throw error, return null, etc.
+        // For now, let's proceed assuming they might exist but log a warning.
+    }
+
+    try {
+        let cellinfo = await holoInstance.getCellInfo(id)
+        let res = h3.getResolution(id)
+        let parent = h3.cellToParent(id, res - 1)
+        let parentInfo = await holoInstance.getCellInfo(parent)
+        parentInfo.wisdom[id] = report
+        //update summary using instance's summarize
+        let summary = await holoInstance.summarize(Object.values(parentInfo.wisdom).join('\n'))
+        parentInfo.summary = summary
+
+        // Assuming db is accessible like this
+        await holoInstance.db.put('cell', parentInfo)
+        return parentInfo
+    } catch (error) {
+        console.error("Error during updateParent:", error);
+        // Re-throw or handle error appropriately
+        throw error;
+    }
+}