Package Exports

@xats-org/ancillary-generator
@xats-org/ancillary-generator/dist/index.js
@xats-org/ancillary-generator/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@xats-org/ancillary-generator) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@xats-org/ancillary-generator

Automated ancillary material generation for xats documents. This package provides tools to extract tagged content from xats documents and generate various supplementary materials including study guides, presentation slides, test banks, and more.

Installation

npm install @xats-org/ancillary-generator

Features

Study Guide Generation: Create comprehensive study guides with summaries, key terms, and practice questions
Slide Deck Generation: Generate presentation slides in multiple formats (PowerPoint, HTML, Markdown)
Test Bank Extraction: Extract and organize assessment questions with answer keys and rubrics
Flexible Tagging System: Use standardized ancillary tags to mark content for extraction
Multiple Output Formats: Support for HTML, PDF, DOCX, PPTX, Markdown, and JSON
Customizable Templates: Use templates to control output formatting and styling

Usage

Basic Example

import { StudyGuideGenerator } from '@xats-org/ancillary-generator';
import { loadDocument } from '@xats-org/validator';

// Load your xats document
const document = await loadDocument('path/to/document.json');

// Create a study guide generator
const generator = new StudyGuideGenerator();

// Extract content tagged for study guides
const content = generator.extractTaggedContent(document, {
  tags: ['study-guide-content'],
  includeNested: true,
});

// Generate study guide
const result = await generator.generateOutput(content, {
  format: 'html',
  includeLearningObjectives: true,
  includeSummaries: true,
  includeGlossary: true,
  includePracticeQuestions: true,
  groupBy: 'chapter',
});

if (result.success) {
  // Save or process the output
  console.log('Study guide generated:', result.output);
}

Generating Slides

import { SlideDeckGenerator } from '@xats-org/ancillary-generator';

const slideGen = new SlideDeckGenerator();

// Extract content marked for slides
const slideContent = slideGen.extractTaggedContent(document, {
  tags: ['slide-content'],
});

// Generate slide deck
const slides = await slideGen.generateOutput(slideContent, {
  format: 'html',
  maxSlides: 30,
  slidesPerSection: 5,
  includeSpeakerNotes: true,
  theme: 'white',
  animations: true,
});

Creating Test Banks

import { TestBankExtractor } from '@xats-org/ancillary-generator';

const testBank = new TestBankExtractor();

// Extract quiz questions
const questions = testBank.extractTaggedContent(document, {
  tags: ['quiz-bank-item'],
});

// Generate test bank
const bank = await testBank.generateOutput(questions, {
  format: 'json',
  questionTypes: ['multiple-choice', 'short-answer'],
  difficultyLevels: ['easy', 'medium', 'hard'],
  questionsPerTopic: 10,
  includeAnswerKey: true,
  includeRubrics: true,
  randomizeOrder: true,
});

Ancillary Tags

The package uses standardized vocabulary tags to mark content for extraction:

Study Guide Tags

study-guide-content: Content to include in study guides
- Properties: importance, reviewFrequency, studyTips

Slide Tags

slide-content: Content to include in presentations
- Properties: slideType, maxBulletPoints, speakerNotes, animationHint

Assessment Tags

quiz-bank-item: Questions for test banks
- Properties: questionType, difficulty, cognitiveLevel, points

Instructor Tags

instructor-note: Notes for instructor manuals
- Properties: noteType, visibility, timing, experienceLevel

Solution Tags

solution-manual-content: Solutions and answer keys
- Properties: solutionType, showWorkRequired, alternativeSolutions

Tagging Content

To mark content for ancillary generation, add tags to your xats blocks:

{
  "blockType": "https://pub.xats.org/vocabularies/blocks/paragraph",
  "content": {
    "runs": [
      {
        "type": "text",
        "text": "The mitochondria is the powerhouse of the cell."
      }
    ]
  },
  "tags": ["study-guide-content", "slide-content"],
  "extensions": {
    "ancillary": {
      "importance": "critical",
      "slideType": "bullet-points",
      "maxBulletPoints": 3
    }
  }
}

Custom Generators

You can create custom generators by extending the base class:

import { BaseAncillaryGenerator } from '@xats-org/ancillary-generator';
import type { ExtractedContent, GenerationResult, OutputFormat } from '@xats-org/ancillary-generator';

export class CustomGenerator extends BaseAncillaryGenerator {
  supportedFormats: OutputFormat[] = ['html', 'json'];

  async generateOutput(
    content: ExtractedContent[],
    options: any
  ): Promise<GenerationResult> {
    // Your custom generation logic
    const output = this.processContent(content, options);
    
    return this.createSuccessResult(
      output,
      options.format,
      {
        blocksProcessed: content.length,
        timeElapsed: Date.now() - startTime,
        outputSize: output.length,
      }
    );
  }

  private processContent(content: ExtractedContent[], options: any): string {
    // Custom processing logic
    return JSON.stringify(content);
  }
}

API Reference

BaseAncillaryGenerator

Base class for all ancillary generators.

Methods

extractTaggedContent(document, options): Extract content blocks matching specified tags
generateOutput(content, options): Generate output from extracted content (abstract)
validateOptions(options): Validate generation options
extractPlainText(semanticText): Extract plain text from SemanticText objects

ExtractionOptions

interface ExtractionOptions {
  tags: string[];              // Tags to filter by
  includeNested?: boolean;     // Include nested content
  maxDepth?: number;          // Maximum nesting depth
  preserveStructure?: boolean; // Preserve document structure
  filter?: (block) => boolean; // Custom filter function
}

GenerationOptions

interface GenerationOptions {
  format: OutputFormat;        // Output format
  template?: Template;         // Custom template
  styling?: Record<string, any>; // Custom styles
  metadata?: Record<string, any>; // Additional metadata
  includeReferences?: boolean; // Include source references
  outputPath?: string;        // Output file path
}

Contributing

Contributions are welcome! Please see the contributing guide for details.