Narrative Graph MCP

Instructions

Implementation Reference

• src/tools/generateEnsemble.ts:14-69 (handler)

  The primary handler function implementing the rtm_generate_ensemble tool. It processes input parameters, generates an RTM ensemble using RTMEnsembleGenerator, computes statistics, and returns a JSON-formatted result.

  export default async function generateEnsemble(params: GenerateEnsembleParams) {
    try {
      // Create narrative from text
      const narrative = createNarrative(params.text, params.title);
      
      // Create RTM parameters
      const parameters = {
        ...createDefaultParameters(),
        maxBranchingFactor: params.maxBranchingFactor || 4,
        maxRecallDepth: params.maxRecallDepth || 6
      };
      
      // Generate ensemble
      const generator = new RTMEnsembleGenerator(parameters);
      const ensemble = await generator.generateEnsemble(
        narrative, 
        params.ensembleSize || 100
      );
      
      // Analyze variance
      const variance = generator.analyzeEnsembleVariance(ensemble);
      
      // Test for scale invariance
      const scaleInvariance = generator.testScaleInvariance(ensemble);
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            success: true,
            ensembleId: `ensemble_${narrative.id}`,
            narrativeId: narrative.id,
            statistics: {
              ensembleSize: ensemble.trees.length,
              meanRecallLength: ensemble.statistics.meanRecallLength,
              stdRecallLength: ensemble.statistics.stdRecallLength,
              scalingExponent: ensemble.statistics.scalingExponent,
              variance: variance,
              scaleInvariance: scaleInvariance
            },
            message: `Generated ensemble of ${ensemble.trees.length} trees with mean recall length ${ensemble.statistics.meanRecallLength.toFixed(2)} ± ${ensemble.statistics.stdRecallLength.toFixed(2)}`
          }, null, 2)
        }],
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            success: false,
            error: error instanceof Error ? error.message : "Unknown error occurred"
          }, null, 2)
        }],
      };
    }
  }

• src/schemas/generateEnsembleSchema.ts:3-9 (schema)

  Zod input schema defining parameters for the rtm_generate_ensemble tool, used for validation in the server.

  export const generateEnsembleSchema = z.object({
    text: z.string().describe('The narrative text to analyze'),
    title: z.string().describe('Title of the narrative'),
    ensembleSize: z.number().default(100).describe('Number of trees to generate in the ensemble'),
    maxBranchingFactor: z.number().default(4).describe('Maximum number of child nodes (K parameter)'),
    maxRecallDepth: z.number().default(6).describe('Maximum depth for recall (D parameter)'),
  });

• src/index.ts:47-52 (registration)

  Registration of the generateEnsemble handler function in the tools registry object under the key 'rtm_generate_ensemble'.

  const tools = {
    rtm_create_narrative_tree: createNarrativeTree,
    rtm_generate_ensemble: generateEnsemble,
    rtm_traverse_narrative: traverseNarrative,
    rtm_find_optimal_depth: findOptimalDepth,
  };

• src/index.ts:62-65 (registration)

  Tool definition in the toolDefinitions array, registering the name, description, and schema for listing and validation.

    name: 'rtm_generate_ensemble',
    description: 'Generate a statistical ensemble of Random Trees to model population-level recall',
    inputSchema: generateEnsembleSchema,
  },

• src/core/rtm-ensemble.ts:24-258 (helper)

  Core helper class RTMEnsembleGenerator used by the handler to generate ensembles, compute statistics, variance analysis, and scale invariance tests.

  export class RTMEnsembleGenerator {
    private limit = pLimit(5); // Concurrent tree generation limit
  
    constructor(private parameters: RTMParameters) {}
  
    /**
     * Generate an ensemble of Random Trees for a narrative
     * @param narrative - Source narrative
     * @param ensembleSize - Number of trees to generate
     * @returns Complete ensemble with statistics
     */
    async generateEnsemble(
      narrative: Narrative,
      ensembleSize: number
    ): Promise<RTMEnsemble> {
      // Create clause map for traversal
      const clauseMap = new Map(
        narrative.clauses.map(c => [c.id, c])
      );
  
      // Generate trees in parallel with concurrency limit
      const treePromises = Array.from({ length: ensembleSize }, () =>
        this.limit(() => this.generateSingleTree(narrative))
      );
  
      const trees = await Promise.all(treePromises);
  
      // Calculate ensemble statistics
      const statistics = this.calculateEnsembleStatistics(trees, clauseMap);
  
      return {
        narrativeId: narrative.id,
        trees,
        parameters: this.parameters,
        statistics
      };
    }
  
    /**
     * Generate a single Random Tree
     * @param narrative - Source narrative
     * @returns Random tree instance
     */
    private async generateSingleTree(narrative: Narrative): Promise<RandomTree> {
      const builder = new RTMTreeBuilder(this.parameters);
      return builder.buildTree(narrative);
    }
  
    /**
     * Calculate statistical properties of the ensemble
     * @param trees - Array of trees
     * @param clauseMap - Map of clause IDs to clauses
     * @returns Ensemble statistics
     */
    private calculateEnsembleStatistics(
      trees: RandomTree[],
      clauseMap: Map<string, Clause>
    ): EnsembleStatistics {
      const recallLengths: number[] = [];
      const compressionByScale: Record<TemporalScale, number[]> = {
        'clause': [],
        'sentence': [],
        'paragraph': [],
        'section': [],
        'chapter': [],
        'document': []
      };
  
      // Analyze each tree
      trees.forEach(tree => {
        const traversal = new RTMTraversal(tree, clauseMap);
        
        // Simulate recall at max depth
        const result = traversal.traverseToDepth(this.parameters.maxRecallDepth);
        recallLengths.push(result.totalClauses);
  
        // Collect compression ratios by scale
        tree.nodes.forEach(node => {
          compressionByScale[node.temporalScale].push(node.compressionRatio);
        });
      });
  
      // Calculate mean and std of recall lengths
      const meanRecallLength = recallLengths.reduce((a, b) => a + b, 0) / recallLengths.length;
      const variance = recallLengths.reduce(
        (sum, len) => sum + Math.pow(len - meanRecallLength, 2),
        0
      ) / recallLengths.length;
      const stdRecallLength = Math.sqrt(variance);
  
      // Calculate scaling exponent if enough data
      const allCompressionRatios = Object.values(compressionByScale)
        .flat()
        .filter(r => r > 0);
      
      const scalingExponent = allCompressionRatios.length > 10
        ? calculateScalingExponent(allCompressionRatios)
        : undefined;
  
      return {
        meanRecallLength,
        stdRecallLength,
        compressionDistribution: compressionByScale,
        scalingExponent
      };
    }
  
    /**
     * Analyze variance across ensemble
     * @param ensemble - Complete ensemble
     * @returns Variance analysis
     */
    analyzeEnsembleVariance(ensemble: RTMEnsemble): {
      structuralVariance: number;
      depthVariance: number;
      branchingVariance: number;
    } {
      const structures = ensemble.trees.map(tree => {
        const stats = this.getTreeStructureStats(tree);
        return {
          nodeCount: stats.totalNodes,
          maxDepth: stats.maxDepth,
          avgBranching: stats.avgBranchingFactor
        };
      });
  
      // Calculate variances
      const avgNodeCount = structures.reduce((sum, s) => sum + s.nodeCount, 0) / structures.length;
      const structuralVariance = structures.reduce(
        (sum, s) => sum + Math.pow(s.nodeCount - avgNodeCount, 2),
        0
      ) / structures.length;
  
      const avgDepth = structures.reduce((sum, s) => sum + s.maxDepth, 0) / structures.length;
      const depthVariance = structures.reduce(
        (sum, s) => sum + Math.pow(s.maxDepth - avgDepth, 2),
        0
      ) / structures.length;
  
      const avgBranching = structures.reduce((sum, s) => sum + s.avgBranching, 0) / structures.length;
      const branchingVariance = structures.reduce(
        (sum, s) => sum + Math.pow(s.avgBranching - avgBranching, 2),
        0
      ) / structures.length;
  
      return {
        structuralVariance,
        depthVariance,
        branchingVariance
      };
    }
  
    /**
     * Get structural statistics for a tree
     * @param tree - Random tree
     * @returns Tree statistics
     */
    private getTreeStructureStats(tree: RandomTree) {
      const nodes = Array.from(tree.nodes.values());
      const leafNodes = nodes.filter(n => n.children.length === 0);
      
      let maxDepth = 0;
      nodes.forEach(node => {
        maxDepth = Math.max(maxDepth, node.level);
      });
  
      const nodesWithChildren = nodes.filter(n => n.children.length > 0);
      const avgBranchingFactor = nodesWithChildren.length > 0
        ? nodesWithChildren.reduce((sum, n) => sum + n.children.length, 0) / nodesWithChildren.length
        : 0;
  
      return {
        totalNodes: nodes.length,
        maxDepth,
        avgBranchingFactor,
        leafNodes: leafNodes.length
      };
    }
  
    /**
     * Test for scale invariance in the ensemble
     * @param ensemble - Complete ensemble
     * @param minNarrativeLength - Minimum length for scale invariance
     * @returns Scale invariance test results
     */
    testScaleInvariance(
      ensemble: RTMEnsemble,
      minNarrativeLength: number = 1000
    ): {
      isScaleInvariant: boolean;
      scalingExponent?: number;
      confidence: number;
    } {
      // Check if narrative is long enough
      const narrativeLength = ensemble.trees[0]?.nodes.get(
        ensemble.trees[0].rootNodeId
      )?.clauses.length || 0;
  
      if (narrativeLength < minNarrativeLength) {
        return {
          isScaleInvariant: false,
          confidence: 0
        };
      }
  
      // Check if we have a consistent scaling exponent
      const exponent = ensemble.statistics.scalingExponent;
      if (!exponent) {
        return {
          isScaleInvariant: false,
          confidence: 0
        };
      }
  
      // Calculate confidence based on variance in compression ratios
      const allRatios = Object.values(ensemble.statistics.compressionDistribution)
        .flat()
        .filter(r => r > 0);
      
      const meanRatio = allRatios.reduce((a, b) => a + b, 0) / allRatios.length;
      const variance = allRatios.reduce(
        (sum, r) => sum + Math.pow(r - meanRatio, 2),
        0
      ) / allRatios.length;
      
      // Lower variance = higher confidence
      const confidence = Math.exp(-variance / meanRatio);
  
      return {
        isScaleInvariant: Math.abs(exponent) > 0.1,
        scalingExponent: exponent,
        confidence
      };
    }
  }