holosphere 1.1.20 → 2.0.0-alpha1

package/src/ai/breakdown.js

@@ -0,0 +1,511 @@
+/**
+ * Task Breakdown - Recursively decompose tasks/quests into subtasks
+ */
+
+/**
+ * Task Breakdown class
+ */
+export class TaskBreakdown {
+  /**
+   * @param {LLMService} llmService - LLM service instance
+   * @param {Object} holosphere - HoloSphere instance
+   */
+  constructor(llmService, holosphere = null) {
+    this.llm = llmService;
+    this.holosphere = holosphere;
+  }
+
+  /**
+   * Set HoloSphere instance
+   * @param {Object} holosphere - HoloSphere instance
+   */
+  setHoloSphere(holosphere) {
+    this.holosphere = holosphere;
+  }
+
+  /**
+   * Recursively break down a task/quest into subtasks
+   * @param {Object} item - The item to break down (must have id)
+   * @param {string} holonId - Holon where the item lives
+   * @param {string} lensName - Lens name (e.g., 'quests', 'tasks')
+   * @param {Object} options - Breakdown options
+   * @param {number} options.depth - Maximum recursion depth (default: 2)
+   * @param {number} options.stepsPerLevel - Number of subtasks per level (default: 3-5)
+   * @param {boolean} options.useContext - Look at other items for context (default: true)
+   * @param {boolean} options.storeResults - Store generated subtasks (default: true)
+   * @param {string} options.dependencyField - Field name for dependencies (default: 'dependencies')
+   * @param {string} options.parentField - Field name for parent reference (default: 'parent')
+   * @returns {Promise<Object>} Breakdown result with tree structure
+   */
+  async breakdown(item, holonId, lensName, options = {}) {
+    if (!item || !item.id) {
+      throw new Error('Item must have an id property');
+    }
+
+    const {
+      depth = 2,
+      stepsPerLevel = { min: 3, max: 5 },
+      useContext = true,
+      storeResults = true,
+      dependencyField = 'dependencies',
+      parentField = 'parent',
+    } = options;
+
+    // Normalize stepsPerLevel
+    const steps = typeof stepsPerLevel === 'number'
+      ? { min: stepsPerLevel, max: stepsPerLevel }
+      : stepsPerLevel;
+
+    // Get context from other items in the holon
+    let context = [];
+    if (useContext && this.holosphere) {
+      try {
+        const allItems = await this.holosphere.getAll(holonId, lensName);
+        context = allItems
+          .filter(i => i.id !== item.id)
+          .slice(0, 10); // Limit context items
+      } catch {
+        // Skip if can't get context
+      }
+    }
+
+    // Get schema for the lens if available
+    let schema = null;
+    if (this.holosphere) {
+      try {
+        schema = await this.holosphere.getSchema(lensName);
+      } catch {
+        // No schema available
+      }
+    }
+
+    // Perform recursive breakdown
+    const result = await this._breakdownRecursive(
+      item,
+      holonId,
+      lensName,
+      depth,
+      steps,
+      context,
+      schema,
+      dependencyField,
+      parentField,
+      storeResults,
+      0 // current depth
+    );
+
+    return {
+      original: item,
+      holonId,
+      lensName,
+      breakdown: result,
+      totalSubtasks: this._countSubtasks(result),
+      maxDepth: depth,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Recursive breakdown implementation
+   * @private
+   */
+  async _breakdownRecursive(
+    item,
+    holonId,
+    lensName,
+    maxDepth,
+    stepsPerLevel,
+    context,
+    schema,
+    dependencyField,
+    parentField,
+    storeResults,
+    currentDepth
+  ) {
+    if (currentDepth >= maxDepth) {
+      return {
+        item,
+        children: [],
+        depth: currentDepth,
+      };
+    }
+
+    // Generate subtasks for this item
+    const subtasks = await this._generateSubtasks(
+      item,
+      context,
+      schema,
+      stepsPerLevel,
+      dependencyField,
+      parentField
+    );
+
+    // Store subtasks if requested
+    if (storeResults && this.holosphere && subtasks.length > 0) {
+      for (const subtask of subtasks) {
+        try {
+          await this.holosphere.write(holonId, lensName, subtask);
+        } catch (err) {
+          console.warn(`Failed to store subtask ${subtask.id}:`, err.message);
+        }
+      }
+
+      // Update parent item with child references if it doesn't have them
+      if (item._meta?.childTasks !== subtasks.map(s => s.id)) {
+        try {
+          await this.holosphere.update(holonId, lensName, item.id, {
+            _meta: {
+              ...item._meta,
+              childTasks: subtasks.map(s => s.id),
+              breakdownTimestamp: Date.now(),
+            }
+          });
+        } catch {
+          // Skip if can't update
+        }
+      }
+    }
+
+    // Recursively break down each subtask
+    const children = [];
+    for (const subtask of subtasks) {
+      const childResult = await this._breakdownRecursive(
+        subtask,
+        holonId,
+        lensName,
+        maxDepth,
+        stepsPerLevel,
+        context,
+        schema,
+        dependencyField,
+        parentField,
+        storeResults,
+        currentDepth + 1
+      );
+      children.push(childResult);
+    }
+
+    return {
+      item,
+      children,
+      depth: currentDepth,
+    };
+  }
+
+  /**
+   * Generate subtasks for an item using AI
+   * @private
+   */
+  async _generateSubtasks(item, context, schema, stepsPerLevel, dependencyField, parentField) {
+    const { min, max } = stepsPerLevel;
+
+    const systemPrompt = `You are a task decomposition expert. Break down the given task/quest into ${min}-${max} concrete, actionable subtasks.
+
+Each subtask should:
+1. Be a clear, specific action
+2. Be smaller and more manageable than the parent
+3. Together with siblings, fully accomplish the parent task
+4. Have a unique ID (format: parentId-1, parentId-2, etc.)
+5. Reference the parent task in the "${parentField}" field
+6. List any dependencies on sibling tasks in "${dependencyField}" array
+
+${schema ? `Follow this schema structure:\n${JSON.stringify(schema, null, 2)}` : ''}
+
+${context.length > 0 ? `Consider these existing items for context and avoid duplication:\n${JSON.stringify(context.slice(0, 5), null, 2)}` : ''}
+
+Return a JSON array of subtasks. Each subtask must have:
+- id: unique identifier (parentId-1, parentId-2, etc.)
+- title/name: clear action title
+- description: what needs to be done
+- ${parentField}: reference to parent id
+- ${dependencyField}: array of sibling task ids this depends on (empty if first task)
+- status: "pending"
+- Any other relevant fields from the parent schema
+
+Example output format:
+[
+  {
+    "id": "parent-1",
+    "title": "First subtask",
+    "description": "Details...",
+    "${parentField}": "parentId",
+    "${dependencyField}": [],
+    "status": "pending"
+  },
+  {
+    "id": "parent-2",
+    "title": "Second subtask (depends on first)",
+    "description": "Details...",
+    "${parentField}": "parentId",
+    "${dependencyField}": ["parent-1"],
+    "status": "pending"
+  }
+]`;
+
+    const userMessage = `Break down this task into ${min}-${max} subtasks:
+
+${JSON.stringify(item, null, 2)}`;
+
+    try {
+      const subtasks = await this.llm.getJSON(systemPrompt, userMessage, {
+        temperature: 0.4,
+        maxTokens: 2000
+      });
+
+      // Ensure all subtasks have proper parent reference and IDs
+      return subtasks.map((subtask, index) => ({
+        ...subtask,
+        id: subtask.id || `${item.id}-${index + 1}`,
+        [parentField]: item.id,
+        [dependencyField]: subtask[dependencyField] || [],
+        status: subtask.status || 'pending',
+        _meta: {
+          ...subtask._meta,
+          generatedFrom: item.id,
+          generatedAt: Date.now(),
+          depth: (item._meta?.depth || 0) + 1,
+        }
+      }));
+    } catch (error) {
+      console.error('Failed to generate subtasks:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Count total subtasks in a breakdown tree
+   * @private
+   */
+  _countSubtasks(node) {
+    if (!node.children || node.children.length === 0) {
+      return 0;
+    }
+    return node.children.length +
+      node.children.reduce((sum, child) => sum + this._countSubtasks(child), 0);
+  }
+
+  /**
+   * Flatten a breakdown tree into a list
+   * @param {Object} breakdownResult - Result from breakdown()
+   * @returns {Object[]} Flat list of all items
+   */
+  flatten(breakdownResult) {
+    const items = [];
+
+    const traverse = (node) => {
+      if (node.item) {
+        items.push(node.item);
+      }
+      if (node.children) {
+        for (const child of node.children) {
+          traverse(child);
+        }
+      }
+    };
+
+    if (breakdownResult.breakdown) {
+      traverse(breakdownResult.breakdown);
+    }
+
+    return items;
+  }
+
+  /**
+   * Get dependency order for execution
+   * @param {Object} breakdownResult - Result from breakdown()
+   * @returns {Object[]} Items in dependency order (parents before children)
+   */
+  getDependencyOrder(breakdownResult) {
+    const items = this.flatten(breakdownResult);
+
+    // Sort by depth (parents first) then by dependency order within same depth
+    return items.sort((a, b) => {
+      const depthA = a._meta?.depth || 0;
+      const depthB = b._meta?.depth || 0;
+      if (depthA !== depthB) return depthA - depthB;
+
+      // At same depth, check if b depends on a
+      const bDeps = b.dependencies || [];
+      if (bDeps.includes(a.id)) return -1;
+
+      const aDeps = a.dependencies || [];
+      if (aDeps.includes(b.id)) return 1;
+
+      return 0;
+    });
+  }
+
+  /**
+   * Suggest breakdown strategy for an item
+   * @param {Object} item - Item to analyze
+   * @returns {Promise<Object>} Suggested breakdown strategy
+   */
+  async suggestStrategy(item) {
+    const systemPrompt = `You are a task decomposition expert. Analyze this task and suggest the best breakdown strategy.
+
+Consider:
+1. Task complexity
+2. Recommended depth (1-4 levels)
+3. Recommended subtasks per level (2-7)
+4. Key areas to focus on
+5. Potential dependencies between subtasks
+
+Return JSON:
+{
+  "complexity": "simple|moderate|complex|very_complex",
+  "recommendedDepth": n,
+  "recommendedStepsPerLevel": {"min": n, "max": n},
+  "focusAreas": ["area1", "area2"],
+  "potentialChallenges": ["challenge1"],
+  "estimatedTotalSubtasks": n,
+  "reasoning": "explanation"
+}`;
+
+    return this.llm.getJSON(
+      systemPrompt,
+      JSON.stringify(item, null, 2),
+      { temperature: 0.3 }
+    );
+  }
+
+  /**
+   * Rebalance a breakdown tree (redistribute subtasks)
+   * @param {Object} breakdownResult - Existing breakdown result
+   * @param {Object} options - Rebalancing options
+   * @returns {Promise<Object>} Rebalanced breakdown
+   */
+  async rebalance(breakdownResult, options = {}) {
+    const { targetStepsPerLevel = { min: 3, max: 5 } } = options;
+
+    const items = this.flatten(breakdownResult);
+
+    const systemPrompt = `You are a task organization expert. Rebalance these tasks to have ${targetStepsPerLevel.min}-${targetStepsPerLevel.max} items per level.
+
+Current tasks:
+${JSON.stringify(items, null, 2)}
+
+Reorganize by:
+1. Merging tasks that are too granular
+2. Splitting tasks that are too large
+3. Maintaining proper dependency chains
+4. Keeping the same overall scope
+
+Return JSON with the rebalanced structure:
+{
+  "tasks": [...],
+  "changes": [{"type": "merge|split|move", "description": "..."}],
+  "summary": "what changed"
+}`;
+
+    return this.llm.getJSON(systemPrompt, '', { temperature: 0.3 });
+  }
+
+  /**
+   * Update progress on a breakdown tree
+   * @param {string} holonId - Holon ID
+   * @param {string} lensName - Lens name
+   * @param {string} itemId - Root item ID
+   * @returns {Promise<Object>} Progress summary
+   */
+  async getProgress(holonId, lensName, itemId) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    // Get all items
+    const allItems = await this.holosphere.getAll(holonId, lensName);
+
+    // Find root and all descendants
+    const root = allItems.find(i => i.id === itemId);
+    if (!root) {
+      throw new Error(`Item ${itemId} not found`);
+    }
+
+    const descendants = this._findDescendants(itemId, allItems);
+
+    // Calculate progress
+    const total = descendants.length;
+    const completed = descendants.filter(i =>
+      i.status === 'completed' || i.status === 'done'
+    ).length;
+    const inProgress = descendants.filter(i =>
+      i.status === 'in_progress' || i.status === 'active'
+    ).length;
+    const pending = total - completed - inProgress;
+
+    return {
+      itemId,
+      title: root.title || root.name,
+      total,
+      completed,
+      inProgress,
+      pending,
+      percentComplete: total > 0 ? Math.round((completed / total) * 100) : 0,
+      blockers: this._findBlockers(descendants),
+      nextUp: this._findNextTasks(descendants),
+    };
+  }
+
+  /**
+   * Find all descendants of an item
+   * @private
+   */
+  _findDescendants(itemId, allItems, parentField = 'parent') {
+    const descendants = [];
+    const children = allItems.filter(i => i[parentField] === itemId);
+
+    for (const child of children) {
+      descendants.push(child);
+      descendants.push(...this._findDescendants(child.id, allItems, parentField));
+    }
+
+    return descendants;
+  }
+
+  /**
+   * Find blocked tasks
+   * @private
+   */
+  _findBlockers(items, dependencyField = 'dependencies') {
+    return items.filter(item => {
+      const deps = item[dependencyField] || [];
+      if (deps.length === 0) return false;
+
+      // Check if any dependency is not completed
+      return deps.some(depId => {
+        const dep = items.find(i => i.id === depId);
+        return dep && dep.status !== 'completed' && dep.status !== 'done';
+      });
+    }).map(item => ({
+      id: item.id,
+      title: item.title || item.name,
+      blockedBy: item[dependencyField],
+    }));
+  }
+
+  /**
+   * Find next tasks ready to work on
+   * @private
+   */
+  _findNextTasks(items, dependencyField = 'dependencies') {
+    return items.filter(item => {
+      if (item.status === 'completed' || item.status === 'done') return false;
+      if (item.status === 'in_progress' || item.status === 'active') return false;
+
+      const deps = item[dependencyField] || [];
+      if (deps.length === 0) return true;
+
+      // All dependencies must be completed
+      return deps.every(depId => {
+        const dep = items.find(i => i.id === depId);
+        return !dep || dep.status === 'completed' || dep.status === 'done';
+      });
+    }).slice(0, 5).map(item => ({
+      id: item.id,
+      title: item.title || item.name,
+      description: item.description,
+    }));
+  }
+}
+
+export default TaskBreakdown;